usecase

type AntigravityUsageCaptureResult struct {
	Applied        int
	AlreadyApplied int
	Unavailable    int
}

type AntigravityUsageCaptureUsecase interface {
	CaptureStatus(context.Context, io.Reader) (AntigravityUsageCaptureResult, error)
	CaptureStopUnavailable(context.Context, AntigravityUsageStopInput) (AntigravityUsageCaptureResult, error)
}

type AntigravityUsageStopInput struct {
	SessionID  types.SessionID
	BoundaryID string
}

type BundleConflictPolicy string

type BundleEventRepository interface {
	// SchemaVersion is the current schema_migrations max version.
	SchemaVersion(ctx context.Context) (int, error)
	ListBundleSessions(ctx context.Context) ([]*model.Session, error)
	ListBundleCommandAudits(ctx context.Context) ([]*model.CommandAudit, error)
	// ListBundleMemories returns all durable memories and their refs for bundle export.
	ListBundleMemories(ctx context.Context) ([]apptypes.MemoryDetails, error)
	// ListBundleMemoryEdges returns all memory graph edges for bundle export.
	ListBundleMemoryEdges(ctx context.Context) ([]*model.MemoryEdge, error)
	// ListBundleUsageObservations returns all provider-neutral usage evidence.
	ListBundleUsageObservations(ctx context.Context) ([]*model.UsageObservation, error)
	// ListBundleRunLineages returns every immutable run lineage fact.
	ListBundleRunLineages(ctx context.Context) ([]*model.RunLineage, error)
	// BeginBundleImport starts the single transaction used by all table
	// importers in registry order.
	BeginBundleImport(ctx context.Context) (BundleImportTransaction, error)
}

type BundleExportOptions struct {
	// OutPath is the filesystem path where the encrypted archive
	// lands.
	OutPath string
	// Passphrase derives the archive's symmetric key via
	// Argon2id. Must be non-empty — Traceary does not produce
	// unencrypted bundles because the same artifact may later be
	// carried over an untrusted channel (email, Dropbox, etc.).
	Passphrase []byte
	// Since / Until narrow the event range. Zero value disables
	// the side of the range.
	Since time.Time
	Until time.Time
	// Workspace, when non-empty, restricts exported events to a
	// single workspace.
	Workspace types.Workspace
}

type BundleImportOptions struct {
	// InPath is the filesystem path of the archive to read.
	InPath string
	// Passphrase decrypts the archive. Must match what Export used.
	Passphrase []byte
	// OnConflict controls UNIQUE collisions. Empty defaults to skip for
	// v0.9-compatible idempotent re-imports.
	OnConflict BundleConflictPolicy
	// MissingParent controls how the sessions importer handles an imported session whose parent session is absent. Empty defaults to reject.
	MissingParent BundleMissingParentPolicy
	// OrphanEdges controls memory_edges rows whose endpoints are missing after
	// memories import. Empty defaults to skip-with-warning.
	OrphanEdges BundleOrphanEdgesPolicy
}

type BundleImportResult struct {
	// EventsImported / EventsSkipped count events that were newly
	// written vs dropped because of a pre-existing (event_id)
	// collision.
	EventsImported        int
	EventsSkipped         int
	SessionsImported      int
	SessionsSkipped       int
	CommandAuditsImported int
	CommandAuditsSkipped  int
	// MemoriesImported / MemoriesSkipped count durable memories that were newly
	// written vs dropped because of a pre-existing memory id collision.
	MemoriesImported int
	MemoriesSkipped  int
	// MemoryEdgesImported / MemoryEdgesSkipped count memory graph edges that were
	// newly written vs skipped due to idempotency or orphan-edge tolerance.
	MemoryEdgesImported int
	MemoryEdgesSkipped  int
	// UsageObservationsImported / UsageObservationsSkipped count durable usage
	// observations restored vs retained as exact or policy-selected duplicates.
	UsageObservationsImported int
	UsageObservationsSkipped  int
	RunLineagesImported       int
	RunLineagesSkipped        int
	// BundleSchemaVersion is the schema_migrations version the
	// archive carried at Export time.
	BundleSchemaVersion int
}

