application

type AntigravityUsageRepository interface {
	model.UsageObservationRepository
	FindSnapshotHead(context.Context, string) (types.Optional[*model.UsageObservation], error)
}

type AntigravityUsageSnapshot struct {
	ConversationID types.SessionID
	Model          string
	SourceVersion  string
	ObservedAt     time.Time
	InputTokens    int64
	OutputTokens   int64
}

type AntigravityUsageSource interface {
	Decode(context.Context, io.Reader) (*AntigravityUsageSnapshot, error)
}

type ArchiveTableData struct {
	Name       string
	PrimaryKey []string
	Rows       []map[string]any
}

type ClaudeHeadlessUsageStream interface {
	io.Writer
	Complete() (ClaudeUsageLoadResult, error)
}

type ClaudeHeadlessUsageStreamFactory interface {
	New(io.Writer) ClaudeHeadlessUsageStream
}

type ClaudePluginDetection struct {
	// Active is true when the user's ~/.claude/settings.json lists a
	// Traceary plugin under enabledPlugins with value true.
	Active bool
	// SettingsPath is the absolute path that was consulted.
	SettingsPath string
	// PluginKey is the enabledPlugins key that matched, e.g.
	// "traceary@traceary-plugins". Empty when Active is false.
	PluginKey string
}

type ClaudePluginDetector interface {
	DetectClaudeTracearyPluginIn(home string) ClaudePluginDetection
}

type ClaudeUsageCaptureMode string

type ClaudeUsageCounters struct {
	InputTokens           *int64
	CachedInputTokens     *int64
	CacheWriteInputTokens *int64
	OutputTokens          *int64
	ReasoningOutputTokens *int64
	TotalTokens           *int64
}

type ClaudeUsageLoadCriteria struct {
	SessionID types.SessionID
}

type ClaudeUsageLoadResult struct {
	Mode             ClaudeUsageCaptureMode
	Samples          []ClaudeUsageSample
	BoundaryObserved bool
}

type ClaudeUsageRepository interface {
	model.UsageObservationRepository
}

type ClaudeUsageSample struct {
	RecordID      string
	SourceName    string
	SourceVersion string
	Model         string
	Scope         types.UsageScope
	ObservedAt    time.Time
	TerminalCode  types.UsageTerminalCode
	Available     bool
	Counters      ClaudeUsageCounters
}

type ClaudeUsageSource interface {
	Load(context.Context, ClaudeUsageLoadCriteria) (ClaudeUsageLoadResult, error)
}

type CodexHeadlessUsageStream interface {
	io.Writer
	Complete() (CodexUsageLoadResult, error)
}

type CodexHeadlessUsageStreamFactory interface {
	New(destination io.Writer) CodexHeadlessUsageStream
}

type CodexMemorySource interface {
	// Load walks the configured root (criteria.Root) and returns candidate
	// rows. Implementations are expected to perform path containment
	// checks — the returned slice must only contain rows whose source path
	// stays inside the resolved root — and to emit non-fatal issues via
	// the warnings return value so the usecase can forward them to the
	// CLI.
	Load(ctx context.Context, criteria apptypes.CodexImportCriteria) ([]apptypes.ImportedMemoryCandidate, []string, error)
}

type CodexUsageCounters struct {
	InputTokens           *int64
	CachedInputTokens     *int64
	CacheWriteInputTokens *int64
	OutputTokens          *int64
	ReasoningOutputTokens *int64
	TotalTokens           *int64
}

type CodexUsageLoadCriteria struct {
	SessionID types.SessionID
}

type CodexUsageLoadResult struct {
	Samples          []CodexUsageSample
	BoundaryObserved bool
}

type CodexUsageRepository interface {
	model.UsageObservationRepository
	RecordExclusive(
		ctx context.Context,
		key types.UsageExclusivityKey,
		additive, excluded *model.UsageObservation,
	) (model.UsageObservationTransition, error)
}

type CodexUsageSample struct {
	RecordID      string
	SuppressionID string
	SourceName    string
	SourceVersion string
	Model         string
	ObservedAt    time.Time
	TerminalCode  types.UsageTerminalCode
	Available     bool
	Counters      CodexUsageCounters
}

