@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.21

package/lib/types.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Pure data types for the chapter archive. No cordis, no DSH imports — this module is what makes the
+ * archive unit-testable without booting a harness, which is the whole testing strategy in
+ * docs/development.md § Test Layers.
+ *
+ * Event field names here were taken from real session logs read during Phase 0 (see
+ * spikes/probe/FINDINGS.md), not guessed: `user/message` carries `data.{id,role,source,content}` and
+ * `tool/call` carries `data.{callId,name,arguments}`. Where the shape is uncertain the renderer degrades
+ * rather than throws, because a dropped detail in an archive is worse than an ugly one.
+ */
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mimeType?: string;
+    data?: string;
+    path?: string;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * One durable session event, as an archive input.
+ *
+ * `data` is **required**, and that is load-bearing (#58). It used to be optional, which is how
+ * `sessionQuery.listEvents` output — a `SessionEventRecord` carrying `seq`/`type`/`time`/`surface`
+ * and NO payload — type-checked as an event list. The renderer's defensive `ev.data ?? {}` then
+ * turned every row into a structurally valid, EMPTY chapter: tool names `unknown`, args `{}`,
+ * results the `sha256("")` blob at 0 B, all messages unrendered. Read the host's `readSession` or
+ * a live `snapshotEvents()` instead — `docs/contract.md` § Durable reads, pinned by
+ * `tests/unit/host-durable-read.test.ts`.
+ */
+export interface SessionEventLike {
+    type: string;
+    seq: number;
+    time?: number;
+    surfaceOp?: string;
+    data: Record<string, unknown>;
+}
+/** One chapter = a contiguous, closed range of durable event seqs. Integers, never text anchors. */
+export interface ChapterRange {
+    title: string;
+    summary: string;
+    startSeq: number;
+    endSeq: number;
+}
+/** The model's sparse exceptions about tool results. Absence means "use the default rule". */
+export interface ToolResultOverride {
+    seq: number;
+    inline: boolean;
+}
+/**
+ * A session plan's verdict, as the log states it (`src/plans.ts`). `failed` is the
+ * family where the host threw without a human verdict (no review channel, service
+ * reloaded mid-review, the call ran outside plan mode, the markdown had no heading)
+ * — labelling those `rejected` would invent a decision nobody made.
+ */
+export type PlanStatus = 'approved' | 'rejected' | 'dismissed' | 'pending' | 'superseded' | 'failed';
+/** One plan's machine facts, carried in the chapter record and the registry row. */
+export interface PlanFact {
+    seq: number;
+    status: PlanStatus;
+    title: string;
+    sha256: string;
+    artifactPath: string;
+    bytes: number;
+    estTokens: number;
+    resultSeq: number | null;
+}
+/**
+ * The notice's flat plan row (archived facts and live, unarchived docs unify here).
+ * Rows travel in CAUSAL order — chapters root-first, plans within a chapter by seq,
+ * then the caller's unarchived tail. Every session numbers its own events from zero,
+ * so a `seq` in one session is NOT comparable with a `seq` in another: the builder's
+ * order is the chronology, and nothing downstream may re-sort by `seq`
+ * (docs/plans-carriage.md § 4).
+ */
+export interface NoticePlan {
+    title: string;
+    status: PlanStatus;
+    seq: number;
+    chapterNumber?: number;
+    chapterPath?: string;
+    artifactPath?: string;
+    /** The plan's own `kind: plan` document, when one was written. */
+    docPath?: string;
+    sha256?: string;
+    estTokens?: number;
+}
+export interface RenderConfig {
+    /** Below this estimated token count a tool result stays inline without needing a model override. */
+    toolResultDeferFloorTokens: number;
+    /** Chapter sizes past this are flagged for a split at the next boundary. Never truncated. */
+    chapterTokenTarget: number;
+    /**
+     * Verbatim plan characters printed inline under a plan's reference. The full text is
+     * ALWAYS artifact-backed, so this is a display budget, never a data decision.
+     * 0 = pointer only (the artifact line and outline still print).
+     */
+    planInlineChars?: number;
+    /**
+     * Above this estimated token count a tool-call ARGUMENT is artifact-backed and the
+     * inline text is a bounded head. 0 = off: every argument keeps the plain head rule,
+     * so a deployment opts in deliberately (it changes chapter bytes, hence tapes).
+     */
+    callArgArtifactTokens?: number;
+    /**
+     * Credential redaction patterns applied at the render chokepoint (record §9).
+     * Absent → the built-in conservative set. Extensible per deployment.
+     */
+    redactions?: readonly import('./redact.ts').RedactPattern[];
+    /**
+     * Lineage stamp (issue #47): the id of the PARENT session when the authoring
+     * session is a subagent child. Copied verbatim from the durable
+     * `session.header.parentSession` the HOST writes (`childSessionMeta`), never
+     * inferred. Emitted ONLY when a non-empty string — a session without a parent
+     * renders byte-identically to the pre-feature shape, which is what keeps every
+     * existing chapter file and every model tape un-re-recorded (same discipline
+     * as the plans block, verify.md P8).
+     */
+    subagentOf?: string;
+}
+/**
+ * Read the lineage the kernel stamped into a session header, or undefined.
+ * The ONE sanctioned reader of `parentSession` for chapter rendering — every
+ * archive door (save, auto-save, compaction finalize) passes its output into
+ * `RenderConfig.subagentOf`, so the field is stamped the same way everywhere.
+ */
+export declare function lineageOf(header: {
+    parentSession?: string;
+} | undefined): string | undefined;
+export interface ArtifactRef {
+    /** Content hash; the artifact path is derived from it, so identical results dedupe across a subtree. */
+    sha256: string;
+    /** Relative path from the store root, as it will be printed in the chapter and read back. */
+    path: string;
+    bytes: number;
+    /** The exact bytes to write. Written whether or not the body was also inlined. */
+    content: string;
+    /** True when the chapter body also carries the text, i.e. the model asked to keep it visible. */
+    inlined: boolean;
+    toolName: string;
+    sourceSeq: number;
+}
+/**
+ * A plan DOCUMENT the writer emits beside its chapter: the whole plan as its own
+ * indexed file (`kind: plan`), so plans are queryable as plans — by topic, by
+ * status, by how they evolved — instead of only as bytes inside a transcript.
+ * It lives in `chapters/` on purpose: the pool transport, the mirror rehydrate and
+ * the corpus index then pick it up with zero special casing.
+ */
+export interface PlanDocFile {
+    seq: number;
+    title: string;
+    status: PlanStatus;
+    body: string;
+    sha256: string;
+    /** The transcript chapter that cites it, once the writer knows its path. */
+    chapterPath?: string | undefined;
+    /** The document this one supersedes (same title, earlier submission). */
+    supersedes?: string | undefined;
+    topics: string[];
+    estTokens: number;
+}
+export interface RenderedChapter {
+    range: ChapterRange;
+    /** Index topics (deterministic floor: paths + top terms). P2 enrichment may relabel. */
+    topics: string[];
+    /** Full Markdown file body, YAML frontmatter included. */
+    markdown: string;
+    artifacts: ArtifactRef[];
+    stats: {
+        /** chars/4 estimate until tokenMeter is wired at the host boundary; labelled as an estimate. */
+        estimatedTokens: number;
+        estimatedBytes: number;
+        events: number;
+        /** user+assistant MESSAGE events in the chapter (record §7.3: counts, not tokens). */
+        messages: number;
+        toolCalls: number;
+        toolResultsInlined: number;
+        toolResultsDeferred: number;
+        /** True when the chapter exceeds chapterTokenTarget — a split signal, never a truncation licence. */
+        overTarget: boolean;
+        /** Events in the range that produced no rendered output, so a silent hole is visible. */
+        unrenderedSeqs: number[];
+        /** Plans submitted inside this range, with the artifact that carries their full
+         * text. Absent (not an empty list) on chapters rendered before this feature —
+         * the same "never a lying zero" rule `messages` follows. */
+        plans?: PlanFact[] | undefined;
+        /** Folded `plan/mode` state at the range's end; 'unknown' when the log never said. */
+        planMode?: 'active' | 'inactive' | 'unknown' | undefined;
+        /** Tool-call arguments artifact-backed by the `callArgArtifactTokens` rule. */
+        invocationArtifacts?: number | undefined;
+        /** Files to emit beside this chapter (one per plan in range). */
+        planDocs?: PlanDocFile[] | undefined;
+    };
+}
+/** A candidate tool result, enumerated by the plugin so the model never guesses at sizes. */
+export interface ToolResultCandidate {
+    seq: number;
+    toolName: string;
+    bytes: number;
+    estimatedTokens: number;
+    excerpt: string;
+}
+export declare class RangeError extends Error {
+    readonly code: 'overlapping' | 'gap' | 'descending' | 'beyond-ceiling' | 'empty';
+    constructor(code: RangeError['code'], message: string);
+}

package/lib/types.js

@@ -0,0 +1,31 @@
+/**
+ * Pure data types for the chapter archive. No cordis, no DSH imports — this module is what makes the
+ * archive unit-testable without booting a harness, which is the whole testing strategy in
+ * docs/development.md § Test Layers.
+ *
+ * Event field names here were taken from real session logs read during Phase 0 (see
+ * spikes/probe/FINDINGS.md), not guessed: `user/message` carries `data.{id,role,source,content}` and
+ * `tool/call` carries `data.{callId,name,arguments}`. Where the shape is uncertain the renderer degrades
+ * rather than throws, because a dropped detail in an archive is worse than an ugly one.
+ */
+/**
+ * Read the lineage the kernel stamped into a session header, or undefined.
+ * The ONE sanctioned reader of `parentSession` for chapter rendering — every
+ * archive door (save, auto-save, compaction finalize) passes its output into
+ * `RenderConfig.subagentOf`, so the field is stamped the same way everywhere.
+ */
+export function lineageOf(header) {
+    if (header === undefined)
+        return undefined;
+    const p = header.parentSession;
+    return typeof p === 'string' && p !== '' ? p : undefined;
+}
+export class RangeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'RangeError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAmHH;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,MAA8C;IACtE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IAC1C,MAAM,CAAC,GAAG,MAAM,CAAC,aAAa,CAAA;IAC9B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1D,CAAC;AAgFD,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,IAAI,CAAmE;IAChF,YAAY,IAAwB,EAAE,OAAe;QACnD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAA;IAC1B,CAAC;CACF"}

package/lib/version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The plugin's own version, stamped into chapter provenance (#61).
+ *
+ * This audit had to *infer* which build wrote which registry row from file mtimes, because `generated:`
+ * recorded a model name and a timestamp and nothing else. Attribution is a fact the writer knows and the
+ * reader cannot recover later, so it belongs in the bytes. A row in tests asserts this literal equals
+ * `package.json`'s version — the one place a hand-mirrored constant must never be allowed to drift.
+ */
+export declare const PLUGIN_VERSION = "0.2.21";

package/lib/version.js

@@ -0,0 +1,10 @@
+/**
+ * The plugin's own version, stamped into chapter provenance (#61).
+ *
+ * This audit had to *infer* which build wrote which registry row from file mtimes, because `generated:`
+ * recorded a model name and a timestamp and nothing else. Attribution is a fact the writer knows and the
+ * reader cannot recover later, so it belongs in the bytes. A row in tests asserts this literal equals
+ * `package.json`'s version — the one place a hand-mirrored constant must never be allowed to drift.
+ */
+export const PLUGIN_VERSION = '0.2.21';
+//# sourceMappingURL=version.js.map

package/lib/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAA"}

package/lib/vocabulary.d.ts

@@ -0,0 +1,41 @@
+/**
+ * P2 S4 — the emergent vocabulary canonicalizer (record §6.3). Pure functions
+ * over topic lists; the sync pass feeds it chapter topics and applies (or,
+ * in shadow mode, merely reports) the merge candidates.
+ *
+ * No seed lists, no hand-editing expectation: plugin-owned curation entries,
+ * every one carrying its signal + counts, written to
+ * `edits/<harnessId>/curation.jsonl` — git-visible, revertible, and already
+ * consumed by the index build (P1 plumbing).
+ */
+export interface VocabOpts {
+    coMin: number;
+    overlapMin: number;
+}
+export interface VocabCandidate {
+    from: string;
+    to: string;
+    cooccur: number;
+    overlap: number;
+    reason: 'co-occurrence' | 'alias-pattern' | 'token-overlap';
+}
+/**
+ * Candidates over a corpus of per-chapter topic lists. Canonical direction:
+ * the MORE FREQUENT label survives (`to`); alphabetical tie-break. Pairs
+ * already aliased (either direction) are skipped by the caller — this module
+ * only proposes, applying and deduping against existing entries is the pass.
+ */
+export declare function analyzeTopics(chapterTopics: string[][], opts: VocabOpts): {
+    candidates: VocabCandidate[];
+    frequency: Map<string, number>;
+};
+/**
+ * The curation lines to append (topic-alias facts) given the aliases already
+ * known. A 'from' already aliased (anywhere in the chain) is skipped, and
+ * chains are resolved to their final target so we never write a->b when b
+ * already maps to c (write a->c instead — deterministic, order-independent).
+ */
+export declare function planAppends(candidates: VocabCandidate[], existing: Map<string, string>, at: string): {
+    lines: string[];
+    plan: VocabCandidate[];
+};

package/lib/vocabulary.js

@@ -0,0 +1,118 @@
+/**
+ * P2 S4 — the emergent vocabulary canonicalizer (record §6.3). Pure functions
+ * over topic lists; the sync pass feeds it chapter topics and applies (or,
+ * in shadow mode, merely reports) the merge candidates.
+ *
+ * No seed lists, no hand-editing expectation: plugin-owned curation entries,
+ * every one carrying its signal + counts, written to
+ * `edits/<harnessId>/curation.jsonl` — git-visible, revertible, and already
+ * consumed by the index build (P1 plumbing).
+ */
+const tokenize = (t) => new Set(t.toLowerCase().split(/[^a-z0-9]+/).filter((s) => s.length > 0));
+const stem = (tok) => (tok.length > 3 && tok.endsWith('s') ? tok.slice(0, -1) : tok);
+const jaccard = (a, b) => {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter += 1;
+    return inter / (a.size + b.size - inter);
+};
+/** one token is a prefix of the other, or equal after plural stemming */
+const aliasPattern = (a, b) => {
+    const ta = [...tokenize(a)], tb = [...tokenize(b)];
+    if (ta.length === 0 || tb.length === 0)
+        return false;
+    const pa = ta[0], pb = tb[0];
+    if (ta.length === 1 && tb.length === 1) {
+        if (pa !== pb && (pa.startsWith(pb) || pb.startsWith(pa)))
+            return true;
+        if (stem(pa) === stem(pb) && pa !== pb)
+            return true;
+    }
+    return false;
+};
+/**
+ * Candidates over a corpus of per-chapter topic lists. Canonical direction:
+ * the MORE FREQUENT label survives (`to`); alphabetical tie-break. Pairs
+ * already aliased (either direction) are skipped by the caller — this module
+ * only proposes, applying and deduping against existing entries is the pass.
+ */
+export function analyzeTopics(chapterTopics, opts) {
+    const frequency = new Map();
+    const cooc = new Map();
+    for (const topics of chapterTopics) {
+        const uniq = [...new Set(topics.map((t) => t.toLowerCase().trim()).filter((t) => t.length > 0))];
+        for (const t of uniq)
+            frequency.set(t, (frequency.get(t) ?? 0) + 1);
+        for (let i = 0; i < uniq.length; i++) {
+            for (let k = i + 1; k < uniq.length; k++) {
+                const key = [uniq[i], uniq[k]].sort().join('\u0000');
+                cooc.set(key, (cooc.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    const labels = [...frequency.keys()].sort();
+    const candidates = [];
+    for (let i = 0; i < labels.length; i++) {
+        for (let k = i + 1; k < labels.length; k++) {
+            const a = labels[i], b = labels[k];
+            const overlap = jaccard(tokenize(a), tokenize(b));
+            const alias = aliasPattern(a, b);
+            const co = cooc.get([a, b].sort().join('\u0000')) ?? 0;
+            const byFreq = (frequency.get(b) ?? 0) - (frequency.get(a) ?? 0);
+            const from = byFreq < 0 ? b : a;
+            const to = byFreq < 0 ? a : b;
+            let reason = null;
+            if (alias)
+                reason = 'alias-pattern';
+            else if (co >= opts.coMin)
+                reason = 'co-occurrence';
+            else if (overlap >= opts.overlapMin)
+                reason = 'token-overlap';
+            if (reason === null)
+                continue;
+            candidates.push({ from, to, cooccur: co, overlap: Number(overlap.toFixed(3)), reason });
+        }
+    }
+    candidates.sort((x, y) => x.from < y.from ? -1 : x.from > y.from ? 1 : 0);
+    return { candidates, frequency };
+}
+/**
+ * The curation lines to append (topic-alias facts) given the aliases already
+ * known. A 'from' already aliased (anywhere in the chain) is skipped, and
+ * chains are resolved to their final target so we never write a->b when b
+ * already maps to c (write a->c instead — deterministic, order-independent).
+ */
+export function planAppends(candidates, existing, at) {
+    const resolve = (label, depth = 0) => {
+        if (depth > 10)
+            return label;
+        const next = existing.get(label);
+        return next === undefined || next === label ? label : resolve(next, depth + 1);
+    };
+    const plan = [];
+    const seen = new Map(existing);
+    const lines = [];
+    for (const c of candidates) {
+        // a RAW 'from' that already aliases is stale by definition (skip); the
+        // target folds forward through known chains so we never write into the
+        // middle of one (a->b when b->c exists becomes a->c)
+        if (existing.has(c.from) || seen.has(c.from))
+            continue;
+        const to = resolve(c.to);
+        const from = c.from;
+        if (from === to)
+            continue;
+        seen.set(from, to);
+        const entry = { ...c, from, to };
+        plan.push(entry);
+        // topic-alias matches the index layer's CurationFact; the reason/count
+        // payload is carried alongside (parseCuration ignores unknown keys) so
+        // every merge is self-documenting in git
+        lines.push(JSON.stringify({ type: 'topic-alias', from, to, at, reason: `${entry.reason}: cooccur=${entry.cooccur} overlap=${entry.overlap}` }));
+    }
+    return { lines, plan };
+}
+//# sourceMappingURL=vocabulary.js.map

package/lib/vocabulary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.js","sourceRoot":"","sources":["../src/vocabulary.ts"],"names":[],"mappings":"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"}

package/lib/warnings.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The one formatter that turns a door's warnings into text a human reads (#61).
+ *
+ * The field failure was delivery, not detection: `writeArchive` produced 86 warnings across six SAIP
+ * saves — naming the hollow chapter, the oversize chapters and an unarchived 0–4082 hole — and every door
+ * reduced them to `(86 warning(s))`. A count is not a message. So all doors call THIS, which shows the
+ * first `cap` texts and then says how many more there are, because "the withheld count is mandatory"
+ * is already the rule for rules selection (record §7.4) and for search results.
+ */
+export declare function formatWarnings(warnings: readonly string[], cap: number): string;

package/lib/warnings.js

@@ -0,0 +1,18 @@
+/**
+ * The one formatter that turns a door's warnings into text a human reads (#61).
+ *
+ * The field failure was delivery, not detection: `writeArchive` produced 86 warnings across six SAIP
+ * saves — naming the hollow chapter, the oversize chapters and an unarchived 0–4082 hole — and every door
+ * reduced them to `(86 warning(s))`. A count is not a message. So all doors call THIS, which shows the
+ * first `cap` texts and then says how many more there are, because "the withheld count is mandatory"
+ * is already the rule for rules selection (record §7.4) and for search results.
+ */
+export function formatWarnings(warnings, cap) {
+    if (warnings.length === 0)
+        return '';
+    const shown = Math.max(1, Math.floor(cap));
+    const head = warnings.slice(0, shown);
+    const rest = warnings.length - head.length;
+    return head.join('; ') + (rest > 0 ? `; …and ${rest} more` : '');
+}
+//# sourceMappingURL=warnings.js.map

package/lib/warnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.js","sourceRoot":"","sources":["../src/warnings.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,QAA2B,EAAE,GAAW;IACrE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACpC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;IAC1C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;IACrC,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;AAClE,CAAC"}

package/package.json

@@ -1,6 +1,154 @@
 {
   "name": "@fractalsynapse/dsh-chapters",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.21",
+  "description": "dsh plugin: verbatim chapter archive + zero-token index for small-context models",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./engine": "./lib/engine.js",
+    "./preset": "./lib/preset.js",
+    "./tools": "./lib/tools.js",
+    "./store": "./lib/store.js",
+    "./registry": "./lib/registry.js",
+    "./client": "./lib/client.js"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "docs",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": false,
+      "inject": [
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-ui-commands"
+      ]
+    }
+  },
+  "scripts": {
+    "test": "node --test tests/unit/*.test.ts tests/integration/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:client": "tsc -p tsconfig.client.strict.json",
+    "typecheck:e2e": "tsc -p tsconfig.e2e.json --noEmit",
+    "build": "tsc -p tsconfig.json && tsdown -c tsdown.client.config.ts --config-loader tsx",
+    "corpus:stamp": "node scripts/build-stamp.mjs stamp",
+    "corpus:check": "node scripts/build-stamp.mjs check",
+    "build:client": "tsdown -c tsdown.client.config.ts",
+    "test:unit": "node --test tests/unit/*.test.ts",
+    "e2e:one": "bash scripts/e2e-one.sh",
+    "e2e:harness:live": "E2E_PROVIDER=harness MODE=live bash scripts/e2e-one.sh",
+    "corpus:heal": "E2E_PROVIDER=harness MODE=heal bash scripts/e2e-one.sh",
+    "corpus:record": "E2E_PROVIDER=harness MODE=record bash scripts/e2e-one.sh",
+    "test:e2e": "PLAYWRIGHT_BROWSERS_PATH=$PWD/var/ms-playwright npx playwright test -c tests/e2e/playwright.config.ts --project=suite && PLAYWRIGHT_BROWSERS_PATH=$PWD/var/ms-playwright npx playwright test -c tests/e2e/playwright.config.ts --project=heavy && PLAYWRIGHT_BROWSERS_PATH=$PWD/var/ms-playwright npx playwright test -c tests/e2e/playwright.config.ts --project=arrival && PLAYWRIGHT_BROWSERS_PATH=$PWD/var/ms-playwright npx playwright test -c tests/e2e/playwright.config.ts --project=enrich && PLAYWRIGHT_BROWSERS_PATH=$PWD/var/ms-playwright npx playwright test -c tests/e2e/playwright.config.ts --project=fanout && PLAYWRIGHT_BROWSERS_PATH=$PWD/var/ms-playwright npx playwright test -c tests/e2e/playwright.config.ts --project=rules && PLAYWRIGHT_BROWSERS_PATH=$PWD/var/ms-playwright npx playwright test -c tests/e2e/playwright.config.ts --project=fork && PLAYWRIGHT_BROWSERS_PATH=$PWD/var/ms-playwright npx playwright test -c tests/e2e/playwright.config.ts --project=plans && PLAYWRIGHT_BROWSERS_PATH=$PWD/var/ms-playwright npx playwright test -c tests/e2e/playwright.config.ts --project=prompt && PLAYWRIGHT_BROWSERS_PATH=$PWD/var/ms-playwright npx playwright test -c tests/e2e/playwright.config.ts --project=prompt-off",
+    "test:all": "npm test && npm run test:e2e",
+    "test:integration": "node --test tests/integration/*.test.ts",
+    "test:e2e:record": "E2E_MODEL=record npm run test:e2e",
+    "test:e2e:replay": "E2E_MODEL=replay bash scripts/chain-replay.sh",
+    "coverage:e2e": "E2E_COVERAGE=1 PLAYWRIGHT_BROWSERS_PATH=$PWD/var/ms-playwright npm run test:e2e:replay && node scripts/e2e-coverage.mjs",
+    "coverage": "node --test --experimental-test-coverage tests/unit/*.test.ts tests/integration/*.test.ts",
+    "coverage:ci": "c8 --check-coverage --statements 85 --branches 85 --functions 85 --lines 85 --reporter=text-summary --reporter=json-summary --report-dir var/coverage node --test tests/unit/*.test.ts tests/integration/*.test.ts",
+    "test:e2e:cache": "E2E_PORT=41739 PLAYWRIGHT_BROWSERS_PATH=$PWD/var/ms-playwright playwright test -c tests/e2e/playwright.config.ts --project=cache",
+    "bench": "node benchmarks/run-bench.mjs",
+    "bench:nightly": "node benchmarks/run-bench.mjs --every 60",
+    "docs:dev": "npm --prefix site run dev",
+    "docs:build": "npm --prefix site run build",
+    "mining:probe": "node scripts/mining-probe.mjs",
+    "llm:where": "node -e \"import('./scripts/llm.mjs').then(async m=>{const t=await m.resolve({});console.log(t.base,t.model,t.regime,'| credential:',m.apiKeySource(),'| key found:',m.apiKey()!==null)})\"",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.0",
+    "@deepseek-ai/cordis-plugin-loader": "*",
+    "@deepseek-ai/dsh-compaction": "*",
+    "@deepseek-ai/dsh-compaction-basic": "*",
+    "@deepseek-ai/dsh-home-paths": "*",
+    "@deepseek-ai/dsh-storage-domain": "*",
+    "@deepseek-ai/dsh-tools": "*",
+    "@deepseek-ai/schemastery": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-compaction": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-storage-domain": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-compaction-basic": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-home-paths": {
+      "optional": true
+    },
+    "@deepseek-ai/cordis-plugin-loader": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.4",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-commands": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-compaction": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-compaction-basic": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-scope": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-format-v3-to-v4": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-storage": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-storage-domain": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/schemastery": "3.18.2",
+    "@playwright/test": "^1.64.1",
+    "@types/node": "^22.20.3",
+    "@types/react": "~18.3.1",
+    "c8": "^12.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "isomorphic-git": "^1.42.2",
+    "zod": "^4.4.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fractalsynapse/dsh-chapters.git"
+  },
+  "homepage": "https://github.com/fractalsynapse/dsh-chapters#readme",
+  "bugs": {
+    "url": "https://github.com/fractalsynapse/dsh-chapters/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
 }