@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.20

package/lib/diag.js

@@ -0,0 +1,186 @@
+/**
+ * The one diagnostics seam for the whole plugin (#54).
+ *
+ * WHY THIS FILE EXISTS. `DSH_CHAPTERS_ENGINE_ERRORS` was written by two copies of the same
+ * three lines — one in the realm engine, one in the subagent auto-save listener — and by
+ * NEITHER of the places that actually fail a user: the host-plane doors and the shared
+ * continuation core. Measured consequence on host 0.2.0-rc.2: `chapters-fork refused: child
+ * creation refused: format v4 message requires a producer-owned source kind` ended the entire
+ * acceptance chain, and the sink — the one artifact a human or an agent could read without a
+ * browser — captured nothing at all. A diagnostic that misses the failure it exists to record
+ * is worse than none, because it is trusted.
+ *
+ * So there is now ONE writer, called from every plane. Rules it upholds:
+ *
+ *  - **Never throws, never blocks.** Diagnostics must not turn a handled failure into an
+ *    unhandled one, so every filesystem touch is swallowed. The real failure keeps its path.
+ *  - **Never silent when opted in.** With no sink configured, `diagnostic` is a no-op by
+ *    design — but `diagnosticRequested` lets a boot-time health line say "no sink is
+ *    configured", so the absence is visible rather than discovered during an incident.
+ *  - **Full detail on disk, short detail on screen.** The UI text is sliced to fit; the sink
+ *    gets the whole message plus the stack when there is one. Refusals that get truncated to
+ *    90 characters for the composer are exactly the ones worth reading in full later.
+ */
+import fs from 'node:fs';
+/**
+ * The sink, in resolution order: `DSH_CHAPTERS_ENGINE_ERRORS` (explicit wins), then the plugin-configured
+ * default, then NO file only when the operator wrote the literal `off`.
+ *
+ * #61 changed the default from silence to a file. Every compaction finalization failure in the SAIP field
+ * data left zero trace, and door 5 logged `saved` to a logger nobody reads for three days — a sink that
+ * must be configured before it works is a sink that is not configured at the moment you need it.
+ */
+let configured;
+/** Called once per plane at boot with `<store-root>/diagnostics.log` (config `diagnosticsLog`). */
+export function configureDiagnostics(path) { configured = path; }
+/**
+ * First door wins: the sink lives in the project whose store we are already writing to, so a session
+ * that never touches a door leaves no stray file, and a session that does gets its failures next to its
+ * chapters. Idempotent — later projects do not relocate the log mid-process.
+ */
+export function ensureDiagnosticsDefault(path, capBytes) {
+    if (configured === undefined)
+        configured = path;
+    if (capBytes !== undefined && Number.isFinite(capBytes) && capBytes >= 0)
+        maxBytes = capBytes;
+}
+/**
+ * The sink cap (#95 follow-up). The diagnostics sink defaults ON and every fix this month made it
+ * chattier — a line per enrichment no-op, per abstention, per declined relief — while `diagnostic()` was
+ * an uncapped `appendFileSync`. Loudness that costs unbounded disk is a bug the operator meets later, on
+ * someone else's machine. The cap is a declared Config key (`diagnosticsMaxBytes`); this constant is only
+ * its default. `0` (or a non-finite value) means uncapped, which stays the operator's explicit choice.
+ */
+export const DEFAULT_DIAGNOSTICS_MAX_BYTES = 8_388_608;
+let maxBytes = DEFAULT_DIAGNOSTICS_MAX_BYTES;
+/**
+ * The size decision, kept pure so a row can prove it without a filesystem: append below the cap, rotate
+ * at it. A diagnostic is NEVER dropped — the file is what makes detection count as delivery (#61a).
+ */
+export function sinkAction(sizeBytes, capBytes) {
+    if (!Number.isFinite(capBytes) || capBytes <= 0)
+        return 'append';
+    if (!Number.isFinite(sizeBytes) || sizeBytes < 0)
+        return 'append';
+    return sizeBytes >= capBytes ? 'rotate' : 'append';
+}
+/** Set the cap from plugin config; absent keeps the default. */
+export function configureDiagnosticsCap(bytes) {
+    if (bytes !== undefined && Number.isFinite(bytes) && bytes >= 0)
+        maxBytes = bytes;
+}
+export const DIAGNOSTICS_OFF = 'off';
+export function diagnosticSink() {
+    const p = process.env.DSH_CHAPTERS_ENGINE_ERRORS;
+    if (p !== undefined && p !== '')
+        return p === DIAGNOSTICS_OFF ? undefined : p;
+    return configured;
+}
+/**
+ * The status line: says out loud whether a failure WOULD be recorded. Discovered the hard way
+ * (#54) — an unconfigured sink is invisible until the one moment you need it, which is exactly
+ * when a human is asking "did the feature run, and what did the kernel say?".
+ */
+export function diagnosticStatusLine() {
+    const sink = diagnosticSink();
+    const envSet = process.env.DSH_CHAPTERS_ENGINE_ERRORS;
+    if (sink === undefined) {
+        return envSet === DIAGNOSTICS_OFF
+            // the operator chose silence — say THAT, not "you forgot to configure it"
+            ? 'Diagnostics: file sink explicitly disabled (DSH_CHAPTERS_ENGINE_ERRORS=off); door/child failures reach only the profile logger'
+            : 'Diagnostics: NO SINK AT ALL — no store root was resolved, so door/child failures reach only the profile logger (this is a bug, not a setting)';
+    }
+    return `Diagnostics: sink → ${sink}${envSet !== undefined && envSet !== '' ? ' (env override)' : ''}`;
+}
+/** True when SOME diagnostic was written since import — for the status line's honest "no sink" arm. */
+let everWritten = false;
+export function diagnosticEverWritten() { return everWritten; }
+/** Reset for tests only; production never calls it. */
+export function resetDiagnosticStateForTests() { everWritten = false; }
+/**
+ * Append one diagnostic record. Returns the composed line even when the write fails, so a
+ * caller can ALSO log or include it in a refusal without recomposing it.
+ *
+ * `where` is the seam that saw it (`'door:fork'`, `'realm:compaction'`, `'auto-save'`) — a
+ * timestamp and a message without an origin is how an incident report becomes a guess.
+ */
+function statSize(p) {
+    try {
+        return fs.statSync(p).size;
+    }
+    catch {
+        return 0;
+    }
+}
+export function diagnostic(where, message, error) {
+    const line = `[${new Date().toISOString()}] [${where}] ${message}` +
+        (error === undefined ? '' : ` :: ${describe(error)}`);
+    const sink = diagnosticSink();
+    if (sink === undefined)
+        return line;
+    try {
+        // appendFileSync, not async: a refused child creation is often followed by the process
+        // tearing the session down, and a pending write can be lost exactly when it matters.
+        // The cap is checked BEFORE the write, and the write then always happens. Rotation renames the
+        // current file to `<sink>.1` (keeping one previous generation) — this is a LOG policy for a file the
+        // plugin owns; nothing under `chapters/` is ever moved or truncated by this path, and the
+        // append-only archive invariant stays where it lives.
+        if (sinkAction(statSize(sink), maxBytes) === 'rotate') {
+            try {
+                fs.renameSync(sink, sink + '.1');
+            }
+            catch { /* rotation failure must never lose the line */ }
+        }
+        fs.appendFileSync(sink, line + '\n');
+        everWritten = true;
+    }
+    catch { /* diagnostics never mask the real failure */ }
+    return line;
+}
+/** The full error text a sink record needs: message, then name/code/stack — in that order. */
+export function describe(error) {
+    if (error === null || error === undefined)
+        return '(no error object)';
+    if (typeof error === 'string')
+        return error;
+    const e = error;
+    const bits = [];
+    if (typeof e.message === 'string' && e.message !== '')
+        bits.push(e.message);
+    if (typeof e.name === 'string' && e.name !== 'Error' && !bits[0]?.startsWith(e.name))
+        bits.push(`name=${e.name}`);
+    if (typeof e.code === 'string')
+        bits.push(`code=${e.code}`);
+    if (typeof e.stack === 'string' && e.stack !== '')
+        bits.push(e.stack.split('\n').slice(0, 6).join(' | '));
+    return bits.join(' :: ') || String(error);
+}
+/**
+ * A logger warn PLUS the sink, for planes that have a Cordis logger. The logger alone is not
+ * enough (r19: headless profiles route `ctx.logger` where nobody can see it), and the sink
+ * alone loses the operator channel — so do both, in that order.
+ */
+/**
+ * The same delivery as `diagnosticWarn`, at INFO — for an OBSERVATION the field needs on disk
+ * without anyone reading it as a failure. #78 is the reason this exists: the acceptance suite had
+ * always been the caller of `compactIfNeeded`, so "did the host invoke context relief at all?"
+ * had no answer in any artifact. A line in the sink answers it, and `info` keeps it out of the
+ * warning vocabulary the composer and `/chapters-status` use.
+ */
+export function diagnosticNote(logger, where, message) {
+    const line = diagnostic(where, message);
+    try {
+        logger?.info?.(line);
+    }
+    catch { /* a hostile logger must not eat the diagnostic */ }
+    return line;
+}
+export function diagnosticWarn(logger, where, message, error) {
+    const line = diagnostic(where, message, error);
+    try {
+        logger?.warn?.(line);
+    }
+    catch { /* a hostile logger must not eat the diagnostic */ }
+    return line;
+}
+//# sourceMappingURL=diag.js.map