type CodexUsageSource interface {
	Load(ctx context.Context, criteria CodexUsageLoadCriteria) (CodexUsageLoadResult, error)
}

type FileRetentionExecutor interface {
	ApplyFileRetention(ctx context.Context, plan apptypes.FileRetentionPlan, confirmedPlanID string, now time.Time) (apptypes.FileRetentionApplyResult, error)
}

type FileRetentionInventory interface {
	InspectFileRetention(ctx context.Context, request apptypes.FileRetentionInventoryRequest) (apptypes.FileRetentionInventorySnapshot, error)
}

type GeminiHeadlessUsageStream interface {
	io.Writer
	Complete() (GeminiUsageLoadResult, error)
}

type GeminiHeadlessUsageStreamFactory interface {
	New(io.Writer) GeminiHeadlessUsageStream
}

type GeminiUsageCounters struct {
	InputTokens       *int64
	CachedInputTokens *int64
	OutputTokens      *int64
	TotalTokens       *int64
}

type GeminiUsageLoadResult struct {
	Samples          []GeminiUsageSample
	BoundaryObserved bool
}

type GeminiUsageRepository interface {
	model.UsageObservationRepository
}

type GeminiUsageSample struct {
	RecordID      string
	SourceName    string
	SourceVersion string
	Model         string
	ObservedAt    time.Time
	TerminalCode  types.UsageTerminalCode
	Available     bool
	Counters      GeminiUsageCounters
}

type GrokHeadlessUsageStream interface {
	io.Writer
	Complete() (GrokUsageLoadResult, error)
}

type GrokHeadlessUsageStreamFactory interface {
	New(io.Writer) GrokHeadlessUsageStream
}

type GrokUsageCounters struct {
	InputTokens       *int64
	CachedInputTokens *int64
	OutputTokens      *int64
	ReasoningTokens   *int64
	TotalTokens       *int64
}

type GrokUsageLoadResult struct {
	Samples          []GrokUsageSample
	BoundaryObserved bool
	TerminalRecordID string
	TerminalCode     types.UsageTerminalCode
}

type GrokUsageRepository interface {
	model.UsageObservationRepository
}

type GrokUsageSample struct {
	RecordID      string
	SourceName    string
	SourceVersion string
	Model         string
	ObservedAt    time.Time
	TerminalCode  types.UsageTerminalCode
	Available     bool
	Counters      GrokUsageCounters
}

type HookDuplicate struct {
	Event      string
	Matcher    string
	ManagedKey string
	Count      int
}

type HookManagedCoverage struct {
	HasPrompt     bool
	HasTranscript bool
	HasAudit      bool
	HasCompact    bool
}

type HookManagedEntry struct {
	Event      string
	Matcher    string
	Name       string
	ManagedKey string
}

type HookUpgradeDiff struct {
	AddedEvents     []string
	RefreshedEvents []string
	PreservedEvents []string
	RemovedEvents   []string
}

type HooksClientHandler interface {
	// Name returns the canonical client identifier (e.g. "claude").
	Name() string

	// Build returns the Hooks aggregate Traceary installs for this client.
	// tracearyBin is the command or path used to launch the traceary binary.
	Build(tracearyBin string) model.Hooks

	// DefaultInstallPath returns the standard configuration file path
	// for this client relative to the given project directory.
	DefaultInstallPath(projectDir string) (string, error)
}

type HooksInspector interface {
	// Inspect parses the given hook configuration content and reports
	// whether it contains a top-level "hooks" field and whether any
	// Traceary-managed hook was detected.
	//
	// Returned errors are the sentinel errors defined in hooks_errors.go:
	// ErrHookConfigNotJSONObject when the payload is not a JSON object and
	// ErrHookConfigInvalidHooksField when the "hooks" field has the wrong
	// shape.
	Inspect(content []byte) (hasHooksField bool, hasTracearyManagedHook bool, err error)
	// DuplicateManagedHooks reports Traceary-managed hook registrations that
	// appear more than once for the same event, matcher, and managed key.
	// Missing hooks fields return an empty slice. Returned errors are the
	// same sentinels as Inspect.
	DuplicateManagedHooks(content []byte) ([]HookDuplicate, error)
	// ExtractManagedKeyFromEntry returns the canonical Traceary-managed
	// key extracted from a hook entry's name / command pair, or an
	// empty string if the entry is not Traceary-managed. Presentation
	// code uses this to recognise installed hook entries without
	// re-implementing the command parsing.
	ExtractManagedKeyFromEntry(name, command string) string
	// ManagedCoverage reports which Traceary-managed enrichment surfaces
	// (prompt, transcript, shell audit, compact) are wired for the given
	// client in the hook configuration content. Missing hooks fields or a
	// payload with no matching Traceary-managed entries return a zero
	// HookManagedCoverage. Returned errors are the same sentinels as
	// Inspect.
	ManagedCoverage(content []byte, client string) (HookManagedCoverage, error)
}