type BundleImportTransaction interface {
	ImportSession(ctx context.Context, session *model.Session, policy BundleConflictPolicy, missingParent BundleMissingParentPolicy) (bool, error)
	ImportEvent(ctx context.Context, event *model.Event, policy BundleConflictPolicy) (bool, error)
	ImportCommandAudit(ctx context.Context, audit *model.CommandAudit, policy BundleConflictPolicy) (bool, error)
	ImportMemory(ctx context.Context, memory *model.Memory, policy BundleConflictPolicy) (bool, error)
	MemoryExists(ctx context.Context, memoryID types.MemoryID) (bool, error)
	MemoryEdgeExists(ctx context.Context, edgeID types.MemoryEdgeID) (bool, error)
	ImportMemoryEdge(ctx context.Context, edge *model.MemoryEdge, policy BundleConflictPolicy) (bool, error)
	ImportUsageObservation(ctx context.Context, observation *model.UsageObservation, policy BundleConflictPolicy) (bool, error)
	ImportRunLineage(ctx context.Context, lineage *model.RunLineage) (bool, error)
	Commit(ctx context.Context) error
	Rollback(ctx context.Context) error
}

type BundleMissingParentPolicy string

type BundleOrphanEdgesPolicy string

type BundleUsecase interface {
	Export(ctx context.Context, opts BundleExportOptions) error
	Import(ctx context.Context, opts BundleImportOptions) (BundleImportResult, error)
}

type ClaudeUsageCaptureInput struct {
	SessionID          types.SessionID
	DeliveryID         string
	FallbackSourceName string
	FallbackTerminal   types.UsageTerminalCode
}

type ClaudeUsageCaptureResult struct {
	Applied        int
	AlreadyApplied int
	Unavailable    int
}

type ClaudeUsageCaptureUsecase interface {
	Capture(context.Context, ClaudeUsageCaptureInput) (ClaudeUsageCaptureResult, error)
	CaptureHeadless(context.Context, ClaudeUsageCaptureInput, application.ClaudeUsageLoadResult) (ClaudeUsageCaptureResult, error)
}

type CodexCaptureDiagnosticUsecase interface {
	Load(
		context.Context,
		apptypes.CodexCaptureDiagnosticCriteria,
	) (apptypes.CodexCaptureDiagnosticEvidence, error)
}

type CodexUsageCaptureInput struct {
	SessionID          types.SessionID
	DeliveryID         string
	FallbackSourceName string
	FallbackTerminal   types.UsageTerminalCode
}

type CodexUsageCaptureResult struct {
	Applied        int
	AlreadyApplied int
	Unavailable    int
}

type CodexUsageCaptureUsecase interface {
	Capture(context.Context, CodexUsageCaptureInput) (CodexUsageCaptureResult, error)
	CaptureHeadless(context.Context, CodexUsageCaptureInput, application.CodexUsageLoadResult) (CodexUsageCaptureResult, error)
}

type ContextUsecase interface {
	// Handoff builds a structured ContextPack. Returns an empty Optional when no
	// matching session exists.
	Handoff(ctx context.Context, criteria apptypes.ContextPackCriteria) (types.Optional[apptypes.ContextPack], error)
}

type EventCoverageInput struct {
	SessionID string
	Kind      types.EventKind
}

type EventMetadataUsecase interface {
	List(ctx context.Context, criteria apptypes.EventListCriteria) ([]apptypes.EventMetadata, error)
	Search(ctx context.Context, criteria apptypes.EventSearchCriteria) ([]apptypes.EventMetadata, error)
	Context(ctx context.Context, criteria apptypes.EventContextCriteria) ([]apptypes.EventMetadata, error)
}

