contextecf-codeledger 0.10.81 → 0.10.82

package/bin/codeledger.js

@@ -2,7 +2,7 @@
 /*
  * CodeLedger npm launcher — thin shim.
  *
- * This file is the ONLY JavaScript that ships to npm under @codeledger/cli.
+ * This launcher and its installation helpers ship to npm under @codeledger/cli.
  * It contains no engine code, no scoring logic, no formulas. All CodeLedger
  * functionality lives inside the hardened binary that is downloaded during
  * `postinstall` from the GitHub Release for this exact version, verified
@@ -18,11 +18,22 @@
 'use strict';
 
 const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { resolveRuntimePin, compareRuntimeVersions, isRuntimePinTrusted } = require('../scripts/runtime-pin.js');
 const { existsSync, realpathSync, statSync } = require('node:fs');
-const { dirname, join, resolve } = require('node:path');
+const { basename, dirname, join, resolve } = require('node:path');
 const { homedir, platform } = require('node:os');
 
-const { version } = require('../package.json');
+const { name: packageName, version } = require('../package.json');
+
+// `codeledger-mcp` bin alias (same file, no extra JS): for MCP registries
+// that cannot pass arguments, it always runs `mcp start` + the user's args.
+// Every other invocation forwards argv unchanged, including a bare launch,
+// so the CLI's own bare-launch MCP detection applies.
+const MCP_ALIAS = /^codeledger-mcp(\.c?js)?$/i.test(basename(process.argv[1] || ''));
+const ARGS = MCP_ALIAS ? ['mcp', 'start', ...process.argv.slice(2)] : process.argv.slice(2);
 
 const CACHE_DIR =
   process.env.CODELEDGER_CACHE_DIR ||
@@ -40,6 +51,34 @@ function die(msg, code = 1) {
   process.exit(code);
 }
 
+// Repair commands use the installed version, so an old pin cannot trap an upgrade.
+function repairing() {
+  const commands = [];
+  for (let i = 0; i < ARGS.length && ARGS[i] !== '--'; i++) {
+    if (ARGS[i] === '--cwd') { i++; continue; }
+    if (!ARGS[i].startsWith('-')) commands.push(ARGS[i]);
+  }
+  return ['vendor', 'upgrade', 'update', 'init'].includes(commands[0]);
+}
+
+function findPinnedRuntime(startDir) {
+  if (process.env.CODELEDGER_GLOBAL_VERSION_PROBE === '1' || repairing()) return null;
+  let root = resolve(startDir);
+  while (true) {
+    const pin = resolveRuntimePin(join(root, '.codeledger'), { fs, path, crypto }, compareRuntimeVersions);
+    if (pin) {
+      const trustDir = process.env.CODELEDGER_RUNTIME_TRUST_DIR || join(homedir(), '.cache', 'codeledger', 'runtime-trust');
+      if (isRuntimePinTrusted(root, pin.manifest, { fs, path, crypto }, trustDir)) return { kind: 'standalone', path: pin.path, repoRoot: root };
+      process.stderr.write('codeledger: repository runtime has no installed trust receipt; using the global installation. Run the installed codeledger vendor command to install and trust its verified runtime.\n');
+      return null;
+    }
+    if (existsSync(join(root, '.git'))) return null;
+    const parent = dirname(root);
+    if (parent === root) return null;
+    root = parent;
+  }
+}
+
 // Repo-local fallback: an already-`codeledger init`'d repo vendors its own
 // runtime under .codeledger/bin/. Checked before attempting a network
 // download since it's instant and needs no connectivity — the global cache
@@ -49,10 +88,14 @@ function findRepoLocalRuntime(startDir) {
   if (process.env.CODELEDGER_GLOBAL_VERSION_PROBE === '1') return null;
   let current = resolve(startDir);
   while (true) {
+    if (existsSync(join(current, '.codeledger', 'runtime.json'))) return null;
+    // Legacy scripts require an explicit environment-level repository trust decision.
+    if (process.env.CODELEDGER_TRUST_LEGACY_RUNTIME !== '1') return null;
     const wrapper = join(current, '.codeledger', 'bin', 'codeledger');
     const standalone = join(current, '.codeledger', 'bin', 'codeledger-standalone.cjs');
     if (existsSync(wrapper)) return { kind: 'wrapper', path: wrapper, repoRoot: current };
     if (existsSync(standalone)) return { kind: 'standalone', path: standalone, repoRoot: current };
+    if (existsSync(join(current, '.git'))) return null;
     const parent = dirname(current);
     if (parent === current) return null;
     current = parent;
@@ -62,18 +105,18 @@ function findRepoLocalRuntime(startDir) {
 function runRepoLocal(runtime) {
   process.stderr.write(
     [
-      `codeledger: ContextECF CodeLedger hardened binary for v${version} is not installed in the global cache.`,
+      `codeledger: using the repository runtime instead of the global v${version} installation.`,
       `codeledger: using repo-local runtime at ${runtime.path}`,
       '',
     ].join('\n'),
   );
   const command = runtime.kind === 'standalone' ? process.execPath : runtime.path;
   const args = runtime.kind === 'standalone'
-    ? [runtime.path, ...process.argv.slice(2)]
-    : process.argv.slice(2);
+    ? [runtime.path, ...ARGS]
+    : ARGS;
   const result = spawnSync(command, args, {
     stdio: 'inherit',
-    cwd: runtime.repoRoot,
+    cwd: process.cwd(),
     env: { ...process.env, CODELEDGER_DELEGATED: '1' },
   });
   if (result.error) {
@@ -89,7 +132,7 @@ function runRepoLocal(runtime) {
 const ON_DEMAND_DEADLINE_MS = 30_000;
 
 function launchDirectory() {
-  const args = process.argv.slice(2);
+  const args = ARGS;
   let target;
   for (let i = 0; i < args.length && args[i] !== '--'; i++) {
     if (args[i].startsWith('--cwd=')) target = args[i].slice(6);
@@ -98,7 +141,7 @@ function launchDirectory() {
       if (!target || target.startsWith('--')) die('--cwd requires a repository directory.', 2);
     }
   }
-  if (target === undefined && args[0] === 'mcp') target = process.env.CODELEDGER_REPO_ROOT;
+  if (target === undefined && (args[0] === 'mcp' || (args.length === 0 && !process.stdin.isTTY))) target = process.env.CODELEDGER_REPO_ROOT;
   if (target !== undefined && !target.trim()) die('Repository target cannot be empty.', 2);
   try {
     const root = realpathSync(resolve(target ?? process.cwd()));
@@ -108,8 +151,17 @@ function launchDirectory() {
 }
 
 async function main() {
+  const pinned = findPinnedRuntime(launchDirectory());
+  if (pinned) runRepoLocal(pinned);
+  if (existsSync(BINARY_PATH)) {
+    const problem = require('../scripts/postinstall.js').verifyCachedBinary(BINARY_PATH);
+    if (problem) {
+      process.stderr.write(`codeledger: cached binary at ${BINARY_PATH} failed verification (${problem}); discarding it and downloading a verified copy.\n`);
+      try { fs.unlinkSync(BINARY_PATH); } catch (error) { die(`could not remove the unverified cached binary: ${error.message}. Delete ${BINARY_PATH} and retry.`); }
+    }
+  }
   if (!existsSync(BINARY_PATH)) {
-    const repoLocal = findRepoLocalRuntime(launchDirectory());
+    const repoLocal = repairing() ? null : findRepoLocalRuntime(launchDirectory());
     if (repoLocal) {
       runRepoLocal(repoLocal);
     }
@@ -118,7 +170,7 @@ async function main() {
     const platformKey = `${platform()}-${arch()}`;
     const installerPath = join(__dirname, '..', 'scripts', 'postinstall.js');
 
-    const { PLATFORM_MAP, downloadAndVerifyBinary, unsupportedPlatformMessage } = require('../scripts/postinstall.js');
+    const { PLATFORM_MAP, downloadAndVerifyBinary, unsupportedPlatformMessage, readInstallFailure, unpublishedAssetsMessage } = require('../scripts/postinstall.js');
     if (!PLATFORM_MAP[platformKey]) {
       // Don't waste time on a download attempt that can only ever fail —
       // getBinaryPaths() would reject this platformKey immediately anyway.
@@ -127,35 +179,43 @@ async function main() {
       die(unsupportedPlatformMessage(platformKey));
     }
 
+    const priorFailure = readInstallFailure();
+    if (priorFailure) {
+      process.stderr.write(`codeledger: the install step could not fetch the hardened binary (${priorFailure.at}): ${priorFailure.message}\n`);
+    }
     process.stderr.write(
       `codeledger: hardened binary for v${version} not cached locally — downloading now (one-time)...\n`,
     );
     try {
       await downloadAndVerifyBinary({ deadlineMs: ON_DEMAND_DEADLINE_MS });
     } catch (err) {
+      const unpublished = unpublishedAssetsMessage(err);
       die(
         [
           `hardened binary for v${version} not found at ${BINARY_PATH}, and the on-demand download just failed: ${err.message}`,
-          '',
-          'The postinstall step may have been skipped (e.g. --ignore-scripts).',
+          ...(unpublished ? ['', unpublished,
+            'Retrying or reinstalling this version will not help until they are published.',
+            'To use a published version instead, list them with: npm view @codeledger/cli versions'] : [
+            '',
+            'The postinstall step may have been skipped (e.g. --ignore-scripts).']),
           'Confirm the official scoped package is installed: @codeledger/cli.',
           'Avoid the unrelated unscoped npm package: codeledger.',
           '',
           'Recover with one of:',
           '  1. Retry: codeledger --version',
-          '  2. Reinstall: npm install -g @codeledger/cli@latest',
+          `  2. Reinstall this version: npm install -g ${packageName}@${version}`,
           `  3. node "${installerPath}"`,
           '  4. Re-run the install without --ignore-scripts',
           '  5. In an initialized repo, use: ./.codeledger/bin/codeledger ready',
           '',
-          'Or download the binary manually from:',
+          `Release page for v${version} (it exists only once that release is published):`,
           `  https://github.com/codeledgerECF/codeledger/releases/tag/v${version}`,
         ].join('\n'),
       );
     }
   }
 
-  const result = spawnSync(BINARY_PATH, process.argv.slice(2), {
+  const result = spawnSync(BINARY_PATH, ARGS, {
     stdio: 'inherit',
     env: process.env,
   });
@@ -167,4 +227,4 @@ async function main() {
   process.exit(result.status ?? 1);
 }
 
-main();
+main().catch((error) => die(error.message));

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "contextecf-codeledger",
-  "version": "0.10.81",
+  "version": "0.10.82",
   "mcpName": "io.github.codeledgerECF/codeledger",
   "description": "ContextECF CodeLedger — deterministic context selection for AI coding agents. Safe unscoped alias for @codeledger/cli; avoid the unrelated codeledger package.",
   "type": "commonjs",
   "bin": {
-    "codeledger": "./bin/codeledger.js"
+    "codeledger": "./bin/codeledger.js",
+    "codeledger-mcp": "./bin/codeledger.js"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js"

package/scripts/postinstall.js

@@ -42,6 +42,8 @@ const {
   chmodSync,
   existsSync,
   unlinkSync,
+  readFileSync,
+  statSync,
 } = require('node:fs');
 const { join } = require('node:path');
 const { homedir, platform, arch } = require('node:os');
@@ -101,9 +103,79 @@ function getBinaryPaths(platformKey) {
   };
 }
 
+// The verified SHA-256 is recorded beside the cached binary so every launch can
+// reject a truncated, replaced, or tampered cache before executing it.
+function receiptPath(binaryPath) {
+  return `${binaryPath}.sha256.json`;
+}
+
+function writeVerifiedReceipt(binaryPath, sha256) {
+  const stat = statSync(binaryPath);
+  writeFileSync(receiptPath(binaryPath), JSON.stringify({ schema: 1, version, sha256, size: stat.size }) + '\n');
+}
+
+/** Returns null when the cached binary matches its install receipt, else the reason it does not. */
+function verifyCachedBinary(binaryPath) {
+  let receipt;
+  try {
+    receipt = JSON.parse(readFileSync(receiptPath(binaryPath), 'utf8'));
+  } catch {
+    return 'no install receipt';
+  }
+  if (!receipt || receipt.schema !== 1 || receipt.version !== version || !/^[a-f0-9]{64}$/.test(String(receipt.sha256))) return 'invalid install receipt';
+  let stat;
+  try {
+    stat = statSync(binaryPath);
+  } catch {
+    return 'binary missing';
+  }
+  if (!stat.isFile() || stat.size === 0) return 'binary is empty or not a file';
+  if (stat.size !== receipt.size) return 'binary size changed since install';
+  // Hashed on every launch: size or timestamps can be preserved by a same-size replacement.
+  const actual = createHash('sha256').update(readFileSync(binaryPath)).digest('hex');
+  return actual === receipt.sha256 ? null : 'SHA256 mismatch with install receipt';
+}
+
+// npm hides postinstall output by default, so a soft failure is recorded where
+// the first `codeledger` run can report it.
+function installFailurePath() {
+  return join(getCacheDir(), `install-failure-v${version}.json`);
+}
+
+function recordInstallFailure(err) {
+  try {
+    mkdirSync(getCacheDir(), { recursive: true });
+    writeFileSync(installFailurePath(), JSON.stringify({
+      schema: 1, version, at: new Date().toISOString(),
+      status: typeof err.statusCode === 'number' ? err.statusCode : null,
+      message: String(err.message).split('\n')[0].slice(0, 300),
+    }) + '\n');
+  } catch { /* Reporting is best effort; the install stays a soft failure. */ }
+}
+
+function readInstallFailure() {
+  try {
+    const record = JSON.parse(readFileSync(installFailurePath(), 'utf8'));
+    return record && record.schema === 1 && record.version === version ? record : null;
+  } catch {
+    return null;
+  }
+}
+
+function clearInstallFailure() {
+  try { unlinkSync(installFailurePath()); } catch { /* Nothing recorded. */ }
+}
+
+/** A 404 after the propagation window means this version's release assets are not published. */
+function unpublishedAssetsMessage(err) {
+  return err && err.statusCode === 404
+    ? `The v${version} release assets were not found (HTTP 404): this version's hardened binaries are not published yet, or were withdrawn.`
+    : null;
+}
+
 function isBinaryCached() {
   const paths = getBinaryPaths(getPlatformKey());
-  return Boolean(paths && existsSync(paths.binaryLocalPath));
+  return Boolean(paths && existsSync(paths.binaryLocalPath) && verifyCachedBinary(paths.binaryLocalPath) === null);
 }
 
 // ─── http ────────────────────────────────────────────────────────────────────
