@aiwg/cli 2026.10.6 → 2026.10.8

package/dist/src/decision/ask.js

@@ -495,6 +495,11 @@ export async function setupJev(input = {}, options = {}) {
         next: ['Run aiwg decision ask --question "<q>" --yes-no --json.'],
     };
     if (input.verify) {
+        // Verify the credential just saved, even when the shell still names an
+        // older token. Ordinary ask calls retain their environment precedence.
+        const verificationEnv = { ...environment };
+        delete verificationEnv.JEV_API_KEY;
+        delete verificationEnv.AIWG_DECISION_JEV_API_KEY;
         const verified = await askDecision({
             question: 'Is this Jev decision setup verification request well formed?',
             mode: { kind: 'yes-no' },
@@ -502,7 +507,7 @@ export async function setupJev(input = {}, options = {}) {
             timeoutMs: 15_000,
             passes: 1,
             escalationPasses: 1,
-        }, options);
+        }, { ...options, env: verificationEnv });
         result.verified = verified.status === 'answered';
         result.model = verified.model;
         result.usage = verified.usage;

package/dist/src/decision/benchmark.js

@@ -57,7 +57,7 @@ export function benchmarkComparison(capture, pricing) {
             return `| Jev, ${passes} pass${passes === 1 ? '' : 'es'} | ${display(t.input)} | n/a | ${display(t.output)} | ${display(t.input === null || t.output === null ? null : t.input + t.output)} | ${t.latency.toFixed(1)} | ${money(t.cost)} |`;
         }),
         `| ${capture.baselineLabel.replace(/[|\r\n]/g, ' ')} | ${display(baseline.input)} | ${display(baseline.cached)} | ${display(baseline.output)} | ${display(baseline.input === null || baseline.output === null ? null : baseline.input + baseline.output)} | ${baseline.latency.toFixed(1)} | ${money(baseline.cost)} |`, '',
-        capture.rows.some(r => r.baseline.cost || r.jev.some(s => s.cost)) ? 'Captured costs use sourced rates recorded per observation; unknown costs remain unknown.' : pricing ? `Rates: decision.ask.cost.* (${pricing.source ?? 'manual'}, checked ${pricing.checked_at ?? 'unknown'}).` : 'Costs unknown: no explicit decision.ask.cost.* rates.',
+        capture.rows.some(r => r.baseline.cost || r.jev.some(s => s.cost)) ? 'Captured costs use provider-reported USD or sourced rates recorded per observation; unknown costs remain unknown.' : pricing ? `Rates: decision.ask.cost.* (${pricing.source ?? 'manual'}, checked ${pricing.checked_at ?? 'unknown'}).` : 'Costs unknown: no explicit decision.ask.cost.* rates.',
         'Costs use reported usage and explicit pricing assumptions, not subscription invoices.',
         'Standalone baseline requests do not measure the marginal cost of an inline LLM decision.',
     ];
@@ -116,6 +116,9 @@ function validCost(sample) {
     if (sample.cost === undefined)
         return true;
     const cost = sample.cost;
+    if (cost?.source === 'provider-reported')
+        return fields(cost, ['usd', 'price', 'source'])
+            && cost.price === null && typeof cost.usd === 'number' && Number.isFinite(cost.usd) && cost.usd >= 0;
     return fields(cost, ['usd', 'price']) && (cost.price === null ? cost.usd === null
         : validPrice(cost.price) && cost.price.model === sample.model && cost.usd === tokenCost(sample.usage, cost.price));
 }
