harness

type Hit struct {
	Rank        int
	NodeID      string
	Text        string
	Score       float64
	Sim         float64
	NodeWeight  float64
	GraphMult   float64
	Depth       int
	SourceMsgID string
	TurnUUID    string // resolved from metadata when available
}

type IngestOptions struct {
	// SessionsPath: file or directory passed to corpus.Extract.
	SessionsPath string
	// CorpusStorePath: where to materialize corpus.sqlite.
	CorpusStorePath string
	// EmbedCachePath: where to materialize the content-addressed cache.
	EmbedCachePath string
	// Embedder produces chunk vectors. Wrap with the Gemini embedder in
	// production; pass fake.New(...) in tests.
	Embedder embed.Embedder
	// EmbedderModelID is the identity stored in the cache key. Bump
	// when the embedder model changes.
	EmbedderModelID string
	// EmbedderKind is "fake" or "gemini" — recorded in the manifest.
	EmbedderKind string
	// Limit caps how many files get walked when SessionsPath is a
	// directory (0 = no cap). Useful for smoke runs.
	Limit int
	// Progress receives per-file and per-chunk updates. Optional.
	Progress Progress
	// Logger is the destination for structured ingest events. Optional.
	Logger *slog.Logger
}

type IngestResult struct {
	FilesScanned    int
	FilesIngested   int
	FilesSkippedDup int
	TurnsAdded      int
	ChunksEmbedded  int
	ChunksCacheHit  int
	CorpusSnapshot  string
	Manifest        manifest.DatasetManifest
}

type Progress interface {
	StartFiles(total int)
	FileDone(path string, turns int)
	StartChunks(total int)
	ChunkDone(n int)
	Finish()
}

type QueryResult struct {
	Query      queries.LabeledQuery
	StartedAt  time.Time
	FinishedAt time.Time
	Hits       []Hit
	PreState   []inspect.NodeState // top-K node state captured before Recall
	PostState  []inspect.NodeState // same nodes after Recall
	Error      string
}

type ReplayOptions struct {
	// CorpusStorePath: source of turns (chronological).
	CorpusStorePath string
	// EmbedCachePath: cache primed by Ingest. Replay's embedder consults
	// this cache so re-running with the same corpus does not re-embed.
	EmbedCachePath string
	// Embedder produces vectors via the cache wrapper.
	Embedder embed.Embedder
	// EmbedderModelID is the cache key namespace.
	EmbedderModelID string
	// ServiceConfig is the memmy service tunable bundle. Optional;
	// nil means defaults.
	ServiceConfig *memmy.ServiceConfig
	// FlatScanThreshold below which Recall uses linear scan. 0 = default.
	FlatScanThreshold int
	// TenantTuple identifies the synthetic tenant memmy will write under.
	// Defaults to {agent: memmy-eval, dataset: <DatasetName>}.
	TenantTuple map[string]string
	// DatasetName is used as the default dataset key in TenantTuple.
	DatasetName string
	// Neo4j is the connection used for both the live memmy.Service and
	// the inspect Reader. Required.
	Neo4j inspect.Connection
}

type ReplayResult struct {
	Service       memmy.Service
	Closer        interface{ Close() error }
	Tenant        map[string]string
	FakeClock     *memmy.FakeClock
	Neo4j         inspect.Connection
	TurnsReplayed int
	NodesWritten  int
	StartedAt     time.Time
	FinishedAt    time.Time
}

type RunQueriesOptions struct {
	Service      memmy.Service
	Tenant       map[string]string
	InspectConn  inspect.Connection // Neo4j connection for the inspect Reader
	K            int
	Hops         int
	OversampleN  int
	AdvanceClock time.Duration // FakeClock advance between queries (0 = none)
	FakeClock    *memmy.FakeClock
}