type EventUsecase interface {
	// Log records a log event. Zero-value kind defaults to note.
	// logCfg carries redaction settings; its zero value is a
	// pass-through for non-transcript kinds. For EventKindTranscript
	// the implementation applies built-in redactors + the caller's
	// extra patterns before persisting so no log-ingest surface has
	// to re-implement that policy in the presentation layer.
	Log(ctx context.Context, message string, kind types.EventKind, client types.Client, agent types.Agent, sessionID types.SessionID, workspace types.Workspace, logCfg apptypes.LogRedaction) (*model.Event, error)

	// Audit records a command execution audit event. The AuditInput value
	// object carries the command, attribution, exit code, and structural
	// failure flag; auditCfg carries the redaction policy.
	Audit(ctx context.Context, in apptypes.AuditInput, auditCfg apptypes.AuditRedaction) (*model.Event, *model.CommandAudit, error)

	// Search performs full-text search across events.
	Search(ctx context.Context, criteria apptypes.EventSearchCriteria) ([]*model.Event, error)

	// List returns events in descending time order.
	List(ctx context.Context, criteria apptypes.EventListCriteria) ([]*model.Event, error)

	// ListWindow returns every event matching the criteria whose created_at
	// falls in [From, To) under a single read snapshot, so concurrent writers
	// cannot cause the paged scan to drop events. criteria.Limit() controls
	// the per-page size for the internal scan; criteria.Offset() is ignored.
	ListWindow(ctx context.Context, criteria apptypes.EventListCriteria) ([]*model.Event, error)

	// Show returns the details for a single event.
	Show(ctx context.Context, eventID types.EventID) (apptypes.EventDetails, error)

	// Context returns recent events for the given context.
	Context(ctx context.Context, criteria apptypes.EventContextCriteria) ([]*model.Event, error)

	// Timeline returns work blocks separated by idle gaps.
	Timeline(ctx context.Context, criteria apptypes.TimelineCriteria) ([]apptypes.TimelineBlock, error)
}

type FileRetentionCapacityInspector interface {
	InspectCapacity(ctx context.Context, request apptypes.FileRetentionCapacityRequest) ([]apptypes.FileRetentionCapacityStatus, error)
}

type FileRetentionUsecase interface {
	FileRetentionCapacityInspector
	CreatePlan(ctx context.Context, request apptypes.FileRetentionPlanRequest, now time.Time) ([]byte, error)
	Apply(ctx context.Context, encodedPlan []byte, confirmedPlanID string, now time.Time) (apptypes.FileRetentionApplyResult, error)
}

type GeminiUsageCaptureInput struct {
	SessionID        types.SessionID
	DeliveryID       string
	FallbackTerminal types.UsageTerminalCode
}

type GeminiUsageCaptureResult struct {
	Applied        int
	AlreadyApplied int
	Unavailable    int
}

type GeminiUsageCaptureUsecase interface {
	CaptureHeadless(context.Context, GeminiUsageCaptureInput, application.GeminiUsageLoadResult) (GeminiUsageCaptureResult, error)
	CaptureInteractiveUnavailable(context.Context, GeminiUsageCaptureInput) (GeminiUsageCaptureResult, error)
}

type GrokUsageCaptureInput struct {
	SessionID        types.SessionID
	DeliveryID       string
	FallbackTerminal types.UsageTerminalCode
}

type GrokUsageCaptureResult struct {
	Applied        int
	AlreadyApplied int
	Unavailable    int
}

type GrokUsageCaptureUsecase interface {
	CaptureHeadless(context.Context, GrokUsageCaptureInput, application.GrokUsageLoadResult) (GrokUsageCaptureResult, error)
	CaptureHookUnavailable(context.Context, GrokUsageCaptureInput) (GrokUsageCaptureResult, error)
}

type KimiUsageBoundary string

type KimiUsageCaptureInput struct {
	SessionID         types.SessionID
	ProviderSessionID string
	Boundary          KimiUsageBoundary
}

type KimiUsageCaptureResult struct {
	Applied        int
	AlreadyApplied int
	Unavailable    int
}

type KimiUsageCaptureUsecase interface {
	Capture(context.Context, KimiUsageCaptureInput) (KimiUsageCaptureResult, error)
}

type MemoryEdgeUsecase interface {
	// Add persists a typed relationship between two memories. See
	// model.NewMemoryEdge for validation rules.
	Add(
		ctx context.Context,
		fromMemoryID types.MemoryID,
		toMemoryID types.MemoryID,
		relation types.MemoryEdgeRelation,
		validFrom types.Optional[time.Time],
		validTo types.Optional[time.Time],
	) (*model.MemoryEdge, error)

	// List returns edges matching the filter. The filter's zero
	// value returns every edge up to the limit.
	List(ctx context.Context, filter model.MemoryEdgeListFilter) ([]*model.MemoryEdge, error)
}

