// Package runtimeports declares interface-only composition seams ("ports")
// that runtime feature roots depend on instead of importing a concrete
// composition host (e.g. internal/bootstrap). It lives in the contract module
// and imports nothing from github.com/nexuscrm/backend (nor kernel/shared/db);
// only stdlib and other contract subpackages are allowed.
//
// The concrete implementations of these ports live in their owning composition
// host (e.g. backend internal/bootstrap) and are wired at the composition root
// (backend internal/application/services). No behavior, DB access, or global
// state may live in this package.
package runtimeports

import (
	"context"

	connector "github.com/pingcap-inc/nexuscrm-contract/pkg/connector"
)

// ConnectorFieldMappingReader is the read-only port for connector / legacy
// field-mapping lookups against the _System_ObjectFieldMapping registry.
//
// The concrete implementation (internal/bootstrap.ConnectorFieldMappingReaderImpl)
// binds a *sql.DB at construction and delegates each method to the canonical
// bootstrap reader of the same name, so behavior is identical to calling the
// bootstrap function directly. The port exists so that consumers
// (internal/features/automation) depend on this neutral interface instead of
// importing internal/bootstrap for these reads.
type ConnectorFieldMappingReader interface {
	// ResolveFieldMapping returns active connector field-mapping rows that match
	// the caller's direction perspective (effective/admin-customized precedence).
	ResolveFieldMapping(ctx context.Context, q connector.ResolveQuery) ([]connector.ConnectorFieldMappingInput, error)

	// ResolvePackConnectorFieldMapping returns the pack-authored connector
	// mapping rows for trusted outbound authority (source-backed declaration;
	// IsCustomized=0), without effective/admin-customized precedence.
	ResolvePackConnectorFieldMapping(ctx context.Context, q connector.ResolveQuery) ([]connector.ConnectorFieldMappingInput, error)

	// GetFieldMappings returns active legacy (Direction='legacy') field mappings
	// for a (sourceObject, targetObject, actionType) conversion, used to copy
	// source-record field values into a newly created target record.
	GetFieldMappings(sourceObject, targetObject, actionType string) ([]connector.FieldMappingDef, error)
}