@linzumi/cli 1.0.111 → 1.0.113

package/scripts/build-core-startup-resume-scan-parity-oracle.mjs

@@ -0,0 +1,296 @@
+// Spec: kandan/plans/2026-07-10-compute-nodes-rescript-commander-zero-ts-program.md
+// (M3 cluster 10, commander core).
+// Relationship: Builds the TS-side PARITY ORACLE for the startup
+// resurrection scan of the ReScript commander port, the sibling of
+// build-queue-parity-oracle.mjs (cluster 5). The oracle bundles the REAL
+// TS module (src/startupResumeScan.ts - the 2026-07-11
+// lease-adopted-no-resurrection incident fix; dossier:
+// kandan/server_v2/test/fixtures/prod-failures/
+// runner_restart_lease_adopted_no_resurrection_2026-07-11.md) behind the
+// cluster 1/2 one-shot batch driver: a JSON array of cases on stdin, a
+// JSON array of results on stdout. The ReScript package's
+// CoreStartupResumeScanParityConformance drives the SAME inputs through
+// the ported module and asserts:
+//   - constants parity (terminal statuses, age gate, concurrency /
+//     stagger / retry-backoff ladders);
+//   - fold parity (foldOutboxTurnSignals over raw journal bytes, encoded
+//     in map-insertion order so even the fold's internal ordering is
+//     pinned);
+//   - classification parity (classifyUnfinishedThreadWork matrices);
+//   - scripted SCAN RUNS: runStartupResumeScan with every effect
+//     (inspect/drain/respawn/publish/seq-in-flight/shutdown/sleep/log)
+//     scripted, a virtual clock advanced only by the scripted sleep, and
+//     ONE shared trace of effect calls + log events in order - compared
+//     byte-for-byte across impls, so the bounded scheduler's interleaving
+//     itself (worker pool, shared stagger chain, retry ladders, shutdown
+//     aborts) is the contract.
+//
+// Determinism: nothing in a scan case touches the real clock or timers -
+// sleep records the requested delay, advances the virtual clock, and
+// resolves immediately; scripted effect outcomes resolve in order;
+// shutdown flips on a scripted effect-call count. The driver's effect
+// functions return plain resolved/rejected promises (never async
+// functions) so both impls award identical microtask hops.
+//
+// SECRETS: the oracle only ever sees the conformance suite's synthetic
+// fixtures; nothing here logs case contents.
+//
+// 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 {
+  classifyUnfinishedThreadWork,
+  defaultResumeSignalMaxAgeMs,
+  defaultStartupResumeConcurrency,
+  defaultStartupResumeRetryBackoffMs,
+  defaultStartupResumeStaggerMs,
+  defaultStartupRespawnRetryBackoffMs,
+  foldOutboxTurnSignals,
+  runStartupResumeScan,
+  terminalMessageStateStatuses,
+} from './src/startupResumeScan';
+
+// --- Encoding helpers -------------------------------------------------------------
+
+// Signals encoded in MAP-INSERTION ORDER: the fold's internal ordering is
+// part of the parity contract (classification iterates the map).
+function encodeSignals(map) {
+  return Array.from(map.values()).map((signal) => ({
+    sourceSeq: signal.sourceSeq,
+    sawActivity: signal.sawActivity,
+    ...(signal.lastMessageStateStatus === undefined
+      ? {}
+      : { lastMessageStateStatus: signal.lastMessageStateStatus }),
+    ...(signal.newestAtMs === undefined ? {} : { newestAtMs: signal.newestAtMs }),
+  }));
+}
+
+function signalMapOf(spec) {
+  if (typeof spec.journalRaw === 'string') {
+    return foldOutboxTurnSignals(spec.journalRaw);
+  }
+  const map = new Map();
+  for (const signal of spec.signals ?? []) {
+    map.set(signal.sourceSeq, {
+      sourceSeq: signal.sourceSeq,
+      sawActivity: signal.sawActivity ?? false,
+      lastMessageStateStatus: signal.lastMessageStateStatus ?? undefined,
+      newestAtMs: signal.newestAtMs ?? undefined,
+    });
+  }
+  return map;
+}
+
+function inputsOf(spec) {
+  return {
+    pendingInboundSeqs: spec.pendingInboundSeqs ?? [],
+    ackedInboundSeqs: spec.ackedInboundSeqs ?? [],
+    inboundHighWaterSeq: spec.inboundHighWaterSeq ?? undefined,
+    appliedFloorSeq: spec.appliedFloorSeq ?? undefined,
+    outboxTurnSignals: signalMapOf(spec),
+  };
+}
+
+function encodeWork(work) {
+  return {
+    unfinished: work.unfinished,
+    seqs: work.seqs.map((entry) => ({ sourceSeq: entry.sourceSeq, shape: entry.shape })),
+    hasPendingInbound: work.hasPendingInbound,
+    loudTerminalSeqs: [...work.loudTerminalSeqs],
+    watermarkGapOnly: work.watermarkGapOnly,
+  };
+}
+
+// --- Case handlers ----------------------------------------------------------------
+
+function handleConstants() {
+  return {
+    terminalMessageStateStatuses: Array.from(terminalMessageStateStatuses),
+    defaultResumeSignalMaxAgeMs,
+    defaultStartupResumeConcurrency,
+    defaultStartupResumeStaggerMs,
+    defaultStartupResumeRetryBackoffMs: [...defaultStartupResumeRetryBackoffMs],
+    defaultStartupRespawnRetryBackoffMs: [...defaultStartupRespawnRetryBackoffMs],
+  };
+}
+
+function handleFold(testCase) {
+  return { signals: encodeSignals(foldOutboxTurnSignals(testCase.raw ?? '')) };
+}
+
+function handleClassify(testCase) {
+  return encodeWork(
+    classifyUnfinishedThreadWork(inputsOf(testCase.inputs ?? {}), {
+      nowMs: testCase.nowMs ?? 0,
+      maxSignalAgeMs: testCase.maxSignalAgeMs ?? undefined,
+    })
+  );
+}
+
+// One scripted scan run. Every effect resolves from the case script; the
+// shared events array is the trace both impls must reproduce byte for
+// byte (virtual-time stamps included).
+async function handleScan(testCase) {
+  const options = testCase.options ?? {};
+  const threads = testCase.threads ?? [];
+  const events = [];
+  let vnow = 0;
+  let effectOps = 0;
+  const shutdownAfterOps = options.shutdownAfterOps ?? undefined;
+  const scripts = new Map(
+    threads.map((thread) => [
+      thread.threadId,
+      {
+        drain: [...(thread.drainScript ?? [])],
+        respawn: [...(thread.respawnScript ?? [])],
+        publish: [...(thread.publishScript ?? [])],
+        inFlight: new Set(thread.inFlightSeqs ?? []),
+      },
+    ])
+  );
+
+  const summary = await runStartupResumeScan({
+    records: threads,
+    threadId: (record) => record.threadId,
+    inspect: (record) => {
+      events.push({ e: 'inspect', vt: vnow, thread: record.threadId });
+      const spec = record.inspect ?? {};
+      if (typeof spec.throw === 'string') {
+        throw new Error(spec.throw);
+      }
+      return inputsOf(spec);
+    },
+    resumePendingInbound: (record) => {
+      effectOps += 1;
+      const step = scripts.get(record.threadId).drain.shift() ?? 'clear';
+      if (typeof step === 'object' && step !== null) {
+        events.push({
+          e: 'drain',
+          vt: vnow,
+          thread: record.threadId,
+          outcome: 'throw:' + step.throw,
+        });
+        return Promise.reject(new Error(step.throw));
+      }
+      events.push({ e: 'drain', vt: vnow, thread: record.threadId, outcome: step });
+      return Promise.resolve(step);
+    },
+    respawnWorker: (record) => {
+      effectOps += 1;
+      const step = scripts.get(record.threadId).respawn.shift() ?? true;
+      if (typeof step === 'object' && step !== null) {
+        events.push({
+          e: 'respawn',
+          vt: vnow,
+          thread: record.threadId,
+          outcome: 'throw:' + step.throw,
+        });
+        return Promise.reject(new Error(step.throw));
+      }
+      events.push({ e: 'respawn', vt: vnow, thread: record.threadId, outcome: step });
+      return Promise.resolve(step);
+    },
+    seqInFlight: (record, sourceSeq) => scripts.get(record.threadId).inFlight.has(sourceSeq),
+    publishInterruptedTurnState: (record, sourceSeq, shape) => {
+      effectOps += 1;
+      const step = scripts.get(record.threadId).publish.shift() ?? 'ok';
+      if (typeof step === 'object' && step !== null) {
+        events.push({
+          e: 'publish',
+          vt: vnow,
+          thread: record.threadId,
+          seq: sourceSeq,
+          shape,
+          outcome: 'throw:' + step.throw,
+        });
+        return Promise.reject(new Error(step.throw));
+      }
+      events.push({
+        e: 'publish',
+        vt: vnow,
+        thread: record.threadId,
+        seq: sourceSeq,
+        shape,
+        outcome: step,
+      });
+      return Promise.resolve(undefined);
+    },
+    shuttingDown: () => shutdownAfterOps !== undefined && effectOps >= shutdownAfterOps,
+    log: (event, fields) => {
+      events.push({ e: 'log', vt: vnow, event, fields });
+    },
+    nowMs: options.nowMs ?? 0,
+    maxSignalAgeMs: options.maxSignalAgeMs ?? undefined,
+    concurrency: options.concurrency ?? undefined,
+    staggerMs: options.staggerMs ?? undefined,
+    retryBackoffMs: options.retryBackoffMs ?? undefined,
+    respawnRetryBackoffMs: options.respawnRetryBackoffMs ?? undefined,
+    sleep: (ms) => {
+      effectOps += 1;
+      events.push({ e: 'sleep', vt: vnow, ms });
+      vnow += ms;
+      return Promise.resolve(undefined);
+    },
+  });
+
+  return { summary, events };
+}
+
+async function handle(testCase) {
+  switch (testCase.op) {
+    case 'constants':
+      return handleConstants();
+    case 'fold':
+      return handleFold(testCase);
+    case 'classify':
+      return handleClassify(testCase);
+    case 'scan':
+      return await handleScan(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));
+}
+// Exit after stdout is fully flushed (the cluster 5 lesson: a bare
+// process.exit(0) truncates large result arrays mid-pipe).
+process.stdout.write(JSON.stringify(results), () => {
+  process.exit(0);
+});
+`;
+
+await mkdir(join(packageRoot, '.differential'), { recursive: true });
+
+await build({
+  stdin: {
+    contents: driverSource,
+    resolveDir: packageRoot,
+    sourcefile: 'core-startup-resume-scan-parity-driver.ts',
+    loader: 'ts',
+  },
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: join(packageRoot, '.differential/core-startup-resume-scan-parity-oracle.mjs'),
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+});