@bridge_gpt/mcp-server 0.2.36 → 0.2.38

package/build/plan-execution-ledger.js

@@ -0,0 +1,550 @@
+/**
+ * BAPI-763 — plan step routing and the durable execution ledger.
+ *
+ * Plan generation commissions several agents and concatenates their output into one
+ * flat markdown plan. Two of those agents exist *only* to author verification work:
+ * the reviewer's grep-driven checks and its scored rendered-UI remediation loop.
+ * Neither was ever executed. The production phase deferred everything that
+ * "validates rather than produces", and the post-PR verification phase had a fixed
+ * depth — builds, touched-area tests, scoped lint — that none of those steps fit.
+ * The work fell through the gap in silence. That is Miss 20.
+ *
+ * This module is the part of the fix that makes silence impossible:
+ *
+ * - **Routing is derived, not guessed.** {@link resolveOwnedSteps} answers "which
+ *   steps does this phase own?" from provenance metadata assembled in code, rather
+ *   than from keyword-matching over plan prose.
+ * - **Coverage is asserted.** {@link assertStepClassCoverage} fails when any class of
+ *   step a planner can emit has no executing phase. Run against the pre-BAPI-763
+ *   ownership registry it fails on the review and rendered-UI classes — that failing
+ *   assertion is the regression test for Miss 20.
+ * - **Every owned step gets a terminal disposition.** {@link validatePhaseResult}
+ *   rejects a phase result that leaves an owned step unsettled. There is no
+ *   "skipped": a step is executed, mechanically adapted, escalated, or declared
+ *   advisory in the plan itself.
+ * - **The record is durable and monotonic.** {@link mergePlanStepRecords} keeps
+ *   chronological evidence and refuses to silently downgrade or drop a settled step,
+ *   so the record survives an approval pause or a resumed session — the conversational
+ *   hand-off it replaces did not.
+ *
+ * Pure domain logic: no I/O, no git, no network, no filesystem, no MCP transport.
+ */
+// ---------------------------------------------------------------------------
+// Vocabulary — closed sets, mirrored from src/python/llms/agents/code_writer/
+// plan_provenance.py. Both sides must agree; the Python side assigns the classes
+// and this side routes on them.
+// ---------------------------------------------------------------------------
+export const PLAN_METADATA_VERSION = 1;
+export const PLAN_PROVENANCE_CLASSES = [
+    "implementation",
+    "documentation",
+    "unit_tests",
+    "e2e_tests",
+    "rendered_ui_review",
+    "test_gap_review",
+    "final_plan_review",
+];
+export const PLAN_PHASES = [
+    "produce",
+    "pre_pr_verification",
+    "post_pr_gap_close",
+];
+export const PLAN_STEP_DISPOSITIONS = [
+    "executed",
+    "adapted",
+    "escalated",
+    "unrun-advisory",
+];
+/**
+ * The only three corrections a phase may make on its own authority.
+ *
+ * The bound is deliberately mechanical. "Preserve the objective" was considered and
+ * rejected as too permissive: it licenses an agent to decide what a step was really
+ * for and substitute its own approach, which is indistinguishable from ignoring the
+ * step. These three are corrections to how a step is *addressed*, never to what it
+ * asks for.
+ */
+export const MECHANICAL_ADAPTATION_KINDS = [
+    "locator-correction",
+    "repository-command-correction",
+    "equivalent-implementation-recognized",
+];
+/**
+ * Change categories that may never be adapted. Meeting one of these means the step's
+ * premise is wrong in a way only a human should resolve, so the run escalates.
+ */
+export const ESCALATION_ONLY_CATEGORIES = [
+    "design",
+    "schema",
+    "public-api",
+    "dependencies",
+    "security",
+];
+/**
+ * Which phase must settle each class of step.
+ *
+ * This registry IS the fix. Before BAPI-763 the entries below for the two review
+ * classes and the rendered-UI class did not exist in any form — no phase claimed
+ * them, and nothing noticed.
+ *
+ * Ownership here means "must record a terminal disposition for every step in the
+ * class". It is not the same as "is the only phase that touches those steps": the
+ * produce phase authors every artifact the plan calls for, including the test files
+ * a test-planner step describes. What produce does not do is *run* them, so the
+ * phase that settles a test step is the one that executes it.
+ */
+export const PLAN_CLASS_OWNERSHIP = Object.freeze({
+    implementation: "produce",
+    documentation: "produce",
+    // Authored during produce; settled by the phase that actually runs them. The
+    // test planners are required to emit a final execution step ("one command per
+    // test"), which is verification work by construction.
+    unit_tests: "pre_pr_verification",
+    e2e_tests: "pre_pr_verification",
+    // The remediation loop CHANGES code. Settling it after the commit gate would
+    // guarantee the pull request's first head carried the un-iterated draft, so it
+    // must land before the PR opens.
+    rendered_ui_review: "pre_pr_verification",
+    test_gap_review: "pre_pr_verification",
+    final_plan_review: "pre_pr_verification",
+});
+export const PRE_PR_VERIFICATION_LIMITS = Object.freeze({
+    maxCorrectionTurns: 3,
+    maxChangedFiles: 40,
+    maxDiffLines: 2000,
+});
+/** The plan-authored rendered-UI remediation loop's hard cycle cap. */
+export const RENDERED_UI_MAX_CYCLES = 3;
+export class PlanLedgerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PlanLedgerError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Metadata validation
+// ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 1;
+}
+/**
+ * Validate a stored provenance envelope, returning it narrowed.
+ *
+ * Throws on every malformed shape rather than repairing one. A repaired envelope
+ * routes *something*, and something plausible-but-wrong is harder to notice than a
+ * loud failure — which is how the original defect survived.
+ */
+export function validatePlanMetadata(value) {
+    if (value === null || value === undefined) {
+        throw new PlanLedgerError("plan metadata is absent; routing requires provenance and must not be inferred from plan prose");
+    }
+    if (!isPlainObject(value)) {
+        throw new PlanLedgerError(`plan metadata must be an object, received ${Array.isArray(value) ? "array" : typeof value}`);
+    }
+    if (value.version !== PLAN_METADATA_VERSION) {
+        throw new PlanLedgerError(`unsupported plan metadata version ${String(value.version)}; expected ${PLAN_METADATA_VERSION}`);
+    }
+    const rawParts = value.parts;
+    if (!Array.isArray(rawParts) || rawParts.length === 0) {
+        throw new PlanLedgerError("plan metadata must carry a non-empty parts array");
+    }
+    const parts = [];
+    const seenIds = new Set();
+    let previousEnd = 0;
+    let previousId = "";
+    for (const [index, raw] of rawParts.entries()) {
+        if (!isPlainObject(raw)) {
+            throw new PlanLedgerError(`plan metadata part at index ${index} is not an object`);
+        }
+        const partId = raw.part_id;
+        if (typeof partId !== "string" || partId.trim() === "") {
+            throw new PlanLedgerError(`plan metadata part at index ${index} has an empty part_id`);
+        }
+        if (seenIds.has(partId)) {
+            throw new PlanLedgerError(`duplicate plan metadata part_id '${partId}'`);
+        }
+        seenIds.add(partId);
+        const producer = raw.producer;
+        if (typeof producer !== "string" || producer.trim() === "") {
+            throw new PlanLedgerError(`plan metadata part '${partId}' has an empty producer`);
+        }
+        const provenanceClass = raw.provenance_class;
+        if (typeof provenanceClass !== "string" ||
+            !PLAN_PROVENANCE_CLASSES.includes(provenanceClass)) {
+            throw new PlanLedgerError(`plan metadata part '${partId}' has unknown provenance class '${String(provenanceClass)}'`);
+        }
+        const startStep = raw.start_step;
+        const endStep = raw.end_step;
+        if (!isPositiveInteger(startStep)) {
+            throw new PlanLedgerError(`plan metadata part '${partId}' has a non-integer or non-positive start_step ${String(startStep)}`);
+        }
+        if (!isPositiveInteger(endStep)) {
+            throw new PlanLedgerError(`plan metadata part '${partId}' has a non-integer or non-positive end_step ${String(endStep)}`);
+        }
+        if (endStep < startStep) {
+            throw new PlanLedgerError(`plan metadata part '${partId}' has a reversed range ${startStep}-${endStep}`);
+        }
+        if (startStep <= previousEnd) {
+            throw new PlanLedgerError(`plan metadata part '${partId}' range ${startStep}-${endStep} overlaps or precedes '${previousId}' ending at ${previousEnd}; ranges must be disjoint and ascending`);
+        }
+        if (startStep > previousEnd + 1) {
+            // A gap is as dangerous as an overlap and far less visible. Routing iterates
+            // only the declared ranges, so a step falling in the gap is owned by no phase
+            // and settled by nobody — Miss 20's shape, reached by arithmetic rather than by
+            // a missing registry entry. Rejected here, before any phase runs.
+            throw new PlanLedgerError(`plan metadata part '${partId}' starts at step ${startStep} but '${previousId}' ended at ${previousEnd}; steps ${previousEnd + 1}-${startStep - 1} are claimed by no part and would be executed by no phase`);
+        }
+        previousEnd = endStep;
+        previousId = partId;
+        parts.push({
+            part_id: partId,
+            producer,
+            provenance_class: provenanceClass,
+            start_step: startStep,
+            end_step: endStep,
+            declared_advisory: raw.declared_advisory === true,
+        });
+    }
+    const totalSteps = value.total_steps;
+    if (typeof totalSteps !== "number" || !Number.isInteger(totalSteps)) {
+        throw new PlanLedgerError("plan metadata total_steps must be an integer");
+    }
+    if (totalSteps < previousEnd) {
+        throw new PlanLedgerError(`plan metadata total_steps ${totalSteps} is below the highest declared step ${previousEnd}`);
+    }
+    const declaredClasses = value.provenance_classes;
+    const derivedClasses = [];
+    for (const part of parts) {
+        if (!derivedClasses.includes(part.provenance_class)) {
+            derivedClasses.push(part.provenance_class);
+        }
+    }
+    if (Array.isArray(declaredClasses)) {
+        for (const declared of declaredClasses) {
+            if (!derivedClasses.includes(declared)) {
+                throw new PlanLedgerError(`plan metadata declares provenance class '${String(declared)}' that no part produces`);
+            }
+        }
+    }
+    return {
+        version: PLAN_METADATA_VERSION,
+        parts,
+        provenance_classes: derivedClasses,
+        total_steps: totalSteps,
+    };
+}
+// ---------------------------------------------------------------------------
+// Routing
+// ---------------------------------------------------------------------------
+/** Inclusive step IDs owned by `phase`, in plan order. */
+export function resolveOwnedSteps(metadata, phase) {
+    if (!PLAN_PHASES.includes(phase)) {
+        throw new PlanLedgerError(`unknown phase '${phase}'`);
+    }
+    const owned = [];
+    for (const part of metadata.parts) {
+        if (PLAN_CLASS_OWNERSHIP[part.provenance_class] !== phase)
+            continue;
+        for (let step = part.start_step; step <= part.end_step; step += 1) {
+            owned.push(step);
+        }
+    }
+    return owned;
+}
+/** The parts owned by `phase`, so a phase can report ranges rather than bare IDs. */
+export function resolveOwnedParts(metadata, phase) {
+    return metadata.parts.filter((part) => PLAN_CLASS_OWNERSHIP[part.provenance_class] === phase);
+}
+/**
+ * Fail unless every provenance class in the plan is claimed by an executing phase or
+ * explicitly declared advisory.
+ *
+ * `ownership` is injectable so a test can prove this assertion catches the historical
+ * defect: pass the pre-BAPI-763 registry (implementation and documentation only) and
+ * it fails on the review and rendered-UI classes.
+ */
+export function assertStepClassCoverage(metadata, ownership = PLAN_CLASS_OWNERSHIP) {
+    const unowned = [];
+    for (const part of metadata.parts) {
+        const owner = ownership[part.provenance_class];
+        if (owner === undefined) {
+            // Declared advisory is the ONLY sanctioned way for a class to go unexecuted,
+            // and it requires the plan to have said so. A phase's inability to run
+            // something never makes it advisory — that is how the gap stayed silent.
+            if (part.declared_advisory)
+                continue;
+            unowned.push(`class '${part.provenance_class}' (part '${part.part_id}', steps ${part.start_step}-${part.end_step}) has no executing phase and is not declared advisory`);
+            continue;
+        }
+        if (!PLAN_PHASES.includes(owner)) {
+            unowned.push(`class '${part.provenance_class}' is mapped to unknown phase '${String(owner)}'`);
+        }
+    }
+    if (unowned.length > 0) {
+        throw new PlanLedgerError(`plan step-class coverage failed — every class a planner can emit must be executed by some phase or declared advisory in the plan:\n  ${unowned.join("\n  ")}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Phase results
+// ---------------------------------------------------------------------------
+function validateRecordShape(record, metadata) {
+    if (!isPositiveInteger(record.stepId)) {
+        throw new PlanLedgerError(`ledger record has a non-positive stepId ${String(record.stepId)}`);
+    }
+    if (!PLAN_STEP_DISPOSITIONS.includes(record.disposition)) {
+        throw new PlanLedgerError(`step ${record.stepId} has unsupported disposition '${String(record.disposition)}'; expected one of ${PLAN_STEP_DISPOSITIONS.join(", ")}`);
+    }
+    if (record.disposition === "adapted") {
+        const adaptation = record.adaptation;
+        if (!adaptation) {
+            throw new PlanLedgerError(`step ${record.stepId} is 'adapted' but carries no adaptation record`);
+        }
+        if (!MECHANICAL_ADAPTATION_KINDS.includes(adaptation.kind)) {
+            throw new PlanLedgerError(`step ${record.stepId} uses unapproved adaptation kind '${String(adaptation.kind)}'; only ${MECHANICAL_ADAPTATION_KINDS.join(", ")} are mechanical — anything touching ${ESCALATION_ONLY_CATEGORIES.join(", ")} must escalate`);
+        }
+        for (const field of ["originalPremise", "correction", "rationale"]) {
+            const value = adaptation[field];
+            if (typeof value !== "string" || value.trim() === "") {
+                throw new PlanLedgerError(`step ${record.stepId} adaptation is missing required evidence '${field}'`);
+            }
+        }
+    }
+    else if (record.adaptation) {
+        throw new PlanLedgerError(`step ${record.stepId} carries an adaptation record but its disposition is '${record.disposition}'`);
+    }
+    if (record.disposition === "escalated") {
+        if (typeof record.escalationReason !== "string" || record.escalationReason.trim() === "") {
+            throw new PlanLedgerError(`step ${record.stepId} is 'escalated' but gives no blocking reason; an escalation must never read as completion`);
+        }
+    }
+    if (record.disposition === "unrun-advisory") {
+        const owningPart = metadata.parts.find((part) => record.stepId >= part.start_step && record.stepId <= part.end_step);
+        if (!owningPart || !owningPart.declared_advisory) {
+            throw new PlanLedgerError(`step ${record.stepId} claims 'unrun-advisory' but its plan part is not declared advisory; advisory status must be declared in the plan, never asserted by the phase that could not run it`);
+        }
+        if (typeof record.advisoryExplanation !== "string" ||
+            record.advisoryExplanation.trim() === "") {
+            throw new PlanLedgerError(`step ${record.stepId} is 'unrun-advisory' but gives no explanation of what was not run`);
+        }
+    }
+    if (record.renderedUi) {
+        const { cycles, cycleCount } = record.renderedUi;
+        if (!Array.isArray(cycles) || cycles.length === 0) {
+            throw new PlanLedgerError(`step ${record.stepId} reports rendered-UI work with no cycle rubric; the per-cycle table is the evidence that the loop actually ran`);
+        }
+        if (!isPositiveInteger(cycleCount) || cycleCount > RENDERED_UI_MAX_CYCLES) {
+            throw new PlanLedgerError(`step ${record.stepId} reports ${String(cycleCount)} rendered-UI cycles; the plan's cap is ${RENDERED_UI_MAX_CYCLES}`);
+        }
+        for (const cycle of cycles) {
+            if (!Array.isArray(cycle.rubric) || cycle.rubric.length === 0) {
+                throw new PlanLedgerError(`step ${record.stepId} rendered-UI cycle ${String(cycle.cycle)} has an empty rubric`);
+            }
+            if (!Array.isArray(cycle.acceptedFixes)) {
+                throw new PlanLedgerError(`step ${record.stepId} rendered-UI cycle ${String(cycle.cycle)} is missing its acceptedFixes list`);
+            }
+        }
+    }
+}
+/**
+ * Validate one phase's reported outcome against the steps it owns.
+ *
+ * Every owned step must be settled exactly once. An omission is the historical bug
+ * (work quietly not done), a duplicate makes the record ambiguous, and an unowned
+ * step means the phase acted outside its routing.
+ */
+export function validatePhaseResult(result, metadata, phase) {
+    if (!result || typeof result !== "object") {
+        throw new PlanLedgerError("phase result is missing");
+    }
+    if (result.version !== PLAN_METADATA_VERSION) {
+        throw new PlanLedgerError(`unsupported phase result version ${String(result.version)}; expected ${PLAN_METADATA_VERSION}`);
+    }
+    if (result.phase !== phase) {
+        throw new PlanLedgerError(`phase result declares phase '${String(result.phase)}' but was produced for '${phase}'`);
+    }
+    if (!Array.isArray(result.records)) {
+        throw new PlanLedgerError(`phase '${phase}' result has no records array`);
+    }
+    const owned = new Set(resolveOwnedSteps(metadata, phase));
+    const settled = new Set();
+    for (const record of result.records) {
+        validateRecordShape(record, metadata);
+        if (!owned.has(record.stepId)) {
+            throw new PlanLedgerError(`phase '${phase}' reported step ${record.stepId}, which it does not own`);
+        }
+        if (settled.has(record.stepId)) {
+            throw new PlanLedgerError(`phase '${phase}' reported step ${record.stepId} more than once`);
+        }
+        settled.add(record.stepId);
+    }
+    const missing = [...owned].filter((step) => !settled.has(step)).sort((a, b) => a - b);
+    if (missing.length > 0) {
+        throw new PlanLedgerError(`phase '${phase}' left owned steps unsettled: ${missing.join(", ")}. Every owned step must end as executed, adapted, escalated, or declared-advisory — there is no silent skip.`);
+    }
+    return result.records.map((record) => ({ ...record, phase }));
+}
+// ---------------------------------------------------------------------------
+// Durable merge
+// ---------------------------------------------------------------------------
+/** Terminal states that must not be silently walked back. */
+const SETTLED_DISPOSITIONS = new Set([
+    "executed",
+    "adapted",
+]);
+/**
+ * Merge a phase's validated records into the durable ledger.
+ *
+ * Chronological evidence is preserved: the returned ledger keeps every prior record
+ * and appends the new ones, so a resumed session reads history rather than a summary.
+ * A settled step may be superseded only by a record that explicitly says what
+ * invalidated it (`invalidatedBy`); anything else that would downgrade or drop it
+ * throws, because a quietly reverted "executed" is a false completion claim.
+ */
+export function mergePlanStepRecords(existing, incoming) {
+    const merged = [...existing];
+    for (const record of incoming) {
+        const priorIndex = [...merged]
+            .map((entry, index) => ({ entry, index }))
+            .filter(({ entry }) => entry.stepId === record.stepId)
+            .pop()?.index;
+        if (priorIndex !== undefined) {
+            const prior = merged[priorIndex];
+            const priorWasSettled = SETTLED_DISPOSITIONS.has(prior.disposition);
+            const wouldRegress = priorWasSettled && !SETTLED_DISPOSITIONS.has(record.disposition);
+            const isRerun = priorWasSettled && SETTLED_DISPOSITIONS.has(record.disposition);
+            if ((wouldRegress || isRerun) && !record.invalidatedBy) {
+                throw new PlanLedgerError(`step ${record.stepId} is already recorded as '${prior.disposition}'; re-recording it as '${record.disposition}' requires an explicit invalidatedBy note stating what invalidated the prior evidence`);
+            }
+        }
+        merged.push({ ...record });
+    }
+    return merged;
+}
+/** The latest record per step — what "current state" means over a chronological log. */
+export function currentLedgerState(ledger) {
+    const latest = new Map();
+    for (const record of ledger) {
+        latest.set(record.stepId, record);
+    }
+    return latest;
+}
+/** Records still needing human attention: escalations and declared-advisory gaps. */
+export function unresolvedLedgerRecords(ledger) {
+    return [...currentLedgerState(ledger).values()]
+        .filter((record) => record.disposition === "escalated" || record.disposition === "unrun-advisory")
+        .sort((a, b) => a.stepId - b.stepId);
+}
+/**
+ * Compare orchestration-observed usage against the configured bounds.
+ *
+ * Values exactly at a limit pass; only a value above it breaches. Returns the
+ * breaches rather than throwing so the caller can turn them into an escalation
+ * record — a bound that only produced a warning in prompt text is not a bound.
+ */
+export function validateExecutionLimits(observed, limits = PRE_PR_VERIFICATION_LIMITS) {
+    const breaches = [];
+    const checks = [
+        ["correctionTurns", observed.correctionTurns, limits.maxCorrectionTurns],
+        ["changedFiles", observed.changedFiles, limits.maxChangedFiles],
+        ["diffLines", observed.diffLines, limits.maxDiffLines],
+    ];
+    for (const [metric, value, limit] of checks) {
+        if (typeof value !== "number" || Number.isNaN(value)) {
+            throw new PlanLedgerError(`observed ${metric} is not a number; limits are enforced from orchestration-observed values, never from an agent's own account`);
+        }
+        if (value > limit) {
+            breaches.push({ metric, observed: value, limit });
+        }
+    }
+    return breaches;
+}
+// ---------------------------------------------------------------------------
+// Secret safety
+// ---------------------------------------------------------------------------
+const REDACTED = "[REDACTED]";
+/**
+ * Patterns for values that must never reach durable state or a log line.
+ *
+ * Each rewrites only the secret itself and keeps the surrounding key or scheme, so a
+ * redacted record still shows *that* a credential was involved — useful for audit,
+ * and materially different from dropping the field.
+ */
+const SECRET_PATTERNS = [
+    // Bearer / token schemes in an Authorization header or bare.
+    [/\b(Bearer|Basic|Token)\s+[A-Za-z0-9._~+/=-]{8,}/gi, `$1 ${REDACTED}`],
+    // authorization: <anything>
+    [/\b(authorization)\s*[:=]\s*\S+/gi, `$1: ${REDACTED}`],
+    // Well-known provider key shapes.
+    [/\b(sk|pk|rk)-[A-Za-z0-9_-]{16,}/g, REDACTED],
+    [/\bgh[pousr]_[A-Za-z0-9]{16,}/g, REDACTED],
+    // key/secret/password/token assignments in prose, env, JSON, or CLI form.
+    [
+        /\b([A-Za-z0-9_-]*(?:api[_-]?key|secret|password|passwd|token|credential)[A-Za-z0-9_-]*)\s*[:=]\s*("[^"]*"|'[^']*'|\S+)/gi,
+        `$1=${REDACTED}`,
+    ],
+    // Credentials embedded in a URL.
+    [/\b([a-z][a-z0-9+.-]*:\/\/)[^/\s:@]+:[^/\s@]+@/gi, `$1${REDACTED}@`],
+];
+/** Redact secret-bearing substrings while leaving safe technical text intact. */
+export function redactSecrets(value) {
+    let output = value;
+    for (const [pattern, replacement] of SECRET_PATTERNS) {
+        output = output.replace(pattern, replacement);
+    }
+    return output;
+}
+function redactDeep(value) {
+    if (typeof value === "string")
+        return redactSecrets(value);
+    if (Array.isArray(value))
+        return value.map((entry) => redactDeep(entry));
+    if (isPlainObject(value)) {
+        const output = {};
+        for (const [key, entry] of Object.entries(value)) {
+            output[key] = redactDeep(entry);
+        }
+        return output;
+    }
+    return value;
+}
+/**
+ * Redact a record before it is persisted or serialized.
+ *
+ * Redaction, not rejection: paths, commands, step identifiers, SHAs, and rubric text
+ * are exactly what makes the ledger auditable, so the record survives with its
+ * technical content and loses only the credential values.
+ */
+export function sanitizePlanStepRecord(record) {
+    return redactDeep(record);
+}
+export function sanitizePlanStepRecords(records) {
+    return records.map((record) => sanitizePlanStepRecord(record));
+}
+/**
+ * Build the audit-ready view of a run's ledger.
+ *
+ * Unresolved records come first and separately: an escalation buried at position 40
+ * of a chronological log reads as a completed run at a glance, which defeats the
+ * point of recording it.
+ */
+export function buildLedgerRunDetail(ledger, options = {}) {
+    const sanitized = sanitizePlanStepRecords(ledger);
+    const latest = [...currentLedgerState(sanitized).values()];
+    const summary = {
+        executed: latest.filter((r) => r.disposition === "executed").length,
+        adapted: latest.filter((r) => r.disposition === "adapted").length,
+        escalated: latest.filter((r) => r.disposition === "escalated").length,
+        unrunAdvisory: latest.filter((r) => r.disposition === "unrun-advisory").length,
+        total: latest.length,
+    };
+    return {
+        metadataVersion: PLAN_METADATA_VERSION,
+        summary,
+        unresolved: unresolvedLedgerRecords(sanitized),
+        ledger: sanitized,
+        ...(options.checkpoint ? { checkpoint: options.checkpoint } : {}),
+    };
+}