deepseek-harness/packages/session/session-projection/README.md

description, kind

description	kind
The session-projection registry for developers serving whole current values of log-derived per-session state to client carriers, and for maintainers of the drive contract.	package-reference

@deepseek-ai/dsh-session-projection

English | 中文

Summary

dsh-session-projection serves whole current values of log-derived per-session state to client carriers — the history tail page and the session/projection push frame — through a registry (ctx.sessionProjections) that folds every committed session event through registered projection units. A domain registers a pure computation unit (initial state, a fold over events, and an optional client view); the framework owns the subscription, the drive, and change notification, so domains hold no subscriptions and clients receive finished values, never fold events themselves. Every served value is plain JSON validated against a schema, and a per-unit stateVersion anchors persisted-cache invalidation. Choose it when a client needs derived per-session state — a todo list, a goal snapshot, conversation stats — without folding the raw log itself.

Table of Contents

• Use this package
• Understand the implementation
• Further Exploration
• Model Experience
• Known Limitations and Deferred Work
• Dev Note

---

Use this package

Mount dsh-session-projection wherever client carriers need current values of log-derived session state. Domain plugins register units; carriers read snapshots and subscribe to the change feed; neither knows the other.

When to choose it

Choose it when a domain keeps state that clients should see without re-deriving it — a todo list, a goal snapshot, conversation statistics. The registry drives units eagerly over committed events, so any registered unit's value is current by construction. Skip it for host-only bookkeeping that no client reads: a unit without a wire block stays host-only, and headless assemblies without the registry are unaffected.

Define a projection unit

A domain contributes one ProjectionDefinition per state key: a key, a state schema, an initial state, a synchronous fold apply(state, event), an optional wire block that projects state to a client view, and a stateVersion that bumps whenever the state fields or fold semantics change:

const definition = {
  key: 'todo',
  stateSchema: todoStateSchema,
  stateVersion: 1,
  init: () => ({ items: [] }),
  apply: (state, event) => event.type === 'todo/upsert'
    ? { items: event.data.items }
    : state,
  wire: {
    viewSchema: todoViewSchema,
    view: state => ({ items: state.items }),
  },
}

apply must be synchronous and must return the same state reference for events that do not concern the unit — an unchanged reference means zero downstream work. A state-carrying log event must carry the complete post-change state, never a bare delta.

Register and read

register(definition) installs the unit; the registration is an effect on the calling fiber, so unloading the domain removes its key. Carriers read a consistent synchronous cut over every client-visible unit with snapshot(session) — { asOfSeq, values }, where asOfSeq is the seq of the last event every value reflects — and subscribe to per-change notifications with onChanged(listener). stateOf(session, key) reads one unit's host state without computing unrelated views.

const dispose = ctx.sessionProjections.register(definition)
const { asOfSeq, values } = ctx.sessionProjections.snapshot(session)

Persisted checkpoints

Every unit's state is checkpointed — client-visible and host-only alike — through checkpoint(session), and the sibling session-projection-cache persists those checkpoints so cold reads skip full log loads. restoreFloor and restore implement the read recipe (cached state plus a forward tail replay) without a live session.

---

Understand the implementation

Implementation internals — click to expand

This section explains the drive machinery and the unit contract; the observable contract is covered in Use this package.

Design concept

The package is the Service Definition and drive role of a capability seam: the framework drives, the domain computes. The registry subscribes to session/event once; every committed event passes every registered unit's apply eagerly (cells build lazily on first touch). The change feed is gated on Object.is — a unit that returns the same state reference costs one call and nothing downstream. Carriers read snapshot() in the same tick as their page slice, which is what makes asOfSeq one consistent cut; an accidentally async view returns a Promise and fails wire.viewSchema.parse.

Source map

File	Role
src/index.ts	Plugin entry: SessionProjectionRegistry service, ProjectionDefinition, snapshot and checkpoint machinery
src/types.ts	The merge-extensible SessionProjectionMap and SessionProjectionStateMap type tables
src/invariant.ts	Invariant companion (no runtime invariant; synchronous discipline is enforced by schema parse)

Drive and checkpoint flow

One committed event drives every registered unit in registration order; a changed client-visible unit notifies the change feed with its schema-validated view and the causing seq. checkpoint(session) returns one detached (key → {ver, seq, val}) row per unit for the persisted cache; restoreFloor anchors a tail read one event below the lowest usable watermark so a shrunk log is detected, and restore refolds persisted rows over a stored suffix, discarding any row whose ver does not match or that claims events past the stored end.

---

Further Exploration

Read these pages when the package-level contract is not enough. They move from the unit contract to the read-model subsystem and the persisted cache.

• Session projections subsystem — the projection unit contract, drive semantics, and generated service API.
• Session persistence subsystem — the event log projections fold over.
• Session projection cache — the persisted checkpoints that make cold reads skip full log loads.
• Session package map — adjacent persistence, title, and telemetry packages.
• Session-projection RFC — the design rationale for projections and the command log.

---

Model Experience

None, as the projection registry serves client-facing read models of already-logged session state and registers nothing model-facing.

KV Cache effect

None; projections never assemble or send provider requests.

Known Limitations and Deferred Work

These limits define where the projection registry needs care at scale. They are current package constraints, not a task backlog.

• Every tail page carries every client-visible key — there is no per-key opt-out or lazy-key request shape yet; acceptable while values are UI-scale whole states, revisit if a domain's value grows large.
• The unit table is process-wide, so key presence is not a per-session capability signal — a key registered by any agent preset appears in every session's snapshot; a client must read the value rather than treat an absent key as absence of the feature.
• Eager drive touches every unit per event — cheap by construction (whole-value rule, same-reference gate), but a hot path would justify per-unit event-type prefilters.
• Registry cells live in memory only — a restart rebuilds by folding the log on first touch; compositions that mount dsh-session-projection-cache seed that fold from persisted rows instead.
• Synchronous unit discipline is only partially mechanical — wire.viewSchema.parse rejects a Promise-returning view, but an apply that blocks or reads torn non-session state is a review concern.

Dev Note

Working context for maintainers — click to expand

None.