modwright 0.1.0

package/dist/core/text/handles.js

@@ -0,0 +1,86 @@
+import { cloneJson, isJsonObject, walkJson } from "./json.js";
+const RENUMBERED_KEYS = ["HandleId", "BufferId"];
+export function renumberHandles(root) {
+    const maps = {
+        HandleId: new Map(),
+        BufferId: new Map(),
+    };
+    const danglingRefs = [];
+    walkJson(root, (node, jsonPath) => {
+        if (!isJsonObject(node))
+            return;
+        const ref = node.HandleRefId;
+        if (typeof ref === "string") {
+            const target = maps.HandleId.get(ref);
+            if (target)
+                target.paths.push(`${jsonPath}.HandleRefId`);
+            else
+                danglingRefs.push({ ref, path: `${jsonPath}.HandleRefId` });
+        }
+        for (const key of RENUMBERED_KEYS) {
+            const raw = node[key];
+            if (typeof raw !== "string")
+                continue;
+            const map = maps[key];
+            const existing = map.get(raw);
+            if (existing) {
+                existing.paths.push(`${jsonPath}.${key}`);
+            }
+            else {
+                map.set(raw, { to: String(map.size), paths: [`${jsonPath}.${key}`] });
+            }
+        }
+    });
+    const cloned = cloneJson(root);
+    const dangling = new Set(danglingRefs.map((d) => d.path));
+    walkJson(cloned, (node, jsonPath) => {
+        if (!isJsonObject(node))
+            return;
+        for (const key of RENUMBERED_KEYS) {
+            const raw = node[key];
+            if (typeof raw !== "string")
+                continue;
+            const mapped = maps[key].get(raw);
+            if (mapped)
+                node[key] = mapped.to;
+        }
+        const ref = node.HandleRefId;
+        if (typeof ref === "string" && !dangling.has(`${jsonPath}.HandleRefId`)) {
+            const mapped = maps.HandleId.get(ref);
+            if (mapped)
+                node.HandleRefId = mapped.to;
+        }
+    });
+    const renumbered = [];
+    for (const key of RENUMBERED_KEYS) {
+        for (const [from, { to, paths }] of maps[key]) {
+            if (from !== to)
+                renumbered.push({ key, from, to, paths });
+        }
+    }
+    return { root: cloned, renumbered, danglingRefs };
+}
+export function handlesAreInEncounterOrder(root) {
+    const seen = { HandleId: new Map(), BufferId: new Map() };
+    let ok = true;
+    walkJson(root, (node) => {
+        if (!ok || !isJsonObject(node))
+            return;
+        for (const key of RENUMBERED_KEYS) {
+            const raw = node[key];
+            if (typeof raw !== "string")
+                continue;
+            const map = seen[key];
+            const already = map.get(raw);
+            if (already !== undefined)
+                continue;
+            const expected = String(map.size);
+            if (raw !== expected) {
+                ok = false;
+                return;
+            }
+            map.set(raw, map.size);
+        }
+    });
+    return ok;
+}

package/dist/core/text/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export { defaultLocateTool } from "./toolchain.js";
+export { renumberHandles, handlesAreInEncounterOrder } from "./handles.js";
+export { convert, getConverter, CONVERTERS, BG3_CONVERTERS, CYBERPUNK_CONVERTERS } from "./converters/index.js";
+export { fieldDiff, diffCr2wJson, diffCr2wJsonText, diffLsx, diffLocaXml, diffLocaEntries, parseLocaXml } from "./diff/index.js";
+export * from "./templates/index.js";

package/dist/core/text/json.js

