state

type DataDirProbeResult struct {
	// FsyncMillis is how long the probe's write+fsync took, in milliseconds.
	FsyncMillis int64 `json:"fsyncMillis"`

	// Slow is true when FsyncMillis exceeded the configured threshold
	// (dataDirSlowFsyncThreshold by default) — the same condition that
	// triggers the one-time startup warning log line.
	Slow bool `json:"slow"`

	// ProbedAt is when the probe ran, UTC.
	ProbedAt time.Time `json:"probedAt"`

	// FsType is the filesystem type hosting the data dir per /proc/mounts
	// (e.g. "ext4", "9p", "fuse.grpcfuse"); empty when it couldn't be read
	// (non-Linux, or /proc/mounts unavailable).
	FsType string `json:"fsType,omitempty"`

	// MountClass is a coarse classification of FsType used to tailor the
	// slow-filesystem advisory: "native" (real in-VM/host filesystem —
	// slowness means I/O pressure, not a bind mount), "shared" (Docker
	// Desktop file-sharing protocol — the bind-mount tax; switching to a
	// named volume applies), or "unknown".
	MountClass string `json:"mountClass,omitempty"`
}

type DebugFlushRecord struct {
	Timestamp      time.Time `json:"timestamp"`
	DurationMillis int64     `json:"durationMillis"`
	Entries        int       `json:"entries"`
	Committed      bool      `json:"committed"`

	// Chunks is how many separate SQLite transactions this flush attempt
	// split Entries across (storage-pressure-handling item 2 — see
	// HybridStore's chunkHybridFlushOps). 1 for a batch small enough to fit
	// in a single transaction; 0 for backends that don't chunk flushes.
	Chunks int `json:"chunks,omitempty"`
}

type DebugMetrics struct {
	// Mode identifies which backend produced this snapshot (e.g. "hybrid",
	// "persistent"), matching config.Config.State's values.
	Mode string `json:"mode"`

	// FlushHistory holds the most recent flush attempts, oldest first,
	// bounded to a small ring buffer. Empty for backends that write
	// synchronously and never batch/flush (e.g. SQLiteStore).
	FlushHistory []DebugFlushRecord `json:"flushHistory,omitempty"`

	// SeedDurationMillis is how long the background TierHot seed took to
	// complete, in milliseconds, or nil if seeding hasn't finished yet, is
	// still in flight, degraded to memory-only before finishing (see
	// HybridStore.degradeToMemoryOnly — there is no coherent "seed
	// duration" for a seed that didn't complete), or never happens for this
	// backend at all.
	SeedDurationMillis *int64 `json:"seedDurationMillis,omitempty"`

	// PendingLogBytes is the current on-disk size of the not-yet-flushed
	// write-ahead log, in bytes. 0 for backends without one.
	PendingLogBytes int64 `json:"pendingLogBytes,omitempty"`

	// NamespaceRowCounts maps namespace -> row count, populated only when
	// DebugMetricsOptions.IncludeNamespaceRowCounts was set.
	NamespaceRowCounts map[string]int `json:"namespaceRowCounts,omitempty"`

	// ReadRetryCount is the total number of individual retry attempts made
	// by the hybrid SQLite read-retry path (retrySQLiteGet/List/
	// ListNamespaces/Scan/ScanPage in hybrid.go) since process start, after
	// an initial read hit busy/locked contention or a canceled context. One
	// Get/List/Scan call under contention can contribute several retries.
	// 0 for backends without a read-retry path (MemoryStore, WALStore).
	ReadRetryCount int64 `json:"readRetryCount,omitempty"`

	// ReadTimeoutCount is the number of hybrid SQLite reads whose retry
	// window (hybridSQLiteReadRetryTimeout) was fully exhausted without
	// success since process start. Each of these is tagged with
	// ErrStorePressure (see HybridStore.wrapStorePressure) so callers up
	// the stack receive an AWS-shaped throttling error instead of a generic
	// InternalError — see protocol/errors.go. 0 for backends without a
	// read-retry path.
	ReadTimeoutCount int64 `json:"readTimeoutCount,omitempty"`

	// DataDirProbe reports the outcome of the one-time startup fsync
	// micro-probe (see HybridStore's runDataDirProbe) that flags a slow
	// data directory (e.g. a Docker Desktop bind mount) before it manifests
	// as flush/read latency. nil for backends that don't run the probe.
	DataDirProbe *DataDirProbeResult `json:"dataDirProbe,omitempty"`

	// JournalMode is the LIVE `PRAGMA journal_mode` readback from this
	// backend's SQLite connection, queried once during store initialisation
	// (after the connection is open and migrated, never per-request) — see
	// hybrid.go's seedFromSQLite and sqlite.go's runMigrate. Empty for
	// backends with no real SQLite connection to ask (MemoryStore, WALStore)
	// or when the backend degraded before the readback could run.
	//
	// This field exists because of a real historical failure, not a
	// hypothetical one: every persistent connection's DSN silently disabled
	// WAL mode for this project's entire history due to a driver-spelling
	// bug (see hybrid_journalmode_internal_test.go), while every doc comment
	// in this package confidently claimed WAL was active the whole time.
	// Surfacing the ACTUAL, LIVE pragma value here — rather than trusting the
	// DSN parameter we asked for — means that class of silent misconfiguration
	// can never hide again; see internal/router/advisories.go's
	// journal-mode-not-wal rule, which alerts the moment this diverges from
	// "wal" on a persistent/hybrid backend.
	JournalMode string `json:"journalMode,omitempty"`

	// Degraded is true when the persistent backend permanently fell back to
	// memory-only for this process's lifetime (see
	// HybridStore.degradeToMemoryOnly) — every write since is memory-only and
	// will not survive a restart. Always false for backends that cannot
	// degrade this way: SQLiteStore fails outright rather than falling back,
	// and MemoryStore/WALStore never persist at all.
	Degraded bool `json:"degraded,omitempty"`

	// Counters holds cumulative storage-layer read/write activity since
	// process start (health/metrics "storage activity" — the answer to "how
	// much is this backend actually doing"). Every implementation
	// (MemoryStore, SQLiteStore, WALStore, HybridStore) populates at least
	// Reads/Writes; see StoreCounters's doc comment for the hybrid-specific
	// tier split.
	Counters StoreCounters `json:"counters"`
}

