state

type EventID string

type Factory func(config.StateConfig) (StateStore, error)

type ListScope struct {
	// MaintenanceScoped asserts the caller is a runtime maintenance
	// loop acting on each returned record under that record's own
	// identity. False (the zero value) is rejected with
	// ErrMaintenanceScopeRequired.
	MaintenanceScoped bool
}

type StateRecord struct {
	ID        EventID
	Identity  identity.Quadruple
	Kind      string
	Version   int
	Bytes     []byte
	UpdatedAt time.Time
}

type StateStore interface {
	// Save persists a record. Idempotent on `EventID`:
	//
	//   - Same EventID + byte-equal Bytes: no-op (no error, no
	//     duplicate write).
	//   - Same EventID + different Bytes: ErrIdempotencyConflict.
	//
	// If a record already exists at (Identity, Kind) but with a
	// different EventID, Save overwrites it (the new EventID becomes
	// the active one for that slot; the previous EventID is no
	// longer LoadByEventID-resolvable).
	Save(ctx context.Context, r StateRecord) error

	// Load returns the record at (id, kind). Returns ErrNotFound
	// (wrapped) when no record exists for that key.
	Load(ctx context.Context, id identity.Quadruple, kind string) (StateRecord, error)

	// LoadByEventID returns the record whose ID matches eventID.
	// Useful for replaying a specific event by its idempotency key.
	// Returns ErrNotFound (wrapped) when not present.
	LoadByEventID(ctx context.Context, eventID EventID) (StateRecord, error)

	// Delete removes the record at (id, kind). Returns nil when the
	// record is absent (idempotent), wrapped error on store failure.
	Delete(ctx context.Context, id identity.Quadruple, kind string) error

	// ListKind enumerates every record whose Kind starts with
	// kindPrefix — the store's ONE maintenance-scan surface
	// (RFC §6.11, D-207). Unlike every other method, the scan crosses
	// identity boundaries: it exists so runtime maintenance loops (the
	// pause sweeper's crash-orphan rescan is the first consumer) can
	// find records whose identities the process has never seen. That
	// elevation is explicit and fail-closed:
	//
	//   - scope.MaintenanceScoped MUST be true, or the call fails with
	//     ErrMaintenanceScopeRequired (CLAUDE.md §6 rule 5 / §13 "no
	//     cross-session queries without an explicit elevated scope
	//     claim"). There is no identity-scoped mode — identity-scoped
	//     reads stay on Load / LoadByEventID.
	//   - kindPrefix MUST be non-empty (ErrInvalidRecord) — a
	//     whole-store dump is never a valid maintenance scan.
	//   - Callers MUST act on each returned record under that record's
	//     OWN identity (every record carries its Quadruple); ListKind
	//     grants visibility for the scan, never a widened mutation
	//     scope.
	//
	// kindPrefix matches literally (no wildcard interpretation — SQL
	// drivers escape LIKE metacharacters). Result order is
	// unspecified; an empty result is ([]StateRecord{} or nil, nil),
	// never an error.
	ListKind(ctx context.Context, scope ListScope, kindPrefix string) ([]StateRecord, error)

	// Close releases driver resources. Subsequent calls return
	// ErrStoreClosed (wrapped). Implementations MUST honour ctx
	// during long teardowns.
	Close(ctx context.Context) error
}