@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.20

package/lib/engine-core.js

@@ -0,0 +1,531 @@
+import { chapterTopics } from "./signature.js";
+import { estimateTokens, noticeIndexSection, renderChapter } from "./render.js";
+import { isInjectedProse } from "./injections.js";
+import { lineageOf } from "./types.js";
+import { slugify, toStoredPath } from "./archive.js";
+import { isFinalized } from "./registry.js";
+/** provider tag written into `compaction/summary` — our event-scan discriminator. */
+export const CHAPTERS_PROVIDER = 'dsh-chapters';
+export const DETERMINISTIC_MODEL = 'deterministic';
+/** Framing tags the host's summarizer wraps checkpoints in (compaction-basic summarizer.ts:21-22). */
+export const SUMMARY_OPEN_TAG = '<compacted-summary>';
+export const SUMMARY_CLOSE_TAG = '</compacted-summary>';
+export const ENGINE_CONFIG_DEFAULTS = {
+    artifactStoreRoot: '.dsh-chapters',
+    knowledgeMirrorDir: '.dsh-knowledge',
+    noticeIndexCap: 6,
+    openRequestCarryMaxChars: 4000,
+    lastResortArtifact: true,
+    diagnosticsMaxBytes: 8388608,
+    chapterTokenTarget: 8000,
+    toolResultDeferFloorTokens: 200,
+    mergeThreshold: 0.3,
+    chapterLimit: 8000,
+    toolResultArtifactTokens: 8000,
+    planInlineChars: 900,
+    callArgArtifactTokens: 0,
+    elicitedPlot: true,
+    plansInCheckpoint: true,
+    planCheckpointChars: 1600,
+};
+// ---------------------------------------------------------------- text helpers
+const messageText = (msg) => (msg?.content ?? []).filter((b) => b.type === 'text').map((b) => b.text ?? '').join('\n');
+/** Every `<compacted-summary>…</compacted-summary>` block in the region, in order. */
+export function extractCheckpointBlocks(messages) {
+    const blocks = [];
+    for (const msg of messages) {
+        const text = messageText(msg);
+        let from = 0;
+        for (;;) {
+            const open = text.indexOf(SUMMARY_OPEN_TAG, from);
+            if (open === -1)
+                break;
+            const close = text.indexOf(SUMMARY_CLOSE_TAG, open);
+            if (close === -1) {
+                blocks.push(text.slice(open + SUMMARY_OPEN_TAG.length));
+                break;
+            }
+            blocks.push(text.slice(open + SUMMARY_OPEN_TAG.length, close));
+            from = close + SUMMARY_CLOSE_TAG.length;
+        }
+    }
+    return blocks;
+}
+/** `N. [Title](path) — summary` as rendered by renderIndex; the accumulation format. */
+const BULLET = /^\s*\d+\.\s+\[(.*?)\]\((.*?)\)\s+—\s+(.*)$/;
+/**
+ * Merge-forward: parse prior bullets out of every checkpoint block. Lines that
+ * are not our bullet format (e.g. an LLM summary produced by `basic` before
+ * this engine took over) are returned as verbatim carry-overs — dropping them
+ * would be exactly the loss this plugin exists to prevent.
+ */
+export function parseTocState(blocks) {
+    const bullets = [];
+    const carriedProse = [];
+    const seen = new Set();
+    for (const block of blocks) {
+        let blockHadBullets = false;
+        for (const line of block.split('\n')) {
+            const m = BULLET.exec(line);
+            if (m === null)
+                continue;
+            blockHadBullets = true;
+            const bullet = { title: m[1], path: m[2], summary: m[3] };
+            if (seen.has(bullet.path))
+                continue; // accumulation dedups by path; numbers may repeat across roots
+            seen.add(bullet.path);
+            bullets.push(bullet);
+        }
+        if (!blockHadBullets && block.trim().length > 0)
+            carriedProse.push(block.trim());
+    }
+    return { bullets, carriedProse };
+}
+// ---------------------------------------------------------------- transaction scanning
+/**
+ * The open transaction's compactionId: the latest `compaction/start` with no
+ * later `compaction/end` carrying the same id. The base appends the start
+ * BEFORE awaiting summarize (region.ts:211) and the durable lock admits only
+ * one open transaction per session — so a backward scan finds exactly it.
+ */
+export function findOpenCompactionId(session) {
+    const closed = new Set();
+    for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+        const ev = session.eventAt(seq);
+        const raw = ev?.data?.compactionId;
+        const cid = typeof raw === 'string' && raw.length > 0 ? raw : null;
+        if (ev?.type === 'compaction/end' && cid !== null) {
+            closed.add(cid);
+            continue;
+        }
+        if (ev?.type === 'compaction/start' && cid !== null && !closed.has(cid))
+            return cid;
+    }
+    return null;
+}
+/** All OUR finalized-or-not summary events (provider-tagged), oldest first. */
+export function scanChaptersSummaries(session) {
+    const out = [];
+    for (let seq = 0; seq < session.seq; seq += 1) {
+        const ev = session.eventAt(seq);
+        if (ev?.type !== 'compaction/summary')
+            continue;
+        if (ev.data?.provider !== CHAPTERS_PROVIDER)
+            continue;
+        const cid = ev.data?.compactionId;
+        const shadowed = ev.data?.shadowedSeqs;
+        if (typeof cid !== 'string' || !Array.isArray(shadowed))
+            continue;
+        out.push({ compactionId: cid, summarySeq: seq, shadowedSeqs: shadowed.map(Number) });
+    }
+    return out;
+}
+// ---------------------------------------------------------------- citation resolution
+/**
+ * Follow `tool/result` replacement chains to the first version (the un-pruned
+ * original). Only single-cited tool results qualify — a compaction checkpoint
+ * `user/message` also carries sourceEventSeqs, and following THOSE would pull
+ * lifecycle bookkeeping into chapter bodies.
+ */
+export function resolveOriginalEvent(session, seq) {
+    let cursor = seq;
+    const guard = new Set();
+    for (;;) {
+        if (guard.has(cursor))
+            throw new Error(`resolveOriginalEvent: citation cycle at seq ${cursor}`);
+        guard.add(cursor);
+        const ev = session.eventAt(cursor);
+        if (ev === undefined)
+            throw new Error(`resolveOriginalEvent: missing event at ${cursor}`);
+        if (ev.type !== 'tool/result')
+            return ev;
+        const cited = ev.sourceEventSeqs;
+        if (cited === undefined || cited.length !== 1)
+            return ev;
+        cursor = cited[0];
+    }
+}
+/** Deterministic title/summary from region content. Never model-authored (invariant 4 — the model is absent). */
+export function deriveIdentity(messages, hasCheckpoint, 
+/**
+ * A plan submitted inside this span, when there is one (docs/plans-carriage.md
+ * § 6): the submission IS the identity of a planning chapter, and it beats the
+ * first prose line the same way a file's own header beats a guess about it.
+ * Callers that hold events pass it; the summarize path, which sees provider
+ * messages only, passes nothing and keeps the old derivation.
+ */
+planTitle) {
+    // Title source: the first USER message that is actual human/agent prose.
+    // Harness injections (system reminders, runtime-context snapshots) ride as
+    // user messages too — an earlier fork titled a chapter "System reminder 1"
+    // from a runtime snapshot that happened to open the span. Skip them; the
+    // r29 command tests pin this behavior.
+    // The same predicate that screens chapter BODIES chooses a title (#59). Two lists of what counts as
+    // injected context is how a runtime snapshot became a filename and a TOC citation.
+    const firstUser = messages.find((m) => m.role === 'user'
+        && !messageText(m).includes(SUMMARY_OPEN_TAG)
+        && !isInjectedProse(messageText(m)));
+    const userCount = messages.filter((m) => m.role === 'user').length;
+    const assistantCount = messages.filter((m) => m.role === 'assistant').length;
+    const headLine = planTitle !== undefined && planTitle.trim() !== ''
+        ? planTitle.trim()
+        : firstUser === undefined ? '' : messageText(firstUser).split('\n')[0].trim();
+    const title = headLine.length > 0
+        ? headLine.length > 72 ? `${headLine.slice(0, 72)}…` : headLine
+        : hasCheckpoint ? 'Earlier history' : 'Conversation span';
+    return {
+        title,
+        summary: `${userCount} user / ${assistantCount} assistant messages (${estimateTokens(messages.map(messageText).join(' '))} est tokens)`,
+    };
+}
+/** Workspace-relative chapter path for a reserved number. */
+export const chapterPathFor = (config, rootSession, number, title) => 
+// #69: normalized at the mint. The realm resolves an ABSOLUTE store root to reach the filesystem, but
+// the RECORD must carry the workspace-relative form, or chapter 1 written by compaction never matches
+// the same file listed from disk and the auditor reports its own archive as lost knowledge.
+toStoredPath(config.workspaceCwd, `${config.artifactStoreRoot.replace(/\/+$/, '')}/${rootSession}/chapters/${String(number).padStart(3, '0')}-${slugify(title)}.md`);
+/**
+ * Map the prepared summarize input back to the log seqs it was built from
+ * (the host builds region messages as `deriveEventMessage(eventAt(seq))` for
+ * the shadowed selection). Returns null — meaning "use the legacy
+ * single-chapter path" — whenever the Session lacks the mapping API, nothing
+ * matches, or MORE THAN ONE contiguous run matches (duplicate small
+ * messages are common; guessing a wrong span would cite chapters that never
+ * cover their seqs, and an honest legacy chapter beats that).
+ */
+export function reconstructShadowedSeqs(session, input) {
+    const nodes = session.surface?.nodes;
+    const derive = session.deriveEventMessage;
+    if (nodes === undefined || nodes.length === 0 || derive === undefined)
+        return null;
+    let region = input.messages;
+    if (region[0]?.role === 'system')
+        region = region.slice(1); // the prepended system head
+    if (region.length === 0)
+        return null;
+    const encoded = region.map((m) => JSON.stringify(m));
+    const matches = [];
+    for (let start = 0; start < nodes.length && matches.length < 2; start += 1) {
+        const seqs = [];
+        let mi = 0;
+        let ok = true;
+        for (let ni = start; ni < nodes.length && mi < encoded.length; ni += 1) {
+            const ev = session.eventAt(nodes[ni].seq);
+            if (ev === undefined)
+                continue;
+            const msg = derive(ev);
+            if (msg === null || msg === undefined)
+                continue;
+            if (JSON.stringify(msg) !== encoded[mi]) {
+                ok = false;
+                break;
+            }
+            seqs.push(ev.seq);
+            mi += 1;
+        }
+        if (ok && mi === encoded.length && seqs.length > 0)
+            matches.push(seqs);
+    }
+    return matches.length === 1 ? matches[0] : null;
+}
+/**
+ * The summarize-time plan: merge prior bullets, derive this span's identity,
+ * reserve numbers (attempt-keyed by the OPEN transaction's compactionId),
+ * build the TOC. Pure given the state; the caller persists the returned
+ * state change BEFORE this text can ever be cited.
+ *
+ * `composition` (r29): topic-sequential ranges from the composer (record
+ * §4.2), spanning the whole selected region head-to-tail (the adapter
+ * absorbs any strays). Present => reserve one number per chapter and cite
+ * them all; absent => the legacy single-chapter identity path, unchanged.
+ */
+export function planSummarize(session, state, input, config, reserveFn, 
+/** Required: the caller fails loudly when no `compaction/start` is open. */
+compactionId, composition = null, 
+/** Model-authored plot note carried into this checkpoint (may be null). */
+plot = null, 
+/**
+ * The operative plan, already rendered as checkpoint prose by `carryActivePlan`
+ * (plans.ts). Carried on BOTH the composed and the legacy path, because the
+ * composed path is where real pressure compaction lands. Note the asymmetry this
+ * deliberately does NOT touch: `plot` is still only prefixed on the legacy path
+ * (`:415`), and changing that would rewrite checkpoint bytes for every plot-carrying
+ * session — i.e. the committed tapes. Plans are new, so carrying them is free.
+ */
+planCarry = null, 
+/**
+ * #50 §7.6 — the rules block carried across this checkpoint, already rendered
+ * by the ONE builder that renders it for the notice too (`rules.buildRulesSection`).
+ * This is the hole the round exists to close: `leadSections` was
+ * `[planSection, plotSection]`, so a plan and a plot survived a compaction and a
+ * RULE did not. Null (nothing active, or the corpus unreadable) renders ZERO
+ * bytes — which is what keeps every committed plot-carrying checkpoint intact.
+ */
+rulesCarry = null) {
+    const planSection = planCarry !== null && planCarry.trim() !== ''
+        ? `Active plan — carried across this checkpoint (it is STILL the work directive):\n\n${planCarry.trim()}`
+        : null;
+    const rulesSection = rulesCarry !== null && rulesCarry.trim() !== '' ? rulesCarry.trim() : null;
+    const leadSections0 = [planSection, rulesSection].filter((x) => x !== null && x !== '');
+    const blocks = extractCheckpointBlocks(input.messages);
+    const { bullets, carriedProse } = parseTocState(blocks);
+    const identity = deriveIdentity(input.messages, blocks.length > 0);
+    const attemptId = `compaction:${compactionId}`;
+    if (composition !== null && composition.length > 0) {
+        const reserved = reserveFn(state, attemptId, composition.length);
+        const usedPaths = new Set();
+        const chapters = composition.map((range, i) => {
+            const number = reserved.numbers[i];
+            let path = chapterPathFor(config, state.rootSession, number, range.title);
+            // Mirror writeArchive's collision rule so the cited path can never dangle.
+            if (usedPaths.has(path))
+                path = path.replace(/\.md$/, `-${number}.md`);
+            usedPaths.add(path);
+            return { number, path, title: range.title, summary: range.summary, startSeq: range.startSeq, endSeq: range.endSeq };
+        });
+        const allBullets = [...bullets, ...chapters.map((c) => ({ title: c.title, path: c.path, summary: c.summary }))];
+        const index = noticeIndexSection(allBullets, config.noticeIndexCap);
+        const quote = (p) => p.split('\n').map((l) => `> ${l}`).join('\n');
+        const composedParts = [
+            `Chapter archive: ${allBullets.length} chapter(s) under ${config.artifactStoreRoot}/ — verbatim text; reload any with the read tool on its path.`,
+            'Tool results shown as head+…+tail in the replaced history were archived in full; oversized ones are file references inside the chapter.',
+            index,
+        ];
+        if (carriedProse.length > 0) {
+            composedParts.push('Earlier summary carried forward (not chapter-formatted):', ...carriedProse.map(quote));
+        }
+        return {
+            plan: {
+                tocText: leadSections0.length === 0
+                    ? composedParts.join('\n\n')
+                    : `${leadSections0.join('\n\n')}\n\n${composedParts.join('\n\n')}`,
+                numbers: reserved.numbers,
+                chapter: { title: chapters[0].title, summary: chapters[0].summary, path: chapters[0].path },
+                chapters,
+            },
+            state: reserved.state,
+        };
+    }
+    const reserved = reserveFn(state, attemptId, 1);
+    const number = reserved.numbers[0];
+    const path = chapterPathFor(config, state.rootSession, number, identity.title);
+    const allBullets = [...bullets, { title: identity.title, path, summary: identity.summary }];
+    const index = noticeIndexSection(allBullets, config.noticeIndexCap);
+    const quote = (p) => p.split('\n').map((l) => `> ${l}`).join('\n');
+    const parts = [
+        `Chapter archive: ${allBullets.length} chapter(s) under ${config.artifactStoreRoot}/ — verbatim text; reload any with the read tool on its path.`,
+        'Tool results shown as head+…+tail in the replaced history were archived in full; oversized ones are file references inside the chapter.',
+        index,
+    ];
+    if (carriedProse.length > 0) {
+        parts.push('Earlier summary carried forward (not chapter-formatted):', ...carriedProse.map(quote));
+    }
+    const plotSection = plot !== null && plot.trim() !== ''
+        ? `Working plot (model-authored, carried across this checkpoint):\n\nPLOT: ${plot.trim()}\n\n(If it has gone stale, revise it in your next reply.)`
+        : null;
+    const leadSections = [planSection, rulesSection, plotSection].filter((x) => x !== null && x !== '');
+    const tocText = leadSections.length === 0 ? parts.join('\n\n') : `${leadSections.join('\n\n')}\n\n${parts.join('\n\n')}`;
+    return {
+        plan: {
+            tocText,
+            numbers: reserved.numbers,
+            chapter: { title: identity.title, summary: identity.summary, path },
+        },
+        state: reserved.state,
+    };
+}
+/**
+ * The plot note (architecture.md amendment 2026-09-19): a short forward-
+ * maintained statement of what the agent is MID-WAY through, authored by the
+ * model itself and carried forward across every in-place checkpoint.
+ */
+export const PLOT_MARKER = 'PLOT:';
+/**
+ * Latest plot paragraph in the region about to be shadowed. Assistant text
+ * wins; a PLOT carried in an earlier checkpoint (user-role, plugin-sourced)
+ * is the fallback, so the thread survives repeatedly shadowed chains.
+ * Returns the paragraph text WITHOUT the marker line, capped at maxChars.
+ *
+ * Shaped by the 2026-09-25 real-world audit (treeseed's first four-session
+ * run): ALL EIGHT checkpoints carried a "plot" that was actually the persona
+ * suffix's own instruction text — `...end each reply with one line beginning
+ * 'PLOT:' (max 60 words — objective...)`. A raw substring scan matched that
+ * quoted marker, and because the result was non-null it also SUPPRESSED the
+ * bounded elicited fallback: every session silently inherited boilerplate
+ * instead of a plot. Extraction now honors the contract the marker lives in:
+ *   - the marker must START a line ("one line beginning 'PLOT:'" —
+ *     mid-sentence quotes are instructions, not plots);
+ *   - system-role messages never yield a plot (invariant 4's cousin: the
+ *     MODEL authors plots; the prompt only asks for them);
+ *   - bodies echoing the instruction template are rejected (belt and braces
+ *     for historical sessions where such text already rides in user
+ *     messages).
+ * A null result now genuinely means "no plot authored" — which is exactly
+ * when the bounded elicited fallback must run.
+ */
+const PLOT_LINE = /^[ \t]*PLOT:[ \t]*([^\n]*)/gm;
+const PLOT_TEMPLATE_ECHO = /max \d+ words|carries this plot forward|revise it on your next plot line/i;
+export function extractPlot(messages, maxChars = 900) {
+    const scan = (roleWanted) => {
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const m = messages[i];
+            if (m.role === 'system')
+                continue;
+            if (roleWanted === 'assistant' && m.role !== 'assistant')
+                continue;
+            const text = messageText(messages[i]);
+            let found = null;
+            for (const line of text.matchAll(PLOT_LINE)) {
+                const body = (line[1] ?? '').trim();
+                if (body.length === 0)
+                    continue;
+                if (PLOT_TEMPLATE_ECHO.test(body))
+                    continue;
+                found = body;
+            }
+            if (found !== null)
+                return found.length > maxChars ? found.slice(0, maxChars) + '…' : found;
+        }
+        return null;
+    };
+    return scan('assistant') ?? scan('any');
+}
+// ---------------------------------------------------------------- finalization
+/**
+ * Post-commit: render the chapter body for one compaction from the durable
+ * log (citation-resolved), and return the record to commit. The caller writes
+ * files (via archive.writeArchive) and persists state; this stays pure over
+ * the event data so the pruner-composition rule is testable.
+ */
+export function buildFinalizedChapter(session, shadowedSeqs, plan, config) {
+    const events = shadowedSeqs.map((seq) => {
+        const ev = resolveOriginalEvent(session, seq);
+        if (ev === undefined)
+            throw new Error(`buildFinalizedChapter: event vanished at ${seq}`);
+        return ev;
+    });
+    const lo = Math.min(...shadowedSeqs, ...events.map((e) => e.seq));
+    const hi = Math.max(...shadowedSeqs, ...events.map((e) => e.seq));
+    // Subagent lineage (issue #47): a compacting child stamps the same header fact
+    // the save doors do — undefined for ordinary sessions, byte-identical output.
+    const lineage = lineageOf(session.header);
+    return renderChapter(events, {
+        title: plan.chapter.title,
+        summary: plan.chapter.summary,
+        startSeq: lo,
+        endSeq: hi,
+    }, {
+        chapterTokenTarget: config.chapterTokenTarget,
+        toolResultDeferFloorTokens: config.toolResultDeferFloorTokens,
+        planInlineChars: config.planInlineChars,
+        callArgArtifactTokens: config.callArgArtifactTokens,
+        ...(lineage !== undefined ? { subagentOf: lineage } : {}),
+    }, [], chapterTopics(events, lo, hi));
+}
+/**
+ * Render the manifest's chapters (r29) — authoritative ranges, no
+ * recomposition (the TOC cited them). A plan without composed chapters
+ * returns the legacy single render. Mismatch between manifest and the
+ * committed shadowed span is a LOUD error: the finalizer defers and warns,
+ * never silently archives the wrong content.
+ */
+export function buildFinalizedChapters(session, shadowedSeqs, plan, config) {
+    const composed = plan.chapters;
+    if (composed === undefined || composed.length === 0) {
+        return [buildFinalizedChapter(session, shadowedSeqs, plan, config)];
+    }
+    const events = shadowedSeqs.map((seq) => {
+        const ev = resolveOriginalEvent(session, seq);
+        if (ev === undefined)
+            throw new Error(`buildFinalizedChapters: event vanished at ${seq}`);
+        return ev;
+    });
+    const shadowMin = Math.min(...shadowedSeqs);
+    const shadowMax = Math.max(...shadowedSeqs);
+    const last = composed[composed.length - 1];
+    if (composed[0].startSeq > shadowMin || last.endSeq < shadowMax) {
+        throw new Error(`buildFinalizedChapters: manifest [${composed[0].startSeq}..${last.endSeq}] does not cover shadowed [${shadowMin}..${shadowMax}] — reconstruction drift`);
+    }
+    const lineage = lineageOf(session.header);
+    const renderCfg = {
+        chapterTokenTarget: config.chapterTokenTarget,
+        toolResultDeferFloorTokens: config.toolResultDeferFloorTokens,
+        planInlineChars: config.planInlineChars,
+        callArgArtifactTokens: config.callArgArtifactTokens,
+        ...(lineage !== undefined ? { subagentOf: lineage } : {}),
+    };
+    return composed.map((ch) => {
+        const inRange = events.filter((e) => e.seq >= ch.startSeq && e.seq <= ch.endSeq);
+        if (inRange.length === 0) {
+            throw new Error(`buildFinalizedChapters: chapter ${ch.number} [${ch.startSeq}..${ch.endSeq}] holds no shadowed events`);
+        }
+        // The WHOLE shadowed list goes in, not just this chapter's events: a plan
+        // verdict can land past a composed boundary, and pairing inside one range
+        // only would print an approved plan as pending (plans-carriage § 1).
+        // renderChapter filters to the range itself.
+        return renderChapter(events, {
+            title: ch.title,
+            summary: ch.summary,
+            startSeq: Math.min(...inRange.map((e) => e.seq)),
+            endSeq: Math.max(...inRange.map((e) => e.seq)),
+        }, renderCfg, [], chapterTopics(inRange, ch.startSeq, ch.endSeq));
+    });
+}
+/** The registry record shape written post-writeArchive for an engine chapter. */
+export function engineRecord(plan, shadowedSeqs, rendered, writtenPath, sha256hex) {
+    return {
+        number: plan.numbers[0],
+        path: writtenPath,
+        title: plan.chapter.title,
+        summary: plan.chapter.summary,
+        startSeq: rendered.range.startSeq,
+        endSeq: rendered.range.endSeq,
+        topics: rendered.topics,
+        messages: rendered.stats.messages,
+        shadowedSeqs: [...shadowedSeqs],
+        sha256: sha256hex,
+        estimatedTokens: rendered.stats.estimatedTokens,
+        artifacts: rendered.artifacts.map((a) => ({ path: a.path, sha256: a.sha256, bytes: a.bytes })),
+        ...(rendered.stats.plans !== undefined && rendered.stats.plans.length > 0 ? { plans: rendered.stats.plans } : {}),
+        ...(rendered.stats.planMode !== undefined && rendered.stats.planMode !== 'unknown' ? { planMode: rendered.stats.planMode } : {}),
+    };
+}
+/** Numbers the plan reserved, or null when the manifest disagrees (corruption). */
+/**
+ * Walk the provider-tagged summaries of one session and finalize each that is not yet finalized,
+ * ONE AT A TIME (#59): an item whose manifest is gone is reported and skipped, never allowed to
+ * abort the items behind it. Pure over injected effects so the poison-pill case is testable without
+ * a host.
+ */
+export async function scanAndFinalize(state, summaries, finalizeOne, onSkip) {
+    const done = [];
+    const skipped = [];
+    for (const found of summaries) {
+        if (isFinalized(state, found.compactionId))
+            continue;
+        const hasManifest = state.plans[found.compactionId] !== undefined
+            && state.reservations[`compaction:${found.compactionId}`] !== undefined;
+        if (!hasManifest) {
+            // The field case: the manifest row was erased by a stale whole-row put. Nothing can write the
+            // chapter now (the cited path/number are not durable), so say which and move on.
+            skipped.push({ compactionId: found.compactionId, reason: 'no-manifest' });
+            onSkip?.({ compactionId: found.compactionId, reason: 'no-manifest' }, new Error('no durable plan/reservation'));
+            continue;
+        }
+        try {
+            await finalizeOne(found);
+            done.push(found.compactionId);
+        }
+        catch (error) {
+            // Keep the rest of the queue alive; the item itself stays un-finalized and is retried next touch.
+            skipped.push({ compactionId: found.compactionId, reason: 'finalize-failed' });
+            onSkip?.({ compactionId: found.compactionId, reason: 'finalize-failed' }, error);
+        }
+    }
+    return { done, skipped };
+}
+export function assertReservationMatchesPlan(state, compactionId, plan) {
+    const got = state.reservations[`compaction:${compactionId}`];
+    return got !== undefined && got.length === plan.numbers.length && got.every((n, i) => n === plan.numbers[i]);
+}
+//# sourceMappingURL=engine-core.js.map

