sessions

type AutoNamingState ¶ added in v1.12.0

type AutoNamingState struct {
	// TitleSource is the session's current title provenance — the auto-namer
	// never overwrites TitleSourceManual.
	TitleSource TitleSource
	// CurrentTitle is the session's current title (may be empty). The
	// re-naming path includes it in the digest so the model can refine an
	// existing auto title; it NEVER rides an event payload.
	CurrentTitle string
	// TurnCount / AutoNameCount / LastAutoNamedTurn are the session's naming
	// counters (see Session).
	TurnCount         int
	AutoNameCount     int
	LastAutoNamedTurn int
}

AutoNamingState is the read-side projection the auto-naming eligibility check consumes: the session's current title provenance plus its three naming counters. It is a lightweight read (no lifecycle mutation) so the terminal-boundary trigger can decide whether a title is due without a second whole-record write.

type CascadeEraser ¶ added in v1.7.0

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

CascadeEraser performs the ordered, fail-loud, idempotent session erasure cascade behind `sessions.delete`: it refuses fail-loud on a running task, then deletes the session's scoped Artifacts, Memory, and State (the kind-agnostic StateStore scope delete removes the durable session-lifecycle record + run-scoped trajectories + planner checkpoints + the durable event stream), clears the registry's in-memory catalogs, and completes with a redacted, content-free `session.erased` audit event under the actor's observability scope.

There is no ACID transaction across the three independent stores; the cascade is ordered and every per-store delete is idempotent, so a mid-cascade error surfaces loudly (never a partial silent success — CLAUDE.md §13) and the cascade is safe to re-invoke to convergence. The refuse-if-running pre-flight runs FIRST so a refusal touches nothing; the event-bus fence (see fenceSession) runs immediately after it and BEFORE any destructive step, and a present-but-failing fence capability fails the whole cascade loud right there — the same retry-safe posture as a mid-cascade store error, just earlier.

The audit record is part of the erasure's success criteria ¶