@@ -268,6 +340,8 @@ async function downloadAndVerifyBinary({ deadlineMs = DEFAULT_DEADLINE_MS } = {}
   chmodSync(tmpPath, 0o755);
   if (existsSync(paths.binaryLocalPath)) unlinkSync(paths.binaryLocalPath);
   require('node:fs').renameSync(tmpPath, paths.binaryLocalPath);
+  writeVerifiedReceipt(paths.binaryLocalPath, actualSha);
+  clearInstallFailure();
 
   console.error(`codeledger: installed ${paths.binaryLocalPath}`);
   console.error(`  sha256:   ${actualSha}`);
@@ -356,7 +430,10 @@ async function runPostinstall() {
     // existing working install (the exact incident this is designed
     // around). bin/codeledger.js retries this same download on-demand,
     // synchronously, the first time it's actually needed.
+    recordInstallFailure(err);
     console.error(`codeledger: could not pre-fetch the hardened binary — ${err.message}`);
+    const unpublished = unpublishedAssetsMessage(err);
+    if (unpublished) console.error(`codeledger: ${unpublished}`);
     console.error('codeledger: not fatal — it will download automatically on first "codeledger" invocation.');
     console.error('codeledger: or, in an initialized repo, use: ./.codeledger/bin/codeledger ready');
   }
@@ -378,4 +455,9 @@ module.exports = {
   getBinaryPaths,
   isBinaryCached,
   unsupportedPlatformMessage,
+  verifyCachedBinary,
+  writeVerifiedReceipt,
+  readInstallFailure,
+  recordInstallFailure,
+  unpublishedAssetsMessage,
 };

package/scripts/runtime-pin.js

@@ -0,0 +1,125 @@
+/* Generated by scripts/generate-runtime-resolver.mjs. Public installation contract only. */
+'use strict';
+module.exports = (() => {
+/** Strict SemVer 2.0, shared by pin validation and explicit installation. */
+function parseRuntimeVersion(value) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.exec(value);
+  if (!match || match[0] !== value) throw new Error(`Invalid runtime version: ${value}. Use an exact semantic version.`);
+  const core = match.slice(1, 4).map(Number);
+  const prerelease = match[4]?.split('.') ?? [];
+  if (core.some((n) => !Number.isSafeInteger(n)) || prerelease.some((p) => /^\d+$/.test(p) && (p.length > 1 && p.startsWith('0')))) {
+    throw new Error(`Invalid runtime version: ${value}`);
+  }
+  return { core, prerelease };
+}
+
+function compareRuntimeVersions(left, right) {
+  const a = parseRuntimeVersion(left);
+  const b = parseRuntimeVersion(right);
+  for (let i = 0; i < 3; i++) {
+    if (a.core[i] !== b.core[i]) return a.core[i] < b.core[i] ? -1 : 1;
+  }
+  if (!a.prerelease.length || !b.prerelease.length) {
+    return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length ? -1 : 1;
+  }
+  for (let i = 0; i < Math.max(a.prerelease.length, b.prerelease.length); i++) {
+    const x = a.prerelease[i];
+    const y = b.prerelease[i];
+    if (x === y) continue;
+    if (x === undefined || y === undefined) return x === undefined ? -1 : 1;
+    const xn = /^\d+$/.test(x);
+    const yn = /^\d+$/.test(y);
+    if (xn && yn) return x.length !== y.length ? (x.length < y.length ? -1 : 1) : x < y ? -1 : 1;
+    if (xn !== yn) return xn ? -1 : 1;
+    return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+function runtimeGenerationSha256(bytes, notices, crypto) {
+  return crypto.createHash('sha256').update(String(bytes.length) + ':').update(bytes).update(notices === null ? '-1:' : String(notices.length) + ':').update(notices || Buffer.alloc(0)).digest('hex');
+}
+
+function resolveRuntimePin(
+  codeledgerDir,
+  io,
+  compare,
+) {
+  const manifestPath = io.path.join(codeledgerDir, 'runtime.json');
+  if (!io.fs.existsSync(manifestPath)) return null;
+  if (io.fs.lstatSync(codeledgerDir).isSymbolicLink() || io.fs.lstatSync(manifestPath).isSymbolicLink()) throw new Error('Runtime state must not be symlinked. Run codeledger vendor from the owning repository.');
+  if (io.fs.statSync(manifestPath).size > 65536) throw new Error('runtime.json exceeds its 64 KiB contract bound. Repair with codeledger vendor.');
+  let raw;
+  try { raw = JSON.parse(io.fs.readFileSync(manifestPath, 'utf8')); } catch (error) { throw new Error('.codeledger/runtime.json is not valid JSON (' + error.message + '). Restore it from version control, or repair with codeledger vendor.'); }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('Invalid runtime.json: expected an object. Repair with codeledger vendor.');
+  const m = raw;
+  if (m.schema_version !== 'codeledger/runtime/v1' || typeof m.installation_id !== 'string' || typeof m.version !== 'string' || typeof m.min_runtime !== 'string'
+    || typeof m.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(m.sha256)
+    || (m.distribution !== 'full' && m.distribution !== 'open') || !['fail-open-v1', 'legacy'].includes(m.hook_contract)
+    || !m.source || typeof m.source.kind !== 'string' || typeof m.source.location !== 'string'
+    || !m.build || m.build.content_sha256 !== m.sha256 || (m.build.revision !== null && typeof m.build.revision !== 'string')
+    || (m.build.source_dirty !== undefined && m.build.source_dirty !== null && typeof m.build.source_dirty !== 'boolean')
+    || (m.build.generation_sha256 === undefined && m.build.legal_sha256 !== undefined)
+    || (m.build.generation_sha256 !== undefined && (typeof m.build.generation_sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(m.build.generation_sha256) || (m.build.legal_sha256 !== null && !/^[a-f0-9]{64}$/.test(m.build.legal_sha256))))
+    || typeof m.entrypoint !== 'string' || m.entrypoint !== `bin/runtime/${m.version}-${m.build.generation_sha256 || m.sha256}/codeledger-standalone.cjs`) {
+    throw new Error('Invalid runtime.json contract. Repair with codeledger vendor.');
+  }
+  for (const reference of [m.previous, m.migration_fallback]) {
+    if (reference === undefined) continue;
+    if (!reference || typeof reference !== 'object' || !/^[a-f0-9]{64}$/.test(reference.sha256) || typeof reference.entrypoint !== 'string') throw new Error('Invalid previous runtime reference. Repair with codeledger vendor.');
+    if (reference.version !== null) compare(reference.version, reference.version);
+    const generation = reference.generation_sha256 || reference.sha256;
+    if (!/^[a-f0-9]{64}$/.test(generation) || (reference.entrypoint !== `bin/runtime/legacy-${reference.sha256}/codeledger-standalone.cjs` && (reference.version === null || reference.entrypoint !== `bin/runtime/${reference.version}-${generation}/codeledger-standalone.cjs`))) throw new Error('Invalid previous runtime path. Repair with codeledger vendor.');
+  }
+  if (compare(m.version, m.min_runtime) < 0) throw new Error('Pinned runtime is older than its configuration contract. Run codeledger upgrade.');
+  if (compare(m.version, '0.10.82-0') >= 0 && m.build.generation_sha256 === undefined) throw new Error('Runtime generation identity is missing. Repair with codeledger vendor.');
+  const root = io.fs.realpathSync(codeledgerDir);
+  if (!io.fs.existsSync(io.path.resolve(root, m.entrypoint))) throw new Error('Pinned runtime is missing: .codeledger/' + m.entrypoint + '. Restore it from version control (git checkout -- .codeledger/bin), or repair with codeledger vendor.');
+  const runtimePath = io.fs.realpathSync(io.path.resolve(root, m.entrypoint));
+  const rel = io.path.relative(root, runtimePath);
+  if (rel.startsWith('..') || io.path.isAbsolute(rel) || runtimePath !== io.path.resolve(root, m.entrypoint) || !io.fs.statSync(runtimePath).isFile()) {
+    throw new Error('Pinned runtime escapes the repository. Repair with codeledger vendor.');
+  }
+  const bytes = io.fs.readFileSync(runtimePath);
+  if (io.crypto.createHash('sha256').update(bytes).digest('hex') !== m.sha256) {
+    throw new Error('Pinned runtime checksum mismatch. Repair with codeledger vendor; do not execute the modified artifact.');
+  }
+  if (m.build.generation_sha256 !== undefined) {
+    let notices = null;
+    if (m.build.legal_sha256 !== null) {
+      const legal = runtimePath + '.LEGAL.txt';
+      if (!io.fs.existsSync(legal)) throw new Error('Pinned notices are missing: ' + legal + '. Restore them from version control, or repair with codeledger vendor.');
+      if (io.fs.lstatSync(legal).isSymbolicLink()) throw new Error('Pinned notices must not be symlinked. Repair with codeledger vendor.');
+      notices = io.fs.readFileSync(legal);
+      if (io.crypto.createHash('sha256').update(notices).digest('hex') !== m.build.legal_sha256) throw new Error('Pinned notices checksum mismatch. Repair with codeledger vendor.');
+    }
+    if (runtimeGenerationSha256(bytes, notices, io.crypto) !== m.build.generation_sha256) throw new Error('Pinned generation checksum mismatch. Repair with codeledger vendor.');
+  }
+  const header = bytes.subarray(0, 65536).toString('utf8');
+  const version = /^\/\* CODELEDGER_STANDALONE_VERSION:([^\s*]+) \*\//m.exec(header)?.[1];
+  const flavor = header.includes('/* CodeLedger Open CLI') ? 'open' : header.includes('/* CodeLedger Standalone CLI') ? 'full' : null;
+  if (version !== m.version || flavor !== m.distribution) throw new Error('Pinned runtime version or distribution does not match runtime.json.');
+  return { manifest: m, path: runtimePath };
+}
+
+
+function runtimeTrustKey(root, manifest, io) {
+  return io.crypto.createHash('sha256').update(JSON.stringify([io.fs.realpathSync(root), manifest])).digest('hex');
+}
+function isRuntimePinTrusted(root, manifest, io, trustDir) {
+  if (!trustDir || trustDir === 'disabled') return false;
+  try {
+    const directory = io.fs.realpathSync(trustDir);
+    const repo = io.fs.realpathSync(root);
+    const relative = io.path.relative(repo, directory);
+    if (!relative || (!relative.startsWith('..' + io.path.sep) && relative !== '..' && !io.path.isAbsolute(relative))) return false;
+    const key = runtimeTrustKey(root, manifest, io);
+    const file = io.path.join(directory, key + '.json');
+    const stat = io.fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096) return false;
+    const receipt = JSON.parse(io.fs.readFileSync(file, 'utf8'));
+    return receipt.schema === 1 && receipt.key === key;
+  } catch { return false; }
+}
+return {parseRuntimeVersion, compareRuntimeVersions, resolveRuntimePin, runtimeGenerationSha256, runtimeTrustKey, isRuntimePinTrusted};
+})();