Files

T

Tianyi Cui 0731ed374b feat(session): metadata seam + JSON-serializability invariant

Adds the durable-session metadata seam and enforces the log's
JSON-serializability invariant at the source:

- SessionHeader / SessionSummary / SessionMeta and CreateSessionOptions in
  dsh-session; Session gains a readonly `header`; SessionStore.create takes
  `(id?, options?: { seed?; meta? })` (validated absolute cwd, parentSession
  lineage). The injection TurnTrigger variant is added for the idle-inject
  one-shot turn that a later change introduces.
- isJsonValue (new json.ts): a value round-trips through JSON losslessly —
  rejects BigInt, function, symbol, undefined, non-finite numbers, sparse
  arrays, circular refs, and exotic objects (Map/Set/Date/class instances).
- Session.append throws on non-JSON-serializable data, and the Session
  constructor validates every seed event (isJsonValue + contiguous seq from
  0), so a replay/fork seed can never build a live log no backend can
  persist — the source-level guarantee a durable backend relies on.

Migrates the ~3 internal positional-seed `create(id, seed)` call sites to
`{ seed }`, and adapts the invariants tests forced by the new guard (the
bad-seq seed is now caught by the constructor; the cyclic deep-freeze test
drives via session/event since append rejects cyclic data; a direct
session/event drives the invariants seq-monotonicity check). Docs kept
backend-agnostic (the persistence packages arrive in a later PR).

2026-06-15 17:54:55 +08:00

src

Merge branch 'feat/rfc006-doc-sync' into feat/rfc005-error-taxonomy

2026-06-14 10:44:29 +08:00

tests

feat(session): metadata seam + JSON-serializability invariant

2026-06-15 17:54:55 +08:00

package.json

feat(llm): structured error taxonomy with a shared HarnessError base (RFC 005 pt 2)

2026-06-14 01:07:28 +08:00

README.md

build: doc-sync gates — typecheck doc code blocks + verify event taxonomy (RFC 006 pts 1-2)

2026-06-14 00:47:38 +08:00

tsconfig.json

feat(invariants): dev-mode event-contract assertions + session-log freeze (RFC 005 pt 3, RFC 008)

2026-06-13 23:25:12 +08:00

README.md

dsh-invariants

Dev-mode event-contract invariants and session-log freeze. A pure-listener plugin (everything is a plugin) that asserts the harness event contract at runtime and, optionally, freezes logged session-event data so any code that mutates history throws instead of corrupting silently.

Off in production. Enable it in tests and the demos, where a contract violation should fail loudly. It costs nothing when not registered, and doubles as executable documentation of the event taxonomy — the assertions are the contract.

Plugin

A functional plugin — register the module namespace (this is what loading by name in cordis.yml does):

import type { Context } from 'cordis'
import * as Invariants from '@deepseek-ai/dsh-invariants'

declare const ctx: Context

await ctx.plugin(Invariants)                     // freeze on (default)
await ctx.plugin(Invariants, { freeze: false })  // assert contract, don't freeze

inject: ['sessions'] — it reads ctx.sessions.list() at apply time to rebuild trace state for sessions that already exist (so a hot reload mid-turn doesn't falsely reject the next event). It listens on session/created, session/event, and agent/status.

Config

Key	Default	Meaning
`freeze`	`true`	Deep-freeze each logged event's data so mutating a logged event throws. Set `false` to assert the contract without freezing.

Invariants asserted

Session log (per session):

seq strictly increases — the spine of replay equivalence.
turns pair and nest — turn/start opens a turn, turn/end closes the matching one; no overlapping turns.
steps nest in turns — step/start opens a step in the open turn; step/end closes the matching step.
chunks belong to an open step — step/start precedes its assistant/chunks.
a tool/result needs a prior tool/call — but NOT the converse: a tool/call may have no result (a thrown tools/execute waterfall ends the step with no tool/result, which is legal).

Agent status (per agent):

legal transitions only — idle↔running and (idle|running)→disposed. A no-op transition (setStatus dedups, so it never fires) and leaving the terminal disposed state are violations.

On any violation it throws InvariantError (code: 'INVARIANT').

Why runtime, not deep-readonly types

A DeepReadonly<SessionEvent> is high type-noise across every log consumer, and a plugin can cast straight through it. A dev-mode freeze plus these assertions catch real corruption at zero production cost and zero type noise. The always-on half of that defense — cloning derived messages so request/adapter mutation can't reach back into the log — lives in dsh-session's deriveMessages. This package is the dev-mode tripwire. See ADR 0012.

Seeded sessions

A seeded/forked session arrives with events already in its log (the Session constructor copies the seed without emitting session/event). On session/created the plugin replays the existing log through the checker and freezes those entries, so seeded history is held to the same contract.