@sublang/playbook 17.11.1 → 18.0.1

package/docs/cli.md

@@ -321,20 +321,25 @@ Unsupported settings and ambiguous failures do not trigger that fallback
 
 ### Following replay history
 
-Beside each `<session-id>.json` manifest, both front ends tee every observed
-host record in order to `<session-id>.records.jsonl`. Each complete line is a
-version-1 envelope with a writer-assigned sequence contiguous from `1`, the
-opaque record, and an optional local playbook role where the trace establishes
-one unambiguously. The stream is a mode-`0600` regular non-symlink file inside
-the private sessions directory. Readers consume only the complete
-newline-terminated prefix; a final partial line is not presented as a record.
-
-Manifests use schema 7 and contain token-free recovery. The matching replay
-stream carries immutable configuration and graph records, so history does not
+Both front ends record observed host records in order through the shared store.
+New sessions use a small schema-8 `<session-id>.json` root, a
+`<session-id>.replay.json` root and immutable files in `<session-id>.chunks/`.
+Every generated root and chunk is at most 8 MiB. Equal content within a session
+is reused; one oversized record is split without discarding its contents.
+Use `readHistory()` or `readStream()` rather than opening a former
+`<session-id>.records.jsonl` file. Logical replay still contains version-1
+envelopes with contiguous writer-assigned sequences and optional local roles.
+
+The hydrated manifest remains logical schema 7 and contains token-free recovery.
+Replay carries immutable configuration and graph records, so history does not
 require installed modules. Provider continuation hints live separately in
 `<session-id>.hints.json` and stay local. A hint is consumed before use and
 accepted only for the exact checkpoint that created it.
 
+The file bound does not cap total disk usage or in-memory session size.
+Superseded chunks are retained for safe concurrent reads and recovery; they are
+removed with the session. This release does not automatically prune evidence.
+
 The manifest hashes its exact durable replay prefix. Missing or changed bytes,
 saved incompleteness, or unsupported required context block continuation while
 preserving readable history. A partial final line waits for completion; valid
@@ -346,7 +351,9 @@ history warning without authorizing a repeated action. Recovery and uncertainty
 remain durable; the incomplete marker persists across process restarts.
 Release retains the lease if that marker cannot be saved.
 
-Copy the manifest and matching replay together. Do not copy hints or leases.
+Copy the complete file inventory from `exportBundle().files`, including chunks
+and assets. Do not copy hints or leases, or serialize the hydrated manifest
+back into one large file.
 Continuation also requires matching working-directory/module paths and
 compatible runtimes; changed paths allow history only. Prompts, replies and
 tool content remain sensitive even after structured continuation fields have
