in2-agent-server 0.20260821.185429

package/dist/core/paths.js

@@ -0,0 +1,105 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { IN2_HOME, isNpmInstall } from "./install.js";
+// Compiled location is dist/core/paths.js, so the app root is two levels up.
+const APP_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+export const APP_ROOT = APP_DIR;
+// Where durable machine state roots (.local/cc-mcp/: grants, telemetry outboxes, sessions, org
+// mirrors). An npm install anchors it at ~/.in2-agent — NEVER relative to the package: the package
+// directory is replaced wholesale on update and moves with the npm prefix, and grants that silently
+// relocate on a Node upgrade are grants that silently vanish. A repo checkout keeps the old
+// two-levels-up (the monorepo root), which is what every dev flow and test fixture assumes.
+export const REPO_ROOT = process.env.CC_MCP_REPO_ROOT?.trim() || (isNpmInstall() ? IN2_HOME : path.resolve(APP_DIR, "..", ".."));
+// Analyzer skills. The bundle stages harness/skills as <root>/skills, so a shipped install and a
+// repo checkout resolve differently — and the shipped case is the one that used to be missing
+// entirely, which left every consultant's supervisor with no SKILL.md to hand its analyzers.
+export const SKILLS_DIR = existsSync(path.join(APP_DIR, "skills"))
+    ? path.join(APP_DIR, "skills")
+    : path.join(APP_DIR, "harness", "skills");
+// The deep supervisor reference (full loop rationale, live-caught lemmas, refusal handling,
+// successor-batch playbook). The bundle stages harness/supervisor-playbook.md as <root>/reference/
+// supervisor-playbook.md — it used to not ship at all, so on a consultant's machine the MCP
+// `instructions` were the ONLY contract text, and clients truncate those to a few KB.
+export const SUPERVISOR_PLAYBOOK_PATH = existsSync(path.join(APP_DIR, "reference", "supervisor-playbook.md"))
+    ? path.join(APP_DIR, "reference", "supervisor-playbook.md")
+    : path.join(APP_DIR, "harness", "supervisor-playbook.md");
+// How the supervisor talks to the human — translation table, card rules, report skeleton.
+// Ships under reference/ with the CI guide (build-artifact copies harness/reference wholesale).
+export const OPERATOR_VOICE_PATH = existsSync(path.join(APP_DIR, "reference", "operator-voice.md"))
+    ? path.join(APP_DIR, "reference", "operator-voice.md")
+    : path.join(APP_DIR, "harness", "reference", "operator-voice.md");
+export const WORKSPACE_ROOT = process.env.CC_MCP_WORKSPACE_ROOT?.trim() ||
+    path.join(REPO_ROOT, ".local", "cc-mcp", "sessions");
+/**
+ * Where the per-org git mirrors live, one directory per 18-char org id (origin R1).
+ *
+ * A SIBLING of the session workspace rather than a child, because the two have opposite lifetimes:
+ * a session is an engagement's working directory and is deletable once its evidence has shipped,
+ * while the mirror is the accumulated history of everything IN2 has ever done to that org and must
+ * outlive every session that contributed to it. Derived from WORKSPACE_ROOT so an install that
+ * relocates its workspace takes its mirrors with it rather than stranding them under the repo.
+ *
+ * No operator-facing git concept exists anywhere above this line — the mirror is a rebuildable
+ * cache read through `direct_history`, never a repository anyone is asked to think about.
+ */
+export const ORGREPO_ROOT = process.env.CC_MCP_ORGREPO_ROOT?.trim() || path.resolve(WORKSPACE_ROOT, "..", "orgrepo");
+/**
+ * Who the operator is, for the commit's `Operator:` trailer.
+ *
+ * NOT the commit author: the author and committer are fixed constants so that identical bundle
+ * sets produce identical SHAs on any machine (origin R5). Operator identity is a fact ABOUT the
+ * wave, so it rides a trailer where it cannot perturb the hash.
+ */
+export const OPERATOR_IDENTITY = process.env.CC_MCP_OPERATOR?.trim() || undefined;
+/**
+ * Content hash of the harness this install is RUNNING — the playbook plus every skill file.
+ *
+ * The skills are GENERATED from the harness, and the two travel in the same package, so they
+ * should always agree. They can still diverge in practice: the copy in ~/.claude/skills is only
+ * re-synced when a server STARTS, so a machine that updated the package but has not yet started a
+ * new session is following superseded instructions while reporting the new server version.
+ * Nothing surfaced that; it had to be inferred from behaviour.
+ *
+ * Hashing content rather than reading a declared version number means the answer cannot drift from
+ * what is actually on disk — a stamped number is a claim, a hash is a measurement.
+ *
+ * Cheap and cached: a handful of files, read once per process.
+ */
+let cachedHarnessVersion;
+export function harnessVersion() {
+    if (cachedHarnessVersion !== undefined)
+        return cachedHarnessVersion || undefined;
+    try {
+        const files = [];
+        if (existsSync(SUPERVISOR_PLAYBOOK_PATH))
+            files.push(SUPERVISOR_PLAYBOOK_PATH);
+        const walk = (dir) => {
+            if (!existsSync(dir))
+                return;
+            for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory())
+                    walk(full);
+                else if (entry.name.endsWith(".md"))
+                    files.push(full);
+            }
+        };
+        walk(SKILLS_DIR);
+        if (files.length === 0) {
+            cachedHarnessVersion = "";
+            return undefined;
+        }
+        const hash = createHash("sha256");
+        for (const file of files)
+            hash.update(readFileSync(file));
+        cachedHarnessVersion = hash.digest("hex").slice(0, 16);
+        return cachedHarnessVersion;
+    }
+    catch {
+        // Never let a version stamp break telemetry.
+        cachedHarnessVersion = "";
+        return undefined;
+    }
+}

