@aiwg/cli 2026.10.1 → 2026.10.4

package/dist/src/artifacts/corpus-tools/vision-extract.js

@@ -21,6 +21,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
+import { boundedSpawnSync, positiveTimeoutMs } from '../../process/bounded-child-process.mjs';
 /** Strict-transcription prompt. `title` parameterizes the corpus-specific intro. */
 export function buildPrompt(page, title) {
     const subject = title ? `from ${title}` : 'from a scanned document';
@@ -53,8 +54,13 @@ const codexAdapter = {
         try {
             const r = spawnSync(process.env.AIWG_CODEX_BIN || 'codex', args, {
                 input: prompt,
-                timeout: ctx.timeoutSec * 1000,
+                // ctx.timeoutSec is caller-controlled (a CLI flag); clamp it so a
+                // configured 0 (or anything else non-positive) can't disable the
+                // bound entirely (#3062 B/C finding 8). 240s matches this
+                // function's own documented default (see extractPages() below).
+                timeout: positiveTimeoutMs(ctx.timeoutSec * 1000, 240_000),
                 encoding: 'utf8',
+                killSignal: 'SIGKILL',
             });
             if (r.status === 0 && fs.existsSync(tmp)) {
                 const text = fs.readFileSync(tmp, 'utf8');
@@ -70,15 +76,93 @@ const codexAdapter = {
         }
     },
 };
+/** Paths enter the shell as positional arguments, never as shell source. */
+const MAX_VISION_TEMPLATE_LENGTH = 4096;
+function visionCommand(template) {
+    const guidance = 'Use "$1"/"$2"/"$3" as data operands or move complex logic to a wrapper script';
+    const reject = (construct) => {
+        throw new Error(`Vision command rejects ${construct}. ${guidance}`);
+    };
+    // Bound the checks below; a vision command template is a short command line.
+    if (template.length > MAX_VISION_TEMPLATE_LENGTH)
+        reject(`templates longer than ${MAX_VISION_TEMPLATE_LENGTH} characters`);
+    // A vision template is one command line; a backslash-newline continuation can
+    // join an allowed name with following text into a different variable at runtime.
+    if (/\\\r?\n|\\\r/.test(template))
+        reject('line continuations (backslash-newline)');
+    // Recognize literal command names even when quoted or backslash-escaped.
+    const syntax = template.replace(/\\([^\n])/g, '$1').replace(/["']/g, '');
+    if (syntax.includes('$('))
+        reject('command substitution ($(...))');
+    if (template.includes('`'))
+        reject('backticks');
+    if (/\beval\b/.test(syntax))
+        reject('eval');
+    if (syntax.includes('<<'))
+        reject('here-documents and here-strings (<<)');
+    // Conservatively reject a shell word together with any short -c option
+    // cluster, regardless of order, wrappers, redirections or command boundaries.
+    const words = syntax.split(/[\s;&|(){}<>]+/);
+    const shellWords = words.map(word => word.slice(word.lastIndexOf('/') + 1)
+        .match(/^(?:sh|bash|zsh|dash|ksh|ash|mksh|yash|fish|csh|tcsh|rbash|busybox|toybox)(?:$|(-[A-Za-z]*c))/));
+    const hasShell = shellWords.some(Boolean);
+    if (shellWords.some(word => word?.[1]) || (hasShell && words.some(word => /^-[A-Za-z]*c/.test(word))))
+        reject('nested shell invocation (-c)');
+    // Only contract-provided parameters may expand; match at each dollar without
+    // rescanning the remaining template. Braces must contain only the exact name.
+    const parameter = /\$(?:[123](?![0-9])|AIWG_VISION_(?:IMAGE|PROMPT_FILE|OUT)(?![A-Za-z0-9_])|\{(?:[123]|AIWG_VISION_(?:IMAGE|PROMPT_FILE|OUT))\})/y;
+    // Track quotes to reject quoted/escaped placeholders, expansions and comments.
+    let quote = '';
+    return template.replace(/\\?\{(image|prompt_file|out)\}|\\[\s\S]|\$'|[$"'#]/g, (token, name, offset) => {
+        if ((token === '#' || token === '\\#') && quote !== "'")
+            reject('comments (# outside single quotes)');
+        if (name) {
+            if (quote)
+                throw new Error(`Vision command placeholders must be outside shell quotes. ${guidance}`);
+            if (token.startsWith('\\'))
+                throw new Error(`Vision command placeholders must not be escaped. ${guidance}`);
+            return `"$${name === 'image' ? 1 : name === 'prompt_file' ? 2 : 3}"`;
+        }
+        if (token === '#')
+            return token;
+        // Backslashes are literal inside POSIX single quotes, but escape the next
+        // character in double quotes and ANSI-C ($'...') quotes.
+        if (token.startsWith('\\')) {
+            if (quote === "'" && token[1] === "'")
+                quote = '';
+            return token;
+        }
+        if (token.startsWith('$')) {
+            if (quote !== "'") {
+                parameter.lastIndex = offset;
+                if (!parameter.test(template))
+                    reject('parameter expansions other than the provided vision variables');
+            }
+            if (token === '$')
+                return token;
+        }
+        if (!quote)
+            quote = token;
+        else if (quote === token || (quote === "$'" && token === "'") || (quote === "'" && token === "$'"))
+            quote = '';
+        return token;
+    });
+}
 /**
  * Generic command-template adapter (provider-neutral). Runs
  * `AIWG_VISION_COMMAND` (or the `--command` flag) with placeholders:
- *   {image}        absolute image path
- *   {prompt_file}  path to a file containing the prompt
- *   {out}          path the command must write the transcription to
- * e.g.  claude -p "$(cat {prompt_file})" --image {image} > {out}
+ *   {image}        "$1": absolute image path
+ *   {prompt_file}  "$2": path to a file containing the prompt
+ *   {out}          "$3": path the command must write the transcription to
+ * Placeholders must be unquoted and unescaped. AIWG_VISION_IMAGE /
+ * AIWG_VISION_PROMPT_FILE / AIWG_VISION_OUT are also exported.
+ * Only $1/$2/$3 and the exported vision variables (also braced) may expand.
+ * Other $ expansions, command substitution, backticks, eval, nested shells with -c, <<, and #
+ * outside single quotes are rejected; use a wrapper script for complex logic.
+ * e.g.  vision-cli --prompt-file {prompt_file} --image {image} > {out}
  */
 function commandAdapter(template) {
+    const cmd = visionCommand(template);
     return {
         name: 'command',
         transcribe(imagePath, prompt, ctx) {
@@ -86,12 +170,13 @@ function commandAdapter(template) {
             const promptFile = path.join(dir, `.vision-prompt-${ctx.page}.txt`);
             const out = path.join(dir, `.vision-out-${ctx.page}.txt`);
             fs.writeFileSync(promptFile, prompt);
-            const cmd = template
-                .replaceAll('{image}', JSON.stringify(imagePath))
-                .replaceAll('{prompt_file}', JSON.stringify(promptFile))
-                .replaceAll('{out}', JSON.stringify(out));
             try {
-                const r = spawnSync('sh', ['-c', cmd], { timeout: ctx.timeoutSec * 1000, encoding: 'utf8' });
+                // Same caller-controlled-timeout clamp as the codex adapter above.
+                const r = spawnSync('sh', ['-c', cmd, 'aiwg-vision', imagePath, promptFile, out], {
+                    timeout: positiveTimeoutMs(ctx.timeoutSec * 1000, 240_000), encoding: 'utf8',
+                    env: { ...process.env, AIWG_VISION_IMAGE: imagePath, AIWG_VISION_PROMPT_FILE: promptFile, AIWG_VISION_OUT: out },
+                    killSignal: 'SIGKILL',
+                });
                 let text;
                 if (fs.existsSync(out))
                     text = fs.readFileSync(out, 'utf8');
@@ -115,7 +200,7 @@ export function resolveAdapter(opts = {}) {
     const provider = opts.provider ?? process.env.AIWG_VISION_PROVIDER ?? (command ? 'command' : 'codex');
     if (provider === 'command') {
         if (!command)
-            throw new Error("vision provider 'command' requires --command or AIWG_VISION_COMMAND (template with {image}/{prompt_file}/{out})");
+            throw new Error("vision provider 'command' requires --command or AIWG_VISION_COMMAND (template with unquoted, unescaped {image}/{prompt_file}/{out} placeholders)");
         return commandAdapter(command);
     }
     if (provider === 'codex')
@@ -125,7 +210,8 @@ export function resolveAdapter(opts = {}) {
 // ── PDF → PNG rasterization (poppler pdftoppm) ───────────────────────────────
 export function pdftoppmAvailable() {
     try {
-        return spawnSync('pdftoppm', ['-v'], { encoding: 'utf8' }).status === 0 || spawnSync('pdftoppm', ['-h'], { encoding: 'utf8' }).status !== null;
+        return boundedSpawnSync('pdftoppm', ['-v'], 'quick', { encoding: 'utf8' }).status === 0
+            || boundedSpawnSync('pdftoppm', ['-h'], 'quick', { encoding: 'utf8' }).status !== null;
     }
     catch {
         return false;
@@ -144,9 +230,15 @@ export function rasterizePdf(pdfPath, outDir, dpi = 200) {
     fs.mkdirSync(outDir, { recursive: true });
     // pdftoppm writes <prefix>-<n>.png with its own zero-padding based on page count.
     const prefix = path.join(outDir, 'page');
-    const r = spawnSync('pdftoppm', ['-png', '-r', String(dpi), pdfPath, prefix], { encoding: 'utf8' });
-    if (r.status !== 0)
-        throw new Error(`pdftoppm failed: ${r.stderr || r.status}`);
+    // Rasterizing a multi-page PDF can take a while; long tier (#3062).
+    const r = boundedSpawnSync('pdftoppm', ['-png', '-r', String(dpi), pdfPath, prefix], 'long', { encoding: 'utf8' });
+    if (r.status !== 0) {
+        // #3062 finding 14: r.error.message (when present) carries the
+        // enriched timeout explanation (tier/bound/override) that stderr/
+        // status alone do not — put it first, captured stderr after.
+        const detail = r.error ? r.error.message : `pdftoppm failed: ${r.stderr || r.status}`;
+        throw new Error(r.error && r.stderr ? `${detail} (stderr: ${r.stderr})` : detail);
+    }
     // Normalize names to page-NNN.png (3-digit zero-pad).
     let count = 0;
     for (const f of fs.readdirSync(outDir)) {

package/dist/src/artifacts/corpus-views/ref-parser.js

@@ -326,11 +326,13 @@ export function loadCorpus(root) {
         const venue = classifyFirst(`${venueRaw ?? ''} ${text.slice(0, 3500)}`.toLowerCase(), VENUE_PATTERNS) ||
             (venueRaw ? String(venueRaw).trim() : null);
         const { tier, paramsM } = extractParams(text);
+        const radar = extractRadar(root, refId);
         records.push({
             refId,
             sourceType: normalizeSourceType({ type: asStr(fm.type), sourceType: asStr(fm.source_type), venue }, srcTypeReg),
             referencedByProjects: extractReferencedByProjects(text),
             title: extractTitle(text, fm),
+            grade: radar?.gradeCurrent ?? asStr(fm.grade),
             path: filePath,
             year: extractYear(text, fm, citation),
             authors,
@@ -343,7 +345,7 @@ export function loadCorpus(root) {
             paramsM,
             incoming,
             outgoing,
-            radar: extractRadar(root, refId),
+            radar,
             discovery: extractDiscovery(citation),
             funders: extractFunders(citation),
         });

package/dist/src/artifacts/corpus-views/renderers.js

@@ -242,9 +242,9 @@ function renderPipeline(ctx) {
 // Cadence → window math lives in corpus-config.ts (the one staleness helper, #1498/#1502).
 /** GRADE display order; unknown grades fall after, 'Ungraded' last. */
 const GRADE_ORDER = ['A', 'A-', 'B', 'B-', 'C', 'C-', 'D'];
-/** Papers grouped by current GRADE (radar `grade-current`); no-radar → Ungraded. (#1492) */
+/** Papers grouped by current GRADE, falling back to reference frontmatter. */
 function renderByGrade(ctx) {
-    const groups = groupBy(ctx.records, (r) => [r.radar?.gradeCurrent || 'Ungraded']);
+    const groups = groupBy(ctx.records, (r) => [r.grade || 'Ungraded']);
     const lines = header('Index: Papers by GRADE', ctx, ctx.records.length);
     const names = [...groups.keys()].sort((a, b) => {
         if (a === 'Ungraded')
@@ -284,7 +284,7 @@ function renderStaleQueue(ctx) {
     const lines = header('Index: Radar Stale-Refresh Queue', ctx, ctx.records.length);
     lines.push(`Overdue = days since last refresh minus the cadence window. ${staleCount} of ${rows.length} radar-tracked papers are overdue.`, '', '| REF | Title | GRADE | Cadence | Last Refreshed | Overdue (days) | Stale |', '|---|---|---|---|---|---:|---|');
     for (const { r, cadence, last, overdue } of sorted) {
-        lines.push(`| ${r.refId} | ${r.title.slice(0, 70)} | ${r.radar.gradeCurrent ?? '—'} | ${cadence} | ${last} | ${overdue} | ${overdue > 0 ? 'yes' : 'no'} |`);
+        lines.push(`| ${r.refId} | ${r.title.slice(0, 70)} | ${r.grade ?? '—'} | ${cadence} | ${last} | ${overdue} | ${overdue > 0 ? 'yes' : 'no'} |`);
     }
     return lines.join('\n') + '\n';
 }

package/dist/src/artifacts/discovery-eval.js

@@ -2,7 +2,8 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
-import { OPERATIONAL_DISCOVERY_TYPES } from './types.js';
+import { getGraphIndexDir, OPERATIONAL_DISCOVERY_TYPES } from './types.js';
+import { getFrameworkIndexBaseDir } from './framework-index-paths.js';
 import { loadGraphIndexFile } from './index-reader.js';
 import { loadFortemiCoreExport, loadFortemiCoreMetadataEntries, scoreStaticRecord } from './fortemi-core-query-adapter.js';
 import { discoverCapability } from './query-engine.js';
@@ -185,8 +186,9 @@ export function calculateDiscoveryMetrics(records, resultSets) {
             .some((item) => record.hard_negative_ids.some((id) => matches(item, id)))).length / records.length),
     };
 }
-function indexBytes(backend) {
-    const root = path.join(process.env.XDG_DATA_HOME ?? path.join(os.homedir(), '.local', 'share'), 'aiwg', 'index', ...(backend === 'local' ? ['framework'] : ['fortemi-core', 'framework']));
+function indexBytes(cwd, backend) {
+    const root = backend === 'local' ? getGraphIndexDir(cwd, 'framework')
+        : path.join(getFrameworkIndexBaseDir(cwd), 'fortemi-core', 'framework');
     let total = 0;
     const visit = (target) => {
         if (!fs.existsSync(target))
@@ -259,7 +261,7 @@ export async function evaluateDiscovery(options) {
         configuration: { backend: options.backend, strategy: options.strategy, limit, graph: 'framework' },
         hardware: { platform: os.platform(), arch: os.arch(), cpu_model: cpus[0]?.model ?? 'unknown', logical_cpus: cpus.length, total_memory_bytes: os.totalmem(), node: process.version },
         metrics,
-        performance: { p50_latency_ms: round(percentile(latencies, 0.5), 3), p95_latency_ms: round(percentile(latencies, 0.95), 3), index_bytes: indexBytes(options.backend), peak_resident_memory_bytes: peakRss },
+        performance: { p50_latency_ms: round(percentile(latencies, 0.5), 3), p95_latency_ms: round(percentile(latencies, 0.95), 3), index_bytes: indexBytes(options.cwd, options.backend), peak_resident_memory_bytes: peakRss },
         ...(parity ? { parity } : {}),
         adoption_gate: {
             baseline: 'local:lexical', no_per_type_hit_at_3_regression: null, aggregate_mrr_improvement: null,

package/dist/src/artifacts/fortemi-core-query-adapter.js

@@ -1,7 +1,11 @@
+import { selectPrebuiltRelations } from './relations.js';
+import { resolveFrameworkIndexRoot } from './framework-index-paths.js';
+import { extractRuleBindings } from './index-builder.js';
 import fs from "node:fs";
 import { createHash } from "node:crypto";
 import { bm25Rank } from "./fulltext.js";
-import { getFortemiCorePrebuiltStatus, getFortemiCoreSyncStatus } from "./fortemi-core-sync.js";
+import { consumeFortemiCoreExport, getFortemiCorePrebuiltStatus, getFortemiCoreSyncStatus } from "./fortemi-core-sync.js";
+import { loadGraphIndexFile } from "./index-reader.js";
 import { operationalStateQueryProjection, } from "./operational-state.js";
 function tokenize(text) {
     return text
@@ -167,6 +171,14 @@ export function loadFortemiCoreExport(cwd, graph = "project", sourcePaths) {
             };
         }
     }
+    // A content-validated shipped corpus does not need the source metadata index.
+    // This also avoids preferring a much larger locally materialized text cache.
+    if (graph === 'framework' && selectPrebuiltRelations(cwd).reader) {
+        const prebuilt = getFortemiCorePrebuiltStatus(graph, resolveFrameworkIndexRoot(cwd));
+        if (prebuilt.built && !prebuilt.stale) {
+            return { exported: JSON.parse(fs.readFileSync(prebuilt.exportPath, 'utf8')) };
+        }
+    }
     let status = getFortemiCoreSyncStatus(cwd, graph);
     // The packaged framework index is a bootstrap fallback for an absent shared
     // cache. Once a shared cache exists, its stale state proves that the local
@@ -178,6 +190,20 @@ export function loadFortemiCoreExport(cwd, graph = "project", sourcePaths) {
             status = prebuilt;
         }
     }
+    // A packaged bootstrap cache can also predate a source checkout's index.
+    // Validate it against the same current data as the shared cache before use.
+    if (status.source === "prebuilt") {
+        const current = loadGraphIndexFile(cwd, "metadata.json", graph);
+        if (current &&
+            Date.parse(current.builtAt) > Date.parse(status.sourceIndexBuiltAt ?? status.generatedAt ?? "")) {
+            status = {
+                ...status,
+                stale: true,
+                sourceIndexNewer: true,
+                reason: "source index is newer than the Fortemi Core static cache",
+            };
+        }
+    }
     if (!status.optedIn) {
         return {
             reason: `Fortemi Core static index is not materialized for graph '${graph}'. Run 'aiwg index sync${graph === "project" ? "" : ` --graph ${graph}`}' first, or pass '--backend local' to use the legacy local index.`,
@@ -185,12 +211,13 @@ export function loadFortemiCoreExport(cwd, graph = "project", sourcePaths) {
     }
     if (!status.built || status.stale) {
         return {
+            ...(status.sourceIndexNewer ? { sourceIndexNewer: true } : {}),
             reason: `${status.reason ??
                 `Fortemi Core static index for graph '${graph}' is stale or incomplete`}. Re-run 'aiwg index sync${graph === "project" ? "" : ` --graph ${graph}`}' or pass '--backend local' to use the legacy local index.`,
         };
     }
     try {
-        const exported = JSON.parse(fs.readFileSync(status.exportPath, "utf-8"));
+        const exported = consumeFortemiCoreExport(status.exportPath, status.exportChecksum);
         if (exported.schema_version !== "aiwg.fortemi.index.export.v2") {
             return {
                 reason: `Fortemi Core static index has schema '${exported.schema_version}', expected 'aiwg.fortemi.index.export.v2'. Re-run 'aiwg index sync'.`,
@@ -255,13 +282,19 @@ function entryFromRecord(record) {
             && typeof indexedScript.runtime === "string"
             ? indexedScript
             : undefined,
+        ...extractRuleBindings(indexedFrontmatter),
+        ...(Array.isArray(indexedFrontmatter.aiwg_governed_paths) ? { governedPaths: indexedFrontmatter.aiwg_governed_paths.filter((value) => typeof value === "string") } : {}),
         operationalState: record.operational_state,
     };
 }
 export function loadFortemiCoreMetadataEntries(cwd, graph = "project", sourcePaths) {
     const loaded = loadFortemiCoreExport(cwd, graph, sourcePaths);
     if (!loaded.exported)
-        return { entries: [], reason: loaded.reason };
+        return {
+            entries: [],
+            reason: loaded.reason,
+            ...(loaded.sourceIndexNewer ? { sourceIndexNewer: true } : {}),
+        };
     return { entries: loaded.exported.items.map(entryFromRecord) };
 }
 export async function queryFortemiCoreAiwgDiscovery(cwd, options) {

package/dist/src/artifacts/fortemi-core-sync.js

@@ -1,15 +1,18 @@
 import fs from "node:fs";
 import path from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { parse as parseYaml } from "yaml";
 import { GRAPH_CONFIGS, getProjectIndexRoot, loadGlobalGraphConfigs } from "./types.js";
 import { buildAiwgFortemiIndexExport, } from "./browser-export.js";
 import { loadGraphIndexFile } from "./index-reader.js";
+import { getFrameworkIndexBaseDir } from './framework-index-paths.js';
 function syncDir(cwd, graph) {
     loadGlobalGraphConfigs();
+    if (graph === 'framework')
+        return path.join(getFrameworkIndexBaseDir(cwd), 'fortemi-core', graph);
     const config = GRAPH_CONFIGS[graph];
-    if (graph === "framework" || config?.shared) {
+    if (config?.shared) {
         const xdgData = process.env.XDG_DATA_HOME ?? path.join(process.env.HOME ?? cwd, ".local", "share");
         return path.join(xdgData, "aiwg", "index", "fortemi-core", graph);
     }
@@ -36,6 +39,47 @@ function prebuiltDir(graph) {
 function sha256(text) {
     return createHash("sha256").update(text).digest("hex");
 }
+// Status checks and the query reader often inspect the same large export.
+// Keep at most two private snapshots, and never retain an object exposed to a
+// caller: query results have always been fresh, mutable objects.
+const exportSnapshots = new Map();
+function exportSignature(file) {
+    const stat = fs.statSync(file, { bigint: true });
+    return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
+}
+function readExportSnapshot(file, expectedChecksum) {
+    const signature = exportSignature(file);
+    const cached = exportSnapshots.get(file);
+    // The manifest checksum is part of the snapshot identity. Filesystems may
+    // preserve every stat field across a same-size rewrite within one timestamp
+    // tick, while the manifest already names the replacement's checksum.
+    if (cached?.signature === signature &&
+        cached.checksum === expectedChecksum)
+        return cached;
+    exportSnapshots.delete(file);
+    const text = fs.readFileSync(file, "utf-8");
+    const exported = JSON.parse(text);
+    const snapshot = { signature, exported, checksum: sha256(text) };
+    // A concurrent replacement cannot publish a snapshot under the wrong stamp.
+    if (exportSignature(file) === signature) {
+        exportSnapshots.set(file, snapshot);
+        while (exportSnapshots.size > 2)
+            exportSnapshots.delete(exportSnapshots.keys().next().value);
+    }
+    return snapshot;
+}
+/** Transfer a checked snapshot to the query reader without sharing mutable results. */
+export function consumeFortemiCoreExport(file, expectedChecksum) {
+    try {
+        const snapshot = readExportSnapshot(file, expectedChecksum);
+        if (snapshot.checksum !== expectedChecksum)
+            throw new Error("export checksum does not match manifest");
+        return snapshot.exported;
+    }
+    finally {
+        exportSnapshots.delete(file);
+    }
+}
 function readManifest(manifestPath) {
     return readManifestResult(manifestPath).manifest;
 }
@@ -59,11 +103,91 @@ function sourceIndexBuiltAt(cwd, graph) {
     const index = loadGraphIndexFile(cwd, "metadata.json", graph);
     return typeof index?.builtAt === "string" ? index.builtAt : null;
 }
+/**
+ * Emit the v2 JSON document without stringifying a collection or a whole record.
+ * Strings are escaped in bounded slices too: a single large text field must not
+ * reintroduce V8's string limit. Preserve pretty-print bytes for stable checksums.
+ */
+function* jsonTokens(value, maxChars, depth = 0, ancestors = new Set()) {
+    if (value && typeof value === "object" && "toJSON" in value && typeof value.toJSON === "function") {
+        value = value.toJSON();
+    }
+    if (typeof value === "string") {
+        yield '"';
+        const sliceChars = Math.floor(maxChars / 6); // A control character can expand to \uXXXX.
+        for (let start = 0; start < value.length;) {
+            let end = Math.min(start + sliceChars, value.length);
+            // Keep surrogate pairs together, including when UTF-8 encoding each write.
+            if (end < value.length && /[\uD800-\uDBFF]/.test(value[end - 1]) && /[\uDC00-\uDFFF]/.test(value[end]))
+                end--;
+            yield JSON.stringify(value.slice(start, end)).slice(1, -1);
+            start = end;
+        }
+        yield '"';
+    }
+    else if (value && typeof value === "object") {
+        if (ancestors.has(value))
+            throw new TypeError("Converting circular structure to JSON");
+        ancestors.add(value);
+        const array = Array.isArray(value);
+        const entries = Array.isArray(value) ? value.map((item, index) => [String(index), item])
+            : Object.entries(value).filter(([, item]) => item !== undefined && typeof item !== "function" && typeof item !== "symbol");
+        yield array ? "[" : "{";
+        for (let i = 0; i < entries.length; i++) {
+            yield (i === 0 ? "\n" : ",\n") + "  ".repeat(depth + 1);
+            const [key, item] = entries[i];
+            if (!array) {
+                yield* jsonTokens(key, maxChars, depth + 1, ancestors);
+                yield ": ";
+            }
+            yield* jsonTokens(item, maxChars, depth + 1, ancestors);
+        }
+        if (entries.length)
+            yield "\n" + "  ".repeat(depth);
+        yield array ? "]" : "}";
+        ancestors.delete(value);
+    }
+    else {
+        yield JSON.stringify(value) ?? "null";
+    }
+}
+/** Write and hash the same bounded chunks; publish only complete exports. */
+function writeExport(file, exported, maxChars) {
+    const hash = createHash("sha256");
+    const fd = fs.openSync(file, "w");
+    try {
+        const flush = (chunk) => {
+            const bytes = Buffer.from(chunk, "utf-8");
+            hash.update(bytes);
+            for (let offset = 0; offset < bytes.length;)
+                offset += fs.writeSync(fd, bytes, offset, bytes.length - offset);
+        };
+        let pending = "";
+        for (const token of jsonTokens(exported, maxChars)) {
+            if (pending.length + token.length > maxChars) {
+                flush(pending);
+                pending = "";
+            }
+            pending += token;
+        }
+        flush(pending);
+        flush("\n");
+        return hash.digest("hex");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 export function syncFortemiCoreIndex(cwd, options = {}) {
     const graph = options.graph ?? "project";
     const dir = syncDir(cwd, graph);
     const exportPath = path.join(dir, "aiwg-fortemi-index-v2.json");
     const manifestPath = path.join(dir, "manifest.json");
+    const maxChars = options.maxChunkChars ?? 64 * 1024;
+    if (!Number.isSafeInteger(maxChars) || maxChars < 64)
+        throw new Error("maxChunkChars must be an integer of at least 64");
+    fs.mkdirSync(dir, { recursive: true });
+    const temporaryPath = path.join(dir, `.export-${randomUUID()}.tmp`);
     const previous = readManifest(manifestPath);
     const sourceBuiltAt = sourceIndexBuiltAt(cwd, graph);
     const buildExport = (generatedAt) => {
@@ -74,12 +198,11 @@ export function syncFortemiCoreIndex(cwd, options = {}) {
             generatedAt,
             schemaVersion: "v2",
         });
-        const json = JSON.stringify(exported, null, 2) + "\n";
+        const checksum = writeExport(temporaryPath, exported, maxChars);
         const recordsWithConcepts = exported.items.filter((item) => (item.skos_concepts?.length ?? 0) > 0).length;
         return {
             generatedAt,
-            json,
-            checksum: sha256(json),
+            checksum,
             itemCount: exported.items.length,
             skosCoverage: {
                 records_with_concepts: recordsWithConcepts,
@@ -91,36 +214,40 @@ export function syncFortemiCoreIndex(cwd, options = {}) {
             },
         };
     };
-    let built = buildExport(options.generatedAt ?? previous?.generated_at ?? new Date().toISOString());
-    let status = "created";
-    if (previous) {
-        if (previous.export_checksum === built.checksum) {
-            status = "unchanged";
-        }
-        else {
-            status = "updated";
-            if (options.generatedAt === undefined) {
-                built = buildExport(new Date().toISOString());
+    try {
+        let built = buildExport(options.generatedAt ?? previous?.generated_at ?? new Date().toISOString());
+        let status = "created";
+        if (previous) {
+            if (previous.export_checksum === built.checksum) {
+                status = "unchanged";
+            }
+            else {
+                status = "updated";
+                if (options.generatedAt === undefined) {
+                    built = buildExport(new Date().toISOString());
+                }
             }
         }
+        fs.renameSync(temporaryPath, exportPath);
+        const manifest = {
+            schema_version: "aiwg.fortemi.core-sync.v1",
+            backend: "fortemi-core",
+            graph,
+            generated_at: built.generatedAt,
+            export_path: path.relative(cwd, exportPath),
+            export_schema_version: "aiwg.fortemi.index.export.v2",
+            export_checksum: built.checksum,
+            item_count: built.itemCount,
+            skos_coverage: built.skosCoverage,
+            status,
+            source_index_built_at: sourceBuiltAt,
+        };
+        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+        return manifest;
+    }
+    finally {
+        fs.rmSync(temporaryPath, { force: true });
     }
-    fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(exportPath, built.json, "utf-8");
-    const manifest = {
-        schema_version: "aiwg.fortemi.core-sync.v1",
-        backend: "fortemi-core",
-        graph,
-        generated_at: built.generatedAt,
-        export_path: path.relative(cwd, exportPath),
-        export_schema_version: "aiwg.fortemi.index.export.v2",
-        export_checksum: built.checksum,
-        item_count: built.itemCount,
-        skos_coverage: built.skosCoverage,
-        status,
-        source_index_built_at: sourceBuiltAt,
-    };
-    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
-    return manifest;
 }
 export function getFortemiCoreSyncStatus(cwd, graph = "project") {
     const dir = syncDir(cwd, graph);
@@ -149,9 +276,8 @@ export function getFortemiCoreSyncStatus(cwd, graph = "project") {
     let exportChecksumMatches = false;
     if (exportExists) {
         try {
-            const exportText = fs.readFileSync(exportPath, "utf-8");
-            const exported = JSON.parse(exportText);
-            exportChecksumMatches = sha256(exportText) === manifest.export_checksum;
+            const { exported, checksum } = readExportSnapshot(exportPath, manifest.export_checksum);
+            exportChecksumMatches = checksum === manifest.export_checksum;
             if (exportChecksumMatches) {
                 if (exported.schema_version !== manifest.export_schema_version) {
                     exportReadReason = `export schema '${exported.schema_version}' does not match manifest '${manifest.export_schema_version}'`;
@@ -182,6 +308,7 @@ export function getFortemiCoreSyncStatus(cwd, graph = "project") {
         exportPath,
         built: exportExists,
         stale,
+        ...(sourceIsNewer ? { sourceIndexNewer: true } : {}),
         itemCount: manifest.item_count,
         exportChecksum: manifest.export_checksum,
         generatedAt: manifest.generated_at,
@@ -195,8 +322,8 @@ export function getFortemiCoreSyncStatus(cwd, graph = "project") {
                     : null,
     };
 }
-export function getFortemiCorePrebuiltStatus(graph = "framework") {
-    const dir = prebuiltDir(graph) ?? path.join(process.cwd(), "prebuilt", "fortemi-core", graph);
+export function getFortemiCorePrebuiltStatus(graph = "framework", packageRoot) {
+    const dir = (packageRoot ? path.join(packageRoot, "prebuilt", "fortemi-core", graph) : prebuiltDir(graph)) ?? path.join(process.cwd(), "prebuilt", "fortemi-core", graph);
     const manifestPath = path.join(dir, "manifest.json");
     const exportPath = path.join(dir, "aiwg-fortemi-index-v2.json");
     const { manifest, reason: manifestReadReason } = readManifestResult(manifestPath);
@@ -222,8 +349,7 @@ export function getFortemiCorePrebuiltStatus(graph = "framework") {
     let reason = null;
     if (exportExists) {
         try {
-            const exportText = fs.readFileSync(exportPath, "utf-8");
-            const exported = JSON.parse(exportText);
+            const { exported, checksum } = readExportSnapshot(exportPath, prebuiltManifest.export_checksum);
             if (prebuiltManifest.schema_version !== "aiwg.fortemi.prebuilt.v1" ||
                 prebuiltManifest.backend !== "fortemi-core" ||
                 prebuiltManifest.graph !== graph ||
@@ -231,7 +357,7 @@ export function getFortemiCorePrebuiltStatus(graph = "framework") {
                 prebuiltManifest.export_schema_version !== "aiwg.fortemi.index.export.v2") {
                 reason = "prebuilt manifest is incompatible with the requested graph";
             }
-            else if (sha256(exportText) !== prebuiltManifest.export_checksum) {
+            else if (checksum !== prebuiltManifest.export_checksum) {
                 reason = "prebuilt export checksum does not match manifest";
             }
             else if (exported.schema_version !== prebuiltManifest.export_schema_version) {