elanous 0.2.35 → 0.2.37

package/scripts/release-loop/resume-release.ts

@@ -2,11 +2,12 @@
 // The saved version-release output is re-pointed at the new branch tip (fast-forward only, state backed up first), so
 // every later node reads the repaired commit without anyone hand-editing the run state.
 import { spawnSync } from 'node:child_process';
-import { constants, copyFileSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { accessSync, closeSync, constants, copyFileSync, existsSync, fstatSync, openSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { debug } from '../../src/debug/log.js';
 import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
-import { lastJsonObject, runGraph, verifyReleaseCommandRoot, type GraphRunState } from '../../src/graph-runner/runner.js';
+import { lastJsonObject, runGraph, verifyReleaseCommandRoot, verifyReleaseRecipeSnapshot, type GraphRunState } from '../../src/graph-runner/runner.js';
 import { withOpSeatFlock } from '../../src/steward/resync-tick.js';
 import { releaseRunUniverse } from './release-universe.js';
 import { isReleaseVersion } from './release-version.js';
@@ -14,6 +15,8 @@ import { changedFilesBetween, clearPartialPlan, planPartialRegate, planStalledSh
 import { gitClosureTree, testsReachingChanged, TRACEABLE_RELEASE_JSON, type ClosureTree } from './gate-closure.js';
 import { releaseResumeAcceptedRegressions, releaseResumeGateExecutor, releaseResumeGatePodPool, releaseResumeWaiver, type AcceptedRegression } from './resume.js';
 import { reserveReleaseResumeAttempt } from './resume-cap.js';
+import { releaseLoopConfig } from './unattended-release.js';
+import { trafficOptionsFromConfig } from './traffic-transition.js';
 
 const GRAPH = join(import.meta.dir, '../../graphs/release/release-loop.yaml');
 
@@ -36,6 +39,8 @@ export interface ResumeReleaseDeps {
   closureTree?: (commit: string) => ClosureTree;
   /** Source observation before the first resumed node. */
   onSource?: (line: string) => void;
+  /** Test seam; production resolves this from ELANOUS_RELEASE_TRAFFIC_FILE / release.loop.trafficFile. */
+  trafficFile?: string;
 }
 
 export interface ResumeReleaseOptions {
@@ -47,7 +52,7 @@ export interface ResumeReleaseOptions {
 export interface ResumeReleasePlan {
   runId: string; version: string; fromNode: string; commandRoot: string; tip: TipRefresh;
   partial: PartialOutcome; gatePlan: { mode: 'not-run' | 'partial' | 'full'; reason?: string };
-  nextAttempt: number; attemptLimit: 2; preflight: 'passed';
+  nextAttempt: number; priorCountKnown: boolean; preflight: 'passed';
 }
 
 /** CLI entry files: a production file that only names one (help text, a goal's command line) does not run it. */
@@ -79,12 +84,12 @@ function safeRunId(runId: string): string {
   return runId;
 }
 
-/** Point the saved version-release output at the current release/<v> tip (fast-forward of the recorded commit only). */
+/** Lower-level maintenance primitive; the resume entrypoints run verifyResumePreflight before calling it. */
 export function refreshReleaseBranchTip(runId: string, deps: ResumeReleaseDeps = {}, from?: string, waiverCommit?: string): TipRefresh {
   return refreshReleaseBranchTipInternal(runId, deps, from, waiverCommit, false);
 }
 
-function refreshReleaseBranchTipInternal(runId: string, deps: ResumeReleaseDeps, from: string | undefined, waiverCommit: string | undefined, dryRun: boolean): TipRefresh {
+function refreshReleaseBranchTipInternal(runId: string, deps: ResumeReleaseDeps, from: string | undefined, waiverCommit: string | undefined, dryRun: boolean, expectedTip?: string): TipRefresh {
   const root = deps.root ?? effectiveInstanceRoot();
   const statePath = join(root, 'graph-runs', 'release-loop', `${safeRunId(runId)}.json`);
   const state = JSON.parse(readFileSync(statePath, 'utf8')) as GraphRunState;
@@ -108,6 +113,7 @@ function refreshReleaseBranchTipInternal(runId: string, deps: ResumeReleaseDeps,
   const git = deps.git ?? gitRunner(deps.repo ?? process.cwd());
   const advertised = git(['ls-remote', '--heads', 'origin', `refs/heads/${branch}`]).split(/\s+/)[0] ?? '';
   if (!/^[0-9a-f]{40}$/i.test(advertised)) throw new Error(`${branch} is not on origin — this run was not cut as a release branch`);
+  if (expectedTip && advertised.toLowerCase() !== expectedTip.toLowerCase()) throw new Error(`${branch} moved during pin preflight (${expectedTip} → ${advertised}) — retry resume`);
   let to: string;
   if (dryRun) {
     // Use the advertised object id directly: a preflight must not create/update local remote-tracking refs.
@@ -126,7 +132,7 @@ function refreshReleaseBranchTipInternal(runId: string, deps: ResumeReleaseDeps,
   }
   // A repair only appends (`cut-branch --append`): anything but a fast-forward is a different release.
   if (!(deps.isAncestor ?? ancestorRunner(deps.repo ?? process.cwd()))(recorded, to)) {
-    throw new Error(`${branch} tip ${to} does not descend from the recorded release commit ${recorded} — refusing to resume`);
+    throw new Error(`${branch} tip ${to} does not descend from the recorded release commit ${recorded} — refusing to resume; remedy: inspect both commits and create a new release run from the intended pinned tip`);
   }
   // A new tip invalidates everything built from the old one (gate verdict, prepared archive, …): restart no later
   // than the first node that consumed the commit, so each of them runs again on the new tip.
@@ -152,6 +158,130 @@ function refreshReleaseBranchTipInternal(runId: string, deps: ResumeReleaseDeps,
   return { version, branch, from: recorded, to, changed: true, statePath, backup };
 }
 
+/** Check the saved graph and recipes before fetch, backup, or run-ledger writes. */
+function verifyResumeRecipePin(commandRoot: string, snapshot: GraphRunState['graphSnapshot'], version: string): void {
+  try { verifyReleaseRecipeSnapshot(commandRoot, snapshot); }
+  catch (error) {
+    if (!snapshot) throw error;
+    const mismatches: string[] = [];
+    for (const [name, savedSha] of [
+      ['release-loop.yaml', snapshot.graphSha], ['recipes.yaml', snapshot.recipesSha],
+    ] as const) {
+      const file = join(commandRoot, 'graphs', 'release', name);
+      let currentSha: string;
+      try { currentSha = createHash('sha256').update(readFileSync(file)).digest('hex'); }
+      catch { continue; }
+      if (currentSha !== savedSha) mismatches.push(`${file} saved=${savedSha} current=${currentSha}`);
+    }
+    if (!mismatches.length) throw error;
+    throw new Error(`release recipe source differs from saved pin: ${mismatches.join('; ')}\nremedy: start a new pinned run with eln release run --version ${version}`, { cause: error });
+  }
+}
+
+/** Common read-only gate for dry-run and actual resume. Every rejection includes an operator action. */
+function verifyResumePreflight(run: GraphRunState, opts: ResumeReleaseOptions, deps: ResumeReleaseDeps,
+  version: string, recordedCommit: string, currentTip: string, commandRoot: string): void {
+  let trafficFile = deps.trafficFile;
+  if (trafficFile === undefined) {
+    try { trafficFile = trafficOptionsFromConfig(process.env, releaseLoopConfig()).trafficFile; }
+    catch (error) { throw new Error(`cannot read release traffic configuration — remedy: repair release.loop.trafficFile in the active config before resuming`, { cause: error }); }
+  }
+  if (!trafficFile) throw new Error('release.loop.trafficFile is not configured — remedy: set release.loop.trafficFile or ELANOUS_RELEASE_TRAFFIC_FILE before resuming');
+  let fd: number | undefined;
+  try {
+    const path = resolve(trafficFile);
+    const info = statSync(path);
+    if (!info.isFile() || (info.mode & 0o222) === 0) throw new Error('not a writable regular file');
+    fd = openSync(path, constants.O_WRONLY);
+    if (!fstatSync(fd).isFile()) throw new Error('not a regular file');
+    accessSync(path, constants.R_OK | constants.W_OK);
+  } catch (error) {
+    throw new Error(`release traffic file is missing or not writable: ${trafficFile} (${error instanceof Error ? error.message : String(error)}) — remedy: create a regular writable traffic file and set release.loop.trafficFile`, { cause: error });
+  } finally { if (fd !== undefined) closeSync(fd); }
+
+  for (const path of [join(commandRoot, 'node_modules'), join(commandRoot, 'apps', 'pwa', 'node_modules')]) {
+    try { if (!statSync(path).isDirectory()) throw new Error('not a directory'); }
+    catch (error) { throw new Error(`release resume dependencies missing: ${path} — remedy: run bun install --frozen-lockfile at repository root and apps/pwa`, { cause: error }); }
+  }
+
+  const nodeOutput = (nodeId: string): Record<string, unknown> | undefined => {
+    const node = run.nodes.find((entry) => entry.nodeId === nodeId);
+    if (!node?.ok || typeof node.output !== 'string') return undefined;
+    try { return lastJsonObject(node.output) as Record<string, unknown> | undefined; } catch { return undefined; }
+  };
+  const recordedNodeOutput = (nodeId: string): Record<string, unknown> | undefined => {
+    const node = run.nodes.find((entry) => entry.nodeId === nodeId);
+    if (typeof node?.output !== 'string') return undefined;
+    try { return lastJsonObject(node.output) as Record<string, unknown> | undefined; } catch { return undefined; }
+  };
+  const roots = [...new Set([deps.root ?? effectiveInstanceRoot(), deps.ledgerRoot ?? releaseLedgerRoot()])];
+  for (const root of roots) {
+    const prepared = join(root, 'release', version, 'prepared');
+    if (existsSync(prepared)) {
+      const record = nodeOutput('prepare');
+      const output = record && typeof record.out === 'string' ? record : undefined;
+      const manifestPath = join(prepared, 'release.json');
+      let manifest: { version?: unknown; sourceCommit?: unknown } | undefined;
+      try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as typeof manifest; } catch { /* fail closed below */ }
+      const ownerPath = join(prepared, '.release-node-owner.json');
+      let owner: { runId?: unknown; commit?: unknown } | undefined;
+      let ownerReadable = !existsSync(ownerPath);
+      try { owner = JSON.parse(readFileSync(ownerPath, 'utf8')) as typeof owner; ownerReadable = true; } catch { /* old artifacts can be owned by the run ledger */ }
+      const ledgerOwns = output?.out === prepared && output.commit === currentTip && output.outcome === 'ok';
+      const receiptOwns = owner ? owner.runId === opts.runId && owner.commit === currentTip : ownerReadable && ledgerOwns;
+      if (!ledgerOwns || manifest?.version !== version || manifest.sourceCommit !== currentTip || !receiptOwns) {
+        throw new Error(`prepared artifact is outside the current release run ledger: ${prepared} — remedy: preserve it, compare release.json and .release-node-owner.json with run ${opts.runId}, then resolve ownership before resume`);
+      }
+    }
+
+    const receiptPath = join(root, 'release', version, 'docs-branch-owner.json');
+    const docsBranch = `release-docs/${version}`;
+    let receipt: { owner?: { runId?: unknown; attempt?: unknown }; branch?: unknown; worktree?: unknown; outcome?: unknown; head?: unknown } | undefined;
+    try { receipt = JSON.parse(readFileSync(receiptPath, 'utf8')) as typeof receipt; } catch { /* no/invalid receipt is rejected if an artifact exists */ }
+    const docsRecord = recordedNodeOutput('docs');
+    const worktree = typeof docsRecord?.worktree === 'string' ? docsRecord.worktree : undefined;
+    let localBranch: string | undefined;
+    try { localBranch = (deps.git ?? gitRunner(deps.repo ?? process.cwd()))(['show-ref', '--verify', '--hash', `refs/heads/${docsBranch}`]).trim(); } catch { /* absent */ }
+    let docsWorktrees: string[] = [];
+    try {
+      const listing = (deps.git ?? gitRunner(deps.repo ?? process.cwd()))(['worktree', 'list', '--porcelain']);
+      docsWorktrees = listing.split(/\n\n+/).filter(Boolean).flatMap((entry) => {
+        const branch = /^branch (.+)$/m.exec(entry)?.[1];
+        const path = /^worktree (.+)$/m.exec(entry)?.[1];
+        return branch === `refs/heads/${docsBranch}` && path ? [path] : [];
+      });
+    } catch (error) {
+      throw new Error(`cannot inspect release worktrees for ${docsBranch} — remedy: restore read-only git access and retry resume`, { cause: error });
+    }
+    let remoteHead: string | undefined;
+    try {
+      const response = (deps.git ?? gitRunner(deps.repo ?? process.cwd()))(['ls-remote', '--heads', 'origin', `refs/heads/${docsBranch}`]);
+      const line = response.split(/\r?\n/).find((candidate) => candidate.trim().endsWith(`refs/heads/${docsBranch}`));
+      remoteHead = line?.trim().split(/\s+/)[0];
+    } catch (error) {
+      throw new Error(`cannot inspect docs branch ${docsBranch} — remedy: restore read-only git access and retry resume`, { cause: error });
+    }
+    const hasDocsArtifact = existsSync(receiptPath) || !!localBranch || !!remoteHead || docsWorktrees.length > 0;
+    const outputOwner = docsRecord?.artifactOwner as { runId?: unknown; attempt?: unknown } | undefined;
+    const receiptMatches = receipt?.branch === docsBranch && receipt.owner?.runId === opts.runId
+      && receipt.owner.attempt === outputOwner?.attempt && outputOwner?.runId === opts.runId
+      && typeof receipt.worktree === 'string' && worktree === receipt.worktree && docsWorktrees.includes(receipt.worktree)
+      && existsSync(receipt.worktree);
+    if (hasDocsArtifact && !receiptMatches) {
+      throw new Error(`docs branch/worktree is outside the current release run ledger: ${docsBranch} — remedy: compare ${receiptPath} with the saved docs node output and resolve ownership before resume`);
+    }
+    if (receipt?.outcome === 'pushed' && (!/^[0-9a-f]{40}$/i.test(String(receipt.head ?? ''))
+      || remoteHead?.toLowerCase() !== String(receipt.head).toLowerCase())) {
+      throw new Error(`docs branch tip differs from the saved ownership receipt: ${docsBranch} — remedy: preserve the branch and worktree, compare the remote tip with ${receiptPath} and the saved docs node output, then resolve ownership before resume`);
+    }
+  }
+
+  const recorded = nodeOutput('version-release');
+  if (recorded?.branch !== `release/${version}` || recorded.commit !== recordedCommit || !/^[0-9a-f]{40}$/i.test(currentTip)) {
+    throw new Error(`release branch tip does not match the saved version-release ledger for ${version} — remedy: inspect the branch and saved run ${opts.runId}, then resume from a node before gate only after resolving the mismatch`);
+  }
+}
+
 /** GATE-PARTIAL outcome of a resume — applied (plan written) or the reason it fell back to a full gate. `auto` marks the
  *  default plan of `--from gate` (GATE-REUSE-BY-DIFF); `closure` is set when code changes were followed. */
 export type PartialOutcome = { requested: false }
@@ -318,7 +448,7 @@ async function planResumeReleaseRunLocked(opts: ResumeReleaseOptions, deps: Resu
   const waiver = original && (opts.waive !== undefined || opts.reason !== undefined) ? releaseResumeWaiver(original, opts) : undefined;
   if (original && opts.acceptedRegressions !== undefined && !waiver)
     releaseResumeAcceptedRegressions(original, opts.acceptedRegressions, opts.from);
-  const attempt = reserveReleaseResumeAttempt(savedRun, deps.root!, { now: deps.now, checkOnly: true, noDecision: true });
+  const attempt = reserveReleaseResumeAttempt(savedRun, deps.root!, { now: deps.now, checkOnly: true });
   let waiverCommit: string | undefined;
   if (waiver) {
     const output = lastJsonObject(savedRun.nodes.find((node) => node.nodeId === 'version-release')?.output);
@@ -331,7 +461,9 @@ async function planResumeReleaseRunLocked(opts: ResumeReleaseOptions, deps: Resu
     waiverCommit = recorded;
   }
   const tip = refreshReleaseBranchTipInternal(opts.runId, deps, opts.from, waiverCommit, true);
+  verifyResumeRecipePin(opts.commandRoot ?? process.cwd(), savedRun.graphSnapshot, tip.version);
   const commandRoot = verifyReleaseCommandRoot(opts.commandRoot ?? process.cwd(), tip.to, deps.git);
+  verifyResumePreflight(savedRun, opts, deps, tip.version, tip.from, tip.to, commandRoot);
   const partial = preparePartial(tip, opts, deps, true);
   const fromIndex = savedRun.path.indexOf(opts.from);
   const gateIndex = savedRun.path.indexOf('gate');
@@ -340,7 +472,7 @@ async function planResumeReleaseRunLocked(opts: ResumeReleaseOptions, deps: Resu
     : partial.requested && partial.applied ? { mode: 'partial' as const }
       : { mode: 'full' as const, reason: partial.requested ? partial.reason : opts.partial === false ? 'partial recheck disabled' : 'no partial plan applies' };
   return { runId: opts.runId, version: tip.version, fromNode: opts.from, commandRoot, tip, partial,
-    gatePlan, nextAttempt: attempt.attempt, attemptLimit: 2, preflight: 'passed' };
+    gatePlan, nextAttempt: attempt.attempt, priorCountKnown: attempt.priorCountKnown, preflight: 'passed' };
 }
 
 async function resumeReleaseRunLocked(opts: ResumeReleaseOptions, deps: ResumeReleaseDeps): Promise<{ tip: TipRefresh; partial: PartialOutcome; state: GraphRunState }> {
@@ -368,7 +500,7 @@ async function resumeReleaseRunLocked(opts: ResumeReleaseOptions, deps: ResumeRe
   const acceptedRegressions = original && opts.acceptedRegressions !== undefined && !waiver
     ? releaseResumeAcceptedRegressions(original, opts.acceptedRegressions, opts.from) : undefined;
   if (savedRun.graphId !== 'release-loop' || savedRun.runId !== opts.runId) throw new Error(`run identity mismatch: ${statePath}`);
-  // Validate request arguments before the cap, then block the third attempt before tip refresh.
+  // Validate request arguments before the tip refresh; the count is observational.
   reserveReleaseResumeAttempt(savedRun, deps.root!, { now: deps.now, checkOnly: true });
   // A waived verdict may reuse its original commit. A moved tip still requires a full re-gate.
   if (waiver) {
@@ -383,13 +515,17 @@ async function resumeReleaseRunLocked(opts: ResumeReleaseOptions, deps: ResumeRe
     if (advertised?.toLowerCase() !== recorded.toLowerCase()) throw new Error('release branch moved — re-gate the new tip before waiving a node');
     waiverCommit = recorded;
   }
-  // Check the refreshed tip before refresh writes a new version-release record or backup.
-  const tip = refreshReleaseBranchTip(opts.runId, deps, opts.from, waiverCommit);
-  const commandRoot = verifyReleaseCommandRoot(opts.commandRoot ?? process.cwd(), tip.to, deps.git);
+  // The read-only tip and recipe pin preflight must pass before fetch or a saved-run rewrite.
+  const previewTip = refreshReleaseBranchTipInternal(opts.runId, deps, opts.from, waiverCommit, true);
+  verifyResumeRecipePin(opts.commandRoot ?? process.cwd(), savedRun.graphSnapshot, previewTip.version);
+  const commandRoot = verifyReleaseCommandRoot(opts.commandRoot ?? process.cwd(), previewTip.to, deps.git);
+  verifyResumePreflight(savedRun, opts, deps, previewTip.version, previewTip.from, previewTip.to, commandRoot);
+  const tip = refreshReleaseBranchTipInternal(opts.runId, deps, opts.from, waiverCommit, false, previewTip.to);
   const partial = preparePartial(tip, opts, deps);
-  // A failed preflight does not consume one of the two release resume attempts.
+  // A failed preflight does not consume an observed release resume attempt.
   const attempt = reserveReleaseResumeAttempt(savedRun, deps.root!, { now: deps.now });
-  debug.log('release-loop.resume', 'attempt', { runId: opts.runId, attempt: attempt.attempt, limit: 2, ledger: attempt.path });
+  debug.log('release-loop.resume', 'attempt', { runId: opts.runId, attempt: attempt.attempt,
+    priorCountKnown: attempt.priorCountKnown, ledger: attempt.path });
   // Resume the graph at the path it was started from (its snapshot is used); only tests inject another path.
   const graphPath = deps.graphPath ?? savedGraphPath(tip.statePath) ?? GRAPH;
   const savedSource = JSON.parse(readFileSync(tip.statePath, 'utf8')) as GraphRunState;

package/scripts/release-loop/resume-test-traffic.ts

@@ -0,0 +1,10 @@
+// Resume tests need the same writable traffic-file prerequisite as the installed release configuration.
+// This module is imported only by test files; the gate process owns and discards this environment.
+import { rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const trafficFile = join(tmpdir(), `elanous-resume-test-traffic-${process.pid}.json`);
+writeFileSync(trafficFile, '{}\n');
+process.env.ELANOUS_RELEASE_TRAFFIC_FILE = trafficFile;
+process.once('exit', () => rmSync(trafficFile, { force: true }));

package/scripts/release-loop/traffic-node.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env bun
+import { spawnSync } from 'node:child_process';
+import { debug } from '../../src/debug/log.js';
+import { SPAWN_SYNC_MAX_BUFFER } from '../../src/util/spawn-sync-output.js';
+import { releaseLoopConfig } from './unattended-release.js';
+import { errorResult, finishNode, readGraphContext } from './node-verdict.js';
+import { applyReleaseTrafficEvent, trafficOptionsFromConfig, type ReleaseTrafficEvent, type TrafficTransitionOptions } from './traffic-transition.js';
+
+const EVENTS: Record<string, ReleaseTrafficEvent> = {
+  'traffic-gate-passed': 'gate-passed',
+  'traffic-verify-complete': 'verify-complete',
+};
+
+export interface TrafficNodeDeps {
+  options?: TrafficTransitionOptions;
+  report?: (body: string) => void;
+}
+
+function reportFailure(body: string): void {
+  const result = spawnSync('eln', ['msg', 'post', '--from', 'MK', '--to', 'OP', '--kind', 'report', '--body', body], { encoding: 'utf8', timeout: 10_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER });
+  if (result.status !== 0 || result.error) process.stderr.write(`traffic OP mail failed: ${result.stderr || result.error || result.status}\n`);
+}
+
+/** Traffic transitions are warning-only for the release graph, but their node result remains truthful. */
+export async function runTrafficNode(node = process.argv[2], env: NodeJS.ProcessEnv = process.env, deps: TrafficNodeDeps = {}): Promise<number> {
+  let version = '';
+  let runId = '';
+  try {
+    const context = readGraphContext(env);
+    version = context.input.version;
+    runId = context.runId ?? '';
+    const event = EVENTS[node ?? ''];
+    if (!event || context.nodeId !== node) throw new Error(`traffic node context mismatch: ${node ?? 'missing'}`);
+    const options = deps.options ?? trafficOptionsFromConfig(env, releaseLoopConfig());
+    if (!options.trafficFile) {
+      const summary = `traffic-file-unset: ${event} skipped because trafficFile is not configured`;
+      debug.log('release-loop.traffic', 'traffic-file-unset', { runId, version, event, node, reason: summary });
+      (deps.report ?? reportFailure)(`RELEASE-POSTPUB-TRAFFIC ${version} ${runId || 'unknown'} ${node} ${summary}. Release traffic was not changed.`);
+      return finishNode(node!, version, { outcome: 'fail', verdict: 'fail', summary });
+    }
+    const result = await applyReleaseTrafficEvent(context, event, options);
+    if (!result.applied) {
+      const consequence = event === 'verify-complete'
+        ? '릴리스 검증은 성공했으나 트래픽 복귀가 적용되지 않았습니다.'
+        : 'gate는 성공했으나 트래픽 감속이 적용되지 않았습니다.';
+      (deps.report ?? reportFailure)(`RELEASE-POSTPUB-TRAFFIC ${version} ${runId || 'unknown'} ${node} 무시 — ${result.reason ?? 'traffic state unchanged'}. ${consequence}`);
+    }
+    return finishNode(node!, version, { outcome: 'ok', verdict: 'pass', summary: `${event} ${result.applied ? 'applied' : result.reason ?? 'ignored'}` });
+  } catch (error) {
+    const detail = errorResult(error).summary;
+    const isLockTimeout = detail.startsWith('traffic lock timeout:');
+    const failure = isLockTimeout ? `traffic-lock-timeout · stale 의심 경로 ${detail.slice('traffic lock timeout:'.length).trim()}` : detail;
+    debug.log('release-loop.traffic', 'non-blocking-failure', { node: node ?? 'missing', version, reason: detail });
+    (deps.report ?? reportFailure)(`RELEASE-POSTPUB-TRAFFIC ${version || 'unknown'} ${runId || 'unknown'} ${node ?? 'unknown'} 실패 — ${failure}. 릴리스 판정은 계속 진행한다.`);
+    return finishNode(node ?? 'traffic', version, { outcome: 'fail', verdict: 'fail', summary: `traffic transition failed; release graph continues with warning: ${failure}` });
+  }
+}
+
+if (import.meta.main) process.exitCode = await runTrafficNode();

package/scripts/release-loop/traffic-transition.ts

@@ -0,0 +1,159 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+import type { GraphContext } from './node-verdict.js';
+import type { ReleaseLoopConfig } from './unattended-release.js';
+
+export type ReleaseTrafficEvent = 'gate-passed' | 'verify-complete';
+
+export interface TrafficFile {
+  global?: string;
+  seats: Record<string, Record<string, unknown>>;
+  releaseLifecycle?: { runId: string; version: string; stage: 1 | 2; event: ReleaseTrafficEvent; startedAt?: string; updatedAt: string };
+  [key: string]: unknown;
+}
+
+type ReleaseTrafficConfig = ReleaseLoopConfig & {
+  trafficFile?: string;
+};
+
+const SEATS = ['OP', 'TC', 'MK', 'UX'] as const;
+const STAGE: Record<ReleaseTrafficEvent, 1 | 2> = { 'gate-passed': 1, 'verify-complete': 2 };
+const TRAFFIC_PER_CYCLE = { half: 3, full: 6 } as const;
+
+export interface TrafficTransitionOptions {
+  trafficFile?: string;
+  lockTimeoutMs?: number;
+  now?: () => Date;
+  log?: (event: string, fields: Record<string, unknown>) => void;
+}
+
+function waitSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function acquireTrafficLock(path: string, timeoutMs = 10_000): () => void {
+  const lock = `${path}.lock.d`;
+  const deadline = Date.now() + timeoutMs;
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      mkdirSync(lock);
+      try { writeFileSync(`${lock}/pid`, `${process.pid}\n`, { flag: 'wx', mode: 0o600 }); }
+      catch (error) { rmSync(lock, { recursive: true, force: true }); throw error; }
+      return () => rmSync(lock, { recursive: true, force: true });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      try {
+        // A directory cannot be conditionally renamed by identity. Reclaiming after
+        // checking its PID can therefore move a replacement owner's live lock.
+        // Fail closed; OP can inspect and remove a stale lock after the warning mail.
+        readFileSync(`${lock}/pid`, 'utf8');
+        statSync(lock);
+      } catch { /* Unknown or concurrently changing locks are left intact. */ }
+      if (Date.now() >= deadline) throw new Error(`traffic lock timeout: ${lock}`);
+      waitSync(100);
+    }
+  }
+}
+
+function readTrafficFile(path: string): TrafficFile {
+  const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('traffic file must contain a JSON object');
+  const file = parsed as TrafficFile;
+  if (!file.seats || typeof file.seats !== 'object' || Array.isArray(file.seats)
+    || !SEATS.every((seat) => file.seats[seat] && typeof file.seats[seat] === 'object' && !Array.isArray(file.seats[seat]))) {
+    throw new Error('traffic seats object missing');
+  }
+  return file;
+}
+
+function atomicWriteTrafficFile(path: string, file: TrafficFile): void {
+  const temp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  const mode = statSync(path).mode & 0o777;
+  try {
+    writeFileSync(temp, `${JSON.stringify(file, null, 2)}\n`, { flag: 'wx', mode });
+    renameSync(temp, path);
+  } catch (error) {
+    rmSync(temp, { force: true });
+    throw error;
+  }
+}
+
+function compareReleaseVersions(left: string, right: string): number {
+  const parse = (value: string) => /^(\d+)\.(\d+)\.(\d+)(?:-(alpha|beta|rc)\.(\d+))?$/.exec(value);
+  const a = parse(left), b = parse(right);
+  if (!a || !b) return left.localeCompare(right);
+  for (const index of [1, 2, 3]) {
+    const delta = Number(a[index]) - Number(b[index]);
+    if (delta) return Math.sign(delta);
+  }
+  if (!a[4] || !b[4]) return a[4] ? -1 : b[4] ? 1 : 0;
+  const rank = { alpha: 0, beta: 1, rc: 2 } as const;
+  const kind = rank[a[4] as keyof typeof rank] - rank[b[4] as keyof typeof rank];
+  return kind || Math.sign(Number(a[5]) - Number(b[5]));
+}
+
+function isLaterRun(current: string | undefined, previous: string | undefined): boolean {
+  return Boolean(current && previous && current > previous);
+}
+
+/** Apply one monotonic release graph event while preserving unrelated traffic policy fields. */
+export async function applyReleaseTrafficEvent(
+  context: GraphContext,
+  event: ReleaseTrafficEvent,
+  options: TrafficTransitionOptions,
+): Promise<{ applied: boolean; stage: number; reason?: string }> {
+  if (!context.runId) throw new Error('release traffic event requires graph runId');
+  if (!options.trafficFile) throw new Error('traffic file path is not configured');
+  const runId = context.runId;
+  const version = context.input.version;
+  const path = resolve(options.trafficFile);
+  if (!existsSync(path)) throw new Error(`traffic file does not exist: ${path}`);
+  const log = options.log ?? ((name, fields) => debug.log('release-loop.traffic', name, fields));
+  const stage = STAGE[event];
+  const stamp = (options.now ?? (() => new Date()))().toISOString();
+  const rate = event === 'gate-passed' ? TRAFFIC_PER_CYCLE.half : TRAFFIC_PER_CYCLE.full;
+  const releaseLifecycle = { runId, version, stage, event, ...(context.startedAt ? { startedAt: context.startedAt } : {}), updatedAt: stamp };
+  const release = () => {
+    const unlock = acquireTrafficLock(path, options.lockTimeoutMs);
+    try {
+      const before = readTrafficFile(path);
+      const prior = before.releaseLifecycle;
+      const sameRun = prior?.runId === runId;
+      const newerVersion = !prior?.runId || compareReleaseVersions(version, prior.version) > 0;
+      const sameVersionLaterRun = prior?.version === version && isLaterRun(context.startedAt, prior.startedAt);
+      if (sameRun && prior.stage >= stage) return { file: before, applied: true, idempotent: true };
+      const permitted = sameRun
+        ? prior.stage === stage - 1
+        : newerVersion || (event === 'gate-passed' && prior?.version === version && (prior.stage ?? 0) < 2 && sameVersionLaterRun)
+          || (event === 'verify-complete' && prior?.version === version && sameVersionLaterRun);
+      if (!permitted) {
+        return { file: before, applied: false, idempotent: false, reason: prior?.runId && prior.runId !== runId ? 'different-run-is-current' : 'event-out-of-order' };
+      }
+      const after: TrafficFile = {
+        ...before,
+        ...(event === 'verify-complete' ? { global: 'green' } : {}),
+        seats: Object.fromEntries(Object.entries(before.seats).map(([seat, value]) => [
+          seat, SEATS.includes(seat as typeof SEATS[number]) ? { ...value, perCycle: rate } : value,
+        ])),
+        releaseLifecycle,
+      };
+      atomicWriteTrafficFile(path, after);
+      return { file: after, applied: true, idempotent: false };
+    } finally { unlock(); }
+  };
+  const result = release();
+  const reason = result.applied && result.idempotent ? 'already-applied' : result.reason;
+  log(result.idempotent ? 'already-applied' : result.applied ? 'applied' : 'ignored', {
+    runId, version, event, stage, reason, perCycle: rate, ...(event === 'verify-complete' ? { global: 'green' } : {}),
+  });
+  return { applied: result.applied, stage: result.file.releaseLifecycle?.stage ?? 0, ...(reason ? { reason } : {}) };
+}
+
+export function trafficOptionsFromConfig(env: NodeJS.ProcessEnv = process.env, rawConfig: ReleaseLoopConfig = {}): TrafficTransitionOptions {
+  const config = rawConfig as ReleaseTrafficConfig;
+  const envTrafficFile = env.ELANOUS_RELEASE_TRAFFIC_FILE?.trim();
+  const configTrafficFile = typeof config.trafficFile === 'string' ? config.trafficFile.trim() : undefined;
+  const trafficFile = envTrafficFile || configTrafficFile;
+  return trafficFile ? { trafficFile } : {};
+}