package/dist/core/phases.js

@@ -0,0 +1,225 @@
+// THE CHAPTER STRUCTURE OF A DELIVERY RUN — the vocabulary, the ledger, and the transition rule.
+//
+// WHY A RUN NEEDS EXPLICIT BOUNDARIES AT ALL, given that it already has a contract and a playbook.
+//
+// Three separate holes closed by one seam:
+//
+//   1. THE DOCTRINE DIET NEEDS A JUST-IN-TIME CHANNEL. The 2026-08-04 audit cut the resident
+//      contract to a loop SKELETON (`supervisorContract.ts`) on the measured ground that a client
+//      truncated it at byte 2,050. The expanded per-step detail had nowhere to go but the playbook,
+//      which is read once at the start of a run and is 60 KB — so the model reads the delivery
+//      rules an hour before it delivers, and the writeback rules ninety minutes before it writes
+//      back. `advance_phase` returns a chapter's instructions AT the chapter, which is the only
+//      arrival time that composes with a skeletal resident contract.
+//
+//   2. A RUN THAT DIES SHIPS NOTHING. `close_batch` is the only thing that flushes the telemetry
+//      outbox and uploads the transcript, and it runs at the END. A run killed at wave three — a
+//      Windows client teardown, a crashed host, an operator who closed the window — leaves every
+//      event of that batch in the local outbox with nothing scheduled to drain it, and no
+//      transcript on the ledger at all. A boundary is a natural, already-motivated moment to ship
+//      what has happened so far, and there are eight of them before the end.
+//
+//   3. A DEAD RUN CANNOT BE PICKED UP. Everything a session produced is on disk and session-scoped
+//      — brief, plan.json files, wave bundles, question rounds — but nothing recorded WHERE THE RUN
+//      HAD GOT TO, so a fresh session had to infer the position from artifacts and would guess
+//      wrong in the one direction that matters (a phase entered but not finished looks identical to
+//      one never entered). The ledger states it.
+//
+// THE LEDGER IS APPEND-ONLY JSONL, one line per boundary, under the session directory beside every
+// other artifact. Append-only rather than a single mutable "current phase" file for the reason the
+// wave bundles are append-only: the question a resumed session asks is not only "where are we" but
+// "what was skipped, and when did this run stall", and a file that only holds the head cannot
+// answer either.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { isoNow } from "./ids.js";
+import { ensureDir, phaseLedgerFile } from "./workspace.js";
+/**
+ * THE NINE CHAPTERS, IN ORDER. This array IS the order — every rule below indexes into it, so
+ * inserting a chapter here is the whole edit.
+ *
+ * They are named for what the OPERATOR would call the stretch of work, not for the tool that
+ * dominates it, because the same names appear in the progress lines the supervisor relays. The one
+ * exception is `parallel-analysis`, which is named for its mechanism because its mechanism is the
+ * thing most often got wrong (serial dispatch, or no fan-out at all).
+ */
+export const CHAPTERS = [
+    "activation",
+    "intake",
+    "partitioning",
+    "parallel-analysis",
+    "clarification",
+    "scope-approval",
+    "delivery",
+    "review-results",
+    "writeback-close"
+];
+export function isChapter(value) {
+    return CHAPTERS.includes(value);
+}
+export function chapterIndex(chapter) {
+    return CHAPTERS.indexOf(chapter);
+}
+/**
+ * The chapters a run may legitimately jump over.
+ *
+ * SMALL BATCHES REALLY DO SKIP THESE, and the playbook says so in as many words: three requirements
+ * two of which name the same object can be analyzed inline, which skips `partitioning` (there is
+ * nothing to partition) and `parallel-analysis` (there is no fan-out); a batch that raises no
+ * genuine fork skips `clarification`, because the playbook's own rule is that a question whose
+ * recommendation you would follow anyway is an assumption to state rather than a round-trip to
+ * spend. Refusing those would make the ledger a thing to work around.
+ *
+ * EVERY OTHER CHAPTER IS LOAD-BEARING and skipping it is a defect worth naming: a run cannot reach
+ * delivery without having read the requirements (`intake`), and it cannot deploy without an
+ * approval card (`scope-approval`). The one escape is stated in `planTransition` — ending the run
+ * early is always legal, so `writeback-close` is reachable from anywhere.
+ */
+export const SKIPPABLE_CHAPTERS = new Set([
+    "partitioning",
+    "parallel-analysis",
+    "clarification"
+]);
+export const PHASE_LEDGER_SCHEMA_VERSION = "cc-phase-ledger-v1";
+/**
+ * Is this boundary legal, and what does crossing it imply was skipped?
+ *
+ * PURE, over the ledger's head plus the two chapter names, so the whole rule is testable without a
+ * session on disk — and so the refusal messages can be asserted verbatim, since they are the only
+ * thing a supervisor that got this wrong will read.
+ *
+ * THE RULE, in the order it is checked:
+ *   - `entering` must be strictly after `completed`. A backwards or same-chapter move is refused:
+ *     a second clarification round is not a boundary, it is more of one chapter.
+ *   - `completed` may be AHEAD of the ledger's head (the run crossed boundaries without saying so,
+ *     which is the common shape on a first adoption) but never BEHIND it.
+ *   - Jumping over a non-skippable chapter is refused BY NAME, with one exception: ending the run
+ *     is always legal, so `writeback-close` is reachable from any chapter. That exception is not a
+ *     loophole, it is the doctrine — `close_batch` is called equally when a run ends badly, and a
+ *     ledger that refused the boundary in front of it would be an argument for not closing.
+ */
+export function planTransition(input) {
+    const { head } = input;
+    if (!isChapter(input.completed) || !isChapter(input.entering)) {
+        const bad = !isChapter(input.completed) ? input.completed : input.entering;
+        return {
+            ok: false,
+            code: "PHASE_UNKNOWN",
+            message: `${JSON.stringify(bad)} is not a chapter of a delivery run. The nine, in order: ${CHAPTERS.join(" -> ")}.`
+        };
+    }
+    const completed = input.completed;
+    const entering = input.entering;
+    const from = chapterIndex(completed);
+    const to = chapterIndex(entering);
+    if (to <= from) {
+        return {
+            ok: false,
+            code: "PHASE_OUT_OF_ORDER",
+            message: to === from
+                ? `You named ${completed} as both finished and entering. A second round inside one chapter is not a boundary — advance_phase marks the move BETWEEN chapters, so keep working and call it when ${entering} is genuinely done. The order is ${CHAPTERS.join(" -> ")}.`
+                : `${entering} comes BEFORE ${completed}, so this is a step backwards and nothing was recorded. Chapters only move forward; if earlier work has to be redone, do it inside the chapter you are in and cross the next boundary when it is finished. The order is ${CHAPTERS.join(" -> ")}.`
+        };
+    }
+    if (head !== null && from < chapterIndex(head)) {
+        return {
+            ok: false,
+            code: "PHASE_ALREADY_PASSED",
+            message: `This session's ledger already records ${head} as entered, so ${completed} is behind where the run stands and nothing was recorded. Call advance_phase with completed: ${JSON.stringify(head)} once ${head} is genuinely finished.`
+        };
+    }
+    const skipped = CHAPTERS.slice(from + 1, to);
+    const blocked = entering === "writeback-close" ? [] : skipped.filter((c) => !SKIPPABLE_CHAPTERS.has(c));
+    if (blocked.length > 0) {
+        return {
+            ok: false,
+            code: "PHASE_SKIP_NOT_ALLOWED",
+            message: [
+                `Going from ${completed} straight to ${entering} jumps over ${blocked.join(", ")}, which no run may skip — nothing was recorded.`,
+                `Skippable: ${[...SKIPPABLE_CHAPTERS].join(", ")} (a batch small enough to analyze inline really does skip the fan-out, and a batch that raises no genuine fork really does skip clarification).`,
+                `${blocked.join(", ")} ${blocked.length === 1 ? "is" : "are"} not: reaching ${entering} without ${blocked.length === 1 ? "it" : "them"} means the run has no ${blocked.includes("scope-approval") ? "approved plan" : "grounding"} behind it.`,
+                `If the run is ENDING here rather than progressing — rejected, blocked, stopped early — advance to writeback-close instead, which is reachable from anywhere, and then call close_batch.`
+            ].join("\n")
+        };
+    }
+    return { ok: true, skipped };
+}
+/**
+ * Every ledger entry this session has written, oldest first.
+ *
+ * TOLERANT LINE BY LINE, like every other reader of an append-only file here: a half-written final
+ * line after a hard kill is exactly the shape this file exists to survive, so it is skipped rather
+ * than allowed to make the whole ledger unreadable. A resumed session reading four good lines and
+ * ignoring a torn fifth knows more than one that refused the file.
+ */
+export async function readPhaseLedger(sessionId) {
+    let raw;
+    try {
+        raw = await fs.readFile(phaseLedgerFile(sessionId), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.entering === "string" && isChapter(parsed.entering))
+                entries.push(parsed);
+        }
+        catch {
+            // A torn final line is the expected cost of appending without a lock; it names no chapter.
+        }
+    }
+    return entries;
+}
+/** The chapter the run is IN — the last one entered, by any entry kind. */
+export function ledgerHead(entries) {
+    return entries.length > 0 ? entries[entries.length - 1].entering : null;
+}
+/**
+ * Append one entry.
+ *
+ * `fs.appendFile` rather than the read-modify-write `writeJsonAtomic` every other session artifact
+ * uses, and that is the point of choosing JSONL: an append is the one file operation that cannot
+ * lose what is already there, which matters most for the artifact whose whole job is to survive a
+ * process that did not get to finish.
+ */
+export async function appendPhaseLedger(entry) {
+    const file = phaseLedgerFile(entry.sessionId);
+    await ensureDir(path.dirname(file));
+    await fs.appendFile(file, `${JSON.stringify(entry)}\n`, "utf8");
+}
+export function newLedgerEntry(input) {
+    return {
+        schemaVersion: PHASE_LEDGER_SCHEMA_VERSION,
+        kind: input.kind,
+        at: input.at ?? isoNow(),
+        sessionId: input.sessionId,
+        ...(input.completed ? { completed: input.completed } : {}),
+        entering: input.entering,
+        ...(input.skipped && input.skipped.length > 0 ? { skipped: input.skipped } : {}),
+        ...(input.note ? { note: input.note } : {}),
+        ...(input.runId ? { runId: input.runId } : {}),
+        ...(input.batchId ? { batchId: input.batchId } : {})
+    };
+}
+/** How long the run has been sitting where it is — the first thing a resumed session states. */
+export function describeStall(entries, now = new Date()) {
+    const last = entries[entries.length - 1];
+    if (!last)
+        return null;
+    const at = Date.parse(last.at);
+    if (!Number.isFinite(at))
+        return null;
+    const ms = Math.max(0, now.getTime() - at);
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 60)
+        return `${minutes} minute(s) ago`;
+    const hours = Math.round(ms / 3_600_000);
+    if (hours < 48)
+        return `${hours} hour(s) ago`;
+    return `${Math.round(ms / 86_400_000)} day(s) ago`;
+}

