ports

type AuditorPort interface {
	Verify(ctx context.Context, frame *domain.CognitiveFrame) (*domain.AuditResult, error)
	GenerateTrace(frame *domain.CognitiveFrame) []byte
}

type CompilerPort interface {
	// Compile compiles a prompt based on the provided functional options.
	Compile(ctx context.Context, intent domain.IntentStr, options ...interface{}) (string, error)
}

type EmbeddingPort interface {
	Embed(ctx context.Context, text string) (Vector, error)
}

type EvidenceItem struct {
	ID      string
	Content string
	Intent  string
}

type EvidenceStorePort interface {
	SimilarityStorePort
	SaveBatch(ctx context.Context, items []EvidenceItem) error
	Load(ctx context.Context, id string) (string, error)
}

type GenePoolPort interface {
	// ActiveGenes returns the iterator of genes available for the current context.
	ActiveGenes(ctx context.Context, intent domain.IntentStr) iter.Seq[*domain.DomainGene]

	// Reload refreshes the gene pool from the underlying storage.
	Reload(ctx context.Context) error
}

type GenerativePort interface {
	// Generate creates a draft plan based on the provided intent, compiled prompt, and context.
	Generate(ctx context.Context, intent domain.IntentStr, compiledPrompt string, context []domain.Atom, genes []domain.DomainGene) (*Plan, error)

	// Induce processes raw text and distills it into Datalog rules.
	Induce(ctx context.Context, input string) (string, error)

	// Embed generates an embedding vector for the given text.
	Embed(ctx context.Context, text string) (Vector, error)
}

type GenomeStoragePort interface {
	ReadManifest(ctx context.Context, path string) ([]byte, error)
	MapGene(ctx context.Context, path string) ([]byte, uintptr, error) // mmap zero-copy
	UnmapGene(data []byte) error
	CalculateFileHash(ctx context.Context, path string) (string, error) // SHA256 integrity

	ReadFile(ctx context.Context, path string) ([]byte, error)
	WriteFile(ctx context.Context, path string, data []byte, perm os.FileMode) error

	LoadKnowledge(ctx context.Context, intent string) ([]byte, error)
	PersistKnowledge(ctx context.Context, intent string, data []byte) error

	PersistTrace(ctx context.Context, frame *domain.CognitiveFrame, content []byte) error
	PersistProposal(ctx context.Context, intent string, data []byte) error

	PersistAsync(ctx context.Context, path string, data []byte) error
	Flush(ctx context.Context) error // Wait for async writes

	ResolvePath(kind, id string) string // e.g: "induced", "pending", "trace", "evidence", "manifest"
}

type PerceptionPort interface {
	// Normalize converts a raw signal into a stream of Atoms.
	Normalize(ctx context.Context, signal domain.Signal) (domain.Payload, error)
}

type Plan struct {
	Intent string
	Steps  []map[string]any
}

type PresentationPort interface {
	Render(ctx context.Context, output *domain.DecisionOutput, frame *domain.CognitiveFrame) ([]byte, error)
}

type ReasoningPort interface {
	// Verify checks the subject (Plan or Content) against the provided genome (axioms).
	Verify(ctx context.Context, subject interface{}, genome []domain.DomainGene) (*domain.AuditResult, error)

	// VerifyAtoms checks a raw set of atoms against the genome.
	VerifyAtoms(ctx context.Context, atoms []domain.Atom, genome []domain.DomainGene) (*domain.AuditResult, error)

	// Query executes a raw Datalog query against the provided genome.
	Query(ctx context.Context, query string, genome []domain.DomainGene) ([]domain.Atom, error)
}

type SimilarityStorePort interface {
	FindSimilar(ctx context.Context, intent string, content string, threshold float64) (string, bool)
	Save(ctx context.Context, item EvidenceItem) error
}

type StoragePort interface {
	SaveTrace(ctx context.Context, traceID uuid.UUID, content []byte) error
}

type Vector []float32

type VectorStorePort interface {
	// Insert adds a vector with associated metadata to the store.
	Insert(vector Vector, metadata string) error

	// Search finds the nearest neighbors to the query vector.
	// Returns a list of metadata strings for the matching vectors.
	Search(vector Vector, limit int, threshold float64) ([]string, error)
}