@treeseed/dsh-chapters 0.1.0

package/lib/continue-core.d.ts

@@ -0,0 +1,153 @@
+/**
+ * chapters_continue — pure orchestration of a citation-linked continuation,
+ * behind ports (docs/development.md § L0: this file imports no cordis and no
+ * @deepseek-ai package; `src/tools.ts` adapts it).
+ *
+ * Order is the atomicity contract (docs/architecture.md § Atomicity):
+ * validate ranges -> reserve -> write+verify files -> assemble the notice ->
+ * budget preflight -> CREATE the child -> commit registry links. A crash before
+ * creation leaves orphan files (harmless, numbers already spent); creation
+ * without the commit is retried idempotently via attemptKey + linkChild.
+ *
+ * Budget honesty: allowance is a share of the window REMAINING after the
+ * header, never of the whole window; the header is bounded by the last real
+ * request's full prompt (conservative — over-counting errs toward loud
+ * refusals, which is the designed direction). No usage yet -> the probe says
+ * `headerBoundTokens: null` and the allowance conservatively assumes a zero
+ * header only because a session with no requests cannot have a large TOC.
+ */
+import type { ChapterRange, RenderConfig, SessionEventLike, ToolResultOverride } from './types.ts';
+import type { SessionState } from './registry.ts';
+export interface ContinueArgs {
+    callerSessionId: string;
+    /** The caller's own preset id, resolved by the adapter from its session observation. */
+    callerPreset: string | null;
+    title: string;
+    handoffNote: string;
+    chapters: ChapterRange[];
+    toolResultOverrides: ToolResultOverride[];
+    /**
+     * The knowledge-project line for the notice (record §8): `Project: <slug> ·
+     * <key>` plus the search instruction. Set by the adapter from the linked
+     * project; absent → the notice simply omits the section.
+     */
+    projectLine?: string;
+    /** P3 §7.3: rules block for the notice (see assembleNotice). */
+    rulesSection?: string;
+}
+export interface ContinueConfig extends RenderConfig {
+    artifactStoreRoot: string;
+    continuationBudgetRatio: number;
+    fallbackPreset: string;
+    /** Topic-sequential composition (record §4.2): merge while overlap ≥ τ. */
+    mergeThreshold: number;
+    /** Estimated-token cap per composed chapter. */
+    chapterLimit: number;
+}
+export interface BudgetProbe {
+    windowTokens: number | null;
+    headerBoundTokens: number | null;
+}
+export interface ContinuePorts {
+    /** The caller's durable events, oldest first (full log; the ceiling trims it). */
+    readCallerEvents(): Promise<SessionEventLike[]>;
+    getState(sessionId: string): Promise<SessionState>;
+    putState(sessionId: string, state: SessionState): Promise<void>;
+    /** ArchiveFs anchored at the caller's workspace cwd (the read tool reaches it). */
+    fs(): import('./archive.ts').ArchiveFs;
+    budgetProbe(): Promise<BudgetProbe>;
+    newId(): string;
+    /** agents.create + setup-mount + workspace attach; throws on kernel refusal. */
+    createChild(input: {
+        sessionId: string;
+        noticeEvent: SessionEventLike;
+        presetId: string;
+        title: string;
+    }): Promise<void>;
+    now(): number;
+}
+export interface ContinueResult {
+    ok: boolean;
+    childSessionId?: string;
+    presetUsed?: string;
+    chapters?: Array<{
+        number: number;
+        path: string;
+        startSeq: number;
+        endSeq: number;
+    }>;
+    warnings?: string[];
+    /** Numbers behind every outcome — AGENTS: refuse WITH the numbers. */
+    budget?: {
+        usedTokens: number;
+        allowanceTokens: number;
+        windowTokens: number | null;
+        headerBoundTokens: number | null;
+    };
+    reason?: string;
+}
+export declare class Refusal extends Error {
+    readonly result: ContinueResult;
+    constructor(result: ContinueResult);
+}
+export interface NoticeEntry {
+    number: number;
+    path: string;
+    title: string;
+    summary: string;
+    status: 'ok' | 'modified' | 'missing';
+    /** user+assistant message count (record §7.3); absent for legacy records. */
+    messages?: number;
+}
+/** The child's whole content: honest preamble, in-flight note, flat index, back-links. */
+export declare function assembleNotice(input: {
+    title: string;
+    handoffNote: string;
+    entries: readonly NoticeEntry[];
+    rootSession: string;
+    parentSession: string;
+    storeRoot: string;
+    projectLine?: string;
+    /** P3 §7.3: CORE RULES + category index, composed by the adapter from this
+     * machine's own approvals. Absent/empty => zero injected bytes (tape-safe). */
+    rulesSection?: string;
+}): string;
+/** The budget formula with its refusal numbers, kept apart for direct testing. */
+export declare function preflight(input: {
+    noticeTokens: number;
+    budget: BudgetProbe;
+    ratio: number;
+}): {
+    ok: true;
+    budget: NonNullable<ContinueResult['budget']>;
+} | {
+    ok: false;
+    budget: NonNullable<ContinueResult['budget']>;
+};
+export declare function runContinue(ports: ContinuePorts, args: ContinueArgs, config: ContinueConfig): Promise<ContinueResult>;
+/** Fields both continue and fork need to create the child. */
+export type FinishArgs = Pick<ContinueArgs, 'callerSessionId' | 'callerPreset' | 'title' | 'handoffNote' | 'projectLine' | 'rulesSection'>;
+/**
+ * chapters_fork: open a sibling line citing the SAME archive, archiving nothing
+ * new. The point is branching (AGENTS "branchable — history can fork, not
+ * just truncate"): parent and child keep working independently; no files are
+ * written and no numbers reserved, so a fork is cheap and cannot orphan a
+ * citation it did not already exist.
+ */
+export interface ForkArgs extends FinishArgs {
+}
+export declare function runFork(ports: ContinuePorts, args: ForkArgs, config: ContinueConfig): Promise<ContinueResult>;
+/**
+ * Deterministic segmentation: split [0..anchorSeq] into chapter ranges WITHOUT
+ * any model call — the fork-button backend (a button cannot wait for proposed
+ * ranges, and auto mode must never paraphrase: invariant 4 holds, only
+ * positions are computed here; titles/summaries derive from content lines).
+ * Cuts land ONLY on `turn/end` boundaries; a segment closes at the first
+ * boundary reaching ~90% of chapterTokenTarget, so overshoot is bounded.
+ */
+export declare function deriveRanges(events: readonly SessionEventLike[], anchorSeq: number, chapterTokenTarget: number, fromSeq?: number): {
+    chapters: ChapterRange[];
+    notes: string[];
+};
+/** The adapter surfaces refusals as tool output, never as crashes. */
+export declare function refusalResult(error: unknown): ContinueResult | null;

