elanous 0.2.42 → 0.2.44

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

@@ -29,6 +29,8 @@ type TranslationRunner = (line: string) => string;
 type AskSpawn = (command: string, args: string[], options: SpawnSyncOptionsWithStringEncoding) => SpawnSyncReturns<string>;
 
 const HANGUL = /[\uac00-\ud7a3]/;
+// Allow common English typography without accepting arbitrary non-ASCII letters, digits, or symbols.
+const PUBLIC_TRANSLATION_NON_ASCII = /[^\x00-\x7f\u00a0\u00a1\u00ab\u00b7\u00bb\u00bf\u2010-\u2015\u2018-\u201f\u2022\u2026]/u;
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
 
 function splitMarkdownPrefix(raw: string): { prefix: string; text: string } {
@@ -130,8 +132,8 @@ function translatePublicText(text: string, runner: TranslationRunner, failures:
       try {
         const candidate = runner(source).trim();
         const alphanumeric = [...candidate].filter((character) => /[\p{L}\p{N}]/u.test(character));
-        if (!candidate || HANGUL.test(candidate) || alphanumeric.length === 0 || /[^\x00-\x7f]/.test(candidate)) {
-          throw new Error('translation is empty or contains non-Latin writing');
+        if (!candidate || HANGUL.test(candidate) || alphanumeric.length === 0 || PUBLIC_TRANSLATION_NON_ASCII.test(candidate)) {
+          throw new Error('translation is empty or contains unsupported non-ASCII characters');
         }
         translated = candidate;
         cache.set(source, candidate);

package/scripts/release-loop/gate-autoheal-sim-evidence.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+/**
+ * Isolated E4 evidence bridge: GATE-MOCK-EVENT-SCENARIOS fake devices plus the production
+ * runGateNode autoheal decision/log path. It never starts a release run or a real Pod.
+ */
+import { mkdirSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { debug } from '../../src/debug/log.js';
+import { setElanousConfigDir } from '../../src/elanous-config-dir.js';
+import { registerStandaloneLogSink } from '../../src/domains/standalone-log-sink.js';
+import { prodInstanceRoot } from '../../src/instance/resolve.js';
+import { runGateNode, type GateResult } from './gate-node.js';
+import { GATE_NODE_SIM_SCENARIOS, judgeInjectedGateEvent } from './gate-node-sim.js';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const testRoot = join(repoRoot, '.elanous-test');
+const runId = `gate-autoheal-sim-${new Date().toISOString().replace(/[-:.TZ]/g, '')}`;
+
+if (realpathSync(repoRoot) === realpathSync(prodInstanceRoot())) {
+  throw new Error('refusing to run evidence simulation from the production state root');
+}
+if (process.env.ELANOUS_STATE_DIR && resolve(process.env.ELANOUS_STATE_DIR) !== resolve(testRoot)) {
+  throw new Error(`ELANOUS_STATE_DIR must be this worktree test root: ${testRoot}`);
+}
+
+const scenario = GATE_NODE_SIM_SCENARIOS.find((item) => item.id === 'host-down-reroute');
+if (!scenario) throw new Error('GATE-MOCK-EVENT-SCENARIOS is missing host-down-reroute');
+const simulated = await judgeInjectedGateEvent(scenario);
+if (simulated.outcome !== scenario.expectedOutcome || simulated.action !== scenario.action || simulated.podCommandCalls !== 0) {
+  throw new Error(`fake-device scenario did not match: ${JSON.stringify(simulated)}`);
+}
+
+mkdirSync(testRoot, { recursive: true });
+process.env.ELANOUS_STATE_DIR = testRoot;
+process.env.ELANOUS_RUN_ID = runId;
+process.env.ELANOUS_GRAPH_CONTEXT = JSON.stringify({
+  runId,
+  input: { version: '0.2.43', previousVersion: '0.2.42', commit: 'a'.repeat(40) },
+  outputs: {},
+});
+setElanousConfigDir(testRoot);
+
+if (!await registerStandaloneLogSink('release-loop')) throw new Error('could not register isolated release-loop logs.db sink');
+
+// Inject the same host-unreachable failure class through the production node's judge seam. runGateNode
+// performs the real cause classification, budgeted decision, ledger write, and debug.log emission.
+const injectedFailure: GateResult = {
+  outcome: 'error', commit: 'a'.repeat(40), introduced: [], preexisting: 0, fixed: 0,
+  knownEnv: 0, knownEnvCleared: [], stalledEnv: [], rcNonzeroNoFailures: [], durationMs: 1_000,
+  error: 'gate host unreachable (simulation injection)',
+};
+const exitCode = await runGateNode(['--json'], process.env, undefined, async () => injectedFailure);
+if (exitCode !== 2) throw new Error(`expected injected gate error exit=2, got ${exitCode}`);
+debug.flush();
+
+console.log(JSON.stringify({ label: 'simulation E4', runId, scenario: scenario.id,
+  scenarioOutcome: simulated.outcome, plannerAction: simulated.action, podCommandCalls: simulated.podCommandCalls,
+  injectedCause: 'host-down', expectedAutohealAction: 'host-switch', exitCode,
+  store: join(testRoot, 'logs/logs.db') }));

package/scripts/release-loop/gate-image-pin.ts

@@ -1,5 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { constants } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
 
 /** A gate run may execute only against one immutable image identity and its exact source tag. */
 export interface GateImagePin { runId: string; digest: string; image: string; commit: string }
@@ -17,7 +19,68 @@ export interface ResolveGateImagePinOptions {
   poolImages: ReadonlyMap<string, readonly string[]>;
 }
 
-function normalizeGateImageDigest(value: unknown): string | null {
+interface PinnedGateImagePullDecision {
+  push: false;
+  imageRef: string;
+  tagDrift?: { event: 'image-tag-drift'; runId: string; tag: string; pinnedDigest: string; observedDigest: string | null; reason: 'digest-changed' | 'tag-unavailable' };
+}
+
+export interface PinnedGateImageSyncResult {
+  images: Map<string, { ok: true; action: 'fresh'; detail: string; ms: 0; imageRef: string }>;
+  tagDrifts: Array<{ event: 'image-tag-drift'; runId: string; tag: string; pinnedDigest: string;
+    observedDigest: string | null; reason: 'digest-changed' | 'tag-unavailable'; context: string }>;
+}
+
+function imageRepository(image: string): string {
+  let repository = image.trim().replace(/@sha256:[a-f0-9]{64}$/i, '');
+  const firstSlash = repository.indexOf('/');
+  if (firstSlash > 0) {
+    const first = repository.slice(0, firstSlash);
+    if (first === 'localhost' || first.includes('.') || first.includes(':')) repository = repository.slice(firstSlash + 1);
+  }
+  return repository.replace(/:[^/:]+$/, '');
+}
+
+/** Build a Job image ref from the registry service visible inside a pool's Kubernetes cluster. */
+function pinnedGateImagePullDecision(input: {
+  runId: string; registry: string; image: string; digest: string; observedTagDigest?: string | null;
+}): PinnedGateImagePullDecision {
+  const digest = normalizeGateImageDigest(input.digest);
+  const registry = input.registry.trim().replace(/\/$/, '');
+  const repository = imageRepository(input.image);
+  if (!input.runId || !registry || !repository || repository.includes('@') || !digest) throw new Error('invalid pinned gate image pull identity');
+  const observed = normalizeGateImageDigest(input.observedTagDigest);
+  const tag = `${registry}/${repository}:${input.image.split(':').at(-1) ?? ''}`;
+  return {
+    push: false,
+    imageRef: `${registry}/${repository}@${digest}`,
+    ...(!observed || observed !== digest ? { tagDrift: { event: 'image-tag-drift', runId: input.runId,
+      tag, pinnedDigest: digest, observedDigest: observed, reason: observed ? 'digest-changed' as const : 'tag-unavailable' as const } } : {}),
+  };
+}
+
+/** Convert every selected gate member to a digest ref; this path deliberately has no build/push operation. */
+export function pinnedGateImageSync(input: {
+  runId: string; commit: string; digest: string; image: string;
+  members: readonly { context: string; registry: string }[];
+  probeTagDigest: (member: { context: string; registry: string }) => string | null;
+}): PinnedGateImageSyncResult {
+  const repository = imageRepository(input.image);
+  if (!/^[0-9a-f]{40}$/i.test(input.commit) || !repository || repository.includes('@')) throw new Error('invalid pinned gate image identity');
+  const tag = `${repository}:${input.commit.slice(0, 12)}`;
+  const images = new Map<string, { ok: true; action: 'fresh'; detail: string; ms: 0; imageRef: string }>();
+  const tagDrifts: PinnedGateImageSyncResult['tagDrifts'] = [];
+  for (const member of input.members) {
+    const decision = pinnedGateImagePullDecision({ runId: input.runId, registry: member.registry, image: tag,
+      digest: input.digest, observedTagDigest: input.probeTagDigest(member) });
+    images.set(member.context, { ok: true, action: 'fresh', detail: 'run-pinned-digest; tag push skipped', ms: 0,
+      imageRef: decision.imageRef });
+    if (decision.tagDrift) tagDrifts.push({ ...decision.tagDrift, context: member.context });
+  }
+  return { images, tagDrifts };
+}
+
+export function normalizeGateImageDigest(value: unknown): string | null {
   if (typeof value !== 'string' || !/^sha256:[a-f0-9]{64}$/i.test(value.trim())) return null;
   return value.trim().toLowerCase();
 }
@@ -52,6 +115,57 @@ export function readGateImagePin(path: string, expectedRunId: string, expectedIm
   return { runId: expectedRunId, digest: normalizeGateImageDigest(parsed.digest)!, image: expectedImage, commit: normalizedCommit };
 }
 
+/** Read a valid pin for this run and image repository while allowing its commit tag to be stale. */
+export function readGateImagePinForRun(path: string, expectedRunId: string, expectedImage: string): GateImagePin | null {
+  if (!existsSync(path)) return null;
+  const parsed = JSON.parse(readFileSync(path, 'utf8')) as { version?: unknown; runId?: unknown; digest?: unknown; image?: unknown; commit?: unknown };
+  const commit = typeof parsed.commit === 'string' && /^[0-9a-f]{40}$/i.test(parsed.commit) ? parsed.commit.toLowerCase() : null;
+  const image = typeof parsed.image === 'string' ? parsed.image : '';
+  const imageRepo = imageRepository(image);
+  if (parsed.version !== 2 || parsed.runId !== expectedRunId || !commit || !normalizeGateImageDigest(parsed.digest)
+    || !imageRepo || imageRepo !== imageRepository(expectedImage) || image !== `${imageRepo}:${commit.slice(0, 12)}`)
+    throw new Error(`invalid gate image pin: ${path}`);
+  return { runId: expectedRunId, digest: normalizeGateImageDigest(parsed.digest)!, image, commit };
+}
+
+/** Preserve a valid old tip pin before a resumed gate establishes a new commit pin. */
+export function supersedeGateImagePin(path: string, expectedRunId: string, expectedImage: string, expectedCommit: string): { pin: GateImagePin; archivePath: string } | null {
+  const prior = readGateImagePinForRun(path, expectedRunId, expectedImage);
+  if (!prior || prior.commit === expectedCommit.toLowerCase()) return null;
+  const stem = `${path}.superseded-${prior.commit.slice(0, 12)}-${process.pid}-${Date.now()}`;
+  let archivePath = stem;
+  for (let suffix = 1; ; suffix++) {
+    archivePath = suffix === 1 ? stem : `${stem}-${suffix}`;
+    try {
+      copyFileSync(path, archivePath, constants.COPYFILE_EXCL);
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      if (readFileSync(path).equals(readFileSync(archivePath))) break;
+    }
+  }
+  return { pin: prior, archivePath };
+}
+
+/** Archive the old tip and atomically replace the active pin without an absent-pin crash window. */
+export function replaceGateImagePin(path: string, runId: string, digest: string, image: string, commit: string,
+  expectedImage: string, expectedPriorCommit: string): string {
+  const prior = readGateImagePinForRun(path, runId, expectedImage);
+  if (!prior || prior.commit !== expectedPriorCommit.toLowerCase()) throw new Error('stale gate image pin changed before replacement');
+  const archived = supersedeGateImagePin(path, runId, expectedImage, commit);
+  if (!archived) throw new Error('stale gate image pin could not be archived');
+  const normalized = normalizeGateImageDigest(digest);
+  if (!normalized || !runId || !image.trim() || !/^[0-9a-f]{40}$/i.test(commit)) throw new Error('invalid gate image pin identity');
+  const value = `${JSON.stringify({ version: 2, runId, digest: normalized, image, commit: commit.toLowerCase() }, null, 2)}\n`;
+  const tempPath = `${path}.pending-${randomUUID()}`;
+  try {
+    writeFileSync(tempPath, value, { mode: 0o600, flag: 'wx' });
+    // Keep the old active pin until the complete replacement is ready; rename is atomic on this filesystem.
+    renameSync(tempPath, path);
+    return archived.archivePath;
+  } finally { rmSync(tempPath, { force: true }); }
+}
+
 export function writeGateImagePin(path: string, runId: string, digest: string, image: string, commit: string): void {
   const normalized = normalizeGateImageDigest(digest);
   if (!runId || !normalized || !image.trim() || !/^[0-9a-f]{40}$/i.test(commit)) throw new Error('invalid gate image pin identity');

package/scripts/release-loop/gate-method.ts

@@ -1,3 +1,142 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+export type ReleaseGateExecutor = 'pod' | 'host';
+export interface ReleaseGateRehearsal {
+  version: string;
+  outcome: string;
+  executor?: string | null;
+  commit?: string;
+}
+
+export interface ReleaseOpsPolicy {
+  schemaVersion: 1;
+  gate: {
+    default: { executor: ReleaseGateExecutor; poolSource: 'config.release.loop.gatePodPool'; imagePin: 'cut-commit' };
+    rehearsalDecisions: Array<{
+      id: string;
+      when: { outcome: string; executor?: string };
+      executor: ReleaseGateExecutor;
+      poolSource: 'config.release.loop.gatePodPool';
+      imagePin: 'cut-commit';
+    }>;
+  };
+  knownInterferences: Array<{
+    id: string;
+    observedVersion: string;
+    issue: string;
+    workaround: { executor: ReleaseGateExecutor; expiresAfterVersion: string; clearCondition: string };
+  }>;
+}
+
+export interface ReleaseGateMethodDecision {
+  executor: ReleaseGateExecutor;
+  pool: string;
+  imagePin: 'cut-commit';
+  decision: string;
+  rehearsalVersion: string | null;
+  expiredWorkarounds: string[];
+}
+
+const DEFAULT_RELEASE_OPS_POLICY = join(import.meta.dir, '../../packs/release-ops/policy.yaml');
+const RELEASE_VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+
+function compareReleaseVersions(a: string, b: string): number {
+  if (!RELEASE_VERSION.test(a) || !RELEASE_VERSION.test(b)) throw new Error(`release policy version must be x.y.z: ${a} / ${b}`);
+  const aa = a.split('.').map(BigInt), bb = b.split('.').map(BigInt);
+  for (let i = 0; i < 3; i++) {
+    if (aa[i]! < bb[i]!) return -1;
+    if (aa[i]! > bb[i]!) return 1;
+  }
+  return 0;
+}
+
+function object(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Read and validate the checked-in release policy. A workaround without both a clear condition and expiry is invalid. */
+export function readReleaseOpsPolicy(path = DEFAULT_RELEASE_OPS_POLICY): ReleaseOpsPolicy {
+  const raw: unknown = parseYaml(readFileSync(path, 'utf8'));
+  if (!object(raw) || raw.schemaVersion !== 1 || !object(raw.gate) || !object(raw.gate.default)
+    || !Array.isArray(raw.gate.rehearsalDecisions) || !Array.isArray(raw.knownInterferences)) {
+    throw new Error('release ops policy has an unsupported or incomplete schema');
+  }
+  const validExecutor = (value: unknown): value is ReleaseGateExecutor => value === 'pod' || value === 'host';
+  const checkMethod = (method: unknown): boolean =>
+    object(method) && validExecutor(method.executor) && method.poolSource === 'config.release.loop.gatePodPool' && method.imagePin === 'cut-commit';
+  if (!checkMethod(raw.gate.default)) throw new Error('release ops policy default must pin executor, config pool, and cut commit image');
+  const defaultMethod = raw.gate.default as ReleaseOpsPolicy['gate']['default'];
+  const rehearsalDecisions: ReleaseOpsPolicy['gate']['rehearsalDecisions'] = [];
+  for (const decision of raw.gate.rehearsalDecisions) {
+    if (!object(decision) || typeof decision.id !== 'string' || !decision.id.trim() || !object(decision.when)
+      || typeof decision.when.outcome !== 'string' || (decision.when.executor !== undefined && !validExecutor(decision.when.executor))
+      || !checkMethod(decision)) throw new Error('release ops policy has an invalid rehearsal decision');
+    const valid = decision as ReleaseOpsPolicy['gate']['rehearsalDecisions'][number];
+    rehearsalDecisions.push({ id: valid.id, when: { outcome: valid.when.outcome,
+      ...(valid.when.executor !== undefined ? { executor: valid.when.executor } : {}) },
+    executor: valid.executor, poolSource: valid.poolSource, imagePin: valid.imagePin });
+  }
+  const knownInterferences: ReleaseOpsPolicy['knownInterferences'] = [];
+  for (const item of raw.knownInterferences) {
+    if (!object(item) || typeof item.id !== 'string' || !item.id.trim() || typeof item.observedVersion !== 'string'
+      || !RELEASE_VERSION.test(item.observedVersion) || typeof item.issue !== 'string' || !item.issue.trim() || !object(item.workaround)) {
+      throw new Error('release ops policy has an invalid known interference');
+    }
+    const workaround = item.workaround;
+    if (!validExecutor(workaround.executor) || typeof workaround.expiresAfterVersion !== 'string'
+      || !RELEASE_VERSION.test(workaround.expiresAfterVersion) || typeof workaround.clearCondition !== 'string' || !workaround.clearCondition.trim()) {
+      throw new Error('workaround must declare expiresAfterVersion and clearCondition');
+    }
+    knownInterferences.push({ id: item.id, observedVersion: item.observedVersion, issue: item.issue,
+      workaround: { executor: workaround.executor, expiresAfterVersion: workaround.expiresAfterVersion, clearCondition: workaround.clearCondition } });
+  }
+  return { schemaVersion: 1, gate: { default: defaultMethod, rehearsalDecisions }, knownInterferences };
+}
+
+/** Pick the executor from the release policy; the rehearsal can select a declared row but never create a new override. */
+export function selectReleaseGateMethod(input: { policy: ReleaseOpsPolicy; targetVersion: string; configuredPool?: string; rehearsal?: ReleaseGateRehearsal }): ReleaseGateMethodDecision {
+  const { policy, targetVersion, configuredPool, rehearsal } = input;
+  compareReleaseVersions(targetVersion, targetVersion);
+  const method = rehearsal
+    ? policy.gate.rehearsalDecisions.find((row) => row.when.outcome === rehearsal.outcome
+      && (row.when.executor === undefined || row.when.executor === rehearsal.executor))
+    : undefined;
+  const selected = method ?? policy.gate.default;
+  const expiredWorkarounds = policy.knownInterferences.filter((item) =>
+    compareReleaseVersions(targetVersion, item.workaround.expiresAfterVersion) > 0).map((item) => item.id);
+  return { executor: selected.executor, pool: selected.executor === 'pod' && typeof configuredPool === 'string' ? configuredPool.trim() : '',
+    imagePin: selected.imagePin, decision: method?.id ?? 'policy-default', rehearsalVersion: rehearsal?.version ?? null, expiredWorkarounds };
+}
+
+/** Read the latest hard rehearsal for a published version; malformed or mismatched stamps are not evidence. */
+export function readReleaseGateRehearsal(ledgerRoot: string, version: string): ReleaseGateRehearsal | undefined {
+  const dir = join(ledgerRoot, 'release', version, 'rehearsal');
+  let files: string[];
+  try { files = readdirSync(dir).filter((file) => /^hard-[a-z0-9-]+\.json$/.test(file)); }
+  catch { return undefined; }
+  const stamps: Array<{ endedAt: number; rehearsal?: ReleaseGateRehearsal }> = [];
+  for (const file of files) {
+    const path = join(dir, file);
+    const step = file.slice(0, -'.json'.length);
+    try {
+      const stamp = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+      const gate = stamp.hardGate as Record<string, unknown> | undefined;
+      const endedAt = typeof stamp.endedAt === 'string' ? Date.parse(stamp.endedAt) : NaN;
+      if (stamp.version !== version || stamp.step !== step || !Number.isFinite(endedAt)) return undefined;
+      const usable = ['ok', 'regression', 'error'].includes(String(gate?.outcome))
+        && typeof gate?.commit === 'string' && /^[a-f0-9]{40}$/i.test(gate.commit)
+        && (gate.executor === 'pod' || gate.executor === 'host');
+      stamps.push({ endedAt, ...(usable ? { rehearsal: { version, outcome: String(gate!.outcome), executor: gate!.executor as string, commit: gate!.commit as string } } : {}) });
+    } catch { return undefined; }
+  }
+  if (!stamps.length) return undefined;
+  stamps.sort((a, b) => b.endedAt - a.endedAt);
+  if (stamps.length > 1 && stamps[0]!.endedAt === stamps[1]!.endedAt) return undefined;
+  return stamps[0]!.rehearsal;
+}
+
 /** File seconds are recorded on the outer testsuite of each JUnit file, not its nested describe suites. */
 export function readJunitFileSeconds(xml: string): Map<string, number> {
   const secondsByFile = new Map<string, number>();