fix(scope): close remaining ownership boundaries

packages/core/session/README.md

@@ -8,7 +8,7 @@ Creates and holds event-sourced `Session` instances. Persistence is intentionall
 
 ### Public API
 
-- `ctx.sessions.create(id?: SessionId, options?: { seed?: SessionEvent[]; meta?: { cwd?: string; parentSession?: SessionId; createdAt?: number; seedLength?: number } }): Session` — Create a session. `options.seed` replays/forks an existing event log; `options.meta` attaches creation metadata (validated absolute `cwd`, `parentSession` lineage, seed boundary) as the immutable `SessionHeader`. The store fills `version`/`id` and defaults `createdAt` to now; a caller reconstructing a persisted session passes the original `createdAt` and persisted `seedLength` to preserve them. Disposed with the calling fiber.
+- `ctx.sessions.create(id?: SessionId, options?: { seed?: SessionEvent[]; meta?: { cwd?: string; parentSession?: SessionId; createdAt?: number; seedLength?: number } }): Session` — Create a session. `options.seed` replays/forks an existing event log: the constructor reads each array entry once, then recursively validates and copies every nested value in one pass so validation and storage cannot observe different getter results or erase an exotic prototype before checking it. `options.meta` attaches creation metadata (validated absolute `cwd`, `parentSession` lineage, seed boundary) as the immutable `SessionHeader`: the store rejects an exotic metadata shell, reads every accepted field once, and constructs a detached, deep-frozen header. The store fills `version`/`id` and defaults `createdAt` to now; a caller reconstructing a persisted session passes the original `createdAt` and persisted `seedLength` to preserve them. Disposed with the calling fiber.
 - `ctx.sessions.flush(session: Session): Promise<void>` Dispatch the awaited `session/flush` durability checkpoint with the carrier captured at enter — THE flush entry point (the loop's turn-end checkpoint and idle injection call it; never dispatch a raw `ctx.parallel`). Rejects a prepared, detached, or stale same-id object instead of inventing a subject-less carrier.
 - `ctx.sessions.fork(source, boundary?, childSessionId?): Session` — Resolve a live session object or id, select a seed through the inclusive `boundary` event seq (default: current last event), require that boundary to be `turn/end`, and create a live child session with lineage metadata.
 - `ctx.sessions.get(id: SessionId): Session | undefined`
@@ -18,7 +18,7 @@ Creates and holds event-sourced `Session` instances. Persistence is intentionall
 
 `create()` covers the common case (the session is owned by the calling fiber). When a session must be torn down **in order with another resource** — so a final flush is captured before `onAppend` detaches — `create()`'s self-contained effect is wrong, because a fiber unload disposes sibling effects *concurrently*. For that, split the lifecycle and fold it into the owner's single effect:
 
-- `ctx.sessions.prepare(id?, options?): Session` — validate the id/cwd and construct the `Session`, WITHOUT entering it into the store. Same options as `create`.
+- `ctx.sessions.prepare(id?, options?): Session` — read `options.seed`/`options.meta` once, validate and detach the metadata/header, and construct the `Session` WITHOUT entering it into the store. Same options as `create`.
 - `ctx.sessions.enter(session): () => void` — wire `onAppend` → `session/event`, capture its scope carrier, and add the session to the store; returns the idempotent DETACH disposer, which clears both notification and carrier state. Does NOT emit `session/created` (the caller installs the disposer first, then calls `announce`, so a throwing listener rolls the attach back). It re-checks the id because public `prepare`/`enter` calls may be interleaved; a stale prepared object must not overwrite a live same-id session.
 - `ctx.sessions.announce(session): void` — emit `session/created` for an entered session.
 
@@ -32,12 +32,17 @@ The store announces creation, publishes each append, and provides an awaited dur
 
 Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
 
-- `session.append(type, data, opts?): SessionEvent` — synchronous, never blocks on I/O. **Throws** if `data` is not losslessly JSON-serializable (BigInt, function, symbol, undefined, non-finite number, circular ref, or an exotic object like Map/Set/Date) — the event log is the durable source of truth, so this invariant is enforced at the source (exported as `isJsonValue` for backends to reuse on their replay/fork entry points). A third parameter `opts: SurfaceIntent` carries surface metadata: `surfaceOp` controls how the event enters the surface linked list, and `sourceEventSeqs` records provenance (the seq numbers of events this one derives from). It is **required** for the five `SurfaceEventType` events (every message-producing event must declare how it joins the surface) and rejected by the compiler for non-surface types. The marker requirement is enforced two ways: the typed overload makes `opts` mandatory when `type` is a specific `SurfaceEventType` literal, AND `append` **throws** at runtime if a surface-eligible event arrives with no `surfaceOp` — covering the case where `type` widens to the `SessionEventType` union (a caller iterating raw events, where the conditional overload collapses to optional) so a marker-less message event can never silently land in the log and vanish from `deriveMessages()`.
+- `session.append(type, data, opts?): SessionEvent` — synchronous, never blocks on I/O. **Throws** if `data` or surface metadata is not losslessly JSON-serializable (BigInt, function, symbol, undefined, `-0`, non-finite number, circular ref, or an exotic object like Map/Set/Date/class instance). One recursive validate-and-copy pass reads each nested value exactly once and produces the detached value that enters the log, so validation and durability cannot diverge through a stateful getter or a prototype-erasing clone. The accepted event and every nested value are deep-frozen before publication; the returned event and observer notification share that immutable owned record. A third parameter `opts: SurfaceIntent` carries surface metadata: `surfaceOp` and `sourceEventSeqs` are each read once, then the former controls how the event enters the surface linked list and the latter records provenance. Runtime validation accepts only `'append'` or the exact `{ op: 'replace', start, end }` record with non-negative safe-integer bounds, and provenance must be an array of non-negative safe integers; non-surface events reject either field. The marker is **required** for the five `SurfaceEventType` events (every message-producing event must declare how it joins the surface) and rejected by the compiler for non-surface types. The contract is enforced two ways: the typed overload handles a specific event literal, AND runtime checks cover widened unions and raw seed/load logs so invalid metadata can never silently enter or disappear from `deriveMessages()`.
 - `session.deriveMessages(): Message[]` — the LLM message history, CACHED: each surface node is projected exactly once, when first seen (O(new nodes) per call; a surface rewrite rebuilds via `surface.replaceGeneration`). Returns a fresh array snapshot per call over SHARED, deep-frozen `Message` objects — cloned once off the log at projection time, so a consumer can never mutate logged data (mutation throws). The surface is the single source of derived history — there is no raw-log fallback.
 - `session.deriveEventMessage(event): Message | null` — the per-event projection `deriveMessages()` folds: one event's derived message (an unfrozen clone), or `null` when it produces none (a non-surface event, or an empty-content `assistant/message` hosting only usage). External reconstructors and the dev invariant fold the same function over a log prefix's surface, so no two paths can disagree about what a request's messages were (the reconstructability RFC).
 - `session.surface: SurfaceManager` — the derived surface, lazily rebuilt from `surfaceOp` markers in the log. Processes only new events (delta) on each access — the log is append-only, so prior events never change. `surface.replaceGeneration` is the rewrite signal: bumped by every folded `replace` and by `invalidate()`, never reset, so an incremental consumer comparing generations cannot be fooled.
-- `session.events`, `session.seq`, `session.id`
-- `session.header: SessionHeader` — immutable creation metadata (`version`, `id`, `createdAt`, optional `cwd`/`parentSession`/`seedLength`). Kept out of the event log (a storage concern, not replayable state); a minimal header (stamped with the current `SESSION_FORMAT_VERSION`) is synthesized for bare `Session` construction.
+- `session.events` — a cached, frozen array snapshot over deep-frozen events. Repeated reads without an append return the same array; an append invalidates the cache and the next read returns a new snapshot, while earlier snapshots stay unchanged. Neither a cast nor a retained reference can push into the live log or rewrite an accepted event.
+- `session.seq`, `session.id`
+- `session.header: SessionHeader` — detached, deep-frozen creation metadata (`version`, `id`, `createdAt`, optional `cwd`/`parentSession`/`seedLength`). Construction validates its lossless-JSON shape and requires the header id to match `session.id`, so a caller cannot later mutate persistence routing or lineage through an aliased header. Kept out of the event log (a storage concern, not replayable state); a minimal header (stamped with the current `SESSION_FORMAT_VERSION`) is synthesized for bare `Session` construction.
+
+### Lossless JSON utilities
+
+Durable values need one accepted representation, not a check followed by a second read. `isJsonValue(value)` is the boolean predicate; `snapshotJsonValue(value)` recursively validates and copies a plain value in one pass, returning `undefined` for invalid input and propagating a throwing getter. The snapshot helper accepts finite JSON numbers except `-0` (JSON rewrites it to `0`), dense ordinary arrays, and plain or null-prototype objects; it rejects cycles, unsupported scalars, and exotic prototypes before normalization.
 
 ### Surface types
 
@@ -65,12 +70,12 @@ Every `SessionEvent` carries two optional top-level fields (structural metadata)
 
 ### Metadata types (`types.ts`)
 
-- `SessionHeader` — immutable session metadata, written once: `{ version, id, createdAt, cwd?, parentSession?, seedLength? }`. Owned here (beside `SessionId`) because `Session.header` is typed by it; persistence backends re-export it rather than own it (which would force a package cycle).
+- `SessionHeader` — session metadata written once when published as `Session.header`, where detachment and deep-freezing enforce immutability at runtime: `{ version, id, createdAt, cwd?, parentSession?, seedLength? }`. Persistence loaders may return mutable detached copies of the same data type. Owned here (beside `SessionId`) because `Session.header` is typed by it; persistence backends re-export it rather than own it (which would force a package cycle).
 
 ### Extension points
 
 - Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata seam (`SessionHeader`, `session.header`) is what such a backend stores beside the log.
-- Replay/fork: `ctx.sessions.create(id, { seed })` seeds a new session with an existing event log. The surface rebuilds deterministically from `surfaceOp` markers in the seeded events. The seed is validated to the SAME always-on invariants `append` enforces — contiguous seqs, JSON-serializable data, and required `surfaceOp` markers on surface-eligible events — so marker-less message events are rejected at construction rather than silently vanishing from `deriveMessages()`. Broader turn-enclosure checks stay in `dsh-invariants` and persistence repair. Ordinary live-session forks use `ctx.sessions.fork(source, boundary?, childSessionId?)`, where `boundary` is the inclusive source event seq to fork through.
+- Replay/fork: `ctx.sessions.create(id, { seed })` seeds a new session with an existing event log. The surface rebuilds deterministically from `surfaceOp` markers in the seeded events. The constructor reads each seed entry once and uses the same one-pass lossless-JSON snapshot and exact surface-metadata shape checks as `append`, then enforces contiguous seqs and deep-freezes every accepted record; a stateful caller, exotic nested value, marker-less or malformed surface event, metadata on a non-surface event, or retained seed reference therefore cannot silently change the reconstructed history. Broader turn-enclosure checks stay in `dsh-invariants` and persistence repair. Ordinary live-session forks use `ctx.sessions.fork(source, boundary?, childSessionId?)`, where `boundary` is the inclusive source event seq to fork through.
 - Compaction: the `dsh-compact-basic` plugin appends a `user/message` with `surfaceOp: { op: 'replace', start, end }` to shadow old surface nodes behind a summary checkpoint.
 
 ### What is NOT here (TODO)

packages/core/session/src/index.ts

@@ -14,12 +14,12 @@ import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { ContentBlock, Message, MessageSource } from '@deepseek-ai/dsh-llm'
 import { SESSION_FORMAT_VERSION, SessionId } from './types.ts'
 import type { CreateSessionOptions, EpochHeader, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceIntent, SurfaceEventType } from './types.ts'
-import { isJsonValue } from './json.ts'
+import { snapshotJsonValue } from './json.ts'
 import { SurfaceManager, isSurfaceEligibleType } from './surface.ts'
 import { foldRequestHeader } from './request-header.ts'
 
 export * from './types.ts'
-export { isJsonValue } from './json.ts'
+export { isJsonValue, snapshotJsonValue } from './json.ts'
 export type { JsonValue } from './json.ts'
 export { interruptedTurnClosers } from './repair.ts'
 export type { SurfaceNode } from './surface.ts'
@@ -99,6 +99,160 @@ function renderTagged(tag: string, content: ContentBlock[], source: MessageSourc
   ]
 }
 