Two follow-ups (issues #409/#410) hardened this cascade's audit trail on top of the ordering + fencing shape above. Previously, the final `session.erased` emit was best-effort AFTER the destructive steps completed: a transient bus/redactor failure lost the ONLY audit record while Erase still reported success, and — because the destructive steps (specifically StateStore.DeleteScope) had already removed the session-lifecycle record — a re-invoke returned ErrSessionNotFound, leaving no second chance to emit. Separately, a mid-cascade retry re-ran idempotent deletes that found fewer records the second time, so the reported counts reflected only the final converging attempt.

The BINDING ordering invariant: at no point may (data irrevocably gone) ∧ (no durable audit record) ∧ (success returned) hold — nor the inverse (record says erased, data present, success returned). The chosen mechanism is to persist a durable compliance checkpoint (erasureLedgerRecord, via the StateStore the cascade already drives) BEFORE each destructive step's result would otherwise become unrecoverable, rather than bounded-retrying the emit in-call. Concretely:

1. The ledger checkpoint is persisted under the actor's observability scope (ledgerScope — same reserved (tenant, user, <erasure-audit>) slot the final event publishes under), NOT the erased triple, so it survives StateStore.DeleteScope's clear of the erased session's own scope. It is tenant/user-scoped OPERATOR AUDIT DATA about a deleted session — never user content — addressing the phase plan's identity-scoping risk note head-on.
2. The ledger is checkpointed immediately after EVERY destructive step (artifacts, memory, state), accumulating each step's own count onto whatever a PRIOR interrupted attempt already contributed (loaded at the top of Erase). This is what makes counts cumulative across converging attempts (#410): a step whose data is already gone on a retry contributes 0 locally, but the ledger already holds the earlier attempt's non-zero contribution. The ledger carries the session lifecycle's OpenedAt stamp so accumulation NEVER crosses a session-id reuse boundary: when the target session still exists (a fresh attempt, not a converging retry) and a leftover ledger's stamp mismatches the live session's OpenedAt, the leftover belongs to an ABANDONED prior lifecycle of the reused id — it is discarded (with a loud Warn) and the cascade starts from zero, so a reused session id's counts reflect only its own lifecycle. Discarding necessarily forfeits the abandoned lifecycle's never-emitted record-of-fact: the caller was told loudly (ErrErasureRecordFailed) to re-invoke and instead reopened the id — inflating the NEW lifecycle's compliance counts to preserve a stale checkpoint would be the worse corruption.
3. Because the ledger holds the complete, accurate counts BEFORE StateStore.DeleteScope ever runs (steps 1-2 checkpoint before step 3), the compliance record is durably persisted strictly before the irreversible clear — satisfying the first half of the invariant. The final record-of-fact emit (completeErasure/emitErased) reads ONLY from the ledger, never recomputing counts, so it can't drift.
4. A re-invoke after the destructive steps completed but the final emit failed finds the session already gone (ErrSessionNotFound from the registry pre-flight) AND a still-present ledger checkpoint — recognized as a CONVERGING retry: it skips every destructive step (nothing left to do) and goes straight to completeErasure, which re-attempts the record + emit using the ledger's cumulative counts. Only a successful emit clears the ledger, so an emit failure keeps the session "re-invokable" without ever touching a store again.
5. A redactor refusal or a bus-publish failure at the final emit both fail Erase loud with the wrapped sentinel ErrErasureRecordFailed (no `Error`-log-and-continue) — the same loud path, because both mean the durable record-of-fact did not land.
6. The final emit is IDEMPOTENT per (session, lifecycle): before publishing, completeErasure checks the observability scope's retained history (when the bus supports events.HistoryReplayer) for a `session.erased` record already carrying this session id + lifecycle stamp, and on a hit skips the publish — converging silently to success and still clearing the ledger. This closes the duplicate-emit window when the publish succeeded but the ledger cleanup failed and the caller re-invoked. The check is capability-gated and bounded (see recordAlreadyEmitted): when it cannot verify, it emits — a duplicate compliance record is the acceptable failure direction, a lost one never is.
7. Concurrent Erase calls for the SAME session are serialized by a striped IN-PROCESS lock (lockSession) so exactly one goroutine in this process ever runs the cascade for a given session at a time: the loser blocks until the winner's cascade (through ledger cleanup) is fully done, then sees the genuine ErrSessionNotFound with no ledger — "one wins, one gets the not-found path, never a double event." HONESTY NOTE — the lock is per-process only: two runtime REPLICAS racing sessions.delete for the same session are NOT serialized (their ledger checkpoints are last-writer-wins StateStore saves, and both may run destructive steps — each of which is idempotent, so the data outcome converges). The cross-replica residuals are count skew on the racing attempts and a possible duplicate emit where the item-6 history check races the other replica's publish; never a lost record, never resurrected data. Cross-replica serialization would need a StateStore CAS/lease primitive — the same recorded limitation as the agent-config registry's per-process owner locks.

Documented residual gap (accepted, not silently dropped): there is no ACID transaction spanning a destructive store (artifacts/memory/state) and the StateStore the ledger checkpoint itself is persisted through — a generalized transactional-outbox subsystem is an explicit non-goal of this design. A failure in the narrow window between a destructive step succeeding and its OWN checkpoint save committing means that step's contribution is not durably recorded; a converging retry's local count for that step is by then 0 (already deleted), so the final total under-counts by exactly that step's amount. This is strictly narrower than the earlier whole-cascade gap it replaces (a failure ANYWHERE previously lost the whole attempt's counts) and is pinned by TestCascadeEraser_LedgerSaveFailure_LoudAndRetrySafe rather than left silently untested. It never affects the fail-loud / no-lost-record invariant (CLAUDE.md §13) — only count exactness on this specific interleaving.

A constructed *CascadeEraser is immutable after construction and safe to share across N concurrent goroutines: every method's per-call state lives in the call's arguments and locals, the shared stores + registry are each independently concurrency-safe, and the fixed-size striped lock array (eraseLocks) is the one internally-synchronized mutable field — it never grows with the number of distinct sessions ever erased.