@@ -0,0 +1,46 @@
+export function isJsonObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+export function isJsonArray(v) {
+    return Array.isArray(v);
+}
+export function parseJson(text, label) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`${label}: not valid JSON (${err.message})`);
+    }
+}
+export function walkJson(root, visit, jsonPath = "$") {
+    visit(root, jsonPath);
+    if (isJsonArray(root)) {
+        root.forEach((item, i) => walkJson(item, visit, `${jsonPath}[${i}]`));
+    }
+    else if (isJsonObject(root)) {
+        for (const [key, value] of Object.entries(root)) {
+            walkJson(value, visit, `${jsonPath}.${key}`);
+        }
+    }
+}
+export function dollarValue(v) {
+    if (isJsonObject(v) && "$value" in v)
+        return v.$value;
+    return v;
+}
+export function dollarType(v) {
+    if (isJsonObject(v) && typeof v.$type === "string")
+        return v.$type;
+    return undefined;
+}
+export function cloneJson(v) {
+    if (isJsonArray(v))
+        return v.map((x) => cloneJson(x));
+    if (isJsonObject(v)) {
+        const out = {};
+        for (const [k, val] of Object.entries(v))
+            out[k] = cloneJson(val);
+        return out;
+    }
+    return v;
+}

package/dist/core/text/templates/cache.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+export function computeTemplateCacheKey(input) {
+    const parts = [
+        input.surface,
+        input.gameVersion,
+        `${input.toolId}@${input.toolVersion}`,
+        input.container,
+        input.internalPath,
+        input.conversion ?? "",
+    ];
+    return createHash("sha256").update(parts.join("\0")).digest("hex").slice(0, 32);
+}
+const SAFE_SEGMENT = /^(?!\.{1,2}$)[A-Za-z0-9._-]+$/;
+export function templateCacheDir(projectRoot, surface, gameVersion, key) {
+    for (const [label, value] of [["surface", surface], ["gameVersion", gameVersion], ["key", key]]) {
+        if (!SAFE_SEGMENT.test(value)) {
+            throw new Error(`template ${label} must be a single name of letters, digits, ".", "_" or "-", got ${JSON.stringify(value)}`);
+        }
+    }
+    return path.join(projectRoot, ".modwright", "cache", "templates", surface, gameVersion, key);
+}
+export function templateContentFilename(sourcePath, convertedExt) {
+    const ext = convertedExt ?? path.extname(sourcePath) ?? ".bin";
+    const normalized = ext.startsWith(".") ? ext : `.${ext}`;
+    return `content${normalized === "." ? ".bin" : normalized}`;
+}
+export async function checkTemplateInvalidation(record, opts) {
+    const reasons = [];
+    if (opts.currentGameVersion !== undefined && opts.currentGameVersion !== record.gameVersion) {
+        reasons.push(`the install reports game version "${opts.currentGameVersion}", but this cache entry is keyed to "${record.gameVersion}"`);
+    }
+    if (opts.locateTool) {
+        const location = await opts.locateTool(record.toolId);
+        if (!(location.found && location.versionNotProbed)) {
+            const currentToolVersion = location.found ? (location.version ?? "unknown") : "not found";
+            if (currentToolVersion !== record.toolVersion) {
+                reasons.push(`${record.toolId}'s version is now "${currentToolVersion}", but this entry was extracted with "${record.toolVersion}"`);
+            }
+        }
+    }
+    if (record.sourceContainer) {
+        try {
+            const stat = await fs.stat(record.sourceContainer);
+            if (record.containerSize !== undefined && stat.size !== record.containerSize) {
+                reasons.push(`container "${record.sourceContainer}" is now ${stat.size} bytes, this entry recorded ${record.containerSize}`);
+            }
+            if (record.containerMtime !== undefined) {
+                const mtime = stat.mtime.toISOString();
+                if (mtime !== record.containerMtime) {
+                    reasons.push(`container "${record.sourceContainer}" mtime is now ${mtime}, this entry recorded ${record.containerMtime}`);
+                }
+            }
+        }
+        catch {
+            reasons.push(`container "${record.sourceContainer}" could not be read (missing, or no longer accessible)`);
+        }
+    }
+    try {
+        const content = await fs.readFile(opts.contentAbsPath);
+        const sha256 = createHash("sha256").update(content).digest("hex");
+        if (sha256 !== record.sha256) {
+            reasons.push(`the cached content's sha256 (${sha256}) does not match the record's (${record.sha256}) — a corrupted or hand-edited entry`);
+        }
+    }
+    catch {
+        reasons.push(`the cached content file "${opts.contentAbsPath}" is missing or unreadable`);
+    }
+    return { valid: reasons.length === 0, reasons };
+}

