@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.21

package/lib/archive.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Archive writer — the first I/O layer, behind an injected fs so it stays testable without a harness.
+ *
+ * Ordering is the whole design here. Reserve numbers → write artifacts → write chapters → verify read-back
+ * → return records for the registry. A crash must be able to leave an orphan file, but never a registry
+ * entry or an index that points at a file which was not written. See docs/architecture.md § Atomicity.
+ *
+ * Deferral is a copy decision, not a data decision: the artifact is written whether or not the chapter body
+ * also inlines it, so a wrong model judgement costs one `read` and never loses text.
+ */
+import type { RenderedChapter } from './types.ts';
+/** Minimal filesystem seam. `ctx.fs` is OPTIONAL in DSH, so absence must be a clean refusal upstream. */
+export interface ArchiveFs {
+    write(path: string, content: string): Promise<void>;
+    read(path: string): Promise<string | undefined>;
+    exists(path: string): Promise<boolean>;
+}
+/** Number allocation through the registry, never by scanning a directory (races a concurrent sibling). */
+export interface NumberAllocator {
+    /** Free an attempt key when NOTHING landed, so a failed door cannot leave keys accumulating. */
+    release?(attemptId: string): Promise<void>;
+    reserve(key: string, count: number): Promise<number[]>;
+    /**
+     * Separate allocation for plan DOCUMENTS (docs/plans-carriage.md § 11), so a plan
+     * never consumes a chapter number or reorders the chapter list. Optional: a writer
+     * without it simply emits no documents, and the chapters still cite their plans.
+     */
+    reservePlan?(key: string, count: number): Promise<number[]>;
+}
+export interface ChapterRecord {
+    number: number;
+    path: string;
+    title: string;
+    summary: string;
+    startSeq: number;
+    endSeq: number;
+    /** Index topics (deterministic floor; P2 enrichment may relabel). */
+    topics: string[];
+    /** user+assistant message count in the chapter (record §7.3 notice line);
+     * absent for records written before counts existed — never a lying zero.
+     * (`| undefined` for the `exactOptionalPropertyTypes` zod round-trip.) */
+    messages?: number | undefined;
+    /**
+     * The exact surface seqs archived, in surface order. Optional because
+     * continuation-path ranges are numeric-contiguous (start/end suffice), but
+     * engine-path spans replace across the log, where start/end are only span
+     * bounds — the set is the truth about coverage. (`| undefined` so the
+     * zod-inferred type satisfies `exactOptionalPropertyTypes` in store.ts.)
+     */
+    shadowedSeqs?: number[] | undefined;
+    /** Body sha256, used to detect on-disk tampering before the text is ever cited. */
+    sha256: string;
+    estimatedTokens: number;
+    artifacts: Array<{
+        path: string;
+        sha256: string;
+        bytes: number;
+    }>;
+    /**
+     * Plans this chapter carries (docs/plans-carriage.md § 2/§ 8): the durable,
+     * machine-readable half of the Plans block. Absent on records written before
+     * the feature — the notice reads `undefined` as "no plans here", never as a
+     * lie. The full bytes live in the cited artifact; the prose lives in the file.
+     */
+    plans?: import('./types.ts').PlanFact[] | undefined;
+    /** Folded plan-mode state at the chapter's end ('unknown' when the log never said). */
+    planMode?: 'active' | 'inactive' | 'unknown' | undefined;
+    /** Where each plan's own `kind: plan` document landed (docs/plans-carriage.md § 11). */
+    planDocs?: Array<{
+        seq: number;
+        path: string;
+        sha256: string;
+    }> | undefined;
+    /**
+     * Set by repair (#60): this record was superseded by chapter `supersededBy`. Set by operator
+     * removal (#255): the chapter's bytes are gone from the store and the mirror, and only this
+     * stub remains — the record, its number and its seqs stay in the registry forever, because
+     * dropping a record would rewind the watermark (`max(endSeq)+1`) and let a spent number be
+     * re-spent (#59). A tombstoned chapter is NOT knowledge — no TOC bullet, no enrichment pass,
+     * no search entry — under EITHER status, through the ONE predicate `isActiveChapter`.
+     */
+    status?: 'superseded' | 'removed' | undefined;
+    supersededBy?: number | undefined;
+    /** ISO instant the operator removed the chapter (#255). Absent on every other record. */
+    removedAt?: string | undefined;
+    /** Why this chapter exists as a replacement, and which number it replaced (`{class, over, at}`). */
+    repairs?: {
+        class: string;
+        over: number;
+        at: number;
+    }[] | undefined;
+}
+export interface WriteResult {
+    records: ChapterRecord[];
+    artifactPathsWritten: string[];
+    /** Duplicate titles, retried attempts reusing numbers, or content that failed read-back. */
+    warnings: string[];
+}
+/** Filesystem-safe, stable, and never empty. Title is display metadata; the number is the identity. */
+export declare function slugify(title: string): string;
+/**
+ * The ONE canonical form of a stored path (#69): **workspace-relative**. `ChapterRecord.path` had two
+ * producers — the doors mint from a relative `artifactStoreRoot`, the compaction realm from a resolved
+ * ABSOLUTE one — so one file could be a cited record by one path and an "unregistered file" by the
+ * other, and `/chapters-repair` then reported its own archive as lost knowledge (measured: 6 records,
+ * chapter 1 of the two longest sessions, each `msgs > 300`, all absolute).
+ *
+ * Relative is the right winner: the store root lives inside the workspace, `read` reaches it, and a
+ * path that survives moving a checkout between machines is the same argument `projectKey` already makes
+ * for the remote over the path. An absolute path OUTSIDE the workspace is passed through unchanged — the
+ * rig legitimately pins an absolute store root per port (#61 item 8), and pretending otherwise would
+ * produce a `../../..` path that resolves nowhere.
+ */
+export declare function toStoredPath(cwd: string | undefined, p: string): string;
+/**
+ * The READ direction of the stored-path dialect: turn a `ChapterRecord.path` back into something the
+ * filesystem understands. `toStoredPath` may hand back an ABSOLUTE path (the rig pins an absolute
+ * `artifactStoreRoot` per port — #61 item 8), and `path.join(cwd, absolute)` CONCATENATES instead of
+ * resolving, so a naive join sends a reader to `<cwd>/tmp/…`, which exists nowhere. Measured on the
+ * `enrich` leg 2026-10-24: the ladder reported `chapter file absent` about a file that was present,
+ * because of exactly this join.
+ */
+export declare function resolveStoredPath(cwd: string | undefined, stored: string): string;
+/** Compare two stored paths in either dialect. Every path COMPARISON goes through this, never `===`. */
+export declare function sameStoredPath(a: string, b: string, cwd?: string): boolean;
+export declare const chapterFileName: (n: number, title: string) => string;
+/** Idempotency key: the same source session + ceiling reuses reserved numbers instead of duplicating. */
+/**
+ * The idempotence key for one archive attempt. `salt` exists for REPAIR (#60): a repair re-rendering a
+ * span the original door keyed would otherwise be swallowed as a retry of that attempt, and a swallowed
+ * repair is indistinguishable from one that worked.
+ */
+export declare const attemptKey: (sourceSessionId: string, archiveCeiling: number, salt?: string) => string;
+export interface WriteInput {
+    fs: ArchiveFs;
+    allocator: NumberAllocator;
+    /** Store root, relative to the session workspace so the `read` tool can reach it. */
+    storeRoot: string;
+    /** Workspace cwd; when given, stored paths are normalized to workspace-relative (#69). */
+    cwd?: string | undefined;
+    /** Directory key — the root of the ancestry tree, not the per-fork id. One dir per tree. */
+    rootSessionId: string;
+    chapters: readonly RenderedChapter[];
+    /** Reuse a prior attempt's allocation when this is a retry of identical work. */
+    attemptId: string;
+}
+export declare function writeArchive(input: WriteInput): Promise<WriteResult>;
+/** Coverage arithmetic: which seqs below the ceiling were NOT archived. Gaps are reported, never silent. */
+export declare function coverage(records: readonly {
+    startSeq: number;
+    endSeq: number;
+}[], archiveCeiling: number, archiveFloor?: number): {
+    covered: number;
+    gaps: Array<{
+        from: number;
+        to: number;
+    }>;
+};
+export type VerifyResult = 'ok' | 'modified' | 'missing';
+/** Called before citing a chapter in an index. Detects accidental drift and single-shot injection. */
+export declare function verifyChapter(fs: ArchiveFs, record: ChapterRecord): Promise<VerifyResult>;