package/lib/engine-core.js.map

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

package/lib/engine-note.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The relief decision note — one formatter, so the numbers a diagnosis needs are never optional (#143).
+ *
+ * Why a module for one string: the live instrumented run of 2026-10-28 showed the note already carried the compaction
+ * id, the route, the surface and the ratio, but **nothing** about the span a pass removed — `grep -c shadowed` over
+ * 3,772 engine lines in the sink returned zero. That is the difference between answering "why did relief need ~19
+ * calls?" and re-guessing at it, so the field is now produced here and pinned by a row (`engine-lifecycle.test.ts`,
+ * #143) rather than being remembered at the call site. Same reason `#noteDecision` exists at all: `decided: none` covers
+ * two opposite bugs (no routed target vs. genuinely under threshold), so the abstention has to say which.
+ *
+ * Pure: no cordis, no ctx, no fs. `#noteDecision` gathers the inputs (it can fail, and the try/catch stays there) and
+ * hands them over; this turns them into bytes. Every field the previous inline template emitted is still emitted, in
+ * the same spellings, because existing rows grep them.
+ */
+export type CompactionNoteInput = {
+    readonly where: string;
+    readonly trigger: unknown;
+    readonly sessionId?: string | null;
+    /** `null` means the session has no routed target — a different failure than "under threshold". */
+    readonly route: string | null;
+    readonly surfaceTokens: number | null;
+    readonly window: number | null;
+    readonly ratio?: number | string | null;
+    /** Nodes still on the surface — read off the SESSION, because the result does not carry it (#143). */
+    readonly surfaceNodes?: number | null;
+    /** The base engine's result, or `null` when it abstained. Field names mirror `CompactionResult` in
+     * `@deepseek-ai/dsh-compaction/lib/types/types.d.ts:shadowedSeqs / shadowedTokenCount`, measured not assumed. */
+    readonly result: {
+        readonly compactionId?: string | null;
+        readonly shadowedSeqs?: readonly number[] | null;
+        readonly shadowedTokenCount?: number | null;
+    } | null;
+};
+/** One line, every field, no missing values: absent counts are `0`, absent numbers are `?`. */
+export declare function compactionNote(input: CompactionNoteInput): string;

package/lib/engine-note.js

@@ -0,0 +1,32 @@
+/**
+ * The relief decision note — one formatter, so the numbers a diagnosis needs are never optional (#143).
+ *
+ * Why a module for one string: the live instrumented run of 2026-10-28 showed the note already carried the compaction
+ * id, the route, the surface and the ratio, but **nothing** about the span a pass removed — `grep -c shadowed` over
+ * 3,772 engine lines in the sink returned zero. That is the difference between answering "why did relief need ~19
+ * calls?" and re-guessing at it, so the field is now produced here and pinned by a row (`engine-lifecycle.test.ts`,
+ * #143) rather than being remembered at the call site. Same reason `#noteDecision` exists at all: `decided: none` covers
+ * two opposite bugs (no routed target vs. genuinely under threshold), so the abstention has to say which.
+ *
+ * Pure: no cordis, no ctx, no fs. `#noteDecision` gathers the inputs (it can fail, and the try/catch stays there) and
+ * hands them over; this turns them into bytes. Every field the previous inline template emitted is still emitted, in
+ * the same spellings, because existing rows grep them.
+ */
+/** One line, every field, no missing values: absent counts are `0`, absent numbers are `?`. */
+export function compactionNote(input) {
+    const r = input.result;
+    const shadowed = Array.isArray(r?.shadowedSeqs) ? r.shadowedSeqs.length : 0;
+    const shadowedTok = typeof r?.shadowedTokenCount === 'number' ? r.shadowedTokenCount : 0;
+    const decided = r === null
+        ? 'none'
+        : `compaction ${String(r?.compactionId ?? '?')}`;
+    const route = input.route === null ? 'none' : input.route;
+    const surface = input.surfaceTokens === null ? '?' : `${String(input.surfaceTokens)} tok`;
+    const window = input.window === null ? '?' : String(input.window);
+    const nodes = input.surfaceNodes === null || input.surfaceNodes === undefined ? '?' : String(input.surfaceNodes);
+    const ratio = input.ratio === null || input.ratio === undefined ? '?' : String(input.ratio);
+    return `${input.where} decided: ${decided} (trigger=${JSON.stringify(input.trigger)}, `
+        + `session=${String(input.sessionId ?? '?')}, route=${route}, surface=${surface}, ratio=${ratio}, `
+        + `window=${window}, shadowed=${String(shadowed)}, shadowedTok=${String(shadowedTok)}, nodes=${nodes})`;
+}
+//# sourceMappingURL=engine-note.js.map

package/lib/engine-note.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-note.js","sourceRoot":"","sources":["../src/engine-note.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAsBH,+FAA+F;AAC/F,MAAM,UAAU,cAAc,CAAC,KAA0B;IACvD,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAA;IACtB,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,YAAkC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;IAClG,MAAM,WAAW,GAAG,OAAO,CAAC,EAAE,kBAAkB,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAA;IACxF,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI;QACxB,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,cAAc,MAAM,CAAC,CAAC,EAAE,YAAY,IAAI,GAAG,CAAC,EAAE,CAAA;IAClD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAA;IACzD,MAAM,OAAO,GAAG,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAA;IACzF,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IACjE,MAAM,KAAK,GAAG,KAAK,CAAC,YAAY,KAAK,IAAI,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;IAChH,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAC3F,OAAO,GAAG,KAAK,CAAC,KAAK,aAAa,OAAO,aAAa,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI;UACnF,WAAW,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,GAAG,CAAC,WAAW,KAAK,aAAa,OAAO,WAAW,KAAK,IAAI;UACjG,UAAU,MAAM,cAAc,MAAM,CAAC,QAAQ,CAAC,iBAAiB,MAAM,CAAC,WAAW,CAAC,WAAW,KAAK,GAAG,CAAA;AAC3G,CAAC"}