func NewCascadeEraser(deps CascadeEraserDeps) (*CascadeEraser, error)

func (e *CascadeEraser) Erase(ctx context.Context, id identity.Identity) (prototypes.SessionsDeleteResponse, error)

type CascadeEraserDeps ¶ added in v1.7.0

type CascadeEraserDeps struct {
	Registry  *Registry
	State     state.StateStore
	Memory    memory.MemoryStore
	Artifacts artifacts.ArtifactStore
	Bus       events.EventBus
	Redactor  audit.Redactor
	Clock     Clock
	Logger    *slog.Logger
}

CascadeEraserDeps bundles the seams the CascadeEraser drives. Registry, State, Memory, Artifacts, and Bus are mandatory; Redactor, Clock, and Logger are optional.

type Clock ¶

type Clock interface {
	Now() time.Time
}

Clock abstracts time so GC tests are deterministic without time.Sleep. Production code uses realClock; tests pass a fakeClock.

The interface intentionally returns time.Time directly (not a monotonic count) so GC's wall-clock math is identical between production and test paths.

type GCPolicy ¶

type GCPolicy struct {
	IdleTTL       time.Duration
	HardCap       time.Duration
	SweepInterval time.Duration
	RunningProbe  RunningProbe
}

GCPolicy bundles the GC sweeper's tunables. Defaults match RFC §6.9: IdleTTL 24h, HardCap 720h (30 days), SweepInterval 15m. The RunningProbe should be TaskRunningProbe wherever a TaskRegistry is in scope; default is the no-op.

type Option ¶

type Option func(*Registry)

Option configures a Registry at construction. Only WithClock is exported; production code does not touch it. Tests use a fake clock to drive GC deterministically.

func WithClock(c Clock) Option

func WithGCPolicy(p GCPolicy) Option

type Registry ¶

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

Registry is the StateStore-backed implementation of SessionRegistry. It is the single concrete impl in V1 — driver pluralism lives at the StateStore layer.

Concurrency model:

• StateStore writes go through `state.StateStore.Save` which is itself concurrent-safe per the concurrent-reuse contract.
• The cross-tenant SessionID-uniqueness map is guarded by mu.
• The sweeper goroutine's lifecycle is owned by `done` + `wg`.

func New(store state.StateStore, cfg config.SessionsConfig, bus events.EventBus, opts ...Option) (*Registry, error)

func (r *Registry) AutoNamingState(ctx context.Context, id string, ident identity.Identity) (AutoNamingState, error)

func (r *Registry) Close(ctx context.Context, id string, reason string) error

func (r *Registry) CloseRegistry(_ context.Context) error

func (r *Registry) EnsureOpen(ctx context.Context, ident identity.Identity) (*Session, error)

func (r *Registry) Erase(ctx context.Context, id string) error

func (r *Registry) GC(ctx context.Context, policy GCPolicy) (int, error)

func (r *Registry) Get(ctx context.Context, id string) (*Session, error)

func (r *Registry) Inspect(ctx context.Context, id string) (*SessionSnapshot, error)

func (r *Registry) ListSnapshots(ctx context.Context, f SessionListFilter) ([]SessionSnapshot, error)

func (r *Registry) OldestRetainedAt(ctx context.Context) (time.Time, bool, error)

func (r *Registry) Open(ctx context.Context, id string, ident identity.Identity) (*Session, error)

func (r *Registry) RecordCompletedTurn(ctx context.Context, id string, ident identity.Identity) (int, error)

func (r *Registry) SetTitle(ctx context.Context, id string, ident identity.Identity, title string) error

func (r *Registry) SetTitleAuto(ctx context.Context, id string, ident identity.Identity, title string) error

func (r *Registry) Touch(ctx context.Context, id string) error

type RunningProbe ¶

type RunningProbe func(ctx context.Context, q identity.Quadruple) (bool, error)

