sessions

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 D-025.
• 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) 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) 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) Open(ctx context.Context, id string, ident identity.Identity) (*Session, 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
	Limits       SessionLimits
	Context      map[string]any
}

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.

Limits and Context are reserved slots — Phase 36a/b will populate Limits with the cost / token ceilings; Phase 23+ will populate Context with the (version, hash, llm/tool ctx, memory, artifacts) quintuple sketched in RFC §6.9. Phase 08 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 (D-020 / D-028).

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 Phase 36a (cost ceilings) and Phase 26 (tool catalog). Empty in Phase 08; 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 Phase 72c `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 (D-171): it
	// returns the live session for ident, creating it if absent and
	// no-opping if already open. A closed session is NOT revived
	// (ErrReopenAfterClose). 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)

	// 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 (Phase 09 envelope writer, Phase 60 Protocol surface, Phase 72-75 Console subscribers, etc.) talks to. One concrete impl ships in Phase 08 (`*Registry`); driver pluralism lives at the StateStore layer.

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 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.