daemon

type CaptureContext struct {
	BranchRef        string
	BranchGeneration int64
	BaseHead         string // HEAD OID at start of pass (or "" if no HEAD)
}

type CaptureOpts struct {
	// MaxFileBytes overrides EnvMaxFileBytes / DefaultMaxFileBytes.
	MaxFileBytes int64
	// IgnoreChecker batches gitignore checks. Caller owns the lifetime —
	// typically built once at daemon start and reused for the run.
	IgnoreChecker *git.IgnoreChecker
	// SensitiveMatcher precomputes the active sensitive glob set. Caller
	// owns the lifetime; nil falls back to a fresh matcher per pass (slow
	// but correct).
	SensitiveMatcher *state.SensitiveMatcher
	// SafeIgnoreMatcher precomputes generated dependency/cache trees that
	// ACD skips internally even when they are not gitignored. Nil falls
	// back to a fresh matcher per pass.
	SafeIgnoreMatcher *state.SafeIgnoreMatcher
	// SubmodulePaths is the set of repo-relative paths that are submodules
	// (mode 160000 in HEAD's tree). Capture must not descend into them.
	SubmodulePaths map[string]bool
	// Trace receives best-effort decision records. Nil disables tracing.
	Trace acdtrace.Logger
	// GitDir is the absolute .git directory. Required to consult the
	// daemon pause gate (manual marker + rewind grace meta). Empty
	// disables the in-Capture pause check entirely; callers that have
	// already gated externally (e.g. the run loop) should set
	// SkipPauseCheck instead so the gate is symmetric across direct and
	// run-loop invocations.
	GitDir string
	// SkipPauseCheck disables the daemon pause gate inside Capture. The
	// run loop already gates capture+replay on the same pause state and
	// emits a single trace event before either pass runs; setting this
	// flag avoids a double-trace. Direct callers (tests, future CLI
	// wrappers) leave it false to honor the gate.
	SkipPauseCheck bool
	// SortByPath, when true, reorders the slice returned by Classify into
	// lexicographic ascending Path order BEFORE the per-op
	// AppendCaptureEvent insert loop runs and BEFORE the pending-depth
	// cap is applied; events that overflow the cap mid-pass are
	// therefore the lex-largest paths, not the most recently edited.
	// Daemon run-loop callers leave this false; the live walk's iteration
	// order is preserved exactly as before. Used by tests and tooling
	// (`acd commit-all`) that need deterministic seq ordering across passes.
	SortByPath bool

	// DisablePendingCap, when true, disables the per-generation
	// pending-depth cap (EnvMaxPendingEvents) for THIS Capture call only.
	// Daemon run-loop callers leave this false so the documented
	// backpressure invariant holds. Single-shot tools like
	// `acd commit-all` set it true so a cold-start dirty worktree can
	// drain in one pass without the mid-walk drop fence kicking in.
	// Mutually exclusive with MaxPendingEventsOverride: when both are
	// set, DisablePendingCap wins. The process-wide env var is NOT
	// touched.
	DisablePendingCap bool

	// MaxPendingEventsOverride overrides the per-generation pending-depth
	// cap for this Capture call only when > 0. -1 (or any negative value)
	// is treated as unset and falls back to resolveMaxPendingEvents().
	// Zero falls through to the env-derived default; use
	// DisablePendingCap to actually turn the cap off. The process-wide
	// env var is NOT touched.
	MaxPendingEventsOverride int64
}

type CaptureSummary struct {
	EventsAppended   int   // number of capture_events rows inserted
	EventsDropped    int   // ops refused due to ACD_MAX_PENDING_EVENTS cap
	Oversize         int   // files skipped due to size cap
	Errors           int   // soft errors (per-file lstat/open failures)
	WalkedFiles      int64 // for diagnostics
	PendingDepth     int   // pending depth observed for the active generation at end of pass (0 if cap disabled)
	PendingHighWater int64 // updated daemon_meta.capture.pending_high_water value (0 if not bumped)
	// Skipped is true when Capture intentionally skipped the walk before
	// touching the worktree (e.g. an active manual pause marker or rewind
	// grace). Mirrors ReplaySummary.Skipped so direct callers can short-
	// circuit the same way the run loop does.
	Skipped bool
	// SkipReason is a short human-readable label populated alongside
	// Skipped. Empty when Skipped is false.
	SkipReason string
	// BackpressurePaused is true when the pass observed the durable
	// capture-backpressure gate as active (either entered this pass or
	// entered earlier and not yet cleared). The walk is skipped on entry;
	// the field is also true for the same pass that drops the gate to
	// describe the state across the transition.
	BackpressurePaused bool
	// BackpressureCleared is true when this pass observed the durable
	// capture-backpressure gate transitioning from active to inactive
	// (pending dropped below CaptureBackpressureClearRatio * cap).
	BackpressureCleared bool
	// EventsDroppedTotal mirrors daemon_meta.capture.events_dropped_total
	// after this pass. 0 when the cumulative counter has never advanced.
	EventsDroppedTotal int64
}