package/lib/archive.js

@@ -0,0 +1,229 @@
+import { sha256 } from "./render.js";
+/** Filesystem-safe, stable, and never empty. Title is display metadata; the number is the identity. */
+export function slugify(title) {
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return slug.length > 0 ? slug.slice(0, 48) : 'chapter';
+}
+/**
+ * The ONE canonical form of a stored path (#69): **workspace-relative**. `ChapterRecord.path` had two
+ * producers — the doors mint from a relative `artifactStoreRoot`, the compaction realm from a resolved
+ * ABSOLUTE one — so one file could be a cited record by one path and an "unregistered file" by the
+ * other, and `/chapters-repair` then reported its own archive as lost knowledge (measured: 6 records,
+ * chapter 1 of the two longest sessions, each `msgs > 300`, all absolute).
+ *
+ * Relative is the right winner: the store root lives inside the workspace, `read` reaches it, and a
+ * path that survives moving a checkout between machines is the same argument `projectKey` already makes
+ * for the remote over the path. An absolute path OUTSIDE the workspace is passed through unchanged — the
+ * rig legitimately pins an absolute store root per port (#61 item 8), and pretending otherwise would
+ * produce a `../../..` path that resolves nowhere.
+ */
+export function toStoredPath(cwd, p) {
+    if (cwd === undefined || cwd === '' || !p.startsWith('/'))
+        return p;
+    const rel = p.startsWith(cwd + '/') ? p.slice(cwd.length + 1) : null;
+    return rel ?? p;
+}
+/**
+ * The READ direction of the stored-path dialect: turn a `ChapterRecord.path` back into something the
+ * filesystem understands. `toStoredPath` may hand back an ABSOLUTE path (the rig pins an absolute
+ * `artifactStoreRoot` per port — #61 item 8), and `path.join(cwd, absolute)` CONCATENATES instead of
+ * resolving, so a naive join sends a reader to `<cwd>/tmp/…`, which exists nowhere. Measured on the
+ * `enrich` leg 2026-10-24: the ladder reported `chapter file absent` about a file that was present,
+ * because of exactly this join.
+ */
+export function resolveStoredPath(cwd, stored) {
+    if (stored.startsWith('/') || cwd === undefined || cwd === '')
+        return stored;
+    return `${cwd.replace(/\/+$/, '')}/${stored}`;
+}
+/** Compare two stored paths in either dialect. Every path COMPARISON goes through this, never `===`. */
+export function sameStoredPath(a, b, cwd) {
+    if (a === b)
+        return true;
+    const root = cwd ?? '';
+    const abs = (p) => (p.startsWith('/') ? p : root === '' ? p : `${root}/${p}`);
+    return abs(a) === abs(b);
+}
+export const chapterFileName = (n, title) => `${String(n).padStart(3, '0')}-${slugify(title)}.md`;
+/** Idempotency key: the same source session + ceiling reuses reserved numbers instead of duplicating. */
+/**
+ * The idempotence key for one archive attempt. `salt` exists for REPAIR (#60): a repair re-rendering a
+ * span the original door keyed would otherwise be swallowed as a retry of that attempt, and a swallowed
+ * repair is indistinguishable from one that worked.
+ */
+export const attemptKey = (sourceSessionId, archiveCeiling, salt) => `${sourceSessionId}@${archiveCeiling}${salt !== undefined ? `+${salt}` : ''}`;
+/** Join without importing path, so the seam stays portable between ctx.fs and node:fs. */
+const join = (...parts) => parts.filter(Boolean).join('/').replace(/\/{2,}/g, '/');
+export async function writeArchive(input) {
+    const { fs, allocator, storeRoot, rootSessionId, chapters } = input;
+    const cwd = input.cwd;
+    if (chapters.length === 0)
+        throw new Error('writeArchive called with no chapters');
+    const treeDir = join(storeRoot, rootSessionId);
+    const warnings = [];
+    // 1. Reserve BEFORE touching the filesystem, so a crash cannot re-use a number.
+    const numbers = await allocator.reserve(input.attemptId, chapters.length);
+    if (numbers.length !== chapters.length) {
+        throw new Error(`allocator returned ${numbers.length} numbers for ${chapters.length} chapters`);
+    }
+    const records = [];
+    const artifactPathsWritten = [];
+    const docPathsByChapter = new Map();
+    const seenArtifact = new Map(); // sha256 → path, for subtree dedup
+    const seenFile = new Set();
+    for (let i = 0; i < chapters.length; i++) {
+        const chapter = chapters[i];
+        const number = numbers[i];
+        let fileName = chapterFileName(number, chapter.range.title);
+        if (seenFile.has(fileName)) {
+            // Same title, same number prefix — disambiguate rather than let one chapter overwrite another.
+            fileName = fileName.replace(/\.md$/, `-${number}.md`);
+            warnings.push(`title collision resolved for "${chapter.range.title}" → ${fileName}`);
+        }
+        seenFile.add(fileName);
+        const chapterPath = join(treeDir, 'chapters', fileName);
+        // 2. Artifacts first: the chapter body cites these paths, so they must exist before it does.
+        for (const artifact of chapter.artifacts) {
+            const existing = seenArtifact.get(artifact.sha256);
+            if (existing !== undefined)
+                continue; // identical result in this batch
+            if (await fs.exists(join(treeDir, artifact.path))) { // identical result from an earlier fork
+                seenArtifact.set(artifact.sha256, artifact.path);
+                continue;
+            }
+            await fs.write(join(treeDir, artifact.path), artifact.content);
+            seenArtifact.set(artifact.sha256, artifact.path);
+            artifactPathsWritten.push(join(treeDir, artifact.path));
+        }
+        // 2b. PLAN DOCUMENTS (docs/plans-carriage.md § 11). One file per plan in this
+        // range, written under the SAME tree as chapters so the pool transport, the
+        // mirror rehydrate and the corpus index carry them with no special casing.
+        // Numbers come from their own registry counter — never from a directory scan.
+        const docs = chapter.stats.planDocs ?? [];
+        if (docs.length > 0 && allocator.reservePlan !== undefined) {
+            const numbers = await allocator.reservePlan(`${input.attemptId}#${chapterPath}`, docs.length);
+            const used = new Set();
+            for (let i = 0; i < docs.length; i++) {
+                const doc = docs[i];
+                const number = numbers[i];
+                // `plan-NNN-` never `NNN-plan-`: a directory listing must not read like two
+                // chapters claim number 001 — chapters and plan documents count separately.
+                let name = `plan-${String(number).padStart(3, '0')}-${slugify(doc.title)}.md`;
+                if (used.has(name) || seenFile.has(name))
+                    name = name.replace(/\.md$/, `-duplicate-${number}.md`);
+                used.add(name);
+                seenFile.add(name);
+                const docPath = join(treeDir, 'chapters', name);
+                const body = `${doc.body}\n`;
+                const fm = [
+                    '---',
+                    `kind: plan`,
+                    `title: ${JSON.stringify(doc.title)}`,
+                    `status: ${doc.status}`,
+                    `planSeq: ${doc.seq}`,
+                    `chapter: ${JSON.stringify(chapterPath)}`,
+                    // The chapter's Plans block cites the content-addressed blob; the blob and
+                    // this document are the SAME bytes, so the sha ties the two handles together
+                    // and a reader can prove neither drifted.
+                    `sha256: ${doc.sha256}`,
+                    `bodySha256: ${sha256(body)}`,
+                    `tokens: ${doc.estTokens}  # chars/4 estimate`,
+                    `topics: [${doc.topics.map((t) => JSON.stringify(t)).join(', ')}]`,
+                    `artifacts: 0`,
+                    'unrenderedSeqs: []',
+                    '---',
+                    '',
+                ].join('\n');
+                await fs.write(docPath, fm + body);
+                const read = await fs.read(docPath);
+                if (read === undefined || read !== fm + body) {
+                    warnings.push(`read-back failed for the plan document, citing the chapter only: ${docPath}`);
+                    continue;
+                }
+                artifactPathsWritten.push(docPath);
+                const list = docPathsByChapter.get(chapterPath) ?? [];
+                list.push({ seq: doc.seq, path: docPath, sha256: doc.sha256 });
+                docPathsByChapter.set(chapterPath, list);
+            }
+        }
+        // 3. The chapter itself.
+        await fs.write(chapterPath, chapter.markdown);
+        // 4. Read-back verification. A file that does not come back byte-identical is not citable.
+        const readBack = await fs.read(chapterPath);
+        if (readBack === undefined) {
+            warnings.push(`read-back failed (missing): ${chapterPath}`);
+            continue;
+        }
+        // Hash the whole file, so verifyChapter() can re-check it with no knowledge of frontmatter layout.
+        const bodyHash = sha256(chapter.markdown);
+        if (readBack !== chapter.markdown) {
+            warnings.push(`read-back mismatch, refusing to cite: ${chapterPath}`);
+            continue;
+        }
+        if (chapter.stats.unrenderedSeqs.length > 0) {
+            warnings.push(`${chapterPath}: ${chapter.stats.unrenderedSeqs.length} event(s) rendered no output (${chapter.stats.unrenderedSeqs.join(', ')})`);
+        }
+        if (chapter.stats.overTarget) {
+            warnings.push(`${chapterPath}: ${chapter.stats.estimatedTokens} tokens over chapterTokenTarget — split at the next boundary, do not clip`);
+        }
+        records.push({
+            number,
+            path: toStoredPath(cwd, chapterPath),
+            title: chapter.range.title,
+            summary: chapter.range.summary,
+            startSeq: chapter.range.startSeq,
+            endSeq: chapter.range.endSeq,
+            topics: chapter.topics,
+            messages: chapter.stats.messages,
+            sha256: bodyHash,
+            estimatedTokens: chapter.stats.estimatedTokens,
+            artifacts: chapter.artifacts.map((a) => ({ path: join(treeDir, a.path), sha256: a.sha256, bytes: a.bytes })),
+            // Plans ride along ONLY when the chapter has them: an absent field means
+            // "no plans here" for a pre-feature record, and an empty array here would
+            // be read as a fact by the notice builder.
+            ...(chapter.stats.plans !== undefined && chapter.stats.plans.length > 0 ? { plans: chapter.stats.plans } : {}),
+            ...(chapter.stats.planMode !== undefined && chapter.stats.planMode !== 'unknown' ? { planMode: chapter.stats.planMode } : {}),
+            ...(() => {
+                const docs = docPathsByChapter.get(chapterPath);
+                return docs !== undefined && docs.length > 0 ? { planDocs: docs } : {};
+            })(),
+        });
+    }
+    // #59: an attempt that landed NOTHING must not leave a reservation key behind forever — that is how
+    // numbers 20 and 37 stayed burned with no file and no record. PARTIAL landing keeps the key on
+    // purpose: a retry of the same attempt reuses those numbers instead of writing a second chapter
+    // over the same span.
+    if (records.length === 0 && allocator.release !== undefined) {
+        await allocator.release(input.attemptId);
+        warnings.push(`attempt ${input.attemptId} landed no chapter; its reservation key was released`);
+    }
+    return { records, artifactPathsWritten, warnings };
+}
+/** Coverage arithmetic: which seqs below the ceiling were NOT archived. Gaps are reported, never silent. */
+export function coverage(records, archiveCeiling, archiveFloor = 0) {
+    const sorted = [...records].sort((a, b) => a.startSeq - b.startSeq);
+    const gaps = [];
+    // Start at the floor, not at the first chapter: a set that skips the opening of the conversation is
+    // exactly the silent-history-loss this function exists to catch.
+    let cursor = archiveFloor;
+    let covered = 0;
+    for (const r of sorted) {
+        if (r.startSeq > cursor)
+            gaps.push({ from: cursor, to: r.startSeq - 1 });
+        cursor = Math.max(cursor, r.endSeq + 1);
+        covered += r.endSeq - r.startSeq + 1;
+    }
+    if (cursor <= archiveCeiling)
+        gaps.push({ from: cursor, to: archiveCeiling });
+    return { covered, gaps };
+}
+/** Called before citing a chapter in an index. Detects accidental drift and single-shot injection. */
+export async function verifyChapter(fs, record) {
+    const text = await fs.read(record.path);
+    if (text === undefined)
+        return 'missing';
+    if (sha256(text) !== record.sha256)
+        return 'modified';
+    return 'ok';
+}
+//# sourceMappingURL=archive.js.map

