@clear-capabilities/agentic-security-scanner 0.162.0 → 0.163.1

package/src/posture/portfolio/wording.js

@@ -0,0 +1,59 @@
+// Bounded assurance wording (X-703.AC03).
+//
+// A scan that found nothing blocking has said something narrow: the checks that ran, on the code and policy it names, found nothing the
+// policy blocks. It has not said the software is safe, secure or free of vulnerabilities, and a signature on the result does not turn
+// it into independent certification. Unconditional "Safe to deploy" wording over-claims in exactly the case where a check did not
+// run, so with the `portfolio-assurance` feature on the verdict becomes the headline below followed by the scope and the gaps.
+//
+// The old wording stays the default. Existing fixtures and docs pin it; the change is additive behind the feature flag
+// (assurance/config.js, `portfolio-assurance`, default off), so a flag-off run is byte-identical to before.
+
+import { resolveAssuranceConfig, featureStatus } from '../assurance/config.js';
+
+export const FEATURE_ID = 'portfolio-assurance';
+export const HEADLINE = 'No blocking findings in completed supported checks';
+export const BLOCKED_HEADLINE = 'Blocking findings present in completed supported checks';
+const INCOMPLETE_HEADLINE = 'Blocking-finding checks did not complete';
+export const NOT_A_GUARANTEE = 'This does not mean the software is safe or free of vulnerabilities, and a signature on it is not independent certification.';
+
+/** Is the bounded wording on? An explicit boolean option wins; otherwise the assurance configuration (kill switch, environment, project file) decides. */
+export function portfolioAssuranceEnabled({ option, env = process.env, scanRoot } = {}) {
+  if (typeof option === 'boolean') return option;
+  try {
+    return featureStatus(resolveAssuranceConfig({ scanRoot, env }), FEATURE_ID).status === 'ok';
+  } catch { return false; }
+}
+
+/**
+ * The bounded statement for a validated manifest: headline, scope and gaps, in that order. `signature` is the optional result of
+ * `verifyAssuranceClaim`; it can only ADD the trust-basis disclosure, never soften the headline.
+ */
+export function assuranceStatement(manifest, { signature = null } = {}) {
+  const cov = manifest.coverage;
+  const blocking = manifest.findings.blocking;
+  let headline = HEADLINE;
+  if (blocking > 0) headline = `${BLOCKED_HEADLINE}: ${blocking}`;
+  else if (!cov.complete) headline = `${HEADLINE}, but the mandatory scope is not fully covered`;
+  const scope = `Scope: ${cov.completed} of ${cov.mandatory} mandatory checks completed, ${cov.waived} waived, ${cov.incomplete} incomplete, ${cov.unsupported} unsupported. ${manifest.scope.description}`;
+  const gaps = [];
+  for (const c of manifest.checks.incomplete) gaps.push(`incomplete: ${c.id} (${c.gaps.join('; ')})`);
+  for (const c of manifest.checks.unsupported) gaps.push(`unsupported: ${c.id} (${c.gaps.join('; ')})`);
+  for (const c of manifest.checks.waived) gaps.push(`waived: ${c.id} (${c.reason}; approved by ${c.approvedBy})`);
+  for (const r of manifest.residualRisks) gaps.push(`residual risk: ${r.id} (${r.statement})`);
+  const lines = [headline, scope, gaps.length ? `Gaps: ${gaps.join(' | ')}` : 'Gaps: none recorded in the manifest', `Policy: ${manifest.policy.id} (blocking severity ${manifest.policy.blockingSeverity} and above)`];
+  if (manifest.synthetic === true) lines.push('Synthetic fixture: this describes no real release.');
+  if (signature) {
+    lines.push(signature.ok
+      ? `Signature: valid under trust basis ${signature.trustBasis} (self-issued, signer ${signature.signer}). It shows the manifest is unmodified; it is not independent certification.`
+      : `Signature: NOT valid (${signature.reason}). Treat this statement as unverified.`);
+  }
+  lines.push(NOT_A_GUARANTEE);
+  return { headline, scope, gaps, blocking, complete: cov.complete, text: lines.join('\n') };
+}
+
+/** Headline for the one-screen scan verdict, from what a plain scan knows (no manifest). */
+export function scanVerdictWording({ clean, scanIncomplete, actionableCount }) {
+  if (clean) return { icon: '✅', headline: HEADLINE, tier: 'ok' };
+  if (actionableCount === 0 && scanIncomplete) return { icon: '⚠️', headline: INCOMPLETE_HEADLINE, tier: 'incomplete' };
+  return { icon: '❌', headline: `${BLOCKED_HEADLINE}: ${actionableCount}`, tier: 'blocked' };
+}

package/src/posture/portfolio/work-units.js

