@linzumi/cli 1.0.113 → 1.0.115

package/scripts/build-worker-entry-parity-oracle.mjs

@@ -0,0 +1,424 @@
+// Spec: kandan/plans/2026-07-10-compute-nodes-rescript-commander-zero-ts-program.md
+// (M3 cluster 12, worker-spawn / the I153 stable-entry machinery).
+// Relationship: Builds the TS-side PARITY ORACLE for the worker-entry
+// stability + harness-pin modules of the ReScript commander port, the
+// sibling of build-config-identity-parity-oracle.mjs (cluster 2). The
+// oracle bundles the REAL workerEntryStability.ts (pinWorkerEntryAtBoot /
+// resolveWorkerEntryForSpawn / installVersionToStableDir /
+// entryPathLooksEphemeral / workerEntryMissingMessage - the I153 machinery)
+// and bundledCodexBin.ts (the #3102/#3129 harness version gate:
+// resolveBundledCodexBinary / pinnedHarnessVersion /
+// assessPathFallbackHarness / resolveRequestedCodexBin /
+// revalidateCodexBinForSpawn) behind the cluster 1/2 one-shot BATCH driver
+// (a JSON array of cases on stdin, a JSON array of results on stdout).
+//
+// Determinism + normalization: every case runs in its own realpath'd
+// scratch dir; paths normalize through the "$DIR" placeholder in both
+// directions; wall-clock material (marker mirroredAt/installedAt, event
+// durationMs, `.building-<pid>-<ts>` staging suffixes) normalizes through
+// fixed placeholders so two runs - and two impls - compare byte-identical.
+// File-tree snapshots after every lifecycle are part of the result: the
+// mirror layout under ~/.linzumi/worker-entry and ~/.linzumi/versions is a
+// CROSS-IMPL contract (both commanders share ~/.linzumi through M4).
+//
+// SECRETS: the oracle only ever sees the conformance suite's synthetic
+// trees. The output is a local test artifact (.differential/ is gitignored,
+// never published) and stays unminified for debuggability.
+import { mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const driverSource = `
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname as pathDirname, join, relative } from 'node:path';
+import {
+  entryPathLooksEphemeral,
+  installVersionToStableDir,
+  pinWorkerEntryAtBoot,
+  resolveWorkerEntryForSpawn,
+  workerEntryMissingMessage,
+} from './src/workerEntryStability';
+import {
+  assessPathFallbackHarness,
+  codexPlatformTarget,
+  pinnedHarnessVersion,
+  resolveBundledCodexBinary,
+  resolveRequestedCodexBin,
+  resetBundledCodexWarningForTests,
+  revalidateCodexBinForSpawn,
+} from './src/bundledCodexBin';
+
+// --- Placeholder + snapshot plumbing --------------------------------------------
+
+const dirPlaceholder = '$DIR';
+
+function scratch() {
+  // realpath so macOS /var -> /private/var never splits the two impls'
+  // placeholder substitution.
+  return realpathSync(mkdtempSync(join(tmpdir(), 'linzumi-worker-entry-oracle-')));
+}
+
+function substitute(value, from, to) {
+  if (typeof value === 'string') {
+    return value.split(from).join(to);
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => substitute(entry, from, to));
+  }
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        substitute(key, from, to),
+        substitute(entry, from, to),
+      ])
+    );
+  }
+  return value;
+}
+
+// Wall-clock normalization: marker timestamps, event durations, staging
+// suffixes.
+function normalizeClock(value) {
+  if (typeof value === 'string') {
+    return value
+      .replaceAll(/\\.building-\\d+-\\d+(?:\\.\\d+)?/g, '.building-X')
+      .replaceAll(
+        /"(mirroredAt|installedAt)":"[^"]*"/g,
+        '"$1":"<at>"'
+      );
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => normalizeClock(entry));
+  }
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        normalizeClock(key),
+        key === 'durationMs' ? '<duration>' : normalizeClock(entry),
+      ])
+    );
+  }
+  return value;
+}
+
+function snapshotFiles(dir) {
+  const files = {};
+  const walk = (current) => {
+    let names;
+    try {
+      names = readdirSync(current).sort();
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const full = join(current, name);
+      if (statSync(full).isDirectory()) {
+        files[relative(dir, full) + '/'] = '<dir>';
+        walk(full);
+      } else {
+        files[relative(dir, full)] = readFileSync(full, 'utf8');
+      }
+    }
+  };
+  walk(dir);
+  return files;
+}
+
+function buildTree(root, files) {
+  for (const [relPath, spec] of Object.entries(files ?? {})) {
+    const full = join(root, relPath);
+    if (spec !== null && typeof spec === 'object' && spec.symlinkTo !== undefined) {
+      mkdirSync(pathDirname(full), { recursive: true });
+      symlinkSync(join(root, spec.symlinkTo), full);
+    } else if (relPath.endsWith('/')) {
+      mkdirSync(full, { recursive: true });
+    } else {
+      mkdirSync(pathDirname(full), { recursive: true });
+      writeFileSync(full, String(spec), 'utf8');
+    }
+  }
+}
+
+// --- The worker-entry lifecycle op ------------------------------------------------
+
+async function handleEntryLifecycle(testCase) {
+  const dir = scratch();
+  const homeDir = join(dir, 'home');
+  mkdirSync(homeDir, { recursive: true });
+  const sub = (value) => substitute(value, dirPlaceholder, dir);
+  buildTree(dir, sub(testCase.files ?? {}));
+
+  const events = [];
+  const onEvent = (event, data) => {
+    events.push({ event, data });
+  };
+  const pinnedRef = { value: undefined };
+  const trace = [];
+
+  for (const action of testCase.actions ?? []) {
+    const act = sub(action);
+    switch (act.act) {
+      case 'buildTree': {
+        buildTree(dir, act.files ?? {});
+        trace.push({ act: 'buildTree' });
+        break;
+      }
+      case 'rm': {
+        rmSync(act.path, { recursive: true, force: true });
+        trace.push({ act: 'rm' });
+        break;
+      }
+      case 'touch': {
+        const when = new Date(act.epochMs);
+        utimesSync(act.path, when, when);
+        trace.push({ act: 'touch' });
+        break;
+      }
+      case 'pin': {
+        const pinned = pinWorkerEntryAtBoot({
+          argv1: act.argv1 ?? undefined,
+          cwd: act.cwd ?? dir,
+          homeDir,
+          onEvent,
+          // Deterministic lost-race injection: materialize the "winner's"
+          // complete mirror between the staging build and the rename, so
+          // the loser branch is provable from a plain JSON case.
+          beforeMirrorRenameForTest:
+            act.raceWinnerFiles === undefined
+              ? undefined
+              : () => buildTree(dir, act.raceWinnerFiles),
+        });
+        pinnedRef.value = pinned;
+        trace.push({
+          act: 'pin',
+          pinned:
+            pinned === undefined
+              ? null
+              : {
+                  kind: pinned.kind,
+                  entryPath: pinned.entryPath,
+                  originalEntryPath:
+                    pinned.kind === 'mirrored' ? pinned.originalEntryPath : null,
+                },
+        });
+        break;
+      }
+      case 'resolveSpawn': {
+        try {
+          const resolved = resolveWorkerEntryForSpawn({
+            pinnedRef,
+            argv1: act.argv1 ?? undefined,
+            cwd: act.cwd ?? dir,
+            homeDir,
+            onEvent,
+          });
+          trace.push({ act: 'resolveSpawn', resolved });
+        } catch (error) {
+          trace.push({
+            act: 'resolveSpawn',
+            threw: error instanceof Error ? error.message : String(error),
+          });
+        }
+        break;
+      }
+      case 'installVersion': {
+        const install = act.install ?? {};
+        try {
+          const result = await installVersionToStableDir({
+            version: act.version,
+            homeDir,
+            onEvent,
+            runInstall: async ({ prefixDir, packageSpec }) => {
+              buildTree(prefixDir, install.files ?? {});
+              trace.push({ act: 'runInstall', packageSpec });
+              return install.ok === false
+                ? { ok: false, message: install.message }
+                : { ok: true };
+            },
+          });
+          trace.push({ act: 'installVersion', result });
+        } catch (error) {
+          trace.push({
+            act: 'installVersion',
+            threw: error instanceof Error ? error.message : String(error),
+          });
+        }
+        break;
+      }
+      default:
+        trace.push({ act: 'unknown', name: String(act.act) });
+    }
+  }
+
+  const result = {
+    trace,
+    events,
+    home: snapshotFiles(homeDir),
+  };
+  return normalizeClock(substitute(result, dir, dirPlaceholder));
+}
+
+// --- The harness-pin ops ----------------------------------------------------------
+
+function harnessDeps(dir, spec) {
+  const resolvable = spec.resolvable ?? {};
+  return {
+    platform: spec.platform ?? process.platform,
+    arch: spec.arch ?? process.arch,
+    fileExists: existsSync,
+    listDirectory: (path) => {
+      try {
+        return readdirSync(path);
+      } catch {
+        return [];
+      }
+    },
+    resolveModulePath: (name) =>
+      resolvable[name] === undefined ? undefined : join(dir, resolvable[name]),
+    moduleDir: spec.moduleDir === undefined ? join(dir, 'module') : join(dir, spec.moduleDir),
+  };
+}
+
+function handleHarnessPin(testCase) {
+  const dir = scratch();
+  const sub = (value) => substitute(value, dirPlaceholder, dir);
+  buildTree(dir, sub(testCase.files ?? {}));
+  const deps = harnessDeps(dir, sub(testCase.deps ?? {}));
+  resetBundledCodexWarningForTests();
+  const warnings = [];
+  const writeWarning = (message) => warnings.push(message);
+  const probe = () => (testCase.probeVersion === undefined ? undefined : testCase.probeVersion);
+  const env = testCase.env ?? {};
+
+  const run = () => {
+    switch (testCase.fn) {
+      case 'platformTarget': {
+        // Project the TYPED contract surface ({triple, packageName}): the
+        // runtime row object carries platform/arch too, which the TS type
+        // deliberately hides.
+        const target = codexPlatformTarget(testCase.platform, testCase.arch);
+        return target === undefined
+          ? null
+          : { triple: target.triple, packageName: target.packageName };
+      }
+      case 'resolveBundled': {
+        const resolved = resolveBundledCodexBinary(deps);
+        return resolved === undefined ? null : resolved;
+      }
+      case 'pinnedVersion': {
+        const version = pinnedHarnessVersion(deps);
+        return version === undefined ? null : version;
+      }
+      case 'assess':
+        return assessPathFallbackHarness({
+          pathVersion: testCase.pathVersion ?? undefined,
+          pinnedVersion: testCase.pinnedVersion ?? undefined,
+        });
+      case 'resolveRequested': {
+        const request = resolveRequestedCodexBin(testCase.explicitCodexBin ?? undefined, {
+          ...deps,
+          writeWarning,
+          probeHarnessVersion: probe,
+          env,
+        });
+        return { request, warnings };
+      }
+      case 'revalidate': {
+        const outcome = revalidateCodexBinForSpawn({
+          codexBin: sub(testCase.codexBin),
+          source: testCase.source ?? undefined,
+          deps,
+          probeHarnessVersion: probe,
+          env,
+        });
+        return outcome;
+      }
+      default:
+        throw new Error('unknown harness fn ' + String(testCase.fn));
+    }
+  };
+
+  try {
+    return substitute({ value: run(), warnings }, dir, dirPlaceholder);
+  } catch (error) {
+    return substitute(
+      {
+        threw: error instanceof Error ? error.message : String(error),
+        warnings,
+      },
+      dir,
+      dirPlaceholder
+    );
+  }
+}
+
+// --- Dispatch -----------------------------------------------------------------------
+
+async function handle(testCase) {
+  switch (testCase.op) {
+    case 'entryLifecycle':
+      return handleEntryLifecycle(testCase);
+    case 'looksEphemeral':
+      return { value: entryPathLooksEphemeral(testCase.path) };
+    case 'missingMessage':
+      return {
+        value: workerEntryMissingMessage({
+          attemptedPaths: testCase.attemptedPaths,
+          ephemeral: testCase.ephemeral,
+        }),
+      };
+    case 'harnessPin':
+      return handleHarnessPin(testCase);
+    default:
+      return { threw: true, message: 'unknown op ' + String(testCase.op) };
+  }
+}
+
+let stdin = '';
+process.stdin.setEncoding('utf8');
+for await (const chunk of process.stdin) {
+  stdin += chunk;
+}
+const cases = JSON.parse(stdin);
+const results = [];
+for (const testCase of cases) {
+  results.push(await handle(testCase));
+}
+process.stdout.write(JSON.stringify(results));
+`;
+
+await mkdir(join(packageRoot, '.differential'), { recursive: true });
+
+await build({
+  stdin: {
+    contents: driverSource,
+    resolveDir: packageRoot,
+    sourcefile: 'worker-entry-parity-driver.ts',
+    loader: 'ts',
+  },
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: join(packageRoot, '.differential/worker-entry-parity-oracle.mjs'),
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+});