README.md 8.2 KB
description: "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."
kind: "package-reference"
@deepseek-ai/dsh-session-projection-cache
English | 中文
Summary
dsh-session-projection-cache persists the state checkpoints of every registered projection unit (ctx.sessionProjectionCache) as one versioned document per session in the session_projcache storage domain's per-record layout. The shipped JSON backend stores each record at <root>/session_projcache/sessions/<id>.json, and the cache never reads the session-persistence layer. A stored row is a fold shortcut, never an authority: it may be stale — its seq says exactly how stale — but never wrong. Three mandatory checkpoints (session creation, turn/end, and session disposal) plus configurable count and interval throttles keep the cache fresh. Choose it when list views need synchronous cached values or cold projection folds should skip an already-checkpointed prefix.
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 in-memory tables with zero I/O. It accepts only an identity-matching record and version- and schema-matching keys, then returns a { asOfSeq, values } cut at the lowest served-row watermark. It returns undefined for an unknown id, unrelated lifecycle, absent or foreign record document, or no usable rows. coldSnapshot(meta, events) accepts a complete ordered log, skips the checkpointed prefix while folding, and refreshes the record without reading the persistence layer itself.
What the cache guarantees
The log leads and the cache follows: a live checkpoint flushes the session's buffered events durably before the cache row lands, so a crash can leave the cache behind the log but never ahead of it. Reads and writes share the storage domain's coherent in-memory state; the per-unit write chain mutates memory only after durability. Each version-stamped record must match the live unit schema and session header identity (createdAt, cwd), so malformed, stale, or unrelated records read as absent. 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](#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. It commits to six consequences: reads never bypass the domain write chain; every background write is fail-soft; a `ver` mismatch discards rather than migrates a row; a record must pass the live unit's `stateSchema`; writes replace one complete session record through the lossless-JSON boundary; and the log leads, the cache follows. ### 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 per-session directories. A malformed or stale record reads as absent, and consumers that require a cold value own any log refold. ### Source map | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Plugin entry: `SessionProjectionCache` service, write-behind listeners, cache reads | | [`src/spec.ts`](src/spec.ts) | The `session_projcache` domain spec and record identity types | | [`src/invariant.ts`](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.
- No cache-side cold refold — the cache serves and refreshes its rows but never reads the session log (it does not depend on the persistence layer); a consumer that needs a guaranteed cold snapshot refolds from the log itself.