@@ -354,18 +361,21 @@ been removed. See the [shared storage contract](https://github.com/sublang-ai/pl
 
 ### Migrating older sessions
 
-Stop old writers and snapshot Spex home and `${XDG_STATE_HOME:-$HOME/.local/state}/playbook` before upgrading.
-The ordinary default migrates known legacy formats into `~/.spex/sessions`, retaining history even when recovery is unavailable; explicit store overrides remain isolated.
+Stop every CLI and Spex writer sharing a store and snapshot its home before
+upgrading. Upgrade all hosts to the coordinated bounded-storage release before
+new writes. Earlier Playbook versions and direct file readers cannot use schema 8.
+When using the ordinary default, the CLI imports supported schema 2–6 sessions from the former `${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions` directory into `~/.spex/sessions`, retaining history even when recovery is unavailable. Explicit store overrides bypass this import; existing schema 7 sessions are not converted automatically.
 Migration retains original files under `local/migrations/` beside the destination sessions directory, validates the new bundle, then removes the former replay and manifest.
 Unknown or unsafe inputs stay in place with a diagnostic.
 
-For an explicitly configured store, migrate each selected legacy session before continuing it:
+For each selected monolithic session, including logical schema 7, run explicit
+migration before continuing it. Use the same configuration that selects its store:
 
 ```sh
 playbook migrate-session <id> [--with <path>]...
 ```
 
-Schema 6 may retain execution; older CLI records and desktop sidecars lacking complete recovery remain readable history.
+Schema 7 retains its validated logical recovery and exact replay; schema 6 may retain execution; older CLI records and desktop sidecars lacking complete recovery remain readable history.
 Discovery skips these histories and unmigrated records with a reason; they do not block other sessions.
 
 ### Reconciling possible repository effects

package/docs/embedding.md

@@ -201,7 +201,8 @@ remain isolated. Child return, frame disposal, and a later root engagement do
 not clear the session ledger.
 
 Runtime and complete shell snapshots are schema 4. The shared store projects
-provider continuations out of nested snapshots and writes schema-7 manifests.
+provider continuations out of nested snapshots and writes logical schema-7
+manifests inside bounded physical schema-8 roots.
 Local hints may rehydrate the current checkpoint; retained generations never
 restore provider tokens. Use the shared migrator for older records instead of
 guessing identity or effect evidence. On a compatible
@@ -472,7 +473,16 @@ only when `isUncertainTurnDiscardable(record)` returns true: no abandonment, no
 clearly marked synthetic projection when a validated legacy journal has no
 stream. `validate()` separates byte integrity from resumability.
 `readManifest()` may return an older or unknown object; use
-`validateSessionManifest()` before interpreting schema-7 recovery.
+`validateSessionManifest()` before interpreting logical schema-7 recovery.
+The store hydrates schema-8 roots transparently; do not parse the physical root
+as a recovery snapshot. `exportBundle().manifest` contains the exact physical
+root bytes, and `exportBundle().files` lists its verified portable file closure
+relative to `sessionsDir`. Copy that closure as one session unit. The
+`replay` result remains its checkpoint-proven logical prefix.
+
+Every new storage root and chunk is at most 8 MiB; total retained disk usage and
+hydrated memory are not capped. Stop all old writers and upgrade the CLI and
+embedded host together before creating new sessions or migrating old ones.
 `migrate()` preserves original inputs before conversion. `delete()` removes the
 bundle under the shared lease, with the manifest last. Management needs no
 playbook module. A coordination-only `acquireManagement()` lease reserves even

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.11.1",
+  "version": "18.0.1",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, PR, and INSPECT workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -92,6 +92,9 @@
     "reference/sdlc/code.playbook/bin/replay-observer.js",
     "reference/sdlc/code.playbook/bin/session-store.js",
     "reference/sdlc/code.playbook/bin/private-paths.js",
+    "reference/sdlc/code.playbook/bin/session-chunks.js",
+    "reference/sdlc/code.playbook/bin/session-replay.js",
+    "reference/sdlc/code.playbook/bin/storage-manifest.js",
     "reference/sdlc/code.playbook/bin/machine-identity.js",
     "reference/sdlc/code.playbook/bin/provision.js",
     "reference/sdlc/code.playbook/bin/adapter-sdk.js",
@@ -273,6 +276,7 @@
     "test:acceptance": "node scripts/run-live-acceptance.mjs",
     "smoke:release": "node scripts/release-smoke.mjs",
     "check:links": "node scripts/check-links.mjs",
+    "prepush": "bash scripts/prepush.sh",
     "playbook": "node reference/sdlc/code.playbook/bin/playbook.js"
   },
   "publishConfig": {
@@ -280,7 +284,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.36.0",
+    "@sublang/cligent": "^0.36.1",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

package/reference/sdlc/code.md

@@ -10,14 +10,14 @@ Roles:
 
 The caller supplies a coding request together with any relevant context.
 
-A new coding intent follows either one direct implementation phase or an IR sequence consisting of a new-IR phase followed by one phase for each IR task.
+A new change intent, including standalone documentation or status maintenance that does not implement an identified unfinished IR task, follows either one direct implementation phase or an IR sequence consisting of a new-IR phase followed by one phase for each IR task.
 An existing IR follows one IR-task phase for each remaining unfinished task, starting with its next unfinished task.
 Each completed phase ends with one new Coder commit (owned by `code`).
 After each `code`-owned commit, Captain shall call the `review` playbook and wait until it passes with no unsettled findings.
 Playbook `review` owns every review round and every review-fix commit.
 Do not rewrite any existing commit.
 
-When `review` passes a direct implementation phase, `code` is complete.
+When `review` passes a direct phase, `code` is complete.
 When `review` passes a new IR or a nonfinal IR-task phase, Captain shall continue with the next unfinished IR-task phase.
 When `review` passes the final IR-task phase, `code` is complete.
 When `review` returns an authored abort or failure, or a terminal result that does not establish that the supplied scope was evaluated with no unsettled findings, `code` shall start no further phase and shall report the failure and the last `code`-owned commit to its caller.
@@ -29,15 +29,18 @@ At the start of the first phase, Captain shall relay to Coder the complete calle
 > Run results: <run-results>
 
 ```markdown
-First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.
+First determine whether the request starts a new change intent or continues an existing IR with unfinished work.
 If the request may continue an existing IR but does not identify it unambiguously, ask Boss before changing files.
 
-For a new coding intent, assess whether it can be completed well in one commit.
+Treat standalone documentation or status maintenance that does not implement an identified unfinished IR task as a new change intent, even when it refers to an IR with no unfinished task.
+Do not invent or reopen an IR task, claim unperformed work complete, or infer an owner decision not supplied by the caller.
+
+For a new change intent, assess whether it can be completed well in one commit.
 If it can, implement and test it, update the affected specs, and ensure @specs/map.md remains accurate.
 If it cannot, decompose it into tasks sized to exactly one commit each, add a new IR under @specs/intents, and do not implement any IR task in this phase.
 Plan affected spec updates before, with, or after their corresponding code changes, either as standalone IR tasks or as explicit work within related tasks.
 
-For an existing IR, read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.
+For an existing IR with unfinished work, read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.
 Do not implement a later task in this phase.
 Mark the IR's progress and deliverables when relevant.
 After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.

package/reference/sdlc/code.playbook/bin/session-chunks.js

@@ -0,0 +1,448 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// Physical storage only: callers retain the session lease and validate the
+// materialized recovery schema. No published chunk is replaced or collected.
+import { createHash, randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { constants } from 'node:fs';
+import * as nativeFs from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { sameFileIdentity, tightenPrivateEntry, verifyPrivateEntry } from './private-paths.js';
+
+export const MAX_SESSION_CHUNK_BYTES = 8 * 1024 * 1024;
+const INLINE_BYTES = 16 * 1024;
+const FANOUT = 1024;
+const CACHE_BYTES = 32 * 1024 * 1024;
+const CACHE_NODES = 4096;
+const DIGEST = /^[0-9a-f]{64}$/;
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const jsonBytes = (value) => Buffer.from(JSON.stringify(value));
+const parseJson = (bytes) => JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+const own = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+const fail = () => { throw new Error('invalid session chunk encoding'); };
+function reference(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      Object.keys(value).length !== 2 || !own(value, 'sha256') || !own(value, 'byteLength') ||
+      !DIGEST.test(value.sha256) || !Number.isSafeInteger(value.byteLength) ||
+      value.byteLength < 1 || value.byteLength > MAX_SESSION_CHUNK_BYTES) fail();
+  return value;
+}
+function privateStat(stat, directory) {
+  if (typeof stat.mode === 'bigint') {
+    const original = stat;
+    stat = { ...stat, mode: Number(stat.mode), uid: Number(stat.uid), nlink: Number(stat.nlink),
+      isFile: () => original.isFile(), isDirectory: () => original.isDirectory(), isSymbolicLink: () => original.isSymbolicLink() };
+  }
+  verifyPrivateEntry(stat, directory, 'session chunk');
+  if ((stat.mode & 0o7777) !== (directory ? 0o700 : 0o600)) throw new Error('session chunk permissions must be private');
+}
+function unchanged(before, after) {
+  const precise = before.mtimeNs !== undefined && after.mtimeNs !== undefined;
+  return BigInt(before.dev) === BigInt(after.dev) && BigInt(before.ino) === BigInt(after.ino) && BigInt(before.size) === BigInt(after.size) &&
+    (precise ? before.mtimeNs === after.mtimeNs && before.ctimeNs === after.ctimeNs :
+      typeof before.size === typeof after.size ? before.mtimeMs === after.mtimeMs && before.ctimeMs === after.ctimeMs :
+        Math.trunc(Number(before.mtimeMs)) === Math.trunc(Number(after.mtimeMs)) && Math.trunc(Number(before.ctimeMs)) === Math.trunc(Number(after.ctimeMs)));
+}
+
+export function createSessionChunks({ directory, fsOps, createDirectory = true }) {
+  if (typeof directory !== 'string' || !isAbsolute(directory) || directory.includes('\0')) throw new TypeError('session chunk directory must be absolute');
+  if (typeof createDirectory !== 'boolean') throw new TypeError('createDirectory must be boolean');
+  const fs = { ...nativeFs, ...fsOps };
+  // Reuse immutable bytes only after a fresh private-path proof with exact
+  // nanosecond metadata. Public export proofs always read and hash the files.
+  const verified = new Map();
+  let cachedBytes = 0;
+  const forget = (digest) => {
+    const entry = verified.get(digest);
+    if (entry) { cachedBytes -= entry.bytes.length; verified.delete(digest); }
+  };
+  const remember = (digest, bytes, stat, owner) => {
+    if (stat.mtimeNs === undefined || stat.ctimeNs === undefined) return;
+    forget(digest);
+    verified.set(digest, { bytes, stat, owner }); cachedBytes += bytes.length;
+    while (cachedBytes > CACHE_BYTES || verified.size > CACHE_NODES) forget(verified.keys().next().value);
+  };
+  const operations = new AsyncLocalStorage();
+  const freshDirectory = async () => { const stat = await fs.lstat(directory); privateStat(stat, true); return stat; };
+  const checkDirectory = async () => {
+    const context = operations.getStore();
+    if (context?.owner) return context.owner;
+    const owner = await freshDirectory();
+    if (context) context.owner = owner;
+    return owner;
+  };
+  const operation = (work, force = false) => operations.run({ reads: new Map(), writes: new Map(), force }, async () => {
+    try { return await work(); }
+    finally {
+      const owner = operations.getStore().owner;
+      if (owner && !sameFileIdentity(owner, await freshDirectory())) throw new Error('session chunk directory changed during operation');
+    }
+  });
+  const sync = async (path, expected) => {
+    const handle = await fs.open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_DIRECTORY ?? 0));
+    try {
+      const opened = await handle.stat(); privateStat(opened, true);
+      if (expected && !sameFileIdentity(expected, opened)) throw new Error('session chunk directory changed');
+      await handle.sync();
+      const current = await fs.lstat(path); privateStat(current, true);
+      if (!sameFileIdentity(opened, current)) throw new Error('session chunk directory changed');
+    } finally { await handle.close(); }
+  };
+  const ensureDirectory = async () => {
+    // Never create the sessions directory or its ancestors implicitly.
+    let stat;
+    try { stat = await fs.lstat(directory); }
+    catch (error) {
+      if (error.code !== 'ENOENT' || !createDirectory) throw error;
+      const parent = await fs.lstat(dirname(directory)); privateStat(parent, true);
+      try { await fs.mkdir(directory, { mode: 0o700 }); }
+      catch (cause) { if (cause.code !== 'EEXIST') throw cause; }
+      stat = await fs.lstat(directory);
+      await sync(dirname(directory), parent);
+    }
+    await tightenPrivateEntry(directory, stat, true, fs, 'session chunk directory');
+  };
+  const prepare = async ({ recoverInterrupted = false } = {}) => {
+    if (typeof recoverInterrupted !== 'boolean') throw new TypeError('recoverInterrupted must be boolean');
+    await ensureDirectory();
+    const pendingAliases = new Map();
+    const names = await fs.readdir(directory);
+    for (const name of names) {
+      const match = /^\.write-([0-9a-f]{64})-[0-9a-f-]{36}\.tmp$/.exec(name);
+      if (!match) continue;
+      const path = join(directory, name);
+      const temporary = await fs.lstat(path);
+      if (temporary.nlink === 1) privateStat(temporary, false);
+      else {
+        // A crash between exclusive link publication and alias removal may
+        // leave precisely these two names for one private store-owned inode.
+        if (temporary.isSymbolicLink() || !temporary.isFile() || temporary.nlink !== 2 ||
+            (process.getuid && temporary.uid !== process.getuid()) || (temporary.mode & 0o7777) !== 0o600) throw new Error('unsafe interrupted session chunk publication');
+        const destination = await fs.lstat(join(directory, match[1]));
+        if (!unchanged(temporary, destination) || destination.isSymbolicLink()) throw new Error('session chunk temporary alias differs from publication');
+        pendingAliases.set(match[1], temporary);
+      }
+      if (recoverInterrupted) {
+        // The caller must hold exclusive recovery authority. Unowned prepare
+        // must never unlink a temporary still being written by another host.
+        if (!unchanged(temporary, await fs.lstat(path))) throw new Error('session chunk temporary changed');
+        await fs.unlink(path);
+      }
+    }
+    await sync(directory, await checkDirectory());
+    for (const name of names) {
+      if (!DIGEST.test(name)) continue;
+      const path = join(directory, name);
+      const stat = await fs.lstat(path);
+      if (stat.size > MAX_SESSION_CHUNK_BYTES) throw new Error('session chunk exceeds file bound');
+      if (!recoverInterrupted && pendingAliases.has(name) && unchanged(pendingAliases.get(name), stat)) continue;
+      await tightenPrivateEntry(path, stat, false, fs, 'session chunk file');
+    }
+  };
+  const readNodeUncached = async (ref) => {
+    reference(ref);
+    const owner = await checkDirectory();
+    const path = join(directory, ref.sha256);
+    const before = await fs.lstat(path, { bigint: true }); privateStat(before, false);
+    if (BigInt(before.size) !== BigInt(ref.byteLength)) throw new Error('session chunk length mismatch');
+    const cached = verified.get(ref.sha256);
+    if (!operations.getStore()?.force && cached && before.mtimeNs !== undefined &&
+        sameFileIdentity(owner, cached.owner) && unchanged(cached.stat, before)) {
+      verified.delete(ref.sha256); verified.set(ref.sha256, cached);
+      return cached.bytes;
+    }
+    forget(ref.sha256);
+    const handle = await fs.open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+      const opened = await handle.stat({ bigint: true }); privateStat(opened, false);
+      if (!unchanged(before, opened)) throw new Error('session chunk changed before read');
+      // Read the proven bounded length, rather than readFile on a growing file.
+      const bytes = Buffer.alloc(ref.byteLength);
+      let offset = 0;
+      while (offset < bytes.length) {
+        const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, offset);
+        if (!bytesRead) throw new Error('session chunk truncated during read');
+        offset += bytesRead;
+      }
+      const after = await handle.stat({ bigint: true }); privateStat(after, false);
+      const current = await fs.lstat(path, { bigint: true }); privateStat(current, false);
+      if (!unchanged(opened, after) || !unchanged(after, current) || !sameFileIdentity(owner, await checkDirectory())) throw new Error('session chunk changed during read');
+      if (hash(bytes) !== ref.sha256) throw new Error('session chunk digest mismatch');
+      if ([before, opened, after, current].every((stat) => stat.mtimeNs !== undefined && stat.ctimeNs !== undefined)) remember(ref.sha256, bytes, current, owner);
+      return bytes;
+    } finally { await handle.close(); }
+  };
+  const readNode = (ref) => {
+    reference(ref);
+    const reads = operations.getStore()?.reads;
+    const previous = reads?.get(ref.sha256);
+    if (previous) {
+      if (previous.byteLength !== ref.byteLength) fail();
+      return previous.bytes;
+    }
+    const bytes = readNodeUncached(ref);
+    reads?.set(ref.sha256, { byteLength: ref.byteLength, bytes });
+    return bytes;
+  };
+  const writeNode = async (bytes) => {
+    if (!bytes.length || bytes.length > MAX_SESSION_CHUNK_BYTES) throw new Error('session chunk exceeds file bound');
+    const ref = Object.freeze({ sha256: hash(bytes), byteLength: bytes.length });
+    const writes = operations.getStore()?.writes;
+    if (writes?.has(ref.sha256)) return writes.get(ref.sha256);
+    const owner = await checkDirectory();
+    try { await readNode(ref); writes?.set(ref.sha256, ref); return ref; }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      operations.getStore()?.reads.delete(ref.sha256);
+    }
+    const temporary = join(directory, `.write-${ref.sha256}-${randomUUID()}.tmp`);
+    const destination = join(directory, ref.sha256);
+    let handle;
+    try {
+      handle = await fs.open(temporary, 'wx', 0o600);
+      await handle.chmod(0o600);
+      const opened = await handle.stat(); privateStat(opened, false);
+      await handle.writeFile(bytes); await handle.sync();
+      const after = await handle.stat(); privateStat(after, false);
+      const current = await fs.lstat(temporary); privateStat(current, false);
+      if (!sameFileIdentity(opened, after) || !unchanged(after, current) || after.size !== bytes.length || !sameFileIdentity(owner, await checkDirectory())) throw new Error('session chunk changed during write');
+      await handle.close(); handle = undefined;
+      // link is exclusive publication; remove its temporary alias before any
+      // private reader sees it, then sync both the file and directory.
+      try { await fs.link(temporary, destination); }
+      catch (error) { if (error.code !== 'EEXIST') throw error; }
+      await fs.unlink(temporary);
+      await readNode(ref);
+      writes?.set(ref.sha256, ref);
+      return ref;
+    } finally {
+      await handle?.close();
+      // Failed publication leaves only unreachable bytes, never a new root.
+      try { await fs.unlink(temporary); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+  };
+  const put = (tag, value) => writeNode(Buffer.concat([Buffer.from([tag]), jsonBytes(value)]));
+  const writeBytes = async (input) => {
+    const bytes = Buffer.from(input);
+    let level = [];
+    for (let offset = 0; offset < bytes.length || offset === 0; offset += MAX_SESSION_CHUNK_BYTES - 1) {
+      level.push(await writeNode(Buffer.concat([Buffer.from([0]), bytes.subarray(offset, offset + MAX_SESSION_CHUNK_BYTES - 1)])));
+    }
+    while (level.length > 1) {
+      const next = [];
+      for (let offset = 0; offset < level.length; offset += FANOUT) next.push(await put(1, level.slice(offset, offset + FANOUT)));
+      level = next;
+    }
+    return level[0];
+  };
+  const readBytes = async (ref, depth = 0) => {
+    if (depth > 512) fail();
+    const bytes = await readNode(ref);
+    if (bytes[0] === 0) return bytes.subarray(1);
+    if (bytes[0] !== 1) fail();
+    const children = parseJson(bytes.subarray(1));
+    if (!Array.isArray(children) || !children.length || children.length > FANOUT) fail();
+    const pieces = [];
+    for (const child of children) pieces.push(await readBytes(reference(child), depth + 1));
+    return Buffer.concat(pieces);
+  };
+  const writeEncodedJson = async (encoded, bytes = jsonBytes(encoded)) => {
+    return bytes.length + 1 <= MAX_SESSION_CHUNK_BYTES
+      ? writeNode(Buffer.concat([Buffer.from([2]), bytes]))
+      : put(3, await writeBytes(bytes));
+  };
+  // Inline JSON has no asynchronous work. Yield only at actual chunk IO,
+  // retaining depth-first ordering even when a child needs persistence.
+  const eachSequential = (values, visit, start = 0) => {
+    for (let index = start; index < values.length; index++) {
+      const pending = visit(values[index], index);
+      if (pending instanceof Promise) return pending.then(() => eachSequential(values, visit, index + 1));
+    }
+  };
+  const writeJson = async (value) => {
+    const active = new Set();
+    const encode = (node, depth) => {
+      if (depth > 512) throw new Error('session JSON nesting exceeds supported depth');
+      if (node === null || typeof node === 'string' || typeof node === 'boolean' || (typeof node === 'number' && Number.isFinite(node))) {
+        const serialized = jsonBytes(node);
+        return serialized.length <= INLINE_BYTES ? ['v', node] : writeBytes(serialized).then((ref) => ['s', ref]);
+      }
+      if (!node || typeof node !== 'object' || (!Array.isArray(node) && ![Object.prototype, null].includes(Object.getPrototypeOf(node))) || active.has(node)) throw new TypeError('session chunks require plain acyclic JSON');
+      active.add(node);
+      try {
+        const entries = [];
+        for (const key of Object.keys(node)) {
+          const descriptor = Object.getOwnPropertyDescriptor(node, key);
+          if (!descriptor || !own(descriptor, 'value')) throw new TypeError('session chunks reject JSON accessors');
+          entries.push([key, descriptor.value]);
+        }
+        if (Array.isArray(node) && (entries.length !== node.length || entries.some(([key], index) => key !== String(index)))) throw new TypeError('session chunks reject sparse or extended arrays');
+        const encoded = [];
+        const finish = () => {
+          const plain = Array.isArray(node) ? encoded.map(([, child]) => child) : encoded;
+          const representation = [Array.isArray(node) ? 'a' : 'o', plain];
+          const bytes = jsonBytes(representation);
+          return bytes.length <= INLINE_BYTES ? representation : writeEncodedJson(representation, bytes).then((ref) => ['r', ref]);
+        };
+        const children = eachSequential(entries, ([key, child]) => {
+          const result = encode(child, depth + 1);
+          if (result instanceof Promise) return result.then((value) => { encoded.push([key, value]); });
+          encoded.push([key, result]);
+        });
+        const result = children instanceof Promise ? children.then(finish) : finish();
+        if (result instanceof Promise) return result.finally(() => active.delete(node));
+        active.delete(node);
+        return result;
+      } catch (error) { active.delete(node); throw error; }
+    };
+    return writeEncodedJson(await encode(value, 0));
+  };
+  const decode = (node, depth, collect) => {
+    if (depth > 2048 || !Array.isArray(node) || node.length !== 2) fail();
+    const [kind, value] = node;
+    if (kind === 'v') {
+      if (value !== null && !['string', 'boolean', 'number'].includes(typeof value) || typeof value === 'number' && !Number.isFinite(value)) fail();
+      return value;
+    }
+    if (kind === 'r') { collect?.(reference(value)); return loadJson(value, depth + 1, collect); }
+    if (kind === 's') {
+      collect?.(reference(value));
+      return readBytes(value).then((bytes) => { const result = parseJson(bytes); if (typeof result !== 'string') fail(); return result; });
+    }
+    if (kind !== 'a' && kind !== 'o' || !Array.isArray(value)) fail();
+    const result = kind === 'a' ? [] : {};
+    const children = eachSequential(value, (entry) => {
+      if (kind === 'o' && (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== 'string' || own(result, entry[0]))) fail();
+      const set = (decoded) => {
+        if (kind === 'a') result.push(decoded);
+        else Object.defineProperty(result, entry[0], { value: decoded, enumerable: true, writable: true, configurable: true });
+      };
+      const decoded = decode(kind === 'a' ? entry : entry[1], depth + 1, collect);
+      if (decoded instanceof Promise) return decoded.then(set);
+      set(decoded);
+    });
+    return children instanceof Promise ? children.then(() => result) : result;
+  };
+  const loadJson = async (ref, depth = 0, collect) => {
+    if (depth > 2048) fail();
+    const bytes = await readNode(ref);
+    if (bytes[0] === 2) return decode(parseJson(bytes.subarray(1)), depth + 1, collect);
+    if (bytes[0] !== 3) fail();
+    const body = reference(parseJson(bytes.subarray(1)));
+    collect?.(body);
+    return decode(parseJson(await readBytes(body)), depth + 1, collect);
+  };
+  const walk = async (ref) => {
+    const seen = new Map();
+    const visit = async (value) => {
+      reference(value);
+      if (seen.has(value.sha256)) { if (seen.get(value.sha256).byteLength !== value.byteLength) fail(); return; }
+      const bytes = await readNode(value);
+      seen.set(value.sha256, Object.freeze({ path: value.sha256, sha256: value.sha256, byteLength: value.byteLength }));
+      if (bytes[0] === 0) return;
+      if (bytes[0] === 1) {
+        const children = parseJson(bytes.subarray(1));
+        if (!Array.isArray(children) || !children.length || children.length > FANOUT) fail();
+        for (const child of children) await visit(child);
+      } else if (bytes[0] === 2 || bytes[0] === 3) {
+        const refs = [];
+        await loadJson(value, 0, (child) => refs.push(child));
+        for (const child of refs) await visit(child);
+      } else fail();
+    };
+    await visit(ref);
+    return Object.freeze([...seen.values()]);
+  };
+  const validateEncoding = (encoded, depth = 0) => {
+    if (depth > 2048 || !Array.isArray(encoded) || encoded.length !== 2) fail();
+    const [kind, value] = encoded;
+    if (kind === 'v') {
+      if (value !== null && !['string', 'boolean', 'number'].includes(typeof value) || typeof value === 'number' && !Number.isFinite(value)) fail();
+    } else if (kind === 'r' || kind === 's') reference(value);
+    else if (kind === 'a') {
+      if (!Array.isArray(value)) fail();
+      for (const child of value) validateEncoding(child, depth + 1);
+    } else if (kind === 'o') {
+      if (!Array.isArray(value)) fail();
+      const keys = new Set();
+      for (const entry of value) {
+        if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== 'string' || keys.has(entry[0])) fail();
+        keys.add(entry[0]); validateEncoding(entry[1], depth + 1);
+      }
+    } else fail();
+  };
+  const validateNamespace = async () => {
+    const owner = await checkDirectory();
+    const entries = [];
+    for (const name of await fs.readdir(directory)) {
+      const path = join(directory, name);
+      const stat = await fs.lstat(path);
+      if (!DIGEST.test(name)) {
+        // A namespace proof never repairs temporary aliases. The same proof
+        // used by prepare permits a pending store-owned publication alias.
+        const temporary = /^\.write-([0-9a-f]{64})-[0-9a-f-]{36}\.tmp$/.exec(name);
+        if (temporary && stat.nlink === 2) {
+          if (stat.isSymbolicLink() || !stat.isFile() ||
+              (process.getuid && stat.uid !== process.getuid()) || (stat.mode & 0o7777) !== 0o600 ||
+              !unchanged(stat, await fs.lstat(join(directory, temporary[1])))) throw new Error('unsafe interrupted session chunk publication');
+        } else privateStat(stat, false);
+        continue;
+      }
+      if (stat.size > MAX_SESSION_CHUNK_BYTES) throw new Error('session chunk exceeds file bound');
+      const bytes = await readNode({ sha256: name, byteLength: stat.size });
+      if (bytes[0] === 1) {
+        const children = parseJson(bytes.subarray(1));
+        if (!Array.isArray(children) || !children.length || children.length > FANOUT) fail();
+        for (const child of children) reference(child);
+      } else if (bytes[0] === 2) validateEncoding(parseJson(bytes.subarray(1)));
+      else if (bytes[0] === 3) reference(parseJson(bytes.subarray(1)));
+      else if (bytes[0] !== 0) fail();
+      entries.push(Object.freeze({ path: name, byteLength: bytes.length }));
+    }
+    if (!sameFileIdentity(owner, await checkDirectory())) throw new Error('session chunk directory changed during validation');
+    return Object.freeze(entries);
+  };
+  const remove = async () => {
+    let owner;
+    try { owner = await checkDirectory(); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+    const names = await fs.readdir(directory);
+    // Validate every candidate before removing any; links and subdirectories
+    // are never followed or recursively removed.
+    for (const name of names) privateStat(await fs.lstat(join(directory, name)), false);
+    for (const name of names) {
+      if (!sameFileIdentity(owner, await checkDirectory())) throw new Error('session chunk directory changed during deletion');
+      const path = join(directory, name); privateStat(await fs.lstat(path), false); await fs.unlink(path);
+    }
+    await sync(directory, owner);
+    await fs.rmdir(directory);
+    verified.clear(); cachedBytes = 0;
+    await sync(dirname(directory));
+  };
+  const writeOperation = (work) => operation(async () => {
+    await ensureDirectory();
+    const owner = await checkDirectory();
+    const result = await work();
+    // Files have each been synced before publication. One directory sync
+    // proves the complete dependency graph before its reference is returned.
+    await sync(directory, owner);
+    return result;
+  });
+  return Object.freeze({
+    prepare,
+    writeJson: (value) => writeOperation(() => writeJson(value)),
+    writeBytesAndJson: (bytes, makeJson) => writeOperation(async () => {
+      if (typeof makeJson !== 'function') throw new TypeError('session chunk JSON builder must be a function');
+      // This fixed dependency pair cannot return an acknowledged head until
+      // both files and the containing directory have been synced.
+      const content = await writeBytes(bytes);
+      return writeJson(makeJson(content));
+    }),
+    readJson: (ref) => operation(() => loadJson(ref)),
+    writeBytes: (bytes) => writeOperation(() => writeBytes(bytes)),
+    readBytes: (ref) => operation(async () => Buffer.from(await readBytes(ref))),
+    walk: (ref) => operation(() => walk(ref), true),
+    validateNamespace: () => operation(validateNamespace, true),
+    delete: remove,
+  });
+}