type HooksOrchestrator interface {
	// Generate returns the rendered hook configuration bytes for the given
	// client. tracearyBin is the command or path used to launch the traceary
	// binary.
	Generate(ctx context.Context, client string, tracearyBin string) ([]byte, error)

	// GenerateWithMatcher is the matcher-aware variant of Generate. The
	// matcher preset only affects clients that honor a preset (Claude
	// Code today); other clients ignore the value. Empty string means
	// "use the client's default matcher set" and is equivalent to
	// calling Generate directly.
	GenerateWithMatcher(ctx context.Context, client string, tracearyBin string, matcherPreset string) ([]byte, error)

	// Install writes the hook configuration file for the given client.
	// outputPath overrides the default install path when present. force
	// overwrites the existing file instead of merging with it.
	// The returned string is the resolved absolute path that was written.
	Install(
		ctx context.Context,
		client string,
		tracearyBin string,
		projectDir string,
		outputPath types.Optional[string],
		force bool,
	) (string, error)

	// InstallWithMatcher is the matcher-aware variant of Install. The
	// matcher preset only affects clients that honor a preset (Claude
	// Code today); other clients ignore the value. Callers should pass
	// the empty string to request the client's default matcher set,
	// which is equivalent to calling Install directly.
	InstallWithMatcher(
		ctx context.Context,
		client string,
		tracearyBin string,
		projectDir string,
		outputPath types.Optional[string],
		force bool,
		matcherPreset string,
	) (string, error)

	// UpgradeWithMatcher applies the current hook configuration for the
	// given client in merge-only mode (never overwrites) and returns a
	// HookUpgradeDiff describing which events were added, refreshed, or
	// preserved. It is the primary entrypoint for non-destructive
	// migrations from older Traceary releases: the file is left byte
	// identical when already up to date (idempotent).
	UpgradeWithMatcher(
		ctx context.Context,
		client string,
		tracearyBin string,
		projectDir string,
		outputPath types.Optional[string],
		matcherPreset string,
	) (string, HookUpgradeDiff, error)

	// RemoveManaged removes only Traceary-owned commands from an existing hook
	// configuration. When dryRun is true it returns the entries that would be
	// removed without writing. Unrelated hooks and top-level fields are kept.
	RemoveManaged(
		ctx context.Context,
		outputPath string,
		dryRun bool,
	) ([]HookManagedEntry, error)

	// SupportedClients returns the canonical list of supported client
	// identifiers (e.g. "claude", "codex", "gemini").
	SupportedClients() []string

	// NormalizeClient resolves a client alias (e.g. "claude-code") to its
	// canonical identifier (e.g. "claude").
	NormalizeClient(client string) (string, error)

	// ResolveInstallPath returns the configuration file path that Install
	// would write to for the given client and project directory. When
	// outputPath is present it overrides the default install path.
	ResolveInstallPath(
		client string,
		projectDir string,
		outputPath types.Optional[string],
	) (string, error)
}

type KimiUsageCounters struct {
	InputOther         *int64
	InputCacheRead     *int64
	InputCacheCreation *int64
	Output             *int64
}

type KimiUsageLoadResult struct {
	Samples           []KimiUsageSample
	LatestTurnOrdinal int64
}

type KimiUsageRepository interface {
	model.UsageObservationRepository
}

type KimiUsageSample struct {
	RecordID      string
	SourceName    string
	SourceVersion string
	Model         string
	ObservedAt    time.Time
	Counters      KimiUsageCounters
}

type KimiUsageSource interface {
	Load(context.Context, string) (KimiUsageLoadResult, error)
}