type DebugMetricsOptions struct {
	// IncludeNamespaceRowCounts additionally populates
	// DebugMetrics.NamespaceRowCounts. For TierCached namespaces this issues
	// one SQL COUNT(*) per namespace currently known to the store — cheap
	// enough for an on-demand debug call, but not something to compute
	// unconditionally on every /_debug/metrics hit, so callers opt in.
	IncludeNamespaceRowCounts bool
}

type DebugMetricsReporter interface {
	DebugMetrics(ctx context.Context, opts DebugMetricsOptions) DebugMetrics
}

type Flushable interface {
	Flush(ctx context.Context) error
}

type HybridOptions struct {
	// FlushInterval is how often the background loop flushes dirty writes to
	// SQLite on a timer, independent of the size-triggered early flush.
	FlushInterval time.Duration

	// SyncMode controls how the pending log file is fsync'd: WALSyncAlways
	// syncs inline on every append, WALSyncInterval (default) syncs on a
	// timer, WALSyncNever relies on the OS page cache plus the sync always
	// performed on Close.
	SyncMode WALSyncMode

	// SyncInterval is used only when SyncMode is WALSyncInterval. Defaults to
	// 100ms.
	SyncInterval time.Duration

	// DirtyEntryThreshold triggers an out-of-band flush signal once this many
	// unflushed pending-log operations have accumulated, ahead of the next
	// FlushInterval tick. Defaults to 10,000. A value <= 0 disables this
	// trigger (byte threshold still applies unless it is also disabled).
	DirtyEntryThreshold int

	// DirtyByteThreshold triggers an out-of-band flush once the approximate
	// byte size of unflushed writes exceeds this many bytes. Defaults to
	// 8 MiB. A value <= 0 disables this trigger.
	DirtyByteThreshold int64

	// MaintenanceInterval controls how often the background loop runs
	// routine SQLite housekeeping (3.5 in docs/plans/storage-plan.md): a passive
	// WAL checkpoint plus a conditional incremental vacuum. Never runs on
	// the request path. Defaults to 5 minutes. A value <= 0 falls back to
	// the default rather than disabling the loop — unlike the dirty
	// thresholds above, there's no useful "off" state for routine
	// maintenance, so this intentionally doesn't support disabling it via a
	// non-positive value.
	MaintenanceInterval time.Duration

	// DataDirSlowFsyncThreshold overrides the duration above which the
	// one-time startup fsync micro-probe (runDataDirProbe) considers the
	// data directory "slow" and logs a warning (storage-pressure-handling
	// item 3). Defaults to dataDirSlowFsyncThreshold. A value <= 0 falls
	// back to the default.
	DataDirSlowFsyncThreshold time.Duration
	// contains filtered or unexported fields
}

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

type KV struct {
	Key   string
	Value string
}

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