RunningProbe is the seam the GC sweeper consults so it can honor "never reap a session with a RUNNING task" (RFC §6.9). The TaskRegistry-backed implementation is TaskRunningProbe; both reference assemblies wire it via WithGCPolicy. A nil probe is treated as the no-op default (returns false, nil) — only for registries constructed without task awareness.

func TaskRunningProbe(reg tasks.TaskRegistry) RunningProbe

type Session ¶

type Session struct {
	ID           string
	Identity     identity.Identity
	OpenedAt     time.Time
	LastSeen     time.Time
	Closed       bool
	ClosedAt     time.Time
	ClosedReason string
	// LastReopenedAt is the timestamp of the most recent reopen (Open /
	// EnsureOpen re-activating a Closed record). Zero on a session that was
	// never reopened. Additive JSON field — an older persisted record decodes
	// with it zero-valued, so no migration is needed. It exists as a SEPARATE
	// stamp from OpenedAt because OpenedAt must NOT be refreshed on reopen:
	// OpenedAt is the erasure cascade's lifecycle discriminator
	// (erasureLedgerRecord.SessionOpenedAt) and mutating it would corrupt
	// erasure reuse-boundary discrimination. The GC hard cap is measured from
	// max(OpenedAt, LastReopenedAt), so a reopened conversation restarts its
	// hard-cap clock from the reopen (resume-forever) without disturbing the
	// erasure discriminator.
	LastReopenedAt time.Time
	Limits         SessionLimits
	Context        map[string]any
	Title          string
	TitleSource    TitleSource
	// TurnCount / AutoNameCount / LastAutoNamedTurn are the auto-naming
	// counters. They are additive JSON fields: an older persisted record
	// (written before auto-naming existed) decodes with all three
	// zero-valued. They are written ONLY when a naming policy is active for
	// the run (a config-free runtime never touches them), so a naming-off
	// fleet carries no per-run write amplification and the counters read
	// zero for every session. Written exclusively through
	// RecordCompletedTurn (bumps TurnCount) and SetTitleAuto (bumps
	// AutoNameCount + LastAutoNamedTurn alongside the title, in ONE record
	// save).
	//
	// TurnCount counts runs completed while a naming policy was active —
	// counting starts at policy enablement, so enabling naming mid-session
	// counts turns from enablement, not from session open (a documented
	// consequence of writing counters only when the policy is active).
	// AutoNameCount is the number of auto-naming LLM calls that produced a
	// title. LastAutoNamedTurn is the TurnCount at which the most recent
	// auto-naming landed (the re-naming cadence anchor).
	TurnCount         int
	AutoNameCount     int
	LastAutoNamedTurn int
}

Session is the persisted lifecycle record for one session. The Identity field carries the triple captured on Open and is immutable afterwards. Closed transitions to true on Close; ClosedAt stays zero while Closed is false.

Title / TitleSource are additive fields: an older persisted session record (one written before these fields existed) decodes with both zero-valued (""), which is exactly TitleSourceUnset — no migration needed. Title has two writers: SetTitle (the sessions.set_title verb — manual set/clear, with trim + length/control-character validation, and an empty value clears the title and resets the auto-naming counters) and SetTitleAuto (the internal auto-namer — writes TitleSource="auto", refusing to overwrite a manual title). Title is user-derived free text and MUST NEVER be copied into an event/log/audit payload (CLAUDE.md §7 rule 7 — content-free posture) — only SessionID + TitleSource ride SessionTitleChangedPayload.

Limits and Context are reserved slots — later phases will populate Limits with the cost / token ceilings and Context with the (version, hash, llm/tool ctx, memory, artifacts) quintuple sketched in RFC §6.9. round-trips both fields through marshal/unmarshal but applies no validation.

type SessionClosedPayload ¶

type SessionClosedPayload struct {
	events.SafeSealed
	SessionID string
	ClosedAt  int64 // unix nanoseconds
	Reason    string
}

SessionClosedPayload reports a Close. Carries the SessionID, the ClosedAt timestamp, and the operator-provided Reason. Reason is a short caller-controlled string — callers MUST NOT pass tool args, raw user input, or any secret-shaped material; the bus does not re-redact SafePayload types.

