Documentation
¶
Overview ¶
Durable continuation claims (#977).
agent_run_lock stops two daemons from *deciding* to continue a session at the same instant. It does not stop them from deciding one after the other, because the lock is released before the continuation turn runs — the turn executes asynchronously in the session's wake loop and that path has no turn-end hook to hold a lease across. So the second daemon acquires the lock cleanly, reads a tail that still looks interrupted (the first daemon's turn has committed nothing yet), and injects a second continuation into the same session.
The window the lock leaves open is therefore not "two turns overlap". It is "two daemons read the same interrupted tail and both act on it", and that is what a claim closes: a durable row saying *this specific interruption has already been continued by somebody*. It needs no new lease semantics and no hook that does not exist, because it is not a lock — it is a fact, and it stays true after the writer has gone away.
Holding agent_run_lock across the turn instead would read like session-level mutual exclusion without being it. Ordinary turns take no lock at all — not attach-driven turns, not wake-loop turns, not the local REPL — so a lock held across the continuation excludes another continuation and nothing else. A reader would infer an invariant the code does not have, which is worse than the narrow scope being visible.
Package eventlog is the durable, append-only audit log that backs agent.Agent's session.Service. Each event the ADK runner appends to a session is persisted to the underlying database (SQLite, MySQL, or Postgres via GORM) and assigned a monotonic seq number. Subscribers can replay history with Since(fromSeq) or live-tail with Watch(fromSeq).
The package layers on top of ADK's session/database service: ADK owns the events / sessions / state tables, and we add a thin agent_eventlog overlay table whose rows reference ADK's events by id and add the seq column. Two GORM connections (ADK's and ours) share the same database file/DSN — atomic-across-tables writes are not provided in v1; the AppendEvent path writes ADK first, then the overlay, and surfaces overlay-write errors so callers can retry (event_id is unique-indexed for safe idempotency).
See docs/eventlog-plan.md and docs/eventlog-decisions.md for the design rationale and milestone breakdown.
Index ¶
- Constants
- Variables
- func IsSessionNotFound(err error) bool
- func ValidReasons() []string
- type AckRecord
- type BootRecord
- type BranchLister
- type DecisionStore
- type Entry
- type ExportMeta
- type ExportOptions
- type GuardrailState
- type GuardrailStore
- func (s *GuardrailStore) AddBudgetExtension(ctx context.Context, appName, userID, sessionID string, addUSD float64) error
- func (s *GuardrailStore) ClearCost(ctx context.Context, appName, userID, sessionID string) error
- func (s *GuardrailStore) ClearWatchdog(ctx context.Context, appName, userID, sessionID string) error
- func (s *GuardrailStore) Load(ctx context.Context, appName, userID, sessionID string) (GuardrailState, error)
- func (s *GuardrailStore) LoadWithLegacyCheck(ctx context.Context, appName, userID, sessionID string) (GuardrailState, bool, error)
- func (s *GuardrailStore) SaveState(ctx context.Context, st GuardrailState) error
- func (s *GuardrailStore) TripCost(ctx context.Context, appName, userID, sessionID, reason string) error
- func (s *GuardrailStore) TripWatchdog(ctx context.Context, appName, userID, sessionID, reason string) error
- type Handle
- func (h *Handle) Ack(ctx context.Context, appName, workload, subject string) (*AckRecord, error)
- func (h *Handle) AckEffects(ctx context.Context, appName, userID, sessionID, by, reason string) (time.Time, error)
- func (h *Handle) Acks(ctx context.Context, appName, workload string) ([]AckRecord, error)
- func (h *Handle) AcquireLock(ctx context.Context, app, user, session string) (*SessionLock, error)
- func (h *Handle) ClaimContinuation(ctx context.Context, app, user, session string, interruptedAt time.Time, ...) (bool, error)
- func (h *Handle) Close() error
- func (h *Handle) ConsumeScheduled(ctx context.Context, appName, token, by string) (*PauseRecord, error)
- func (h *Handle) ConsumeToken(ctx context.Context, appName, token, by string) (*PauseRecord, error)
- func (h *Handle) EffectsAckedAt(ctx context.Context, appName, userID, sessionID string) (time.Time, bool)
- func (h *Handle) ExportDecisions(ctx context.Context, w io.Writer, opts ExportOptions) (int, error)
- func (h *Handle) ExtendToken(ctx context.Context, appName, token string, ttl time.Duration) (*PauseRecord, error)
- func (h *Handle) FindToken(ctx context.Context, appName, token string) (*PauseRecord, error)
- func (h *Handle) GatePause(ctx context.Context, appName, userID, sessionID string) *PauseRecord
- func (h *Handle) HasDecision(ctx context.Context, sessionID, functionCallID string) (bool, error)
- func (h *Handle) ListParks(ctx context.Context, appName, userID, sessionID string) ([]SessionParkedCalls, error)
- func (h *Handle) PauseGate(ctx context.Context, appName, userID, sessionID string, spec PauseSpec) (PauseHandle, bool, error)
- func (h *Handle) PauseInterrupt(ctx context.Context, appName, userID, sessionID, interruptID string, ...) (PauseHandle, error)
- func (h *Handle) PauseRecords(ctx context.Context, appName, userID, sessionID string) (map[string]*PauseRecord, error)
- func (h *Handle) Ping(ctx context.Context) error
- func (h *Handle) RecentBoots(ctx context.Context, since time.Time) ([]BootRecord, error)
- func (h *Handle) RecordAck(ctx context.Context, appName string, rec AckRecord) error
- func (h *Handle) RecordBoot(ctx context.Context, at time.Time, attempted []string) (uint, error)
- func (h *Handle) RecordDecision(ctx context.Context, d approval.Decision) error
- func (h *Handle) ReleaseContinuationClaim(ctx context.Context, app, user, session string, interruptedAt time.Time, ...) error
- func (h *Handle) SaveSchedule(ctx context.Context, appName string, rec ScheduleRecord) error
- func (h *Handle) ScanPauses(ctx context.Context, appName string) ([]*PauseRecord, error)
- func (h *Handle) Schedule(ctx context.Context, appName, workload string) (*ScheduleRecord, error)
- func (h *Handle) SessionDecisions(ctx context.Context, appName, userID, sessionID string) ([]approval.Decision, error)
- func (h *Handle) UpdateBootAttempted(ctx context.Context, id uint, attempted []string) error
- type MetadataExtractor
- type Option
- type ParkedCall
- type PauseHandle
- type PauseRecord
- type PauseSpec
- type QueryOption
- func ForSession(appName, userID, sessionID string) QueryOption
- func WithAnyBranchPrefix(prefixes ...string) QueryOption
- func WithAuthor(name string) QueryOption
- func WithAuthorSuffix(suffix string) QueryOption
- func WithBranchPrefix(prefix string) QueryOption
- func WithLimit(n int) QueryOption
- func WithSessionTree(appName, userID, parentSessionID string) QueryOption
- type Reason
- type ScheduleRecord
- type SessionLock
- type SessionParkedCalls
- type SpendRecord
- type SpendState
- type SpendStore
- func (s *SpendStore) Append(ctx context.Context, app, user, sid string, rec SpendRecord) error
- func (s *SpendStore) AppendBatch(ctx context.Context, app, user, sid string, recs []SpendRecord) error
- func (s *SpendStore) Fold(ctx context.Context, app, user, sid string) (SpendState, error)
- func (s *SpendStore) FoldTree(ctx context.Context, app, user, parentSID string) (SpendState, error)
- func (s *SpendStore) History(ctx context.Context, app, user, sid string) ([]SpendRecord, error)
- func (s *SpendStore) HistoryTree(ctx context.Context, app, user, parentSID string) ([]SpendRecord, error)
- type SpendTotals
- type Stream
Constants ¶
const ( // EffectsAckTimeKey is the session-state key under which AckEffects records // the operator's acknowledgement watermark for ambiguous prior effects. EffectsAckTimeKey = "mast_effects_ack_time" // EffectsAckReasonKey is the session-state key under which AckEffects records // the operator's acknowledgement reason. EffectsAckReasonKey = "mast_effects_ack_reason" // EffectsAckByKey is the session-state key under which AckEffects records // the operator identity. EffectsAckByKey = "mast_effects_ack_by" // RedactionApproverDigest is the default export mode: human approvers are // replaced with approval.RedactApprover's SHA-256 prefix, and machine // identities pass through in the clear. RedactionApproverDigest = "approver-sha256" // RedactionNone marks an export written with IncludeApprover: true. RedactionNone = "none" // AwaitingApproval indicates a session is parked on a write-gate confirmation. AwaitingApproval = "approval" // AwaitingInput indicates a session is parked on an operator input question. AwaitingInput = "input" )
const ( // MetadataKeyCaller is the effective Caller.Identity that // originated the turn this event belongs to. Empty when no auth // context was available (legacy / single-user / out-of-band code // paths). MetadataKeyCaller = "caller" // MetadataKeyProxyBy is set when the effective Caller was // asserted via the proxy path (X-Asserted-Caller header): records // the proxying identity (e.g., "sa:slack-bot"). Empty for direct // authentication. MetadataKeyProxyBy = "proxy_by" )
MetadataKey* are the well-known keys agent.Agent uses when wiring the per-request caller context into the eventlog metadata sidecar. They're exported so audit consumers can read what's there without guessing at conventions.
const ( // DefaultTokenTTL is the default resume-token lifetime. DefaultTokenTTL = 7 * 24 * time.Hour // PlaneGate and PlaneInterrupt identify the two pause planes recorded in PauseRecord.Plane. PlaneGate = "gate" PlaneInterrupt = "interrupt" )
const FinishReasonMetadataKey = "finish_reason"
FinishReasonMetadataKey is the CustomMetadata key under which AppendEvent records a model turn's genai FinishReason before persist. ADK's storage row has no FinishReason column (createEventFromStorageEvent drops it), but it DOES round-trip CustomMetadata — so stamping the reason here is what lets a reloaded event distinguish a MAX_TOKENS truncation (resume-able) from a normal STOP completion. Read by pkg/agent's auto-continue classifier (#582); mirrors the CompactionMetadataKey piggy-back the classifier already consults.
const ModelVersionMetadataKey = "model_version"
ModelVersionMetadataKey is the CustomMetadata key under which AppendEvent records a model turn's LLMResponse.ModelVersion before persist (#1359). ADK's storageEvent has no ModelVersion column (createEventFromStorageEvent drops it), so without this stamp a reloaded event loses its model identity and RebuildTrackerFromEvents falls back to the parent session's default model.
Variables ¶
var ( ErrTokenNotFound = fmt.Errorf("eventlog: resume token not found: %w", gorm.ErrRecordNotFound) ErrTokenExpired = errors.New("eventlog: resume token expired") ErrAlreadyResumed = errors.New("eventlog: pause already resumed") )
Pause/token sentinel errors.
var ErrClosed = errors.New("eventlog: stream is closed")
ErrClosed is returned by Stream methods invoked after Close.
var ErrLeaseLost = errors.New("eventlog: session lease lost")
ErrLeaseLost is returned by consumers of SessionLock.Lost (such as autonomous.Resume) when a held session lease is stolen by another process or its heartbeat fails past the staleness window (#1361).
var ErrSessionLocked = errors.New("eventlog: session is locked by another process")
ErrSessionLocked is returned by AcquireLock when another live process already holds the lease. The error message includes the holder identifier so operators can diagnose contention.
var ErrUnscopedQuery = errors.New("eventlog: query must be scoped to a session or session tree")
ErrUnscopedQuery is what a Stream returns (wrapped) from Since or Watch when the query names no session ID (neither ForSession nor WithSessionTree with a non-empty one) and the implementation cannot serve a query across its whole store. It is yielded before any entry and before Watch blocks. The SQL implementation never returns it. It is exported ahead of the first implementation that does, so a caller that reads across sessions (an audit dashboard, say) can handle it with errors.Is from the start.
Functions ¶
func IsSessionNotFound ¶
IsSessionNotFound reports whether err means "that session is not in the log", as opposed to a real failure to read it.
ADK's database session service wraps GORM's ErrRecordNotFound with %w behind the text "database error while fetching session", which reads like a database fault and is not one — a session that has never been written is the ordinary state of every session before its first event. Callers that treat any non-nil error as a problem log a scary line on a healthy cold boot; this is the check that tells the two apart without matching on message text.
It lives here rather than in the callers because the GORM coupling is this package's to own.
func ValidReasons ¶ added in v3.1.0
func ValidReasons() []string
ValidReasons lists the accepted Reason values.
Types ¶
type AckRecord ¶ added in v3.1.0
type AckRecord struct {
Workload string `json:"workload"`
Subject string `json:"subject"`
By string `json:"by"`
ProxyBy string `json:"proxy_by,omitempty"`
Reason string `json:"reason,omitempty"`
At time.Time `json:"at"`
Forwarded bool `json:"forwarded"`
}
AckRecord is the durable operator acknowledgement of an active monitoring subject (`Transition.SubjectKey`), stored in ADK session state on the reserved `"mast-acks:mast-ops"` session.
An ack is an operational signal suppressing monitor.notify.remind_after reminders for an open subject; it is NOT an approval of a gated tool call and never writes a DecisionRecord.
type BootRecord ¶
BootRecord is the public view of one boot-scan run.
type BranchLister ¶
type BranchLister interface {
Branches(ctx context.Context, opts ...QueryOption) ([]string, error)
}
BranchLister is an OPTIONAL Stream extension: report the distinct branch labels that exist under a query's filters, without hydrating a single event.
It answers "what ran here?", which the Since/Watch pair can only answer by reading every row and looking at the branch column. The caller that needs it is the attach layer's subagent-events endpoint: a subagent declared as "cluster" writes its turns under the branch the runner minted for the instance ("bg.cluster-1"), so resolving a name to its branches means asking the log which branches are there (go-steer/core-agent#694).
Not part of Stream itself — adding a method to a published interface breaks every implementation outside this repo. Type-assert for it and degrade when it's absent:
if bl, ok := stream.(eventlog.BranchLister); ok { ... }
Honors the same QueryOptions as Since, including WithLimit (a cap on the number of DISTINCT labels returned, not on rows scanned). Labels come back sorted, and the empty branch — the parent session's own turns — is omitted.
type DecisionStore ¶ added in v3.1.0
type DecisionStore struct {
// contains filtered or unexported fields
}
DecisionStore persists write-gate Decision records in agent_approval_decisions. A nil *DecisionStore is a safe no-op.
func NewDecisionStore ¶ added in v3.1.0
NewDecisionStore constructs a DecisionStore over an existing GORM connection and AutoMigrates agent_approval_decisions.
func (*DecisionStore) HasDecision ¶ added in v3.1.0
func (s *DecisionStore) HasDecision(ctx context.Context, sessionID, functionCallID string) (bool, error)
HasDecision reports whether a Decision record for functionCallID in sessionID exists in agent_approval_decisions. It matches approval.DecisionLookup so write-gate plugins can detect pre-crash dispatches across process restarts (#1400, mast #561).
func (*DecisionStore) ListDecisions ¶ added in v3.1.0
func (s *DecisionStore) ListDecisions(ctx context.Context, sessionID string) ([]approval.Decision, error)
ListDecisions returns the durable decisions recorded in SQL for sessionID (or across all sessions when sessionID is empty), oldest first.
func (*DecisionStore) RecordDecision ¶ added in v3.1.0
RecordDecision persists a write-gate Decision record before tool execution.
type Entry ¶
type Entry struct {
// Seq orders entries within one root session tree; see the
// Stream doc for what it does and does not promise.
Seq int64
Event *session.Event
Metadata map[string]string
}
Entry is one row from the event log: the assigned seq plus the underlying ADK session.Event (loaded via the paired session.Service).
Metadata is an optional sidecar map populated by a MetadataExtractor (see WithMetadataExtractor). The eventlog package itself is agnostic to the keys — agent.Agent wires an extractor that pulls auth.Caller.Identity (key "caller") and proxy attribution (key "proxy_by") from the request context. Rows persisted before the sidecar column shipped read back as a nil Metadata map.
type ExportMeta ¶ added in v3.1.0
type ExportMeta struct {
Schema string `json:"schema"`
Tool string `json:"tool"`
ExportedAt time.Time `json:"exported_at"`
Source string `json:"source,omitempty"`
Session string `json:"session,omitempty"`
Workload string `json:"workload,omitempty"`
Since *time.Time `json:"since,omitempty"`
Until *time.Time `json:"until,omitempty"`
Redaction string `json:"redaction"`
Warning string `json:"warning"`
Records int `json:"records"`
}
ExportMeta is the provenance object on the first line of an export.
type ExportOptions ¶ added in v3.1.0
type ExportOptions struct {
AppName string
UserID string
SessionID string
Workload string
Since time.Time
Until time.Time
IncludeApprover bool
Source string
Tool string
}
ExportOptions scopes a decision export.
type GuardrailState ¶ added in v3.1.0
type GuardrailState struct {
AppName string `gorm:"primaryKey;not null"`
UserID string `gorm:"primaryKey;not null"`
SessionID string `gorm:"primaryKey;not null"`
WatchdogTripped bool `gorm:"not null;default:false"`
WatchdogReason string `gorm:"type:text"`
CostTripped bool `gorm:"not null;default:false"`
CostReason string `gorm:"type:text"`
BudgetExtensionUSD float64 `gorm:"not null;default:0"`
// LastEventID records the most recent reset event ID that added to
// BudgetExtensionUSD so fallback retries cannot double-apply an
// additive budget extension (trip/clear assignments are naturally
// idempotent).
LastEventID string `gorm:"type:text"`
UpdatedAt time.Time `gorm:"autoUpdateTime"`
}
GuardrailState is the durable row in agent_guardrail_state tracking whether a session's watchdog or cost ceiling has tripped and any cumulative operator-granted budget extensions (#1360).
func (GuardrailState) TableName ¶ added in v3.1.0
func (GuardrailState) TableName() string
TableName pins the GORM table name across database drivers.
type GuardrailStore ¶ added in v3.1.0
type GuardrailStore struct {
// contains filtered or unexported fields
}
GuardrailStore persists guardrail trip, reset, and budget-extension state synchronously to the database so a tripped session remains tripped across restarts and RestoreGuardrails reads current state by primary key without hydrating the session history (#1360, #1438). Sessions created through eventlog.Handle.Service seed a zero state row on creation; pre-upgrade sessions without a state row perform a one-time indexed check on agent_eventlog and backfill or seed the row so subsequent reads are O(1) primary-key lookups.
func NewGuardrailStore ¶ added in v3.1.0
NewGuardrailStore auto-migrates agent_guardrail_state on db and returns a ready GuardrailStore.
func (*GuardrailStore) AddBudgetExtension ¶ added in v3.1.0
func (s *GuardrailStore) AddBudgetExtension(ctx context.Context, appName, userID, sessionID string, addUSD float64) error
AddBudgetExtension adds a positive USD budget extension to the session's durable guardrail state. Non-positive addUSD is a no-op.
func (*GuardrailStore) ClearCost ¶ added in v3.1.0
func (s *GuardrailStore) ClearCost(ctx context.Context, appName, userID, sessionID string) error
ClearCost clears a durable cost-ceiling trip for the session.
func (*GuardrailStore) ClearWatchdog ¶ added in v3.1.0
func (s *GuardrailStore) ClearWatchdog(ctx context.Context, appName, userID, sessionID string) error
ClearWatchdog clears a durable watchdog trip for the session.
func (*GuardrailStore) Load ¶ added in v3.1.0
func (s *GuardrailStore) Load(ctx context.Context, appName, userID, sessionID string) (GuardrailState, error)
Load returns the current GuardrailState for the session in O(1) by primary key, or a zero GuardrailState when no row has been recorded.
func (*GuardrailStore) LoadWithLegacyCheck ¶ added in v3.1.0
func (s *GuardrailStore) LoadWithLegacyCheck(ctx context.Context, appName, userID, sessionID string) (GuardrailState, bool, error)
LoadWithLegacyCheck returns the session's GuardrailState from agent_guardrail_state in O(1) by primary key when a state or sentinel row is present. When no row exists yet (e.g. a pre-upgrade session), it probes agent_eventlog via idx_agent_eventlog_session_author in O(log N) to report whether pre-upgrade guardrail events need a one-time fold and backfill; when none exist and the session is present in storage, it seeds a zero sentinel row so future calls hit the primary key directly (#1360, #1438).
func (*GuardrailStore) SaveState ¶ added in v3.1.0
func (s *GuardrailStore) SaveState(ctx context.Context, st GuardrailState) error
SaveState writes a full GuardrailState snapshot for the session. Used by RestoreGuardrails when backfilling a pre-upgrade session whose guardrail events predated agent_guardrail_state (#1360).
func (*GuardrailStore) TripCost ¶ added in v3.1.0
func (s *GuardrailStore) TripCost(ctx context.Context, appName, userID, sessionID, reason string) error
TripCost records a durable cost-ceiling trip for the session.
func (*GuardrailStore) TripWatchdog ¶ added in v3.1.0
func (s *GuardrailStore) TripWatchdog(ctx context.Context, appName, userID, sessionID, reason string) error
TripWatchdog records a durable watchdog trip for the session.
type Handle ¶
type Handle struct {
// Stream is the seq + replay + watch primitive.
Stream Stream
// Service is the session.Service backed by the same database.
// Pass to agent.WithSessionService (or use the
// agent.WithEventLog convenience that does both at once).
Service session.Service
// Guardrail is the durable O(1) guardrail state store backed by
// agent_guardrail_state on the same database (#1360). Nil on a
// non-SQL Handle.
Guardrail *GuardrailStore
// Spend is the durable append-only spend ledger backed by
// agent_budget_spend on the same database (#1359). Nil on a
// non-SQL Handle.
Spend *SpendStore
// Decisions is the durable write-gate decision store backed by
// agent_approval_decisions on the same database (#1400). Nil on a
// non-SQL Handle.
Decisions *DecisionStore
// DB exposes the overlay-table connection so adjacent
// substrates (e.g., pkg/attach.SessionACLStore) can share the
// same database without re-opening it. Read-only access from
// outside pkg/eventlog — mutations happen via the typed
// stores. Nil before Open returns. Close closes the pool but
// leaves the field set.
//
// DB is only ever set by a SQL-backed Handle; a Handle built on a
// non-SQL store leaves it nil. Read a nil DB as "this Handle has
// no SQL connection to share", never as "closed" or "unhealthy":
// use Ping for that.
DB *gorm.DB
// contains filtered or unexported fields
}
Handle bundles the Stream with the session.Service that writes to the same database. agent.WithEventLog(handle) wires both into an agent.Agent in one call.
func Open ¶
Open constructs a Handle backed by the supplied GORM dialector. Pass any standard dialector (sqlite.Open, postgres.Open, mysql.Open).
Open does several things:
- Constructs ADK's database.SessionService against the dialector and runs its AutoMigrate so the events / sessions / state tables exist.
- Opens a second GORM connection for our overlay table and AutoMigrates agent_eventlog.
- For SQLite (detected via the dialector's Name()), enables WAL journal mode so concurrent readers can run alongside the writer. Disable with WithSkipWAL.
- Wraps the ADK service so AppendEvent writes to both layers.
func (*Handle) Ack ¶ added in v3.1.0
Ack looks up the durable AckRecord for (workload, subject). It returns (nil, nil) when no acknowledgement has been recorded.
func (*Handle) AckEffects ¶ added in v3.1.0
func (h *Handle) AckEffects(ctx context.Context, appName, userID, sessionID, by, reason string) (time.Time, error)
AckEffects appends an operator acknowledgement watermark for ambiguous prior effects on sessionID. Dangling mutating tool calls at or before the returned timestamp no longer trip the outbox's ambiguous-effect refusal mode.
func (*Handle) Acks ¶ added in v3.1.0
Acks returns all recorded acknowledgements for workload (or across all workloads when workload is empty), ordered by At ascending.
func (*Handle) AcquireLock ¶
AcquireLock takes an exclusive lease on (app, user, session) for the lifetime of the returned *SessionLock. Returns ErrSessionLocked if another process holds a fresh lease (heartbeat within staleAfter); steals the lease if the existing holder's heartbeat is older than staleAfter (indicating a crashed process).
The lease is heartbeated automatically until SessionLock.Release is called; Release is idempotent and safe to defer.
func (*Handle) ClaimContinuation ¶
func (h *Handle) ClaimContinuation(ctx context.Context, app, user, session string, interruptedAt time.Time, holder string) (bool, error)
ClaimContinuation records that the caller is about to inject a continuation for the interruption at interruptedAt, and reports whether the claim is the caller's to act on.
false means the interruption at that exact instant has already been claimed — by this daemon on an earlier pass, or by a peer sharing the database — and the caller must stand down rather than inject a second continuation for the same interruption. true means the row now names the caller.
A *later* interruption is a different fact and always claimable: the row carries one instant, not a flag, so a session interrupted again after a continuation has run gets continued again. That is the whole point of keying on the interruption rather than on the session. A claim older than continuationClaimTTL is also re-claimable; see that constant for why an eternal claim would be a deadlock.
Atomic in one statement rather than read-then-write. Every in-tree caller already holds the session run lock, so the compare-and-set is belt and braces — but a claim whose correctness depends on a lock taken somewhere else is exactly the kind of invariant that quietly stops being true, and one conditional upsert costs nothing to make honest.
func (*Handle) Close ¶
Close releases all resources held by the Handle (Stream + the underlying database connection). Safe to call multiple times.
func (*Handle) ConsumeScheduled ¶ added in v3.1.0
func (h *Handle) ConsumeScheduled(ctx context.Context, appName, token, by string) (*PauseRecord, error)
ConsumeScheduled consumes a token on behalf of the timed-pause scheduler without enforcing token TTL.
func (*Handle) ConsumeToken ¶ added in v3.1.0
ConsumeToken marks the token's pause record consumed, enforcing token TTL.
func (*Handle) EffectsAckedAt ¶ added in v3.1.0
func (h *Handle) EffectsAckedAt(ctx context.Context, appName, userID, sessionID string) (time.Time, bool)
EffectsAckedAt returns the session's effects-acknowledgement watermark, if one was recorded. Read failures and missing markers report false.
func (*Handle) ExportDecisions ¶ added in v3.1.0
ExportDecisions writes the store's write-gate Decision records to w as JSON Lines, preceded by one ExportMeta provenance line, and returns the number of decision rows written.
func (*Handle) ExtendToken ¶ added in v3.1.0
func (h *Handle) ExtendToken(ctx context.Context, appName, token string, ttl time.Duration) (*PauseRecord, error)
ExtendToken moves an active token's expiry to now + ttl.
func (*Handle) FindToken ¶ added in v3.1.0
FindToken resolves a resume token to its pause record (active or consumed).
func (*Handle) GatePause ¶ added in v3.1.0
func (h *Handle) GatePause(ctx context.Context, appName, userID, sessionID string) *PauseRecord
GatePause returns the session's active gate-pause record, if any.
func (*Handle) HasDecision ¶ added in v3.1.0
HasDecision delegates to Handle.Decisions.HasDecision.
func (*Handle) ListParks ¶ added in v3.1.0
func (h *Handle) ListParks(ctx context.Context, appName, userID, sessionID string) ([]SessionParkedCalls, error)
ListParks returns the open parks for one session (when sessionID is non-empty) or across all sessions under appName. When sessionID is empty, only sessions with at least one open park are returned.
func (*Handle) PauseGate ¶ added in v3.1.0
func (h *Handle) PauseGate(ctx context.Context, appName, userID, sessionID string, spec PauseSpec) (PauseHandle, bool, error)
PauseGate writes or updates a session's plane-B gate pause.
func (*Handle) PauseInterrupt ¶ added in v3.1.0
func (h *Handle) PauseInterrupt(ctx context.Context, appName, userID, sessionID, interruptID string, spec PauseSpec) (PauseHandle, error)
PauseInterrupt mints the plane-A pause record for a parked interrupt.
func (*Handle) PauseRecords ¶ added in v3.1.0
func (h *Handle) PauseRecords(ctx context.Context, appName, userID, sessionID string) (map[string]*PauseRecord, error)
PauseRecords returns all pause records for one session (active and consumed).
func (*Handle) Ping ¶
Ping reports whether the event log is still readable, for use by a readiness probe (#946).
It issues a real bounded read against the overlay table rather than pinging the connection pool. On SQLite a pool ping proves almost nothing: the pool hands back a live *sql.DB whose file may since have been deleted, replaced, or locked by another writer, and database/sql only discovers that on a statement. One indexed row read is the cheapest query that actually touches the file.
A closed Handle reports ErrClosed rather than panicking, so a probe racing shutdown fails cleanly instead of taking the process with it.
func (*Handle) RecentBoots ¶
RecentBoots returns boot-scan records with BootAt >= since, oldest first. Rows with unparsable Attempted blobs are returned with a nil slice rather than dropped — the breaker counts boots, and losing a row to corruption would weaken the guard exactly when things are already going wrong.
func (*Handle) RecordAck ¶ added in v3.1.0
RecordAck persists rec into the reserved `"mast-acks:mast-ops"` session's durable state via AppendEvent StateDelta. Repeated acks for the same (Workload, Subject) overwrite the state entry in place.
func (*Handle) RecordBoot ¶
RecordBoot appends a boot-scan record and returns the new row's ID. attempted lists the session IDs the scan triggered continuations for (empty slice = scan ran, found nothing). The returned ID lets a caller later narrow the row to the sessions that actually got a fair shot via UpdateBootAttempted — outcome-aware accounting for the write-ahead intent record (#575). AutoMigrate is idempotent and cheap at once-per-boot call frequency.
func (*Handle) RecordDecision ¶ added in v3.1.0
RecordDecision delegates to Handle.Decisions.RecordDecision.
func (*Handle) ReleaseContinuationClaim ¶
func (h *Handle) ReleaseContinuationClaim(ctx context.Context, app, user, session string, interruptedAt time.Time, holder string) error
ReleaseContinuationClaim gives back a claim whose injection did not happen, so the interruption can be claimed again immediately — by the retry driver on its next tick, or by a peer daemon — rather than after continuationClaimTTL.
Conditional on the claim still naming this interruption AND this holder, so a caller unwinding late cannot delete a successor's claim for a newer interruption.
Note the asymmetry with the claim itself: a claim that is never released is a continuation delayed by the TTL, and a release that never runs is the same. Both failure directions cost latency, and neither produces the duplicate this file exists to prevent — which is why callers log a failed release rather than retrying it.
func (*Handle) SaveSchedule ¶ added in v3.1.0
SaveSchedule writes the workload's cadence state to the reserved "mast-scheduler:mast-ops" session, replacing any previous record for rec.Workload.
func (*Handle) ScanPauses ¶ added in v3.1.0
ScanPauses walks every session's ops row under appName and returns all active pause records.
func (*Handle) Schedule ¶ added in v3.1.0
Schedule reads a workload's persisted cadence state, or (nil, nil) when no valid record is present.
Missing sessions, blanked keys, corrupt JSON, and anchor-less records all return (nil, nil) so the caller re-anchors on now rather than wedging the scheduled trigger.
func (*Handle) SessionDecisions ¶ added in v3.1.0
func (h *Handle) SessionDecisions(ctx context.Context, appName, userID, sessionID string) ([]approval.Decision, error)
SessionDecisions returns the write-gate Decision records for one session in the order the calls were adjudicated, merging records from the SQL DecisionStore and the session's event state deltas.
func (*Handle) UpdateBootAttempted ¶
UpdateBootAttempted rewrites the attempted-session list of an existing boot-log row (identified by the ID from RecordBoot). It exists to narrow a pessimistic write-ahead record down to the sessions a scan actually attempted, after synchronous skips (a run lock held by another daemon, a raced-clean tail) have been resolved — so those skips don't burn the per-session cumulative cap on daemons that never got a fair shot (#575, the fleet cap-burn). The write-ahead property is preserved: this only ever runs AFTER the intent record exists, so a daemon killed mid-scan leaves the full pessimistic list in place.
type MetadataExtractor ¶
MetadataExtractor pulls the per-event sidecar metadata from the context at Append time. Return nil (or empty map) to skip — empty maps round-trip as nil on the read side. Callers wire an extractor via WithMetadataExtractor; the default is no-op (preserves the pre-sidecar shape on disk).
The function is called inside Append's request context, so it can safely fetch request-scoped values without spawning goroutines.
type Option ¶
type Option func(*openOpts)
Option configures Open.
func WithGORMConfig ¶
WithGORMConfig overrides the gorm.Config used for the overlay connection. Useful for silencing the default logger in tests (gorm.Config{Logger: logger.Default.LogMode(logger.Silent)}).
func WithLockHeartbeat ¶ added in v3.1.0
WithLockHeartbeat overrides the heartbeat cadence and staleness window used by Handle.AcquireLock (defaults: 5s interval, 30s staleness window). Non-positive arguments keep their respective defaults.
func WithMetadataExtractor ¶
func WithMetadataExtractor(fn MetadataExtractor) Option
WithMetadataExtractor wires a function that produces sidecar metadata for each appended event. The map (JSON-encoded) is stored in the overlay row's metadata column and surfaces on Entry.Metadata at read time. Nil disables the sidecar (default).
agent.New wires an extractor that pulls the per-request caller + proxy attribution from the context so multi-session audit logs carry who triggered each event without coupling pkg/eventlog to pkg/auth.
func WithSkipWAL ¶
func WithSkipWAL() Option
WithSkipWAL disables the automatic PRAGMA journal_mode=WAL set on SQLite databases at Open time. WAL is on by default because it permits concurrent readers alongside a writer; turn it off for in-memory databases or read-only setups where WAL adds no value.
func WithWatchInterval ¶
WithWatchInterval sets the polling interval Watch uses to check for new rows. Default is 200ms. Smaller values reduce subscriber latency at the cost of database load; larger values do the opposite.
type ParkedCall ¶ added in v3.1.0
type ParkedCall struct {
InterruptID string `json:"interrupt_id"`
CallID string `json:"call_id,omitempty"`
ToolName string `json:"tool_name,omitempty"`
Awaiting string `json:"awaiting,omitempty"`
Message string `json:"message,omitempty"`
ProposedTool string `json:"proposed_tool,omitempty"`
ProposedArgs map[string]any `json:"proposed_args,omitempty"`
Subject string `json:"subject,omitempty"`
Author string `json:"author,omitempty"`
RaisedAt time.Time `json:"raised_at"`
LongRunning bool `json:"long_running,omitempty"`
ResponseSchema *jsonschema.Schema `json:"response_schema,omitempty"`
Payload any `json:"payload,omitempty"`
}
ParkedCall is one open interrupt or long-running tool park on a session.
func ScanPendingParks ¶ added in v3.1.0
func ScanPendingParks(events session.Events) []ParkedCall
ScanPendingParks walks a session's event log in order and returns any RequestedInput or LongRunningToolIDs parks that have not been resolved by a later FunctionResponse.
type PauseHandle ¶ added in v3.1.0
type PauseHandle struct {
Token string `json:"token"`
SessionID string `json:"session_id"`
ExpiresAt time.Time `json:"expires_at"`
}
PauseHandle is returned when a pause record is minted or updated.
type PauseRecord ¶ added in v3.1.0
type PauseRecord struct {
Token string `json:"token"`
Plane string `json:"plane"`
InterruptID string `json:"interrupt_id,omitempty"`
App string `json:"app"`
User string `json:"user"`
SessionID string `json:"session_id"`
Reason Reason `json:"reason"`
Message string `json:"message,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
MintedAt time.Time `json:"minted_at"`
ExpiresAt time.Time `json:"expires_at"`
ResumeAt time.Time `json:"resume_at,omitzero"`
ConsumedAt time.Time `json:"consumed_at,omitzero"`
ConsumedBy string `json:"consumed_by,omitempty"`
}
PauseRecord is the durable pause record and resume token stored on a session's companion ops row.
func (*PauseRecord) Active ¶ added in v3.1.0
func (r *PauseRecord) Active() bool
Active reports whether the record still gates or awaits a resume.
type PauseSpec ¶ added in v3.1.0
type PauseSpec struct {
Reason Reason
Message string
Metadata map[string]any
ResumeAt time.Time
Interrupt bool
TokenTTL time.Duration
}
PauseSpec is the caller-facing pause request.
type QueryOption ¶
type QueryOption func(*queryOpts)
QueryOption filters Since/Watch results.
func ForSession ¶
func ForSession(appName, userID, sessionID string) QueryOption
ForSession restricts results to one session triple. Without it, queries scan across every session in the database — useful for audit dashboards, dangerous for high-volume reads. An empty argument is a wildcard, so ForSession(app, user, "") is unscoped too. Only the SQL implementation is promised to serve unscoped queries; others may refuse them with ErrUnscopedQuery (see the Stream doc).
func WithAnyBranchPrefix ¶
func WithAnyBranchPrefix(prefixes ...string) QueryOption
WithAnyBranchPrefix matches events whose Branch begins with ANY of the supplied prefixes (an OR group, AND'd with the other filters).
One subagent is reachable under several branch spellings depending on how it was launched — a sync subagent tool tags its events with the bare name, the background runner with "bg.<name>", RunSubtask with "sub.<name>", the remote runner with "remote.<name>" — so an operator asking "what did subagent X do?" needs the union, not a single prefix (#638).
Empty prefixes are dropped: a caller building the list from user input can't accidentally widen the query to everything by passing "". LIKE metacharacters ('%', '_') in a prefix are escaped, so a prefix matches literally and only the intended subtree.
func WithAuthor ¶
func WithAuthor(name string) QueryOption
WithAuthor matches events emitted by a specific author. The autonomous driver uses Author="<binary>/autonomous" for checkpoint events; consumer-supplied authors work the same way.
func WithAuthorSuffix ¶
func WithAuthorSuffix(suffix string) QueryOption
WithAuthorSuffix matches events whose Author ends with the supplied suffix. Used by ResumeAutonomous to find checkpoint events regardless of which binary emitted them — checkpoints land with Author="<binary>/autonomous", so suffix "/autonomous" matches checkpoints from any core-agent-family process. Empty suffix is a no-op (matches everything).
func WithBranchPrefix ¶
func WithBranchPrefix(prefix string) QueryOption
WithBranchPrefix matches events whose Branch field begins with prefix. Use to scope queries to a subagent subtree once Phase 4 of the eventlog plan ships subagent runners that set Branch.
Repeated calls accumulate and are OR'd together — see WithAnyBranchPrefix, which this delegates to.
func WithLimit ¶
func WithLimit(n int) QueryOption
WithLimit caps the number of entries returned. Zero or negative is treated as no limit.
func WithSessionTree ¶
func WithSessionTree(appName, userID, parentSessionID string) QueryOption
WithSessionTree restricts results to the parent session ID and any derived sub-session IDs. The subagent runner names its session "<parent>:sub:<branch>" by convention; this option's underlying SQL matches the parent + every "<parent>:sub:%" descendant in one query so an audit can pull the whole tree without a follow-up join.
When set, takes precedence over the (App, User, Session) triple from ForSession — the two are mutually exclusive in practice because WithSessionTree implies the (app, user) pair already. Mutually composable with the other QueryOptions (WithBranchPrefix, WithAuthor, WithAuthorSuffix, WithLimit).
type Reason ¶ added in v3.1.0
type Reason string
Reason is the pause-reason taxonomy.
const ( ReasonBudgetExhaustion Reason = "budget_exhaustion" ReasonWatchdogAnomaly Reason = "watchdog_anomaly" ReasonCostCoolDown Reason = "cost_cool_down" ReasonMaintenanceWindow Reason = "maintenance_window" ReasonRateLimitBackoff Reason = "rate_limit_backoff" ReasonAmbiguity Reason = "ambiguity" ReasonOperator Reason = "operator" ReasonA2ATaskPending Reason = "a2a_task_pending" ReasonOther Reason = "other" )
type ScheduleRecord ¶ added in v3.1.0
type ScheduleRecord struct {
// Workload names the bundle or recipe this cadence belongs to.
Workload string `json:"workload"`
// Interval is the configured cadence duration at the time of the write.
Interval time.Duration `json:"interval,omitempty"`
// Anchor is the instant the cadence is counted from.
Anchor time.Time `json:"anchor"`
// LastTick is the most recent lattice point accounted for — fired,
// or coalesced away as a missed tick.
LastTick time.Time `json:"last_tick,omitempty"`
// LastFire is when the last fire actually started (tick + jitter),
// and Fires counts the fires this schedule has driven since the
// anchor was set.
LastFire time.Time `json:"last_fire,omitempty"`
Fires int64 `json:"fires,omitempty"`
}
ScheduleRecord is one workload's persisted cadence state.
The anchor is the instant the cadence is counted from: the moment the daemon first saw this workload's schedule. Every fire lands on Anchor + k*Interval, so a daemon returning from a restart preserves the workload's phase instead of re-anchoring to process boot time.
type SessionLock ¶
type SessionLock struct {
// contains filtered or unexported fields
}
SessionLock is the lease returned by Handle.AcquireLock. It runs a background goroutine that refreshes heartbeat_at every heartbeatInterval until Release is called. Safe to call Release multiple times.
func (*SessionLock) Holder ¶
func (l *SessionLock) Holder() string
Holder returns the identifier we registered when acquiring the lock. Useful for diagnostics + for tests that need to assert the row content.
func (*SessionLock) Lost ¶
func (l *SessionLock) Lost() <-chan struct{}
Lost returns a channel that is closed if the lease is lost while it is held: either the heartbeat's conditional UPDATE matched zero rows — another process reclaimed the lease after our heartbeat lapsed past the staleness window (a long GC pause, sleep, or DB stall) — or heartbeats have failed to reach the database for the loss window (staleAfter minus one heartbeat interval), after which we can no longer prove exclusivity. A caller running work under the lock — e.g. the autonomous run loop — must select on this channel and abort promptly, otherwise both processes run against the same session: the exact split-brain the lock exists to prevent. Reaffirm tells the two causes apart after the fact. The channel is never closed for a lock that is cleanly Released while still held.
func (*SessionLock) Reaffirm ¶ added in v3.1.0
func (l *SessionLock) Reaffirm(ctx context.Context) (bool, error)
Reaffirm re-proves ownership with one conditional heartbeat UPDATE and reports whether this holder still owns the row. It exists for the moment after Lost() has closed because heartbeats STALLED (not because the row was stolen): in a single-replica deployment nobody took the lease during the outage, and a caller that can prove that may still write its final checkpoint. A stolen lease reports false without touching the database. The query is bounded by heartbeatTimeout.
func (*SessionLock) Release ¶
func (l *SessionLock) Release() error
Release ends the lease and stops the heartbeat goroutine. Idempotent; safe to defer.
type SessionParkedCalls ¶ added in v3.1.0
type SessionParkedCalls struct {
SessionID string `json:"session_id"`
UserID string `json:"user_id,omitempty"`
Awaiting string `json:"awaiting"`
Pending []ParkedCall `json:"pending"`
}
SessionParkedCalls groups a session's open parks with its awaiting classification.
type SpendRecord ¶ added in v3.1.0
type SpendRecord struct {
Author string
Tokens int64
CostUSD float64
Unpriced bool
// At is the wall-clock time of the call. Zero means "now".
At time.Time
// EventID is the ledger's idempotency key within a session: a
// second Append with the same (app, user, session, EventID) is a
// no-op. Empty makes no idempotency claim — the row is stored
// with a NULL key and never deduplicated.
EventID string
// Model and Backend are what the call was priced on
// (usage.Turn.Model / usage.Turn.Backend).
Model string
Backend string
// Side marks a call recorded with usage.Tracker.AppendSideUsage.
Side bool
// Token buckets, as on usage.Turn. Tokens above is their sum for
// the Fold aggregate; these are what a restored Turn is built from.
InputTokens int64
CachedInputTokens int64
CacheCreationInputTokens int64
OutputTokens int64
ThoughtsTokens int64
ToolUseTokens int64
}
SpendRecord is one priced model call recorded in agent_budget_spend.
Author is the event's author or model attribution verbatim. CostUSD is what the call cost when it was made, priced by the catalog in force at the time. Unpriced marks a call the catalog could not price, so a restored figure preserves the same unpriced-turn signal a live tracker carries.
The remaining fields (#1433) carry the per-call shape a usage.Tracker needs to be restored from the ledger without re-pricing: the model and backend the call was billed on, the token buckets, whether it was a side call, and the event it was committed on.
type SpendState ¶ added in v3.1.0
type SpendState struct {
Session SpendTotals
ByAuthor map[string]SpendTotals
// Unpriced counts calls the catalog could not price.
Unpriced int
}
SpendState is what folding a session's ledger produces: the session's total, and the same rows broken out by author so per-subagent or per-model ceilings come back too.
Session includes every call ByAuthor also accounts for — the two are projections of the same rows, computed in the same query.
type SpendStore ¶ added in v3.1.0
type SpendStore struct {
// contains filtered or unexported fields
}
SpendStore persists and folds a session's per-call spend (#1359).
A nil *SpendStore is usable and does nothing: Append is a no-op and Fold reports empty state — the "no durable store configured" case at the call sites, same shape as GuardrailStore.
Safe for concurrent use.
func NewSpendStore ¶ added in v3.1.0
NewSpendStore constructs a store over an existing GORM connection — typically Handle.DB, the connection the guardrail store and pkg/attach's session ACL store already share. AutoMigrates agent_budget_spend; safe against an existing database.
func (*SpendStore) Append ¶ added in v3.1.0
func (s *SpendStore) Append(ctx context.Context, app, user, sid string, rec SpendRecord) error
Append writes one call's spend.
Idempotent on rec.EventID (#1433): a row already present for (app, user, sid, EventID) is left alone and no error is returned — `ON CONFLICT DO NOTHING` on SQLite and Postgres, which GORM's MySQL dialector renders as `ON DUPLICATE KEY UPDATE` of the key to itself. An empty EventID is stored as NULL and is never deduplicated.
func (*SpendStore) AppendBatch ¶ added in v3.1.0
func (s *SpendStore) AppendBatch(ctx context.Context, app, user, sid string, recs []SpendRecord) error
AppendBatch writes multiple spend rows atomically in a single transaction, with the same EventID idempotency semantics as Append (#1433). Used when seeding a pre-ledger session's historical turns so a transient mid-replay error never commits a partial ledger.
func (*SpendStore) Fold ¶ added in v3.1.0
func (s *SpendStore) Fold(ctx context.Context, app, user, sid string) (SpendState, error)
Fold reconstructs the session's spend from its ledger.
One GROUP BY author, summed in the database rather than in Go: the ledger is one row per model call, and a long-running session is the case this exists for.
A session with no rows folds to the zero value and no error.
func (*SpendStore) FoldTree ¶ added in v3.1.0
func (s *SpendStore) FoldTree(ctx context.Context, app, user, parentSID string) (SpendState, error)
FoldTree reconstructs the spend across a root session and every derived "<parent>:sub:..." sub-session in its tree, matching the scoping of WithSessionTree (#1359).
func (*SpendStore) History ¶ added in v3.1.0
func (s *SpendStore) History(ctx context.Context, app, user, sid string) ([]SpendRecord, error)
History returns the session's spend rows oldest-first — the per-call cost trail behind a folded total.
func (*SpendStore) HistoryTree ¶ added in v3.1.0
func (s *SpendStore) HistoryTree(ctx context.Context, app, user, parentSID string) ([]SpendRecord, error)
HistoryTree is History over a root session and every derived "<parent>:sub:..." sub-session in its tree, oldest-first across the whole tree — the rows a resumed session's usage.Tracker is restored from (#1433). Empty, with no error, for a session with no rows.
type SpendTotals ¶ added in v3.1.0
SpendTotals is one accumulator's folded form.
type Stream ¶
type Stream interface {
// Append writes ev to the log under sess. Returns the assigned
// seq number. The event itself is also expected to be persisted
// via the paired session.Service.AppendEvent. In the SQL
// implementation Stream.Append only writes the overlay row that
// carries the seq.
//
// Most callers don't invoke this directly; agent.Run drives the
// session.Service which in turn calls Append internally.
Append(ctx context.Context, sess session.Session, ev *session.Event) (seq int64, err error)
// Since returns events with seq > fromSeq, in seq order. Bounded
// by current end-of-log; returns when caught up. Apply filters
// via QueryOption (ForSession, WithBranchPrefix, WithAuthor,
// WithLimit). An unscoped call may yield ErrUnscopedQuery; see
// the Stream doc.
Since(ctx context.Context, fromSeq int64, opts ...QueryOption) iter.Seq2[Entry, error]
// Watch returns events with seq > fromSeq, in seq order, blocking
// for new events as they're appended. Cancel ctx to stop. Same
// QueryOptions as Since, and the same scoping rule.
//
// How new events are noticed is implementation-defined. The SQL
// implementation polls the database, by default every 200ms,
// configurable via Open's WithWatchInterval option.
Watch(ctx context.Context, fromSeq int64, opts ...QueryOption) iter.Seq2[Entry, error]
// Close releases resources held by the Stream (typically the
// underlying gorm.DB connection pool). Safe to call multiple
// times.
Close() error
}
Stream is the append-only event log primitive. Implementations are expected to be safe for concurrent use.
What every implementation promises, and what it does not:
- Seq is unique and strictly increasing within one root session tree. A session ID's root is the part before its first ":sub:"; its tree is the root plus every "<root>:sub:..." descendant, at any depth. An ID with no ":sub:" in it is its own root, which includes derived IDs such as "<sid>:digest". Seq is NOT promised to be unique across trees, so never compare or merge seqs from two different trees. The SQL implementation happens to assign one global sequence, which satisfies this.
- A query scoped to one session is always served: ForSession or WithSessionTree with a non-empty session ID. Any other query (none of those options, or an empty session ID, which every option treats as a wildcard) may span trees, and may be refused with an error wrapping ErrUnscopedQuery by an implementation that cannot enumerate its whole store. The SQL implementation serves every query.
docs/external-state-design.md is why the contract stops there.