@open-everywhere/core 0.1.0

package/dist/agent/scaffold/roster-plan.js

@@ -0,0 +1,668 @@
+// THE ROSTER PLANNER (OPE-375) — validate → resolve → plan, as a TOTAL FUNCTION of its arguments.
+//
+// PURE: no `node:fs`, no clock, no environment, no network, no module loading. Everything the plan
+// depends on — the config object, the lock, each package's manifest and version, eve's framework
+// tool names — is passed IN, so the same inputs always produce the same plan. That is the whole of
+// "`oe build` is as boring-reliable as `next build`": determinism is a property of this module, and
+// `scripts/roster-test.ts` asserts it by planning twice and by permuting config key order.
+//
+// The disk half lives next door in `roster-fs.ts`, mirroring the existing `tool-roster.ts` /
+// `tool-roster-read.ts` split — a caller that must stay pure (the config snapshot's `mounted`
+// section) imports this file and inherits no filesystem edge.
+//
+// ─── WHAT THE PLAN IS ────────────────────────────────────────────────────────────────────────
+// A sorted list of `{ path, content }` covering the SIX eve slot directories plus
+// `agent/lib/providers.generated.ts`. The build OWNS each slot directory wholesale: anything in one
+// that is not in the plan is deleted. There is no cache and no incremental mode — 131 tiny files is
+// sub-100ms, and staleness is the enemy the design rules out by construction.
+//
+// ─── THE GOVERNANCE PROPERTY ─────────────────────────────────────────────────────────────────
+// A capability is never granted silently. Today that costs a committed FILE; here it costs a
+// committed LOCK LINE (and, for a decline, a committed REASON). A contribution present in a
+// package's manifest but absent from the lock is UNREVIEWED and reds the build — that is what makes
+// `npm update @open-everywhere/core` a decision rather than an event. There is deliberately NO
+// bypass flag: an escape hatch under time pressure becomes the default path within a week.
+import { CONTRIBUTION_KINDS, ROSTER_GENERATOR_VERSION, SLOT_DIR, } from "./roster-config.js";
+// ONE vocabulary for "mounted vs disabled" (OPE-258): the row values the config snapshot records and
+// `classifyRosterTransition` reads come from the same two constants the old file-reading gate used.
+// Two classifiers for one concern is how the snapshot and the gate come to disagree.
+import { PRIMITIVE_DISABLED, PRIMITIVE_MOUNTED } from "./tool-roster.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Slug grammar (eve's, copied deliberately)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * eve's own slug patterns, from `eve/dist/src/discover/grammar.js`. COPIED rather than imported:
+ * they are not a public export, and reaching into eve's minified internals from a PURE module would
+ * give this planner a runtime dependency it must not have. `scripts/roster-test.ts` pins the copies
+ * against the shapes eve accepts; an eve upgrade that tightens a pattern shows up as a build red in
+ * our own tree long before a deployer's.
+ */
+const SLUG_PATTERN = {
+    tool: /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/u,
+    channel: /^(\.?[a-z][a-z0-9-]{0,63}|\[[a-zA-Z][a-zA-Z0-9_]{0,63}\])$/u,
+    hook: /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/u,
+    // eve has no dedicated schedule/skill slug pattern; both are flat module slots discovered by
+    // basename, so the permissive tool grammar is the honest constraint to enforce here.
+    schedule: /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/u,
+    skill: /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/u,
+    connection: /^[a-z][a-z0-9-]{0,63}$/u,
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Small helpers
+// ─────────────────────────────────────────────────────────────────────────────
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Wrap prose to `width` columns, preserving explicit newlines as paragraph breaks. */
+export function wrapComment(text, width) {
+    const out = [];
+    for (const para of text.split("\n")) {
+        const words = para.trim().split(/\s+/u).filter((w) => w.length > 0);
+        if (words.length === 0) {
+            out.push("");
+            continue;
+        }
+        let line = "";
+        for (const word of words) {
+            if (line.length === 0)
+                line = word;
+            else if (line.length + 1 + word.length <= width)
+                line += ` ${word}`;
+            else {
+                out.push(line);
+                line = word;
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
+/** Stable key: `"<kind>/<name>"`. The lock's and the collision index's one grammar. */
+export const contributionKey = (kind, name) => `${kind}/${name}`;
+function sortedRecord(record) {
+    const out = {};
+    for (const key of Object.keys(record).sort((a, b) => a.localeCompare(b)))
+        out[key] = record[key];
+    return out;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Config parsing (rules 1–3) — structural, before anything is resolved
+// ─────────────────────────────────────────────────────────────────────────────
+const CONFIG_KEYS = new Set(["framework", "core", "adapters", "providers", "packages", "subagents", "output"]);
+function checkDecision(where, value, reds) {
+    if (typeof value === "boolean")
+        return;
+    if (!isRecord(value)) {
+        reds.push(`CONFIG · ${where} must be true, false, or an object of { exclude, note, about } — got ${typeof value}.`);
+        return;
+    }
+    for (const key of Object.keys(value)) {
+        if (key !== "exclude" && key !== "note" && key !== "about") {
+            reds.push(`CONFIG · ${where}.${key} is not a known key. Expected one of: exclude, note, about.`);
+        }
+    }
+    if (value.about !== undefined && typeof value.about !== "string") {
+        reds.push(`CONFIG · ${where}.about must be a string.`);
+    }
+    for (const field of ["exclude", "note"]) {
+        const map = value[field];
+        if (map === undefined)
+            continue;
+        if (!isRecord(map)) {
+            reds.push(`CONFIG · ${where}.${field} must be an object mapping a contribution key to a string.`);
+            continue;
+        }
+        for (const [key, reason] of Object.entries(map)) {
+            if (typeof reason !== "string") {
+                reds.push(`CONFIG · ${where}.${field}["${key}"] must be a string.`);
+                continue;
+            }
+            // RULE 3 — a decline with no reason is the one a later reader deletes by accident.
+            if (field === "exclude" && reason.trim().length === 0) {
+                reds.push(`CONFIG · ${where}.exclude["${key}"] has an empty reason. Every exclusion carries WHY this ` +
+                    `deployment declines the capability — that text is the review surface.`);
+            }
+        }
+    }
+}
+/** RULES 1–3: the config is an object of known keys whose decisions are well-shaped. */
+export function parseRosterConfig(raw) {
+    const reds = [];
+    if (!isRecord(raw)) {
+        return { reds: [`CONFIG · roster.config.ts must \`export default defineRoster({ … })\` — got ${raw === undefined ? "no default export" : typeof raw}.`] };
+    }
+    for (const key of Object.keys(raw)) {
+        if (!CONFIG_KEYS.has(key)) {
+            reds.push(`CONFIG · unknown top-level key "${key}". Expected one of: ${[...CONFIG_KEYS].sort().join(", ")}.`);
+        }
+    }
+    if (raw.framework !== undefined) {
+        if (!isRecord(raw.framework))
+            reds.push(`CONFIG · framework must be an object with a \`disable\` map.`);
+        else {
+            for (const key of Object.keys(raw.framework)) {
+                if (key !== "disable")
+                    reds.push(`CONFIG · framework.${key} is not a known key. Expected: disable.`);
+            }
+            const disable = raw.framework.disable;
+            if (disable !== undefined) {
+                if (!isRecord(disable))
+                    reds.push(`CONFIG · framework.disable must be an object mapping an eve tool name to a reason.`);
+                else {
+                    for (const [name, reason] of Object.entries(disable)) {
+                        if (typeof reason !== "string" || reason.trim().length === 0) {
+                            reds.push(`CONFIG · framework.disable["${name}"] has no reason. A sentinel takes a built-in AWAY; ` +
+                                `the reason is what stops a later reader deleting it by accident.`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    for (const key of ["core", "adapters"]) {
+        if (raw[key] !== undefined)
+            checkDecision(key, raw[key], reds);
+    }
+    for (const group of ["providers", "packages"]) {
+        const value = raw[group];
+        if (value === undefined)
+            continue;
+        if (!isRecord(value)) {
+            reds.push(`CONFIG · ${group} must be an object keyed by ${group === "providers" ? "provider id" : "npm package name"}.`);
+            continue;
+        }
+        for (const [id, decision] of Object.entries(value))
+            checkDecision(`${group}.${id}`, decision, reds);
+    }
+    if (raw.output !== undefined) {
+        if (!isRecord(raw.output))
+            reds.push(`CONFIG · output must be an object.`);
+        else if (raw.output.agentDir !== undefined && typeof raw.output.agentDir !== "string") {
+            reds.push(`CONFIG · output.agentDir must be a string.`);
+        }
+    }
+    if (reds.length > 0)
+        return { reds };
+    return { config: raw, reds };
+}
+/** Every package this config declares, in report order. `false` decisions are included so the plan
+ *  can say "declared and switched off" rather than "never mentioned" — the two are different facts. */
+export function declaredPackages(config) {
+    const out = [];
+    if (config.core !== undefined)
+        out.push({ declaredAs: "core", name: "@open-everywhere/core", decision: config.core });
+    if (config.adapters !== undefined) {
+        out.push({ declaredAs: "adapters", name: "@open-everywhere/adapters", decision: config.adapters });
+    }
+    for (const [id, decision] of Object.entries(config.providers ?? {})) {
+        out.push({ declaredAs: `providers.${id}`, name: `@open-everywhere/provider-${id}`, providerId: id, decision });
+    }
+    for (const [name, decision] of Object.entries(config.packages ?? {})) {
+        out.push({ declaredAs: `packages["${name}"]`, name, decision });
+    }
+    return out;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Manifest validation — a manifest is untrusted DATA from an installed package
+// ─────────────────────────────────────────────────────────────────────────────
+export function parseContributionManifest(raw, pkg) {
+    const reds = [];
+    const where = `MANIFEST · ${pkg}/agent/contributions.ts`;
+    if (!isRecord(raw))
+        return { reds: [`${where} must export CONTRIBUTIONS as an object.`] };
+    if (raw.schemaVersion !== 1)
+        reds.push(`${where} has schemaVersion ${String(raw.schemaVersion)}; this build understands 1.`);
+    if (typeof raw.package !== "string" || raw.package.length === 0)
+        reds.push(`${where} must declare its own npm \`package\` name.`);
+    if (raw.register !== undefined && (typeof raw.register !== "string" || !raw.register.includes("#"))) {
+        reds.push(`${where} \`register\` must be "<module>#<exportName>", e.g. "agent/register.js#registerSlackProvider".`);
+    }
+    if (!Array.isArray(raw.contributions)) {
+        reds.push(`${where} must declare a \`contributions\` array.`);
+        return { reds };
+    }
+    const seen = new Set();
+    for (const [index, entry] of raw.contributions.entries()) {
+        const at = `${where} contributions[${index}]`;
+        if (!isRecord(entry)) {
+            reds.push(`${at} must be an object.`);
+            continue;
+        }
+        if (typeof entry.kind !== "string" || !CONTRIBUTION_KINDS.includes(entry.kind)) {
+            reds.push(`${at} has kind "${String(entry.kind)}"; expected one of ${CONTRIBUTION_KINDS.join(", ")}.`);
+            continue;
+        }
+        if (typeof entry.name !== "string" || entry.name.length === 0) {
+            reds.push(`${at} must have a non-empty \`name\` (it is BOTH the filename and the mounted name).`);
+            continue;
+        }
+        if (typeof entry.module !== "string" || !entry.module.endsWith(".js")) {
+            reds.push(`${at} (${entry.name}) must have a \`module\` sub-path ending in ".js" (ESM), e.g. "agent/tools/${entry.name}.js".`);
+            continue;
+        }
+        for (const optional of ["summary", "since"]) {
+            if (entry[optional] !== undefined && typeof entry[optional] !== "string") {
+                reds.push(`${at} (${entry.name}) \`${optional}\` must be a string.`);
+            }
+        }
+        const key = contributionKey(entry.kind, entry.name);
+        if (seen.has(key))
+            reds.push(`${at} duplicates "${key}" — a package may contribute a (kind, name) pair once.`);
+        seen.add(key);
+    }
+    if (reds.length > 0)
+        return { reds };
+    return { manifest: raw, reds };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Render templates
+// ─────────────────────────────────────────────────────────────────────────────
+const HEADER = "// GENERATED by `oe build` from roster.config.ts — DO NOT EDIT.";
+const WRAP = 100;
+/** A mounted contribution: the two-line header plus the re-export the app tree has always carried. */
+export function renderMountedShim(specifier, note) {
+    const lines = [HEADER];
+    if (note !== undefined && note.trim().length > 0) {
+        for (const line of wrapComment(note, WRAP - 3))
+            lines.push(line.length === 0 ? "//" : `// ${line}`);
+    }
+    lines.push(`export { default } from "${specifier}";`);
+    return `${lines.join("\n")}\n`;
+}
+/** A framework sentinel: how the roster records a REFUSAL of an eve BUILT-IN. */
+export function renderFrameworkSentinel(name, reason) {
+    const lines = [HEADER, `// ${name} — DECLINED as a static tool:`];
+    for (const line of wrapComment(reason, WRAP - 3))
+        lines.push(line.length === 0 ? "//" : `// ${line}`);
+    lines.push("// A sentinel is how the roster records a REFUSAL — eve keeps a built-in unless a slot file takes", "// it away. To change this, edit `framework.disable` in roster.config.ts, then `oe build`.", 'import { disableTool } from "eve/tools";', "", "export default disableTool();");
+    return `${lines.join("\n")}\n`;
+}
+/** The provider selection table + boot wiring. STATIC imports only — see the emitted header. */
+function renderProvidersModule(providers) {
+    const lines = [
+        HEADER,
+        "//",
+        "// THE PROVIDER SELECTION MANIFEST — this deployment's declaration of which provider bundles it",
+        "// carries. It is DERIVED: every row is a `providers` entry in roster.config.ts whose decision is",
+        "// not `false`, and the four artefacts that used to have to move together (row, app-tree stubs,",
+        "// dependency, bundle dir) are now one edit — the stubs and this table are both build output.",
+        "//",
+        "// This is the app tree, so vendor names are allowed here — and ONLY here. Core never names a",
+        "// provider: `agent/lib/register-adapters.ts` hands these ids to `declareProviderSelection()` as",
+        "// opaque strings, and every platform-keyed registration seam in core then REFUSES a provider that",
+        "// is not on this list (packages/core/agent/access/provider-selection.ts).",
+        "//",
+        "// 🔴 STATIC imports on purpose: eve bundles the agent definition and its whole import graph into",
+        "// one rolldown chunk, and a literal dynamic `import()` code-splits into a second chunk and trips",
+        "// eve's \"expected one authored module\" invariant.",
+        "",
+    ];
+    for (const p of providers)
+        lines.push(`import { ${p.exportName} } from "${p.pkg}/${p.module}";`);
+    lines.push("", "/** One selected provider bundle: its id (the `@open-everywhere/provider-<id>` suffix, and the", " *  `platform` string every core registry keys on) and the ONE boot call that registers it. */", "export interface SelectedProvider {", "  readonly id: string;", "  /** The bundle's single registration entry — see docs/extending/provider-bundles.md § anatomy. */", "  readonly register: () => void;", "}", "", "/** THE table. Order is irrelevant — each row is an independent registry write. */", "export const SELECTED_PROVIDERS: readonly SelectedProvider[] = [");
+    for (const p of providers) {
+        if (p.about !== undefined && p.about.trim().length > 0) {
+            for (const line of wrapComment(p.about, WRAP - 5))
+                lines.push(line.length === 0 ? "  //" : `  // ${line}`);
+        }
+        lines.push(`  { id: ${JSON.stringify(p.id)}, register: ${p.exportName} },`);
+    }
+    lines.push("];", "", "/** The selected ids, for `declareProviderSelection()`. */", "export const SELECTED_PROVIDER_IDS: readonly string[] = SELECTED_PROVIDERS.map((p) => p.id);");
+    return `${lines.join("\n")}\n`;
+}
+function decisionConfig(decision) {
+    return typeof decision === "boolean" ? {} : decision;
+}
+/** Resolve a config key (`"remember"` or `"tool/remember"`) against one package's manifest. */
+function lookupKey(index, key) {
+    if (key.includes("/")) {
+        const hit = index.byQualified.get(key);
+        return hit === undefined
+            ? { red: `names "${key}", which ${index.manifest.package} does not contribute.` }
+            : { hit };
+    }
+    const candidates = index.byBare.get(key) ?? [];
+    if (candidates.length === 0)
+        return { red: `names "${key}", which ${index.manifest.package} does not contribute.` };
+    if (candidates.length > 1) {
+        return {
+            red: `names "${key}", which ${index.manifest.package} contributes in ${candidates.length} kinds ` +
+                `(${candidates.map((c) => c.kind).sort().join(", ")}). Qualify it as "<kind>/${key}".`,
+        };
+    }
+    return { hit: candidates[0] };
+}
+export function planRoster(input) {
+    const reds = [];
+    const { config, agentDir } = input;
+    // ── Resolve packages (rule 6) and validate their manifests ────────────────
+    const indexes = [];
+    for (const pkg of input.packages) {
+        if (pkg.decision === false)
+            continue; // declared and switched off — nothing to resolve
+        if (pkg.error !== undefined || pkg.manifest === undefined) {
+            reds.push(`PACKAGE · roster.config.ts declares \`${pkg.declaredAs}\` but ${pkg.name} could not be resolved ` +
+                `(${pkg.error ?? "no contributions manifest"}). Fix: \`npm i ${pkg.name}\`, or set \`${pkg.declaredAs}: false\`.`);
+            continue;
+        }
+        if (pkg.resolvedName !== undefined && pkg.resolvedName !== pkg.name) {
+            reds.push(`PACKAGE · \`${pkg.declaredAs}\` resolved to package.json name "${pkg.resolvedName}", not "${pkg.name}".`);
+            continue;
+        }
+        // A missing version must red, not silently default — a silent "0.0.0" in the lock is
+        // indistinguishable from a real version and survives every `--check` (OPE-432: the committed
+        // lock carried "0.0.0" for all eight packages with nobody noticing until a manual diff).
+        if (pkg.version === undefined) {
+            reds.push(`PACKAGE · \`${pkg.declaredAs}\` (${pkg.name}) resolved with no \`version\` field in its package.json — the lock cannot record one.`);
+            continue;
+        }
+        const parsed = parseContributionManifest(pkg.manifest, pkg.name);
+        if (parsed.manifest === undefined) {
+            reds.push(...parsed.reds);
+            continue;
+        }
+        if (parsed.manifest.package !== pkg.name) {
+            reds.push(`MANIFEST · ${pkg.name}/agent/contributions.ts declares package "${parsed.manifest.package}" but was ` +
+                `resolved through "${pkg.name}". A manifest that misnames its own package cannot be attributed.`);
+            continue;
+        }
+        const byQualified = new Map();
+        const byBare = new Map();
+        for (const c of parsed.manifest.contributions) {
+            byQualified.set(contributionKey(c.kind, c.name), c);
+            byBare.set(c.name, [...(byBare.get(c.name) ?? []), c]);
+        }
+        indexes.push({ pkg, manifest: parsed.manifest, byQualified, byBare });
+    }
+    // ── Resolve every decision (rules 4, 5, 8) ────────────────────────────────
+    const resolved = [];
+    for (const index of indexes) {
+        const cfg = decisionConfig(index.pkg.decision);
+        const excludeOf = new Map();
+        const noteOf = new Map();
+        for (const [field, sink] of [["exclude", excludeOf], ["note", noteOf]]) {
+            for (const [key, text] of Object.entries(cfg[field] ?? {})) {
+                const { hit, red } = lookupKey(index, key);
+                if (red !== undefined || hit === undefined) {
+                    // RULE 4/5 — a governance property today's tree cannot express at all: you cannot mistype
+                    // an absent file, but you can absolutely mistype a config key and silently mount the thing
+                    // you meant to decline.
+                    reds.push(`CONFIG · ${index.pkg.declaredAs}.${field} ${red}`);
+                    continue;
+                }
+                sink.set(contributionKey(hit.kind, hit.name), text);
+            }
+        }
+        for (const c of index.manifest.contributions) {
+            const key = contributionKey(c.kind, c.name);
+            if (!SLUG_PATTERN[c.kind].test(c.name)) {
+                reds.push(`GRAMMAR · ${index.pkg.name} contributes ${c.kind} "${c.name}", which eve's ${c.kind} slug pattern ` +
+                    `rejects — it would be discovered as an invalid slot, not mounted.`);
+                continue;
+            }
+            const reason = excludeOf.get(key);
+            resolved.push({
+                package: index.pkg.name,
+                kind: c.kind,
+                name: c.name,
+                module: c.module,
+                summary: c.summary,
+                decision: reason === undefined ? "mounted" : "excluded",
+                reason,
+                note: noteOf.get(key),
+            });
+        }
+    }
+    // ── Name collisions (rule 9) ──────────────────────────────────────────────
+    const mounted = resolved.filter((r) => r.decision === "mounted");
+    const byMountKey = new Map();
+    for (const r of mounted)
+        byMountKey.set(contributionKey(r.kind, r.name), [...(byMountKey.get(contributionKey(r.kind, r.name)) ?? []), r]);
+    for (const [key, rows] of [...byMountKey].sort((a, b) => a[0].localeCompare(b[0]))) {
+        if (rows.length < 2)
+            continue;
+        reds.push(`COLLISION · ${rows.length} packages mount "${key}" (${rows.map((r) => r.package).join(", ")}). eve names a ` +
+            `slot after its FILE, so only one can win. Fix: exclude it from all but one, with a reason.`);
+    }
+    // ── Framework disables (rule 7) ───────────────────────────────────────────
+    const frameworkDisabled = {};
+    for (const [name, reason] of Object.entries(config.framework?.disable ?? {})) {
+        if (input.frameworkToolNames !== undefined && !input.frameworkToolNames.includes(name)) {
+            reds.push(`FRAMEWORK · framework.disable["${name}"] is not an eve framework tool ` +
+                `(eve offers: ${[...input.frameworkToolNames].sort().join(", ")}). A sentinel for a non-built-in ` +
+                `mounts nothing and hides nothing; eve's graph resolver rejects it too.`);
+            continue;
+        }
+        if (!SLUG_PATTERN.tool.test(name)) {
+            reds.push(`GRAMMAR · framework.disable["${name}"] is not a legal eve tool slug.`);
+            continue;
+        }
+        frameworkDisabled[name] = reason;
+    }
+    for (const r of mounted) {
+        if (r.kind === "tool" && frameworkDisabled[r.name] !== undefined) {
+            reds.push(`COLLISION · "${r.name}" is both mounted from ${r.package} and listed in framework.disable. ` +
+                `One file, two intents — pick one.`);
+        }
+    }
+    // ── The lock this config WOULD write ──────────────────────────────────────
+    const lockPackages = {};
+    for (const index of indexes) {
+        const contributions = {};
+        for (const r of resolved.filter((x) => x.package === index.pkg.name)) {
+            contributions[contributionKey(r.kind, r.name)] = r.decision;
+        }
+        // `index.pkg.version` is defined here by construction — the resolution loop above reds and
+        // `continue`s before pushing to `indexes` when a version is missing, so this is never the
+        // silent "0.0.0" placeholder OPE-432 found in the committed lock.
+        lockPackages[index.pkg.name] = { version: index.pkg.version ?? "0.0.0", contributions: sortedRecord(contributions) };
+    }
+    const wouldLock = {
+        schemaVersion: 1,
+        generator: ROSTER_GENERATOR_VERSION,
+        framework: sortedRecord(Object.fromEntries(Object.keys(frameworkDisabled).map((n) => [n, "disabled"]))),
+        packages: sortedRecord(lockPackages),
+    };
+    // ── Reconcile against the committed lock (rules 10–11) ────────────────────
+    const unreviewed = [];
+    const vanished = [];
+    const parsedLock = isRecord(input.lock) && isRecord(input.lock.packages) ? input.lock : undefined;
+    if (input.lock !== undefined && parsedLock === undefined) {
+        reds.push(`LOCK · roster.lock.json is present but is not a lock object. Fix: \`oe build --accept\`.`);
+    }
+    // An ABSENT lock reviews nothing — it is the empty ledger, not a pass. Only `--accept` skips.
+    const lock = input.acceptLock === true ? undefined : (parsedLock ?? { schemaVersion: 1, generator: ROSTER_GENERATOR_VERSION, framework: {}, packages: {} });
+    if (lock !== undefined) {
+        for (const index of indexes) {
+            const locked = lock.packages[index.pkg.name];
+            if (locked === undefined || !isRecord(locked.contributions)) {
+                for (const r of resolved.filter((x) => x.package === index.pkg.name)) {
+                    unreviewed.push({ package: r.package, kind: r.kind, name: r.name, module: r.module, summary: r.summary });
+                }
+                continue;
+            }
+            for (const r of resolved.filter((x) => x.package === index.pkg.name)) {
+                const key = contributionKey(r.kind, r.name);
+                const was = locked.contributions[key];
+                if (was === undefined) {
+                    const c = index.byQualified.get(key);
+                    unreviewed.push({ package: r.package, kind: r.kind, name: r.name, module: r.module, summary: r.summary, since: c?.since });
+                    continue;
+                }
+                if (was !== r.decision) {
+                    reds.push(`LOCK · ${index.pkg.name} "${key}" is ${was} in roster.lock.json but ${r.decision} per roster.config.ts. ` +
+                        `The lock is the REVIEWED state — fix: \`oe build --accept\` and commit the lock diff.`);
+                }
+            }
+            for (const key of Object.keys(locked.contributions)) {
+                if (index.byQualified.has(key))
+                    continue;
+                vanished.push({ package: index.pkg.name, kind: key.split("/")[0], name: key.slice(key.indexOf("/") + 1), lockedDecision: locked.contributions[key] });
+            }
+        }
+        const lockedFramework = isRecord(lock.framework) ? lock.framework : {};
+        for (const name of Object.keys(frameworkDisabled)) {
+            if (lockedFramework[name] === undefined) {
+                reds.push(`LOCK · framework.disable["${name}"] is not in roster.lock.json. Fix: \`oe build --accept\`.`);
+            }
+        }
+        for (const name of Object.keys(lockedFramework)) {
+            if (frameworkDisabled[name] === undefined) {
+                reds.push(`LOCK · roster.lock.json disables eve built-in "${name}" but roster.config.ts no longer does — ` +
+                    `that is a capability GAIN. Fix: \`oe build --accept\` and read the diff.`);
+            }
+        }
+    }
+    if (unreviewed.length > 0) {
+        for (const u of unreviewed) {
+            reds.push(`UNREVIEWED · ${u.package} contributes ${u.kind} "${u.name}"${u.summary === undefined ? "" : ` — ${u.summary}`} ` +
+                `which roster.lock.json has never seen. Decide it in roster.config.ts (mount by doing nothing, or add an ` +
+                `\`exclude\` with a reason), then \`oe build --accept\`.`);
+        }
+    }
+    for (const v of vanished) {
+        reds.push(`VANISHED · roster.lock.json reviewed ${v.package} ${v.kind} "${v.name}" (${v.lockedDecision}) but the package ` +
+            `no longer offers it — a rename or a removal. Both are capability changes; \`oe build --accept\` records it.`);
+    }
+    // ── The provider selection table ──────────────────────────────────────────
+    const providerRows = [];
+    for (const index of indexes) {
+        if (index.pkg.providerId === undefined)
+            continue;
+        const register = index.manifest.register;
+        if (register === undefined) {
+            reds.push(`PROVIDER · ${index.pkg.name} is selected as a provider bundle but its manifest declares no \`register\` ` +
+                `entry, so nothing would wire it at boot.`);
+            continue;
+        }
+        const [module, exportName] = register.split("#");
+        providerRows.push({
+            id: index.pkg.providerId,
+            pkg: index.pkg.name,
+            module: module,
+            exportName: exportName,
+            about: decisionConfig(index.pkg.decision).about,
+        });
+    }
+    // ── Nothing is planned when the inputs don't parse ────────────────────────
+    const structural = reds.filter((r) => !r.startsWith("UNREVIEWED ·") && !r.startsWith("VANISHED ·"));
+    const verdict = structural.length > 0 ? "invalid" : unreviewed.length > 0 ? "unreviewed" : vanished.length > 0 ? "vanished" : "clean";
+    const files = [];
+    if (verdict !== "invalid") {
+        for (const r of mounted) {
+            files.push({
+                path: `${agentDir}/${SLOT_DIR[r.kind]}/${r.name}.ts`,
+                content: renderMountedShim(`${r.package}/${r.module}`, r.note),
+            });
+        }
+        for (const [name, reason] of Object.entries(frameworkDisabled)) {
+            files.push({ path: `${agentDir}/${SLOT_DIR.tool}/${name}.ts`, content: renderFrameworkSentinel(name, reason) });
+        }
+        files.push({ path: `${agentDir}/lib/providers.generated.ts`, content: renderProvidersModule(providerRows) });
+        files.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    return {
+        verdict,
+        reds,
+        files,
+        lock: wouldLock,
+        resolved: [...resolved].sort((a, b) => contributionKey(a.kind, a.name).localeCompare(contributionKey(b.kind, b.name))),
+        unreviewed,
+        vanished,
+        frameworkDisabled: sortedRecord(frameworkDisabled),
+        selectedProviders: providerRows.map((p) => p.id),
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Projections
+// ─────────────────────────────────────────────────────────────────────────────
+/** The slot directories the build OWNS wholesale — anything in one that is not planned is deleted. */
+export function ownedSlotDirs(agentDir) {
+    return CONTRIBUTION_KINDS.map((k) => `${agentDir}/${SLOT_DIR[k]}`).sort((a, b) => a.localeCompare(b));
+}
+/** Two-space JSON, keys already sorted by the planner, trailing newline — `package-lock.json`'s shape. */
+export function serializeLock(lock) {
+    return `${JSON.stringify(lock, null, 2)}\n`;
+}
+/**
+ * The GOLDEN PLAN line for one planned path: `<path>\t<classification>`.
+ *
+ * This is what restores "the roster's git diff is the review surface" for a tree that is no longer
+ * committed. `scripts/goldens/roster-plan.txt` holds it, `lint:roster` checks it, and it is the
+ * artefact a reviewer reads when the lock changes.
+ */
+export function goldenPlanLines(plan, agentDir) {
+    const lines = [];
+    for (const r of plan.resolved) {
+        if (r.decision !== "mounted") {
+            lines.push(`(excluded)\t${r.kind}/${r.name}\texcluded ${r.package}: ${r.reason ?? ""}`.trimEnd());
+            continue;
+        }
+        lines.push(`${agentDir}/${SLOT_DIR[r.kind]}/${r.name}.ts\tmounted ${r.package}`);
+    }
+    for (const name of Object.keys(plan.frameworkDisabled)) {
+        lines.push(`${agentDir}/${SLOT_DIR.tool}/${name}.ts\tframework-disabled`);
+    }
+    lines.push(`${agentDir}/lib/providers.generated.ts\tproviders ${plan.selectedProviders.join(",")}`);
+    return lines.sort((a, b) => a.localeCompare(b));
+}
+/**
+ * The `mounted` snapshot rows, in the EXACT key/value grammar `scripts/config-snapshot-build.ts`
+ * used to read off disk — so `classifyRosterTransition` and `rosterToolNameOf` keep working
+ * unmodified and the capability gain/loss direction survives the move to a generated tree.
+ *
+ * 🔴 WHY THIS EXISTS AT ALL: `config-diff` builds the BASE snapshot inside a git worktree of the
+ * base ref. With the slot tree gitignored, that worktree has no `agent/tools/` at all, so a
+ * disk-reading projection would emit `<directory absent>` for every slot and report a catastrophic
+ * fake delta. Projecting from the resolved roster is the fix.
+ */
+export function mountedRosterRows(plan) {
+    return rosterRows(plan.resolved.filter((r) => r.decision === "mounted").map((r) => ({ dir: SLOT_DIR[r.kind], name: r.name })), Object.keys(plan.frameworkDisabled));
+}
+/**
+ * The same rows, projected from the COMMITTED LOCK instead of from a resolved plan.
+ *
+ * This is what `scripts/config-snapshot-build.ts` uses, and the choice is deliberate: the lock is a
+ * committed JSON file, so it reads SYNCHRONOUSLY and — decisively — it is present in a bare git
+ * worktree of the base ref, where neither `node_modules` nor the generated tree exists. Snapshotting
+ * the REVIEWED state is also the more honest reading: an exclusion only reaches the lock once a human
+ * has run `oe build --accept` and committed the diff, which is exactly the event a config diff should
+ * be reporting.
+ */
+export function mountedRowsFromLock(lock) {
+    if (!isRecord(lock) || !isRecord(lock.packages))
+        return [{ key: "roster.lock.json", value: "<lock absent or unreadable>" }];
+    const mounted = [];
+    for (const pkg of Object.values(lock.packages)) {
+        if (!isRecord(pkg) || !isRecord(pkg.contributions))
+            continue;
+        for (const [key, decision] of Object.entries(pkg.contributions)) {
+            if (decision !== "mounted")
+                continue;
+            const kind = key.slice(0, key.indexOf("/"));
+            const dir = SLOT_DIR[kind];
+            if (dir === undefined)
+                continue;
+            mounted.push({ dir, name: key.slice(key.indexOf("/") + 1) });
+        }
+    }
+    return rosterRows(mounted, isRecord(lock.framework) ? Object.keys(lock.framework) : []);
+}
+function rosterRows(mounted, frameworkDisabled) {
+    const rows = [];
+    const perDir = new Map();
+    const add = (key, value) => rows.push({ key, value });
+    const planned = [];
+    for (const r of mounted)
+        planned.push({ dir: r.dir, file: `${r.name}.ts`, value: PRIMITIVE_MOUNTED });
+    for (const name of frameworkDisabled)
+        planned.push({ dir: SLOT_DIR.tool, file: `${name}.ts`, value: PRIMITIVE_DISABLED });
+    for (const p of planned)
+        perDir.set(p.dir, (perDir.get(p.dir) ?? 0) + 1);
+    for (const dir of [...new Set(planned.map((p) => p.dir))].sort((a, b) => a.localeCompare(b))) {
+        add(`${dir}/`, `${perDir.get(dir)} entr(y|ies)`);
+    }
+    for (const p of planned.sort((a, b) => `${a.dir}/${a.file}`.localeCompare(`${b.dir}/${b.file}`))) {
+        add(`${p.dir}/${p.file}`, p.value);
+    }
+    return rows;
+}
+//# sourceMappingURL=roster-plan.js.map