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 SlotExpectation struct {
	Identity        identity.Quadruple
	Kind            string
	ExpectedEventID EventID
}

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

type StateScanCursor struct {
	UserID    string
	SessionID string
	RunID     string
	Kind      string
}

type StateScanPage struct {
	Records      []StateRecord
	Continuation string
}

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

	// SaveIf atomically verifies every expectation and persists next. The
	// expectation set is non-empty, has no duplicate slots, and must include
	// next's slot. A mismatch returns ErrConditionFailed and leaves every slot
	// unchanged. Save's EventID idempotency contract applies to next only after
	// all predicates match; it never bypasses a failed predicate.
	SaveIf(ctx context.Context, expectations []SlotExpectation, next StateRecord) error

	// DeleteIf atomically removes exactly one present slot generation. A
	// different or absent generation is a normal concurrent-state outcome and
	// returns (false, nil); only an exact EventID match may be deleted. This is
	// the conditional-delete counterpart to SaveIf for compensations that must
	// restore a genuinely absent pre-operation state without writing a marker.
	DeleteIf(ctx context.Context, expectation SlotExpectation) (bool, error)

	// FenceIf acquires the driver's cross-instance lock for one exact slot
	// generation, verifies the EventID, runs fn while that generation cannot be
	// replaced, then releases the lock without mutating the slot. fn MUST NOT
	// call this StateStore; it exists for a short process-local publication
	// linearization that must serialize with SaveIf on the same durable slot.
	// Context cancellation is an admission condition before fn starts; callers
	// must not use cancellation to infer that an already-started callback did
	// not publish.
	FenceIf(ctx context.Context, expectation SlotExpectation, fn func() error) 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

	// DeleteScope removes EVERY record whose (tenant, user, session)
	// matches id, regardless of run_id or kind. It is the kind-agnostic
	// cascade primitive a session-erasure (`sessions.delete`) runs to
	// remove all data scoped to a session in one call — the session
	// lifecycle record, run-scoped trajectories, planner checkpoints, and
	// the durable event stream all live under the triple and all go.
	//
	// Unlike ListKind, DeleteScope is identity-scoped — NOT a
	// maintenance-elevated cross-identity scan. It deletes only the
	// caller's OWN session, so it needs no ListScope claim: the triple IS
	// the scope. It fails closed with ErrIdentityRequired on an
	// incomplete triple (empty tenant / user / session); empty RunID is
	// irrelevant — the match ignores run_id entirely.
	//
	// It is idempotent: an absent scope returns (0, nil), never an error,
	// so a cascade interrupted mid-flight is safe to re-invoke to
	// convergence. Returns the number of records deleted.
	DeleteScope(ctx context.Context, id identity.Identity) (int, error)

	// ListKind enumerates every record whose Kind starts with
	// kindPrefix — the store's unbounded cross-tenant maintenance scan
	// (RFC §6.11). 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 or case-folding
	// interpretation). 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)

	// ListKindForIdentity enumerates records for one complete identity whose
	// Kind starts with kindPrefix. Unlike ListKind, this is not an elevated
	// maintenance scan: the supplied triple is the complete read boundary.
	// Prefix matching is literal and kindPrefix must be non-empty.
	ListKindForIdentity(ctx context.Context, id identity.Quadruple, kindPrefix string) ([]StateRecord, error)

	// ListKindForIdentityBounded is the identity-scoped counterpart for a
	// caller that must cap materialization before it processes records. It
	// returns at most limit rows, with the identity and literal-prefix
	// semantics of ListKindForIdentity. Callers that must reject overflow ask
	// for their accepted bound plus one. It is deliberately not a cursor: it
	// is a bounded admission check, not a maintenance traversal.
	ListKindForIdentityBounded(ctx context.Context, id identity.Quadruple, kindPrefix string, limit int) ([]StateRecord, error)

	// ScanKindForTenant returns one deterministic, tenant-bounded maintenance
	// page whose Kind begins with literalKindPrefix. It is deliberately a
	// keyset scan, not a database snapshot: callers that need convergence must
	// quiesce writers and complete a final verification pass. continuation is
	// an opaque cursor returned by the preceding page and is bound to this
	// exact maintenance scope, tenant, and literal prefix.
	ScanKindForTenant(ctx context.Context, scope ListScope, tenantID, literalKindPrefix string, limit int, continuation string) (StateScanPage, error)

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