dsh-session-format lets persistence code restore a current Session directly or compose a unique sequence of adjacent migrations while consuming physical rows once. A restore transfers caller-owned parsed values through stateful stages without intermediate artifact copies or freezing. Physical framing, compression, immutable generation naming, exclusive publication, and Cordis lifecycle behavior remain outside this library.

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

Use this package

When to use it

Use this library from persistence or format-catalog code that must classify a physical Session header, restore current logical values, or compose released adjacent migrations. It is not a Cordis plugin and has no profile mount row. No runtime invariant companion is published because each completed operation validates its result; decoder and transformer state belongs to one unfinished streaming restore and is never shared across restores.

Entry point

const catalog = createSessionFormatCatalog({ currentVersion, codecs, currentEncoder, migrations, restoreCurrent, restoreTransformedCurrent, restoreCurrentHeader })
const descriptor = catalog.readHeader(physicalHeader)
const restore = catalog.createRestore(physicalHeader, { recovery: 'recoverable', validation: 'transformed' })
for (const row of physicalRows) restore.decodeRow(row)
const current = restore.finish()
const headerRecord = catalog.encodeCurrentHeader(current.header, current.inheritedEventCount)
const eventRecords = current.events.map(catalog.encodeCurrentEvent)

createSessionFormatCatalog() accepts one frozen codec per supported version, the current record encoder, one migration per adjacent version pair, and current artifact and header restorers. readHeader() returns a current, migration-required, unsupported, or malformed descriptor without reading events. Body readers create one restore, push each parsed physical row through decodeRow(), and call finish() once for a current artifact. Writers encode its header and events record by record.

The recovery option selects strict row failure or recoverable suffix handling. validation: 'current' applies all installed current-format validation. validation: 'transformed' applies released current-format validation after historical migration, while already-current input receives only its codec's physical validation.

The recoverable decoder returns the accepted logical prefix. A codec may drop one malformed or sequence-gapped row and its uncommitted suffix, but a later decoded turn/end makes the original issue fatal.

Understand the implementation

Implementation internals — click to expand

The chain validates unique gap-free ordering at construction. The catalog composes one row decoder with stateful adjacent event transformers, retains only their bounded state and the final current events, and performs target validation at finish(); only the caller decides whether and how to publish that result.

File	Role
`src/chain.ts`	Adjacent plan construction and current bypass
`src/catalog.ts`	Physical version dispatch and header classification
`src/json.ts`	Detached lossless JSON snapshots and common coordinate checks
`src/filename.ts`	Canonical `session[.vN].jsonl` basename shared by persistence, export, and fixtures

Further Exploration

Released v0 to v1 edge — frozen historical decoding and identity conversion.
Static catalog — first-party codec and migration assembly.
JSONL persistence — durable framing and generation publication.

Model Experience

Session restoration

What the model sees

Nothing directly. Consumers reconstruct model history from the validated current artifact through deriveMessages().

Token effect

Zero direct tokens.

KV Cache effect

No direct effect. A migration that changes current history can change the cache identity owned by request reconstruction.

Known Limitations and Deferred Work

Final current history remains resident — streaming retains only bounded intermediate state, but the returned current event array and any required sequence-remap table remain O(event count).
Adjacent integer versions only — the library does not expose spans, stable event identities, or a general reference-rewrite algebra.

Dev Note

Working context for maintainers — click to expand

None.

README.md

@deepseek-ai/dsh-session-format

Summary

Table of Contents