type MemoryToolUsecase interface {
	View(ctx context.Context, path string, viewRange []int) (string, error)
	Create(ctx context.Context, path string, fileText string) (string, error)
	StrReplace(ctx context.Context, path string, oldStr string, newStr string) (string, error)
	Insert(ctx context.Context, path string, insertLine int, insertText string) (string, error)
	Delete(ctx context.Context, path string) (string, error)
	Rename(ctx context.Context, oldPath string, newPath string) (string, error)
}

type MemoryUsecase interface {
	// Lifecycle
	// Remember records an accepted memory directly.
	Remember(
		ctx context.Context,
		memoryType domtypes.MemoryType,
		scope domtypes.MemoryScope,
		fact string,
		confidence domtypes.Optional[domtypes.Confidence],
		source domtypes.MemorySource,
		evidenceRefs []domtypes.EvidenceRef,
		artifactRefs []domtypes.ArtifactRef,
	) (apptypes.MemoryDetails, error)

	// Propose records a candidate memory that still requires review.
	Propose(
		ctx context.Context,
		memoryType domtypes.MemoryType,
		scope domtypes.MemoryScope,
		fact string,
		source domtypes.MemorySource,
		evidenceRefs []domtypes.EvidenceRef,
		artifactRefs []domtypes.ArtifactRef,
	) (apptypes.MemoryDetails, error)

	// Accept accepts an existing candidate memory.
	Accept(ctx context.Context, memoryID domtypes.MemoryID, confidence domtypes.Optional[domtypes.Confidence]) (apptypes.MemoryDetails, error)

	// Distill turns one or more candidate memories into a new accepted
	// operator-provided memory while preserving source refs.
	Distill(ctx context.Context, criteria apptypes.MemoryDistillCriteria) (apptypes.MemoryDistillResult, error)

	// Reject rejects an existing candidate memory.
	Reject(ctx context.Context, memoryID domtypes.MemoryID) (apptypes.MemoryDetails, error)

	// AttachCandidateRefs attaches supporting refs to an existing candidate
	// memory without changing its lifecycle status. New evidence is required
	// unless the candidate already has evidence; artifact-only attachments are
	// allowed only for already substantiated candidates.
	AttachCandidateRefs(
		ctx context.Context,
		memoryID domtypes.MemoryID,
		evidenceRefs []domtypes.EvidenceRef,
		artifactRefs []domtypes.ArtifactRef,
	) (apptypes.MemoryDetails, error)

	// Supersede replaces an accepted memory with a new accepted memory.
	// validFrom / validTo control the replacement's temporal validity
	// window. Both default to the legacy behaviour (validFrom=now,
	// validTo=open-ended) when None, which keeps manual supersede
	// compatible with pre-v0.8.1 callers. Callers that need to carry
	// a bounded window over to the replacement (e.g. the hygiene
	// `validity_overlap_supersede` apply) must pass the explicit
	// window through — without this, applying the suggestion would
	// discard the very window that caused the pair to be flagged.
	Supersede(
		ctx context.Context,
		memoryID domtypes.MemoryID,
		memoryType domtypes.MemoryType,
		scope domtypes.MemoryScope,
		fact string,
		confidence domtypes.Optional[domtypes.Confidence],
		source domtypes.MemorySource,
		evidenceRefs []domtypes.EvidenceRef,
		artifactRefs []domtypes.ArtifactRef,
		validFrom domtypes.Optional[time.Time],
		validTo domtypes.Optional[time.Time],
	) (apptypes.MemoryDetails, error)

	// Expire expires an active memory at the given time. Empty expiry means now.
	Expire(ctx context.Context, memoryID domtypes.MemoryID, expiresAt domtypes.Optional[time.Time]) (apptypes.MemoryDetails, error)

	// SetValidity sets the content-validity window (valid_from / valid_to)
	// on an existing memory. Either bound may be omitted to leave the
	// current value unchanged. Set clearValidTo=true to explicitly
	// remove an existing validTo (return the memory to open-ended
	// validity). clearValidTo=true with a non-empty validTo argument
	// is invalid.
	SetValidity(
		ctx context.Context,
		memoryID domtypes.MemoryID,
		validFrom domtypes.Optional[time.Time],
		validTo domtypes.Optional[time.Time],
		clearValidTo bool,
	) (apptypes.MemoryDetails, error)

	// List returns memory summaries matching the criteria.
	List(ctx context.Context, criteria apptypes.MemoryListCriteria) ([]apptypes.MemorySummary, error)

	// ListStale returns stale durable-memory rows and the total count before
	// paging. It is a read-side helper for the top dashboard's stale-memory
	// pane.
	ListStale(ctx context.Context, criteria apptypes.StaleMemoryListCriteria) (apptypes.StaleMemoryListResult, error)

	// Search searches durable memories.
	Search(ctx context.Context, criteria apptypes.MemorySearchCriteria) ([]apptypes.MemorySummary, error)

	// Show returns the details for a single durable memory.
	Show(ctx context.Context, memoryID domtypes.MemoryID) (apptypes.MemoryDetails, error)

	// Extract proposes candidate memories from existing session/history signals.
	Extract(ctx context.Context, criteria apptypes.MemoryExtractionCriteria) ([]apptypes.MemoryDetails, error)

	// ExplainExtraction returns segment-level extraction diagnostics without proposing candidates.
	ExplainExtraction(ctx context.Context, criteria apptypes.MemoryExtractionCriteria) (apptypes.MemoryExtractionDebugReport, error)

	// ImportCodex proposes candidate memories from host-native Codex memory sources.
	ImportCodex(ctx context.Context, criteria apptypes.CodexImportCriteria) (apptypes.MemoryImportResult, error)

	// ImportInstructions proposes candidate memories from host instruction files.
	ImportInstructions(ctx context.Context, criteria apptypes.MemoryBridgeImportCriteria) (apptypes.MemoryBridgeImportResult, error)

	// Decay expires eligible auto-extracted candidates (dry-run by default)
	// and optionally collapses exact duplicate candidates. Never auto-accepts.
	Decay(ctx context.Context, criteria apptypes.MemoryDecayCriteria) (apptypes.MemoryDecayResult, error)

	// Restore returns an expired memory to candidate status for re-review.
	Restore(ctx context.Context, memoryID domtypes.MemoryID) (apptypes.MemoryDetails, error)

	// Scan surfaces suggestions for accepted durable memories that need attention.
	Scan(ctx context.Context, criteria apptypes.MemoryHygieneScanCriteria) (apptypes.MemoryHygieneScanResult, error)

	// Apply commits lifecycle transitions for matching hygiene suggestions.
	Apply(ctx context.Context, criteria apptypes.MemoryHygieneApplyCriteria) (apptypes.MemoryHygieneApplyResult, error)

	// Export serializes accepted durable memories into host instruction markdown.
	Export(ctx context.Context, criteria apptypes.MemoryExportCriteria) (apptypes.MemoryExportResult, error)

	// ActivatePlan resolves a host-native activation target and renders the dry-run content.
	ActivatePlan(ctx context.Context, criteria apptypes.MemoryActivationCriteria) (apptypes.MemoryActivationPlan, error)

	// Activate writes accepted durable memories into a host-native activation target.
	Activate(ctx context.Context, criteria apptypes.MemoryActivationCriteria) (apptypes.MemoryActivationApplyResult, error)

	// ActivationStatus compares the host-native activation target with the current accepted memories.
	ActivationStatus(ctx context.Context, criteria apptypes.MemoryActivationCriteria) (apptypes.MemoryActivationStatusResult, error)
}