type SessionErasedPayload ¶ added in v1.7.0

type SessionErasedPayload struct {
	events.SafeSealed
	// SessionID is the session that was erased.
	SessionID string
	// StateRecordsDeleted is the number of StateStore records removed by
	// the kind-agnostic scope delete. Cumulative across converging
	// attempts.
	StateRecordsDeleted int
	// ArtifactsDeleted is the number of artifacts removed. Cumulative
	// across converging attempts.
	ArtifactsDeleted int
	// MemoryPurged is true when the session's memory was flushed clean.
	MemoryPurged bool
	// ErasedAt is the erasure timestamp (unix nanoseconds).
	ErasedAt int64
}

SessionErasedPayload reports a completed session erasure. It carries the erased SessionID plus the per-store deletion counts and the erasure timestamp — non-sensitive telemetry only, NO user content. The erased session id is a payload FIELD (not the event's Identity): the event is published under the actor's observability scope so it never re-persists durable state under the erased triple. SafePayload by construction — every field is a bounded id, count, or timestamp.

This is the durable record-of-fact for a right-to-erasure operation, and publishing it is part of `sessions.delete`'s SUCCESS CRITERIA rather than a best-effort afterthought: Erase only ever returns success once this payload has been redacted and durably published. The count fields are CUMULATIVE across any converging retries the cascade needed (see internal/sessions.CascadeEraser's package godoc) — the true total actually removed, never just the last attempt's own count.

type SessionGCReapedPayload ¶

type SessionGCReapedPayload struct {
	events.SafeSealed
	SessionID string
	ReapedAt  int64 // unix nanoseconds
	Reason    string
}

SessionGCReapedPayload reports a GC sweep reaping. Reason is one of "gc:idle" or "gc:hard_cap"; the same string is also stored in Session.ClosedReason. SafePayload by construction.

type SessionLimits ¶

type SessionLimits struct {
}

SessionLimits is reserved for later phases (cost ceilings, tool catalog). Empty at V1; round-trips through marshal.

type SessionListFilter ¶

type SessionListFilter struct {
	TenantIDs     []string
	UserIDs       []string
	SessionIDs    []string
	SinceLastSeen time.Time
	UntilLastSeen time.Time
	IncludeClosed bool
}

SessionListFilter narrows ListSnapshots's result set. All fields are wildcards when empty. SinceLastSeen / UntilLastSeen filter by the LastSeen timestamp; zero means "no bound."

type SessionLister ¶

type SessionLister interface {
	// ListSnapshots returns session snapshots that match the filter,
	// scoped to the requested tenants. Empty `TenantIDs` matches every
	// tenant the registry has seen (the search subsystem gates this
	// on the caller's auth.ScopeAdmin claim — the registry does NOT
	// re-check scope). Empty `UserIDs` / `SessionIDs` are wildcards.
	ListSnapshots(ctx context.Context, f SessionListFilter) ([]SessionSnapshot, error)
}

SessionLister is the narrow read-side capability the `search.sessions` Searcher consumes. The triple `(tenant, user, session)` is the load-bearing isolation key (CLAUDE.md §6); the listing is server-enforced per the supplied SessionListFilter. The returned snapshots include both currently-open and previously-closed sessions — search wants the union.

Intentionally NOT on the SessionRegistry interface: the lister is a projection over the in-memory open-session index plus the StateStore. Concrete `*Registry` implements it; future drivers add it when their backing store gains a `list` capability (StateStore List is post-V1).

type SessionOpenedPayload ¶

type SessionOpenedPayload struct {
	events.SafeSealed
	SessionID string
	OpenedAt  int64 // unix nanoseconds; identity-of-record across drivers
}

SessionOpenedPayload reports a successful Open. Carries the SessionID and the OpenedAt timestamp; the identity triple lives on the Event itself, so it is intentionally NOT duplicated here.

SafePayload by construction — no secret-shaped fields.

