@nforma.ai/nforma 0.2.1

package/bin/run-installer-alloy.cjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+'use strict';
+// bin/run-installer-alloy.cjs
+// Invokes Alloy 6 JAR headless for QGSD installer and taxonomy specs (GAP-7, GAP-8).
+// Requirements: GAP-7, GAP-8
+//
+// Usage:
+//   node bin/run-installer-alloy.cjs [--spec=<name>]
+//
+// Valid spec names:
+//   install-scope   (default) — GAP-7: installer rollback soundness + config sync completeness
+//   taxonomy-safety           — GAP-8: Haiku taxonomy injection safety + closed/open consistency
+//
+// Prerequisites:
+//   - Java >=17 (https://adoptium.net/)
+//   - .planning/formal/alloy/org.alloytools.alloy.dist.jar (see VERIFICATION_TOOLS.md for download)
+
+const { spawnSync } = require('child_process');
+const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const fs   = require('fs');
+const path = require('path');
+const { writeCheckResult } = require('./write-check-result.cjs');
+const { getRequirementIds } = require('./requirement-map.cjs');
+
+// ── Resolve project root (--project-root= overrides __dirname-relative) ─────
+let ROOT = path.join(__dirname, '..');
+for (const arg of process.argv) {
+  if (arg.startsWith('--project-root=')) ROOT = path.resolve(arg.slice('--project-root='.length));
+}
+
+// ── 0. Parse --spec argument ──────────────────────────────────────────────────
+const VALID_SPECS = ['install-scope', 'taxonomy-safety'];
+const CHECK_ID_MAP = {
+  'install-scope':   'alloy:install-scope',
+  'taxonomy-safety': 'alloy:taxonomy-safety',
+};
+const PROPERTY_MAP = {
+  'install-scope':   'Installer rollback soundness and config sync completeness',
+  'taxonomy-safety': 'Taxonomy injection prevention and closed/open consistency',
+};
+
+const args    = process.argv.slice(2);
+const specArg = args.find(a => a.startsWith('--spec=')) || null;
+const specName = specArg
+  ? specArg.split('=')[1]
+  : (args.find(a => !a.startsWith('-')) || 'install-scope');
+
+if (!VALID_SPECS.includes(specName)) {
+  process.stderr.write(
+    '[run-installer-alloy] Unknown spec: ' + specName +
+    '. Valid: ' + VALID_SPECS.join(', ') + '\n'
+  );
+  const check_id = CHECK_ID_MAP[specName] || ('alloy:' + specName);
+  try { writeCheckResult({ tool: 'run-installer-alloy', formalism: 'alloy', result: 'fail', check_id: check_id, surface: 'alloy', property: PROPERTY_MAP[specName] || specName, runtime_ms: 0, summary: 'fail: ' + check_id + ' (invalid spec)', triage_tags: [], requirement_ids: getRequirementIds(check_id), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-installer-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 1. Locate Java ───────────────────────────────────────────────────────────
+const JAVA_HOME = process.env.JAVA_HOME;
+let javaExe;
+
+const check_id = CHECK_ID_MAP[specName];
+const property = PROPERTY_MAP[specName];
+
+if (JAVA_HOME) {
+  javaExe = path.join(JAVA_HOME, 'bin', 'java');
+  if (!fs.existsSync(javaExe)) {
+    process.stderr.write(
+      '[run-installer-alloy] JAVA_HOME is set but java binary not found at: ' + javaExe + '\n' +
+      '[run-installer-alloy] Unset JAVA_HOME or fix the path.\n'
+    );
+    try { writeCheckResult({ tool: 'run-installer-alloy', formalism: 'alloy', result: 'fail', check_id: check_id, surface: 'alloy', property: property, runtime_ms: 0, summary: 'fail: ' + check_id + ' (Java not found)', triage_tags: [], requirement_ids: getRequirementIds(check_id), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-installer-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+    process.exit(1);
+  }
+} else {
+  // Fall back to PATH lookup
+  const probe = spawnSync('java', ['--version'], { encoding: 'utf8' });
+  if (probe.error || probe.status !== 0) {
+    process.stderr.write(
+      '[run-installer-alloy] Java not found. Install Java >=17 and set JAVA_HOME.\n' +
+      '[run-installer-alloy] Download: https://adoptium.net/\n'
+    );
+    try { writeCheckResult({ tool: 'run-installer-alloy', formalism: 'alloy', result: 'fail', check_id: check_id, surface: 'alloy', property: property, runtime_ms: 0, summary: 'fail: ' + check_id + ' (Java not found)', triage_tags: [], requirement_ids: getRequirementIds(check_id), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-installer-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+    process.exit(1);
+  }
+  javaExe = 'java';
+}
+
+// ── 2. Check Java version >=17 ───────────────────────────────────────────────
+const versionResult = spawnSync(javaExe, ['--version'], { encoding: 'utf8' });
+if (versionResult.error || versionResult.status !== 0) {
+  process.stderr.write('[run-installer-alloy] Failed to run: ' + javaExe + ' --version\n');
+  try { writeCheckResult({ tool: 'run-installer-alloy', formalism: 'alloy', result: 'fail', check_id: check_id, surface: 'alloy', property: property, runtime_ms: 0, summary: 'fail: ' + check_id + ' (version check failed)', triage_tags: [], requirement_ids: getRequirementIds(check_id), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-installer-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+const versionOutput = versionResult.stdout + versionResult.stderr;
+// Java version string varies: "openjdk 17.0.1 ..." or "java version \"17.0.1\""
+const versionMatch = versionOutput.match(/(?:openjdk\s+|java version\s+[""]?)(\d+)/i);
+const javaMajor    = versionMatch ? parseInt(versionMatch[1], 10) : 0;
+if (javaMajor < 17) {
+  process.stderr.write(
+    '[run-installer-alloy] Java >=17 required. Found: ' + versionOutput.split('\n')[0] + '\n' +
+    '[run-installer-alloy] Download Java 17+: https://adoptium.net/\n'
+  );
+  try { writeCheckResult({ tool: 'run-installer-alloy', formalism: 'alloy', result: 'fail', check_id: check_id, surface: 'alloy', property: property, runtime_ms: 0, summary: 'fail: ' + check_id + ' (Java < 17)', triage_tags: [], requirement_ids: getRequirementIds(check_id), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-installer-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 3. Locate org.alloytools.alloy.dist.jar ──────────────────────────────────
+const jarPath = path.join(ROOT, '.planning', 'formal', 'alloy', 'org.alloytools.alloy.dist.jar');
+if (!fs.existsSync(jarPath)) {
+  process.stderr.write(
+    '[run-installer-alloy] org.alloytools.alloy.dist.jar not found at: ' + jarPath + '\n' +
+    '[run-installer-alloy] Download Alloy 6.2.0:\n' +
+    '  curl -L https://github.com/AlloyTools/org.alloytools.alloy/releases/download/v6.2.0/org.alloytools.alloy.dist.jar \\\n' +
+    '       -o .planning/formal/alloy/org.alloytools.alloy.dist.jar\n'
+  );
+  try { writeCheckResult({ tool: 'run-installer-alloy', formalism: 'alloy', result: 'fail', check_id: check_id, surface: 'alloy', property: property, runtime_ms: 0, summary: 'fail: ' + check_id + ' (JAR not found)', triage_tags: [], requirement_ids: getRequirementIds(check_id), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-installer-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 4. Locate .als file ───────────────────────────────────────────────────────
+const alsPath = path.join(ROOT, '.planning', 'formal', 'alloy', specName + '.als');
+if (!fs.existsSync(alsPath)) {
+  process.stderr.write(
+    '[run-installer-alloy] ' + specName + '.als not found at: ' + alsPath + '\n' +
+    '[run-installer-alloy] This file should exist in the repository. Check your git status.\n'
+  );
+  try { writeCheckResult({ tool: 'run-installer-alloy', formalism: 'alloy', result: 'fail', check_id: check_id, surface: 'alloy', property: property, runtime_ms: 0, summary: 'fail: ' + check_id + ' (ALS not found)', triage_tags: [], requirement_ids: getRequirementIds(check_id), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-installer-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 5. Invoke Alloy 6 ────────────────────────────────────────────────────────
+process.stdout.write('[run-installer-alloy] spec: ' + specName + '\n');
+process.stdout.write('[run-installer-alloy] ALS:  ' + alsPath + '\n');
+process.stdout.write('[run-installer-alloy] JAR:  ' + jarPath + '\n');
+
+const _startMs = Date.now();
+
+// Use stdio: 'pipe' so we can scan stdout for counterexamples (Alloy exits 0 even on CEX)
+process.stderr.write('[heap] Xms=64m Xmx=' + JAVA_HEAP_MAX + '\n');
+const alloyResult = spawnSync(javaExe, [
+  '-Djava.awt.headless=true',
+  '-Xms64m', '-Xmx' + JAVA_HEAP_MAX,
+  '-jar', jarPath,
+  'exec',
+  '--output', '-',
+  '--type', 'text',
+  '--quiet',
+  alsPath,
+], { encoding: 'utf8', stdio: 'pipe' });
+
+if (alloyResult.error) {
+  process.stderr.write('[run-installer-alloy] Alloy invocation failed: ' + alloyResult.error.message + '\n');
+  const _runtimeMs = Date.now() - _startMs;
+  try { writeCheckResult({ tool: 'run-installer-alloy', formalism: 'alloy', result: 'fail', check_id: check_id, surface: 'alloy', property: property, runtime_ms: _runtimeMs, summary: 'fail: ' + check_id + ' in ' + _runtimeMs + 'ms', triage_tags: _runtimeMs > 60000 ? ['timeout-risk'] : [], requirement_ids: getRequirementIds(check_id), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-installer-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 6. Scan stdout for counterexamples ───────────────────────────────────────
+// Alloy 6 exits 0 even when counterexamples are found. Scan stdout to detect them.
+const stdout = alloyResult.stdout || '';
+const stderr = alloyResult.stderr || '';
+
+// Write stdout to process.stdout (mirrors stdio: 'inherit' output)
+if (stdout) { process.stdout.write(stdout); }
+if (stderr) { process.stderr.write(stderr); }
+
+if (/Counterexample/i.test(stdout)) {
+  process.stderr.write(
+    '[run-installer-alloy] WARNING: Counterexample found in ' + specName + '.als assertion.\n' +
+    '[run-installer-alloy] This indicates a spec violation — review .planning/formal/alloy/' + specName + '.als.\n'
+  );
+  const _runtimeMs = Date.now() - _startMs;
+  try { writeCheckResult({ tool: 'run-installer-alloy', formalism: 'alloy', result: 'fail', check_id: check_id, surface: 'alloy', property: property, runtime_ms: _runtimeMs, summary: 'fail: ' + check_id + ' in ' + _runtimeMs + 'ms', triage_tags: _runtimeMs > 60000 ? ['timeout-risk'] : [], requirement_ids: getRequirementIds(check_id), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-installer-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 7. Propagate Alloy exit code ─────────────────────────────────────────────
+if (alloyResult.status !== 0) {
+  const _runtimeMs = Date.now() - _startMs;
+  try { writeCheckResult({ tool: 'run-installer-alloy', formalism: 'alloy', result: 'fail', check_id: check_id, surface: 'alloy', property: property, runtime_ms: _runtimeMs, summary: 'fail: ' + check_id + ' in ' + _runtimeMs + 'ms', triage_tags: _runtimeMs > 60000 ? ['timeout-risk'] : [], requirement_ids: getRequirementIds(check_id), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-installer-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(alloyResult.status || 1);
+}
+
+const _runtimeMs = Date.now() - _startMs;
+try { writeCheckResult({ tool: 'run-installer-alloy', formalism: 'alloy', result: 'pass', check_id: check_id, surface: 'alloy', property: property, runtime_ms: _runtimeMs, summary: 'pass: ' + check_id + ' in ' + _runtimeMs + 'ms', triage_tags: _runtimeMs > 60000 ? ['timeout-risk'] : [], requirement_ids: getRequirementIds(check_id), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-installer-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+process.exit(0);

package/bin/run-oauth-rotation-prism.cjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+'use strict';
+// bin/run-oauth-rotation-prism.cjs
+// Invokes PRISM model checker against .planning/formal/prism/oauth-rotation.pm.
+// Requirements: PRM-AM-01
+//
+// Usage:
+//   node bin/run-oauth-rotation-prism.cjs                           # all 3 properties
+//   node bin/run-oauth-rotation-prism.cjs -pf "P=? [ F s=1 ]"      # explicit property
+//   node bin/run-oauth-rotation-prism.cjs -const p_fail=0.15        # override failure rate
+//   node bin/run-oauth-rotation-prism.cjs -const p_fail=0.15 -const max_retries=5
+//
+// Properties (.planning/formal/prism/oauth-rotation.props):
+//   P=? [ F s=1 ]              — probability of eventual success within max_retries
+//   P=? [ F s=0 ]              — probability all attempts fail (complement)
+//   R{"rotations"}=? [ F s<=1] — expected number of rotation attempts before outcome
+//
+// Defaults: p_fail=0.30, max_retries=3
+//   Expected P(succeed) ≈ 1 - 0.3^3 = 0.973
+//
+// Prerequisites:
+//   - PRISM 4.x installed; set PRISM_BIN to path of the prism shell script
+//     e.g. export PRISM_BIN="$HOME/prism/bin/prism"
+//   - Java >=17 (same JRE used by TLA+/Alloy)
+
+const { spawnSync } = require('child_process');
+const fs   = require('fs');
+const path = require('path');
+const { writeCheckResult } = require('./write-check-result.cjs');
+const { getRequirementIds } = require('./requirement-map.cjs');
+
+// ── Locate PRISM binary ──────────────────────────────────────────────────────
+const prismBin = process.env.PRISM_BIN || 'prism';
+
+if (prismBin !== 'prism' && !fs.existsSync(prismBin)) {
+  process.stderr.write(
+    '[run-oauth-rotation-prism] PRISM binary not found at: ' + prismBin + '\n' +
+    '[run-oauth-rotation-prism] Install PRISM and set PRISM_BIN env var:\n' +
+    '[run-oauth-rotation-prism]   export PRISM_BIN="$HOME/prism/bin/prism"\n' +
+    '[run-oauth-rotation-prism] Download: https://www.prismmodelchecker.org/download.php\n'
+  );
+  try { writeCheckResult({ tool: 'run-oauth-rotation-prism', formalism: 'prism', result: 'fail', check_id: 'prism:oauth-rotation', surface: 'prism', property: 'OAuth token rotation probability — successful rotation under expiry and concurrency', runtime_ms: 0, summary: 'fail: prism:oauth-rotation (binary not found)', triage_tags: [], requirement_ids: getRequirementIds('prism:oauth-rotation'), observation_window: { window_start: new Date().toISOString(), window_end: new Date().toISOString(), n_traces: 0, n_events: 0, window_days: 0 }, metadata: {} }); } catch (e) { process.stderr.write('[run-oauth-rotation-prism] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── Locate model file ────────────────────────────────────────────────────────
+const modelPath = path.join(__dirname, '..', '.planning', 'formal', 'prism', 'oauth-rotation.pm');
+if (!fs.existsSync(modelPath)) {
+  process.stderr.write(
+    '[run-oauth-rotation-prism] Model file not found: ' + modelPath + '\n'
+  );
+  try { writeCheckResult({ tool: 'run-oauth-rotation-prism', formalism: 'prism', result: 'fail', check_id: 'prism:oauth-rotation', surface: 'prism', property: 'OAuth token rotation probability — successful rotation under expiry and concurrency', runtime_ms: 0, summary: 'fail: prism:oauth-rotation (model not found)', triage_tags: [], requirement_ids: getRequirementIds('prism:oauth-rotation'), observation_window: { window_start: new Date().toISOString(), window_end: new Date().toISOString(), n_traces: 0, n_events: 0, window_days: 0 }, metadata: {} }); } catch (e) { process.stderr.write('[run-oauth-rotation-prism] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── Extract max_retries from providers.json (live source of truth) ───────────
+// Reads bin/providers.json → gemini-1.oauth_rotation.max_retries.
+// Injected as -const max_retries=<N> unless the caller already supplies it.
+let liveMaxRetries = null;
+const providersPath = path.join(__dirname, 'providers.json');
+if (fs.existsSync(providersPath)) {
+  try {
+    const parsed  = JSON.parse(fs.readFileSync(providersPath, 'utf8'));
+    // providers.json has shape { providers: [...] } with each entry having a `name` field
+    const list    = Array.isArray(parsed) ? parsed : (parsed.providers || []);
+    const gemini1 = list.find(function(p) { return p.name === 'gemini-1' || p.id === 'gemini-1'; }) || {};
+    const rot     = gemini1.oauth_rotation || {};
+    if (typeof rot.max_retries === 'number') {
+      liveMaxRetries = rot.max_retries;
+      process.stdout.write(
+        '[run-oauth-rotation-prism] max_retries=' + liveMaxRetries +
+        ' (from providers.json)\n'
+      );
+    }
+  } catch (_) { /* malformed providers.json — fall through to spec default */ }
+}
+
+// ── Build argument list ──────────────────────────────────────────────────────
+// Extra args passed to this script are forwarded to PRISM after the model path.
+// If .planning/formal/prism/oauth-rotation.props exists, pass it as the properties file.
+// Otherwise fall back to a single inline property.
+const extraArgs  = process.argv.slice(2);
+const hasPf      = extraArgs.some(a => a === '-pf' || a === '-prop');
+const propsFile  = path.join(__dirname, '..', '.planning', 'formal', 'prism', 'oauth-rotation.props');
+const hasProps   = !hasPf && fs.existsSync(propsFile);
+// Inject live max_retries unless the caller already overrides it
+const callerOverridesRetries = extraArgs.some(
+  (a, i) => a === '-const' && (extraArgs[i + 1] || '').startsWith('max_retries=')
+);
+
+const prismArgs = [modelPath];
+if (hasProps) {
+  prismArgs.push(propsFile);
+} else if (!hasPf) {
+  prismArgs.push('-pf', 'P=? [ F s=1 ]');
+}
+if (liveMaxRetries !== null && !callerOverridesRetries) {
+  prismArgs.push('-const', 'max_retries=' + liveMaxRetries);
+}
+prismArgs.push(...extraArgs);
+
+process.stdout.write('[run-oauth-rotation-prism] Binary: ' + prismBin + '\n');
+process.stdout.write('[run-oauth-rotation-prism] Model:  ' + modelPath + '\n');
+process.stdout.write('[run-oauth-rotation-prism] Args:   ' + prismArgs.slice(1).join(' ') + '\n');
+
+// ── Invoke PRISM ─────────────────────────────────────────────────────────────
+const _startMs = Date.now();
+
+const result = spawnSync(prismBin, prismArgs, {
+  encoding: 'utf8',
+  stdio: 'inherit',
+});
+
+if (result.error) {
+  process.stderr.write('[run-oauth-rotation-prism] Failed to launch PRISM: ' + result.error.message + '\n');
+  const _runtimeMs = Date.now() - _startMs;
+  const tags = [];
+  if (_runtimeMs > 300000) tags.push('timeout-risk');
+  else if (_runtimeMs > 120000) tags.push('slow-verify');
+  tags.push('low-confidence');
+  try { writeCheckResult({ tool: 'run-oauth-rotation-prism', formalism: 'prism', result: 'fail', check_id: 'prism:oauth-rotation', surface: 'prism', property: 'OAuth token rotation probability — successful rotation under expiry and concurrency', runtime_ms: _runtimeMs, summary: 'fail: prism:oauth-rotation in ' + _runtimeMs + 'ms', triage_tags: tags, requirement_ids: getRequirementIds('prism:oauth-rotation'), observation_window: { window_start: new Date().toISOString(), window_end: new Date().toISOString(), n_traces: 0, n_events: 0, window_days: 0 }, metadata: {} }); } catch (e) { process.stderr.write('[run-oauth-rotation-prism] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+const passed = (result.status || 0) === 0;
+const _runtimeMs = Date.now() - _startMs;
+const tags = [];
+if (_runtimeMs > 300000) tags.push('timeout-risk');
+else if (_runtimeMs > 120000) tags.push('slow-verify');
+tags.push('low-confidence'); // OAuth rotation always insufficient data
+try { writeCheckResult({ tool: 'run-oauth-rotation-prism', formalism: 'prism', result: passed ? 'pass' : 'fail', check_id: 'prism:oauth-rotation', surface: 'prism', property: 'OAuth token rotation probability — successful rotation under expiry and concurrency', runtime_ms: _runtimeMs, summary: (passed ? 'pass' : 'fail') + ': prism:oauth-rotation in ' + _runtimeMs + 'ms', triage_tags: tags, requirement_ids: getRequirementIds('prism:oauth-rotation'), observation_window: { window_start: new Date().toISOString(), window_end: new Date().toISOString(), n_traces: 0, n_events: 0, window_days: 0 }, metadata: {} }); } catch (e) { process.stderr.write('[run-oauth-rotation-prism] Warning: failed to write check result: ' + e.message + '\n'); }
+process.exit(result.status || 0);

package/bin/run-oscillation-tlc.cjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+'use strict';
+// bin/run-oscillation-tlc.cjs
+// Invokes TLC model checker for QGSD oscillation and convergence TLA+ specifications.
+// Requirements: GAP-1, GAP-5
+//
+// Usage:
+//   node bin/run-oscillation-tlc.cjs MCoscillation   # oscillation detection (liveness, -workers 1)
+//   node bin/run-oscillation-tlc.cjs MCconvergence   # state persistence (liveness, -workers 1)
+//   node bin/run-oscillation-tlc.cjs --config=MCoscillation
+//
+// Prerequisites:
+//   - Java >=17 (https://adoptium.net/)
+//   - .planning/formal/tla/tla2tools.jar (see .planning/formal/tla/README.md for download command)
+
+const { spawnSync } = require('child_process');
+const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const fs   = require('fs');
+const path = require('path');
+const { writeCheckResult } = require('./write-check-result.cjs');
+const { detectLivenessProperties } = require('./run-tlc.cjs');
+const { getRequirementIds } = require('./requirement-map.cjs');
+
+// ── Resolve project root (--project-root= overrides __dirname-relative) ─────
+let ROOT = path.join(__dirname, '..');
+for (const arg of process.argv) {
+  if (arg.startsWith('--project-root=')) ROOT = path.resolve(arg.slice('--project-root='.length));
+}
+
+const CHECK_ID_MAP = {
+  'MCoscillation': 'tla:oscillation',
+  'MCconvergence': 'tla:convergence',
+};
+
+const PROPERTY_MAP = {
+  'MCoscillation': 'Run-collapse oscillation detection algorithm correctness',
+  'MCconvergence': 'Haiku convergence — OscillationConvergence liveness property',
+};
+
+// ── Parse --config argument ──────────────────────────────────────────────────
+const args       = process.argv.slice(2);
+const configArg  = args.find(a => a.startsWith('--config=')) || null;
+const configName = configArg
+  ? configArg.split('=')[1]
+  : (args.find(a => !a.startsWith('-')) || 'MCoscillation');
+
+const VALID_CONFIGS = ['MCoscillation', 'MCconvergence'];
+if (!VALID_CONFIGS.includes(configName)) {
+  process.stderr.write(
+    '[run-oscillation-tlc] Unknown config: ' + configName +
+    '. Valid: ' + VALID_CONFIGS.join(', ') + '\n'
+  );
+  const _startMs = Date.now();
+  const _runtimeMs = 0;
+  try { writeCheckResult({ tool: 'run-oscillation-tlc', formalism: 'tla', result: 'fail', check_id: CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase()), surface: 'tla', property: PROPERTY_MAP[configName] || configName, runtime_ms: _runtimeMs, summary: 'fail: unknown config in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds(CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase())), metadata: { config: configName } }); } catch (e) { process.stderr.write('[run-oscillation-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 1. Locate Java ───────────────────────────────────────────────────────────
+const JAVA_HOME = process.env.JAVA_HOME;
+let javaExe;
+
+if (JAVA_HOME) {
+  javaExe = path.join(JAVA_HOME, 'bin', 'java');
+  if (!fs.existsSync(javaExe)) {
+    process.stderr.write(
+      '[run-oscillation-tlc] JAVA_HOME is set but java binary not found at: ' + javaExe + '\n' +
+      '[run-oscillation-tlc] Unset JAVA_HOME or fix the path.\n'
+    );
+    const _startMs = Date.now();
+    const _runtimeMs = 0;
+    try { writeCheckResult({ tool: 'run-oscillation-tlc', formalism: 'tla', result: 'fail', check_id: CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase()), surface: 'tla', property: PROPERTY_MAP[configName] || configName, runtime_ms: _runtimeMs, summary: 'fail: Java not found in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds(CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase())), metadata: { config: configName } }); } catch (e) { process.stderr.write('[run-oscillation-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+    process.exit(1);
+  }
+} else {
+  // Fall back to PATH lookup
+  const probe = spawnSync('java', ['--version'], { encoding: 'utf8' });
+  if (probe.error || probe.status !== 0) {
+    process.stderr.write(
+      '[run-oscillation-tlc] Java not found. Install Java >=17 and set JAVA_HOME.\n' +
+      '[run-oscillation-tlc] Download: https://adoptium.net/\n'
+    );
+    const _startMs = Date.now();
+    const _runtimeMs = 0;
+    try { writeCheckResult({ tool: 'run-oscillation-tlc', formalism: 'tla', result: 'fail', check_id: CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase()), surface: 'tla', property: PROPERTY_MAP[configName] || configName, runtime_ms: _runtimeMs, summary: 'fail: Java not found in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds(CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase())), metadata: { config: configName } }); } catch (e) { process.stderr.write('[run-oscillation-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+    process.exit(1);
+  }
+  javaExe = 'java';
+}
+
+// ── 2. Check Java version >=17 ───────────────────────────────────────────────
+const versionResult = spawnSync(javaExe, ['--version'], { encoding: 'utf8' });
+if (versionResult.error || versionResult.status !== 0) {
+  process.stderr.write('[run-oscillation-tlc] Failed to run: ' + javaExe + ' --version\n');
+  const _startMs = Date.now();
+  const _runtimeMs = 0;
+  try { writeCheckResult({ tool: 'run-oscillation-tlc', formalism: 'tla', result: 'fail', check_id: CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase()), surface: 'tla', property: PROPERTY_MAP[configName] || configName, runtime_ms: _runtimeMs, summary: 'fail: Java version check failed in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds(CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase())), metadata: { config: configName } }); } catch (e) { process.stderr.write('[run-oscillation-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+const versionOutput = versionResult.stdout + versionResult.stderr;
+// Java version string varies: "openjdk 17.0.1 ..." or "java version \"17.0.1\""
+const versionMatch = versionOutput.match(/(?:openjdk\s+|java version\s+[""]?)(\d+)/i);
+const javaMajor    = versionMatch ? parseInt(versionMatch[1], 10) : 0;
+if (javaMajor < 17) {
+  process.stderr.write(
+    '[run-oscillation-tlc] Java >=17 required. Found: ' + versionOutput.split('\n')[0] + '\n' +
+    '[run-oscillation-tlc] Download Java 17+: https://adoptium.net/\n'
+  );
+  const _startMs = Date.now();
+  const _runtimeMs = 0;
+  try { writeCheckResult({ tool: 'run-oscillation-tlc', formalism: 'tla', result: 'fail', check_id: CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase()), surface: 'tla', property: PROPERTY_MAP[configName] || configName, runtime_ms: _runtimeMs, summary: 'fail: Java ' + javaMajor + ' < 17 in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds(CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase())), metadata: { config: configName } }); } catch (e) { process.stderr.write('[run-oscillation-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 3. Locate tla2tools.jar ──────────────────────────────────────────────────
+const jarPath = path.join(ROOT, '.planning', 'formal', 'tla', 'tla2tools.jar');
+if (!fs.existsSync(jarPath)) {
+  process.stderr.write(
+    '[run-oscillation-tlc] tla2tools.jar not found at: ' + jarPath + '\n' +
+    '[run-oscillation-tlc] Download v1.8.0:\n' +
+    '  curl -L https://github.com/tlaplus/tlaplus/releases/download/v1.8.0/tla2tools.jar \\\n' +
+    '       -o .planning/formal/tla/tla2tools.jar\n'
+  );
+  const _startMs = Date.now();
+  const _runtimeMs = 0;
+  try { writeCheckResult({ tool: 'run-oscillation-tlc', formalism: 'tla', result: 'fail', check_id: CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase()), surface: 'tla', property: PROPERTY_MAP[configName] || configName, runtime_ms: _runtimeMs, summary: 'fail: tla2tools.jar not found in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds(CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase())), metadata: { config: configName } }); } catch (e) { process.stderr.write('[run-oscillation-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 4. Resolve spec and config paths ─────────────────────────────────────────
+const specFileName = configName === 'MCoscillation'
+  ? 'QGSDOscillation.tla'
+  : 'QGSDConvergence.tla';
+const specPath = path.join(ROOT, '.planning', 'formal', 'tla', specFileName);
+const cfgPath  = path.join(ROOT, '.planning', 'formal', 'tla', configName + '.cfg');
+
+// Both MCoscillation and MCconvergence declare PROPERTY (liveness) clauses in their .cfg files.
+// TLC has a known multi-worker liveness checking bug (v1.8.0) — always use -workers 1.
+// MCconvergence.cfg declares PROPERTY ConvergenceEventuallyResolves; 'auto' workers is NOT safe.
+const workers = '1';
+
+// ── 5. Invoke TLC ────────────────────────────────────────────────────────────
+process.stdout.write('[run-oscillation-tlc] Config: ' + configName + '  Workers: ' + workers + '\n');
+process.stdout.write('[run-oscillation-tlc] Spec:   ' + specPath + '\n');
+process.stdout.write('[run-oscillation-tlc] Cfg:    ' + cfgPath + '\n');
+
+const _startMs = Date.now();
+process.stderr.write('[heap] Xms=64m Xmx=' + JAVA_HEAP_MAX + '\n');
+const tlcResult = spawnSync(javaExe, [
+  '-Xms64m', '-Xmx' + JAVA_HEAP_MAX,
+  '-jar', jarPath,
+  '-config', cfgPath,
+  '-workers', workers,
+  specPath,
+], { encoding: 'utf8', stdio: 'inherit' });
+const _runtimeMs = Date.now() - _startMs;
+
+if (tlcResult.error) {
+  process.stderr.write('[run-oscillation-tlc] TLC invocation failed: ' + tlcResult.error.message + '\n');
+  const check_id = CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase());
+  const property = PROPERTY_MAP[configName] || configName;
+  try { writeCheckResult({ tool: 'run-oscillation-tlc', formalism: 'tla', result: 'fail', check_id: check_id, surface: 'tla', property: property, runtime_ms: _runtimeMs, summary: 'fail: TLC invocation failed in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds(check_id), metadata: { config: configName } }); } catch (e) { process.stderr.write('[run-oscillation-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+const passed = (tlcResult.status || 0) === 0;
+const check_id = CHECK_ID_MAP[configName] || ('tla:' + configName.toLowerCase());
+const property = PROPERTY_MAP[configName] || configName;
+const triage_tags = _runtimeMs > 120000 ? ['timeout-risk'] : [];
+
+if (passed) {
+  const missingDeclarations = detectLivenessProperties(configName, cfgPath);
+  if (missingDeclarations.length > 0) {
+    try {
+      writeCheckResult({
+        tool: 'run-oscillation-tlc',
+        formalism: 'tla',
+        result: 'inconclusive',
+        check_id: check_id,
+        surface: 'tla',
+        property: property,
+        runtime_ms: _runtimeMs,
+        summary: 'inconclusive: fairness missing in ' + _runtimeMs + 'ms',
+        triage_tags: ['needs-fairness'],
+        requirement_ids: getRequirementIds(check_id),
+        metadata: {
+          config: configName,
+          reason: 'Fairness declaration missing for: ' + missingDeclarations.join(', '),
+        }
+      });
+    } catch (e) {
+      process.stderr.write('[run-oscillation-tlc] Warning: failed to write inconclusive result: ' + e.message + '\n');
+    }
+    process.stdout.write('[run-oscillation-tlc] Result: inconclusive — fairness declaration missing for: ' + missingDeclarations.join(', ') + '\n');
+    process.exit(0);
+  }
+  try { writeCheckResult({ tool: 'run-oscillation-tlc', formalism: 'tla', result: 'pass', check_id: check_id, surface: 'tla', property: property, runtime_ms: _runtimeMs, summary: 'pass: ' + configName + ' in ' + _runtimeMs + 'ms', triage_tags: triage_tags, requirement_ids: getRequirementIds(check_id), metadata: { config: configName } }); } catch (e) { process.stderr.write('[run-oscillation-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(0);
+} else {
+  try { writeCheckResult({ tool: 'run-oscillation-tlc', formalism: 'tla', result: 'fail', check_id: check_id, surface: 'tla', property: property, runtime_ms: _runtimeMs, summary: 'fail: ' + configName + ' in ' + _runtimeMs + 'ms', triage_tags: triage_tags, requirement_ids: getRequirementIds(check_id), metadata: { config: configName } }); } catch (e) { process.stderr.write('[run-oscillation-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(tlcResult.status || 0);
+}