type MemoryUsecaseDependencies struct {
	SessionQuery queryservice.SessionQueryService
	EventQuery   queryservice.EventQueryService
	CodexSource  application.CodexMemorySource
}

type OneShotRepairUsecase interface {
	Preview(ctx context.Context, params apptypes.OneShotRepairParams) (apptypes.OneShotRepairResult, error)
	Apply(ctx context.Context, params apptypes.OneShotRepairApplyParams) (apptypes.OneShotRepairResult, error)
}

type RawBodyRetentionUsecase interface {
	CreatePlan(ctx context.Context, before time.Time, recoveryPath string, now time.Time) ([]byte, error)
	Apply(ctx context.Context, planData []byte, recoveryPath, confirmedPlanID string, now time.Time) (apptypes.RawBodyApplyResult, error)
	Restore(ctx context.Context, planData []byte, recoveryPath, confirmedPlanID string, now time.Time) (apptypes.RawBodyRestoreResult, error)
}

type ReplayUsecase interface {
	// Bundle returns a ReplayBundle that captures recent sessions (each
	// with its per-session event slice) plus the memory panel scoped to
	// those sessions' workspaces.
	Bundle(ctx context.Context, criteria apptypes.ReplayCriteria) (apptypes.ReplayBundle, error)
}

type ReportCommandUsecase interface {
	Summarize(ctx context.Context, criteria apptypes.EventListCriteria) (apptypes.ReportCommandSummary, error)
}