package/lib/diag.js.map

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

package/lib/engine-core.d.ts

@@ -0,0 +1,301 @@
+/**
+ * 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 cwd, so a resolved-absolute store root still yields workspace-relative records (#69). */
+    workspaceCwd?: string | undefined;
+    /** Workspace-relative archive root; must be reachable by the `read` tool. */
+    artifactStoreRoot: string;
+    /**
+     * #85: where approved rules and the knowledge pool are read from when a notice is composed.
+     * Defaults to the historical `.dsh-knowledge` for real installs; an e2e boot pins it per port,
+     * because a tape is a claim about ONE world and a fixed path inside the developer's repo is not
+     * part of that world.
+     */
+    knowledgeMirrorDir: string;
+    /** Lines of the chapter index a continuation notice lists; 0 lists all of them. Keeps the notice's SIZE
+     * settled so a leg parked on the compaction boundary can be captured and replayed (#56). */
+    noticeIndexCap: number;
+    /** #87: how much of the newest human turn the summary carries verbatim when relief
+     *  shadows the turn that asked it. A cap, never a silent cut — the block says how much was left. */
+    openRequestCarryMaxChars: number;
+    /** #78 A: the survivability switch. See `docs/host-compaction-seam.md` § the last-resort deferral. */
+    lastResortArtifact: boolean;
+    /** Diagnostics sink size cap in bytes; 0 = uncapped (docs/verify.md, #61a). */
+    diagnosticsMaxBytes: number;
+    chapterTokenTarget: number;
+    toolResultDeferFloorTokens: number;
+    /** Composer tunables (record §4.2/§12) — same register, same defaults as the host plugin's. */
+    mergeThreshold: number;
+    chapterLimit: number;
+    /** #61 Amendment A — the seventh archive moment (see auto-save.ts `shouldForceChildArchive`). */
+    childAutoArchive?: boolean | undefined;
+    childAutoArchiveMinTurns?: number | undefined;
+    /** 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;
+    /** Verbatim plan characters printed in a chapter's Plans block (plans-carriage § 2).
+     * The full plan is ALWAYS artifact-backed, so this is display economy, not data. */
+    planInlineChars: number;
+    /** Above this many estimated tokens a tool-call ARGUMENT is artifact-backed and the
+     * inline text is a bounded head. 0 = off (default): enabling it changes chapter
+     * bytes, hence the model tapes — a deployment opts in deliberately. */
+    callArgArtifactTokens: number;
+    /** Elicit a plot note with one bounded call when the model wrote none. */
+    elicitedPlot: boolean;
+    /**
+     * Carry the operative session plan into every in-place checkpoint (the PLOT
+     * mechanism, applied to plans — docs/plans-carriage.md § 9). Shadowing can hide the
+     * chapter that holds a plan; a directive that survives only in a file the agent may
+     * never open is a directive it drifts from.
+     */
+    plansInCheckpoint: boolean;
+    /** Bounded plan characters carried in the checkpoint text; the archive keeps all. */
+    planCheckpointChars: number;
+}
+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, 
+/**
+ * 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?: string): {
+    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, 
+/**
+ * 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?: string | 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?: 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:";
+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). */
+/**
+ * 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 declare function scanAndFinalize(state: SessionState, summaries: readonly {
+    compactionId: string;
+    summarySeq: number;
+    shadowedSeqs: number[];
+}[], finalizeOne: (found: {
+    compactionId: string;
+    summarySeq: number;
+    shadowedSeqs: number[];
+}) => Promise<void>, onSkip?: (reason: {
+    compactionId: string;
+    reason: string;
+}, error: unknown) => void): Promise<{
+    done: string[];
+    skipped: Array<{
+        compactionId: string;
+        reason: string;
+    }>;
+}>;
+export declare function assertReservationMatchesPlan(state: SessionState, compactionId: string, plan: SummarizePlan): boolean;