type SessionRegistry ¶

type SessionRegistry interface {
	Open(ctx context.Context, id string, ident identity.Identity) (*Session, error)
	// EnsureOpen is the create-on-first-use entry point: it
	// returns the live session for ident, creating it if absent,
	// no-opping if already open, and RE-ACTIVATING it if closed (RFC §6.9
	// amended). An ERASED session is the terminal exception:
	// EnsureOpen fails loud with ErrReopenAfterErase. See the concrete impl
	// for full semantics.
	EnsureOpen(ctx context.Context, ident identity.Identity) (*Session, error)
	Get(ctx context.Context, id string) (*Session, error)
	Touch(ctx context.Context, id string) error
	Close(ctx context.Context, id string, reason string) error
	Inspect(ctx context.Context, id string) (*SessionSnapshot, error)
	GC(ctx context.Context, policy GCPolicy) (int, error)

	// SetTitle sets or clears the manual title of session `id`. `ident`
	// is the CALLER's verified (tenant, user, session) — id MAY name a
	// sibling session of the same (tenant, user) (the write scope is
	// (tenant, user), matching sessions.list); it is not
	// required to equal ident.SessionID. Semantics: trims whitespace;
	// an empty-after-trim title clears Title and resets TitleSource to
	// TitleSourceUnset; a non-empty title is validated (MaxSessionTitleLen,
	// no newline/control characters — ErrInvalidTitle, never a silent
	// clamp) and stored with TitleSource = TitleSourceManual. Unknown id
	// (or an id belonging to a different (tenant, user)) returns
	// ErrSessionNotFound; a stored-identity (tenant, user) mismatch
	// (defence-in-depth) returns ErrIdentityMismatch. Renaming a CLOSED
	// session is allowed; renaming an ERASED session is
	// ErrSessionNotFound (the record is gone).
	SetTitle(ctx context.Context, id string, ident identity.Identity, title string) error

	// RecordCompletedTurn increments the session's TurnCount and returns the
	// new value. It is called from the run loop's terminal boundary ONLY when
	// a naming policy is active for the run — a naming-off runtime never calls
	// it, so it writes nothing for the naming-off fleet. `ident` is the run's
	// verified (tenant, user, session); a stored-identity mismatch returns
	// ErrIdentityMismatch, an unknown / erased id returns ErrSessionNotFound.
	// The load→bump→save runs through the serialized whole-record write path
	// (never a torn two-write update).
	RecordCompletedTurn(ctx context.Context, id string, ident identity.Identity) (int, error)

	// SetTitleAuto sets the session's title from the internal auto-namer and
	// bumps AutoNameCount + LastAutoNamedTurn in the SAME record save. It
	// REFUSES with ErrManualTitle when the current TitleSource is
	// TitleSourceManual (manual wins, structurally). `title` is expected to be
	// already clamped by the caller to the naming policy bound; the registry
	// re-clamps defensively to MaxSessionTitleLen runes and single-line, and
	// rejects an empty-after-trim title with ErrInvalidTitle (the auto path
	// never intentionally clears). On success it stores TitleSource =
	// TitleSourceAuto and publishes a content-free session.title_changed
	// (source=auto). `ident` is the run's verified triple; a stored-identity
	// mismatch returns ErrIdentityMismatch, an unknown / erased id returns
	// ErrSessionNotFound.
	SetTitleAuto(ctx context.Context, id string, ident identity.Identity, title string) error

	// CloseRegistry cancels the sweeper goroutine and joins it.
	// Idempotent. Distinct method name (rather than Close) so it
	// doesn't collide with Close(id, reason).
	CloseRegistry(ctx context.Context) error
}

SessionRegistry is the public surface every consumer ( envelope writer, Protocol surface, Console subscribers, etc.) talks to. One concrete impl ships in a later phase (`*Registry`); driver pluralism lives at the StateStore layer.

type SessionReopenedPayload ¶ added in v1.14.0