type ClassifiedOp struct {
	Op         string // "create" | "modify" | "delete" | "mode" | "rename"
	Path       string
	OldPath    string
	BeforeOID  string
	BeforeMode string
	AfterOID   string
	AfterMode  string
	Fidelity   string // "rescan" for poll-driven capture
}

type ControlLock struct {
	// contains filtered or unexported fields
}

type DaemonLock struct {
	// contains filtered or unexported fields
}

type EventContext struct {
	Event state.CaptureEvent
	Ops   []state.CaptureOp
}

type FsnotifyOptions struct {
	RepoPath      string
	GitDir        string
	IgnoreChecker fsnotifyIgnoreChecker
	Sensitive     *state.SensitiveMatcher
	SafeIgnore    *state.SafeIgnoreMatcher
	Debounce      time.Duration
	MaxWatches    int
	WakeFn        func()
	Logger        *slog.Logger
	DiagnosticsFn func(WatcherDiagnostics)
}

type FsnotifyWatcher struct {
	// contains filtered or unexported fields
}

type LiveEntry struct {
	Path string
	Mode string // git mode bits ("100644", "100755", "120000")
	OID  string // blob OID
}

type LiveIndexRepairSummary struct {
	Candidates int
	Applied    int
	Skipped    []git.LiveIndexSkip
}

type MessageFn func(ctx context.Context, ec EventContext) (string, error)