type Migration struct {
	// Version is this migration's position in PRAGMA user_version terms.
	// Must be unique across every call to RegisterMigration in the binary.
	Version int

	// Name is a short, human-readable label used in log lines and error
	// messages — it is not used to order or identify the migration, Version
	// is.
	Name string

	// Up applies the migration's schema/data change. It runs inside a
	// transaction the runner opens and commits together with the
	// PRAGMA user_version bump for this migration — if Up returns an error,
	// the whole transaction (including the version bump) rolls back, so a
	// failed migration never leaves user_version pointing past a change that
	// didn't actually apply.
	Up func(ctx context.Context, tx *sql.Tx) error

	// AfterCommit, if set, runs immediately after Up's transaction commits
	// (and user_version has advanced to Version) — for statements SQLite
	// refuses to run inside a transaction. VACUUM is the motivating case: it
	// opens its own internal transaction and errors with "cannot VACUUM from
	// within a transaction" if issued through tx.ExecContext. AfterCommit
	// runs against the raw *sql.DB instead, right after the wrapping
	// transaction commits, still gated by the same pending-migration check
	// as every other migration.
	//
	// An AfterCommit failure is still reported as a failed migration (the
	// runner returns an error naming this migration and stops before running
	// any later ones), but because Up's transaction already committed and
	// user_version already advanced, a restart will not retry Up or
	// AfterCommit for this version — only Up's effects are guaranteed
	// idempotent/transactional; AfterCommit is best-effort and its own
	// statements should be safe to have partially applied (VACUUM is: it
	// either finishes or SQLite leaves the database in its pre-VACUUM
	// state).
	AfterCommit func(ctx context.Context, db *sql.DB) error
}

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

type NotReadyReporter interface {
	// NotReady reports, without blocking, whether the store is still
	// completing one-time startup work.
	NotReady() bool
}

type PersistentHealth struct {
	Mode          string    `json:"mode"`
	Healthy       bool      `json:"healthy"`
	PendingWrites int       `json:"pendingWrites"`
	LastError     string    `json:"lastError,omitempty"`
	LastErrorAt   time.Time `json:"lastErrorAt,omitempty"`
	LastSuccessAt time.Time `json:"lastSuccessAt,omitempty"`
}

type PersistentHealthReporter interface {
	PersistentHealth() PersistentHealth
}

type PrefixDeleter interface {
	DeletePrefix(ctx context.Context, namespace, prefix string) error
}

type ReadyAwaiter interface {
	// WaitReady blocks until the store's background initialisation is
	// complete or ctx is cancelled. Returns nil when the store is ready.
	WaitReady(ctx context.Context) error
}

type SQLiteDBProvider interface {
	DB() *sql.DB
}

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

type Store interface {
	// Get retrieves a value by namespace+key.
	// Returns ("", false, nil) if the key does not exist.
	Get(ctx context.Context, namespace, key string) (value string, found bool, err error)

	// Set stores a value. Overwrites any existing value for the same key.
	Set(ctx context.Context, namespace, key, value string) error

	// Delete removes a key. Returns nil (not an error) if the key does not exist.
	Delete(ctx context.Context, namespace, key string) error

	// List returns all keys in namespace whose names start with prefix.
	// Returns an empty slice (not nil) when no keys match.
	List(ctx context.Context, namespace, prefix string) (keys []string, err error)

	// ListNamespaces returns all namespaces that currently contain at least one
	// key. Returns an empty slice (not nil) when the store is empty.
	ListNamespaces(ctx context.Context) (namespaces []string, err error)

	// Scan returns all key-value pairs in namespace whose keys start with prefix,
	// in a single atomic read. Prefer Scan over List+Get when you need both keys
	// and values — it avoids N individual Get calls and holds the lock only once.
	// Returns an empty slice (not nil) when no keys match.
	Scan(ctx context.Context, namespace, prefix string) ([]KV, error)

	// ScanPage returns up to limit key-value pairs in namespace whose keys
	// start with prefix, in key order, starting strictly after startAfter —
	// a paginated variant of Scan for namespaces too large to return in one
	// response (e.g. sqs:messages, logs:events). Pass startAfter == "" for
	// the first page.
	//
	// nextKey is the startAfter value to pass for the next page, or "" when
	// this page reached the end of the prefix range (no more results).
	// limit <= 0 means "no limit" — behaves exactly like Scan(ctx, namespace,
	// prefix) with nextKey always "". This keeps ScanPage a strict superset
	// of Scan (a caller can always pass limit 0 and get Scan's behavior)
	// rather than making an unbounded request an error, matching this
	// package's general preference for permissive zero-value defaults (see
	// e.g. HybridOptions' zero-valued fields falling back to documented
	// defaults) over forcing every caller to think about a limit.
	//
	// Returns an empty slice (not nil) when no keys match.
	ScanPage(ctx context.Context, namespace, prefix, startAfter string, limit int) (page []KV, nextKey string, err error)

	// Close releases any resources held by the store (file handles, DB connections).
	// Called once on graceful shutdown.
	Close() error
}

type StoreCounters struct {
	Reads  int64 `json:"reads"`
	Writes int64 `json:"writes"`

	ReadsMemory       int64 `json:"readsMemory,omitempty"`
	ReadsSQLite       int64 `json:"readsSQLite,omitempty"`
	WritesFlushedRows int64 `json:"writesFlushedRows,omitempty"`
}

type Tier int

type WALOptions struct {
	SyncMode WALSyncMode

	// SyncInterval is used only when SyncMode is WALSyncInterval.
	SyncInterval time.Duration

	// MaxLogBytes triggers compaction when the append log reaches this size.
	MaxLogBytes int64
}

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

type WALSyncMode string