package/dist/core/text/templates/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export { computeTemplateCacheKey, templateCacheDir, templateContentFilename, checkTemplateInvalidation } from "./cache.js";
+export { extractTemplate, listTemplates, getTemplate, invalidateTemplate } from "./library.js";

package/dist/core/text/templates/library.js

@@ -0,0 +1,245 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { runTool } from "../../toolchain/run.js";
+import { executePlan, planFile, planMkdir } from "../../safety/index.js";
+import { convert, getConverter } from "../converters/index.js";
+import { defaultLocateTool } from "../toolchain.js";
+import { checkTemplateInvalidation, computeTemplateCacheKey, templateCacheDir, templateContentFilename } from "./cache.js";
+import { templateRecordSchema } from "./types.js";
+async function safeReaddir(dir) {
+    try {
+        return (await fs.readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+async function readRecordIfPresent(recordPath) {
+    let text;
+    try {
+        text = await fs.readFile(recordPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = templateRecordSchema.safeParse(json);
+    return parsed.success ? parsed.data : undefined;
+}
+function regexEscape(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function extractionArgv(surface, container, internalPath, destDir) {
+    if (surface === "baldursgate3") {
+        return [
+            "-g", "bg3", "-a", "extract-package",
+            "-s", container, "-d", destDir,
+            "-x", `^${regexEscape(internalPath)}$`, "--use-regex",
+        ];
+    }
+    return ["extract", "-p", container, "-o", destDir, "-w", internalPath];
+}
+function contentExtFor(sourcePath, conversion) {
+    return conversion ? getConverter(conversion).to : path.extname(sourcePath);
+}
+export async function extractTemplate(input) {
+    const mode = input.mode ?? "dry-run";
+    const locateTool = input.locateTool ?? defaultLocateTool();
+    const toolId = input.surface === "baldursgate3" ? "divine" : "wolvenkit-cli";
+    const location = await locateTool(toolId);
+    const toolVersion = location.found ? (location.version ?? "unknown") : "unknown";
+    const key = computeTemplateCacheKey({
+        surface: input.surface,
+        gameVersion: input.gameVersion,
+        toolId,
+        toolVersion,
+        container: input.sourceContainer,
+        internalPath: input.sourcePath,
+        conversion: input.conversion,
+    });
+    const cacheDir = templateCacheDir(input.projectRoot, input.surface, input.gameVersion, key);
+    const recordPath = path.join(cacheDir, "record.json");
+    const contentFilename = templateContentFilename(input.sourcePath, contentExtFor(input.sourcePath, input.conversion));
+    const contentPath = path.join(cacheDir, contentFilename);
+    if (!input.refresh && mode === "apply") {
+        const existing = await readRecordIfPresent(recordPath);
+        if (existing) {
+            const invalidation = await checkTemplateInvalidation(existing, {
+                currentGameVersion: input.gameVersion,
+                locateTool,
+                contentAbsPath: contentPath,
+            });
+            if (invalidation.valid) {
+                return { action: "extract", mode, surface: input.surface, gameVersion: input.gameVersion, key, cacheDir, cached: true, invalidation, record: existing, applied: false, next: "Served from cache; no extraction ran." };
+            }
+        }
+    }
+    const extractionCommand = extractionArgv(input.surface, input.sourceContainer, input.sourcePath, "<cache>");
+    const conversionEntry = input.conversion ? getConverter(input.conversion) : undefined;
+    const planText = `${toolId} ${extractionCommand.join(" ")}${conversionEntry ? ` then ${conversionEntry.describe("<extracted>", "<content>")}` : ""}`;
+    if (mode === "dry-run") {
+        return {
+            action: "extract",
+            mode,
+            surface: input.surface,
+            gameVersion: input.gameVersion,
+            key,
+            cacheDir,
+            cached: false,
+            plan: planText,
+            applied: false,
+            next: 'Nothing was changed. Re-run with { mode: "apply" } to extract and cache this template.',
+        };
+    }
+    if (!location.found) {
+        return {
+            action: "extract",
+            mode,
+            surface: input.surface,
+            gameVersion: input.gameVersion,
+            key,
+            cacheDir,
+            cached: false,
+            applied: false,
+            next: location.hint,
+        };
+    }
+    const workDir = await fs.mkdtemp(path.join(os.tmpdir(), "modwright-text-extract-"));
+    try {
+        const rawDestDir = path.join(workDir, "raw");
+        await fs.mkdir(rawDestDir, { recursive: true });
+        const realArgv = extractionArgv(input.surface, input.sourceContainer, input.sourcePath, rawDestDir);
+        const rawOutputAbs = path.join(rawDestDir, input.sourcePath);
+        const result = await runTool(location, { args: realArgv, expectOutputs: [rawOutputAbs] });
+        if (!result.ok) {
+            return {
+                action: "extract",
+                mode,
+                surface: input.surface,
+                gameVersion: input.gameVersion,
+                key,
+                cacheDir,
+                cached: false,
+                applied: false,
+                next: `${toolId} extraction failed: ${result.error?.message ?? `exit ${result.exitCode}`}`,
+            };
+        }
+        let finalAbs = rawOutputAbs;
+        if (conversionEntry) {
+            const convertedAbs = path.join(workDir, `converted${conversionEntry.to.startsWith(".") ? conversionEntry.to : ".bin"}`);
+            const convResult = await convert(conversionEntry.id, rawOutputAbs, convertedAbs, { mode: "apply", locateTool, verifyRoundTrip: false });
+            if (!convResult.applied) {
+                return {
+                    action: "extract",
+                    mode,
+                    surface: input.surface,
+                    gameVersion: input.gameVersion,
+                    key,
+                    cacheDir,
+                    cached: false,
+                    applied: false,
+                    next: `template conversion (${conversionEntry.id}) did not apply: ${convResult.next ?? "unknown reason"}`,
+                };
+            }
+            finalAbs = convertedAbs;
+        }
+        const content = await fs.readFile(finalAbs);
+        const sha256 = createHash("sha256").update(content).digest("hex");
+        const containerStat = await fs.stat(input.sourceContainer).catch(() => undefined);
+        const record = templateRecordSchema.parse({
+            ref: input.ref,
+            surface: input.surface,
+            kind: input.kind,
+            provenance: "vanilla-extract",
+            permission: input.permission,
+            sourcePath: input.sourcePath,
+            sourceContainer: input.sourceContainer,
+            containerSize: containerStat?.size,
+            containerMtime: containerStat?.mtime.toISOString(),
+            gameVersion: input.gameVersion,
+            toolId,
+            toolVersion,
+            extractionCommand,
+            conversion: input.conversion,
+            sha256,
+            sizeBytes: content.length,
+            extractedAt: new Date().toISOString(),
+            strippedPaths: [],
+            notes: input.notes,
+        });
+        const normalizedRecord = JSON.parse(JSON.stringify(record));
+        const plan = {
+            purpose: `extract template ${input.ref} (${input.surface}/${input.gameVersion})`,
+            operations: [planMkdir(cacheDir), planFile(contentPath, content), planFile(recordPath, `${JSON.stringify(normalizedRecord, null, 2)}\n`)],
+            backupRoot: path.join(input.projectRoot, ".modwright", "backups"),
+        };
+        const writeReport = await executePlan(plan, {
+            mode: "apply",
+            confidence: { level: "medium", assumptions: [`${toolId}'s extraction argv is unconfirmed against a real binary.`] },
+        });
+        return {
+            action: "extract",
+            mode,
+            surface: input.surface,
+            gameVersion: input.gameVersion,
+            key,
+            cacheDir,
+            cached: false,
+            record: normalizedRecord,
+            applied: writeReport.applied,
+            next: writeReport.next,
+        };
+    }
+    finally {
+        await fs.rm(workDir, { recursive: true, force: true });
+    }
+}
+export async function listTemplates(projectRoot, filter = {}) {
+    const cacheRoot = path.join(projectRoot, ".modwright", "cache", "templates");
+    const surfaces = filter.surface ? [filter.surface] : (await safeReaddir(cacheRoot));
+    const out = [];
+    for (const surface of surfaces) {
+        const surfaceDir = path.join(cacheRoot, surface);
+        const versions = filter.gameVersion ? [filter.gameVersion] : await safeReaddir(surfaceDir);
+        for (const gameVersion of versions) {
+            const versionDir = path.join(surfaceDir, gameVersion);
+            for (const key of await safeReaddir(versionDir)) {
+                const record = await readRecordIfPresent(path.join(versionDir, key, "record.json"));
+                if (record)
+                    out.push({ key, surface, gameVersion, cacheDir: path.join(versionDir, key), record });
+            }
+        }
+    }
+    return out;
+}
+export async function getTemplate(projectRoot, surface, gameVersion, key, opts = {}) {
+    const cacheDir = templateCacheDir(projectRoot, surface, gameVersion, key);
+    const record = await readRecordIfPresent(path.join(cacheDir, "record.json"));
+    if (!record)
+        return undefined;
+    const contentPath = path.join(cacheDir, templateContentFilename(record.sourcePath, contentExtFor(record.sourcePath, record.conversion)));
+    const invalidation = opts.currentGameVersion !== undefined || opts.locateTool
+        ? await checkTemplateInvalidation(record, { currentGameVersion: opts.currentGameVersion, locateTool: opts.locateTool, contentAbsPath: contentPath })
+        : undefined;
+    return { record, cacheDir, contentPath, invalidation };
+}
+export async function invalidateTemplate(projectRoot, surface, gameVersion, key, mode = "dry-run") {
+    const cacheDir = templateCacheDir(projectRoot, surface, gameVersion, key);
+    const plan = {
+        purpose: `invalidate cached template ${surface}/${gameVersion}/${key}`,
+        operations: [{ kind: "delete", path: cacheDir }],
+        backupRoot: path.join(projectRoot, ".modwright", "backups"),
+    };
+    return executePlan(plan, {
+        mode,
+        confidence: { level: "high", assumptions: ["Only the untracked template cache (.modwright/cache/templates/) is touched; the tracked authoring manifest is never affected."] },
+    });
+}

package/dist/core/text/templates/types.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+export const TEMPLATE_PROVENANCE = ["vanilla-extract", "own-work", "authored"];
+export const TEMPLATE_PERMISSION = ["never-redistribute", "maintainer-own", "declared-dependency"];
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+export const templateRecordSchema = z
+    .object({
+    ref: z.string(),
+    surface: z.enum(["baldursgate3", "cyberpunk2077"]),
+    kind: z.string(),
+    provenance: z.enum(TEMPLATE_PROVENANCE),
+    permission: z.enum(TEMPLATE_PERMISSION),
+    sourcePath: z.string(),
+    sourceContainer: z.string().optional(),
+    containerSize: z.number().int().optional(),
+    containerMtime: z.string().optional(),
+    gameVersion: z.string(),
+    toolId: z.string(),
+    toolVersion: z.string(),
+    extractionCommand: z.array(z.string()),
+    conversion: z.string().optional(),
+    sha256: z.string().regex(SHA256_PATTERN),
+    sizeBytes: z.number().int(),
+    extractedAt: z.string(),
+    strippedPaths: z.array(z.string()).default([]),
+    notes: z.string().optional(),
+})
+    .strict();
+export function templateCacheDir(projectRoot, surface, gameVersion, key) {
+    return [projectRoot, ".modwright", "cache", "templates", surface, gameVersion, key].join("/");
+}
+export const TEMPLATE_MANIFEST_FILE = ".modwright/templates/manifest.json";
+export const AUTHORING_MANIFEST_SCHEMA_VERSION = 1;
+export const authoringManifestEntrySchema = z
+    .object({
+    path: z.string(),
+    derivedFrom: z.string(),
+    provenance: z.enum(TEMPLATE_PROVENANCE),
+    permission: z.enum(TEMPLATE_PERMISSION),
+    templateSha256: z.string().regex(SHA256_PATTERN),
+    authoredSha256: z.string().regex(SHA256_PATTERN),
+    rewrittenPaths: z.array(z.string()),
+    scaffold: z.string(),
+    writtenAt: z.string(),
+})
+    .strict();
+export const authoringManifestSchema = z
+    .object({
+    schemaVersion: z.literal(AUTHORING_MANIFEST_SCHEMA_VERSION),
+    entries: z.array(authoringManifestEntrySchema),
+})
+    .strict();

package/dist/core/text/toolchain.js

@@ -0,0 +1,16 @@
+import { locateTool as coreLocateTool, TOOL_SPECS } from "../toolchain/index.js";
+export function defaultLocateTool(projectOverrides, probe = "all") {
+    return async (id) => {
+        const spec = TOOL_SPECS.find((s) => s.id === id);
+        if (!spec) {
+            return {
+                id,
+                label: id,
+                found: false,
+                usedBy: [],
+                hint: `"${id}" is not a known tool id in ModWright's toolchain catalog (see core/toolchain/specs.ts).`,
+            };
+        }
+        return coreLocateTool(spec, { projectOverrides, probe });
+    };
+}

package/dist/core/text/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/text/validate.js

@@ -0,0 +1,149 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { walk } from "../fsutil.js";
+import { sha256File } from "../build/manifest.js";
+import { listTemplates } from "./templates/library.js";
+import { TEMPLATE_MANIFEST_FILE, authoringManifestSchema } from "./templates/types.js";
+const GROUPS = ["history"];
+const MOD_TYPES = ["packaging"];
+function isProjectTarget(target) {
+    return target.kind === "project";
+}
+function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+function projectRelative(root, abs) {
+    return toPosix(path.relative(root, abs));
+}
+async function readAuthoringManifest(root) {
+    const manifestPath = path.join(root, TEMPLATE_MANIFEST_FILE);
+    let text;
+    try {
+        text = await fs.readFile(manifestPath, "utf8");
+    }
+    catch {
+        return new Map();
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        return new Map();
+    }
+    const parsed = authoringManifestSchema.safeParse(json);
+    if (!parsed.success)
+        return new Map();
+    return new Map(parsed.data.entries.map((e) => [toPosix(e.path), e]));
+}
+async function vanillaExtractShaIndex(root, surface) {
+    const entries = await listTemplates(root, { surface });
+    const index = new Map();
+    for (const e of entries) {
+        if (e.record.provenance === "vanilla-extract")
+            index.set(e.record.sha256, e.record.ref);
+    }
+    return index;
+}
+function collectRoots(project) {
+    const roots = [];
+    if (project.build?.absStaging)
+        roots.push({ label: "build.staging", abs: project.build.absStaging });
+    if (project.build?.outDirExists && project.build.absOutDir)
+        roots.push({ label: "build.outDir", abs: project.build.absOutDir });
+    const targets = project.project.deploy?.targets ?? [];
+    for (const target of targets) {
+        const sourceMatch = project.sources.find((s) => s.id === target.from && s.exists);
+        if (sourceMatch) {
+            roots.push({ label: `deploy target "${target.from}" (source)`, abs: sourceMatch.absPath });
+            continue;
+        }
+        if (project.build?.absOutDir) {
+            roots.push({ label: `deploy target "${target.from}"`, abs: path.join(project.build.absOutDir, target.from) });
+        }
+    }
+    return roots;
+}
+export function vanillaExtractNeverShipValidator(opts) {
+    const surface = opts.game;
+    return {
+        id: opts.id,
+        game: opts.game,
+        groups: GROUPS,
+        modTypes: MOD_TYPES,
+        summary: "Blocks a build whose staged/dist/deploy output carries a verbatim vanilla-extract template (by sha256), " +
+            "or one the tracked authoring manifest records as derived from such a template with no rewrittenPaths — a " +
+            "curated shipped copy of vanilla content is a licence violation, and non-negotiable.",
+        appliesTo: isProjectTarget,
+        appliesToDescription: "the whole project: build.staging, build.outDir (once it exists on disk) and every resolved deploy.targets[].from root",
+        needs: { project: true },
+        cost: "build",
+        severity: "block",
+        evidence: opts.evidence,
+        async run(ctx) {
+            const project = ctx.project;
+            const findings = [];
+            const manifestByPath = await readAuthoringManifest(project.root);
+            const shaIndex = await vanillaExtractShaIndex(project.root, surface);
+            if (manifestByPath.size === 0 && shaIndex.size === 0)
+                return findings;
+            const seen = new Set();
+            for (const root of collectRoots(project)) {
+                const { files, truncated } = await walk(root.abs, { limit: 50_000 });
+                for (const rel of files) {
+                    const abs = path.join(root.abs, rel);
+                    if (seen.has(abs))
+                        continue;
+                    seen.add(abs);
+                    const relPosix = toPosix(rel);
+                    const projectRel = projectRelative(project.root, abs);
+                    const manifestEntry = manifestByPath.get(projectRel);
+                    if (manifestEntry && manifestEntry.provenance === "vanilla-extract" && manifestEntry.rewrittenPaths.length === 0) {
+                        findings.push({
+                            validatorId: opts.id,
+                            severity: "block",
+                            file: abs,
+                            message: `"${relPosix}" under ${root.label} (${root.abs}) is recorded in ${TEMPLATE_MANIFEST_FILE} as derived from the ` +
+                                `vanilla-extract template "${manifestEntry.derivedFrom}" (written by scaffold "${manifestEntry.scaffold}") with ` +
+                                `an empty rewrittenPaths — a copy with the serial numbers not even filed off.`,
+                            fix: `Rewrite at least one field before this file ships, or drop it from the deploy/dist set.`,
+                            evidence: opts.evidence,
+                            related: [path.join(project.root, TEMPLATE_MANIFEST_FILE)],
+                        });
+                        continue;
+                    }
+                    let sha256;
+                    try {
+                        sha256 = await sha256File(abs);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const ref = shaIndex.get(sha256);
+                    if (ref) {
+                        findings.push({
+                            validatorId: opts.id,
+                            severity: "block",
+                            file: abs,
+                            message: `"${relPosix}" under ${root.label} (${root.abs}) is byte-identical (sha256 ${sha256}) to the cached ` +
+                                `vanilla-extract template "${ref}" — a verbatim copy of vanilla content. Vanilla game data is never ` +
+                                `redistributed and never shipped, by ModWright or by a mod built with it.`,
+                            fix: `Remove this file from the shipping set, or run it through a scaffold that rewrites at least one field.`,
+                            evidence: opts.evidence,
+                        });
+                    }
+                }
+                if (truncated) {
+                    findings.push({
+                        validatorId: opts.id,
+                        severity: "info",
+                        file: root.abs,
+                        message: `${root.label} has more files than this scan's limit; the vanilla-extract-never-ships scan may be incomplete for it.`,
+                        evidence: opts.evidence,
+                    });
+                }
+            }
+            return findings;
+        },
+    };
+}