type Options struct {
	// RepoPath is the absolute path to the worktree root.
	RepoPath string
	// GitDir is the absolute .git directory.
	GitDir string
	// DB is the already-open per-repo state database. Run does NOT close
	// the DB on exit — caller owns the lifetime.
	DB *state.DB

	// Logger emits all run-loop progress. Nil falls back to slog.Default().
	Logger *slog.Logger

	// Scheduler is the backoff helper. Zero-valued struct = production
	// defaults; tests pass a Scheduler with smaller bases/ceilings to keep
	// the suite fast.
	Scheduler Scheduler

	// BootGrace is the post-start window during which empty refcount
	// sweeps do not count toward self-termination. Zero falls back to
	// DefaultBootGrace.
	BootGrace time.Duration

	// EventRetention overrides the capture_events retention window. Zero
	// falls back to DefaultEventRetention (with EnvEventRetentionDays
	// honored).
	EventRetention time.Duration

	// ClientTTL overrides the daemon_clients TTL. Zero falls back to
	// DefaultClientTTL (or EnvClientTTLSeconds if set).
	ClientTTL time.Duration

	// EmptySweepThreshold overrides the consecutive-empty-sweeps gate.
	// Zero falls back to DefaultEmptySweepThreshold.
	EmptySweepThreshold int

	// ClientSweepInterval throttles refcount sweeps. Zero falls back to
	// DefaultClientSweepInterval.
	ClientSweepInterval time.Duration

	// PruneInterval throttles the capture_events pruner. Zero falls back
	// to DefaultPruneInterval.
	PruneInterval time.Duration

	// RollupInterval caps how often the daily rollup hook may run. Zero
	// falls back to DefaultRollupInterval. The aggregator is also fired
	// immediately when a UTC-day boundary crossing is detected.
	RollupInterval time.Duration

	// CentralStatsDBPath, when non-empty, opens the central stats.db at
	// daemon start and pushes per-repo daily_rollups into it after each
	// rollup pass. Empty means "skip central push" — only the per-repo
	// daily_rollups table is updated. Tests typically leave this empty.
	CentralStatsDBPath string

	// CentralStats, when non-nil, is used as the central stats handle
	// instead of opening one from CentralStatsDBPath. Tests inject a
	// pre-opened *central.StatsDB this way to avoid filesystem coupling.
	CentralStats *central.StatsDB

	// RepoHash is the stable cross-repo identifier used when pushing
	// per-repo daily_rollups into the central stats.db. Empty disables
	// the central push (logged but non-fatal).
	RepoHash string

	// MessageFn produces commit messages. Nil falls back to a MessageFn
	// derived from MessageProvider (or, when MessageProvider is also nil,
	// from ai.BuildProvider(ai.LoadProviderConfigFromEnv())). Tests may
	// pin a deterministic MessageFn here directly without involving the
	// ai package at all.
	MessageFn MessageFn

	// MessageProvider, when non-nil, is the ai.Provider used to compose
	// commit messages on the replay path. Nil triggers env-driven
	// selection via ai.LoadProviderConfigFromEnv + ai.BuildProvider —
	// production callers leave this nil and rely on ACD_AI_*. Tests can
	// inject a stub Provider to assert the message reaches the commit.
	MessageProvider ai.Provider

	// MessageProviderCloser, when non-nil, is closed on Run shutdown.
	// Pair this with MessageProvider when the provider holds OS
	// resources (currently only ai.SubprocessProvider). When Run
	// constructs the provider itself from env vars, the closer returned
	// by ai.BuildProvider is captured automatically.
	MessageProviderCloser io.Closer

	// Now lets tests inject a fake clock. Nil falls back to time.Now.
	Now func() time.Time

	// WakeCh is an optional injection point so tests can trigger wakes
	// without sending real OS signals. Production callers leave this nil
	// and the loop relies on InstallSignalHandlers' SIGUSR1 channel.
	WakeCh <-chan struct{}

	// ShutdownCh is the test-side equivalent for SIGTERM/SIGINT. Nil
	// falls back to InstallSignalHandlers' shutdown channel.
	ShutdownCh <-chan struct{}

	// SkipSignals disables the real os/signal registration. Tests that
	// inject WakeCh / ShutdownCh set this to true so the test goroutine
	// has full control over wake + shutdown.
	SkipSignals bool

	// FlushLimit caps how many flush_requests are drained per iteration.
	// Zero falls back to DefaultFlushLimit (256). Tests set it to 1 for
	// tighter control.
	FlushLimit int

	// FsnotifyEnabled turns on the recursive fsnotify watcher (D11 hybrid).
	// Default is false so the existing test suite keeps deterministic
	// poll-only timing; production callers (and the integration test) opt
	// in by setting this true. Even when true, ACD_DISABLE_FSNOTIFY=1
	// forces poll-only mode at watcher construction time.
	FsnotifyEnabled bool

	// FsnotifyDebounce overrides the trailing-edge debounce on fsnotify
	// wakes. Zero falls back to DefaultDebounce.
	FsnotifyDebounce time.Duration

	// FsnotifyMaxWatches caps the OS watch budget. Zero asks the watcher
	// to derive a sensible default from the platform.
	FsnotifyMaxWatches int

	// Trace receives best-effort decision records. Nil uses ACD_TRACE env
	// wiring; disabled env returns a no-op logger.
	Trace acdtrace.Logger
}

