9.9 KiB
| description | kind |
|---|---|
| The persisted session-projection cache for deployments and maintainers choosing, configuring, or debugging durable checkpoints, zero-I/O list reads, and accelerated cold projection folds. | package-reference |
@deepseek-ai/dsh-session-projection-cache
English | 中文
Summary
dsh-session-projection-cache persists every registered projection unit's state as one versioned document per session in the session_projcache storage domain's per-record layout. A stored row is a disposable fold shortcut, never an authority: a zero-I/O listing may use it as a tentative hint, but the row may lag the log or overreach a later crash-repaired truncation. Exact prepared-session reads validate cached state against the supplied complete log and refold when a row no longer fits; the cache never reads session persistence itself. Three mandatory checkpoints — session creation, turn/end, and session disposal — plus configurable count and interval throttles keep records fresh enough for list prewarming and accelerated cold folds.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Mount this package beside the projection registry and the storage stack when clients should list projection values for cold sessions without loading their logs. Without it, consumers must obtain the log before they can reconstruct cold projection values.
When to choose it
Choose it when a deployment restarts sessions and needs durable projection values for history lists, statistics, or goal snapshots. Skip it when projections serve only live sessions, or when the extra storage writes cost more than the saved projection work.
Minimal configuration
Both throttle fields are required — flush cadence is a deployment choice with no universally correct value:
The cache opens its domain through the storage stack, so base mounts storage, storage-json (root dshHomePath('storages')), and storage-domain (backend: json) before it:
- id: session-projection-cache
name: '@deepseek-ai/dsh-session-projection-cache'
config:
writeEveryEvents: 200
writeIntervalMs: 5000
| Field | Default | Meaning |
|---|---|---|
writeEveryEvents |
required | Committed events per session that force a durable checkpoint write between mandatory points |
writeIntervalMs |
required | Longest time a dirty checkpoint may stay unwritten between mandatory points |
The plugin injects storageDomain, sessionProjections, and sessions. The generated configuration catalog is the exhaustive source for every accepted field and its JSDoc.
How checkpoints are written
Three mandatory points always write: session creation persists the seed-derived cut, turn/end persists the value that listing reads want, and session disposal persists the final live cut. Between them, the configured count and interval throttles write as events accumulate. Every write atomically replaces the session's complete record through the domain write chain; a failure logs a warning and keeps the cache stale, and the next write self-heals.
Reading cached values
cachedSnapshot(meta) synchronously serves client values from the storage domain's coherent in-memory table with zero I/O. It accepts only an identity-matching record and version- and schema-matching client keys, then returns a best-effort { asOfSeq, values } cut at the lowest served-row watermark; host-only rows are omitted. It returns undefined for an unknown id, unrelated lifecycle, absent or foreign record document, or no usable rows. The list carrier submits this value as a tentative hint to the per-Session Client projection store. For each carried key, a later list block replaces an earlier tentative row by arrival order, even when crash repair lowers its durable watermark; the first authoritative frame replaces a tentative row regardless of sequence, and later frames require a higher sequence. A successful follow opening gives the store a complete cut: it replaces pre-opening rows and retains only authoritative frames that arrived after the opening began and are newer than that cut. A control-generation baseline also replaces its complete per-Session value, including equal-sequence and omitted keys; when it arrives during an opening at an equal or newer cut, it remains authoritative.
coldSnapshot(meta, events) accepts the complete ordered log, validates every seeded row against that exact extent once, folds any required events from init(header), and refreshes the record without consulting persistence. hydratePrepared(session, meta, events) performs the production exact-read validation for an unpublished prepared Session; if cached state is malformed or out of range, that path retries over the full supplied log from init(header). Corruption in the durable event stream still fails the retry instead of producing a partial snapshot.
What the cache guarantees
At checkpoint commit time, the log leads and the cache follows: a live write flushes buffered Session events before storing the row, so that write cannot commit beyond the then-intact log. A later crash repair may truncate the log below an existing row, which is why cache-only values remain tentative and exact reads validate the supplied full log. Reads and writes share the storage domain's coherent in-memory state, which changes only after durability. Each record is bound to the Session header identity (createdAt, cwd), and each row is version- and schema-checked; unrelated or unusable cached data is discarded rather than migrated. The JSON backend stores each record at <root>/session_projcache/sessions/<id>.json in an owner-only directory tree.
Understand the implementation
Implementation internals — click to expand
This section explains the cache's durability and storage ownership; the observable behavior is covered in Use this package.
Design concept
The cache is a fold shortcut over the projection registry's checkpoint face, stored in a per-record domain data table. Reads never bypass the domain's coherent memory; every background write is fail-soft; a ver mismatch discards rather than migrates a row; state must pass the live unit's stateSchema; writes replace one complete Session record through the lossless-JSON boundary; and exact reads treat the complete supplied log as authoritative.
Read and write ownership
The cache stores one version-stamped document per Session in the session_projcache domain. It does not depend on a session-persistence backend, call locate, or inspect persistence directories. Callers own the exact log read and pass its immutable header and complete events into the cache; the cache owns validation, refolding, and fail-soft write-back.
Source map
| File | Role |
|---|---|
src/index.ts |
Plugin entry: SessionProjectionCache service, write-behind listeners, cache reads |
src/spec.ts |
The session_projcache domain spec and record identity types |
src/invariant.ts |
Invariant companion (no runtime invariant; correctness is enforced at the write and read paths) |
Further Exploration
Read these pages when the package-level contract is not enough. They move from the cache to the registry it checkpoints and the storage domain that holds its records.
- Session projections subsystem — the projection unit contract and drive semantics this cache checkpoints.
- Session projection registry — the
ctx.sessionProjectionsservice whose checkpoints this cache persists. - Storage subsystem — the domain routing and backend behavior that store cache records.
- Session package map — adjacent persistence, title, and telemetry packages.
- Session-projection RFC — the persisted projection cache design rationale.
Model Experience
None, as the persisted cache accelerates host-side reads of projection state and registers nothing model-facing.
KV Cache effect
None; the cache never assembles or sends provider requests.
Known Limitations and Deferred Work
These limits define where the cache needs operational care. They are current package constraints, not a task backlog.
- No eviction or retention surface — records accumulate per session; pruning stored checkpoints is out-of-band maintenance, same stance as session persistence itself.
- Interval throttle is per-session coarse — the timer arms at the first dirty event after a clean write; a steady sub-threshold trickle writes once per interval, not a sliding window.
- Zero-I/O values are best effort — a cached row may trail current events or overreach a crash-repaired truncation; exact Host reads validate against the complete log, while the Client treats each list value as tentative until the first authoritative frame or complete follow/control baseline replaces it under the projection store's precedence rules.
- Callers supply cold logs — the cache can validate and refold a complete log but never reads session persistence itself; a consumer that needs an exact cold snapshot owns that log read.
Dev Note
Working context for maintainers — click to expand
None.