package/lib/archive.js.map

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

package/lib/arrival.d.ts

@@ -0,0 +1,23 @@
+export interface ArrivalSessionShim {
+    surface: {
+        nodes: number[];
+    };
+    eventAt(seq: number): {
+        type: string;
+        data: unknown;
+    } | undefined | null;
+    append(type: string, data: unknown, opts?: unknown): unknown;
+}
+export declare const ARRIVAL_MARKER = "[dsh:artifact";
+export interface ArrivalOpts {
+    cwd: string;
+    storeRoot: string;
+    floorTokens: number;
+    /** message → estimated tokens (host tokenMeter injected; tests use chars/4). */
+    estimate: (message: unknown) => number;
+}
+export interface ArrivalResult {
+    stubbed: number;
+    detail?: string;
+}
+export declare function applyArrivalStubs(session: ArrivalSessionShim, opts: ArrivalOpts): Promise<ArrivalResult>;

package/lib/arrival.js

@@ -0,0 +1,125 @@
+/**
+ * Arrival-time artifacting (record architecture.md amendment, 2026-09-19):
+ * tool results at or above the floor never get to become context. The blob
+ * goes to the content-addressed artifact store; the surface node is replaced
+ * IN PLACE (the pruner's proven single-node form: a shadowing event + a
+ * replacement append carrying `surfaceOp: replace`) with a stub that cites
+ * the path and the query tool. Runs at the head of compactIfNeeded/compactNow,
+ * i.e. inside the awaited `agent/pre-step` chain, BEFORE the next request is
+ * composed — so the blob is prefilled zero times, ever.
+ *
+ * A plain factory over structural shims, per house rule (the r28 lesson:
+ * the LOGIC must be L0-testable against the real host Session shape).
+ */
+import { artifactPath, sha256 } from "./render.js";
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { resolveStoreRoot } from "./store.js";
+export const ARRIVAL_MARKER = '[dsh:artifact';
+const kb = (n) => n < 1024 ? `${n} B` : `${(n / 1024).toFixed(1)} KB`;
+export async function applyArrivalStubs(session, opts) {
+    let stubbed = 0;
+    // #131: resolve each result's tool name once, so an artifact ANSWER can be exempted below.
+    //
+    // Arrival-time deferral was applied to `chapters_artifact`'s own output: asking to read a stored blob returned
+    // ANOTHER stub pointing at ANOTHER blob, so the store became unreachable at exactly the sizes it exists for, and
+    // the `arrival` leg's model called the tool 20 times before the run gave up. A query answer is the payload the
+    // caller reached for — economizing it is a cycle, not context relief. The tool already bounds its own output per
+    // action (`limit`, `maxTokens`), so nothing needs a second layer here.
+    const nameByCall = new Map();
+    for (const seq of [...session.surface.nodes]) {
+        const ev = session.eventAt(seq);
+        if (ev?.type !== 'tool/call')
+            continue;
+        const d = ev.data;
+        if (typeof d?.callId === 'string' && typeof d?.name === 'string')
+            nameByCall.set(d.callId, d.name);
+    }
+    const isArtifactAnswer = (message) => {
+        const src = message.source;
+        const wrappers = Array.isArray(message.content) ? message.content : [];
+        const ids = [src?.callId, message.toolCallId, ...wrappers.map((w) => w?.toolCallId)];
+        return ids.some((id) => typeof id === 'string' && nameByCall.get(id) === 'chapters_artifact');
+    };
+    for (const seq of [...session.surface.nodes]) {
+        const event = session.eventAt(seq);
+        if (event?.type !== 'tool/result')
+            continue;
+        const data = event.data;
+        if (data?.message === undefined)
+            continue;
+        // REAL shape (measured e2e, 2026-09-19): message.content blocks are
+        // { type: 'tool-result', toolCallId, isError, content: [{type:'text',text}] }
+        // — the text is nested one level below the wrapper. A unit fixture that
+        // invented a flat shape hid this for a whole run; the fake mirrors the
+        // real from now on.
+        const blocks = Array.isArray(data.message.content) ? data.message.content
+            : typeof data.message.content === 'string' ? [{ type: 'text', text: data.message.content }] : [];
+        // TWO real shapes, one per host generation — both measured, neither assumed.
+        //  0.1.x: content = [{ type: 'tool-result', toolCallId, isError, content: [{type:'text',text}] }]
+        //  0.2.0-rc.2: content = [{ type: 'text', text }]  ← flattened; measured 2026-10-22 in the
+        //    arrival leg's own durable log (seq 51, 54,763 bytes; message keys role,source,toolCallId,
+        //    content,isError,id; block keys type,text).
+        // Recognizing only the first meant `wrappers.length === 0` on EVERY result of the new host:
+        // nothing stubbed, `detail` unset, and no line anywhere — which is how arrival artifacting
+        // vanished from the whole acceptance chain while the engine's entry line proved it was running.
+        const wrappers = blocks.filter((b) => b?.type === 'tool-result');
+        const carriers = wrappers.length > 0 ? wrappers : blocks.filter((b) => b?.type === 'text' && typeof b.text === 'string');
+        if (carriers.length === 0)
+            continue;
+        const textOf = (w) => Array.isArray(w.content)
+            ? w.content.filter((c) => c?.type === 'text').map((c) => c.text ?? '').join('')
+            : typeof w.content === 'string' ? w.content
+                : typeof w.text === 'string' ? w.text : '';
+        const text = carriers.map(textOf).join('');
+        if (text.length === 0 || text.includes(ARRIVAL_MARKER))
+            continue;
+        if (isArtifactAnswer(data.message))
+            continue; // #131 — a pointer to a pointer is not relief
+        const tokens = opts.estimate(data.message);
+        if (tokens < opts.floorTokens)
+            continue;
+        const hash = sha256(text);
+        const rel = artifactPath(hash);
+        const abs = path.join(resolveStoreRoot(opts.cwd, opts.storeRoot), rel);
+        try {
+            await fs.mkdir(path.dirname(abs), { recursive: true, mode: 0o700 });
+            // content-addressed: rewriting identical bytes is a no-op by definition
+            await fs.writeFile(abs, text, 'utf8');
+        }
+        catch (error) {
+            // the blob stays inline — arrival artifacting is an optimization, and a
+            // disk problem must never eat the conversation (loud via detail).
+            return { stubbed, detail: `artifact write failed (${String(error?.message ?? error)}); ${stubbed} node(s) stubbed before the failure` };
+        }
+        const stub = `${ARRIVAL_MARKER} ${hash.slice(0, 12)}] ${kb(text.length)} ≈ ${tokens} tok stored at ${rel} — query it with chapters_artifact (path '${rel}' or the sha): action 'toc' for the heading map with line numbers, 'search' for term hits as small blocks, 'read' for exact line ranges. The full result is NOT elsewhere in this context; re-running the original tool only recreates it.`;
+        // the stub goes back in the shape it arrived: nested wrappers keep their `content` blocks,
+        // flattened v4 blocks keep their own `text` and their `type: 'text'` — a replacement that
+        // changed the block type would be a new shape assumption on the read side.
+        const stubbedCarriers = carriers.map((w, i) => (wrappers.length > 0 && Array.isArray(w.content))
+            ? { ...w, content: [{ type: 'text', text: i === 0 ? stub : '' }] }
+            : { ...w, text: i === 0 ? stub : '' });
+        const message = {
+            ...data.message,
+            content: [...blocks.filter((b) => !carriers.includes(b)), ...stubbedCarriers],
+        };
+        try {
+            session.append('compaction/prune', {
+                shadowedRange: { start: seq, end: seq },
+                shadowedSeqs: [seq],
+                shadowedTokenCount: tokens,
+                by: 'dsh-chapters-arrival',
+            });
+            session.append('tool/result', { ...data, message }, {
+                surfaceOp: { op: 'replace', startSeq: seq, endSeq: seq },
+                sourceEventSeqs: [seq],
+            });
+            stubbed++;
+        }
+        catch (error) {
+            return { stubbed, detail: `surface replace refused at seq ${seq} (${String(error?.message ?? error)})` };
+        }
+    }
+    return { stubbed };
+}
+//# sourceMappingURL=arrival.js.map

