codex-workflow-v2 2.0.0-beta.13.8 → 2.0.0-beta.14

package/src/alpha6/journal.ts

@@ -0,0 +1,473 @@
+import { randomUUID } from 'node:crypto';
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+  writeSync,
+} from 'node:fs';
+import path from 'node:path';
+import type {
+  MilestoneTransactionJournal,
+  MilestoneTransactionJournalFileSnapshot,
+  MilestoneTransactionPhase,
+} from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+import { ensureDirectory, readJson } from '../fs-utils.js';
+import { assertHash64, assertNoSymlinkPathComponents, sha256Hex } from './store-sidecars.js';
+
+const TRANSACTION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const JOURNAL_PHASES = new Set<MilestoneTransactionPhase>(['prepared', 'applying', 'applied', 'rolled_back']);
+
+export type JournalSnapshotMode = 'inline' | 'path';
+
+interface ValidateJournalOptions {
+  expectedMilestoneId?: string;
+}
+
+export function resolveMilestoneTransactionDirectory(milestoneRoot: string): string {
+  assertNoSymlinkPathComponents(milestoneRoot, { label: 'Milestone root', requireLeaf: true });
+  return path.join(milestoneRoot, '.transactions');
+}
+
+export function resolveMilestoneTransactionJournalPath(milestoneRoot: string, transactionId: string): string {
+  assertSafeTransactionId(transactionId);
+  return path.join(resolveMilestoneTransactionDirectory(milestoneRoot), `${transactionId}.json`);
+}
+
+export function resolveMilestoneTransactionTargetPath(milestoneRoot: string, relativePath: string): string {
+  const normalized = normalizeRelativePath(relativePath, 'Milestone transaction target path');
+  const resolved = resolveWithinRoot(milestoneRoot, normalized, 'Milestone transaction target path');
+  const transactionsRoot = path.resolve(resolveMilestoneTransactionDirectory(milestoneRoot));
+  if (resolved === transactionsRoot || resolved.startsWith(`${transactionsRoot}${path.sep}`)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Transaction target path must not point into .transactions: ${relativePath}`);
+  }
+  return resolved;
+}
+
+export function createAbsentJournalSnapshot(): MilestoneTransactionJournalFileSnapshot {
+  return {
+    exists: false,
+    contentHash: null,
+    contentBase64: null,
+    contentPath: null,
+  };
+}
+
+export function captureJournalTargetSnapshot(
+  milestoneRoot: string,
+  relativePath: string,
+  options: { mode?: JournalSnapshotMode; transactionId?: string; snapshotPath?: string } = {},
+): MilestoneTransactionJournalFileSnapshot {
+  const targetFile = resolveMilestoneTransactionTargetPath(milestoneRoot, relativePath);
+  if (!existsSync(targetFile)) return createAbsentJournalSnapshot();
+  if (lstatSync(targetFile).isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction target must not be a symlink: ${targetFile}`);
+  }
+  const content = readFileSync(targetFile);
+  const snapshotOptions: { mode?: JournalSnapshotMode; transactionId?: string; snapshotPath?: string } = {
+    snapshotPath: options.snapshotPath ?? relativePath,
+  };
+  if (options.mode !== undefined) snapshotOptions.mode = options.mode;
+  if (options.transactionId !== undefined) snapshotOptions.transactionId = options.transactionId;
+  return createJournalSnapshotFromContent(milestoneRoot, content, snapshotOptions);
+}
+
+export function createJournalSnapshotFromContent(
+  milestoneRoot: string,
+  content: string | Buffer,
+  options: { mode?: JournalSnapshotMode; transactionId?: string; snapshotPath?: string } = {},
+): MilestoneTransactionJournalFileSnapshot {
+  const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
+  if ((options.mode ?? 'inline') === 'path') {
+    if (!options.transactionId) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Path-backed journal snapshots require a transaction id.');
+    }
+    if (!options.snapshotPath) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Path-backed journal snapshots require a snapshot path.');
+    }
+    const snapshotFile = resolveMilestoneTransactionSnapshotFile(
+      milestoneRoot,
+      options.transactionId,
+      options.snapshotPath,
+    );
+    writeBufferAtomic(snapshotFile, buffer);
+    const transactionsRoot = resolveMilestoneTransactionDirectory(milestoneRoot);
+    return {
+      exists: true,
+      contentHash: sha256Hex(buffer),
+      contentBase64: null,
+      contentPath: path.relative(transactionsRoot, snapshotFile).split(path.sep).join('/'),
+    };
+  }
+  return {
+    exists: true,
+    contentHash: sha256Hex(buffer),
+    contentBase64: buffer.toString('base64'),
+    contentPath: null,
+  };
+}
+
+export function readJournalSnapshotContent(
+  milestoneRoot: string,
+  snapshot: MilestoneTransactionJournalFileSnapshot,
+  options: ValidateJournalOptions & { transactionId?: string } = {},
+): Buffer | null {
+  validateJournalSnapshot(snapshot, milestoneRoot, options);
+  if (!snapshot.exists) return null;
+  if (snapshot.contentBase64 !== null) {
+    const buffer = decodeCanonicalBase64(snapshot.contentBase64);
+    assertSnapshotHash(snapshot, buffer);
+    return buffer;
+  }
+  if (snapshot.contentPath === null) {
+    throw new WorkflowError('STATE_CORRUPT', 'Existing journal snapshot must provide contentBase64 or contentPath.');
+  }
+  const snapshotFile = resolveJournalSnapshotReference(milestoneRoot, snapshot.contentPath, options.transactionId);
+  if (!existsSync(snapshotFile)) {
+    throw new WorkflowError('STATE_CORRUPT', `Journal snapshot content file not found: ${snapshot.contentPath}`);
+  }
+  const buffer = readFileSync(snapshotFile);
+  assertSnapshotHash(snapshot, buffer);
+  return buffer;
+}
+
+export function writeMilestoneTransactionJournal(
+  milestoneRoot: string,
+  journal: MilestoneTransactionJournal,
+): MilestoneTransactionJournal {
+  validateMilestoneTransactionJournal(journal, milestoneRoot);
+  const file = resolveMilestoneTransactionJournalPath(milestoneRoot, journal.transactionId);
+  writeJsonAtomicDurable(file, journal);
+  return readMilestoneTransactionJournal(milestoneRoot, journal.transactionId, {
+    expectedMilestoneId: journal.milestoneId,
+    transactionId: journal.transactionId,
+  });
+}
+
+export function readMilestoneTransactionJournal(
+  milestoneRoot: string,
+  transactionId: string,
+  options: ValidateJournalOptions & { transactionId?: string } = {},
+): MilestoneTransactionJournal {
+  const file = resolveMilestoneTransactionJournalPath(milestoneRoot, transactionId);
+  if (!existsSync(file)) {
+    throw new WorkflowError('NOT_FOUND', `Milestone transaction journal not found: ${transactionId}`);
+  }
+  const journal = readJson<MilestoneTransactionJournal>(file);
+  const validationOptions: ValidateJournalOptions & { transactionId?: string } = { ...options };
+  if (!validationOptions.transactionId) validationOptions.transactionId = transactionId;
+  validateMilestoneTransactionJournal(journal, milestoneRoot, validationOptions);
+  return journal;
+}
+
+export function listMilestoneTransactionJournals(
+  milestoneRoot: string,
+  options: ValidateJournalOptions = {},
+): MilestoneTransactionJournal[] {
+  const directory = resolveMilestoneTransactionDirectory(milestoneRoot);
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .map((entry) => {
+      const transactionId = entry.name.slice(0, -'.json'.length);
+      return readMilestoneTransactionJournal(milestoneRoot, transactionId, { ...options, transactionId });
+    })
+    .sort((left, right) => left.preparedAt.localeCompare(right.preparedAt) || left.transactionId.localeCompare(right.transactionId));
+}
+
+export function updateMilestoneTransactionJournalPhase(
+  milestoneRoot: string,
+  transactionId: string,
+  phase: MilestoneTransactionPhase,
+  updatedAt: string,
+  options: ValidateJournalOptions = {},
+): MilestoneTransactionJournal {
+  if (!JOURNAL_PHASES.has(phase)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Invalid milestone transaction phase: ${phase}`);
+  }
+  const journal = readMilestoneTransactionJournal(milestoneRoot, transactionId, options);
+  return writeMilestoneTransactionJournal(milestoneRoot, { ...journal, phase, updatedAt });
+}
+
+export function removeMilestoneTransactionJournal(milestoneRoot: string, transactionId: string): void {
+  const file = resolveMilestoneTransactionJournalPath(milestoneRoot, transactionId);
+  rmSync(file, { force: true });
+  rmSync(path.join(resolveMilestoneTransactionDirectory(milestoneRoot), transactionId), { recursive: true, force: true });
+}
+
+function resolveMilestoneTransactionSnapshotFile(
+  milestoneRoot: string,
+  transactionId: string,
+  snapshotPath: string,
+): string {
+  assertSafeTransactionId(transactionId);
+  const normalized = normalizeRelativePath(snapshotPath, 'Milestone transaction snapshot path');
+  return resolveWithinRoot(
+    path.join(resolveMilestoneTransactionDirectory(milestoneRoot), transactionId),
+    normalized,
+    'Milestone transaction snapshot path',
+  );
+}
+
+function validateMilestoneTransactionJournal(
+  journal: MilestoneTransactionJournal,
+  milestoneRoot: string,
+  options: ValidateJournalOptions & { transactionId?: string } = {},
+): void {
+  if (!journal || typeof journal !== 'object' || Array.isArray(journal)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone transaction journal must be an object.');
+  }
+  if (typeof journal.transactionId !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone transaction journal is missing transactionId.');
+  }
+  assertSafeTransactionId(journal.transactionId);
+  if (typeof journal.milestoneId !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal is missing milestoneId: ${journal.transactionId}`);
+  }
+  if (options.expectedMilestoneId && journal.milestoneId !== options.expectedMilestoneId) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal milestone mismatch: ${journal.transactionId}`, {
+      expectedMilestoneId: options.expectedMilestoneId,
+      actualMilestoneId: journal.milestoneId,
+    });
+  }
+  if (!journal.milestoneId.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal is missing milestoneId: ${journal.transactionId}`);
+  }
+  if (!Number.isInteger(journal.expectedMilestoneRevision) || journal.expectedMilestoneRevision < 1) {
+    throw new WorkflowError(
+      'STATE_CORRUPT',
+      `Milestone transaction journal expectedMilestoneRevision must be >= 1: ${journal.transactionId}`,
+    );
+  }
+  if (typeof journal.actor !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal is missing actor: ${journal.transactionId}`);
+  }
+  if (!journal.actor.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal is missing actor: ${journal.transactionId}`);
+  }
+  if (typeof journal.confirmationCodeBindingHash !== 'string') {
+    throw new WorkflowError(
+      'STATE_CORRUPT',
+      `Milestone transaction journal is missing confirmationCodeBindingHash: ${journal.transactionId}`,
+    );
+  }
+  assertHash64(
+    journal.confirmationCodeBindingHash,
+    `Milestone transaction journal confirmationCodeBindingHash for ${journal.transactionId}`,
+  );
+  if (typeof journal.phase !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal has invalid phase: ${journal.transactionId}`);
+  }
+  if (!JOURNAL_PHASES.has(journal.phase)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal has invalid phase: ${journal.transactionId}`, {
+      phase: journal.phase,
+    });
+  }
+  if (typeof journal.preparedAt !== 'string' || !journal.preparedAt.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal is missing preparedAt: ${journal.transactionId}`);
+  }
+  if (typeof journal.updatedAt !== 'string' || !journal.updatedAt.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal is missing updatedAt: ${journal.transactionId}`);
+  }
+  if (!Array.isArray(journal.targetFiles)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal targetFiles must be an array: ${journal.transactionId}`);
+  }
+  if (journal.targetFiles.length === 0) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal must declare target files: ${journal.transactionId}`);
+  }
+  const targetPaths = new Set<string>();
+  for (const target of journal.targetFiles) {
+    if (!target || typeof target !== 'object' || Array.isArray(target)) {
+      throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal target must be an object: ${journal.transactionId}`);
+    }
+    if (typeof target.path !== 'string') {
+      throw new WorkflowError(
+        'STATE_CORRUPT',
+        `Milestone transaction journal target path must be a string: ${journal.transactionId}`,
+      );
+    }
+    const resolvedTarget = resolveMilestoneTransactionTargetPath(milestoneRoot, target.path);
+    if (targetPaths.has(resolvedTarget)) {
+      throw new WorkflowError('STATE_CORRUPT', `Milestone transaction journal target path is duplicated: ${target.path}`, {
+        transactionId: journal.transactionId,
+      });
+    }
+    targetPaths.add(resolvedTarget);
+    validateJournalSnapshot(target.preimage, milestoneRoot, { transactionId: journal.transactionId });
+    validateJournalSnapshot(target.staged, milestoneRoot, { transactionId: journal.transactionId });
+  }
+}
+
+function validateJournalSnapshot(
+  snapshot: MilestoneTransactionJournalFileSnapshot,
+  milestoneRoot: string,
+  options: { transactionId?: string } = {},
+): void {
+  if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Journal snapshot must be an object.');
+  }
+  if (typeof snapshot.exists !== 'boolean') {
+    throw new WorkflowError('STATE_CORRUPT', 'Journal snapshot exists must be boolean.');
+  }
+  if (!snapshot.exists) {
+    if (snapshot.contentHash !== null || snapshot.contentBase64 !== null || snapshot.contentPath !== null) {
+      throw new WorkflowError('STATE_CORRUPT', 'Absent journal snapshot must not include content.');
+    }
+    return;
+  }
+  if (typeof snapshot.contentHash !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', 'Existing journal snapshot is missing contentHash.');
+  }
+  assertHash64(snapshot.contentHash, 'Journal snapshot contentHash');
+  if (snapshot.contentBase64 !== null && typeof snapshot.contentBase64 !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', 'Journal snapshot contentBase64 must be a string or null.');
+  }
+  if (snapshot.contentPath !== null && typeof snapshot.contentPath !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', 'Journal snapshot contentPath must be a string or null.');
+  }
+  const hasInline = typeof snapshot.contentBase64 === 'string';
+  const hasPath = typeof snapshot.contentPath === 'string';
+  if (hasInline === hasPath) {
+    throw new WorkflowError('STATE_CORRUPT', 'Existing journal snapshot must provide exactly one content source.');
+  }
+  if (hasInline) {
+    assertSnapshotHash(snapshot, decodeCanonicalBase64(snapshot.contentBase64 ?? ''));
+    return;
+  }
+  const snapshotFile = resolveJournalSnapshotReference(milestoneRoot, snapshot.contentPath ?? '', options.transactionId);
+  if (!existsSync(snapshotFile)) {
+    throw new WorkflowError('STATE_CORRUPT', `Journal snapshot content file not found: ${snapshot.contentPath}`);
+  }
+  assertNoSymlinkPathComponents(snapshotFile, { label: 'Journal snapshot content file', requireLeaf: true });
+  assertSnapshotHash(snapshot, readFileSync(snapshotFile));
+}
+
+function resolveJournalSnapshotReference(milestoneRoot: string, contentPath: string, transactionId?: string): string {
+  const normalized = normalizeRelativePath(contentPath, 'Milestone transaction snapshot contentPath');
+  const transactionsRoot = resolveMilestoneTransactionDirectory(milestoneRoot);
+  const resolved = resolveWithinRoot(transactionsRoot, normalized, 'Milestone transaction snapshot contentPath');
+  if (transactionId) {
+    const transactionRoot = path.resolve(path.join(transactionsRoot, transactionId));
+    if (resolved !== transactionRoot && !resolved.startsWith(`${transactionRoot}${path.sep}`)) {
+      throw new WorkflowError(
+        'STATE_CORRUPT',
+        `Journal snapshot contentPath must stay under the journal transaction root: ${contentPath}`,
+        { transactionId },
+      );
+    }
+    return resolved;
+  }
+  const relative = path.relative(transactionsRoot, resolved).split(path.sep).filter(Boolean);
+  if (relative.length < 2) {
+    throw new WorkflowError(
+      'STATE_CORRUPT',
+      `Journal snapshot contentPath must include a transaction directory: ${contentPath}`,
+    );
+  }
+  assertSafeTransactionId(relative[0] ?? '');
+  return resolved;
+}
+
+function assertSnapshotHash(snapshot: MilestoneTransactionJournalFileSnapshot, buffer: Buffer): void {
+  if (snapshot.contentHash === null) {
+    throw new WorkflowError('STATE_CORRUPT', 'Journal snapshot is missing contentHash.');
+  }
+  const actualContentHash = sha256Hex(buffer);
+  if (snapshot.contentHash !== actualContentHash) {
+    throw new WorkflowError('STATE_CORRUPT', 'Journal snapshot content hash mismatch.', {
+      expectedContentHash: snapshot.contentHash,
+      actualContentHash,
+    });
+  }
+}
+
+function assertSafeTransactionId(transactionId: string): void {
+  if (!transactionId.trim() || !TRANSACTION_ID_PATTERN.test(transactionId)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Invalid milestone transaction id: ${transactionId}`);
+  }
+}
+
+function normalizeRelativePath(candidate: string, label: string): string {
+  if (!candidate.trim()) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} is required.`);
+  }
+  if (path.isAbsolute(candidate)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} must be relative: ${candidate}`);
+  }
+  const normalized = path.posix.normalize(candidate.replaceAll('\\', '/'));
+  if (normalized === '.' || normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} must not traverse directories: ${candidate}`);
+  }
+  return normalized.split('/').join(path.sep);
+}
+
+function resolveWithinRoot(root: string, relativePath: string, label: string): string {
+  const resolvedRoot = path.resolve(root);
+  const resolvedCandidate = path.resolve(resolvedRoot, relativePath);
+  if (resolvedCandidate !== resolvedRoot && !resolvedCandidate.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} escapes the milestone root: ${relativePath}`);
+  }
+  return resolvedCandidate;
+}
+
+function writeBufferAtomic(file: string, content: Buffer): void {
+  const directory = path.dirname(file);
+  ensureDirectory(directory);
+  assertNoSymlinkPathComponents(directory, { label: 'Snapshot directory', requireLeaf: true });
+  if (existsSync(file) && lstatSync(file).isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `Refusing to replace snapshot symlink: ${file}`);
+  }
+  const temporary = path.join(directory, `.${path.basename(file)}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, content, { mode: 0o600 });
+    renameSync(temporary, file);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+function writeJsonAtomicDurable(file: string, value: unknown): void {
+  const directory = path.dirname(file);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  assertNoSymlinkPathComponents(directory, { label: 'Journal directory', requireLeaf: true });
+  if (existsSync(file) && lstatSync(file).isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `Refusing to replace transaction journal symlink: ${file}`);
+  }
+  const temporary = path.join(directory, `.${path.basename(file)}.${randomUUID()}.tmp`);
+  let fileDescriptor: number | null = null;
+  let directoryDescriptor: number | null = null;
+  try {
+    fileDescriptor = openSync(temporary, 'wx', 0o600);
+    const payload = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    writeSync(fileDescriptor, payload);
+    fsyncSync(fileDescriptor);
+    closeSync(fileDescriptor);
+    fileDescriptor = null;
+    renameSync(temporary, file);
+    directoryDescriptor = openSync(directory, 'r');
+    fsyncSync(directoryDescriptor);
+  } finally {
+    if (fileDescriptor !== null) closeSync(fileDescriptor);
+    if (directoryDescriptor !== null) closeSync(directoryDescriptor);
+    rmSync(temporary, { force: true });
+  }
+}
+
+function decodeCanonicalBase64(value: string): Buffer {
+  if (!value || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Journal snapshot contentBase64 must be canonical base64.');
+  }
+  const buffer = Buffer.from(value, 'base64');
+  if (buffer.toString('base64') !== value) {
+    throw new WorkflowError('STATE_CORRUPT', 'Journal snapshot contentBase64 must be canonical base64.');
+  }
+  return buffer;
+}

package/src/alpha6/literal-test-invocation.ts

@@ -0,0 +1,84 @@
+/** A deliberately bounded lexical reader, not a JavaScript evaluator. Unknown
+ * syntax produces no dependency evidence. Comments/string contents are never code. */
+const SAFE_TEST = /^(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_.-]+\.(?:spec|test)\.[cm]?[jt]sx?$/;
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+type Token = { text: string; string?: string };
+
+function tokens(source: string): Token[] {
+  const result: Token[] = [];
+  const lexer = /\s+|\/\/[^\n]*|\/\*[\s\S]*?\*\/|'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"|`(?:\\.|[^`\\])*`|\/(?:\\.|\[(?:\\.|[^\]\\])*\]|[^/\\\n])+\/[a-z]*|[A-Za-z_$][\w$]*|\d+|\.\.\.|===|!==|=>|&&|\|\||[^\s]/gy;
+  let match: RegExpExecArray | null;
+  while ((match = lexer.exec(source))) {
+    const raw = match[0];
+    if (/^\s|^\/\//.test(raw) || raw.startsWith('/*')) continue;
+    if (raw.startsWith('/') && raw.length > 1) { result.push({ text: '<regex>' }); continue; }
+    if (raw.startsWith('`')) { result.push({ text: '<template>' }); continue; }
+    if (raw.startsWith("'") || raw.startsWith('"')) {
+      // Escapes cannot establish executable/path identity in this bounded profile.
+      const value = raw.slice(1, -1);
+      result.push({ text: JSON.stringify(value), ...(value.includes('\\') ? {} : { string: value }) });
+    } else result.push({ text: raw });
+  }
+  return result;
+}
+
+export function literalVitestInvocations(source: string): string[][] {
+  const ts = tokens(source), code = ts.map(t => t.text).join(' ');
+  const functionOffsets = new Set<number>();
+  let offset = 0;
+  for (const token of ts) {
+    if (token.text === 'function' && token.string === undefined) functionOffsets.add(offset);
+    offset += token.text.length + 1;
+  }
+  // Only a local, typed or untyped three-argument wrapper forwarding argv unchanged
+  // to imported Node spawnSync at repository cwd, with no shell, is supported.
+  const wrappers = new Set<string>();
+  const header = /function ([\w$]+) \( ([\w$]+)(?: : string)? , ([\w$]+)(?: : readonly string \[ \])? , ([\w$]+)(?: : NodeJS \. ProcessEnv)?(?: ,)? \) (?:: void )?\{ /g;
+  for (const match of code.matchAll(header)) {
+    if (!functionOffsets.has(match.index!)) continue;
+    const [name, executable, args, env] = match.slice(1);
+    if (![name, executable, args, env].every(v => v && IDENTIFIER.test(v))) continue;
+    const prefix = `const result = spawnSync ( ${executable} , ${args} , { cwd : process . cwd ( ) , env : ${env} , stdio : "inherit" , } ) ;`;
+    const body = code.slice(match.index! + match[0].length);
+    // The recognized wrapper has exactly the usual nonzero/error check and throw.
+    const ending = /^ if \( result \. error !== undefined \|\| result \. status !== 0 \) \{ throw new Error \( <template> , \{ cause : result \. error , \}(?: ,)? \) ; \} \}/;
+    if (body.startsWith(prefix) && ending.test(body.slice(prefix.length))) wrappers.add(name!);
+  }
+  if (!/import \{ spawnSync \} from "node:child_process" ;/.test(code)) return [];
+  // A local shadow/reassignment makes forwarding ambiguous; fail closed.
+  for (const name of [...wrappers]) {
+    const declarations = ts.filter((t, i) => t.text === name && ts[i - 1]?.text === 'function').length;
+    if (declarations !== 1 || ts.some((token, i) => token.text === name
+      && ts[i - 1]?.text !== 'function' && ts[i + 1]?.text !== '(')) wrappers.delete(name);
+  }
+  if (ts.some((token, i) => token.text === 'spawnSync'
+    && ts[i + 1]?.text !== '('
+    && !(ts[i - 1]?.text === '{' && ts[i - 2]?.text === 'import' && ts[i + 1]?.text === '}'))) return [];
+  if (/\bfunction spawnSync\b/.test(code)) return [];
+  const found: string[][] = [];
+  for (let i = 0; i < ts.length; i++) {
+    if (!wrappers.has(ts[i]!.text) || ts[i - 1]?.text === '.' || ts[i + 1]?.text !== '(' || ts[i + 2]?.string !== 'npx' || ts[i + 3]?.text !== ',' || ts[i + 4]?.text !== '[') continue;
+    const argv: string[] = []; let j = i + 5;
+    while (ts[j]?.string !== undefined) {
+      argv.push(ts[j]!.string!); j++;
+      if (ts[j]?.text !== ',') break;
+      j++;
+    }
+    if (ts[j]?.text !== ']' || ts[j + 1]?.text !== ',' || argv[0] !== 'vitest' || argv[1] !== 'run') continue;
+    const paths = argv.slice(2).filter(arg => !arg.startsWith('--'));
+    if (!paths.length || paths.some(arg => !SAFE_TEST.test(arg) || arg.split('/').includes('..'))) continue;
+    const options = argv.slice(2 + paths.length);
+    if (argv.slice(2, 2 + paths.length).some(arg => arg.startsWith('--')) || options.some(arg => !/^--maxWorkers=[1-9][0-9]*$/.test(arg)) || options.length > 1) continue;
+    found.push(argv);
+  }
+  return found;
+}
+
+export function literalMigrationCatalogNames(source: string): string[] {
+  const ts = tokens(source);
+  const key = (t: Token | undefined) => t?.string ?? t?.text;
+  if (!ts.some((t, i) => key(t) === 'checksum_sha256' && ts[i + 1]?.text === ':')) return [];
+  return [...new Set(ts.flatMap((t, i) => key(t) === 'migration_name' && ts[i + 1]?.text === ':'
+    && ts[i + 2]?.string && /^[0-9]{4}_[a-z0-9_]+\.sql$/.test(ts[i + 2]!.string!)
+    ? [ts[i + 2]!.string!] : []))].sort();
+}