+/** Reject a record shell that cloning or spreading would otherwise sanitize. */
+function assertPlainRecord(value: unknown, label: string): asserts value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') {
+    throw new Error(`${label} is not a plain JSON record`)
+  }
+  const prototype = Object.getPrototypeOf(value) as unknown
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new Error(`${label} is not a plain JSON record`)
+  }
+}
+
+/** Capture and validate the caller-owned fields that become a session header. */
+function snapshotSessionMeta(source: CreateSessionOptions['meta']): NonNullable<CreateSessionOptions['meta']> {
+  if (source === undefined) return {}
+  assertPlainRecord(source, 'session metadata')
+
+  // Read each accepted field exactly once. The metadata vocabulary is scalar,
+  // so this plain record is already detached from the caller; cloning the
+  // caller's shell first would erase a class prototype before validation.
+  const cwd = source.cwd
+  const parentSession = source.parentSession
+  const createdAt = source.createdAt
+  const seedLength = source.seedLength
+  const accepted = {
+    ...cwd !== undefined ? { cwd } : {},
+    ...parentSession !== undefined ? { parentSession } : {},
+    ...createdAt !== undefined ? { createdAt } : {},
+    ...seedLength !== undefined ? { seedLength } : {},
+  }
+  const snapshot = snapshotJsonValue(accepted)
+  if (snapshot === undefined) throw new Error('session metadata is not losslessly JSON-serializable')
+  if (snapshot.cwd !== undefined) {
+    if (typeof snapshot.cwd !== 'string') throw new Error('session cwd must be a string')
+    if (!isAbsolute(snapshot.cwd)) {
+      throw new Error(`session cwd must be an absolute path, got "${snapshot.cwd}"`)
+    }
+  }
+  if (snapshot.parentSession !== undefined && typeof snapshot.parentSession !== 'string') {
+    throw new Error('session parentSession must be a string')
+  }
+  if (snapshot.createdAt !== undefined
+    && (typeof snapshot.createdAt !== 'number' || !Number.isFinite(snapshot.createdAt))) {
+    throw new Error('session createdAt must be a finite number')
+  }
+  if (snapshot.seedLength !== undefined
+    && (typeof snapshot.seedLength !== 'number' || !Number.isSafeInteger(snapshot.seedLength) || snapshot.seedLength < 0)) {
+    throw new Error('session seedLength must be a non-negative safe integer')
+  }
+  return snapshot
+}
+
+/** Detach, validate, and freeze the creation metadata published by a session. */
+function snapshotSessionHeader(id: SessionId, source?: SessionHeader): SessionHeader {
+  const input: SessionHeader = source === undefined
+    ? { version: SESSION_FORMAT_VERSION, id, createdAt: Date.now() }
+    : source
+  assertPlainRecord(input, 'session header')
+
+  // Capture each property once before validation. A stateful accessor therefore
+  // cannot present one identity or storage location to a check and publish a
+  // different one afterward.
+  const version = input.version
+  const headerId = input.id
+  const createdAt = input.createdAt
+  const cwd = input.cwd
+  const parentSession = input.parentSession
+  const seedLength = input.seedLength
+  const accepted = {
+    version,
+    id: headerId,
+    createdAt,
+    ...cwd !== undefined ? { cwd } : {},
+    ...parentSession !== undefined ? { parentSession } : {},
+    ...seedLength !== undefined ? { seedLength } : {},
+  }
+  const snapshot = snapshotJsonValue(accepted)
+  if (snapshot === undefined) throw new Error('session header is not losslessly JSON-serializable')
+  if (snapshot.version !== SESSION_FORMAT_VERSION) {
+    throw new Error(`session header version must be ${SESSION_FORMAT_VERSION}, got ${String(snapshot.version)}`)
+  }
+  if (snapshot.id !== id) {
+    throw new Error(`session header id "${String(snapshot.id)}" does not match session id "${id}"`)
+  }
+  if (typeof snapshot.createdAt !== 'number' || !Number.isFinite(snapshot.createdAt)) {
+    throw new Error('session header createdAt must be a finite number')
+  }
+  if (snapshot.cwd !== undefined) {
+    if (typeof snapshot.cwd !== 'string') throw new Error('session header cwd must be a string')
+    if (!isAbsolute(snapshot.cwd)) {
+      throw new Error(`session header cwd must be an absolute path, got "${snapshot.cwd}"`)
+    }
+  }
+  if (snapshot.parentSession !== undefined && typeof snapshot.parentSession !== 'string') {
+    throw new Error('session header parentSession must be a string')
+  }
+  if (snapshot.seedLength !== undefined
+    && (typeof snapshot.seedLength !== 'number' || !Number.isSafeInteger(snapshot.seedLength) || snapshot.seedLength < 0)) {
+    throw new Error('session header seedLength must be a non-negative safe integer')
+  }
+  return deepFreeze(snapshot)
+}
+
+/** Validate the runtime shape of surface metadata after its JSON snapshot. */
+function assertSurfaceMetadataShape(
+  type: string,
+  surfaceOp: unknown,
+  sourceEventSeqs: unknown,
+): void {
+  const eligible = isSurfaceEligibleType(type)
+  if (!eligible) {
+    if (surfaceOp !== undefined || sourceEventSeqs !== undefined) {
+      throw new Error(`session event "${type}" is not surface-eligible and cannot carry surface metadata`)
+    }
+    return
+  }
+  if (surfaceOp === undefined) {
+    throw new Error(`session event "${type}" is surface-eligible and requires a surfaceOp marker`)
+  }
+  if (surfaceOp !== 'append') {
+    if (surfaceOp === null || typeof surfaceOp !== 'object' || Array.isArray(surfaceOp)) {
+      throw new Error(`session event "${type}" carries an invalid surfaceOp`)
+    }
+    const op = surfaceOp as Record<string, unknown>
+    const keys = Object.keys(op)
+    if (keys.length !== 3 || !Object.hasOwn(op, 'op') || !Object.hasOwn(op, 'start') || !Object.hasOwn(op, 'end')
+      || op['op'] !== 'replace'
+      || typeof op['start'] !== 'number' || !Number.isSafeInteger(op['start']) || op['start'] < 0
+      || typeof op['end'] !== 'number' || !Number.isSafeInteger(op['end']) || op['end'] < 0) {
+      throw new Error(`session event "${type}" carries an invalid replace surfaceOp`)
+    }
+  }
+  if (sourceEventSeqs !== undefined) {
+    if (!Array.isArray(sourceEventSeqs)
+      || sourceEventSeqs.some(seq => typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 0)) {
+      throw new Error(`session event "${type}" sourceEventSeqs must contain non-negative safe integers`)
+    }
+  }
+}
+
+/** Validate the fixed event envelope after one-pass JSON materialization. */
+function assertSessionEventEnvelope(value: Record<string, unknown>, index: number): asserts value is SessionEvent {
+  const event = value
+  const allowed = new Set(['type', 'seq', 'time', 'data', 'surfaceOp', 'sourceEventSeqs'])
+  if (Object.keys(event).some(key => !allowed.has(key))
+    || !Object.hasOwn(event, 'type') || typeof event['type'] !== 'string'
+    || !Object.hasOwn(event, 'seq') || typeof event['seq'] !== 'number'
+    || !Number.isSafeInteger(event['seq']) || event['seq'] < 0
+    || !Object.hasOwn(event, 'time') || typeof event['time'] !== 'number'
+    || !Number.isSafeInteger(event['time']) || event['time'] < 0
+    || !Object.hasOwn(event, 'data')) {
+    throw new Error(`seed event at index ${index} has an invalid event envelope`)
+  }
+}
+
 /**
  * An event-sourced session: an append-only log of {@link SessionEvent}s.
  *
@@ -126,10 +280,10 @@ export class Session {
   }
 
   /**
-   * Immutable creation metadata (format version, cwd, lineage, seed boundary).
-   * Supplied by the store via `ctx.sessions.create()`. When a `Session` is
-   * constructed bare (tests, ad-hoc replay), a minimal header is synthesized
-   * (stamped with the current {@link SESSION_FORMAT_VERSION}) so
+   * Detached, deep-frozen creation metadata (format version, cwd, lineage,
+   * seed boundary). Supplied by the store via `ctx.sessions.create()`. When a
+   * `Session` is constructed bare (tests, ad-hoc replay), a minimal header is
+   * synthesized (stamped with the current {@link SESSION_FORMAT_VERSION}) so
    * `session.header` is always present. Kept out of the event log — it is a
    * storage concern, not replayable conversation state.
    */