type OneShotRepairSafetyStore interface {
	CreateBackup(ctx context.Context, outputPath string, overwrite bool) error
	Initialize(ctx context.Context) error
}

type OneShotRepairStore interface {
	PreviewOneShotSessions(ctx context.Context, params apptypes.OneShotRepairParams) (apptypes.OneShotRepairResult, error)
	ApplyOneShotSessions(ctx context.Context, params apptypes.OneShotRepairParams) (apptypes.OneShotRepairResult, error)
}

type PluginCacheInspector interface {
	// DetectClaudePluginCacheStatus resolves the cached plugin version
	// and the marketplace plugin.json version for the given pluginKey
	// (of the form "<plugin>@<marketplace>"). Missing caches and
	// missing marketplace clones are reported via empty fields rather
	// than as errors; only structural IO errors surface through the
	// returned struct.
	DetectClaudePluginCacheStatus(home, pluginKey string) PluginCacheStatus
}

type PluginCacheStatus struct {
	// CachePath is the directory scanned for cached plugin versions.
	// Empty when detection could not resolve it.
	CachePath string
	// CachedVersion is the highest version found under CachePath.
	// Empty when no versioned directory exists (plugin never cached).
	CachedVersion string
	// CachedVersions lists every non-orphaned versioned cache
	// directory found under CachePath, sorted from highest to lowest
	// by semver. Diagnostics use the full list to detect the
	// session-snapshot ambiguity reported in #670.
	CachedVersions []string
	// MarketplaceVersion is the plugin.json "version" Claude Code
	// sees via `~/.claude/plugins/marketplaces/<marketplace>/...`.
	// Empty when the marketplace clone is missing.
	MarketplaceVersion string
	// MarketplacePath is the plugin.json path that was read (empty if
	// the read failed).
	MarketplacePath string
}

type RawBodyRetentionExecutor interface {
	ApplyRawBodyPlan(ctx context.Context, databaseIdentity string, sqliteUserVersion int, migrationDigest, planID string, candidates []apptypes.RawBodyCandidate, appliedAt time.Time) (apptypes.RawBodyApplyResult, error)
	RestoreRawBodyPlan(ctx context.Context, databaseIdentity string, sqliteUserVersion int, migrationDigest, planID string, bodies []apptypes.RawBodyRecoveryBody, restoredAt time.Time) (apptypes.RawBodyRestoreResult, error)
}

type RawBodyRetentionPlanner interface {
	ListRawBodyCandidates(ctx context.Context, before time.Time) (apptypes.RawBodyRetentionSnapshot, error)
}

type StoreArchiver interface {
	// ListArchiveEligible returns full row maps for GC-eligible records.
	ListArchiveEligible(ctx context.Context, before time.Time, target apptypes.GarbageCollectionTarget) ([]ArchiveTableData, error)
	// DeleteArchiveRows deletes exact primary-key sets in FK-safe order.
	// idsByTable maps table name → composite id strings (NUL-separated for multi-column PKs).
	DeleteArchiveRows(ctx context.Context, idsByTable map[string][]string) (int, error)
	// RestoreArchiveRows inserts rows idempotently. Conflicts (same PK, different content) are counted.
	RestoreArchiveRows(ctx context.Context, tables []ArchiveTableData, dryRun bool) (inserted, skipped, conflicts int, err error)
}

type StoreManager 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.
	RestoreBackup(ctx context.Context, inputPath string, overwrite bool) error
	// CollectGarbage removes events older than the given time. Returns the count of deleted events.
	CollectGarbage(ctx context.Context, before time.Time, target apptypes.GarbageCollectionTarget, dryRun bool) (int, 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) (int, error)
	// DedupeContentEvents reports (and, when params.Apply is set, quarantines)
	// historical hook-originated prompt/transcript duplicate rows. It never hard-
	// deletes: duplicates are moved into the reversible quarantine archive.
	DedupeContentEvents(ctx context.Context, params apptypes.ContentEventDedupeParams) (apptypes.ContentEventDedupeResult, error)
	// RestoreContentEventDedupeRun moves the rows quarantined by the given dedupe
	// run back into events. It fails rather than overwrite if an original event
	// id already exists in events.
	RestoreContentEventDedupeRun(ctx context.Context, runID string) (apptypes.ContentEventDedupeRestoreResult, error)
}