package/lib/continue-core.js

@@ -0,0 +1,252 @@
+import { chapterTopics } from "./signature.js";
+import { estimateTokens, renderChapter, validateRanges } from "./render.js";
+import { attemptKey, coverage, verifyChapter, writeArchive } from "./archive.js";
+import { appendChapters, freshSession, linkChild, reserve } from "./registry.js";
+import { buildTocNotice } from "./notice.js";
+import { deriveIdentity } from "./engine-core.js";
+export class Refusal extends Error {
+    result;
+    constructor(result) {
+        super(result.reason ?? 'refused');
+        this.result = result;
+    }
+}
+/** The child's whole content: honest preamble, in-flight note, flat index, back-links. */
+export function assembleNotice(input) {
+    const lines = [
+        `# Continuation: ${input.title}`,
+        ...(input.projectLine !== undefined && input.projectLine !== '' ? ['', input.projectLine] : []),
+        ...(input.rulesSection !== undefined && input.rulesSection !== '' ? ['', input.rulesSection] : []),
+        '',
+        'This session continues an archived conversation. Chapters are verbatim Markdown in the workspace;',
+        'every byte remains retrievable — inline, or at artifact paths cited inside a chapter. Read a chapter',
+        'by its path with the read tool when the detail matters. The previous session stays intact.',
+        '',
+        '## In flight',
+        input.handoffNote.trim().length > 0 ? input.handoffNote.trim() : '(none stated)',
+        '',
+        '## Chapters',
+    ];
+    for (const e of input.entries) {
+        const mark = e.status === 'ok' ? '' : ` ⚠ ${e.status} since archived`;
+        const msgs = e.messages !== undefined ? ` (${e.messages} msgs)` : '';
+        lines.push(`${e.number}. [${e.title}](${e.path}) — ${e.summary}${msgs}${mark}`);
+    }
+    lines.push('', `Ancestry: root ${input.rootSession}; parent ${input.parentSession}; archive under ${input.storeRoot}/.`);
+    return lines.join('\n');
+}
+/** The budget formula with its refusal numbers, kept apart for direct testing. */
+export function preflight(input) {
+    const window = input.budget.windowTokens;
+    if (window === null) {
+        const budget = { usedTokens: input.noticeTokens, allowanceTokens: 0, windowTokens: null, headerBoundTokens: input.budget.headerBoundTokens };
+        return { ok: false, budget };
+    }
+    const remaining = Math.max(0, window - (input.budget.headerBoundTokens ?? 0));
+    const allowance = Math.floor(remaining * input.ratio);
+    const budget = { usedTokens: input.noticeTokens, allowanceTokens: allowance, windowTokens: window, headerBoundTokens: input.budget.headerBoundTokens };
+    return input.noticeTokens <= allowance ? { ok: true, budget } : { ok: false, budget };
+}
+/** Ancestor ids root-first, via registry links; cycles refuse, never hang. */
+async function ancestryPath(ports, sessionId, limit = 1000) {
+    const walk = [];
+    const seen = new Set();
+    let cursor = sessionId;
+    while (cursor !== null) {
+        if (seen.has(cursor) || walk.length >= limit)
+            throw new Refusal({ ok: false, reason: `registry ancestry cycle/limit at ${cursor}` });
+        seen.add(cursor);
+        walk.unshift(cursor);
+        cursor = (await ports.getState(cursor)).parentSession;
+    }
+    return walk;
+}
+export async function runContinue(ports, args, config) {
+    // ---- 1. Facts: ceiling and ranges.
+    const allEvents = await ports.readCallerEvents();
+    const lastTurnEnd = [...allEvents].reverse().find((e) => e.type === 'turn/end');
+    if (lastTurnEnd === undefined) {
+        throw new Refusal({ ok: false, reason: 'no completed turn to archive — the conversation has not reached a turn/end boundary' });
+    }
+    const ceiling = lastTurnEnd.seq;
+    try {
+        validateRanges(args.chapters, ceiling);
+    }
+    catch (error) {
+        throw new Refusal({ ok: false, reason: `ranges refused: ${error.message}` });
+    }
+    const below = allEvents.filter((e) => e.seq <= ceiling);
+    const gaps = coverage(args.chapters, ceiling).gaps;
+    const warnings = gaps.map((g) => `seqs ${g.from}-${g.to} fall outside the supplied ranges — NOT archived (gaps are reported, never silent)`);
+    // ---- 2. Render + reserve + write (idempotent per attempt key).
+    const callerState = await ports.getState(args.callerSessionId);
+    const renderConfig = {
+        toolResultDeferFloorTokens: config.toolResultDeferFloorTokens,
+        chapterTokenTarget: config.chapterTokenTarget,
+    };
+    const rendered = args.chapters.map((range) => renderChapter(below, range, renderConfig, args.toolResultOverrides, chapterTopics(below, range.startSeq, range.endSeq)));
+    warnings.push(...rendered
+        .filter((r) => r.stats.overTarget)
+        .map((r) => `chapter "${r.range.title}" is ${r.stats.estimatedTokens} est tokens over chapterTokenTarget — split at the next continuation, never clip`));
+    const fs = ports.fs();
+    const wrote = await writeArchive({
+        fs,
+        allocator: {
+            async reserve(attemptId, count) {
+                const fresh = await ports.getState(args.callerSessionId);
+                const r = reserve(fresh, attemptId, count);
+                await ports.putState(args.callerSessionId, r.state);
+                return r.numbers;
+            },
+        },
+        storeRoot: config.artifactStoreRoot,
+        rootSessionId: callerState.rootSession,
+        chapters: rendered,
+        attemptId: attemptKey(args.callerSessionId, ceiling),
+    });
+    warnings.push(...wrote.warnings);
+    // ---- 3. Cumulative flat index over the ancestor path, integrity-verified.
+    const entries = await collectEntries(ports, args.callerSessionId, wrote.records, warnings);
+    // ---- 4/5. Notice + budget gate, create the child, commit.
+    return await finishChild(ports, config, args, callerState, entries, warnings, wrote.records);
+}
+/** Ancestors' committed records (root-first) plus fresh records; verified, numbered for display. */
+async function collectEntries(ports, callerSessionId, freshRecords, warnings) {
+    const fs = ports.fs();
+    const pathIds = await ancestryPath(ports, callerSessionId);
+    const priorRecords = [];
+    for (const id of pathIds) {
+        const st = await ports.getState(id);
+        // Registry order is insertion order = authoring order within a session;
+        // sessions walk root-first, so reading order IS causal order.
+        priorRecords.push(...st.chapters);
+    }
+    const seenPaths = new Set();
+    const cited = [];
+    for (const record of [...priorRecords, ...freshRecords]) {
+        if (seenPaths.has(record.path))
+            continue; // a retry re-wrote the same path: cite once
+        seenPaths.add(record.path);
+        cited.push(record);
+    }
+    const entries = [];
+    for (const record of cited) {
+        const status = await verifyChapter(fs, record);
+        if (status !== 'ok')
+            warnings.push(`${record.path}: ${status} since archived — marked in the TOC, not silently trusted`);
+        entries.push({ number: entries.length + 1, path: record.path, title: record.title, summary: record.summary, status, ...(record.messages !== undefined ? { messages: record.messages } : {}) });
+    }
+    return entries;
+}
+/** Shared tail of both flows: notice -> budget gate -> create (invariant 2) -> commit. */
+async function finishChild(ports, config, args, callerState, entries, warnings, commitRecords) {
+    // ---- Notice text, then the budget gate (measure the WHOLE notice).
+    const noticeText = assembleNotice({
+        title: args.title,
+        handoffNote: args.handoffNote,
+        entries,
+        rootSession: callerState.rootSession,
+        parentSession: args.callerSessionId,
+        storeRoot: config.artifactStoreRoot,
+        ...(args.projectLine !== undefined ? { projectLine: args.projectLine } : {}),
+        ...(args.rulesSection !== undefined ? { rulesSection: args.rulesSection } : {}),
+    });
+    const budget = preflight({
+        noticeTokens: estimateTokens(noticeText),
+        budget: await ports.budgetProbe(),
+        ratio: config.continuationBudgetRatio,
+    });
+    if (!budget.ok) {
+        throw new Refusal({
+            ok: false,
+            reason: budget.budget.windowTokens === null
+                ? 'cannot resolve the model context window for this caller — refusing to create an unbounded continuation (check agentDefaultModel selection / adapter metadata)'
+                : `continuation over budget: notice ~${budget.budget.usedTokens} tokens > allowance ${budget.budget.allowanceTokens} (${config.continuationBudgetRatio} × (window ${budget.budget.windowTokens} − header bound ${budget.budget.headerBoundTokens ?? 'unmeasured'})). Shorten the handoff note or split the archive.`,
+            budget: budget.budget,
+            warnings,
+        });
+    }
+    // ---- Create the child (one synthetic event at seq 0 — invariant 2), then commit.
+    const noticeEvent = buildTocNotice(noticeText, { newId: ports.newId, time: ports.now() });
+    const childId = `ch-${ports.newId()}`;
+    const presetId = args.callerPreset ?? config.fallbackPreset;
+    try {
+        await ports.createChild({ sessionId: childId, noticeEvent, presetId, title: args.title });
+    }
+    catch (error) {
+        throw new Refusal({ ok: false, reason: `child creation refused: ${error.message}`, warnings });
+    }
+    if (commitRecords.length > 0) {
+        const callerFresh = await ports.getState(args.callerSessionId);
+        await ports.putState(args.callerSessionId, appendChapters(callerFresh, commitRecords));
+    }
+    await ports.putState(childId, linkChild(freshSession(childId), args.callerSessionId, callerState.rootSession));
+    return {
+        ok: true,
+        childSessionId: childId,
+        presetUsed: presetId,
+        chapters: commitRecords.map((r) => ({ number: r.number, path: r.path, startSeq: r.startSeq, endSeq: r.endSeq })),
+        warnings,
+        budget: budget.budget,
+    };
+}
+export async function runFork(ports, args, config) {
+    const warnings = [];
+    const callerState = await ports.getState(args.callerSessionId);
+    const entries = await collectEntries(ports, args.callerSessionId, [], warnings);
+    return await finishChild(ports, config, args, callerState, entries, warnings, []);
+}
+/**
+ * Deterministic segmentation: split [0..anchorSeq] into chapter ranges WITHOUT
+ * any model call — the fork-button backend (a button cannot wait for proposed
+ * ranges, and auto mode must never paraphrase: invariant 4 holds, only
+ * positions are computed here; titles/summaries derive from content lines).
+ * Cuts land ONLY on `turn/end` boundaries; a segment closes at the first
+ * boundary reaching ~90% of chapterTokenTarget, so overshoot is bounded.
+ */
+export function deriveRanges(events, anchorSeq, chapterTokenTarget, fromSeq = 0) {
+    const upto = events.filter((e) => e.seq <= anchorSeq);
+    const boundaries = upto.filter((e) => e.type === 'turn/end' && e.seq >= fromSeq).map((e) => e.seq);
+    if (boundaries.length === 0) {
+        throw new Refusal({ ok: false, reason: fromSeq > 0
+                ? `nothing new to archive: every completed turn at or before seq ${anchorSeq} is already in the archive (watermark ${fromSeq - 1})`
+                : `no completed turn at or before seq ${anchorSeq} — nothing to branch from yet` });
+    }
+    const last = boundaries[boundaries.length - 1];
+    const notes = [];
+    if (last !== anchorSeq) {
+        notes.push(`anchor ${anchorSeq} is not a turn boundary: segmentation ran to ${last}; later events belong to an unfinished turn (describe them in the handoff note)`);
+    }
+    const tokensBetween = (lo, hi) => upto
+        .filter((e) => e.seq >= lo && e.seq <= hi)
+        .reduce((n, e) => n + Math.ceil(JSON.stringify(e.data ?? {}).length / 4), 0);
+    const chapters = [];
+    const cut = Math.max(1, Math.floor(chapterTokenTarget * 0.9));
+    let start = fromSeq;
+    for (const b of boundaries) {
+        const isLast = b === last;
+        if (isLast || tokensBetween(start, b) >= cut) {
+            const seg = upto.filter((e) => e.seq >= start && e.seq <= b);
+            const msgs = seg
+                .filter((e) => e.type === 'user/message' || e.type === 'assistant/message')
+                .map((e) => {
+                const d = e.data;
+                return { role: e.type === 'assistant/message' ? 'assistant' : 'user', content: d?.content ?? [] };
+            });
+            const identity = deriveIdentity(msgs, seg.some((e) => JSON.stringify(e.data ?? '').includes('<compacted-summary>')));
+            chapters.push({
+                title: `${identity.title} (${chapters.length + 1})`,
+                summary: `events ${start}-${b}; ${identity.summary}`,
+                startSeq: start,
+                endSeq: b,
+            });
+            start = b + 1;
+        }
+    }
+    return { chapters, notes };
+}
+/** The adapter surfaces refusals as tool output, never as crashes. */
+export function refusalResult(error) {
+    return error instanceof Refusal ? error.result : null;
+}
+//# sourceMappingURL=continue-core.js.map