type ReportUsecase interface {
	Generate(ctx context.Context, criteria apptypes.ReportCriteria) (apptypes.ReportSnapshot, error)
}

type RunLineageUsecase interface {
	Record(ctx context.Context, lineage *model.RunLineage) (model.RunLineageTransition, error)
}

type SessionEventCoverage struct {
	// Sessions counts only sessions whose session_started event was
	// observed in the scanned window. List queries return newest-first, so
	// observing the start means every subsequent event of that session is
	// also in the window — this avoids misclassifying a truncated session
	// (start out of window) as prompt/transcript-missing.
	Sessions                int
	BoundaryOnly            int
	Enriched                int
	Complete                int
	PromptTranscriptMissing int
	WithPrompt              int
	WithTranscript          int
	WithCommand             int
}

type SessionUsecase interface {
	// Start begins a new session. If sessionID is zero, a new ID is generated.
	// Zero-value parentSessionID means no parent (top-level session).
	Start(ctx context.Context, client types.Client, agent types.Agent, sessionID types.SessionID, workspace types.Workspace, parentSessionID types.SessionID) (*model.Event, error)

	// StartWithRuntimeMode begins a session under an explicit non-zero runtime
	// lifecycle contract. Zero-value parentSessionID means no parent.
	StartWithRuntimeMode(ctx context.Context, client types.Client, agent types.Agent, sessionID types.SessionID, workspace types.Workspace, parentSessionID types.SessionID, runtimeMode types.RuntimeMode) (*model.Event, error)

	// StartChild begins a child session spawned from an existing parent.
	StartChild(ctx context.Context, parent types.SessionID, childID types.SessionID, agent types.Agent, workspace types.Workspace, spawnEventID types.EventID, kind string, startedAt time.Time) (*model.Event, error)

	// End closes an existing session. Zero-value client/agent/workspace
	// falls back to values from the corresponding session_started event.
	End(ctx context.Context, client types.Client, agent types.Agent, sessionID types.SessionID, workspace types.Workspace, summary string) (*model.Event, error)

	// FinalizeOneShot applies one authoritative terminal reason to an explicit
	// one-shot session. Same-reason retries return already_applied without
	// writing another boundary event; other runtime modes and conflicts fail closed.
	FinalizeOneShot(ctx context.Context, client types.Client, agent types.Agent, sessionID types.SessionID, workspace types.Workspace, reason types.TerminalReason, summary string) (model.SessionTerminalTransition, *model.Event, error)

	// Label updates the label on an existing session.
	Label(ctx context.Context, sessionID types.SessionID, label string) error

	// List returns session summaries matching the criteria.
	List(ctx context.Context, criteria apptypes.SessionListCriteria) ([]apptypes.SessionSummary, error)

	// FindEndedSessionIDs returns the subset of sessionIDs that have a persisted end boundary.
	FindEndedSessionIDs(ctx context.Context, sessionIDs []types.SessionID) (map[types.SessionID]struct{}, error)

	// Tree returns session summaries as a hierarchy for the given workspace.
	// Zero-value workspace returns sessions across all workspaces. When rootSessionID
	// is set, the requested root is included regardless of the limit window.
	Tree(ctx context.Context, workspace types.Workspace, rootSessionID types.SessionID, limit int) ([]apptypes.SessionSummary, error)

	// Lineage returns the full hierarchy rooted at the topmost ancestor of sessionID.
	Lineage(ctx context.Context, sessionID types.SessionID) ([]apptypes.SessionSummary, error)

	// Active returns the session_started event for the active session matching the criteria.
	// Returns an empty Optional when no active session exists.
	Active(ctx context.Context, criteria apptypes.SessionLookupCriteria) (types.Optional[*model.Event], error)

	// Latest returns the session_started event for the latest session matching the criteria.
	// Returns an empty Optional when no matching session exists.
	Latest(ctx context.Context, criteria apptypes.SessionLookupCriteria) (types.Optional[*model.Event], error)

	// SetSummaryIfEmpty stores summary into sessions.summary when the existing
	// value is NULL or empty. Manually authored summaries are preserved.
	// Returns true when a row was actually updated.
	SetSummaryIfEmpty(ctx context.Context, sessionID types.SessionID, summary string) (bool, error)

	// SetModelIfEmpty stores a host-reported model identifier when the session
	// row still has an empty model. Empty input is a no-op. Never fabricates
	// a model value.
	SetModelIfEmpty(ctx context.Context, sessionID types.SessionID, model string) (bool, error)

	// Handoff returns the legacy session handoff summary shape used by older CLI
	// and MCP callers.
	//
	// New callers that want the structured working-memory pack should prefer
	// ContextUsecase.Handoff instead. Zero-value workspace means no workspace
	// filter. Returns an empty Optional when no matching session exists.
	Handoff(ctx context.Context, sessionID types.SessionID, workspace types.Workspace, recent int) (types.Optional[apptypes.HandoffSummary], error)
}