@@ -128,10 +131,18 @@ export async function collectBenchmark(dataset, options) {
         throw new Error('Positive maxUsd required for live collection.');
     if (!Number.isInteger(options.passes) || options.passes < 1 || options.passes > MAX_BENCHMARK_PASSES)
         throw new Error('passes must be 1..20.');
+    if (options.jevCapture && options.extendCapture)
+        throw new Error('Cannot combine Jev reuse and capture extension.');
     const cases = splitBenchmarkHoldout(dataset, options.holdout ?? 0.3, options.seed ?? '3291');
     const prior = options.extendCapture;
     if (prior)
         validateBenchmarkCapture(cases, prior);
+    const reused = options.jevCapture;
+    if (reused) {
+        validateBenchmarkCapture(cases, reused);
+        if (reused.rows.length !== cases.length || reused.rows.some(row => row.jev.length !== options.passes))
+            throw new Error('Reused Jev capture must contain every case with the same pass count.');
+    }
     if (typeof options.baselineLabel !== 'string' || !options.baselineLabel.trim() || options.baselineLabel.length > 200
         || prior && prior.baselineLabel !== options.baselineLabel)
         throw new Error('Invalid or changed baseline label.');
@@ -147,7 +158,7 @@ export async function collectBenchmark(dataset, options) {
         throw new Error('Extension cannot remove existing passes.');
     const planned = cases.reduce((sum, c) => {
         const row = rows.find(r => r.id === c.id);
-        return sum + (row ? 0 : 1) + Math.max(0, options.passes - (row?.jev.length ?? 0));
+        return sum + (row ? 0 : 1) + (reused ? 0 : Math.max(0, options.passes - (row?.jev.length ?? 0)));
     }, 0);
     if (planned > options.maxCalls)
         throw new Error(`Insufficient maxCalls: need ${planned}; no providers invoked.`);
@@ -177,7 +188,7 @@ export async function collectBenchmark(dataset, options) {
         return capture;
     }
     const environment = options.env ?? process.env;
-    if (!options.jev && planned > 0 && cases.some(c => (rows.find(r => r.id === c.id)?.jev.length ?? 0) < options.passes)
+    if (!reused && !options.jev && planned > 0 && cases.some(c => (rows.find(r => r.id === c.id)?.jev.length ?? 0) < options.passes)
         && !(environment.JEV_API_KEY?.trim() || environment.AIWG_DECISION_JEV_API_KEY?.trim()))
         throw new Error('Live benchmark requires JEV_API_KEY or AIWG_DECISION_JEV_API_KEY in the caller environment.');
     const jev = options.jev ?? (async (input) => {
@@ -201,8 +212,9 @@ export async function collectBenchmark(dataset, options) {
         if (!validObservation(sample) || !modeAnswer(c, sample))
             throw new Error(`Invalid provider observation: ${c.id}`);
         const price = (baseline ? options.baselinePrices ?? [] : jevPrices).find(p => p.model === sample.model) ?? null;
-        const usd = price ? tokenCost(sample.usage, price) : null;
-        sample.cost = { usd, price: structuredClone(price) };
+        sample.cost = result.cost?.source === 'provider-reported' && validCost(result)
+            ? structuredClone(result.cost) : { usd: price ? tokenCost(sample.usage, price) : null, price: structuredClone(price) };
+        const usd = sample.cost.usd;
         if (usd === null)
             stopReason = 'unknown-cost';
         else {
@@ -215,7 +227,8 @@ export async function collectBenchmark(dataset, options) {
     for (const c of cases) {
         let row = rows.find(r => r.id === c.id);
         if (!row) {
-            row = { id: c.id, baseline: await invoke(c, true), jev: [] };
+            row = { id: c.id, baseline: await invoke(c, true),
+                jev: structuredClone(reused?.rows.find(r => r.id === c.id).jev ?? []) };
             rows.push(row);
         }
         if (options.onCheckpoint)

package/dist/src/decision/driver.js

@@ -4,12 +4,12 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { askDecision, setupJev, DecisionAskUsageError, readDecisionContextFile, validateDecisionAskInput, } from './ask.js';
-import { recordDecisionAsk, decisionLedgerHistory, decisionLedgerStats, resolveDecisionSessionId, resolveDecisionSession, DECISION_SESSION_ENV_VARS, parseDecisionLedgerSince, DecisionLedgerSinceError, DECISION_LEDGER_SCHEMA, DECISION_LEDGER_SCHEMA_V1, ATTRIBUTION_FIELD_PATTERN, MAX_ATTRIBUTION_FIELD_LENGTH, MAX_RECORDED_CHOICE_IDS, MAX_RECORD_TEXT_BYTES, MAX_LEDGER_RECORD_BYTES, DECISION_LEDGER_RECORD_TIMEOUT_MS, DECISION_SAVINGS_REASONING_ALLOWANCE_TOKENS, DECISION_SAVINGS_ESTIMATION_METHOD, buildDecisionLedgerRecord, appendDecisionLedgerRecord, filterDecisionLedgerRecords, } from './ledger.js';
+import { recordDecisionAsk, decisionLedgerHistory, decisionLedgerStats, rotateDecisionLedger, parseDecisionLedgerRetention, resolveDecisionSessionId, resolveDecisionSession, DECISION_SESSION_ENV_VARS, parseDecisionLedgerSince, DecisionLedgerSinceError, DECISION_LEDGER_SCHEMA, DECISION_LEDGER_SCHEMA_V1, ATTRIBUTION_FIELD_PATTERN, MAX_ATTRIBUTION_FIELD_LENGTH, MAX_RECORDED_CHOICE_IDS, MAX_RECORD_TEXT_BYTES, MAX_LEDGER_RECORD_BYTES, DECISION_LEDGER_RECORD_TIMEOUT_MS, DECISION_SAVINGS_REASONING_ALLOWANCE_TOKENS, DECISION_SAVINGS_ESTIMATION_METHOD, buildDecisionLedgerRecord, appendDecisionLedgerRecord, filterDecisionLedgerRecords, } from './ledger.js';
 export { DEFAULT_DECISION_SAVINGS_WEIGHTS, decisionSavingsWeights } from './savings.js';
 import { resolveActiveProvider } from '../cli/provider-resolution.js';
 export { appendDecisionOpportunity, buildDecisionOffloadSnapshot, decisionOffloadCategory, DECISION_OFFLOAD_CHECKPOINT_COVERAGE, DECISION_OFFLOAD_EXECUTABLE_COVERAGE, DECISION_OFFLOAD_SNAPSHOT_SCHEMA, DECISION_OPPORTUNITY_SCHEMA, runDecisionOffloadCheckpoint, } from './offload.js';
 import { assertDecisionEvaluateDispatcherConfig, decisionPatternPacks, getDecisionPatternPack, governedPatternArtifacts, listDecisionPatterns, patternInputSchema, patternOutputSchema, planLiveDecisionPattern, runOfflineDecisionPattern, validateAgainstSchema, validateDecisionDocument, validateDefinition, validateRuleset, } from './index.js';
-export { askDecision, setupJev, readDecisionContextFile, validateDecisionAskInput, DecisionAskUsageError, recordDecisionAsk, decisionLedgerHistory, decisionLedgerStats, resolveDecisionSessionId, resolveDecisionSession, DECISION_SESSION_ENV_VARS, parseDecisionLedgerSince, DecisionLedgerSinceError, DECISION_LEDGER_SCHEMA, DECISION_LEDGER_SCHEMA_V1, ATTRIBUTION_FIELD_PATTERN, MAX_ATTRIBUTION_FIELD_LENGTH, MAX_RECORDED_CHOICE_IDS, MAX_RECORD_TEXT_BYTES, MAX_LEDGER_RECORD_BYTES, DECISION_LEDGER_RECORD_TIMEOUT_MS, DECISION_SAVINGS_REASONING_ALLOWANCE_TOKENS, DECISION_SAVINGS_ESTIMATION_METHOD, buildDecisionLedgerRecord, appendDecisionLedgerRecord, filterDecisionLedgerRecords, resolveActiveProvider, };
+export { askDecision, setupJev, readDecisionContextFile, validateDecisionAskInput, DecisionAskUsageError, recordDecisionAsk, decisionLedgerHistory, decisionLedgerStats, rotateDecisionLedger, parseDecisionLedgerRetention, resolveDecisionSessionId, resolveDecisionSession, DECISION_SESSION_ENV_VARS, parseDecisionLedgerSince, DecisionLedgerSinceError, DECISION_LEDGER_SCHEMA, DECISION_LEDGER_SCHEMA_V1, ATTRIBUTION_FIELD_PATTERN, MAX_ATTRIBUTION_FIELD_LENGTH, MAX_RECORDED_CHOICE_IDS, MAX_RECORD_TEXT_BYTES, MAX_LEDGER_RECORD_BYTES, DECISION_LEDGER_RECORD_TIMEOUT_MS, DECISION_SAVINGS_REASONING_ALLOWANCE_TOKENS, DECISION_SAVINGS_ESTIMATION_METHOD, buildDecisionLedgerRecord, appendDecisionLedgerRecord, filterDecisionLedgerRecords, resolveActiveProvider, };
 const DECISION_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const VALIDATION_TARGETS = ['request', 'definition', 'ruleset', 'binding'];
 const OFFLINE_ADAPTER = 'agentic/code/addons/decision-engine/examples/fixture-jev-adapter.mjs';

package/dist/src/decision/jev-credentials.js

@@ -1,10 +1,11 @@
 import { resolveDecisionEnablement } from '../config/decision-config.js';
 import { constants } from 'node:fs';
-import { access, chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { access, chmod, lstat, mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { JevCredentialError } from './adapters/jev.js';
+import { readPrivateValueFile } from '../auth/sensitive-input.js';
 export const JEV_CREDENTIAL_REF = 'typesafe-api';
 export const JEV_DEFAULT_REGION = 'us';
 function env(options) {
@@ -45,10 +46,22 @@ function parseRecord(raw) {
 async function readCredentialFile(options = {}) {
     const credentialPath = jevCredentialPath(options);
     try {
-        const [fileStat, parentStat] = await Promise.all([stat(credentialPath), stat(path.dirname(credentialPath))]);
-        if (isInsecureMode(fileStat.mode) || isInsecureMode(parentStat.mode))
-            throw new JevCredentialError('denied');
-        return parseRecord(await readFile(credentialPath, 'utf8'));
+        // Preserve the missing-file result and the existing directory requirement.
+        // The shared reader validates the opened descriptor, including ownership
+        // and link checks, before any credential record is parsed.
+        const [, parentStat] = await Promise.all([lstat(credentialPath), stat(path.dirname(credentialPath))]);
+        if (isInsecureMode(parentStat.mode)) {
+            throw Object.assign(new JevCredentialError('denied'), { message: 'Jev credential directory must not allow group or other access (chmod 700).' });
+        }
+        let raw;
+        try {
+            raw = await readPrivateValueFile(credentialPath, 'Jev credential file');
+        }
+        catch (error) {
+            // Shared private-file diagnostics contain no path or credential bytes.
+            throw Object.assign(new JevCredentialError('denied'), { message: error.message });
+        }
+        return parseRecord(raw);
     }
     catch (error) {
         if (error.code === 'ENOENT')

package/dist/src/decision/ledger.js

@@ -21,9 +21,9 @@
  * assumption that the artifact root is owned and written by the SAME local
  * user running `aiwg`. It does not and cannot defend against a HOSTILE
  * process running as that same user: such a process already has read/write
- * access to everything the ledger could protect. There is no cross-process
- * lock and no privilege boundary here, by design — adding one would be the
- * "second subsystem" this feature deliberately avoids. Every filesystem
+ * access to everything the ledger could protect. Appenders, rotation and
+ * readers share the existing cross-process directory-lock helper. There is
+ * no privilege boundary here. Every filesystem
  * check below uses only portable Node primitives (no `/proc`, no handle
  * anchoring): `mkdir`/`lstat` for the directory, `open`+`fstat` for the
  * file, with `O_NOFOLLOW` applied when the platform defines it (POSIX; not
@@ -39,25 +39,26 @@
  * single-write atomicity boundary most platforms also honor for `PIPE_BUF`
  * (4096 bytes on Linux): this makes a single, non-interleaved write the
  * overwhelmingly likely outcome for one record, but it is not a guarantee.
- * There is no cross-process append lock, so two concurrent writers can in
- * rare cases interleave and produce one malformed line; `history`/`stats`
- * detect and skip a malformed line (counted, never silently merged into a
- * neighboring record) rather than assuming it is impossible.
+ * The lock covers opening, checking the trailing newline, writing every
+ * byte and closing. Rotation holds that same lock through live-file
+ * replacement. `history`/`stats` count malformed lines as skipped; retention
+ * preserves their original bytes.
  *
  * Recording — attribution resolution and the write — is bounded by a short
  * deadline (`DECISION_LEDGER_RECORD_TIMEOUT_MS`). On timeout, the in-flight
  * attempt is not cancelled (Node has no way to abort an in-flight `open`),
  * so its outcome is genuinely unknown: the record may or may not eventually
  * land. The warning says exactly that ("completion unknown"), and no
- * further stage of that same attempt starts once the deadline has fired
- * (checked before each later `await`), so a slow attribution lookup cannot
- * itself delay the subsequent write past the deadline.
+ * attribution-to-append stage starts once the deadline has fired. An append
+ * already waiting for the ledger lock can still complete after that deadline.
  */
 import { randomUUID, createHash } from 'node:crypto';
 import { constants as fsConstants, createReadStream, existsSync } from 'node:fs';
-import { lstat, mkdir, open } from 'node:fs/promises';
+import { lstat, mkdir, open, readdir, rename, rm } from 'node:fs/promises';
 import { createInterface } from 'node:readline';
-import { join } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { acquireDirectoryLock } from '../artifacts/prebuilt-build-lock.js';
+import { syncDirectory } from '../storage/protected-files.js';
 import { projectAiwgPath, projectAiwgWritePath } from '../config/project-artifacts.js';
 import { redactText } from '../governance/redaction.js';
 import { CanonicalJsonByteEstimator } from './context-plan.js';
@@ -121,6 +122,7 @@ export const MAX_LEDGER_RECORD_BYTES = 4000;
 export const DECISION_LEDGER_RECORD_TIMEOUT_MS = 250;
 const LEDGER_DIR_MODE = 0o700;
 const LEDGER_FILE_MODE = 0o600;
+const LEDGER_LOCK_TIMEOUT_MS = 30_000;
 const IS_WINDOWS = process.platform === 'win32';
 const HAS_O_NOFOLLOW = typeof fsConstants.O_NOFOLLOW === 'number';
 function errorMessage(error) {
@@ -349,8 +351,8 @@ async function ensurePrivateDecisionDir(projectRoot, warn) {
     return decisionDir;
 }
 /**
- * Open (creating if needed) `ledger.jsonl` for append and verify it is safe
- * to write: a regular file with exactly one hard link (rejects a
+ * Open a private ledger/archive file (append by default, read-only for
+ * retention) and verify it is a regular file with exactly one hard link (rejects a
  * pre-planted hard link to an unrelated file, which `O_NOFOLLOW` alone does
  * not catch), and on POSIX owned by the current user with no group/other
  * permission bits. `O_NOFOLLOW` is applied when the platform defines it
@@ -360,7 +362,7 @@ async function ensurePrivateDecisionDir(projectRoot, warn) {
  * check is closed untouched (no chmod, no write) and recording is skipped
  * with exactly one warning naming the reason.
  */
-async function openLedgerFileForAppend(ledgerPath, warn) {
+async function openPrivateLedgerFile(ledgerPath, warn, flags = fsConstants.O_APPEND | fsConstants.O_CREAT | fsConstants.O_WRONLY) {
     try {
         const pre = await lstat(ledgerPath);
         if (pre.isSymbolicLink()) {
@@ -374,10 +376,9 @@ async function openLedgerFileForAppend(ledgerPath, warn) {
             return null;
         }
     }
-    const flags = fsConstants.O_APPEND | fsConstants.O_CREAT | fsConstants.O_WRONLY | (HAS_O_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
     let handle;
     try {
-        handle = await open(ledgerPath, flags, LEDGER_FILE_MODE);
+        handle = await open(ledgerPath, flags | (HAS_O_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0), LEDGER_FILE_MODE);
     }
     catch (error) {
         warn(`warning: cannot open decision ledger file: ${errorMessage(error)}`);
@@ -466,10 +467,13 @@ export async function appendDecisionLedgerRecord(record, options) {
     if (!decisionDir)
         return false;
     const ledgerPath = join(decisionDir, DECISION_LEDGER_FILE_NAME);
-    const handle = await openLedgerFileForAppend(ledgerPath, warn);
-    if (!handle)
-        return false;
+    let release;
+    let handle = null;
     try {
+        release = await lockDecisionLedger(decisionDir);
+        handle = await openPrivateLedgerFile(ledgerPath, warn);
+        if (!handle)
+            return false;
         const prefix = (await needsLeadingNewline(ledgerPath)) ? '\n' : '';
         await writeFully(handle, Buffer.from(prefix + line, 'utf8'), options.writeChunk);
         return true;
@@ -479,7 +483,162 @@ export async function appendDecisionLedgerRecord(record, options) {
         return false;
     }
     finally {
-        await handle.close().catch(() => { });
+        await handle?.close().catch(() => { });
+        await release?.().catch(error => warn(`warning: cannot release decision ledger lock: ${errorMessage(error)}`));
+    }
+}
+function lockDecisionLedger(decisionDir) {
+    return acquireDirectoryLock(join(decisionDir, 'ledger.lock'), {
+        timeoutMs: LEDGER_LOCK_TIMEOUT_MS, pollMs: 10, reclaimDeadOwner: true,
+    });
+}
+export function parseDecisionLedgerRetention(keepLast, all = false) {
+    if (all) {
+        if (keepLast !== undefined)
+            throw new Error('--all cannot be combined with --keep-last');
+        return {};
+    }
+    const match = /^(\d+)(d?)$/.exec(keepLast ?? '90d');
+    const n = match ? Number(match[1]) : NaN;
+    if (!Number.isSafeInteger(n) || n <= 0 || !Number.isSafeInteger(n * (match?.[2] ? 86_400_000 : 1))) {
+        throw new Error('--keep-last must be a positive count or <N>d; rotating everything requires --all');
+    }
+    return match?.[2] ? { ms: n * 86_400_000 } : { count: n };
+}
+function isBeneath(root, target) {
+    const rel = relative(root, target);
+    return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+/** Walk before mkdir: recursive mkdir alone could write through a symlinked ancestor. */
+async function privateArchiveDirectory(root, target, create) {
+    let current = root;
+    for (const part of relative(root, target).split(sep)) {
+        current = join(current, part);
+        if (create) {
+            try {
+                await mkdir(current, { mode: LEDGER_DIR_MODE });
+                if (!IS_WINDOWS)
+                    await syncDirectory(dirname(current));
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+        }
+        let info;
+        try {
+            info = await lstat(current);
+        }
+        catch (error) {
+            if (!create && error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+        // archive/ is shared with the activity log and may already be readable.
+        // Its decision/ subtree (and any nested directories) must be private.
+        const modeMask = current === join(root, 'archive') ? 0o022 : 0o077;
+        if (!info.isDirectory() || (!IS_WINDOWS && (info.uid !== currentUid() || (info.mode & modeMask) !== 0))) {
+            throw new Error(`Unsafe decision archive directory (requires a private, owned real directory): ${current}`);
+        }
+    }
+    return true;
+}
+/** Retention preserves each raw line, including invalid UTF-8, CRLF and an unterminated final line. */
+export async function rotateDecisionLedger(options) {
+    const retention = parseDecisionLedgerRetention(options.keepLast, options.all);
+    const now = (options.now ?? Date.now)();
+    const artifactRoot = projectAiwgWritePath(options.projectRoot);
+    const archiveRoot = join(artifactRoot, 'archive', 'decision');
+    const archivePath = resolve(artifactRoot, options.to ?? join('archive', 'decision', `${new Date(now).toISOString().replace(/[-:]/g, '').replace('T', '-').replace(/\.\d{3}Z$/, '')}-${randomUUID()}.jsonl`));
+    if (!isBeneath(artifactRoot, archivePath))
+        throw new Error('Archive path must stay inside the resolved artifact root');
+    if (!isBeneath(archiveRoot, archivePath) || !archivePath.endsWith('.jsonl')) {
+        throw new Error('Archive path must be a .jsonl file beneath archive/decision/ in the resolved artifact root');
+    }
+    const fail = (message) => { throw new Error(message); };
+    const decisionDir = await ensurePrivateDecisionDir(options.projectRoot, fail);
+    if (!decisionDir)
+        throw new Error('Cannot access decision ledger directory');
+    const release = await lockDecisionLedger(decisionDir);
+    const ledgerPath = join(decisionDir, DECISION_LEDGER_FILE_NAME);
+    const tempPath = join(decisionDir, `.ledger-${randomUUID()}.tmp`);
+    let archiveCreated = false;
+    try {
+        const live = await openPrivateLedgerFile(ledgerPath, fail, fsConstants.O_RDONLY | fsConstants.O_CREAT);
+        if (!live)
+            throw new Error('Cannot read decision ledger');
+        let content;
+        try {
+            content = await live.readFile();
+        }
+        finally {
+            await live.close();
+        }
+        const lines = [];
+        for (let start = 0; start < content.length;) {
+            const newline = content.indexOf(0x0a, start);
+            const end = newline < 0 ? content.length : newline + 1;
+            const bytes = content.subarray(start, end);
+            let timestamp = null;
+            try {
+                const record = JSON.parse(bytes.toString('utf8'));
+                if (isDecisionLedgerRecord(record))
+                    timestamp = Date.parse(record.timestamp);
+            }
+            catch { /* preserve malformed bytes */ }
+            lines.push({ bytes, timestamp });
+            start = end;
+        }
+        const valid = lines.filter(line => line.timestamp !== null).sort((a, b) => a.timestamp - b.timestamp);
+        const recent = new Set(retention.count === undefined ? [] : valid.slice(-retention.count));
+        const kept = [], archived = [];
+        for (const line of lines) {
+            const keep = !options.all && (line.timestamp === null || (retention.count !== undefined
+                ? recent.has(line) : line.timestamp >= now - retention.ms));
+            (keep ? kept : archived).push(line.bytes);
+        }
+        const result = { archived: archived.length, retained: kept.length,
+            malformed: lines.length - valid.length, archivePath: archived.length ? archivePath : null };
+        if (!archived.length)
+            return result;
+        await privateArchiveDirectory(artifactRoot, dirname(archivePath), true);
+        const archive = await open(archivePath, 'wx', LEDGER_FILE_MODE);
+        archiveCreated = true;
+        try {
+            await writeFully(archive, Buffer.concat(archived));
+            await archive.sync();
+        }
+        finally {
+            await archive.close();
+        }
+        if (!IS_WINDOWS)
+            await syncDirectory(dirname(archivePath));
+        const replacement = await open(tempPath, 'wx', LEDGER_FILE_MODE);
+        try {
+            await writeFully(replacement, Buffer.concat(kept));
+            await replacement.sync();
+        }
+        finally {
+            await replacement.close();
+        }
+        await rename(tempPath, ledgerPath);
+        archiveCreated = false; // Both files now own their respective records.
+        if (!IS_WINDOWS)
+            await syncDirectory(decisionDir);
+        return result;
+    }
+    catch (error) {
+        if (archiveCreated)
+            await rm(archivePath, { force: true }); // Live file is still intact.
+        throw error;
+    }
+    finally {
+        try {
+            await rm(tempPath, { force: true });
+        }
+        finally {
+            await release();
+        }
     }
 }
 /** Never throws: a provider-detection failure (missing config, unreadable capability matrix, …) degrades to "unknown". */
@@ -723,20 +882,57 @@ async function* streamDecisionLedgerLines(path) {
         rl.close();
     }
 }
-/** Streams parsed-and-validated records one at a time; invalid lines yield `null` so callers can count them as skipped. */
-async function* streamDecisionLedgerRecords(projectRoot) {
-    for await (const line of streamDecisionLedgerLines(ledgerReadPath(projectRoot))) {
-        const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        try {
-            const parsed = JSON.parse(trimmed);
-            yield isDecisionLedgerRecord(parsed) ? parsed : null;
+async function archiveLedgerPaths(artifactRoot, directory = join(artifactRoot, 'archive', 'decision')) {
+    if (!await privateArchiveDirectory(artifactRoot, directory, false))
+        return [];
+    const paths = [];
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const target = join(directory, entry.name);
+        if (entry.isSymbolicLink())
+            throw new Error(`Unsafe decision archive symlink: ${target}`);
+        if (entry.isDirectory())
+            paths.push(...await archiveLedgerPaths(artifactRoot, target));
+        else if (entry.name.endsWith('.jsonl')) {
+            const handle = await openPrivateLedgerFile(target, message => { throw new Error(message); }, fsConstants.O_RDONLY);
+            if (!handle)
+                throw new Error(`Unsafe decision archive: ${target}`);
+            await handle.close();
+            paths.push(target);
         }
-        catch {
-            yield null;
+    }
+    return paths.sort();
+}
+/** Streams validated records under the rotation lock; invalid lines yield null. */
+async function* streamDecisionLedgerRecords(projectRoot, includeArchives = false) {
+    const livePath = ledgerReadPath(projectRoot);
+    const decisionDir = dirname(livePath);
+    if (!existsSync(decisionDir))
+        return;
+    if (!(await lstat(decisionDir)).isDirectory())
+        throw new Error('Decision ledger directory must be a real directory');
+    // A single lock also prevents readers from observing the archive and live
+    // replacement at different points in a rotation (duplicates or omissions).
+    const release = await lockDecisionLedger(decisionDir);
+    try {
+        const paths = includeArchives ? [...await archiveLedgerPaths(projectAiwgPath(projectRoot)), livePath] : [livePath];
+        for (const path of paths) {
+            for await (const line of streamDecisionLedgerLines(path)) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    yield isDecisionLedgerRecord(parsed) ? parsed : null;
+                }
+                catch {
+                    yield null;
+                }
+            }
         }
     }
+    finally {
+        await release();
+    }
 }
 function matchesFilters(record, filters) {
     if (filters.since && new Date(record.timestamp).getTime() < filters.since.getTime())
@@ -765,7 +961,7 @@ export function filterDecisionLedgerRecords(records, filters) {
 export async function decisionLedgerHistory(projectRoot, filters = {}) {
     const records = [];
     let skipped = 0;
-    for await (const record of streamDecisionLedgerRecords(projectRoot)) {
+    for await (const record of streamDecisionLedgerRecords(projectRoot, filters.includeArchives)) {
         if (!record) {
             skipped += 1;
             continue;
@@ -897,7 +1093,7 @@ export async function decisionLedgerStats(projectRoot, filters = {}) {
     const weights = decisionSavingsWeights(config?.decision?.ask);
     const groups = new Map();
     let skipped = 0;
-    for await (const record of streamDecisionLedgerRecords(projectRoot)) {
+    for await (const record of streamDecisionLedgerRecords(projectRoot, filters.includeArchives)) {
         if (!record) {
             skipped += 1;
             continue;

package/dist/src/decision/qualification/gate-evidence.js

@@ -4,7 +4,7 @@ import { matchEvidenceDigest } from '../../gates/stats/index.js';
 import { CalibrationRegistry, calibrationArtifactDigest } from '../calibration/registry.js';
 import { validateCaseInventory } from './manifest.js';
 import { verifyQualificationSplits } from './quality.js';
-import { verifyDecisionStagedLoadRecord } from './load.js';
+import { DECISION_STAGED_LOAD_RESULT_VERSIONS, verifyDecisionStagedLoadRecord } from './load.js';
 import { validateReviewEvaluation } from '../review/validate.js';
 const range = (prefix, from, to) => Array.from({ length: to - from + 1 }, (_, index) => `${prefix}${String(from + index).padStart(2, '0')}`);
 export const DECISION_GATE_SUITES = {
@@ -34,7 +34,7 @@ export const DECISION_GATE_SUITES = {
 export const GATE_ARTIFACT_SCHEMAS = {
     'immutable-splits': 'decision-binary-benchmark-plan/v2',
     'calibration-qualified': 'decision-calibration-artifact/v1',
-    'load-manifest-qualified': 'decision-load-result/v1',
+    'load-manifest-qualified': 'decision-load-result/v2',
     'review-decision-recorded': 'decision-qualification-review/v1',
 };
 export const GATE_ARTIFACT_FLAGS = Object.keys(GATE_ARTIFACT_SCHEMAS);
@@ -127,7 +127,7 @@ function validCalibration(value, context) {
         && artifact.metrics.selectiveRisk <= artifact.profile.maximumSelectiveRisk;
 }
 function validLoadResult(value, context) {
-    if (!record(value) || value.schemaVersion !== GATE_ARTIFACT_SCHEMAS['load-manifest-qualified'])
+    if (!record(value) || !DECISION_STAGED_LOAD_RESULT_VERSIONS.includes(String(value.schemaVersion)))
         return false;
     // Legacy records remain readable, but only completed live v3 evidence bound to
     // this exact clean source revision can qualify the performance gate.
@@ -177,7 +177,9 @@ export function deriveGateEvidence(manifest, proof = {}) {
         const ref = manifest.gateArtifacts?.[flag];
         const versionOk = flag === 'immutable-splits'
             ? ref !== undefined && IMMUTABLE_SPLIT_VERSIONS.includes(ref.schemaVersion)
-            : ref !== undefined && ref.schemaVersion === GATE_ARTIFACT_SCHEMAS[flag];
+            : flag === 'load-manifest-qualified'
+                ? ref !== undefined && DECISION_STAGED_LOAD_RESULT_VERSIONS.includes(ref.schemaVersion)
+                : ref !== undefined && ref.schemaVersion === GATE_ARTIFACT_SCHEMAS[flag];
         flags[flag] = versionOk && ref !== undefined
             && typeof ref.artifact === 'string' && ref.artifact.length > 0 && sha256Pattern.test(ref.digest);
         if (flag === 'load-manifest-qualified') {