package/lib/continue-core.js.map

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

package/lib/engine-core.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Engine core — the deterministic logic behind ChaptersCompactionEngine, as
+ * pure functions over minimal structural types. NO cordis, NO @deepseek-ai
+ * imports: this file runs under `node --test` with no harness, which is where
+ * the two scariest engine-path bugs get caught — a lost TOC bullet (silently
+ * unreachable chapter) and a mis-resolved citation (wrong text archived).
+ *
+ * The correlation model (docs/host-compaction-seam.md + FINDINGS § Phase 0b):
+ *   summarize()  — sees region CONTENT (no seqs); reserves numbers keyed by the
+ *                  OPEN transaction's compactionId (found by scanning the log:
+ *                  the last `compaction/start` without a matching `end` — the
+ *                  durable lock guarantees uniqueness) and emits the TOC text
+ *                  citing deterministic paths.
+ *   finalize()   — post-commit, from authoritative CompactionResult.shadowedSeqs,
+ *                  renders bodies from the DURABLE LOG, following each
+ *                  `tool/result` replacement's `sourceEventSeqs` chain back to
+ *                  the pre-prune original. Never from summarize's input.
+ *
+ * Checkpoint merge-forward: the next compaction's span usually includes the
+ * previous checkpoint node (r12 measured it). Its TOC bullets are extracted
+ * and re-emitted; an embedded LLM-style summary (a host `basic` checkpoint
+ * from before this engine was mounted) is carried verbatim ONCE — honest,
+ * bounded, and never silently dropped.
+ */
+import type { ChapterRange, RenderedChapter } from './types.ts';
+import type { ChapterRecord } from './archive.ts';
+import type { PlanChapter, SessionState } from './registry.ts';
+/** provider tag written into `compaction/summary` — our event-scan discriminator. */
+export declare const CHAPTERS_PROVIDER = "dsh-chapters";
+export declare const DETERMINISTIC_MODEL = "deterministic";
+/** Framing tags the host's summarizer wraps checkpoints in (compaction-basic summarizer.ts:21-22). */
+export declare const SUMMARY_OPEN_TAG = "<compacted-summary>";
+export declare const SUMMARY_CLOSE_TAG = "</compacted-summary>";
+/** One TOC bullet, as re-parsed from prior checkpoints — the accumulation unit. */
+export interface TocBullet {
+    title: string;
+    path: string;
+    summary: string;
+}
+export interface EngineConfig {
+    /** Workspace-relative archive root; must be reachable by the `read` tool. */
+    artifactStoreRoot: string;
+    chapterTokenTarget: number;
+    toolResultDeferFloorTokens: number;
+    /** Composer tunables (record §4.2/§12) — same register, same defaults as the host plugin's. */
+    mergeThreshold: number;
+    chapterLimit: number;
+    /** Arrival-time artifacting floor (architecture.md amendment 2026-09-19):
+     * tool results at/above this many estimated tokens are stored as artifacts
+     * and replaced by reference stubs BEFORE the next request is composed. */
+    toolResultArtifactTokens: number;
+    /** Elicit a plot note with one bounded call when the model wrote none. */
+    elicitedPlot: boolean;
+}
+export declare const ENGINE_CONFIG_DEFAULTS: EngineConfig;
+export interface SummarizeInputLike {
+    readonly tools?: readonly unknown[];
+    readonly messages: readonly EngineMessage[];
+}
+export interface EngineMessage {
+    readonly role: string;
+    readonly content?: readonly {
+        type: string;
+        text?: string;
+    }[];
+}
+export interface SummarizeResultLike {
+    summary: {
+        type: 'text';
+        text: string;
+    }[];
+    provider: string;
+    model: string;
+}
+/** The slice of `Session` the core reads. Kept small so fakes are honest. */
+export interface EngineSession {
+    readonly id: string;
+    readonly seq: number;
+    eventAt(seq: number): EngineSessionEvent | undefined;
+    /**
+     * Present on the real host Session (a class) — `reconstructShadowedSeqs`
+     * needs them to map summarize-input messages back to log seqs. Absence of
+     * either simply means: no reconstruction, legacy single-chapter compaction.
+     */
+    readonly surface?: {
+        readonly nodes?: readonly {
+            readonly seq: number;
+        }[];
+    };
+    deriveEventMessage?(event: EngineSessionEvent): EngineMessage | null | undefined;
+}
+export interface EngineSessionEvent {
+    readonly type: string;
+    readonly seq: number;
+    readonly time?: number;
+    readonly sourceEventSeqs?: readonly number[];
+    readonly data?: Record<string, unknown>;
+}
+/** Every `<compacted-summary>…</compacted-summary>` block in the region, in order. */
+export declare function extractCheckpointBlocks(messages: readonly EngineMessage[]): string[];
+/**
+ * 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 declare function parseTocState(blocks: readonly string[]): {
+    bullets: TocBullet[];
+    carriedProse: string[];
+};
+/**
+ * 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 declare function findOpenCompactionId(session: EngineSession): string | null;
+/** All OUR finalized-or-not summary events (provider-tagged), oldest first. */
+export declare function scanChaptersSummaries(session: EngineSession): Array<{
+    compactionId: string;
+    summarySeq: number;
+    shadowedSeqs: number[];
+}>;
+/**
+ * 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 declare function resolveOriginalEvent(session: EngineSession, seq: number): EngineSessionEvent | undefined;
+export interface SummarizePlan {
+    /** TOC text for the checkpoint (what summarize returns). */
+    tocText: string;
+    /** Chapter numbers reserved during planning — attemptId `compaction:${id}`. */
+    numbers: number[];
+    /** Everything finalize needs, since finalize cannot re-derive the title. */
+    chapter: {
+        title: string;
+        summary: string;
+        path: string;
+    };
+    /**
+     * Topic-composed plan (r29): when the composer ran over the span, one
+     * manifest chapter per composed range — finalize renders exactly these,
+     * it never recomposes (the TOC cited them; determinism is the contract).
+     */
+    chapters?: PlanChapter[];
+}
+/** Deterministic title/summary from region content. Never model-authored (invariant 4 — the model is absent). */
+export declare function deriveIdentity(messages: readonly EngineMessage[], hasCheckpoint: boolean): {
+    title: string;
+    summary: string;
+};
+/** Workspace-relative chapter path for a reserved number. */
+export declare const chapterPathFor: (config: EngineConfig, rootSession: string, number: number, title: string) => string;
+/**
+ * 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 declare function reconstructShadowedSeqs(session: EngineSession, input: SummarizeInputLike): number[] | 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 declare function planSummarize(session: EngineSession, state: SessionState, input: SummarizeInputLike, config: EngineConfig, reserveFn: (state: SessionState, attemptId: string, count: number) => {
+    state: SessionState;
+    numbers: number[];
+}, 
+/** Required: the caller fails loudly when no `compaction/start` is open. */
+compactionId: string, composition?: readonly ChapterRange[] | null, 
+/** Model-authored plot note carried into this checkpoint (may be null). */
+plot?: string | null): {
+    plan: SummarizePlan;
+    state: SessionState;
+};
+/**
+ * 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 declare 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.
+ */
+export declare function extractPlot(messages: readonly EngineMessage[], maxChars?: number): string | null;
+/**
+ * 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 declare function buildFinalizedChapter(session: EngineSession, shadowedSeqs: readonly number[], plan: SummarizePlan, config: EngineConfig): RenderedChapter;
+/**
+ * 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 declare function buildFinalizedChapters(session: EngineSession, shadowedSeqs: readonly number[], plan: SummarizePlan, config: EngineConfig): RenderedChapter[];
+/** The registry record shape written post-writeArchive for an engine chapter. */
+export declare function engineRecord(plan: SummarizePlan, shadowedSeqs: readonly number[], rendered: RenderedChapter, writtenPath: string, sha256hex: string): ChapterRecord;
+/** Numbers the plan reserved, or null when the manifest disagrees (corruption). */
+export declare function assertReservationMatchesPlan(state: SessionState, compactionId: string, plan: SummarizePlan): boolean;