type StoreManagementUsecase interface {
	// Initialize creates the store and applies migrations.
	Initialize(ctx context.Context) error

	// CreateBackup creates a backup of the store.
	CreateBackup(ctx context.Context, outputPath string, overwrite bool) error

	// RestoreBackup restores a backup into the store.
	RestoreBackup(ctx context.Context, inputPath string, overwrite bool) error

	// CollectGarbage removes events older than the given time.
	CollectGarbage(ctx context.Context, before time.Time, target apptypes.GarbageCollectionTarget, dryRun bool) (apptypes.CollectGarbageResult, error)

	// CloseStaleSessions closes sessions that started before the threshold and
	// have no activity inside it, excluding the protected active sessions.
	CloseStaleSessions(ctx context.Context, staleAfter time.Duration, dryRun bool, protectedSessionIDs []types.SessionID) (apptypes.CloseStaleSessionsResult, error)

	// DedupeContentEvents reports (dry-run) or quarantines (apply) historical
	// hook-originated prompt/transcript duplicate rows.
	DedupeContentEvents(ctx context.Context, params apptypes.ContentEventDedupeParams) (apptypes.ContentEventDedupeResult, error)

	// RestoreContentEventDedupeRun reverses a quarantine run, moving its rows
	// back into events.
	RestoreContentEventDedupeRun(ctx context.Context, runID string) (apptypes.ContentEventDedupeRestoreResult, error)

	// CreateStoreArchive exports GC-eligible rows to a versioned archive package.
	// When DeleteAfterVerify is set, verifies the package then deletes exact IDs.
	CreateStoreArchive(ctx context.Context, params apptypes.StoreArchiveCreateParams) (apptypes.StoreArchiveResult, error)
	// VerifyStoreArchive checks package integrity (and decryptability when sealed).
	VerifyStoreArchive(ctx context.Context, path string, passphrase []byte) error
	// RestoreStoreArchive imports archived rows idempotently by primary key.
	RestoreStoreArchive(ctx context.Context, path string, passphrase []byte, dryRun bool) (apptypes.StoreArchiveRestoreResult, error)
}

type UsageObservationUsecase interface {
	Record(ctx context.Context, observation *model.UsageObservation) (model.UsageObservationTransition, error)
}

type WorkspaceIdentityUsecase interface {
	Report(ctx context.Context, conflictSampleLimit int) (apptypes.WorkspaceIdentityReport, error)
	AddAlias(ctx context.Context, sessionID types.SessionID, workspace types.Workspace, reviewedBy, note string) error
	RemoveAlias(ctx context.Context, sessionID types.SessionID, workspace types.Workspace) error
}