@@ -144,12 +298,27 @@ export class Session {
       // `seq = log.length` contract the whole system relies on). Without this,
       // a bad seed would surface only later as a backend rejection or a silent
       // divergence between the live log and disk.
-      seed.forEach((event, index) => {
-        if (event.seq !== index) {
-          throw new Error(`seed event at index ${index} has seq ${event.seq} (expected ${index}); seed must be contiguous from 0`)
+      this.log = Array.from(seed, (source, index) => {
+        // Spreading would erase a class instance's prototype. Reject an exotic
+        // event shell before that normalization can turn it into an apparently
+        // valid plain record; field values are still captured by the one spread
+        // below, so their accessors are not read twice.
+        assertPlainRecord(source, `seed event at index ${index}`)
+        // Read every enumerable event field once. Validation and snapshot
+        // construction must consume this same captured record: a stateful seed
+        // index or event getter cannot present one record to the checks and
+        // another to the durable log.
+        const event = { ...source }
+        // Materialize the complete accepted record in one recursive pass. A
+        // validate-then-structuredClone sequence would reread nested getters and
+        // could sanitize a class instance returned only to the clone.
+        const snapshot = snapshotJsonValue(event)
+        if (snapshot === undefined) {
+          throw new Error(`seed event at index ${index} is not losslessly JSON-serializable`)
         }
-        if (!isJsonValue(event.data)) {
-          throw new Error(`seed event "${event.type}" (seq ${event.seq}) carries non-JSON-serializable data`)
+        assertSessionEventEnvelope(snapshot, index)
+        if (snapshot.seq !== index) {
+          throw new Error(`seed event at index ${index} has seq ${snapshot.seq} (expected ${index}); seed must be contiguous from 0`)
         }
         // Surface-eligible events MUST carry a surfaceOp marker — the surface is
         // the sole source of derived history, so a marker-less message event
@@ -157,30 +326,30 @@ export class Session {
         // this at compile time via its typed overload; a seed arrives as raw
         // SessionEvent[] (replay/fork/load), bypassing that, so re-check at
         // runtime here rather than silently resuming with empty history.
-        if (isSurfaceEligibleType(event.type)
-          && (event as SessionEvent<SurfaceEventType>).surfaceOp === undefined) {
-          throw new Error(`seed event "${event.type}" (seq ${event.seq}) is surface-eligible but carries no surfaceOp marker`)
+        const structural = snapshot as SessionEvent & { surfaceOp?: unknown; sourceEventSeqs?: unknown }
+        try {
+          assertSurfaceMetadataShape(snapshot.type, structural.surfaceOp, structural.sourceEventSeqs)
+        } catch (error: unknown) {
+          throw new Error(`invalid seed event at index ${index}: ${error instanceof Error ? error.message : 'invalid surface metadata'}`)
         }
+        return deepFreeze(snapshot)
       })
-      // Deep-clone each seed event, NOT just the array: the seed events and
-      // their `data` are still owned by the caller (or the source session of a
-      // fork), so keeping the references would let a post-create mutation of the
-      // original rewrite this session's durable log — or reintroduce a
-      // non-JSON-serializable value AFTER the validation above. Snapshotting at
-      // the boundary makes `session.events` independent and keeps it equal to
-      // what was validated. Serializability is guaranteed by the check above, so
-      // structuredClone can never hit a non-cloneable value here.
-      this.log = seed.map(event => structuredClone(event))
     }
-    this.header = header ?? { version: SESSION_FORMAT_VERSION, id, createdAt: Date.now() }
+    this.header = snapshotSessionHeader(id, header)
   }
 
+  /** Cached immutable public snapshot of the private append-only log. */
+  private eventsSnapshot: readonly SessionEvent[] | undefined
+
   /**
-   * The append-only event log, exposed live by reference (readonly-typed, not
-   * a snapshot): later appends are visible through the same array.
+   * An immutable snapshot of the append-only event log. The snapshot is reused
+   * until the next append; a previously returned array does not grow later.
+   * Events and their nested data are deep-frozen at acceptance, so neither a
+   * cast nor ordinary JavaScript can rewrite durable history.
    */
   get events(): readonly SessionEvent[] {
-    return this.log
+    this.eventsSnapshot ??= Object.freeze([...this.log])
+    return this.eventsSnapshot
   }
 
   /** The next event's sequence number — always the log length (the `seq = log.length` contiguity contract). */
@@ -205,23 +374,27 @@ export class Session {
    * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of
    *   `data` that entered the log, so reading `event.data` back sees the logged
    *   value, never the caller's still-mutable input.
-   * @throws if `data` is not losslessly JSON-serializable (BigInt, function,
-   *   symbol, undefined, non-finite number, circular ref, or an exotic object
-   *   like Map/Set/Date). The event log is the durable source of truth, so this
-   *   invariant is enforced at the source — a bad event never enters the log,
-   *   keeping `session.events` always equal to what a backend can persist. The
-   *   throw surfaces at the buggy caller's append site, not asynchronously in a
-   *   backend flush.
+   * @throws if `type` is not a string, or if `data` or surface metadata is not
+   *   losslessly JSON-serializable
+   *   (BigInt, function, symbol, undefined, negative zero, non-finite number,
+   *   circular reference, sparse array, or an exotic object such as
+   *   Map/Set/Date/class instance). One recursive pass reads, validates, and
+   *   copies each nested value once, so a stateful getter cannot supply one value
+   *   to validation and another to storage. The event log is the durable source
+   *   of truth, so a bad event fails at the append site rather than later during
+   *   a backend flush.
    */
   append<T extends SessionEventType>(
     type: T,
     data: SessionEventMap[T],
     ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : []
   ): SessionEvent<T> {
-    if (!isJsonValue(data)) {
-      throw new Error(`session event "${type}" carries non-JSON-serializable data`)
+    if (typeof type !== 'string') {
+      throw new TypeError('session event type must be a string')
     }
     const surfaceOpts: SurfaceIntent | undefined = opts[0]
+    const sourceEventSeqs = surfaceOpts?.sourceEventSeqs
+    const surfaceOp = surfaceOpts?.surfaceOp
     // Surface-eligible events MUST carry a surfaceOp marker — the surface is the
     // sole source of derived history, so a marker-less message event would be
     // logged yet vanish from deriveMessages(). The typed `opts` overload makes
@@ -230,41 +403,49 @@ export class Session {
     // events: `for (const e of log) append(e.type, e.data)`), the conditional
     // rest collapses to optional and the compiler stops enforcing it. Re-check
     // at runtime so that loophole can't silently drop history.
-    if (isSurfaceEligibleType(type) && surfaceOpts?.surfaceOp === undefined) {
-      throw new Error(`session event "${type}" is surface-eligible and requires a surfaceOp marker`)
+    const surfaceMetadata = {
+      ...sourceEventSeqs !== undefined ? { sourceEventSeqs } : {},
+      ...surfaceOp !== undefined ? { surfaceOp } : {},
     }
-    // Snapshot `data` into the log, NOT the caller's reference: the validation
-    // above proves it is JSON-serializable AT THIS MOMENT, but the caller still
-    // owns the object and could mutate it afterwards (before a persistence
-    // flush, or permanently in the in-memory history) — making `session.events`
-    // diverge from the value that passed validation, or reintroducing a
-    // non-serializable value. Cloning here keeps the log equal to what was
-    // validated. structuredClone is safe because serializability was just
-    // checked. The returned event carries the SAME snapshot, so a caller reading
-    // back `event.data` sees the logged value, not its own mutable input.
+    // The caller still owns the data and metadata objects and could mutate them
+    // after append. Materialize each accepted value exactly once while checking
+    // its JSON vocabulary, so the log cannot drift and a stateful getter cannot
+    // show one value to validation and another to a prototype-erasing clone. The
+    // returned event carries these SAME snapshots.
     //
-    // Surface metadata is snapshot separately: sourceEventSeqs (number[] —
-    // primitives, so array spread is a complete copy) and surfaceOp (a string
-    // primitive, or cloned if it's a replace object).
+    // Surface metadata accessors are read once into one plain record; the
+    // recursive snapshot then reads each nested value once as it copies it.
     // Build the event shape with conditional surface fields via spreading.
     // The result is cast through `unknown` because the conditional spreads
     // produce an intersection type that the assignability checker can't
     // narrow to a specific discriminated-union member when T is generic.
-    // This is a safe internal boundary: data was validated above, and
-    // surface metadata was snapshot from primitive/clone-safe values.
+    // This is a safe internal boundary: data and surface metadata are
+    // materialized below before the event enters the log.
+    const dataSnapshot = snapshotJsonValue(data)
+    if (dataSnapshot === undefined) {
+      throw new Error(`session event "${type}" carries non-JSON-serializable data`)
+    }
+    const surfaceMetadataSnapshot = snapshotJsonValue(surfaceMetadata)
+    if (surfaceMetadataSnapshot === undefined) {
+      throw new Error(`session event "${type}" carries non-JSON-serializable surface metadata`)
+    }
+    assertSurfaceMetadataShape(
+      type,
+      (surfaceMetadataSnapshot as { surfaceOp?: unknown }).surfaceOp,
+      (surfaceMetadataSnapshot as { sourceEventSeqs?: unknown }).sourceEventSeqs,
+    )
     const event = {
       type,
       seq: this.log.length,
       time: Date.now(),
-      data: structuredClone(data),
-      ...surfaceOpts?.sourceEventSeqs !== undefined ? { sourceEventSeqs: [...surfaceOpts.sourceEventSeqs] } : {},
-      ...surfaceOpts?.surfaceOp !== undefined ? {
-        surfaceOp: typeof surfaceOpts.surfaceOp === 'string' ? surfaceOpts.surfaceOp : structuredClone(surfaceOpts.surfaceOp),
-      } : {},
+      data: dataSnapshot,
+      ...surfaceMetadataSnapshot,
     } as unknown as SessionEvent<T>
-    this.log.push(event as unknown as SessionEvent)
-    this.onAppend?.(event as unknown as SessionEvent)
-    return event
+    const acceptedEvent = deepFreeze(event)
+    this.log.push(acceptedEvent as unknown as SessionEvent)
+    this.eventsSnapshot = undefined
+    this.onAppend?.(acceptedEvent as unknown as SessionEvent)
+    return acceptedEvent
   }
 
   /** Cached fold of the request-header events — see {@link requestHeader}. */
@@ -457,7 +638,8 @@ export class SessionStore extends Service {
    * @param id - the session id; omitted, the store mints `session-<n>`.
    * @param options - seed events and/or creation metadata for the header.
    * @returns the live session, already entered and announced.
-   * @throws if a session with `id` already exists, or if `meta.cwd` is a
+   * @throws if a session with `id` already exists, metadata is not a plain
+   *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
    *   non-absolute path (storage backends key directories off it).
    */
   create(id?: SessionId, options?: CreateSessionOptions): Session {
@@ -485,25 +667,27 @@ export class SessionStore extends Service {
    * @param id - the session id; omitted, the store mints `session-<n>`.
    * @param options - seed events and/or creation metadata for the header.
    * @returns the constructed session, NOT yet in the store.
-   * @throws if a session with `id` already exists, or if `meta.cwd` is a
+   * @throws if a session with `id` already exists, metadata is not a plain
+   *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
    *   non-absolute path.
    */
   prepare(id?: SessionId, options?: CreateSessionOptions): Session {
     const sessionId = SessionId(id ?? `session-${++this.counter}`)
     if (this.store.has(sessionId)) throw new Error(`session "${sessionId}" already exists`)
-    const cwd = options?.meta?.cwd
-    if (cwd !== undefined && !isAbsolute(cwd)) {
-      throw new Error(`session cwd must be an absolute path, got "${cwd}"`)
-    }
+    const seed = options?.seed
+    const meta = snapshotSessionMeta(options?.meta)
+    const cwd = meta.cwd
+    const parentSession = meta.parentSession
+    const seedLength = meta.seedLength
     const header: SessionHeader = {
       version: SESSION_FORMAT_VERSION,
       id: sessionId,
-      createdAt: options?.meta?.createdAt ?? Date.now(),
+      createdAt: meta.createdAt ?? Date.now(),
       ...cwd !== undefined ? { cwd } : {},
-      ...options?.meta?.parentSession !== undefined ? { parentSession: options.meta.parentSession } : {},
-      ...options?.meta?.seedLength !== undefined ? { seedLength: options.meta.seedLength } : {},
+      ...parentSession !== undefined ? { parentSession } : {},
+      ...seedLength !== undefined ? { seedLength } : {},
     }
-    return new Session(sessionId, options?.seed, header)
+    return new Session(sessionId, seed, header)
   }
 
   /**

packages/core/session/src/json.ts

@@ -1,45 +1,127 @@
 /**
- * JSON-serializability validation for session event data.
+ * Lossless-JSON validation and snapshot materialization for session data.
  *
  * The session event log is the durable source of truth (the event-sourcing / session-persistence RFCs): every
  * `event.data` must round-trip losslessly through JSON so any persistence
  * backend can store and reload it byte-identically. This invariant belongs to
  * the log itself — `Session.append` enforces it at the source, so a
  * non-serializable event never enters `session.events` and the live log can
- * never diverge from what a backend can persist. Backends re-use the same
- * predicate to validate their own `append(events)` entry point (replay/fork
- * paths that do not go through a live `Session`).
+ * never diverge from what a backend can persist. Other public boundaries use
+ * {@link snapshotJsonValue} when they must validate and detach in one pass;
+ * {@link isJsonValue} remains the non-copying structural predicate.
  *
  * @module @deepseek-ai/dsh-session/json
  */
 
 /**
  * A value that round-trips losslessly through JSON: `null`, a boolean, a finite
- * number, a string, an array of such values, or a plain object whose values are
- * such values. The static type companion to {@link isJsonValue} (which validates
- * the same shape at runtime). Use it to type a payload that must survive
- * session-log persistence and replay byte-identically — e.g. a tool's private
- * presentation `meta`.
+ * number other than negative zero, a string, an array of such values, or a
+ * plain object whose values are such values. TypeScript cannot distinguish
+ * `-0` from `number`, so {@link isJsonValue} and {@link snapshotJsonValue}
+ * enforce that last numeric detail at runtime. Use this type for a payload that
+ * must survive session-log persistence and replay byte-identically — e.g. a
+ * tool's private presentation `meta`.
  */
 export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
 
 /**
- * Whether `value` is losslessly JSON-serializable: only `null`, finite numbers,
- * booleans, strings, plain arrays, and plain objects of such values. Rejects
- * `BigInt`, function, symbol, `undefined`, non-finite numbers (`NaN`/`Infinity`,
- * which `JSON.stringify` turns into `null`), and exotic objects (`Map`/`Set`/
- * `Date`/class instances) — anything `JSON.stringify` would drop, throw on, or
- * convert lossily. Sparse arrays are rejected too: a hole serializes to `null`,
- * so `[1, , 3]` would not round-trip. Detects circular references (which would
- * throw) and reports them as non-serializable rather than propagating the throw.
+ * Materialize one detached lossless-JSON snapshot in a SINGLE recursive pass.
+ * Each array slot or own enumerable string-keyed object value is read exactly
+ * once, validated, and copied immediately. This is intentionally not
+ * `isJsonValue(value)` followed by `structuredClone(value)`: a stateful getter
+ * could return plain JSON to the check and an exotic class instance to the
+ * clone, whose prototype `structuredClone` would erase before a later check.
  *
- * Scope — matches `JSON.stringify` exactly: only an object's OWN ENUMERABLE
- * STRING-keyed properties are inspected (`Object.values`). Symbol-keyed and
- * non-enumerable properties are NOT examined, because `JSON.stringify` likewise
- * drops them — they never reach the durable form, so a non-serializable value
- * hiding under a symbol/non-enumerable key cannot make the round-trip lossy.
- * Getters are invoked during the check (again as `JSON.stringify` would), so the
- * contract is for plain data records, not objects with side-effecting accessors.
+ * Accepts the same scalar/object vocabulary as {@link isJsonValue}: arrays use
+ * the ordinary `Array.prototype` (subclass instances are not plain JSON
+ * containers), while null-prototype objects are accepted and normalized to
+ * ordinary plain objects. Sparse arrays, cycles, negative zero, non-finite
+ * numbers, unsupported scalar types, and exotic object or array shells return
+ * `undefined`. A throwing getter is a caller failure and propagates unchanged.
+ *
+ * @param value - the candidate value to validate and detach.
+ * @returns the detached snapshot, or `undefined` when the value is not
+ *   losslessly JSON-serializable.
+ */
+export function snapshotJsonValue<T>(value: T): T | undefined {
+  const ancestors = new Set<object>()
+
+  const visit = (current: unknown): JsonValue | undefined => {
+    if (current === null) return null
+    switch (typeof current) {
+      case 'boolean':
+      case 'string':
+        return current
+      case 'number':
+        return Number.isFinite(current) && !Object.is(current, -0) ? current : undefined
+      case 'bigint':
+      case 'function':
+      case 'symbol':
+      case 'undefined':
+        return undefined
+      case 'object':
+        break
+    }
+
+    if (ancestors.has(current)) return undefined
+    ancestors.add(current)
+    try {
+      if (Array.isArray(current)) {
+        if (Object.getPrototypeOf(current) !== Array.prototype) return undefined
+        const length = current.length
+        const snapshot: JsonValue[] = []
+        for (let index = 0; index < length; index++) {
+          if (!Object.prototype.hasOwnProperty.call(current, index)) return undefined
+          const item = visit(current[index])
+          if (item === undefined) return undefined
+          snapshot.push(item)
+        }
+        return snapshot
+      }
+
+      const prototype = Object.getPrototypeOf(current) as unknown
+      if (prototype !== Object.prototype && prototype !== null) return undefined
+      const snapshot: { [key: string]: JsonValue } = {}
+      for (const key of Object.keys(current)) {
+        const item = visit((current as Record<string, unknown>)[key])
+        if (item === undefined) return undefined
+        // Define the key as data so a JSON field literally named "__proto__"
+        // cannot mutate the snapshot's prototype through ordinary assignment.
+        Object.defineProperty(snapshot, key, {
+          value: item,
+          enumerable: true,
+          configurable: true,
+          writable: true,
+        })
+      }
+      return snapshot
+    } finally {
+      ancestors.delete(current)
+    }
+  }
+
+  return visit(value) as T | undefined
+}
+
+/**
+ * Whether `value` is losslessly JSON-serializable: only `null`, finite numbers
+ * other than negative zero, booleans, strings, plain arrays, and plain objects
+ * of such values. Rejects `BigInt`, function, symbol, `undefined`, `-0` (which
+ * JSON rewrites to `0`), non-finite numbers (`NaN`/`Infinity`, which JSON turns
+ * into `null`), and exotic objects (`Map`/`Set`/`Date`/class instances) —
+ * anything `JSON.stringify` would drop, throw on, or convert lossily. Sparse
+ * arrays are rejected too: a hole serializes to `null`, so `[1, , 3]` would not
+ * round-trip. Detects circular references (which would throw) and reports them
+ * as non-serializable rather than propagating the throw.
+ *
+ * Scope — this is a structural plain-data predicate, not an invocation of
+ * `JSON.stringify`: only an object's OWN ENUMERABLE STRING-keyed properties are
+ * inspected (`Object.values`). Symbol-keyed and non-enumerable properties are
+ * omitted from the durable data surface. Custom `toJSON` behavior is not
+ * executed; boundaries that persist a value first materialize a new plain-data
+ * record with {@link snapshotJsonValue}. Getters are invoked during this check,
+ * so callers that need a stable detached value use that one-pass materializer
+ * instead of checking and then rereading a side-effecting record.
  * @param value - the candidate event data to test.
  * @param seen - objects on the current descent path, for circular-reference
  *   detection; the recursion threads it — callers omit it.
@@ -52,7 +134,7 @@ export function isJsonValue(value: unknown, seen: Set<object> = new Set()): bool
     case 'string':
       return true
     case 'number':
-      return Number.isFinite(value)
+      return Number.isFinite(value) && !Object.is(value, -0)
     case 'bigint':
     case 'function':
     case 'symbol':
@@ -66,6 +148,7 @@ export function isJsonValue(value: unknown, seen: Set<object> = new Set()): bool
   seen.add(value)
   try {
     if (Array.isArray(value)) {
+      if (Object.getPrototypeOf(value) !== Array.prototype) return false
       // Reject sparse arrays: a hole is skipped by `every`/`forEach` but
       // JSON.stringify writes it as `null`, so `[1, , 3]` would round-trip
       // lossily. Require every index 0..length-1 to be an OWN property.

packages/core/session/src/types.ts

@@ -32,6 +32,9 @@ export const SESSION_FORMAT_VERSION = 0
 
 /**
  * Immutable session metadata — written once at creation and never rewritten.
+ * {@link Session} enforces that contract at runtime: it validates and detaches
+ * the accepted scalar fields, requires this header's id to match the session
+ * id, and deep-freezes the published record.
  *
  * Kept SEPARATE from the event log deliberately: format-version, cwd, and
  * lineage are storage concerns, not conversation events, so they stay out of
@@ -75,7 +78,8 @@ export interface CreateSessionOptions {
   /** Events to seed the new session with (replay/fork). */
   seed?: SessionEvent[]
   /**
-   * Creation metadata. The store fills in `version`/`id` and defaults
+   * Creation metadata. The store reads this plain record and each accepted
+   * field once, then fills in `version`/`id` and defaults
    * `createdAt` to now; the caller supplies the storage-level fields (validated
    * absolute `cwd`, `parentSession` lineage, the seed boundary `seedLength`, and
    * — when reconstructing a persisted session — the original `createdAt` to

packages/core/session/tests/fork.spec.ts

@@ -60,7 +60,7 @@ describe('SessionStore.fork', () => {
     })
   })
 
-  it('forks the latest completed boundary by default and deep-clones seed events', async () => {
+  it('forks the latest completed boundary by default into detached frozen seed events', async () => {
     const { ctx, sessions } = await setup()
     const source = ctx.sessions.create(SessionId('parent'), { meta: { cwd: '/workspace' } })
     appendClosedTurn(source, 1, 'hello')
@@ -70,8 +70,11 @@ describe('SessionStore.fork', () => {
     expect(child.events).toEqual(source.events)
     expect(child.events).not.toBe(source.events)
     expect(child.events[1]).not.toBe(source.events[1])
-    firstUserMessage(child.events).data.content[0] = { type: 'text', text: 'child mutation' }
+    expect(() => {
+      firstUserMessage(child.events).data.content[0] = { type: 'text', text: 'child mutation' }
+    }).toThrow(TypeError)
     expect(firstUserMessage(source.events).data.content).toEqual([{ type: 'text', text: 'hello' }])
+    expect(firstUserMessage(child.events).data.content).toEqual([{ type: 'text', text: 'hello' }])
     expect(child.header).toMatchObject({
       id: SessionId('child'),
       cwd: '/workspace',

packages/core/session/tests/json.spec.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest'
+import { isJsonValue, snapshotJsonValue } from '@deepseek-ai/dsh-session'
+
+describe('snapshotJsonValue', () => {
+  it('copies the complete JSON scalar vocabulary and rejects unsupported scalars', () => {
+    const unsupportedFunction = (): void => {}
+
+    expect(snapshotJsonValue(null)).toBeNull()
+    expect(snapshotJsonValue(true)).toBe(true)
+    expect(snapshotJsonValue('text')).toBe('text')
+    expect(snapshotJsonValue(1.25)).toBe(1.25)
+    expect(snapshotJsonValue(-0)).toBeUndefined()
+    expect(isJsonValue(-0)).toBe(false)
+    expect(snapshotJsonValue(Number.NaN)).toBeUndefined()
+    expect(snapshotJsonValue(Number.POSITIVE_INFINITY)).toBeUndefined()
+    expect(snapshotJsonValue(1n)).toBeUndefined()
+    expect(snapshotJsonValue(unsupportedFunction)).toBeUndefined()
+    expect(snapshotJsonValue(Symbol('value'))).toBeUndefined()
+    const unsupportedUndefined: unknown = undefined
+    expect(snapshotJsonValue(unsupportedUndefined)).toBeUndefined()
+  })
+
+  it('recursively detaches dense arrays and plain or null-prototype objects', () => {
+    const shared = { value: 1 }
+    const nullPrototype = Object.assign(Object.create(null) as Record<string, unknown>, { shared })
+    const source = { list: [nullPrototype, shared], alias: shared }
+
+    const snapshot = snapshotJsonValue(source)!
+    shared.value = 2
+
+    expect(snapshot).toEqual({ list: [{ shared: { value: 1 } }, { value: 1 }], alias: { value: 1 } })
+    expect(snapshot).not.toBe(source)
+    expect(snapshot.list).not.toBe(source.list)
+    expect(snapshot.alias).not.toBe(shared)
+    expect(snapshot.list[0]).not.toBe(nullPrototype)
+    expect(Object.getPrototypeOf(snapshot.list[0])).toBe(Object.prototype)
+  })
+
+  it('reads each object value and array slot once while materializing', () => {
+    class Exotic {
+      readonly accepted = false
+    }
+    let objectReads = 0
+    let arrayReads = 0
+    const nested = Object.defineProperty({}, 'value', {
+      enumerable: true,
+      get: () => {
+        objectReads += 1
+        return objectReads === 1 ? { accepted: true } : new Exotic()
+      },
+    })
+    const array = new Array<unknown>(1)
+    Object.defineProperty(array, 0, {
+      enumerable: true,
+      get: () => {
+        arrayReads += 1
+        return arrayReads === 1 ? nested : new Exotic()
+      },
+    })
+
+    expect(snapshotJsonValue(array)).toEqual([{ value: { accepted: true } }])
+    expect(objectReads).toBe(1)
+    expect(arrayReads).toBe(1)
+  })
+
+  it('rejects exotic containers, sparse arrays, cycles, and invalid children', () => {
+    class ExoticObject {
+      readonly value = 1
+    }
+    class ExoticArray extends Array<number> {}
+    const sparse = new Array<number>(1)
+    const cyclic: Record<string, unknown> = {}
+    cyclic.self = cyclic
+
+    expect(snapshotJsonValue(new ExoticObject())).toBeUndefined()
+    expect(snapshotJsonValue(new Map([['value', 1]]))).toBeUndefined()
+    expect(snapshotJsonValue(new ExoticArray(1))).toBeUndefined()
+    expect(snapshotJsonValue(sparse)).toBeUndefined()
+    expect(snapshotJsonValue(cyclic)).toBeUndefined()
+    expect(snapshotJsonValue([undefined])).toBeUndefined()
+    expect(snapshotJsonValue({ value: undefined })).toBeUndefined()
+  })
+
+  it('preserves a literal __proto__ JSON key without changing the snapshot prototype', () => {
+    const source = Object.create(null) as Record<string, unknown>
+    source.__proto__ = { safe: true }
+
+    const snapshot = snapshotJsonValue(source)!
+
+    expect(Object.getPrototypeOf(snapshot)).toBe(Object.prototype)
+    expect(Object.prototype.hasOwnProperty.call(snapshot, '__proto__')).toBe(true)
+    expect(snapshot.__proto__).toEqual({ safe: true })
+  })
+
+  it('propagates a throwing getter after reading it once', () => {
+    const failure = new Error('getter failed')
+    let reads = 0
+    const source = Object.defineProperty({}, 'value', {
+      enumerable: true,
+      get: () => {
+        reads += 1
+        throw failure
+      },
+    })
+
+    expect(() => snapshotJsonValue(source)).toThrow(failure)
+    expect(reads).toBe(1)
+  })
+})
+
+describe('isJsonValue', () => {
+  it('recognizes supported scalars and rejects every lossy scalar case', () => {
+    const unsupportedFunction = (): void => {}
+    const unsupportedUndefined: unknown = undefined
+
+    expect(isJsonValue(null)).toBe(true)
+    expect(isJsonValue(false)).toBe(true)
+    expect(isJsonValue('text')).toBe(true)
+    expect(isJsonValue(1.25)).toBe(true)
+    expect(isJsonValue(-0)).toBe(false)
+    expect(isJsonValue(Number.NaN)).toBe(false)
+    expect(isJsonValue(1n)).toBe(false)
+    expect(isJsonValue(unsupportedFunction)).toBe(false)
+    expect(isJsonValue(Symbol('value'))).toBe(false)
+    expect(isJsonValue(unsupportedUndefined)).toBe(false)
+  })
+
+  it('accepts dense arrays and plain objects, including null-prototype records', () => {
+    const nullPrototype = Object.assign(Object.create(null) as Record<string, unknown>, { value: true })
+
+    expect(isJsonValue([1, { nested: null }, nullPrototype])).toBe(true)
+    expect(isJsonValue({ value: [1, 2] })).toBe(true)
+    expect(isJsonValue(nullPrototype)).toBe(true)
+  })
+
+  it('rejects sparse arrays, invalid children, exotic objects, and cycles', () => {
+    class Exotic {
+      readonly value = 1
+    }
+    class ExoticArray extends Array<number> {}
+    const sparse = new Array<number>(1)
+    const cyclic: Record<string, unknown> = {}
+    cyclic.self = cyclic
+
+    expect(isJsonValue(sparse)).toBe(false)
+    expect(isJsonValue(new ExoticArray(1))).toBe(false)
+    expect(isJsonValue([undefined])).toBe(false)
+    expect(isJsonValue({ value: undefined })).toBe(false)
+    expect(isJsonValue(new Exotic())).toBe(false)
+    expect(isJsonValue(cyclic)).toBe(false)
+  })
+})

packages/core/session/tests/session.spec.ts

@@ -1,8 +1,8 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
-import type { SessionEventType, TodoItem } from '@deepseek-ai/dsh-session'
+import type { CreateSessionOptions, SessionEventType, SessionHeader, TodoItem } from '@deepseek-ai/dsh-session'
 
 describe('Session', () => {
   it('derives message history from the event log', () => {
@@ -129,6 +129,16 @@ describe('Session', () => {
     expect(session.events).toHaveLength(0)
   })
 
+  it('rejects a non-string event type without retaining or freezing caller data', () => {
+    const session = new Session(SessionId('invalid-event-type'))
+    const type = { tag: 'caller-owned' }
+    const appendRaw = session.append.bind(session) as unknown as (type: unknown, data: unknown) => SessionEvent
+
+    expect(() => appendRaw(type, {})).toThrow(/event type must be a string/)
+    expect(Object.isFrozen(type)).toBe(false)
+    expect(session.events).toEqual([])
+  })
+
   it('rejects a surface-eligible append with no surfaceOp marker (runtime guard for the union-widening loophole)', () => {
     const session = new Session(SessionId('s5b'))
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
@@ -156,7 +166,7 @@ describe('Session', () => {
     const badSeed = [
       { type: 'user/message' as const, seq: 0, time: 1, data: { content: [{ type: 'text' as const, text: 'x' }], source: { kind: 'user' as const }, bad: 1n } },
     ] as unknown as SessionEvent[]
-    expect(() => new Session(SessionId('seed-bad'), badSeed)).toThrow(/non-JSON-serializable/)
+    expect(() => new Session(SessionId('seed-bad'), badSeed)).toThrow(/losslessly JSON-serializable/)
   })
 
   it('validates seed events: rejects a non-contiguous seq', () => {
@@ -177,7 +187,7 @@ describe('Session', () => {
       { type: 'user/message' as const, seq: 1, time: 2, data: { content: [{ type: 'text' as const, text: 'hi' }], source: { kind: 'user' as const } } },
       { type: 'turn/end' as const, seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' as const } } },
     ] as SessionEvent[]
-    expect(() => new Session(SessionId('seed-no-marker'), markerlessSeed)).toThrow(/surface-eligible but carries no surfaceOp/)
+    expect(() => new Session(SessionId('seed-no-marker'), markerlessSeed)).toThrow(/requires a surfaceOp marker/)
   })
 
   it('accepts a well-formed contiguous serializable seed', () => {
@@ -190,6 +200,151 @@ describe('Session', () => {
     expect(session.events).toHaveLength(3)
   })
 
+  it('reads each seed array entry once so validation and storage use the same event', () => {
+    const accepted = {
+      type: 'turn/start' as const,
+      seq: 0,
+      time: 1,
+      data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } },
+    }
+    const drifted = { ...accepted, seq: 99, data: { invalid: 1n } }
+    let reads = 0
+    const seed = new Array<SessionEvent>(1)
+    Object.defineProperty(seed, 0, {
+      enumerable: true,
+      get: () => {
+        reads += 1
+        return reads === 1 ? accepted : drifted
+      },
+    })
+
+    const session = new Session(SessionId('seed-entry-snapshot'), seed)
+
+    expect(reads).toBe(1)
+    expect(session.events).toEqual([accepted])
+  })
+
+  it('reads a nested seed-data getter once and stores its first JSON value', () => {
+    let reads = 0
+    const data = Object.defineProperty({}, 'value', {
+      enumerable: true,
+      get: () => {
+        reads += 1
+        return reads === 1 ? 'accepted' : 1n
+      },
+    })
+    const seed = [{ type: 'test/unstable', seq: 0, time: 1, data }] as unknown as SessionEvent[]
+
+    const session = new Session(SessionId('seed-nested-drift'), seed)
+
+    expect(reads).toBe(1)
+    expect(session.events[0]!.data).toEqual({ value: 'accepted' })
+  })
+
+  it('rejects non-JSON surface metadata in a seed event', () => {
+    const seed = [{
+      type: 'user/message',
+      seq: 0,
+      time: 1,
+      data: { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } },
+      surfaceOp: { op: 'replace', start: 1n, end: 2 },
+    }] as unknown as SessionEvent[]
+
+    expect(() => new Session(SessionId('seed-bad-metadata'), seed))
+      .toThrow(/losslessly JSON-serializable/)
+  })
+
+  it('rejects exotic seed metadata before cloning can erase its prototype', () => {
+    class ReplaceOp {
+      readonly op = 'replace' as const
+      readonly start = 0
+      readonly end = 0
+    }
+    const seed = [{
+      type: 'user/message',
+      seq: 0,
+      time: 1,
+      data: { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } },
+      surfaceOp: new ReplaceOp(),
+    }] as unknown as SessionEvent[]
+
+    expect(() => new Session(SessionId('seed-exotic-metadata'), seed))
+      .toThrow(/losslessly JSON-serializable/)
+  })
+
+  it('rejects an exotic seed event shell before spreading erases its prototype', () => {
+    class SeedEvent {
+      readonly type = 'turn/start' as const
+      readonly seq = 0
+      readonly time = 1
+      readonly data = { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } }
+    }
+    const seed: SessionEvent[] = [new SeedEvent()]
+
+    expect(() => new Session(SessionId('seed-exotic-shell'), seed))
+      .toThrow(/not a plain JSON record/)
+  })
+
+  it('accepts a null-prototype seed event shell as a plain JSON record', () => {
+    const event = Object.assign(Object.create(null) as Record<string, unknown>, {
+      type: 'turn/start' as const,
+      seq: 0,
+      time: 1,
+      data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } },
+    }) as unknown as SessionEvent
+
+    const session = new Session(SessionId('seed-null-prototype'), [event])
+
+    expect(session.events).toEqual([{ ...event }])
+  })
+
+  it('reads a nested seed-metadata getter once and stores its first JSON value', () => {
+    let reads = 0
+    const surfaceOp = Object.defineProperty({ op: 'replace', end: 0 }, 'start', {
+      enumerable: true,
+      get: () => {
+        reads += 1
+        return reads === 1 ? 0 : 1n
+      },
+    })
+    const seed = [{
+      type: 'user/message',
+      seq: 0,
+      time: 1,
+      data: { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } },
+      surfaceOp,
+    }] as unknown as SessionEvent[]
+
+    const session = new Session(SessionId('seed-unstable-metadata'), seed)
+    const event = session.events[0]!
+    if (event.type !== 'user/message') throw new Error('test fixture must remain a user/message')
+
+    expect(reads).toBe(1)
+    expect(event.surfaceOp).toEqual({ op: 'replace', start: 0, end: 0 })
+  })
+
+  it('adds seed context when surface validation throws a non-Error value', () => {
+    const originalHasOwn = Object.hasOwn
+    const hasOwn = vi.spyOn(Object, 'hasOwn').mockImplementation((object: object, property: PropertyKey): boolean => {
+      if ((object as Record<string, unknown>)['op'] === 'replace') throw 'validator failed'
+      return originalHasOwn(object, property)
+    })
+    const seed = [{
+      type: 'user/message',
+      seq: 0,
+      time: 1,
+      data: { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } },
+      surfaceOp: { op: 'replace', start: 0, end: 0 },
+    }] as unknown as SessionEvent[]
+
+    try {
+      expect(() => new Session(SessionId('seed-non-error-metadata-failure'), seed))
+        .toThrow('invalid seed event at index 0: invalid surface metadata')
+    } finally {
+      hasOwn.mockRestore()
+    }
+  })
+
   it('snapshots the seed: mutating the original after construction does not affect session.events', () => {
     const seed = [
       { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
@@ -222,6 +377,304 @@ describe('Session', () => {
     // The returned event carries the same snapshot, not the caller's input.
     expect((event.data.content[0] as { text: string }).text).toBe('original')
   })
+
+  it('reads a nested append-data getter once and stores its first JSON value', () => {
+    const session = new Session(SessionId('append-nested-drift'))
+    let reads = 0
+    const data = Object.defineProperty({}, 'value', {
+      enumerable: true,
+      get: () => {
+        reads += 1
+        return reads === 1 ? 'accepted' : 1n
+      },
+    })
+
+    const event = session.append('todo/write', data as never)
+
+    expect(reads).toBe(1)
+    expect(event.data).toEqual({ value: 'accepted' })
+    expect(session.events).toEqual([event])
+  })
+
+  it('reads surface metadata accessors once so a validated marker is logged', () => {
+    const session = new Session(SessionId('surface-intent-snapshot'))
+    let reads = 0
+    const intent = {
+      get surfaceOp(): 'append' | undefined {
+        reads += 1
+        return reads === 1 ? 'append' : undefined
+      },
+    }
+
+    const event = session.append(
+      'user/message',
+      { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } },
+      intent as { surfaceOp: 'append' },
+    )
+
+    expect(reads).toBe(1)
+    expect(event.surfaceOp).toBe('append')
+  })
+
+  it('rejects non-JSON surface metadata before appending the event', () => {
+    const session = new Session(SessionId('append-bad-metadata'))
+
+    expect(() => session.append(
+      'user/message',
+      { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } },
+      { surfaceOp: { op: 'replace', start: 1n, end: 2 } } as never,
+    )).toThrow(/non-JSON-serializable surface metadata/)
+    expect(session.events).toEqual([])
+  })
+
+  it('rejects exotic surface metadata before cloning can erase its prototype', () => {
+    class ReplaceOp {
+      readonly op = 'replace' as const
+      readonly start = 0
+      readonly end = 0
+    }
+    const session = new Session(SessionId('append-exotic-metadata'))
+
+    expect(() => session.append(
+      'user/message',
+      { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } },
+      { surfaceOp: new ReplaceOp() },
+    )).toThrow(/non-JSON-serializable surface metadata/)
+    expect(session.events).toEqual([])
+  })
+
+  it('reads a nested append-metadata getter once and stores its first JSON value', () => {
+    const session = new Session(SessionId('append-unstable-metadata'))
+    let reads = 0
+    const surfaceOp = Object.defineProperty({ op: 'replace', end: 0 }, 'start', {
+      enumerable: true,
+      get: () => {
+        reads += 1
+        return reads === 1 ? 0 : 1n
+      },
+    })
+
+    const event = session.append(
+      'user/message',
+      { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } },
+      { surfaceOp } as never,
+    )
+
+    expect(reads).toBe(1)
+    expect(event.surfaceOp).toEqual({ op: 'replace', start: 0, end: 0 })
+    expect(session.events).toEqual([event])
+  })
+
+  it('rejects invalid plain surface metadata shapes at append', () => {
+    const session = new Session(SessionId('append-invalid-surface-shape'))
+    const appendRaw = session.append.bind(session) as unknown as (
+      type: SessionEventType,
+      data: unknown,
+      opts?: unknown,
+    ) => SessionEvent
+    const data = { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } }
+
+    expect(() => appendRaw('user/message', data, { surfaceOp: 'invalid' }))
+      .toThrow(/invalid surfaceOp/)
+    expect(() => appendRaw('user/message', data, {
+      surfaceOp: { op: 'replace', start: -1, end: 0 },
+    })).toThrow(/invalid replace surfaceOp/)
+    expect(() => appendRaw('user/message', data, {
+      surfaceOp: 'append',
+      sourceEventSeqs: [0, -1],
+    })).toThrow(/non-negative safe integers/)
+    expect(session.events).toEqual([])
+  })
+
+  it('rejects surface metadata on non-surface append and seed events', () => {
+    const session = new Session(SessionId('non-surface-metadata'))
+    const appendRaw = session.append.bind(session) as unknown as (
+      type: SessionEventType,
+      data: unknown,
+      opts?: unknown,
+    ) => SessionEvent
+
+    expect(() => appendRaw(
+      'turn/start',
+      { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+      { surfaceOp: 'append' },
+    )).toThrow(/not surface-eligible and cannot carry surface metadata/)
+    expect(() => new Session(SessionId('non-surface-metadata-seed'), [{
+      type: 'turn/start',
+      seq: 0,
+      time: 1,
+      data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+      surfaceOp: 'append',
+    } as unknown as SessionEvent])).toThrow(/invalid seed event.*not surface-eligible/)
+    expect(session.events).toEqual([])
+  })
+
+  it('deep-freezes seeded and appended event snapshots', () => {
+    const seeded = new Session(SessionId('seed-frozen'), [{
+      type: 'turn/start',
+      seq: 0,
+      time: 1,
+      data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+    }])
+    const seededEvent = seeded.events[0]!
+    if (seededEvent.type !== 'turn/start') throw new Error('test fixture must remain a turn/start')
+    expect(Object.isFrozen(seededEvent)).toBe(true)
+    expect(Object.isFrozen(seededEvent.data)).toBe(true)
+    expect(Object.isFrozen(seededEvent.data.trigger)).toBe(true)
+    expect(() => { seededEvent.data.turn = 99 }).toThrow(TypeError)
+
+    const appended = new Session(SessionId('append-frozen'))
+    const appendedEvent = appended.append('todo/write', {
+      todos: [{ content: 'first', status: 'pending' }],
+    })
+    expect(Object.isFrozen(appendedEvent)).toBe(true)
+    expect(Object.isFrozen(appendedEvent.data)).toBe(true)
+    expect(Object.isFrozen(appendedEvent.data.todos)).toBe(true)
+    expect(Object.isFrozen(appendedEvent.data.todos[0])).toBe(true)
+    expect(() => { appendedEvent.data.todos[0]!.content = 'mutated' }).toThrow(TypeError)
+  })
+
+  it('returns cached frozen event-array snapshots that do not grow after append', () => {
+    const session = new Session(SessionId('events-snapshot'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const before = session.events
+    const beforeEvent = before[0]!
+    if (beforeEvent.type !== 'turn/start') throw new Error('test fixture must remain a turn/start')
+
+    expect(session.events).toBe(before)
+    expect(Object.isFrozen(before)).toBe(true)
+    expect(() => { (before as SessionEvent[]).push(beforeEvent) }).toThrow(TypeError)
+    expect(() => { beforeEvent.data.turn = 99 }).toThrow(TypeError)
+
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    const after = session.events
+    expect(before).toHaveLength(1)
+    expect(after).toHaveLength(2)
+    expect(after).not.toBe(before)
+    expect(session.events).toBe(after)
+  })
+
+  it('detaches and freezes an explicitly supplied session header', () => {
+    const input = {
+      version: SESSION_FORMAT_VERSION,
+      id: SessionId('header-owned'),
+      createdAt: 123,
+      cwd: '/accepted',
+      parentSession: SessionId('parent'),
+      seedLength: 2,
+    }
+
+    const session = new Session(SessionId('header-owned'), undefined, input)
+    input.cwd = '/caller-mutated'
+
+    expect(session.header).toEqual({
+      version: SESSION_FORMAT_VERSION,
+      id: 'header-owned',
+      createdAt: 123,
+      cwd: '/accepted',
+      parentSession: 'parent',
+      seedLength: 2,
+    })
+    expect(session.header).not.toBe(input)
+    expect(Object.isFrozen(session.header)).toBe(true)
+    expect(Reflect.set(session.header, 'cwd', '/published-mutated')).toBe(false)
+    expect(session.header.cwd).toBe('/accepted')
+  })
+
+  it('reads each supplied header field once before validation and publication', () => {
+    const reads = { version: 0, id: 0, createdAt: 0, cwd: 0, parentSession: 0, seedLength: 0 }
+    const header = {
+      get version() { reads.version += 1; return reads.version === 1 ? SESSION_FORMAT_VERSION : 99 },
+      get id() { reads.id += 1; return reads.id === 1 ? SessionId('header-once') : SessionId('drifted') },
+      get createdAt() { reads.createdAt += 1; return reads.createdAt === 1 ? 123 : Number.NaN },
+      get cwd() { reads.cwd += 1; return reads.cwd === 1 ? '/accepted' : 'relative' },
+      get parentSession() { reads.parentSession += 1; return reads.parentSession === 1 ? SessionId('parent') : 1n },
+      get seedLength() { reads.seedLength += 1; return reads.seedLength === 1 ? 0 : 1n },
+    } as unknown as SessionHeader
+
+    const session = new Session(SessionId('header-once'), undefined, header)
+
+    expect(reads).toEqual({ version: 1, id: 1, createdAt: 1, cwd: 1, parentSession: 1, seedLength: 1 })
+    expect(session.header).toEqual({
+      version: SESSION_FORMAT_VERSION,
+      id: 'header-once',
+      createdAt: 123,
+      cwd: '/accepted',
+      parentSession: 'parent',
+      seedLength: 0,
+    })
+  })
+
+  it('rejects an exotic, non-JSON, or mismatched supplied header', () => {
+    class ExoticHeader implements SessionHeader {
+      readonly version = SESSION_FORMAT_VERSION
+      readonly id = SessionId('header-invalid')
+      readonly createdAt = 123
+    }
+
+    expect(() => new Session(SessionId('header-invalid'), undefined, new ExoticHeader()))
+      .toThrow(/not a plain JSON record/)
+    expect(() => new Session(SessionId('header-invalid'), undefined, {
+      version: SESSION_FORMAT_VERSION,
+      id: SessionId('header-invalid'),
+      createdAt: 123,
+      parentSession: 1n,
+    } as unknown as SessionHeader)).toThrow(/not losslessly JSON-serializable/)
+    expect(() => new Session(SessionId('header-invalid'), undefined, {
+      version: SESSION_FORMAT_VERSION,
+      id: SessionId('other'),
+      createdAt: 123,
+    })).toThrow(/does not match session id/)
+  })
+
+  it('rejects invalid scalar fields in an explicitly supplied header', () => {
+    const base = {
+      version: SESSION_FORMAT_VERSION,
+      id: SessionId('header-shape'),
+      createdAt: 123,
+    }
+    const cases: Array<{ header: unknown; error: RegExp }> = [
+      { header: 1, error: /not a plain JSON record/ },
+      { header: null, error: /not a plain JSON record/ },
+      { header: { ...base, version: 1 }, error: /header version/ },
+      { header: { ...base, createdAt: '123' }, error: /createdAt must be a finite number/ },
+      { header: { ...base, cwd: 1 }, error: /header cwd must be a string/ },
+      { header: { ...base, cwd: 'relative' }, error: /header cwd must be an absolute path/ },
+      { header: { ...base, parentSession: 1 }, error: /header parentSession must be a string/ },
+      { header: { ...base, seedLength: '1' }, error: /seedLength must be a non-negative safe integer/ },
+      { header: { ...base, seedLength: 0.5 }, error: /seedLength must be a non-negative safe integer/ },
+      { header: { ...base, seedLength: -1 }, error: /seedLength must be a non-negative safe integer/ },
+    ]
+
+    for (const { header, error } of cases) {
+      expect(() => new Session(SessionId('header-shape'), undefined, header as SessionHeader)).toThrow(error)
+    }
+  })
+
+  it('rejects seed records with invalid fixed-envelope fields', () => {
+    const base = {
+      type: 'turn/start',
+      seq: 0,
+      time: 1,
+      data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+    }
+    const cases: unknown[] = [
+      { ...base, extra: true },
+      { ...base, type: 1 },
+      { ...base, seq: '0' },
+      { ...base, seq: 0.5 },
+      { ...base, seq: -1 },
+      { ...base, time: '1' },
+      { ...base, time: 0.5 },
+      { ...base, time: -1 },
+      { type: base.type, seq: base.seq, time: base.time },
+    ]
+
+    for (const [index, event] of cases.entries()) {
+      expect(() => new Session(SessionId(`bad-envelope-${index}`), [event as SessionEvent]))
+        .toThrow(/invalid event envelope/)
+    }
+  })
 })
 
 
@@ -317,6 +770,66 @@ describe('SessionStore', () => {
     })
   })
 
+  it('reads session options and each metadata field once in prepare()', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const reads = { seed: 0, meta: 0, cwd: 0, parentSession: 0, createdAt: 0, seedLength: 0 }
+    const meta = {
+      get cwd() { reads.cwd += 1; return reads.cwd === 1 ? '/accepted' : 'relative' },
+      get parentSession() { reads.parentSession += 1; return reads.parentSession === 1 ? SessionId('parent') : 1n },
+      get createdAt() { reads.createdAt += 1; return reads.createdAt === 1 ? 123 : Number.NaN },
+      get seedLength() { reads.seedLength += 1; return reads.seedLength === 1 ? 0 : 1n },
+    }
+    const options = {
+      get seed() { reads.seed += 1; return reads.seed === 1 ? undefined : [] },
+      get meta() { reads.meta += 1; return reads.meta === 1 ? meta : undefined },
+    } as unknown as CreateSessionOptions
+
+    const session = ctx.sessions.prepare(SessionId('metadata-once'), options)
+
+    expect(reads).toEqual({ seed: 1, meta: 1, cwd: 1, parentSession: 1, createdAt: 1, seedLength: 1 })
+    expect(session.header).toEqual({
+      version: SESSION_FORMAT_VERSION,
+      id: 'metadata-once',
+      createdAt: 123,
+      cwd: '/accepted',
+      parentSession: 'parent',
+      seedLength: 0,
+    })
+  })
+
+  it('rejects exotic metadata before cloning can erase its prototype', async () => {
+    class ExoticMeta {
+      readonly cwd = '/accepted'
+    }
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+
+    expect(() => ctx.sessions.prepare(SessionId('exotic-meta'), { meta: new ExoticMeta() }))
+      .toThrow(/session metadata is not a plain JSON record/)
+  })
+
+  it('rejects non-JSON and invalid scalar session metadata', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const cases: Array<{ meta: unknown; error: RegExp }> = [
+      { meta: 1, error: /metadata is not a plain JSON record/ },
+      { meta: { parentSession: 1n }, error: /metadata is not losslessly JSON-serializable/ },
+      { meta: { cwd: 1 }, error: /session cwd must be a string/ },
+      { meta: { parentSession: 1 }, error: /parentSession must be a string/ },
+      { meta: { createdAt: '123' }, error: /createdAt must be a finite number/ },
+      { meta: { seedLength: '1' }, error: /seedLength must be a non-negative safe integer/ },
+      { meta: { seedLength: 0.5 }, error: /seedLength must be a non-negative safe integer/ },
+      { meta: { seedLength: -1 }, error: /seedLength must be a non-negative safe integer/ },
+    ]
+
+    for (const [index, { meta, error }] of cases.entries()) {
+      expect(() => ctx.sessions.prepare(SessionId(`bad-meta-${index}`), {
+        meta: meta as NonNullable<CreateSessionOptions['meta']>,
+      })).toThrow(error)
+    }
+  })
+
   it('rejects a non-absolute meta.cwd', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)