ushman-characterize 0.4.0

package/dist/stub-pure.js

@@ -0,0 +1,987 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import traverse from '@babel/traverse';
+import * as t from '@babel/types';
+import { parseModuleAst } from "./babel-config.js";
+import { parseTraceRecord, stampTraceRecord } from "./format-contract.js";
+import { recordCharacterizeToolingGap, recordCharacterizeValidatorResult } from "./ledger.js";
+import { classifyPureTopLevelFunctionsFromBundle } from "./purity-classifier.js";
+import { hashSeedScaffoldContent, listFilesRecursive, loadSeedFingerprintSidecar, toWorkspaceRelativePath, updateSeedFingerprintSidecar, } from "./seed-scaffolds.js";
+import { buildStandaloneSymbolModule, parseBundleAst, parseJsonLines, relativeImportPath, sanitizeSymbolName, stableJsonStringify, toJsonLines, } from "./shared.js";
+import { canonicalizeTraceValue, ensureWorkspaceTraceHarness } from "./trace-format.js";
+import { assertV4Workspace, atomicWriteText } from "./workspace-paths.js";
+// Keep automatic pure-function sampling small enough that stub generation remains fast.
+// Operators can expand coverage manually after the initial scaffold lands.
+const MAX_AUTO_CASES = 5;
+// Prevent combinatorial explosion when heuristic argument candidates are cartesian-producted.
+const MAX_CANDIDATE_ARG_PRODUCTS = 10;
+// Promise-returning helpers that do not settle quickly are treated as non-deterministic samples.
+const PROMISE_SAMPLE_TIMEOUT_MS = 100;
+// Best-effort heuristic inference for seed-time sample generation. This is
+// intentionally conservative and only drives the legacy manual stub-pure flow.
+const inferKind = (parameterName) => {
+    const name = parameterName.toLowerCase();
+    const isScalarShortName = /^(ms|n|t|x|y|z)$/u.test(name);
+    if (/^(is|has|should|can)[a-z]/u.test(parameterName) || /enabled|flag|visible|open|closed/u.test(name)) {
+        return 'boolean';
+    }
+    if (/array|items|list|children|values|points/u.test(name)) {
+        return 'array';
+    }
+    if (/name|label|text|path|slug|key|id|url|message/u.test(name)) {
+        return 'string';
+    }
+    if (isScalarShortName ||
+        /value|count|index|offset|min|max|width|height|size|scale|angle|yaw|pitch|roll/u.test(name)) {
+        return 'number';
+    }
+    if (/options|config|meta|props|state|data/u.test(name)) {
+        return 'object';
+    }
+    return 'unknown';
+};
+const product = (items, limit) => {
+    const out = [[]];
+    for (const values of items) {
+        const next = [];
+        for (const prefix of out) {
+            for (const value of values) {
+                next.push([...prefix, value]);
+                if (next.length >= limit) {
+                    return next;
+                }
+            }
+        }
+        out.splice(0, out.length, ...next);
+    }
+    return out;
+};
+const candidateValuesForKind = (kind) => {
+    switch (kind) {
+        case 'array':
+            return [[], [0], [1, 2], ['a', 'b']];
+        case 'boolean':
+            return [false, true];
+        case 'number':
+            return [-1, 0, 1, 5, 10];
+        case 'object':
+            return [{}, { value: 1 }, { max: 10, min: 0 }];
+        case 'string':
+            return ['', 'a', 'abc', 'value'];
+        default:
+            return [0, 1, 'a', true, {}, []];
+    }
+};
+const buildCandidateArgs = (info) => {
+    if (info.parameterNames.length === 0) {
+        return [[]];
+    }
+    if (info.parameterNames.length === 3 &&
+        inferKind(info.parameterNames[0] ?? '') === 'number' &&
+        inferKind(info.parameterNames[1] ?? '') === 'number' &&
+        inferKind(info.parameterNames[2] ?? '') === 'number') {
+        return [
+            [-1, 0, 10],
+            [0, 0, 10],
+            [5, 0, 10],
+            [11, 0, 10],
+            [1, 2, 3],
+        ];
+    }
+    const perParameter = info.parameterNames.map((name) => candidateValuesForKind(inferKind(name)));
+    return product(perParameter, MAX_CANDIDATE_ARG_PRODUCTS);
+};
+const renderArrayLiteral = (value) => {
+    const rendered = value.map((entry) => renderLiteral(entry));
+    return rendered.every((entry) => entry !== null) ? `[${rendered.join(', ')}]` : null;
+};
+const renderObjectLiteral = (value) => {
+    const entries = Object.entries(value).map(([key, entry]) => [key, renderLiteral(entry)]);
+    if (entries.some(([, entry]) => entry === null)) {
+        return null;
+    }
+    return `{ ${entries.map(([key, entry]) => `${JSON.stringify(key)}: ${entry}`).join(', ')} }`;
+};
+const renderLiteral = (value) => {
+    if (value === undefined) {
+        return 'undefined';
+    }
+    if (typeof value === 'number') {
+        if (Number.isNaN(value)) {
+            return 'Number.NaN';
+        }
+        if (value === Number.POSITIVE_INFINITY) {
+            return 'Number.POSITIVE_INFINITY';
+        }
+        if (value === Number.NEGATIVE_INFINITY) {
+            return 'Number.NEGATIVE_INFINITY';
+        }
+        if (Object.is(value, -0)) {
+            return '-0';
+        }
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'boolean' || value === null) {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return renderArrayLiteral(value);
+    }
+    if (typeof value === 'object') {
+        return renderObjectLiteral(value);
+    }
+    return null;
+};
+const isCaseRenderable = (value) => renderLiteral(value.expected) !== null && value.args.every((entry) => renderLiteral(entry) !== null);
+const hasDetachedTextureLoadHazard = (source) => {
+    const ast = parseModuleAst({
+        source,
+        sourcePath: 'inline://stub-pure-hazard-check.js',
+    });
+    let sawTextureLoader = false;
+    let sawPromiseConstructor = false;
+    traverse(ast, {
+        Identifier(identifierPath) {
+            if (identifierPath.node.name === 'TextureLoader') {
+                sawTextureLoader = true;
+            }
+            if (identifierPath.node.name === 'Promise' &&
+                identifierPath.parentPath.isNewExpression() &&
+                identifierPath.parentPath.node.callee === identifierPath.node) {
+                sawPromiseConstructor = true;
+            }
+            if (sawTextureLoader && sawPromiseConstructor) {
+                identifierPath.stop();
+            }
+        },
+        NewExpression(newExpressionPath) {
+            if (t.isIdentifier(newExpressionPath.node.callee, { name: 'Promise' })) {
+                sawPromiseConstructor = true;
+                if (sawTextureLoader) {
+                    newExpressionPath.stop();
+                }
+            }
+        },
+    });
+    return sawTextureLoader && sawPromiseConstructor;
+};
+const isPromiseLike = (value) => Boolean(value) && typeof value === 'object' && typeof value.then === 'function';
+const settlePromiseSample = async (value) => {
+    let timeoutId;
+    try {
+        return await Promise.race([
+            Promise.resolve(value).then((resolved) => ({ ok: true, value: resolved }), () => ({ ok: false })),
+            new Promise((resolve) => {
+                timeoutId = setTimeout(() => resolve({ ok: false }), PROMISE_SAMPLE_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+};
+const executeSampleSafely = async (run) => {
+    let asyncFault = false;
+    const markAsyncFault = () => {
+        asyncFault = true;
+    };
+    process.on('unhandledRejection', markAsyncFault);
+    process.on('uncaughtException', markAsyncFault);
+    try {
+        let value;
+        try {
+            value = run();
+        }
+        catch {
+            return { ok: false };
+        }
+        const settled = isPromiseLike(value) ? await settlePromiseSample(value) : { ok: true, value };
+        if (!settled.ok) {
+            return settled;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        return asyncFault ? { ok: false } : settled;
+    }
+    finally {
+        process.off('unhandledRejection', markAsyncFault);
+        process.off('uncaughtException', markAsyncFault);
+    }
+};
+const loadFunctionCases = async ({ info, modulePath, }) => {
+    const moduleSource = await Bun.file(modulePath).text();
+    if (hasDetachedTextureLoadHazard(moduleSource)) {
+        return [];
+    }
+    const moduleUrl = `${pathToFileURL(modulePath).href}?cacheBust=${Date.now()}`;
+    const mod = (await import(__rewriteRelativeImportExtension(moduleUrl)));
+    const fn = mod[info.bindingName];
+    if (typeof fn !== 'function') {
+        return [];
+    }
+    const cases = [];
+    const seen = new Set();
+    for (const args of buildCandidateArgs(info)) {
+        try {
+            const expected = await executeSampleSafely(() => fn(...args));
+            if (!expected.ok) {
+                continue;
+            }
+            const canonicalExpected = canonicalizeTraceValue(expected.value);
+            const key = JSON.stringify({ args, expected: canonicalExpected });
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            const sample = { args, expected: canonicalExpected };
+            if (isCaseRenderable(sample)) {
+                cases.push(sample);
+            }
+        }
+        catch {
+            continue;
+        }
+        if (cases.length >= MAX_AUTO_CASES) {
+            break;
+        }
+    }
+    return cases;
+};
+const renderTestSource = ({ info, fixtureName, harnessPath, modulePath, testFile, }) => {
+    const harnessImportPath = relativeImportPath({ fromFile: testFile, toFile: harnessPath });
+    const importPath = relativeImportPath({ fromFile: testFile, toFile: modulePath });
+    return `// AUTO-GENERATED by ushman-characterize stub-pure. Do not hand-edit.
+import { expect, test } from 'bun:test';
+import { fixture, registerTraceMatchers } from '${harnessImportPath}';
+import { ${info.bindingName} } from '${importPath}';
+
+registerTraceMatchers();
+
+const cases = await fixture('pure', '${fixtureName}');
+
+for (const [index, entry] of cases.entries()) {
+  test('${info.name}: case #' + (index + 1), () => {
+    expect(${info.bindingName}(...entry.args)).toMatchTrace(entry.expected);
+  });
+}
+
+test.todo('${info.name}: add operator-supplied edge cases');
+`;
+};
+const isRelativeSpecifier = (value) => value.startsWith('./') || value.startsWith('../');
+const uniqueSymbolsInOrder = (symbols) => {
+    const seen = new Set();
+    return symbols.filter((symbol) => {
+        if (seen.has(symbol)) {
+            return false;
+        }
+        seen.add(symbol);
+        return true;
+    });
+};
+const collectManagedImportCandidateSymbols = (node) => node.specifiers
+    .map((specifier) => {
+    if (t.isImportSpecifier(specifier)) {
+        return t.isIdentifier(specifier.imported) ? specifier.imported.name : specifier.imported.value;
+    }
+    if (t.isImportDefaultSpecifier(specifier)) {
+        return 'default';
+    }
+    if (t.isImportNamespaceSpecifier(specifier)) {
+        return '*';
+    }
+    return null;
+})
+    .filter((symbol) => symbol !== null);
+const selectManagedImportCandidate = ({ candidates, filePath, todoSymbols, }) => {
+    const matchingCandidates = candidates.filter((candidate) => todoSymbols.every((symbol) => candidate.exportedSymbols.includes(symbol)));
+    if (matchingCandidates.length === 1) {
+        return matchingCandidates[0];
+    }
+    if (matchingCandidates.length > 1) {
+        throw new Error(`Managed pure scaffold ${filePath} matched multiple source-module imports for symbols: ${todoSymbols.join(', ')}.`);
+    }
+    throw new Error(`Managed pure scaffold ${filePath} could not resolve a unique source-module import for symbols: ${todoSymbols.join(', ')}.`);
+};
+const parseManagedPureScaffold = ({ filePath, source, workspaceDir, }) => {
+    const ast = parseModuleAst({
+        source,
+        sourcePath: filePath,
+    });
+    const todoSymbols = [];
+    const importCandidates = [];
+    const srcRoot = path.join(workspaceDir, 'src');
+    traverse(ast, {
+        CallExpression(callPath) {
+            if (t.isMemberExpression(callPath.node.callee) &&
+                t.isIdentifier(callPath.node.callee.object, { name: 'test' }) &&
+                t.isIdentifier(callPath.node.callee.property, { name: 'todo' })) {
+                const [firstArgument] = callPath.node.arguments;
+                if (t.isStringLiteral(firstArgument)) {
+                    todoSymbols.push(firstArgument.value);
+                }
+            }
+        },
+        ImportDeclaration(importPathNode) {
+            if (!isRelativeSpecifier(importPathNode.node.source.value)) {
+                return;
+            }
+            const resolvedImportPath = path.resolve(path.dirname(filePath), importPathNode.node.source.value);
+            if (!resolvedImportPath.startsWith(`${srcRoot}${path.sep}`) && resolvedImportPath !== srcRoot) {
+                return;
+            }
+            const exportedSymbols = collectManagedImportCandidateSymbols(importPathNode.node);
+            if (exportedSymbols.length === 0) {
+                return;
+            }
+            importCandidates.push({
+                exportedSymbols,
+                importPath: importPathNode.node.source.value,
+                moduleFilePath: resolvedImportPath,
+            });
+        },
+    });
+    const managedSymbols = uniqueSymbolsInOrder(todoSymbols);
+    if (managedSymbols.length === 0) {
+        throw new Error(`Unable to find any managed export symbols in ${filePath}.`);
+    }
+    const selectedImport = selectManagedImportCandidate({
+        candidates: importCandidates,
+        filePath,
+        todoSymbols: managedSymbols,
+    });
+    if (!selectedImport) {
+        throw new Error(`Unable to find a managed source-module import in ${filePath}.`);
+    }
+    const moduleRelativePath = path
+        .relative(srcRoot, selectedImport.moduleFilePath)
+        .split(path.sep)
+        .join('/')
+        .replace(/\.[^.]+$/u, '');
+    if (moduleRelativePath.startsWith('../')) {
+        throw new Error(`Managed pure scaffold ${filePath} points outside ${srcRoot}.`);
+    }
+    return {
+        filePath,
+        importPath: selectedImport.importPath,
+        moduleFilePath: selectedImport.moduleFilePath,
+        moduleRelativePath,
+        relativeTestPath: toWorkspaceRelativePath({
+            filePath,
+            workspaceDir,
+        }),
+        symbols: managedSymbols,
+    };
+};
+const collectManagedPureScaffolds = async (workspaceDir) => {
+    const testsDir = path.join(workspaceDir, 'tests', 'pure');
+    const files = await listFilesRecursive({
+        dir: testsDir,
+        suffix: '.test.ts',
+    });
+    const parsed = await Promise.all(files.map(async (filePath) => {
+        try {
+            return {
+                error: null,
+                filePath,
+                scaffold: parseManagedPureScaffold({
+                    filePath,
+                    source: await Bun.file(filePath).text(),
+                    workspaceDir,
+                }),
+            };
+        }
+        catch (error) {
+            return {
+                error: error instanceof Error ? error.message : String(error),
+                filePath,
+                scaffold: null,
+            };
+        }
+    }));
+    return {
+        parseFailures: parsed
+            .filter((entry) => entry.error !== null)
+            .map((entry) => ({
+            filePath: entry.filePath,
+            message: entry.error,
+        }))
+            .sort((left, right) => left.filePath.localeCompare(right.filePath)),
+        scaffolds: parsed
+            .flatMap((entry) => (entry.scaffold ? [entry.scaffold] : []))
+            .sort((left, right) => left.filePath.localeCompare(right.filePath)),
+    };
+};
+const isScaffoldUnmodified = ({ currentHash, trackedHash, }) => trackedHash !== undefined && trackedHash === currentHash;
+const matchesPopulateFilters = ({ modulePathPrefix, scaffold, symbolFilter, }) => (modulePathPrefix === undefined || scaffold.moduleRelativePath.startsWith(modulePathPrefix)) &&
+    (symbolFilter === undefined ||
+        scaffold.symbols.some((symbol) => symbolFilter(symbol, scaffold.moduleRelativePath)));
+const buildSymbolOwnershipMap = (scaffolds) => {
+    const ownershipCounts = new Map();
+    for (const scaffold of scaffolds) {
+        for (const symbol of new Set(scaffold.symbols)) {
+            const owners = ownershipCounts.get(symbol) ?? new Set();
+            owners.add(scaffold.relativeTestPath);
+            ownershipCounts.set(symbol, owners);
+        }
+    }
+    return new Map([...ownershipCounts.entries()].map(([symbol, owners]) => [
+        symbol,
+        [...owners].sort((left, right) => left.localeCompare(right)),
+    ]));
+};
+const buildPureModuleTracePath = ({ moduleRelativePath, workspaceDir, }) => path.join(workspaceDir, '.lab', 'characterize', 'traces', `${moduleRelativePath}.jsonl`);
+const readTraceRecords = async ({ contextPrefix, filePath, }) => {
+    try {
+        return parseJsonLines(await Bun.file(filePath).text()).map((record, index) => parseTraceRecord({
+            context: `${contextPrefix}:${index + 1}`,
+            value: record,
+        }));
+    }
+    catch (error) {
+        throw new Error(`Trace file ${filePath} is invalid or incompatible. ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+const sortStableStrings = (values) => [...values].sort((left, right) => left.localeCompare(right));
+const recordMatchesSymbol = ({ record, symbol }) => record.bindingName === symbol || record.functionName === symbol || record.methodName === symbol;
+const buildPureCases = ({ records, symbol, }) => {
+    const deduped = new Map();
+    for (const record of records) {
+        if (!recordMatchesSymbol({ record, symbol })) {
+            continue;
+        }
+        const nextCase = {
+            args: record.args,
+            expected: record.expected,
+            state: record.state,
+            thisArg: record.thisArg,
+            threw: record.threw,
+        };
+        const key = stableJsonStringify({
+            args: nextCase.args,
+            expected: nextCase.expected,
+            thisArg: nextCase.thisArg,
+            threw: nextCase.threw,
+        });
+        if (!deduped.has(key)) {
+            deduped.set(key, nextCase);
+        }
+    }
+    return [...deduped.values()].sort((left, right) => stableJsonStringify(left).localeCompare(stableJsonStringify(right)));
+};
+const renderPureCaseConst = ({ cases, symbol, }) => `const ${sanitizeSymbolName(symbol)}Cases = ${stableJsonStringify(cases, 2)} as const;\n`;
+const renderPureSymbolBlock = ({ cases, symbol, }) => {
+    if (cases.length === 0) {
+        return `  test.todo('${symbol}');\n`;
+    }
+    const caseConstName = `${sanitizeSymbolName(symbol)}Cases`;
+    return cases
+        .map((entry, index) => [
+        `  test('${symbol} case #${index + 1} [${entry.state}]', async () => {`,
+        `    const observed = await invokeManagedTraceCase(${symbol}, ${caseConstName}[${index}]!);`,
+        `    const traceEntry = ${caseConstName}[${index}]!;`,
+        '    if (traceEntry.threw !== null) {',
+        '      expect(observed.threw).not.toBeNull();',
+        '      expect(canonicalizeThrownValue(observed.threw)).toEqual(traceEntry.threw);',
+        '      return;',
+        '    }',
+        '    expect(observed.threw).toBeNull();',
+        '    assertObservedTraceValue(observed.value, traceEntry.expected, { floatDigits: FLOAT_TOLERANCE_DIGITS });',
+        '  });',
+        '',
+    ].join('\n'))
+        .join('\n');
+};
+const renderPopulatedPureTestSource = ({ harnessPath, scaffold, symbolCases, }) => {
+    const harnessImportPath = relativeImportPath({
+        fromFile: scaffold.filePath,
+        toFile: harnessPath,
+    });
+    const importPath = relativeImportPath({
+        fromFile: scaffold.filePath,
+        toFile: scaffold.moduleFilePath,
+    });
+    const managedSymbols = scaffold.symbols.filter((symbol) => symbolCases.has(symbol));
+    return [
+        '// AUTO-GENERATED by ushman-characterize populateScaffolds. Do not hand-edit.',
+        "import { describe, expect, test } from 'bun:test';",
+        `import { assertObservedTraceValue, canonicalizeThrownValue, invokeManagedTraceCase } from '${harnessImportPath}';`,
+        `import { ${managedSymbols.join(', ')} } from '${importPath}';`,
+        '',
+        'const FLOAT_TOLERANCE_DIGITS = 4;',
+        '',
+        ...scaffold.symbols
+            .filter((symbol) => (symbolCases.get(symbol) ?? []).length > 0)
+            .map((symbol) => renderPureCaseConst({
+            cases: symbolCases.get(symbol) ?? [],
+            symbol,
+        })),
+        `describe('${scaffold.moduleRelativePath}', () => {`,
+        ...scaffold.symbols.map((symbol) => renderPureSymbolBlock({
+            cases: symbolCases.get(symbol) ?? [],
+            symbol,
+        })),
+        '});',
+        '',
+    ].join('\n');
+};
+const listLegacyStateTraceFiles = async (workspaceDir) => {
+    const tracesDir = path.join(workspaceDir, '.lab', 'characterize', 'traces');
+    const files = await listFilesRecursive({
+        dir: tracesDir,
+        suffix: '.jsonl',
+    });
+    return files.filter((filePath) => path.dirname(filePath) === tracesDir);
+};
+const indexLegacyStateTraceRecords = async (workspaceDir) => {
+    const topLevelTraceFiles = await listLegacyStateTraceFiles(workspaceDir);
+    const groupedRecords = new Map();
+    const parseFailures = [];
+    for (const filePath of topLevelTraceFiles) {
+        let records;
+        try {
+            records = await readTraceRecords({
+                contextPrefix: `Trace record ${path.basename(filePath)}`,
+                filePath,
+            });
+        }
+        catch (error) {
+            parseFailures.push(error instanceof Error ? error.message : String(error));
+            continue;
+        }
+        for (const record of records) {
+            for (const symbol of uniqueSymbolsInOrder([record.bindingName, record.functionName, record.methodName].filter((entry) => typeof entry === 'string' && entry.length > 0))) {
+                const current = groupedRecords.get(symbol) ?? [];
+                current.push(record);
+                groupedRecords.set(symbol, current);
+            }
+        }
+    }
+    return {
+        parseFailures,
+        recordsBySymbol: new Map([...groupedRecords.entries()].map(([symbol, records]) => [
+            symbol,
+            [...records].sort((left, right) => stableJsonStringify(left).localeCompare(stableJsonStringify(right))),
+        ])),
+        topLevelTraceFiles,
+    };
+};
+const synthesizeModuleTraceFromLegacyStateTraces = async ({ legacyTraceIndex, ownershipMap, scaffold, targetPath, }) => {
+    const ambiguousSymbols = sortStableStrings(scaffold.symbols.filter((symbol) => (ownershipMap.get(symbol) ?? []).length > 1));
+    if (ambiguousSymbols.length > 0) {
+        return {
+            ambiguity: ambiguousSymbols.map((symbol) => ({
+                owners: ownershipMap.get(symbol) ?? [],
+                symbol,
+            })),
+            written: false,
+        };
+    }
+    const matchedRecords = scaffold.symbols.flatMap((symbol) => legacyTraceIndex.recordsBySymbol.get(symbol) ?? []);
+    if (matchedRecords.length === 0) {
+        return {
+            ambiguity: [],
+            written: false,
+        };
+    }
+    const deduped = new Map();
+    for (const record of matchedRecords.sort((left, right) => stableJsonStringify(left).localeCompare(stableJsonStringify(right)))) {
+        const versioned = stampTraceRecord(record);
+        deduped.set(stableJsonStringify(versioned), versioned);
+    }
+    await atomicWriteText(targetPath, `${toJsonLines([...deduped.values()])}\n`);
+    return {
+        ambiguity: [],
+        written: true,
+    };
+};
+const resolveModuleTracePath = async ({ legacyTraceIndex, ownershipMap, scaffold, workspaceDir, }) => {
+    const moduleTracePath = buildPureModuleTracePath({
+        moduleRelativePath: scaffold.moduleRelativePath,
+        workspaceDir,
+    });
+    if (await Bun.file(moduleTracePath).exists()) {
+        return {
+            kind: 'found',
+            moduleTracePath,
+            synthesized: false,
+        };
+    }
+    const synthesized = await synthesizeModuleTraceFromLegacyStateTraces({
+        legacyTraceIndex,
+        ownershipMap,
+        scaffold,
+        targetPath: moduleTracePath,
+    });
+    if (synthesized.written) {
+        return {
+            kind: 'found',
+            moduleTracePath,
+            synthesized: true,
+        };
+    }
+    if (synthesized.ambiguity.length > 0) {
+        return {
+            kind: 'gap',
+            result: {
+                body: `Cannot synthesize ${moduleTracePath} from legacy state traces because these symbols are ambiguous across scaffolds: ${synthesized.ambiguity
+                    .map(({ owners, symbol }) => `${symbol} (${owners.join(', ')})`)
+                    .join('; ')}`,
+                summary: `ambiguous legacy trace synthesis for ${scaffold.relativeTestPath}`,
+            },
+        };
+    }
+    return {
+        kind: 'missing',
+        moduleTracePath,
+    };
+};
+const summarizePopulateScaffolds = ({ skipped, toolingGaps, written, }) => [
+    `populated ${written.length} pure scaffold file(s)`,
+    skipped.length > 0 ? `skipped ${skipped.length} operator-managed file(s)` : null,
+    toolingGaps.length > 0 ? `${toolingGaps.length} tooling gap(s)` : null,
+]
+    .filter((value) => value !== null)
+    .join('; ');
+export const scaffoldPureCharacterizationTests = async ({ bundlePath, dryRun = false, workspaceRoot, }) => {
+    await assertV4Workspace(workspaceRoot);
+    const source = await Bun.file(bundlePath).text();
+    const bundle = parseBundleAst({ source, sourcePath: bundlePath });
+    const classification = classifyPureTopLevelFunctionsFromBundle(bundle);
+    const testsDir = path.join(workspaceRoot, 'tests', 'pure');
+    const harnessPaths = await ensureWorkspaceTraceHarness(workspaceRoot);
+    const moduleDir = harnessPaths.modulesDir;
+    await mkdir(testsDir, { recursive: true });
+    await mkdir(moduleDir, { recursive: true });
+    await mkdir(harnessPaths.pureFixturesDir, { recursive: true });
+    const written = [];
+    let autoAssertionCount = 0;
+    let stubCount = 0;
+    for (const info of classification.pureFunctions) {
+        const modulePath = path.join(moduleDir, `${sanitizeSymbolName(info.name)}.mjs`);
+        const moduleSource = buildStandaloneSymbolModule({
+            bindingName: info.bindingName,
+            bundle,
+            outputFilePath: modulePath,
+        });
+        if (!dryRun) {
+            await Bun.write(modulePath, `${moduleSource.trimEnd()}\n`);
+        }
+        const cases = dryRun ? [] : await loadFunctionCases({ info, modulePath });
+        autoAssertionCount += cases.length;
+        if (cases.length === 0) {
+            stubCount += 1;
+        }
+        const fixtureName = sanitizeSymbolName(info.name);
+        const fixturePath = path.join(harnessPaths.pureFixturesDir, `${fixtureName}.json`);
+        if (!dryRun) {
+            await Bun.write(fixturePath, `${JSON.stringify(cases, null, 2)}\n`);
+        }
+        const testFile = path.join(testsDir, `${sanitizeSymbolName(info.name)}.test.ts`);
+        const sourceText = renderTestSource({
+            fixtureName,
+            harnessPath: harnessPaths.harnessFile,
+            info,
+            modulePath,
+            testFile,
+        });
+        if (!dryRun) {
+            await Bun.write(testFile, sourceText);
+        }
+        written.push(testFile);
+    }
+    return {
+        autoAssertionCount,
+        pureFunctionCount: classification.pureFunctions.length,
+        stubCount,
+        totalTopLevelFunctions: classification.totalTopLevelFunctions,
+        written,
+    };
+};
+const recordPureToolingGap = async ({ body, summary, toolingGaps, workspaceDir, }) => {
+    toolingGaps.push(body);
+    await recordCharacterizeToolingGap({
+        body,
+        summary,
+        workspaceRoot: workspaceDir,
+    });
+};
+const resolvePureScaffoldUpdateMode = async ({ scaffold, sidecarScaffolds, }) => {
+    const trackedHash = sidecarScaffolds[scaffold.relativeTestPath];
+    if (trackedHash === undefined) {
+        return {
+            kind: 'gap',
+            result: {
+                body: `Cannot manage ${scaffold.relativeTestPath} because tests/.seed-fingerprints.json does not track it. Re-run \`ushman go --stage=seed\` for this workspace, or add the scaffold to the sidecar before retrying population.`,
+                summary: `untracked pure scaffold ${scaffold.relativeTestPath}`,
+            },
+        };
+    }
+    const currentSource = await Bun.file(scaffold.filePath).text();
+    const currentHash = hashSeedScaffoldContent(currentSource);
+    if (!isScaffoldUnmodified({
+        currentHash,
+        trackedHash,
+    })) {
+        return {
+            kind: 'skip',
+        };
+    }
+    return {
+        kind: 'populate',
+    };
+};
+const readPureScaffoldRecords = async ({ moduleTracePath, scaffold, }) => {
+    try {
+        return {
+            kind: 'records',
+            records: await readTraceRecords({
+                contextPrefix: `Trace record ${scaffold.moduleRelativePath}.jsonl`,
+                filePath: moduleTracePath,
+            }),
+        };
+    }
+    catch (error) {
+        return {
+            kind: 'gap',
+            result: {
+                body: `${error instanceof Error ? error.message : String(error)}\nRe-run \`ushman-characterize capture\` and then \`ushman-characterize stub-pure --regen-stale\` after regenerating stale traces.`,
+                summary: `invalid trace file for ${scaffold.relativeTestPath}`,
+            },
+        };
+    }
+};
+const buildPureScaffoldSymbolCases = ({ moduleTracePath, records, scaffold, }) => {
+    const symbolCases = new Map(scaffold.symbols.map((symbol) => [
+        symbol,
+        buildPureCases({
+            records,
+            symbol,
+        }),
+    ]));
+    const populatedCaseCount = [...symbolCases.values()].reduce((total, cases) => total + cases.length, 0);
+    if (populatedCaseCount === 0) {
+        return {
+            kind: 'gap',
+            result: {
+                body: `Missing trace cases for ${scaffold.relativeTestPath}. Trace file ${moduleTracePath} did not contain any records for ${scaffold.symbols.join(', ')}.\nRe-run \`ushman-characterize capture\` for the missing module coverage, or leave the operator-owned \`test.todo\` blocks in place until that symbol is exercised.`,
+                summary: `missing trace cases for ${scaffold.relativeTestPath}`,
+            },
+        };
+    }
+    return {
+        kind: 'cases',
+        symbolCases,
+    };
+};
+const populateSinglePureScaffold = async ({ harnessPath, legacyTraceIndex, ownershipMap, scaffold, sidecarScaffolds, workspaceDir, }) => {
+    const updateMode = await resolvePureScaffoldUpdateMode({
+        scaffold,
+        sidecarScaffolds,
+    });
+    if (updateMode.kind === 'gap') {
+        return {
+            toolingGap: updateMode.result,
+        };
+    }
+    if (updateMode.kind === 'skip') {
+        return {
+            skippedFilePath: scaffold.filePath,
+        };
+    }
+    const moduleTracePath = await resolveModuleTracePath({
+        legacyTraceIndex,
+        ownershipMap,
+        scaffold,
+        workspaceDir,
+    });
+    if (moduleTracePath.kind === 'gap') {
+        return {
+            toolingGap: moduleTracePath.result,
+        };
+    }
+    if (moduleTracePath.kind === 'missing' || !(await Bun.file(moduleTracePath.moduleTracePath).exists())) {
+        return {
+            toolingGap: {
+                body: `Missing trace for ${scaffold.relativeTestPath}. Expected ${buildPureModuleTracePath({
+                    moduleRelativePath: scaffold.moduleRelativePath,
+                    workspaceDir,
+                })}. Capture the module trace before re-running populateScaffolds.`,
+                summary: `missing trace for ${scaffold.relativeTestPath}`,
+            },
+        };
+    }
+    const recordsResult = await readPureScaffoldRecords({
+        moduleTracePath: moduleTracePath.moduleTracePath,
+        scaffold,
+    });
+    if (recordsResult.kind === 'gap') {
+        return {
+            toolingGap: recordsResult.result,
+        };
+    }
+    const casesResult = buildPureScaffoldSymbolCases({
+        moduleTracePath: moduleTracePath.moduleTracePath,
+        records: recordsResult.records,
+        scaffold,
+    });
+    if (casesResult.kind === 'gap') {
+        return {
+            toolingGap: casesResult.result,
+        };
+    }
+    const nextSource = renderPopulatedPureTestSource({
+        harnessPath,
+        scaffold,
+        symbolCases: casesResult.symbolCases,
+    });
+    await atomicWriteText(scaffold.filePath, `${nextSource.endsWith('\n') ? nextSource : `${nextSource}\n`}`);
+    return {
+        fingerprintEntry: [scaffold.relativeTestPath, hashSeedScaffoldContent(nextSource)],
+        synthesizedTracePath: moduleTracePath.synthesized ? moduleTracePath.moduleTracePath : undefined,
+        writtenFilePath: scaffold.filePath,
+    };
+};
+const recordPurePreflightFailures = async ({ legacyTraceIndex, parseFailures, toolingGaps, workspaceDir, }) => {
+    for (const failure of parseFailures) {
+        await recordCharacterizeToolingGap({
+            body: `${failure.message}\nFix the scaffold syntax or rerun \`ushman go --stage=seed\` to restore the managed scaffold before retrying population.`,
+            summary: `invalid pure scaffold ${toWorkspaceRelativePath({
+                filePath: failure.filePath,
+                workspaceDir,
+            })}`,
+            workspaceRoot: workspaceDir,
+        });
+    }
+    for (const failure of legacyTraceIndex.parseFailures) {
+        await recordCharacterizeToolingGap({
+            body: `${failure}\nRe-run \`ushman-characterize capture\` to refresh the malformed state trace before retrying legacy synthesis.`,
+            summary: 'invalid legacy state trace',
+            workspaceRoot: workspaceDir,
+        });
+    }
+    toolingGaps.push(...parseFailures.map((failure) => failure.message), ...legacyTraceIndex.parseFailures);
+};
+const applyPureScaffoldProcessingResult = async ({ nextFingerprints, result, skipped, synthesizedTraces, toolingGaps, workspaceDir, written, }) => {
+    if (result.toolingGap) {
+        await recordPureToolingGap({
+            body: result.toolingGap.body,
+            summary: result.toolingGap.summary,
+            toolingGaps,
+            workspaceDir,
+        });
+    }
+    if (result.skippedFilePath) {
+        skipped.push(result.skippedFilePath);
+    }
+    if (result.synthesizedTracePath) {
+        synthesizedTraces.push(result.synthesizedTracePath);
+    }
+    if (result.writtenFilePath) {
+        written.push(result.writtenFilePath);
+    }
+    if (result.fingerprintEntry) {
+        nextFingerprints[result.fingerprintEntry[0]] = result.fingerprintEntry[1];
+    }
+};
+export const populateScaffolds = async ({ modulePathPrefix, symbolFilter, workspaceDir, }) => {
+    await assertV4Workspace(workspaceDir);
+    const harnessPaths = await ensureWorkspaceTraceHarness(workspaceDir);
+    const sidecar = await loadSeedFingerprintSidecar(workspaceDir);
+    const { parseFailures, scaffolds } = await collectManagedPureScaffolds(workspaceDir);
+    const ownershipMap = buildSymbolOwnershipMap(scaffolds);
+    const legacyTraceIndex = await indexLegacyStateTraceRecords(workspaceDir);
+    const nextFingerprints = {};
+    const skipped = [];
+    const synthesizedTraces = [];
+    const toolingGaps = [];
+    const written = [];
+    await recordPurePreflightFailures({
+        legacyTraceIndex,
+        parseFailures,
+        toolingGaps,
+        workspaceDir,
+    });
+    for (const scaffold of scaffolds) {
+        if (!matchesPopulateFilters({
+            modulePathPrefix,
+            scaffold,
+            symbolFilter,
+        })) {
+            continue;
+        }
+        const result = await populateSinglePureScaffold({
+            harnessPath: harnessPaths.harnessFile,
+            legacyTraceIndex,
+            ownershipMap,
+            scaffold,
+            sidecarScaffolds: sidecar.scaffolds,
+            workspaceDir,
+        });
+        await applyPureScaffoldProcessingResult({
+            nextFingerprints,
+            result,
+            skipped,
+            synthesizedTraces,
+            toolingGaps,
+            workspaceDir,
+            written,
+        });
+    }
+    const affectedFiles = [...written, ...synthesizedTraces].map((filePath) => toWorkspaceRelativePath({
+        filePath,
+        workspaceDir,
+    }));
+    const sidecarPath = Object.keys(nextFingerprints).length > 0
+        ? await updateSeedFingerprintSidecar({
+            entries: nextFingerprints,
+            workspaceDir,
+        })
+        : sidecar.filePath;
+    await recordCharacterizeValidatorResult({
+        affectedFiles,
+        metrics: {
+            skippedCount: skipped.length,
+            synthesizedTraceCount: synthesizedTraces.length,
+            toolingGapCount: toolingGaps.length,
+            writtenCount: written.length,
+        },
+        summary: summarizePopulateScaffolds({
+            skipped,
+            toolingGaps,
+            written,
+        }),
+        verdict: toolingGaps.length > 0 ? 'yellow' : 'green',
+        workspaceRoot: workspaceDir,
+    });
+    return {
+        sidecarPath,
+        skipped,
+        synthesizedTraces,
+        toolingGaps,
+        written,
+    };
+};
+export const __testOnly = {
+    buildCandidateArgs,
+    executeSampleSafely,
+    hasDetachedTextureLoadHazard,
+    inferKind,
+    isCaseRenderable,
+    loadFunctionCases,
+    renderLiteral,
+    settlePromiseSample,
+};