package/dist/core/planFile.js

@@ -0,0 +1,251 @@
+import { promises as fs } from "node:fs";
+/** The legal `intent` values, in one place, so the refusal message cannot drift from the parser. */
+const INTENTS = ["create", "update", "delete"];
+/** `CustomField:PV_Asset__c.PV_Critical__c` — component identity, unchanged by the revision model. */
+export const componentKey = (typeName, fullName) => `${typeName}:${fullName}`;
+/**
+ * Parse one requirement's plan.json.
+ *
+ * `extId` is the requirement the file was found under, which is authoritative over anything the
+ * document says about itself — the directory is what the requirements index and every writeback
+ * path key on.
+ */
+export function parsePlanFile(text, extId, file) {
+    let document;
+    try {
+        document = JSON.parse(text);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: {
+                code: "PLAN_MALFORMED",
+                message: `plan.json for ${extId} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+                ...(file ? { file } : {})
+            }
+        };
+    }
+    if (document === null || typeof document !== "object" || Array.isArray(document)) {
+        return {
+            ok: false,
+            error: { code: "PLAN_SHAPE_INVALID", message: `plan.json for ${extId} is not a JSON object.`, ...(file ? { file } : {}) }
+        };
+    }
+    const doc = document;
+    const rawComponents = doc.components;
+    // A plan with no `components` key is legal — an analyzer that found nothing to own writes one.
+    // A `components` that is present but not a list is a shape error, not an empty plan: reading it
+    // as zero components would report a broken plan as a requirement that owns nothing.
+    if (rawComponents !== undefined && !Array.isArray(rawComponents)) {
+        return {
+            ok: false,
+            error: { code: "PLAN_SHAPE_INVALID", message: `plan.json for ${extId} has a \`components\` field that is not a list.`, ...(file ? { file } : {}) }
+        };
+    }
+    const entries = [];
+    const deprecations = [];
+    const skipped = [];
+    const refusals = [];
+    const components = (rawComponents ?? []);
+    for (let index = 0; index < components.length; index++) {
+        const node = components[index];
+        if (node === null || typeof node !== "object" || Array.isArray(node)) {
+            skipped.push({ extId, index, reason: "component entry is not an object" });
+            continue;
+        }
+        const raw = node;
+        const typeName = stringOrNull(raw.typeName);
+        const fullName = stringOrNull(raw.fullName);
+        // The three existing readers all `continue` past an entry missing either half of the identity.
+        // Kept — but recorded, because "the plan named something this could not identify" and "the plan
+        // named nothing" are different facts and only one of them needs an analyzer to go fix it.
+        if (!typeName || !fullName) {
+            skipped.push({ extId, index, reason: "component entry has no typeName and/or fullName" });
+            continue;
+        }
+        const key = componentKey(typeName, fullName);
+        let intent = null;
+        const rawIntent = raw.intent;
+        const authoredFile = stringOrNull(raw.authoredFile);
+        if (rawIntent !== undefined && rawIntent !== null) {
+            if (INTENTS.includes(rawIntent)) {
+                intent = rawIntent;
+            }
+            else {
+                // Not "needs inference": the entry DID declare something, and it was not a legal intent.
+                // Reading it as undeclared would run the inference fallback on an entry whose author
+                // believed they had settled the question.
+                refusals.push({
+                    code: "INVALID_INTENT",
+                    key,
+                    message: `${extId} entry ${index} (${key}) declares intent ${JSON.stringify(rawIntent)}; the only legal values are ${INTENTS.map((i) => `"${i}"`).join(", ")}.`,
+                    entries: [{ extId, index, key, authoredFile, intent: null }]
+                });
+            }
+        }
+        if (intent === "delete" && authoredFile !== null) {
+            // A deletion has no source file. Tolerating the binding would leave a file bound to an entry
+            // the assembler could still resolve — which deploys the component this entry declares gone.
+            // Refused rather than ignored: the author wrote a path, so they believed one belonged here,
+            // and dropping it silently would settle that disagreement without telling them.
+            refusals.push({
+                code: "DELETE_BINDS_FILE",
+                key,
+                message: [
+                    `${extId} entry ${index} (${key}) declares intent "delete" and also binds authoredFile ${JSON.stringify(authoredFile)}.`,
+                    "A deletion has no authored file — there is no source for a component that is being removed, and a bound file",
+                    "is one the assembler can copy into a wave, deploying the very component this entry exists to delete.",
+                    'Drop the `authoredFile`, or declare the entry `intent: "update"` if the file is a state you meant to deploy.'
+                ].join("\n"),
+                entries: [{ extId, index, key, authoredFile, intent }]
+            });
+        }
+        const deprecatedAction = stringOrNull(raw.action);
+        if (deprecatedAction !== null) {
+            deprecations.push({ extId, key, field: "action", value: deprecatedAction });
+        }
+        entries.push({
+            typeName,
+            fullName,
+            key,
+            extId,
+            index,
+            intent,
+            authoredFile,
+            dependsOn: Array.isArray(raw.dependsOn) ? raw.dependsOn.filter((d) => typeof d === "string") : [],
+            // `deployable` defaults TRUE on absence — the same default all three readers use today.
+            deployable: raw.deployable !== false,
+            // Unrecognized causes read as null (ordinary manual, counted against the rate) — the
+            // fail-closed direction: a typo can under-exclude, never over-exclude.
+            routeCause: raw.routeCause === "not_metadata" || raw.routeCause === "impossible" ? raw.routeCause : null,
+            provisional: raw.provisional === true,
+            blockedBy: stringOrNull(raw.blockedBy),
+            deprecatedAction,
+            raw
+        });
+    }
+    refusals.push(...checkRevisionBindings(entries));
+    return {
+        ok: true,
+        plan: {
+            extId,
+            declaredExtId: stringOrNull(doc.extId),
+            entries,
+            deprecations,
+            refusals,
+            skipped,
+            document: doc,
+            source: text,
+            dirty: false
+        }
+    };
+}
+/** Read and parse a plan.json from disk. ENOENT is its own code — an unwritten plan is not a broken one. */
+export async function readPlanFile(file, extId) {
+    let text;
+    try {
+        text = await fs.readFile(file, "utf8");
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT") {
+            return { ok: false, error: { code: "PLAN_NOT_FOUND", message: `No plan.json for ${extId} at ${file}. The analyzer has not run, or the extId is wrong.`, file } };
+        }
+        return {
+            ok: false,
+            error: { code: "PLAN_UNREADABLE", message: `plan.json for ${extId} at ${file} could not be read: ${error instanceof Error ? error.message : String(error)}`, file }
+        };
+    }
+    return parsePlanFile(text, extId, file);
+}
+/**
+ * R3, checked over whatever scope the caller hands in.
+ *
+ * BATCH-SCOPED BY DESIGN. The shape this model exists for — EV-31 creates the field, EV-40 updates
+ * it — puts the two revisions in two DIFFERENT plan.json files, where each file sees one entry per
+ * key and a per-file check would find nothing wrong. `parsePlanFile` runs this over its own entries
+ * so a within-file duplication still refuses at parse; callers that hold the whole batch
+ * (`plan_waves`, the internal assembler) must run it again over the union.
+ *
+ * Counts DEPLOYABLE, FILE-BEARING entries only. Two kinds are excluded because neither has a file
+ * to bind: a `deployable: false` entry is a route, not a revision (R4), and a `delete` entry is a
+ * component's removal, which no file expresses. Counting a delete would refuse the plainest shape
+ * this model exists to legalize — one requirement creates a component, another deletes it — by
+ * demanding an `authoredFile` on the create that single-revision discovery has always made optional.
+ */
+export function checkRevisionBindings(entries) {
+    const byKey = new Map();
+    for (const entry of entries) {
+        if (!entry.deployable || entry.intent === "delete")
+            continue;
+        const group = byKey.get(entry.key) ?? [];
+        group.push(entry);
+        byKey.set(entry.key, group);
+    }
+    const refusals = [];
+    for (const [key, group] of byKey) {
+        if (group.length < 2)
+            continue;
+        const unbound = group.filter((e) => e.authoredFile === null);
+        if (unbound.length === 0)
+            continue;
+        refusals.push({
+            code: "MISSING_REVISION_BINDING",
+            key,
+            message: [
+                `${key} has ${group.length} entries — two revisions of one component — but ${unbound.length} of them declare no \`authoredFile\`.`,
+                "With more than one entry per component, nothing can tell which authored file belongs to which revision;",
+                "every entry for the key must name its own file. Entries:",
+                ...group.map((e) => `  ${e.extId} entry ${e.index}: intent=${e.intent ?? "(undeclared)"} authoredFile=${e.authoredFile ?? "(none)"}`)
+            ].join("\n"),
+            entries: group.map(entryRef)
+        });
+    }
+    return refusals;
+}
+/** Point a refusal at an entry without handing out the mutable document node. */
+export function entryRef(entry) {
+    return { extId: entry.extId, index: entry.index, key: entry.key, authoredFile: entry.authoredFile, intent: entry.intent };
+}
+/**
+ * Render the plan back to text.
+ *
+ * Byte-identical to what was parsed until something actually changed it — a read-modify-write that
+ * modified nothing must not reformat a file the operator hand-edited, and a diff that shows every
+ * line moved is a diff nobody reads. After a mutation it renders at the same 2-space indent with a
+ * trailing newline `tools/analyze.ts:176` already writes, so the only churn is the change itself.
+ */
+export function serializePlanFile(plan) {
+    if (!plan.dirty)
+        return plan.source;
+    return `${JSON.stringify(plan.document, null, 2)}\n`;
+}
+/**
+ * Drop one entry — `resolve_blocker`'s `drop`, addressed at a single revision.
+ *
+ * Takes the ENTRY, not the key: under the revision model a key can name two entries, and the whole
+ * point of addressing by entry is that dropping "the component" would take both.
+ */
+export function removeEntry(plan, entry) {
+    const components = plan.document.components;
+    if (!Array.isArray(components))
+        return false;
+    const at = components.indexOf(entry.raw);
+    if (at < 0)
+        return false;
+    components.splice(at, 1);
+    plan.dirty = true;
+    return true;
+}
+/** Clear `provisional`/`blockedBy` on one entry — `resolve_blocker`'s `promote`, per revision. */
+export function clearProvisional(plan, entry) {
+    if (!("provisional" in entry.raw) && !("blockedBy" in entry.raw))
+        return false;
+    delete entry.raw.provisional;
+    delete entry.raw.blockedBy;
+    plan.dirty = true;
+    return true;
+}
+function stringOrNull(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}