package/lib/arrival.js.map

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

package/lib/artifact-query.d.ts

@@ -0,0 +1,62 @@
+export type TocEntry = {
+    line: number;
+    depth: number;
+    title: string;
+};
+/**
+ * Resolve a user/model-supplied reference to an absolute artifact path INSIDE
+ * the store. Accepts a 64-hex sha, 'artifacts/xx/<sha>.txt', or an absolute
+ * path. Throws on anything escaping the store — this tool is read-only, the
+ * containment is the whole security story.
+ */
+export declare function resolveArtifactPath(storeDir: string, ref: string): string;
+/**
+ * Markdown heading map with 1-based line numbers — a 300-page book arrives
+ * with its own table of contents (fenced code blocks are skipped so '#
+ * comments' inside them never masquerade as headings).
+ */
+export declare function buildToc(text: string, maxEntries?: number): {
+    entries: TocEntry[];
+    truncated: boolean;
+};
+export type SearchBlock = {
+    start: number;
+    end: number;
+    lines: string[];
+};
+/**
+ * Case-insensitive query over lines: regex when it compiles, literal phrase
+ * otherwise. Matches expand to ±context lines and overlapping windows merge;
+ * the pack stops at maxTokens and REPORTS what it left behind.
+ */
+export declare function searchArtifact(text: string, query: string, opts?: {
+    maxTokens?: number;
+    contextLines?: number;
+}): {
+    total: number;
+    blocks: SearchBlock[];
+    truncated: boolean;
+    remaining: number;
+};
+/** Exact line window (1-based inclusive), capped per call; bounds reported. */
+export declare function readLines(text: string, offset: number, limit: number, hardCap?: number): {
+    start: number;
+    end: number;
+    of: number;
+    lines: string[];
+};
+/** Load an artifact with a size guard; returns text + totals for the pack. */
+export declare function loadArtifact(absPath: string): {
+    text: string;
+    bytes: number;
+    lines: number;
+};
+/**
+ * Store-first, mirror-second resolution (measured 2026-09-28, treeseed pool
+ * audit): chapters cite 'artifacts/aa/<sha>.txt' — on another machine the blob
+ * lives in the knowledge MIRROR (artifacts/<projectKey>/aa/<sha>.txt, one dir
+ * per linked project), not the local store. Returns the absolute path of the
+ * first existing match, or null. Containment holds on BOTH roots; '..' can
+ * never escape.
+ */
+export declare function resolveArtifactWithMirror(storeDir: string, ref: string, mirrorDir: string): string | null;