@linzumi/cli 1.0.110 → 1.0.112

package/scripts/build-core-lifecycle-guards-parity-oracle.mjs

@@ -0,0 +1,443 @@
+// 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 lifecycle
+// drain-guards slice of the ReScript commander port, a sibling of
+// build-pipeline-parity-oracle.mjs (cluster 9). The oracle bundles the REAL
+// TS lifecycle guards module (src/runnerLifecycleGuards.ts - the
+// SIGTERM/SIGINT fast-exit drain and the SIGUSR2 graceful update-restart
+// drain: drain constants, env resolvers, refusal/held/forced-kill reason
+// strings, the hold classification, the SIGTERM routing decision, the
+// force-exit verdict, and the two drain machines themselves) behind the
+// cluster 1/2 one-shot BATCH driver (a JSON array of cases on stdin, a JSON
+// array of results on stdout).
+//
+// Byte parity: log events are traced VERBATIM (event name + the TS field
+// objects' own key order rides JSON.stringify), so the ReScript side's log
+// field dicts must reproduce field presence AND insertion order exactly.
+// Determinism: the graceful-drain runs ride a scripted clock + a scripted
+// poll scheduler fired explicitly by ops, signal deliveries ride
+// process.emit (synchronous JS listener dispatch, no real signal), and
+// every op is followed by a macrotask settle so async hook completions land
+// in a stable order. The fast-exit drain runs use real (small) deadline
+// timers - the traced outcome is deterministic either way because scripted
+// steps either settle immediately or never.
+//
+// SECRETS: the oracle only ever sees the conformance suite's synthetic
+// payloads. 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 {
+  runDrain,
+  installDrainOnSigterm,
+  gracefulUpdateDrainSignal,
+  defaultGracefulUpdateDrainMaxWaitMs,
+  defaultGracefulUpdateDrainHardCapMs,
+  defaultGracefulUpdateDrainOverlapHardCapMs,
+  gracefulUpdateDrainActivityIdleMs,
+  gracefulUpdateDrainPollMs,
+  gracefulUpdateDrainWaitingLogIntervalMs,
+  resolveGracefulUpdateDrainMaxWaitMs,
+  resolveGracefulUpdateDrainHardCapMs,
+  resolveGracefulUpdateDrainActivityIdleMs,
+  updateRestartDrainRefusalPrefix,
+  updateRestartDrainRefusalReason,
+  isUpdateRestartDrainRefusalError,
+  updateRestartDrainHeldReason,
+  defaultUpdateDrainHeldTurnMaxWaitMs,
+  updateDrainHeldTurnSweepIntervalMs,
+  resolveUpdateDrainHeldTurnMaxWaitMs,
+  classifyUpdateDrainStartHold,
+  updateRestartDrainForcedKillReasonPrefix,
+  updateRestartDrainForcedKillReason,
+  updateRestartDrainForcedKillWaitingOnApprovalReason,
+  shouldRouteSigtermThroughGracefulUpdateDrain,
+  updateDrainForceExitVerdict,
+  updateDrainShouldForceExit,
+  createGracefulUpdateDrain,
+  installGracefulUpdateDrainOnSignal,
+} from './src/runnerLifecycleGuards';
+
+const settle = () => new Promise((resolve) => setImmediate(resolve));
+
+// Env cases carry null for "unset"; a real env never holds null.
+function envOf(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input ?? {})) {
+    if (value !== null) env[key] = value;
+  }
+  return env;
+}
+
+function scriptedStep(name, behavior, trace) {
+  if (behavior === undefined || behavior === null || behavior === 'omit') {
+    return undefined;
+  }
+  return () => {
+    trace.push({ t: 'step', name });
+    if (behavior === 'fail') throw new Error(name + ' failed');
+    if (behavior === 'never') return new Promise(() => {});
+    return undefined;
+  };
+}
+
+function scriptedSteps(input, trace) {
+  return {
+    stopAccepting: scriptedStep('stopAccepting', input.stopAccepting ?? 'ok', trace),
+    interruptInFlightTurns: scriptedStep(
+      'interruptInFlightTurns',
+      input.interruptInFlightTurns,
+      trace
+    ),
+    flushInboundQueues: scriptedStep('flushInboundQueues', input.flushInboundQueues ?? 'ok', trace),
+    flushOutbox: scriptedStep('flushOutbox', input.flushOutbox ?? 'ok', trace),
+    checkpointCurrentTurn: scriptedStep(
+      'checkpointCurrentTurn',
+      input.checkpointCurrentTurn ?? 'ok',
+      trace
+    ),
+  };
+}
+
+async function runDrainStepsCase(input) {
+  const trace = [];
+  const steps = scriptedSteps(input.steps ?? {}, trace);
+  const log = (event, fields) => trace.push({ t: 'log', event, fields });
+  // The drain's deadline timer is unref'd by design; with a scripted
+  // never-resolving step it can be the ONLY pending work in this one-shot
+  // driver, and node would exit before it fires. Keep the loop alive for
+  // the duration of the case (production runners always have live handles).
+  const keepAlive = setInterval(() => {}, 25);
+  let result;
+  try {
+    const outcome = await runDrain(steps, input.deadlineMs, log);
+    result = { ok: { drained: outcome.drained, timedOut: outcome.timedOut } };
+  } catch (error) {
+    result = { error: error instanceof Error ? error.message : String(error) };
+  } finally {
+    clearInterval(keepAlive);
+  }
+  return { trace, result };
+}
+
+async function runSigtermDrainCase(input) {
+  const trace = [];
+  const steps = scriptedSteps(input.steps ?? {}, trace);
+  let exitThrowsRemaining = input.exitThrows ?? 0;
+  let exitCount = 0;
+  const installed = installDrainOnSigterm({
+    steps,
+    deadlineMs: input.deadlineMs ?? 5_000,
+    log: (event, fields) => trace.push({ t: 'log', event, fields }),
+    exit: (code, signal) => {
+      trace.push({ t: 'exit', code, signal: signal ?? null });
+      exitCount += 1;
+      if (exitThrowsRemaining > 0) {
+        exitThrowsRemaining -= 1;
+        throw new Error('scripted exit failure');
+      }
+    },
+    forceExit: (code) => {
+      trace.push({ t: 'forceExit', code });
+      if (input.forceExitThrows === true) {
+        throw new Error('scripted force-exit failure');
+      }
+    },
+    signals: input.signals ?? undefined,
+  });
+  let uninstalled = false;
+  for (const op of input.ops ?? []) {
+    if (op.op === 'trigger') installed.trigger(op.signal);
+    else if (op.op === 'emit') process.emit(op.signal);
+    else if (op.op === 'uninstall') {
+      installed.uninstall();
+      uninstalled = true;
+    }
+    await settle();
+  }
+  const expectedExits = input.expectedExits ?? 0;
+  const deadlineAt = Date.now() + 5_000;
+  while (exitCount < expectedExits && Date.now() < deadlineAt) {
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  await settle();
+  if (!uninstalled) installed.uninstall();
+  return { trace };
+}
+
+function turnOf(spec) {
+  return {
+    threadId: spec.threadId,
+    turnId: spec.turnId ?? undefined,
+    engine: spec.engine,
+  };
+}
+
+async function runUpdateDrainCase(input) {
+  const trace = [];
+  const clock = { nowMs: input.startMs ?? 0 };
+  const state = {
+    turns: (input.turns ?? []).map(turnOf),
+    quiescent: input.quiescent === true,
+    activity: input.activity ?? undefined,
+    approvalPending: input.approvalPending === true,
+    waitEligible: input.waitEligible === true,
+  };
+  const scheduler = { active: null, nextId: 1 };
+  const scheduleRepeating = (callback, ms) => {
+    const id = scheduler.nextId;
+    scheduler.nextId += 1;
+    trace.push({ t: 'interval.set', id, ms });
+    scheduler.active = { id, callback };
+    return id;
+  };
+  const cancelRepeating = (handle) => {
+    if (scheduler.active !== null && scheduler.active.id === handle) {
+      trace.push({ t: 'interval.clear', id: scheduler.active.id });
+      scheduler.active = null;
+    }
+  };
+  const hardCapMs =
+    input.capEnv !== undefined && input.capEnv !== null
+      ? resolveGracefulUpdateDrainHardCapMs(
+          envOf(input.capEnv),
+          input.maxWaitMs,
+          input.capOverlap === true
+        )
+      : input.hardCapMs ?? undefined;
+  const hooks = {
+    beginDraining: () => trace.push({ t: 'beginDraining' }),
+    isQuiescent: () => state.quiescent,
+    isWaitEligible:
+      input.waitEligible === undefined || input.waitEligible === null
+        ? undefined
+        : () => state.waitEligible,
+    inFlightTurns: input.withTurnsHook === false ? undefined : () => state.turns.slice(),
+    lastActivityAtMs: input.withActivityHook === false ? undefined : () => state.activity,
+    publishForcedKillTerminalStates:
+      input.withPublishHook === false
+        ? undefined
+        : (turns) => {
+            trace.push({
+              t: 'publishForcedKill',
+              threadIds: turns.map((turn) => turn.threadId),
+              reasons: turns.map(() =>
+                state.approvalPending
+                  ? updateRestartDrainForcedKillWaitingOnApprovalReason
+                  : updateRestartDrainForcedKillReason
+              ),
+            });
+            if (input.publishFails === true) {
+              throw new Error('scripted publish failure');
+            }
+            return undefined;
+          },
+    onTurnCompleted:
+      input.withOnTurnCompleted === true
+        ? (turn) =>
+            trace.push({ t: 'turnCompleted', threadId: turn.threadId, turnId: turn.turnId ?? null })
+        : undefined,
+    exitViaDrain: (outcome) =>
+      trace.push({ t: 'exitViaDrain', forced: outcome.forced, waitedMs: outcome.waitedMs }),
+  };
+  const params = {
+    hooks,
+    maxWaitMs: input.maxWaitMs,
+    hardCapMs,
+    activityIdleMs: input.activityIdleMs ?? undefined,
+    pollMs: input.pollMs ?? undefined,
+    waitingLogIntervalMs: input.waitingLogIntervalMs ?? undefined,
+    log: (event, fields) => trace.push({ t: 'log', event, fields }),
+    scheduler: { setInterval: scheduleRepeating, clearInterval: cancelRepeating },
+    now: () => clock.nowMs,
+  };
+  let requestDrain;
+  let cancelDrain;
+  let cleanup;
+  if (input.installSignals !== undefined && input.installSignals !== null) {
+    const installed = installGracefulUpdateDrainOnSignal({
+      ...params,
+      signals: input.installSignals,
+    });
+    requestDrain = installed.requestDrain;
+    cancelDrain = installed.cancelDrain;
+    cleanup = installed.uninstall;
+  } else {
+    const drain = createGracefulUpdateDrain(params);
+    requestDrain = drain.requestDrain;
+    cancelDrain = drain.cancelDrain;
+    cleanup = drain.stop;
+  }
+  for (const op of input.ops ?? []) {
+    if (op.op === 'requestDrain') requestDrain(op.trigger);
+    else if (op.op === 'cancelDrain') trace.push({ t: 'cancelResult', value: cancelDrain(op.reason) });
+    else if (op.op === 'advance') clock.nowMs = op.toMs;
+    else if (op.op === 'firePoll') {
+      if (scheduler.active !== null) scheduler.active.callback();
+    } else if (op.op === 'setTurns') state.turns = op.turns.map(turnOf);
+    else if (op.op === 'setActivity') state.activity = op.atMs;
+    else if (op.op === 'clearActivity') state.activity = undefined;
+    else if (op.op === 'setQuiescent') state.quiescent = op.value === true;
+    else if (op.op === 'setApprovalPending') state.approvalPending = op.value === true;
+    else if (op.op === 'setWaitEligible') state.waitEligible = op.value === true;
+    else if (op.op === 'stop') cleanup();
+    else if (op.op === 'emit') process.emit(op.signal);
+    await settle();
+  }
+  await settle();
+  cleanup();
+  return { trace };
+}
+
+async function runCase(input) {
+  switch (input.kind) {
+    case 'constants':
+      return {
+        gracefulUpdateDrainSignal,
+        defaultGracefulUpdateDrainMaxWaitMs,
+        defaultGracefulUpdateDrainHardCapMs,
+        defaultGracefulUpdateDrainOverlapHardCapMs,
+        gracefulUpdateDrainActivityIdleMs,
+        gracefulUpdateDrainPollMs,
+        gracefulUpdateDrainWaitingLogIntervalMs,
+        defaultUpdateDrainHeldTurnMaxWaitMs,
+        updateDrainHeldTurnSweepIntervalMs,
+        updateRestartDrainRefusalPrefix,
+        updateRestartDrainRefusalReason,
+        updateRestartDrainHeldReason,
+        updateRestartDrainForcedKillReasonPrefix,
+        updateRestartDrainForcedKillReason,
+        updateRestartDrainForcedKillWaitingOnApprovalReason,
+      };
+    case 'resolveMaxWait':
+      return resolveGracefulUpdateDrainMaxWaitMs(envOf(input.env));
+    case 'resolveHardCap':
+      return resolveGracefulUpdateDrainHardCapMs(
+        envOf(input.env),
+        input.maxWaitMs ?? undefined,
+        input.generationOverlap === true
+      );
+    case 'resolveActivityIdle':
+      return resolveGracefulUpdateDrainActivityIdleMs(envOf(input.env));
+    case 'resolveHeldTurnMaxWait':
+      return resolveUpdateDrainHeldTurnMaxWaitMs(envOf(input.env));
+    case 'isRefusalError': {
+      const value =
+        input.errorKind === 'error'
+          ? new Error(input.message)
+          : input.errorKind === 'string'
+            ? input.message
+            : input.errorKind === 'number'
+              ? input.number
+              : input.errorKind === 'null'
+                ? null
+                : undefined;
+      return isUpdateRestartDrainRefusalError(value);
+    }
+    case 'classifyHold': {
+      const decision = classifyUpdateDrainStartHold({
+        controlType: input.controlType,
+        channel: input.channel ?? undefined,
+        threadId: input.threadId ?? undefined,
+        sourceSeq: input.sourceSeq ?? undefined,
+        workDescription: input.workDescription ?? undefined,
+        workspace: input.workspace ?? undefined,
+        codexThreadId: input.codexThreadId ?? undefined,
+        cwd: input.cwd ?? undefined,
+        agentProvider: input.agentProvider ?? undefined,
+        hasRegistryRecord: input.hasRegistryRecord === true,
+      });
+      return { hold: decision.hold, refuse: decision.hold ? null : decision.refuse };
+    }
+    case 'routeSigterm':
+      return shouldRouteSigtermThroughGracefulUpdateDrain({
+        supervised: input.supervised === true,
+        platform: input.platform,
+      });
+    case 'forceExitVerdict': {
+      const verdict = updateDrainForceExitVerdict({
+        waitedMs: input.waitedMs,
+        maxWaitMs: input.maxWaitMs,
+        hardCapMs: input.hardCapMs,
+        nowMs: input.nowMs,
+        lastActivityAtMs: input.lastActivityAtMs ?? undefined,
+        activityIdleMs: input.activityIdleMs ?? undefined,
+      });
+      return {
+        force: verdict.force,
+        cause: verdict.force ? verdict.cause : null,
+        idleMs: verdict.force ? (verdict.idleMs ?? null) : null,
+        shouldForce: updateDrainShouldForceExit({
+          waitedMs: input.waitedMs,
+          maxWaitMs: input.maxWaitMs,
+          hardCapMs: input.hardCapMs,
+          nowMs: input.nowMs,
+          lastActivityAtMs: input.lastActivityAtMs ?? undefined,
+          activityIdleMs: input.activityIdleMs ?? undefined,
+        }),
+      };
+    }
+    case 'drainStepsRun':
+      return runDrainStepsCase(input);
+    case 'sigtermDrainRun':
+      return runSigtermDrainCase(input);
+    case 'updateDrainRun':
+      return runUpdateDrainCase(input);
+    default:
+      return { error: 'unknown case kind ' + String(input.kind) };
+  }
+}
+
+async function runBatch() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const cases = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  const results = [];
+  for (const testCase of cases) {
+    results.push(await runCase(testCase));
+  }
+  process.stdout.write(JSON.stringify(results), () => {
+    process.exit(0);
+  });
+}
+
+runBatch().then(
+  () => {},
+  (error) => {
+    process.stderr.write(String(error && error.stack ? error.stack : error) + '\\n');
+    process.exit(1);
+  }
+);
+`;
+
+const outDir = join(packageRoot, '.differential');
+const outPath = join(outDir, 'core-lifecycle-guards-parity-oracle.mjs');
+
+await mkdir(outDir, { recursive: true });
+
+await build({
+  stdin: {
+    contents: driverSource,
+    resolveDir: packageRoot,
+    sourcefile: 'core-lifecycle-guards-parity-driver.ts',
+    loader: 'ts',
+  },
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: outPath,
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  logLevel: 'silent',
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+});
+
+process.stdout.write(outPath + '\n');