@@ -0,0 +1,405 @@
+// Durable, leased portfolio work units (X-704).
+//
+// fleet.js already gives a many-repository run isolation, bounded concurrency and a per-repository completed marker. What it cannot do
+// is say WHICH unit of work was in flight when a process died, hand that unit to another worker without doing it twice, or refuse to
+// count a half-finished attempt as progress. This module adds that, in the same local-first shape: one JSON file, written atomically,
+// no server, no network.
+//
+//   PLAN      `planPortfolio` decomposes the AUTHORIZED repositories into units, one per (repository, exact commit, task type). A unit id
+//             is a hash of those three and its required inputs, so the same plan always yields the same ids (X-704.AC01); a repository
+//             that is not on the authorization list is excluded and disclosed, never silently planned.
+//   STATES    pending, leased, running, verified, blocked, failed, canceled. A lease has an expiry; an expired lease is recovered into
+//             pending (or failed once retries are spent). Every transition appends an event to the unit's attempt chain; the chain is
+//             hash-linked, so an attempt record can be read and verified but not rewritten (X-704.AC02).
+//   PROGRESS  only a unit in `verified` with a recorded result counts. A leased or running unit, a failed attempt, an expired lease and a
+//             duplicate delivery of a completion all leave the count where it was (X-704.AC03).
+//
+// Operations are idempotent by attempt id: delivering the same `complete` twice records one verification; delivering a completion for a
+// stale attempt (the lease expired and the unit moved on) is refused, because a zombie worker's result must not displace its successor's.
+//
+// The clock is an argument everywhere (`now`, milliseconds), so recovery is testable without sleeping and nothing here reads a clock.
+// Persistence is `mutateStore`: an exclusive lock file, read, verify, change, write to a temporary file, rename. A store that fails
+// verification is an error, never silently reset to empty.
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { canonicalJson } from '../evidence-bundle.js';
+import { digestOf } from '../assurance/identity.js';
+import { isCommit } from '../assurance/schema-kit.js';
+
+const STORE_SCHEMA = 'agentic-security/portfolio-store';
+const PLAN_SCHEMA = 'agentic-security/portfolio-plan';
+const STORE_VERSION = 1;
+export const UNIT_STATES = Object.freeze(['pending', 'leased', 'running', 'verified', 'blocked', 'failed', 'canceled']);
+const TASK_TYPES = Object.freeze(['sast-scan', 'sca-reachability', 'boundary-graph', 'invariant-scenarios', 'verification-replay', 'attestation']);
+export const DEPENDENCY_DIMENSIONS = Object.freeze(['code', 'policy', 'graph', 'invariant', 'oracle', 'toolchain']);
+
+export const PORTFOLIO_LIMITS = Object.freeze({
+  maxUnits: 5000, maxEventsPerUnit: 400, maxStoreBytes: 32 * 1024 * 1024, defaultLeaseMs: 5 * 60_000, maxLeaseMs: 6 * 60 * 60_000, defaultMaxRetries: 2, maxRetries: 10,
+  lockStaleMs: 30_000, lockWaitMs: 2000,
+});
+
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+
+// ---------------------------------------------------------------- plan
+
+const unitIdOf = (u) => `wu:${crypto.createHash('sha256').update(canonicalJson({ repository: u.repository, commit: u.commit, taskType: u.taskType, requiredInputs: u.requiredInputs })).digest('hex').slice(0, 16)}`;
+
+/**
+ * Decompose authorized repositories into stable work units.
+ *
+ * @param {object} a
+ * @param {Array<{name:string, commit:string}>} a.repositories   candidates, each pinned to an exact commit
+ * @param {string[]} a.authorized       the repository names the operator has authorized; anything else is excluded and disclosed
+ * @param {string[]} a.taskTypes        task types to run per repository (from TASK_TYPES)
+ * @param {Object<string,string[]>} [a.requiredInputs]  per task type, the named inputs the unit needs (e.g. ['source','policy'])
+ */
+export function planPortfolio({ repositories = [], authorized = [], taskTypes = [], requiredInputs = {}, synthetic = false } = {}) {
+  const errors = [];
+  const rejected = [];
+  const allow = new Set(authorized);
+  for (const t of taskTypes) if (!TASK_TYPES.includes(t)) errors.push({ code: 'UNKNOWN_TASK_TYPE', message: `'${t}' is not a task type` });
+  if (taskTypes.length === 0) errors.push({ code: 'NO_TASKS', message: 'a plan needs at least one task type' });
+  const seen = new Set();
+  const units = [];
+  for (const r of repositories) {
+    if (!r || typeof r.name !== 'string' || !r.name) { errors.push({ code: 'BAD_REPOSITORY', message: 'repository needs a name' }); continue; }
+    if (!allow.has(r.name)) { rejected.push({ repository: r.name, reason: 'not-authorized' }); continue; }
+    if (!isCommit(r.commit)) { errors.push({ code: 'UNBOUND_REVISION', message: `repository '${r.name}' is not pinned to an exact commit` }); continue; }
+    if (seen.has(r.name)) { errors.push({ code: 'DUPLICATE_REPOSITORY', message: `repository '${r.name}' is listed twice` }); continue; }
+    seen.add(r.name);
+    for (const taskType of taskTypes) {
+      const inputs = [...new Set(requiredInputs[taskType] ?? [])].sort();
+      const u = { repository: r.name, commit: r.commit, taskType, requiredInputs: inputs };
+      units.push({ id: unitIdOf(u), ...u });
+    }
+  }
+  if (units.length > PORTFOLIO_LIMITS.maxUnits) errors.push({ code: 'TOO_MANY_UNITS', message: `plan has ${units.length} units; the limit is ${PORTFOLIO_LIMITS.maxUnits}` });
+  units.sort((a, b) => (a.id < b.id ? -1 : 1));
+  const body = { schema: PLAN_SCHEMA, schemaVersion: '1.0.0', ...(synthetic ? { synthetic: true } : {}), units, rejected: rejected.sort((a, b) => (a.repository < b.repository ? -1 : 1)) };
+  return { ok: errors.length === 0, errors, plan: errors.length === 0 ? { ...body, id: `pplan:${digestOf(units).slice(7, 23)}` } : null };
+}
+
+// ---------------------------------------------------------------- state
+
+const eventDigest = (e) => digestOf(e);
+
+export function appendEvent(unit, ev) {
+  if (unit.events.length >= PORTFOLIO_LIMITS.maxEventsPerUnit) throw typedError('EVENT_LIMIT', `unit ${unit.id} reached ${PORTFOLIO_LIMITS.maxEventsPerUnit} recorded events`);
+  const prev = unit.events.length ? unit.events[unit.events.length - 1].digest : null;
+  const body = { seq: unit.events.length + 1, prev, ...ev };
+  unit.events.push({ ...body, digest: eventDigest(body) });
+}
+
+export function typedError(code, message, extra = {}) { return Object.assign(new Error(message), { code, ...extra }); }
+
+/** A new, empty store for a plan. */
+export function newStore(plan) {
+  if (!plan || plan.schema !== PLAN_SCHEMA) throw typedError('BAD_PLAN', 'not a portfolio plan');
+  const units = {};
+  for (const u of plan.units) {
+    units[u.id] = { ...u, state: 'pending', retryCount: 0, maxRetries: PORTFOLIO_LIMITS.defaultMaxRetries, generation: 0, attemptSeq: 0, lease: null, result: null, stale: [], blockedReason: null, events: [] };
+  }
+  return { schema: STORE_SCHEMA, version: STORE_VERSION, planId: plan.id, ...(plan.synthetic ? { synthetic: true } : {}), units };
+}
+
+/** Verify the store's internal consistency: event chains, state/lease/result agreement. Returns `{ ok, errors }`. */
+export function verifyStore(store) {
+  const errors = [];
+  if (!store || store.schema !== STORE_SCHEMA || store.version !== STORE_VERSION || typeof store.units !== 'object' || !store.units) return { ok: false, errors: [{ code: 'BAD_STORE', message: 'not a portfolio store of a supported version' }] };
+  for (const [id, u] of Object.entries(store.units)) {
+    if (u.id !== id || unitIdOf(u) !== id) errors.push({ code: 'ID_MISMATCH', unit: id, message: 'unit identity does not match its repository, commit, task type and inputs' });
+    if (!UNIT_STATES.includes(u.state)) errors.push({ code: 'BAD_STATE', unit: id, message: `unknown state '${u.state}'` });
+    let prev = null;
+    (u.events ?? []).forEach((e, i) => {
+      const { digest, ...body } = e;
+      if (e.seq !== i + 1 || e.prev !== prev || eventDigest(body) !== digest) errors.push({ code: 'EVENT_CHAIN_BROKEN', unit: id, message: `event ${i + 1} was altered or removed` });
+      prev = digest;
+    });
+    if ((u.state === 'leased' || u.state === 'running') !== !!u.lease) errors.push({ code: 'LEASE_STATE_MISMATCH', unit: id, message: 'a lease exists exactly when the unit is leased or running' });
+    if (u.state === 'verified' && !(u.result && DIGEST_RE.test(u.result.resultDigest ?? ''))) errors.push({ code: 'VERIFIED_WITHOUT_RESULT', unit: id, message: 'a verified unit must carry a result digest' });
+    if (u.state !== 'verified' && u.result) errors.push({ code: 'RESULT_WITHOUT_VERIFIED', unit: id, message: 'only a verified unit may carry a current result' });
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------- transitions (pure on a store object)
+
+const unitOf = (store, id) => {
+  const u = store.units[id];
+  if (!u) throw typedError('UNKNOWN_UNIT', `no such unit '${id}'`);
+  return u;
+};
+
+function clampLease(ttlMs) {
+  const t = ttlMs ?? PORTFOLIO_LIMITS.defaultLeaseMs;
+  if (!Number.isFinite(t) || t < 1) throw typedError('BAD_LEASE', 'lease duration must be a positive number of milliseconds');
+  return Math.min(t, PORTFOLIO_LIMITS.maxLeaseMs);
+}
+
+function spendAttempt(u, ev, now) {
+  // an attempt ended without a verified result: it costs a retry. Out of retries is a terminal failure.
+  u.lease = null;
+  u.retryCount += 1;
+  appendEvent(u, { ...ev, at: now });
+  u.state = u.retryCount > u.maxRetries ? 'failed' : 'pending';
+}
+
+/** Recover every unit whose lease has expired. Returns the ids recovered. */
+export function recoverExpired(store, now) {
+  const out = [];
+  for (const id of Object.keys(store.units).sort()) {
+    const u = store.units[id];
+    if ((u.state === 'leased' || u.state === 'running') && u.lease && u.lease.expiresAt <= now) {
+      const attemptId = u.lease.attemptId;
+      spendAttempt(u, { type: 'expired', attemptId, holder: u.lease.holder }, now);
+      out.push(id);
+    }
+  }
+  return out;
+}
+
+/**
+ * Lease the next pending unit (or a named one) to `holder`. A repeat of the same `requestId` from the same holder returns the same lease
+ * instead of leasing a second unit (duplicate delivery of the request). Returns `null` when nothing is leasable.
+ */
+export function leaseUnit(store, { holder, now, ttlMs, unitId = null, requestId = null, skip = () => false }) {
+  if (typeof holder !== 'string' || !holder) throw typedError('BAD_HOLDER', 'a lease needs a holder');
+  recoverExpired(store, now);
+  if (requestId) {
+    for (const u of Object.values(store.units)) {
+      if (u.lease && u.lease.requestId === requestId && u.lease.holder === holder) return { unitId: u.id, attemptId: u.lease.attemptId, expiresAt: u.lease.expiresAt, duplicate: true };
+    }
+  }
+  const candidates = unitId ? [unitOf(store, unitId)] : Object.values(store.units).sort((a, b) => (a.id < b.id ? -1 : 1));
+  const u = candidates.find((c) => c.state === 'pending' && !skip(c));
+  if (!u) return null;
+  u.attemptSeq += 1;
+  const attemptId = `${u.id}#${u.generation}.${u.attemptSeq}`;
+  const expiresAt = now + clampLease(ttlMs);
+  u.lease = { holder, attemptId, expiresAt, requestId };
+  u.state = 'leased';
+  appendEvent(u, { type: 'leased', attemptId, holder, at: now, expiresAt });
+  return { unitId: u.id, attemptId, expiresAt, duplicate: false };
+}
+
+function liveAttempt(store, unitId, attemptId, now) {
+  recoverExpired(store, now);
+  const u = unitOf(store, unitId);
+  if (!u.lease || u.lease.attemptId !== attemptId) return { u, ok: false };
+  return { u, ok: true };
+}
+
+/** leased -> running. Idempotent for the same attempt. */
+export function startUnit(store, { unitId, attemptId, now }) {
+  const { u, ok } = liveAttempt(store, unitId, attemptId, now);
+  if (!ok) return { ok: false, code: 'stale-attempt', reason: 'this attempt does not hold the lease (it expired, or the unit moved on)' };
+  if (u.state === 'running') return { ok: true, duplicate: true };
+  u.state = 'running';
+  appendEvent(u, { type: 'started', attemptId, at: now });
+  return { ok: true, duplicate: false };
+}
+
+/** Extend a live lease. */
+export function renewLease(store, { unitId, attemptId, now, ttlMs }) {
+  const { u, ok } = liveAttempt(store, unitId, attemptId, now);
+  if (!ok) return { ok: false, code: 'stale-attempt', reason: 'the lease is no longer held' };
+  u.lease.expiresAt = now + clampLease(ttlMs);
+  appendEvent(u, { type: 'renewed', attemptId, at: now, expiresAt: u.lease.expiresAt });
+  return { ok: true, expiresAt: u.lease.expiresAt };
+}
+
+/** A recorded result's dependency digests, one per dimension. All six are required: a result without them cannot be reused. */
+export function checkDependencies(deps) {
+  const missing = DEPENDENCY_DIMENSIONS.filter((d) => !DIGEST_RE.test(deps?.[d] ?? ''));
+  return missing;
+}
+
+/**
+ * Record a verified result. Accepted only from the live attempt, with all six dependency digests. A second delivery of the same
+ * completion is acknowledged and changes nothing; a completion from a stale attempt is refused.
+ */
+export function completeUnit(store, { unitId, attemptId, resultDigest, dependencies, now }) {
+  const u0 = unitOf(store, unitId);
+  if (u0.state === 'verified' && u0.result?.attemptId === attemptId) return { ok: true, duplicate: true, counted: false };
+  const { u, ok } = liveAttempt(store, unitId, attemptId, now);
+  if (!ok) return { ok: false, code: 'stale-attempt', reason: 'this attempt does not hold the lease (it expired, or the unit moved on); the result is discarded' };
+  if (!DIGEST_RE.test(resultDigest ?? '')) return { ok: false, code: 'bad-result', reason: 'a result needs a sha256 digest' };
+  const missing = checkDependencies(dependencies);
+  if (missing.length) return { ok: false, code: 'unbound-dependencies', reason: `result is missing dependency digests: ${missing.join(', ')}` };
+  const deps = Object.fromEntries(DEPENDENCY_DIMENSIONS.map((d) => [d, dependencies[d]]));
+  u.lease = null;
+  u.result = { attemptId, resultDigest, dependencies: deps, dependencyDigest: digestOf(deps), generation: u.generation };
+  u.state = 'verified';
+  appendEvent(u, { type: 'verified', attemptId, at: now, resultDigest, dependencyDigest: u.result.dependencyDigest });
+  return { ok: true, duplicate: false, counted: true };
+}
+
+/** The live attempt ended in failure. Costs a retry; out of retries the unit is terminally `failed`. */
+export function failUnit(store, { unitId, attemptId, reason, now }) {
+  const u0 = unitOf(store, unitId);
+  const dup = u0.events.some((e) => e.type === 'failed' && e.attemptId === attemptId);
+  if (dup) return { ok: true, duplicate: true };
+  const { u, ok } = liveAttempt(store, unitId, attemptId, now);
+  if (!ok) return { ok: false, code: 'stale-attempt', reason: 'this attempt does not hold the lease' };
+  spendAttempt(u, { type: 'failed', attemptId, holder: u.lease?.holder ?? null, reason: String(reason ?? 'failed').slice(0, 300) }, now);
+  return { ok: true, duplicate: false, state: u.state };
+}
+
+/** Park a unit that cannot proceed (a missing input). Not counted; independent units still run. */
+export function blockUnit(store, { unitId, reason, now }) {
+  const u = unitOf(store, unitId);
+  if (!['pending', 'leased', 'running'].includes(u.state)) return { ok: false, code: 'bad-state', reason: `cannot block a ${u.state} unit` };
+  u.lease = null; u.state = 'blocked'; u.blockedReason = String(reason ?? 'blocked').slice(0, 300);
+  appendEvent(u, { type: 'blocked', reason: u.blockedReason, at: now });
+  return { ok: true };
+}
+
+export function unblockUnit(store, { unitId, now }) {
+  const u = unitOf(store, unitId);
+  if (u.state !== 'blocked') return { ok: false, code: 'bad-state', reason: `unit is ${u.state}, not blocked` };
+  u.state = 'pending'; u.blockedReason = null;
+  appendEvent(u, { type: 'unblocked', at: now });
+  return { ok: true };
+}
+
+/** Cancel every unit that is not verified or terminally failed (or one named unit). Leases are released; verified receipts and failure records are kept. */
+export function cancelUnits(store, { unitId = null, reason, now }) {
+  const canceled = [];
+  for (const id of Object.keys(store.units).sort()) {
+    if (unitId && id !== unitId) continue;
+    const u = store.units[id];
+    if (u.state === 'verified' || u.state === 'canceled' || u.state === 'failed') continue; // receipts and terminal failures keep their own status
+    u.lease = null; u.state = 'canceled';
+    appendEvent(u, { type: 'canceled', reason: String(reason ?? 'canceled').slice(0, 300), at: now });
+    canceled.push(id);
+  }
+  return { ok: true, canceled };
+}
+
+// ---------------------------------------------------------------- progress
+
+/** Counts by state. `verified` is the only count that is progress. */
+export function progressOf(store) {
+  const by = Object.fromEntries(UNIT_STATES.map((s) => [s, 0]));
+  let staleResults = 0;
+  for (const u of Object.values(store.units)) { by[u.state] += 1; staleResults += u.stale.length; }
+  const total = Object.keys(store.units).length;
+  return { total, ...by, completed: by.verified, remaining: total - by.verified - by.canceled, staleResults, done: total > 0 && by.verified === total };
+}
+
+/** The current scoped results: verified units only, keyed by unit id. Two runs converged exactly when these are equal. */
+export function scopedResults(store) {
+  return Object.fromEntries(Object.values(store.units).filter((u) => u.state === 'verified').sort((a, b) => (a.id < b.id ? -1 : 1)).map((u) => [u.id, u.result.resultDigest]));
+}
+
+/** Repositories whose every unit is verified and current: what `runFleet({ portfolioVerified })` may skip. */
+export function fullyVerifiedRepositories(store) {
+  const by = new Map();
+  for (const u of Object.values(store.units)) by.set(u.repository, (by.get(u.repository) ?? true) && u.state === 'verified');
+  return [...by].filter(([, ok]) => ok).map(([r]) => r).sort();
+}
+
+// ---------------------------------------------------------------- persistence
+
+function sleepSync(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+
+function withLock(file, fn) {
+  const lock = `${file}.lock`;
+  const start = Date.now();
+  for (;;) {
+    try { fs.writeFileSync(lock, String(process.pid), { flag: 'wx' }); break; } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      try { if (Date.now() - fs.statSync(lock).mtimeMs > PORTFOLIO_LIMITS.lockStaleMs) { fs.unlinkSync(lock); continue; } } catch { continue; }
+      if (Date.now() - start > PORTFOLIO_LIMITS.lockWaitMs) throw typedError('LOCK_TIMEOUT', 'could not take the portfolio store lock');
+      sleepSync(5);
+    }
+  }
+  try { return fn(); } finally { try { fs.unlinkSync(lock); } catch { /* already gone */ } }
+}
+
+/** Read and verify a store. Throws `STORE_CORRUPT` rather than returning a guess. */
+export function readStore(file) {
+  let raw;
+  try {
+    const st = fs.lstatSync(file);
+    if (st.isSymbolicLink() || !st.isFile() || st.size > PORTFOLIO_LIMITS.maxStoreBytes) throw typedError('STORE_CORRUPT', 'store is not a regular file within the size limit');
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+  let store;
+  try { store = JSON.parse(raw); } catch { throw typedError('STORE_CORRUPT', 'store is not valid JSON'); }
+  const v = verifyStore(store);
+  if (!v.ok) throw typedError('STORE_CORRUPT', `store failed verification: ${v.errors[0].code} ${v.errors[0].unit ?? ''}`, { errors: v.errors });
+  return store;
+}
+
+function writeStore(file, store) {
+  const text = JSON.stringify(store);
+  if (text.length > PORTFOLIO_LIMITS.maxStoreBytes) throw typedError('STORE_TOO_LARGE', 'store would exceed the size limit');
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(tmp, text, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * Open (or create) the durable store for a plan. An existing store for a DIFFERENT plan is an error: resuming the wrong portfolio would
+ * silently mix two sets of results.
+ */
+export function openStore(file, plan) {
+  return withLock(file, () => {
+    const existing = readStore(file);
+    if (existing) {
+      if (existing.planId !== plan.id) throw typedError('PLAN_MISMATCH', `the store at this path belongs to plan ${existing.planId}, not ${plan.id}`);
+      return existing;
+    }
+    const fresh = newStore(plan);
+    writeStore(file, fresh);
+    return fresh;
+  });
+}
+
+/** Locked read-modify-write. `fn(store)` mutates and returns a value; the store is verified before it is written back. */
+export function mutateStore(file, fn) {
+  return withLock(file, () => {
+    const store = readStore(file);
+    if (!store) throw typedError('NO_STORE', 'no portfolio store at this path');
+    const out = fn(store);
+    const v = verifyStore(store);
+    if (!v.ok) throw typedError('STORE_CORRUPT', `refusing to write a store that fails verification: ${v.errors[0].code}`, { errors: v.errors });
+    writeStore(file, store);
+    return out;
+  });
+}
+
+// ---------------------------------------------------------------- runner
+
+/**
+ * Drive a store to completion with bounded concurrency. Mirrors runFleet's isolation: an executor that throws FAILS its unit (and costs
+ * a retry), it never takes the run down. `executor(unit, ctx)` returns `{ resultDigest, dependencies }`.
+ *
+ * `maxUnits` stops after that many units have been leased, for interruption tests and for time-boxed runs. Returns the progress.
+ */
+export async function runPortfolio({ file, executor, holder = 'worker', clock = () => Date.now(), ttlMs, concurrency = 2, maxUnits = Infinity, skip = () => false }) {
+  let leased = 0;
+  const limit = Math.max(1, Math.min(concurrency, 16));
+  async function worker(n) {
+    for (;;) {
+      if (leased >= maxUnits) return;
+      const lease = mutateStore(file, (s) => leaseUnit(s, { holder: `${holder}-${n}`, now: clock(), ttlMs, skip }));
+      if (!lease) return;
+      leased += 1;
+      mutateStore(file, (s) => startUnit(s, { unitId: lease.unitId, attemptId: lease.attemptId, now: clock() }));
+      const unit = readStore(file).units[lease.unitId];
+      let res = null; let err = null;
+      try { res = await executor(unit, { attemptId: lease.attemptId }); } catch (e) { err = e; }
+      mutateStore(file, (s) => {
+        if (err || !res) failUnit(s, { unitId: lease.unitId, attemptId: lease.attemptId, reason: err ? err.message : 'executor returned nothing', now: clock() });
+        else completeUnit(s, { unitId: lease.unitId, attemptId: lease.attemptId, resultDigest: res.resultDigest, dependencies: res.dependencies, now: clock() });
+      });
+    }
+  }
+  await Promise.all(Array.from({ length: limit }, (_, i) => worker(i)));
+  return progressOf(readStore(file));
+}

package/src/posture/replay/replay.js

@@ -243,6 +243,7 @@ export async function replayManifest(bundle, o = {}) {
   const reproduced = manifest.expected ? run.outcome === manifest.expected.outcome : null;
   return {
     status: 'completed', executed: true, outcome: run.outcome, record: run.record, receipt: run.receipt, reproduced, disclosure: run.disclosure,
+    ...(run.report !== undefined ? { report: run.report } : {}),
     prerequisites: [], errors: [], run: run.run, environment: run.environment,
     attempt: attemptRecord(manifest.id, step.n, step.history, 'completed', { outcome: run.outcome }),
   };

package/src/posture/routing/adapter.js

@@ -0,0 +1,140 @@
+// Provider adapter with auditable telemetry (X-602.AC03).
+//
+// One function turns a task run into an outcome record. It owns NO network client. Every call goes through guardedModelCall
+// (assurance/bounded-io.js), which gates on the `model-routing` feature, evaluates the egress policy BEFORE the prompt exists, redacts
+// the payload, enforces the request-size limit, runs the injected transport under a deadline with bounded retries, and appends each
+// decision to the egress audit chain. The transport is the caller's: a test passes a fake, production passes whatever the operator
+// configured. There is no default transport and no cloud fallback.
+//
+// The telemetry this module emits is built from an ALLOWLIST. It carries the provider id, model, endpoint HOST (no userinfo, path or
+// query), status, a fixed failure code, token counts, cache state, latency and byte counts. It never carries the prompt, the response
+// text, a transport error message (which can echo a request) or any credential, and nothing is added to it by spreading an object.
+// The prompt/response stay with the caller; telemetry is what is safe to log, hash and calibrate on.
+//
+// Outcomes: provider failures, partial responses, cancellation, timeouts and cache hits are all kept as outcome records. A failed call
+// yields a record with unknown (null) usage, never zero tokens and never a dropped row.
+
+import { guardedModelCall } from '../assurance/bounded-io.js';
+import { envPresent } from '../assurance/config.js';
+import { payloadMetrics } from '../../egress/audit.js';
+import { buildRoutingOutcome } from './outcomes.js';
+import { costOf } from './economics.js';
+
+/** Failure codes a provider error may carry into telemetry. Anything else becomes `unknown-failure`; the message is never kept. */
+export const PROVIDER_FAILURE_CODES = Object.freeze(['rate-limit', 'server-error', 'overloaded', 'auth', 'bad-request', 'network', 'unknown-failure']);
+const FINISH_REASONS = Object.freeze(['stop', 'length', 'content-filter', 'tool-use', 'error']);
+
+const nonNegInt = (v) => (Number.isInteger(v) && v >= 0 ? v : null);
+
+/** The endpoint reduced to scheme and host. A URL with userinfo or a query string (a common place for a key) loses both. */
+export function endpointHost(endpoint) {
+  try { const u = new URL(String(endpoint)); return `${u.protocol}//${u.host}`; } catch { return null; }
+}
+
+function usageOf(raw) {
+  if (!raw || typeof raw !== 'object') return { inputTokens: null, outputTokens: null, cachedInputTokens: null, source: 'unknown' };
+  const inputTokens = nonNegInt(raw.inputTokens);
+  const outputTokens = nonNegInt(raw.outputTokens);
+  let cachedInputTokens = nonNegInt(raw.cachedInputTokens);
+  if (cachedInputTokens !== null && inputTokens !== null && cachedInputTokens > inputTokens) cachedInputTokens = null; // inconsistent: unknown, not clamped
+  const reported = inputTokens !== null || outputTokens !== null;
+  return { inputTokens, outputTokens, cachedInputTokens, source: reported ? 'measured' : 'unknown' };
+}
+
+function cacheStateOf(usage, hint) {
+  if (usage.cachedInputTokens !== null && usage.inputTokens !== null) {
+    if (usage.cachedInputTokens === 0) return 'miss';
+    return usage.cachedInputTokens >= usage.inputTokens ? 'hit' : 'partial';
+  }
+  return ['hit', 'partial', 'miss', 'ineligible'].includes(hint) ? hint : 'unknown';
+}
+
+/**
+ * Create an adapter for one provider model.
+ *
+ * @param {object} o
+ * @param {object} o.config        resolveAssuranceConfig() result (the `model-routing` feature must be enabled)
+ * @param {string} o.scanRoot
+ * @param {string} o.provider      provider slot id (for example 'provider-a'), recorded in telemetry
+ * @param {string} o.model
+ * @param {string|null} [o.modelVersion]
+ * @param {string|null} o.endpoint operator-configured; null yields a typed `missing-provider` outcome, never a default
+ * @param {(req)=>Promise<{text:string, finishReason?:string, usage?:object, cacheState?:string}>} o.transport  injected; receives redacted text only
+ * @param {object} [o.priceBook]
+ * @param {{name:string, env?:object}|null} [o.credential]  names the environment variable the transport needs; only presence is checked
+ * @param {()=>number} [o.clock]   monotonic milliseconds, injectable for tests
+ */
+export function createProviderAdapter({ config, scanRoot, provider, model, modelVersion = null, endpoint, transport, priceBook = null, credential = null, clock = () => Number(process.hrtime.bigint() / 1_000_000n) }) {
+  return {
+    provider, model, modelVersion,
+    /**
+     * Run one task. Always resolves to `{ outcome, telemetry, text }`: `outcome` is a validated routing-outcome record (or null if the
+     * task itself was malformed), `telemetry` the allowlisted record, `text` the redacted-side response for the caller only.
+     * `signal` lets the caller cancel; a cancelled run is recorded as `cancelled`, not dropped.
+     */
+    async invoke({ task, runId, prompt, filePath = null, signal = null, group = null, observedAt = null, purpose = 'routing-task' }) {
+      const requirements = credential ? [{ kind: 'credential', name: credential.name, present: envPresent(credential.name, credential.env || process.env) }] : [];
+      let captured = null; let failure = null; let cancelled = false; let calls = 0;
+      const t0 = clock();
+      const res = await guardedModelCall({
+        config, featureId: 'model-routing', scanRoot, endpoint, purpose, text: prompt, filePath, model, requirements,
+        call: async (req) => {
+          calls += 1;
+          if (signal?.aborted) { cancelled = true; const e = new Error('cancelled'); e.retryable = false; throw e; }
+          const inner = signal ? AbortSignal.any([signal, req.signal]) : req.signal;
+          let out;
+          try {
+            out = await Promise.race([
+              transport({ endpoint: req.endpoint, text: req.text, signal: inner, timeoutMs: req.timeoutMs }),
+              new Promise((_, rej) => { if (signal) signal.addEventListener('abort', () => { cancelled = true; const e = new Error('cancelled'); e.retryable = false; rej(e); }, { once: true }); }),
+            ]);
+          } catch (e) {
+            if (!cancelled) failure = { code: PROVIDER_FAILURE_CODES.includes(e?.code) ? e.code : 'unknown-failure', retryable: !!e?.retryable };
+            throw Object.assign(new Error(cancelled ? 'cancelled' : 'provider failure'), { retryable: !cancelled && !!e?.retryable });
+          }
+          captured = out && typeof out === 'object' ? out : { text: String(out ?? '') };
+          return typeof captured.text === 'string' ? captured.text : '';
+        },
+      });
+      const latencyMs = Math.max(0, clock() - t0);
+      const promptMetrics = payloadMetrics(String(prompt ?? ''));
+
+      let status; let code = res.code ?? null; let usage = usageOf(null); let finish = null; let hint = 'unknown';
+      if (cancelled) { status = 'cancelled'; code = 'cancelled'; }
+      else if (res.status === 'ok' || res.status === 'degraded') {
+        usage = usageOf(captured?.usage);
+        finish = FINISH_REASONS.includes(captured?.finishReason) ? captured.finishReason : null;
+        hint = captured?.cacheState;
+        status = res.truncated || finish === 'length' || finish === 'content-filter' ? 'partial' : 'completed';
+      } else if (res.code === 'timeout') status = 'timeout';
+      else if (failure) { status = 'provider-error'; code = failure.code; }
+      else if (['egress-denied', 'missing-provider', 'missing-credential', 'limit-exceeded', 'disabled', 'kill-switch', 'platform-unsupported', 'invalid-config'].includes(res.code) || res.status === 'disabled') status = 'blocked';
+      else status = 'failed';
+
+      const attempts = Number.isInteger(res.attempts) ? res.attempts : calls;
+      const retries = Math.max(0, attempts - 1);
+      usage = { ...usage, retries };
+      const cacheState = cacheStateOf(usage, hint);
+
+      // Retries that reported no usage are bounded by the request size, never priced at zero.
+      const cost = priceBook ? costOf({
+        usage, model, priceBook, retries: Array.from({ length: retries }, () => ({})), estimatedRequestTokens: promptMetrics.tokenCount || null,
+        toolExecutionUsd: 0, // this adapter runs no tools: a known zero, not an unmeasured one
+      }) : null;
+      const costUsd = cost && cost.totalStatus === 'measured' ? cost.totalUsd : null;
+      const costStatus = cost ? cost.totalStatus : 'unknown';
+
+      const built = buildRoutingOutcome({
+        runId, task, model, modelVersion, status, outcome: status === 'completed' || status === 'partial' ? 'delayed' : 'unknown',
+        group, usage, costUsd, costStatus, latencyMs, cacheState, observedAt, synthetic: !!task?.synthetic,
+      });
+      const telemetry = Object.freeze({
+        provider, model, modelVersion, endpoint: endpointHost(endpoint), status, code, finishReason: finish, attempts, cacheState,
+        usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens, cachedInputTokens: usage.cachedInputTokens, retries, source: usage.source },
+        latencyMs, requestBytes: promptMetrics.byteCount, requestTokensEstimated: promptMetrics.tokenCount, redactions: res.redactions ?? 0,
+        cost: cost ? { priceVersion: cost.priceVersion, currency: cost.currency, billingBasis: cost.billingBasis, status: cost.totalStatus, lowerUsd: cost.totalLowerUsd, upperUsd: cost.totalUpperUsd } : null,
+      });
+      return { outcome: built.ok ? built.outcome : null, outcomeErrors: built.errors, telemetry, text: status === 'completed' || status === 'partial' ? (res.text ?? '') : '' };
+    },
+  };
+}