modwright 0.1.0

package/dist/core/scaffold/engine.js

@@ -0,0 +1,680 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { pathExists } from "../fsutil.js";
+import { executePlan, planFile, planMkdir } from "../safety/index.js";
+import { buildContext } from "../validate/context.js";
+import { runValidators } from "../validate/run.js";
+import { parseProject } from "../project/schema.js";
+import { loadProject } from "../project/load.js";
+import { expandBareString } from "../project/build-steps.js";
+import { applyClaimTransition } from "../ledger/record.js";
+import { loadClaims, saveClaims } from "../ledger/store.js";
+import { loadTestPlanFile, saveTestPlan } from "../testplan/load.js";
+import { testPlanRowSchema } from "../testplan/types.js";
+import { lookupProbe } from "../testplan/registry.js";
+import { getConverter } from "../text/converters/index.js";
+import { templateContentFilename } from "../text/templates/cache.js";
+import { authoringManifestSchema, templateRecordSchema, TEMPLATE_MANIFEST_FILE, AUTHORING_MANIFEST_SCHEMA_VERSION } from "../text/templates/types.js";
+import { checkCollision } from "./collisions.js";
+import { renderEmits } from "./emit.js";
+import { collisionSlot, renderId } from "./ids.js";
+import { emptyScope, interpolate, interpolateDeep, listInputItems, reindentBlock } from "./render.js";
+import { DERIVED_ID_FORMS, NUMERIC_ID_FORMS } from "./types.js";
+import { bridgeGameSchema } from "../bridge/types.js";
+function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+function slugify(raw) {
+    return raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function computeVersion64(version) {
+    if (!version)
+        return undefined;
+    const parts = version.split(".").map((p) => Number(p));
+    if (parts.length < 3 || parts.slice(0, 3).some((p) => !Number.isInteger(p) || p < 0))
+        return undefined;
+    const [major, minor, revision] = parts;
+    const value = (BigInt(major) << 55n) | (BigInt(minor) << 47n) | (BigInt(revision) << 31n) | 1n;
+    return value.toString();
+}
+function projectScope(project) {
+    const out = { name: project.project.name, game: project.project.game };
+    const moduleName = project.project.name.replace(/[^A-Za-z0-9_]/g, "");
+    out.moduleName = /^[A-Za-z_]/.test(moduleName) ? moduleName : `Mod${moduleName}`;
+    if (project.project.version)
+        out.version = project.project.version;
+    const version64 = computeVersion64(project.project.version);
+    if (version64)
+        out.version64 = version64;
+    for (const [k, v] of Object.entries(project.project.identity ?? {}))
+        out[`identity.${k}`] = v;
+    return out;
+}
+function resolveInputValue(spec, given, optional) {
+    const raw = given[spec.name];
+    if (raw !== undefined)
+        return raw;
+    if (spec.type === "string" && spec.default !== undefined)
+        return spec.default;
+    if (spec.type === "number" && spec.default !== undefined)
+        return String(spec.default);
+    if (spec.type === "list" && spec.default !== undefined)
+        return spec.default;
+    if (optional)
+        return undefined;
+    throw new Error(`scaffold: missing required input "${spec.name}" (${spec.prompt})`);
+}
+function getPath(obj, dotted) {
+    return dotted.split(".").reduce((acc, seg) => {
+        if (Array.isArray(acc)) {
+            const idx = Number(seg);
+            if (Number.isInteger(idx))
+                return acc[idx];
+            return acc.find((el) => el && typeof el === "object" && el.name === seg);
+        }
+        if (acc && typeof acc === "object")
+            return acc[seg];
+        return undefined;
+    }, obj);
+}
+function sameBuildStepAddition(existing, addition) {
+    if (existing && typeof existing === "object") {
+        const o = existing;
+        if (typeof o.step === "string" &&
+            typeof o.glob === "string" &&
+            typeof addition.step === "string" &&
+            typeof addition.glob === "string" &&
+            o.step === addition.step &&
+            o.glob === addition.glob) {
+            return true;
+        }
+    }
+    return canonicalJson(existing) === canonicalJson(addition);
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        const o = value;
+        return `{${Object.keys(o)
+            .sort()
+            .filter((k) => o[k] !== undefined)
+            .map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function stepMatchesBeforeTarget(entry, target, project) {
+    if (typeof entry === "string") {
+        if (entry === target)
+            return true;
+        try {
+            return expandBareString(entry, project).some((s) => s.step === target);
+        }
+        catch {
+            return false;
+        }
+    }
+    if (entry && typeof entry === "object") {
+        const o = entry;
+        return o.id === target || o.step === target;
+    }
+    return false;
+}
+function mergeBuildSteps(existing, additions, project) {
+    const result = [...existing];
+    const warnings = [];
+    for (const raw of additions) {
+        if (!raw || typeof raw !== "object") {
+            if (!result.some((entry) => JSON.stringify(entry) === JSON.stringify(raw)))
+                result.push(raw);
+            continue;
+        }
+        const { before, ...stepRest } = raw;
+        if (result.some((entry) => sameBuildStepAddition(entry, stepRest)))
+            continue;
+        if (typeof before === "string") {
+            const idx = result.findIndex((entry) => stepMatchesBeforeTarget(entry, before, project));
+            if (idx !== -1) {
+                result.splice(idx, 0, stepRest);
+                continue;
+            }
+            warnings.push(`build step "${String(stepRest.step ?? stepRest.id ?? "?")}" asked to be inserted before "${before}", but no ` +
+                `build.steps entry matches that step id or kind — it was appended to the end of build.steps instead. ` +
+                `If it must run before another step, move it by hand in ${"modwright.json"}.`);
+        }
+        result.push(stepRest);
+    }
+    return { steps: result, warnings };
+}
+export async function runScaffold(options) {
+    const { project, surface, definition, store, install, registry } = options;
+    const mode = options.mode ?? "dry-run";
+    const now = options.now ?? (() => new Date());
+    const by = options.by ?? "scaffold";
+    const skipped = [];
+    const lookup = async (kind, params) => {
+        if (!store)
+            return { kind, params, count: 0, rows: [], note: "no vanilla index open" };
+        return surface.index.query(store, kind, params);
+    };
+    const inputValues = {};
+    const oneOfMembers = new Set(definition.oneOf.flat());
+    for (const spec of definition.inputs) {
+        const resolved = resolveInputValue(spec, options.inputs, oneOfMembers.has(spec.name));
+        if (resolved === undefined)
+            continue;
+        inputValues[spec.name] = resolved;
+        if (spec.type === "enum" && !spec.values.includes(inputValues[spec.name])) {
+            throw new Error(`scaffold "${definition.id}": input "${spec.name}" must be one of ${spec.values.join(", ")}, got "${inputValues[spec.name]}".`);
+        }
+        if (spec.type === "string" && spec.pattern && !new RegExp(spec.pattern).test(inputValues[spec.name])) {
+            throw new Error(`scaffold "${definition.id}": input "${spec.name}" = "${inputValues[spec.name]}" does not match pattern ${spec.pattern}.`);
+        }
+        if (spec.type === "number") {
+            const n = Number(inputValues[spec.name]);
+            if (inputValues[spec.name].trim() === "" || !Number.isFinite(n)) {
+                throw new Error(`scaffold "${definition.id}": input "${spec.name}" must be a number, got "${inputValues[spec.name]}".`);
+            }
+            if ((spec.min !== undefined && n < spec.min) || (spec.max !== undefined && n > spec.max)) {
+                throw new Error(`scaffold "${definition.id}": input "${spec.name}" = ${n} is outside ${spec.min ?? "-inf"}..${spec.max ?? "inf"}.`);
+            }
+        }
+        if (spec.type === "path" && spec.mustExist) {
+            const abs = path.isAbsolute(inputValues[spec.name]) ? inputValues[spec.name] : path.join(project.root, inputValues[spec.name]);
+            if (!(await pathExists(abs))) {
+                throw new Error(`scaffold "${definition.id}": input "${spec.name}" names a path that does not exist: ${abs}.`);
+            }
+        }
+        if (spec.type === "list") {
+            const items = listInputItems(inputValues[spec.name]);
+            if (items.length < spec.minItems) {
+                throw new Error(`scaffold "${definition.id}": input "${spec.name}" needs at least ${spec.minItems} item(s) (one per line or semicolon-separated), got ${items.length}.`);
+            }
+            if (spec.itemPattern) {
+                const re = new RegExp(spec.itemPattern);
+                const bad = items.find((it) => !re.test(it));
+                if (bad !== undefined) {
+                    throw new Error(`scaffold "${definition.id}": input "${spec.name}" item "${bad}" does not match pattern ${spec.itemPattern}.`);
+                }
+            }
+        }
+        if (spec.type === "string" && spec.reindent !== undefined) {
+            inputValues[spec.name] = reindentBlock(inputValues[spec.name], spec.reindent);
+        }
+    }
+    for (const group of definition.oneOf) {
+        const present = group.filter((name) => inputValues[name] !== undefined);
+        if (present.length !== 1) {
+            throw new Error(`scaffold "${definition.id}": exactly one of {${group.join(", ")}} must be provided` +
+                (present.length === 0 ? `, but none was.` : `, not ${present.length} (${present.join(", ")}).`));
+        }
+    }
+    const numberInputs = new Set(definition.inputs.filter((i) => i.type === "number").map((i) => i.name));
+    const listInputs = new Set(definition.inputs.filter((i) => i.type === "list").map((i) => i.name));
+    const numberIds = new Set(definition.ids.filter((i) => NUMERIC_ID_FORMS.has(i.form)).map((i) => i.name));
+    const scope = { ...emptyScope(), input: inputValues, project: projectScope(project), numberInputs, listInputs, numberIds };
+    scope.project.today = now().toISOString().slice(0, 10);
+    for (const spec of definition.inputs) {
+        if (spec.type !== "index-ref")
+            continue;
+        if (inputValues[spec.name] === undefined)
+            continue;
+        if (!store) {
+            const exposed = spec.requires.flatMap((r) => [r.expose, r.through?.expose].filter((e) => e !== undefined));
+            if (exposed.length > 0) {
+                throw new Error(`scaffold "${definition.id}": input "${spec.name}" needs the ${surface.id} vanilla index — its lookup exposes ${exposed.map((e) => `\${template.${e}}`).join(", ")} to the emitted files, so there is nothing to write without it. Run build_index first.`);
+            }
+            skipped.push({
+                id: `${definition.id}:input:${spec.name}`,
+                reason: `no vanilla index built for ${surface.id} — cannot verify "${inputValues[spec.name]}" or its requires[]; the value is used as given (run build_index first to check it).`,
+            });
+            continue;
+        }
+        const params = {};
+        for (const [k, v] of Object.entries(spec.lookup.params))
+            params[k] = interpolate(v, scope);
+        const res = await lookup(spec.lookup.kind, params);
+        if (res.count === 0) {
+            throw new Error(`scaffold "${definition.id}": input "${spec.name}" ("${inputValues[spec.name]}") does not resolve via lookup "${spec.lookup.kind}".`);
+        }
+        for (const req of spec.requires) {
+            const value = getPath(res.rows[0], req.path);
+            if (req.expose && value !== undefined && value !== null && value !== "") {
+                scope.template[req.expose] = String(value);
+            }
+            if (req.through) {
+                if (value === undefined || value === null || value === "")
+                    continue;
+                const throughParams = {};
+                for (const [k, v] of Object.entries(req.through.params ?? {}))
+                    throughParams[k] = interpolate(v, scope);
+                const throughRes = await lookup(req.through.kind, { ...throughParams, [req.through.param]: String(value) });
+                if (throughRes.count === 0) {
+                    throw new Error(`scaffold "${definition.id}": ${req.reason}`);
+                }
+                const throughValue = getPath(throughRes.rows[0], req.through.path);
+                const throughMatches = req.matches !== undefined ? new RegExp(req.matches).test(String(throughValue ?? "")) : throughValue !== undefined;
+                if (!throughMatches) {
+                    throw new Error(`scaffold "${definition.id}": ${req.reason}`);
+                }
+                if (req.through.expose && throughValue !== undefined && throughValue !== null && throughValue !== "") {
+                    scope.template[req.through.expose] = String(throughValue);
+                }
+                continue;
+            }
+            const matches = req.matches !== undefined ? new RegExp(req.matches).test(String(value ?? "")) : value !== undefined;
+            if (!matches) {
+                throw new Error(`scaffold "${definition.id}": ${req.reason}`);
+            }
+        }
+    }
+    for (const spec of definition.inputs) {
+        if (spec.type !== "template-record")
+            continue;
+        if (inputValues[spec.name] === undefined)
+            continue;
+        const given = inputValues[spec.name];
+        const dir = path.isAbsolute(given) ? given : path.join(project.root, given);
+        const recordPath = path.join(dir, "record.json");
+        let raw;
+        try {
+            raw = JSON.parse(await fs.readFile(recordPath, "utf8"));
+        }
+        catch (err) {
+            throw new Error(`scaffold "${definition.id}": input "${spec.name}" names a template-record directory with no readable record.json: ${dir} (${err.message}).`);
+        }
+        const parsed = templateRecordSchema.safeParse(raw);
+        if (!parsed.success) {
+            throw new Error(`scaffold "${definition.id}": input "${spec.name}"'s record.json at ${recordPath} is not a valid TemplateRecord: ${parsed.error.message}.`);
+        }
+        const record = parsed.data;
+        const contentExt = record.conversion ? getConverter(record.conversion).to : path.extname(record.sourcePath);
+        const contentPath = path.join(dir, templateContentFilename(record.sourcePath, contentExt));
+        if (!(await pathExists(contentPath))) {
+            throw new Error(`scaffold "${definition.id}": input "${spec.name}"'s cached content is missing: ${contentPath}.`);
+        }
+        scope.template[`${spec.name}.ref`] = record.ref;
+        scope.template[`${spec.name}.kind`] = record.kind;
+        scope.template[`${spec.name}.provenance`] = record.provenance;
+        scope.template[`${spec.name}.permission`] = record.permission;
+        scope.template[`${spec.name}.sha256`] = record.sha256;
+        scope.template[`${spec.name}.sourcePath`] = record.sourcePath;
+        scope.template[`${spec.name}.contentPath`] = contentPath;
+        if (spec.expectKind) {
+            const by = scope.template[spec.expectKind.by];
+            if (by === undefined || by === "") {
+                skipped.push({
+                    id: `${definition.id}:input:${spec.name}:expectKind`,
+                    reason: `\${template.${spec.expectKind.by}} is unset (nothing exposed it — the base record declares no such value), so the template's kind "${record.kind}" was not checked against the base.`,
+                });
+            }
+            else {
+                const pattern = Object.hasOwn(spec.expectKind.map, by) ? spec.expectKind.map[by] : undefined;
+                if (pattern === undefined) {
+                    skipped.push({
+                        id: `${definition.id}:input:${spec.name}:expectKind`,
+                        reason: `no expected template kind is recorded for base type "${by}", so the template's kind "${record.kind}" was not checked.`,
+                    });
+                }
+                else if (!new RegExp(pattern).test(record.kind)) {
+                    throw new Error(`scaffold "${definition.id}": input "${spec.name}"'s record is labelled kind "${record.kind}" (${record.sourcePath}), but \${template.${spec.expectKind.by}} is "${by}", which needs a template whose kind matches /${pattern}/. ${spec.expectKind.reason}`);
+                }
+            }
+        }
+    }
+    const generatedIds = [];
+    const projectIdentity = project.project.identity?.uuid ?? project.project.name;
+    for (const idSpec of definition.ids) {
+        const { report: idReport, unresolvedSkips } = await allocateOneId(idSpec, scope, {
+            projectIdentity,
+            scaffoldId: definition.id,
+            project,
+            surface,
+            store,
+            install,
+            lookup,
+            force: Boolean(options.force),
+        });
+        generatedIds.push(idReport);
+        scope.ids[idSpec.name] = idReport.value;
+        for (const s of unresolvedSkips) {
+            skipped.push({ id: `${definition.id}:id:${idSpec.name}:${s.check}`, reason: s.reason });
+        }
+    }
+    const rendered = await renderEmits(definition, scope, project.root);
+    for (const g of rendered.guardSkipped) {
+        skipped.push({
+            id: `${definition.id}:emit:${g.op}${g.path ? `:${path.relative(project.root, g.path).split(path.sep).join("/")}` : ""}`,
+            reason: `not written — ${g.reason}`,
+        });
+    }
+    const rowProbes = definition.testRows.map((row) => buildTestRowProbes(definition, row, scope));
+    const operations = [
+        ...[...rendered.mkdirs].map((abs) => planMkdir(abs)),
+        ...[...rendered.content.entries()]
+            .filter(([abs]) => !rendered.mkdirs.has(abs))
+            .map(([abs, text]) => planFile(abs, text)),
+    ];
+    const patch = rendered.projectPatch;
+    const hasPatch = patch.sources.length + patch.steps.length + patch.deployTargets.length + patch.dependencies.length + Object.keys(patch.toolchain).length > 0;
+    if (hasPatch) {
+        const projectFilePath = project.file;
+        const pendingProjectText = rendered.content.get(projectFilePath);
+        const baseJson = pendingProjectText
+            ? JSON.parse(pendingProjectText)
+            : JSON.parse(await fs.readFile(projectFilePath, "utf8"));
+        if (patch.sources.length) {
+            const existingSources = (baseJson.sources ?? []);
+            const merged = [...existingSources];
+            for (const raw of patch.sources) {
+                const dup = merged.some((s) => s.id === raw.id || (typeof raw.path === "string" && s.path === raw.path));
+                if (!dup)
+                    merged.push(raw);
+            }
+            baseJson.sources = merged;
+        }
+        if (patch.steps.length) {
+            const build = (baseJson.build ?? {});
+            const merged = mergeBuildSteps((build.steps ?? []), patch.steps, project.project);
+            build.steps = merged.steps;
+            for (const [n, reason] of merged.warnings.entries()) {
+                skipped.push({ id: `${definition.id}:patch-project:steps[${n}]`, reason });
+            }
+            if (build.outDir === undefined && patch.outDir !== undefined)
+                build.outDir = patch.outDir;
+            baseJson.build = build;
+        }
+        if (patch.deployTargets.length) {
+            const deploy = (baseJson.deploy ?? { targets: [] });
+            const existingTargets = (deploy.targets ?? []);
+            const fromKey = (t) => typeof t.from === "string" && t.into === undefined ? (t.from.split(/[\\/]/).pop() ?? t.from) : String(t.from);
+            const sameTarget = (a, b) => a.rootId === b.rootId && fromKey(a) === fromKey(b) && (a.into ?? undefined) === (b.into ?? undefined) && (a.variant ?? undefined) === (b.variant ?? undefined);
+            const merged = [...existingTargets];
+            for (const raw of patch.deployTargets) {
+                if (!merged.some((t) => sameTarget(t, raw)))
+                    merged.push(raw);
+            }
+            deploy.targets = merged;
+            baseJson.deploy = deploy;
+        }
+        if (patch.dependencies.length)
+            baseJson.dependencies = [...(baseJson.dependencies ?? []), ...patch.dependencies];
+        if (Object.keys(patch.toolchain).length) {
+            const existing = (baseJson.toolchain ?? {});
+            baseJson.toolchain = { ...patch.toolchain, ...existing };
+        }
+        try {
+            parseProject(baseJson);
+        }
+        catch (err) {
+            throw new Error(`scaffold "${definition.id}": patch-project would leave ${path.basename(projectFilePath)} invalid: ${err.message}`);
+        }
+        const text = `${JSON.stringify(baseJson, null, 2)}\n`;
+        if (rendered.content.has(projectFilePath)) {
+            rendered.content.set(projectFilePath, text);
+            const existingOpIdx = operations.findIndex((op) => op.kind !== "mkdir" && "path" in op && op.path === projectFilePath);
+            if (existingOpIdx !== -1)
+                operations[existingOpIdx] = planFile(projectFilePath, text);
+            const renderedOp = rendered.ops.find((op) => op.absPath === projectFilePath && op.content !== undefined);
+            if (renderedOp) {
+                renderedOp.content = text;
+                renderedOp.sizeBytes = Buffer.byteLength(text, "utf8");
+            }
+        }
+        else {
+            rendered.content.set(projectFilePath, text);
+            operations.push(planFile(projectFilePath, text));
+        }
+    }
+    const write = await executePlan({ purpose: `scaffold ${definition.id} in ${project.project.name}`, operations, backupRoot: path.join(project.root, ".modwright", "backups") }, {
+        mode,
+        now,
+        confidence: {
+            level: "medium",
+            assumptions: ["Emitted content is built from this scaffold's own templates, not verified against a real toolchain."],
+        },
+    });
+    const files = rendered.ops.map((op) => {
+        const rel = toPosix(path.relative(project.root, op.absPath));
+        const manifestEntry = rendered.authoringManifestEntries.find((e) => e.path === rel);
+        return {
+            path: rel,
+            op: op.kind,
+            sizeBytes: op.sizeBytes,
+            sha256: op.content ? createHash("sha256").update(op.content).digest("hex") : undefined,
+            derivedFrom: manifestEntry?.derivedFrom,
+            rewrittenPaths: manifestEntry?.rewrittenPaths,
+            reason: op.reason,
+        };
+    });
+    const manual = definition.manual.map((m) => ({
+        title: interpolate(m.title, scope),
+        steps: m.steps.map((s) => interpolate(s, scope)),
+        expected: interpolate(m.expected, scope),
+    }));
+    const preconditions = manual.map((m) => m.title);
+    const primarySpec = definition.inputs.find((i) => i.type === "string" || i.type === "index-ref");
+    const primaryInputSlug = slugify(primarySpec ? inputValues[primarySpec.name] : project.project.name);
+    const claimId = `${slugify(project.project.name)}.${primaryInputSlug}.${interpolate(definition.claim.idSuffix, scope)}`;
+    const claimText = interpolate(definition.claim.claim, scope);
+    const entryNames = generatedIds.filter((g) => ["tweak-record", "slug", "map-key"].includes(g.form)).map((g) => g.value);
+    const testRows = definition.testRows.map((row, i) => {
+        const base = {
+            id: `${claimId}.${row.gate}.${i}`,
+            gate: row.gate,
+            title: interpolate(row.title, scope),
+            preconditions,
+            steps: [],
+            expected: interpolate(row.expected, scope),
+            claim: claimId,
+            status: "authored",
+        };
+        const probes = rowProbes[i];
+        if (probes)
+            return testPlanRowSchema.parse({ ...base, manual: false, probe: { allowMutate: false, probes } });
+        return testPlanRowSchema.parse({ ...base, manual: true });
+    });
+    const validatorIds = new Set([...definition.satisfies, ...registry.cheap(surface.id).map((v) => v.id)]);
+    const report = {
+        scaffold: definition.id,
+        game: surface.id,
+        mode,
+        project: project.project.name,
+        inputs: inputValues,
+        generatedIds,
+        files,
+        write,
+        satisfies: definition.satisfies,
+        testRows,
+        manual,
+        skipped,
+        confidence: write.confidence,
+        next: write.next,
+    };
+    if (mode === "dry-run")
+        return report;
+    if (write.applied) {
+        const reload = rendered.content.has(project.file) || project.sources.some((s) => !s.exists);
+        const validatedProject = reload ? await loadProject(project.file) : project;
+        const ctx = buildContext({ project: validatedProject, surface, install, store });
+        const fullReport = await runValidators(registry, ctx, {});
+        const ran = fullReport.ran.filter((id) => validatorIds.has(id));
+        const skippedFiltered = fullReport.skipped.filter((s) => validatorIds.has(s.id));
+        const findings = fullReport.findings.filter((f) => validatorIds.has(f.validatorId));
+        const unsuppressedBlocking = findings.filter((f) => f.severity === "block" && !f.suppressedBy);
+        const satisfiesSet = new Set(definition.satisfies);
+        const skippedSatisfies = skippedFiltered.filter((s) => satisfiesSet.has(s.id));
+        const cleanReasons = [
+            ...unsuppressedBlocking.map((f) => `${f.validatorId}: ${f.message}`),
+            ...skippedSatisfies.map((s) => `${s.id} (listed in satisfies) skipped: ${s.reason}`),
+        ];
+        report.validation = {
+            ran,
+            skipped: skippedFiltered,
+            findings,
+            clean: cleanReasons.length === 0,
+            cleanReasons,
+        };
+        const stamp = now().toISOString().replace(/[:.]/g, "-");
+        const manifest = {
+            schemaVersion: 1,
+            scaffold: definition.id,
+            inputs: inputValues,
+            generatedIds: generatedIds.map((g) => ({ name: g.name, slot: g.slot, form: g.form, value: g.value })),
+            files,
+            satisfies: definition.satisfies,
+            validation: { ran, skipped: skippedFiltered, findings },
+            claimId,
+            testRowIds: testRows.map((r) => r.id),
+            manual,
+        };
+        const manifestDir = path.join(project.root, ".modwright", "scaffolds");
+        const manifestPath = path.join(manifestDir, `${stamp}.json`);
+        await executePlan({
+            purpose: `scaffold ${definition.id} manifest`,
+            operations: [planMkdir(manifestDir), planFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)],
+            backupRoot: path.join(project.root, ".modwright", "backups"),
+        }, { mode: "apply", now, confidence: { level: "high", assumptions: [] } });
+        report.manifestPath = manifestPath;
+        if (rendered.authoringManifestEntries.length > 0) {
+            const templateManifestPath = path.join(project.root, ...TEMPLATE_MANIFEST_FILE.split("/"));
+            let existingEntries = [];
+            try {
+                const raw = JSON.parse(await fs.readFile(templateManifestPath, "utf8"));
+                const parsed = authoringManifestSchema.safeParse(raw);
+                if (parsed.success)
+                    existingEntries = parsed.data.entries;
+            }
+            catch {
+            }
+            const recorded = new Set(existingEntries.map((e) => `${e.path}\0${e.templateSha256}\0${e.authoredSha256}`));
+            const added = rendered.authoringManifestEntries.filter((e) => !recorded.has(`${e.path}\0${e.templateSha256}\0${e.authoredSha256}`));
+            const nextManifest = { schemaVersion: AUTHORING_MANIFEST_SCHEMA_VERSION, entries: [...existingEntries, ...added] };
+            if (added.length > 0)
+                await executePlan({
+                    purpose: `scaffold ${definition.id}: record template-derived files`,
+                    operations: [planMkdir(path.dirname(templateManifestPath)), planFile(templateManifestPath, `${JSON.stringify(nextManifest, null, 2)}\n`)],
+                    backupRoot: path.join(project.root, ".modwright", "backups"),
+                }, { mode: "apply", now, confidence: { level: "high", assumptions: [] } });
+        }
+        const { claims } = await loadClaims(project.root);
+        const result = applyClaimTransition({
+            claims,
+            id: claimId,
+            to: "authored",
+            tool: "ledger",
+            by,
+            now,
+            claimText,
+            scope: { files: files.map((f) => f.path), entries: entryNames },
+            note: manifestPath,
+        });
+        if (result.ok) {
+            await saveClaims(project.root, result.claims, { mode: "apply", now });
+        }
+        report.ledger = { claimId, claim: result.claim, written: result.ok, refusal: result.refusal };
+        const bridgeGame = bridgeGameSchema.safeParse(definition.game);
+        if (testRows.length > 0 && !bridgeGame.success) {
+            skipped.push({ id: `${definition.id}:test-plan`, reason: `tests/authored.yaml not written: ${definition.game} has no bridge, so no test plan can run its rows; they are listed in the report as manual steps.` });
+        }
+        else if (testRows.length > 0 && bridgeGame.success) {
+            const testPlanPath = path.join(project.root, "tests", "authored.yaml");
+            const existing = await loadTestPlanFile(testPlanPath);
+            const plan = existing.plan ?? {
+                planId: "authored",
+                title: "Authored rows (scaffold-proposed)",
+                game: bridgeGame.data,
+                fixture: project.project.testProfile
+                    ? { save: project.project.testProfile.saveName, notes: project.project.testProfile.notes }
+                    : undefined,
+                rows: [],
+            };
+            const fresh = new Map(testRows.map((r) => [r.id, r]));
+            const kept = plan.rows.map((r) => {
+                const next = fresh.get(r.id);
+                if (next)
+                    fresh.delete(r.id);
+                return next ?? r;
+            });
+            plan.rows = [...kept, ...fresh.values()];
+            await saveTestPlan(testPlanPath, plan, { mode: "apply", now, backupRoot: path.join(project.root, ".modwright", "backups") });
+            report.testPlanPath = testPlanPath;
+        }
+    }
+    return report;
+}
+function buildTestRowProbes(definition, row, scope) {
+    if (!row.probes || !row.probes.every((p) => lookupProbe(p.kind)?.status === "attested"))
+        return undefined;
+    return row.probes.map((p, j) => buildRowProbe(definition, row.gate, p, j, scope));
+}
+function buildRowProbe(definition, gate, spec, index, scope) {
+    const entry = lookupProbe(spec.kind);
+    if (!entry) {
+        throw new Error(`scaffold "${definition.id}": test row "${gate}" names unknown probe kind "${spec.kind}".`);
+    }
+    if (entry.game !== definition.game) {
+        throw new Error(`scaffold "${definition.id}" (${definition.game}): test row "${gate}" names probe kind "${spec.kind}", which the registry lists as a ${entry.game} probe — run_tests refuses a row whose probe is for another game (core/testplan/check.ts), so it would never run.`);
+    }
+    const params = interpolateDeep(spec.params, scope);
+    const parsedParams = entry.paramsSchema.safeParse(params);
+    if (!parsedParams.success) {
+        throw new Error(`scaffold "${definition.id}": test row "${gate}" probe "${spec.kind}" params do not match its registry schema (${entry.citation}): ${parsedParams.error.message}`);
+    }
+    const expect = spec.expect ? interpolateDeep(spec.expect, scope) : undefined;
+    return {
+        id: `${gate}.${index}`,
+        kind: spec.kind,
+        context: entry.context,
+        effect: entry.effect,
+        params: parsedParams.data,
+        ...(expect ? { expect } : {}),
+    };
+}
+async function allocateOneId(idSpec, scope, ctx) {
+    let slot = interpolate(idSpec.slot, scope);
+    if (DERIVED_ID_FORMS.has(idSpec.form)) {
+        const value = renderId(idSpec.form, ctx.projectIdentity, ctx.scaffoldId, slot, idSpec.fractionBits);
+        return { report: { name: idSpec.name, slot, form: idSpec.form, value, collisions: [] }, unresolvedSkips: [] };
+    }
+    let attempt = 0;
+    for (;;) {
+        const value = renderId(idSpec.form, ctx.projectIdentity, ctx.scaffoldId, slot);
+        const result = await checkCollision({
+            idSpec,
+            value,
+            project: ctx.project,
+            surface: ctx.surface,
+            store: ctx.store,
+            install: ctx.install,
+            lookup: ctx.lookup,
+        });
+        if (result.hits.length === 0 || ctx.force) {
+            return {
+                report: {
+                    name: idSpec.name,
+                    slot,
+                    form: idSpec.form,
+                    value,
+                    collisions: result.hits.map((h) => ({ check: h.check, source: h.source, detail: h.detail })),
+                },
+                unresolvedSkips: result.skipped,
+            };
+        }
+        if (idSpec.form === "tweak-record" || idSpec.form === "slug" || idSpec.form === "map-key") {
+            throw new Error(`scaffold: generated id "${idSpec.name}" = "${value}" already exists (${result.hits.map((h) => h.detail).join("; ")}). Choose a different name.`);
+        }
+        attempt++;
+        if (attempt > 20) {
+            throw new Error(`scaffold: could not allocate a collision-free id for "${idSpec.name}" after ${attempt} attempts.`);
+        }
+        slot = collisionSlot(interpolate(idSpec.slot, scope), attempt);
+    }
+}