type SessionReopenedPayload struct {
	events.SafeSealed
	// SessionID is the session that was reopened.
	SessionID string
	// ReopenedAt is the reopen timestamp (unix nanoseconds).
	ReopenedAt int64
	// PriorClosedReason is the reason the session had been closed with
	// before this reopen — a GC reason ("gc:idle" / "gc:hard_cap") or the
	// operator-supplied Close reason. A bounded, closed-set-or-operator
	// string, never user content (the Close reason is caller-controlled but
	// MUST NOT carry secret-shaped material — the same contract
	// SessionClosedPayload.Reason follows).
	PriorClosedReason string
}

SessionReopenedPayload reports a session being re-activated from a Closed state (RFC §6.9 amended). Carries the SessionID, the ReopenedAt timestamp, and the PriorClosedReason (the reason the session had been closed with — "gc:idle" / "gc:hard_cap" for a GC reap, or the operator-supplied Close reason). Content-free by construction: NO title, NO user content, NO conversation body — the identity triple lives on the Event itself. Consumers refetch the projection / windowed history for the resumed conversation. SafePayload by construction.

type SessionSnapshot ¶

type SessionSnapshot struct {
	Session
	Running bool
}

SessionSnapshot is the read-side projection returned by Inspect. Carries the lifecycle fields plus a Running boolean derived from the GCPolicy.RunningProbe at inspection time. Running is intrinsically stale by the time the caller reads it; the same is true of any snapshot model.

type SessionTitleChangedPayload ¶ added in v1.12.0

type SessionTitleChangedPayload struct {
	events.SafeSealed
	// SessionID is the session whose title changed.
	SessionID string
	// Source is the resulting TitleSource after the call — a three-value
	// domain: "manual" when a caller set a non-empty title via
	// sessions.set_title, "auto" when the internal auto-namer set it via
	// SetTitleAuto, and "" (TitleSourceUnset) when the title was cleared. The
	// wire verb produces only "manual" / ""; the "auto" value comes from the
	// runtime's own auto-naming path.
	Source string
}

SessionTitleChangedPayload reports a successful title change from EITHER producer — the `sessions.set_title` verb (SetTitle: manual set or clear) or the internal auto-namer (SetTitleAuto: auto set). Carries the SessionID and the resulting Source ONLY — the title string itself NEVER rides this payload (the same content-free contract SessionErasedPayload follows): the title is user-derived free text, and SafePayload types are published WITHOUT a redactor pass (the bus skips the redactor for types sealed via SafeSealed), so any raw content here would leak straight to every subscriber. Consumers that want the title text refetch `sessions.list` / `sessions.inspect`.

SafePayload by construction — every field is a bounded id or a closed-set enum string.

type SessionTouchedPayload ¶

type SessionTouchedPayload struct {
	events.SafeSealed
	SessionID string
	LastSeen  int64 // unix nanoseconds
}

SessionTouchedPayload reports a Touch. Carries the SessionID and the new LastSeen timestamp. SafePayload by construction.

type TitleSource ¶ added in v1.12.0

type TitleSource string

TitleSource marks who produced a session's Title. The wire verb `sessions.set_title` ALWAYS writes TitleSourceManual (empty title clears both fields to TitleSourceUnset) — TitleSourceAuto is not expressible over the wire; it is declared here for the runtime's internal auto-naming writer, which is the only producer. This makes "manual wins" structurally unforgeable: a caller can never claim `auto` provenance for a title they set themselves.

const (
	// TitleSourceUnset — no title has ever been set, or the title was
	// cleared (an empty SetTitle call resets both Title and
	// TitleSource to this zero value).
	TitleSourceUnset TitleSource = ""
	// TitleSourceAuto — the title was produced by the runtime's internal
	// auto-naming writer. Not reachable via the `sessions.set_title`
	// wire verb.
	TitleSourceAuto TitleSource = "auto"
	// TitleSourceManual — the title was set by an authenticated caller
	// via `sessions.set_title`. Manual titles are never silently
	// overwritten by an auto-namer.
	TitleSourceManual TitleSource = "manual"
)