type ReplayOpts struct {
	// MessageFn produces the commit message. Nil falls back to
	// DeterministicMessage.
	MessageFn MessageFn

	// IndexFile is the GIT_INDEX_FILE path used for an isolated index. When
	// empty, Replay creates a per-pass tempfile under <gitDir>/acd and
	// removes it before returning. Caller-provided values are left in place
	// for tests that need to inspect the index.
	IndexFile string

	// GitDir is the absolute git dir for the worktree. Required to seed a
	// default IndexFile.
	GitDir string

	// Limit caps the number of events drained per call. 0 = no limit.
	//
	// The run loop sets Limit = DefaultReplayLimit so each replay pass returns
	// to the daemon promptly enough to claim flush_requests, refresh the
	// heartbeat, and observe shutdown. ReplaySummary.HasMore signals whether
	// the queue still contains pending work so the run loop can schedule an
	// immediate follow-up wake instead of waiting for the next poll tick.
	Limit int
	// Trace receives best-effort decision records. Nil disables tracing.
	Trace acdtrace.Logger
	// PromptTrace receives opt-in provider prompt records. Nil disables prompt
	// persistence.
	PromptTrace prompttrace.Logger

	// CommitStrategy selects one-event replay or intent-grouped replay. Empty
	// resolves from ACD_COMMIT_STRATEGY, preserving event replay by default.
	CommitStrategy ai.CommitStrategy

	// IntentPlanner chooses selected/deferred capture groups when
	// CommitStrategy is intent. Nil falls back to the env-selected AI provider,
	// and then deterministic planning if that provider is unavailable.
	IntentPlanner ai.IntentPlanner

	// IntentWindow caps the normal planning window. Zero resolves from env.
	IntentWindow int

	// IntentMinPending is the preferred pending-count gate before intent
	// planning starts. Zero resolves from env.
	IntentMinPending int

	// IntentMaxPendingAge is the bounded wait escape hatch for sparse pending
	// queues that have not reached IntentMinPending. Zero resolves from env.
	IntentMaxPendingAge time.Duration

	// IntentRecentCommits caps recent history context supplied to the planner.
	// Zero resolves from env.
	IntentRecentCommits int

	// IntentDeferLimit controls forced-aging windows. Zero resolves from env;
	// use a negative value in tests to force zero.
	IntentDeferLimit int

	// IntentIncludeDiffs permits captured diffs in planner requests. Production
	// callers should leave this false unless diff egress is explicitly enabled.
	IntentIncludeDiffs bool

	// IntentBypassBatchWait lets explicit flush requests plan the currently
	// visible pending window without waiting for IntentMinPending or
	// IntentMaxPendingAge.
	IntentBypassBatchWait bool
}

type ReplaySummary struct {
	Published int // events that produced a new commit
	Conflicts int // events terminally settled in state.EventStateBlockedConflict
	Failed    int // events marked failed (validation/commit errors)
	BaseHead  string
	Skipped   bool // replay drain was intentionally skipped without publishing
	// SkippedReason distinguishes intentional no-op passes from an empty
	// pending queue. Empty means replay was not skipped or the legacy pause
	// skip path set only Skipped.
	SkippedReason string
	// HasMore is true when ReplayOpts.Limit capped the batch and at least one
	// additional pending event was visible beyond the cap. The run loop uses
	// this to schedule an immediate follow-up replay pass without waiting for
	// the next poll tick. Always false when Limit <= 0 (unbounded drain).
	HasMore bool
}

type RunDailyRollupOpts struct {
	// RepoPath is stamped into daily_rollups.repo_root for cross-repo
	// joins. Required.
	RepoPath string
	// Now lets tests inject a fake clock. Nil falls back to time.Now.
	Now func() time.Time
}

type Scheduler struct {
	Base         time.Duration
	IdleCeiling  time.Duration
	ErrorCeiling time.Duration
}

type SelfTerminateOpts struct {
	BootGrace           time.Duration
	EmptySweepThreshold int
}

type ShadowEntry struct {
	Path string
	Mode string
	OID  string
}

type Signals struct {
	Wake     <-chan struct{}
	Shutdown <-chan struct{}
}

type SweepOpts struct {
	// TTL overrides DefaultClientTTL. Zero falls back to default.
	TTL time.Duration
	// CaptureFingerprint resolves a live fingerprint for a pid. Defaulted to
	// identity.Capture; tests inject a deterministic stub so they don't need
	// a real `ps`. A nil function defaults to identity.Capture.
	CaptureFingerprint func(context.Context, int) (identity.Fingerprint, error)
	// AliveFn checks pid liveness. Defaulted to identity.Alive; tests inject.
	AliveFn func(context.Context, int) bool
}

type TokenTransition int

type WatcherDiagnostics struct {
	// Mode is "fsnotify" while the OS watcher is live, "poll" once we've
	// fallen back to poll-only.
	Mode string
	// WatchCount is the number of directories the OS watcher currently
	// holds. Zero in poll mode.
	WatchCount int
	// DroppedEvents is the running count of fsnotify channel errors. The
	// poll loop is still the safety net so a few drops are non-fatal.
	DroppedEvents int
	// FallbackReason names the trigger that put us in poll mode. Empty
	// while Mode=="fsnotify".
	FallbackReason string
}