@clear-capabilities/agentic-security-scanner 0.161.0 → 0.163.0

package/src/posture/replay/replay.js

@@ -0,0 +1,250 @@
+// Replay manifests and environment identity (X-203).
+//
+// Extends the existing proof-of-concept sandbox path (a payload run under the
+// confinement backend, judged by an observed effect) with an identity for the run
+// and a way to repeat it. It is NOT a second sandbox or a second runner: a replay
+// is an oracle run (`oracles/oracle.js`), which goes through `runInBoundary` and
+// therefore through the supervised process tree, output cap and cleanup of
+// CORE-003. What this module adds is the pinned, validated description of the run.
+//
+// A manifest pins: the repository commit, the patch hash, the fixture hash, the
+// toolchain (and container digest when there is one), the oracle id, version and
+// logic digest, the inputs and the budgets. Replaying it on the same supported
+// environment reproduces the verdict, and the identical verification record id.
+//
+// Honesty rules, each with a test:
+//   - A manifest is REJECTED, and nothing executes, when a content hash does not
+//     match the content, when the oracle changed since the manifest was made, when
+//     its scope asks for more than the oracle's declared scope (network, another
+//     oracle, a write outside the workspace) or when a budget exceeds the oracle's
+//     ceiling. The manifest is closed-world, so a field such as a model verdict
+//     cannot ride along.
+//   - A missing toolchain, container image or container runtime, or a disabled
+//     feature, is a typed PREREQUISITE and the attempt is resumable. Nothing is
+//     substituted for the execution that did not happen: the outcome is `not-run`
+//     (or `unsupported` when this build can never meet it), with no evidence.
+//   - This build never fetches anything. A prerequisite whose acquisition would
+//     need the network is reported as such, with the network denied.
+//   - Container execution is not implemented. A manifest pinning a container
+//     digest is therefore `unsupported` here, never run outside the container it
+//     names.
+//   - Toolchain identity is exact (runtime version, platform, architecture). A
+//     different patch release is a different environment, reported as an unmet
+//     prerequisite rather than silently tolerated.
+import { digestOf, semanticId } from '../assurance/identity.js';
+import { SCHEMA_VERSION, isCommit, isDigest, isPlainObject } from '../assurance/schema-kit.js';
+import { detectBackend } from '../../sandbox/capabilities.js';
+import { runOracle, recordWithoutExecution, isSafeRelativePath, FEATURE_ID } from '../oracles/oracle.js';
+import * as registry from '../oracles/registry.js';
+
+export const REPLAY_SCHEMA = 'agentic-security/replay-manifest';
+export const ATTEMPT_SCHEMA = 'agentic-security/replay-attempt';
+export const MAX_ATTEMPTS = 10;
+
+const ALLOWED = ['schema', 'schemaVersion', 'id', 'hypothesisId', 'repository', 'patch', 'fixture', 'toolchain', 'oracle', 'entry', 'inputs', 'inputsDigest', 'budgets', 'scope', 'expected'];
+const REQUIRED = ['schema', 'schemaVersion', 'id', 'hypothesisId', 'repository', 'patch', 'fixture', 'toolchain', 'oracle', 'entry', 'inputs', 'inputsDigest', 'budgets', 'scope'];
+const ID_FIELDS = ALLOWED.filter((k) => k !== 'id');
+const REPLAY_BUDGET_KEYS = ['timeoutMs', 'graceMs', 'maxOutputBytes'];
+const EXPECTED_OUTCOMES = ['confirmed', 'refuted', 'inconclusive'];
+
+/** The pinned scope a replay may have: exactly the oracle it names, no network, workspace-only writes. */
+export function allowedScope(oracleId) {
+  return { executes: [oracleId], network: false, writes: 'workspace-only' };
+}
+
+/** Sanitized identity of the execution environment: facts about the toolchain, nothing about the host. */
+export function environmentIdentity(overrides = {}) {
+  const base = {
+    runtime: 'node', version: process.versions.node, platform: process.platform, arch: process.arch,
+    containerDigest: null, backend: detectBackend(),
+  };
+  const env = { ...base, ...overrides };
+  return { ...env, toolchainDigest: digestOf({ runtime: env.runtime, version: env.version, platform: env.platform, arch: env.arch, containerDigest: env.containerDigest }) };
+}
+
+/**
+ * Build a manifest from the pieces of a verification. The oracle identity and the
+ * environment come from this build, not from the caller.
+ */
+export function createReplayManifest({ hypothesisId, commit, fixtureFiles, patchFiles = null, oracleId, entry, inputs, budgets = {}, expected, environment }) {
+  const oracle = registry.getOracle(oracleId);
+  if (!oracle) throw new Error(`unknown oracle '${oracleId}'`);
+  const env = environment || environmentIdentity();
+  const m = {
+    schema: REPLAY_SCHEMA, schemaVersion: SCHEMA_VERSION, hypothesisId,
+    repository: { commit },
+    patch: patchFiles && Object.keys(patchFiles).length ? { digest: digestOf(patchFiles) } : null,
+    fixture: { digest: digestOf(fixtureFiles) },
+    toolchain: { runtime: env.runtime, version: env.version, platform: env.platform, arch: env.arch, containerDigest: env.containerDigest ?? null },
+    oracle: { id: oracle.id, version: oracle.version, logicDigest: oracle.logicDigest },
+    entry, inputs, inputsDigest: digestOf(inputs),
+    budgets: { timeoutMs: oracle.budgets.timeoutMs, graceMs: oracle.budgets.graceMs, maxOutputBytes: oracle.budgets.maxOutputBytes, ...budgets },
+    scope: allowedScope(oracle.id),
+  };
+  if (expected) m.expected = expected;
+  m.id = manifestId(m);
+  return m;
+}
+
+export function manifestId(m) { return semanticId('rpl', m, ID_FIELDS); }
+
+function err(errors, code, path, message) { errors.push({ code, path, message }); }
+
+/**
+ * Validate a manifest against the content it describes. Rejects, and the caller
+ * must not execute, on any error. Pure: reads no file and runs nothing.
+ */
+export function validateReplayManifest(m, { fixtureFiles, patchFiles = null } = {}) {
+  const errors = [];
+  if (!isPlainObject(m)) { err(errors, 'NOT_AN_OBJECT', '', 'manifest must be an object'); return { ok: false, errors }; }
+  if (m.schema !== REPLAY_SCHEMA) { err(errors, 'SCHEMA_MISMATCH', 'schema', `expected '${REPLAY_SCHEMA}'`); return { ok: false, errors }; }
+  if (typeof m.schemaVersion !== 'string' || m.schemaVersion.split('.')[0] !== '1') { err(errors, 'UNSUPPORTED_MAJOR', 'schemaVersion', 'only major version 1 is supported'); return { ok: false, errors }; }
+  for (const k of Object.keys(m)) if (!ALLOWED.includes(k)) err(errors, 'UNKNOWN_FIELD', k, `field '${k}' is not part of a replay manifest`);
+  for (const k of REQUIRED) if (m[k] === undefined) err(errors, 'MISSING_FIELD', k, `required field '${k}' is missing`);
+  if (errors.length) return { ok: false, errors };
+
+  if (typeof m.hypothesisId !== 'string' || !m.hypothesisId) err(errors, 'BAD_TYPE', 'hypothesisId', 'must be a non-empty string');
+  if (!isPlainObject(m.repository) || !isCommit(m.repository.commit)) err(errors, 'BAD_COMMIT', 'repository.commit', 'a replay pins an exact 40 or 64 character commit');
+  if (!isPlainObject(m.fixture) || !isDigest(m.fixture.digest)) err(errors, 'BAD_DIGEST', 'fixture.digest', 'must be sha256:<64 hex>');
+  else if (!isPlainObject(fixtureFiles) || digestOf(fixtureFiles) !== m.fixture.digest) err(errors, 'HASH_MISMATCH', 'fixture.digest', 'the fixture content does not match its pinned hash');
+  const havePatch = isPlainObject(patchFiles) && Object.keys(patchFiles).length > 0;
+  if (m.patch === null) {
+    if (havePatch) err(errors, 'HASH_MISMATCH', 'patch', 'patch content was supplied but the manifest pins no patch');
+  } else if (!isPlainObject(m.patch) || !isDigest(m.patch.digest)) err(errors, 'BAD_DIGEST', 'patch.digest', 'must be null or { digest: sha256:<64 hex> }');
+  else if (!havePatch || digestOf(patchFiles) !== m.patch.digest) err(errors, 'HASH_MISMATCH', 'patch.digest', 'the patch content does not match its pinned hash');
+  if (!isDigest(m.inputsDigest) || !isPlainObject(m.inputs) || digestOf(m.inputs) !== m.inputsDigest) err(errors, 'HASH_MISMATCH', 'inputsDigest', 'the inputs do not match their pinned hash');
+
+  // Paths are part of the allowed execution scope: a fixture or patch that names a file outside the workspace is refused here,
+  // before anything can run, even when its hash matches.
+  for (const [label, files] of [['fixture', fixtureFiles], ['patch', patchFiles]]) {
+    for (const rel of Object.keys(isPlainObject(files) ? files : {})) {
+      if (!isSafeRelativePath(rel)) err(errors, 'SCOPE_VIOLATION', `${label}.files`, `path ${JSON.stringify(String(rel).slice(0, 60))} is not a safe relative path inside the workspace`);
+    }
+  }
+  if (typeof m.entry === 'string' && isPlainObject(fixtureFiles) && !(m.entry in { ...fixtureFiles, ...(isPlainObject(patchFiles) ? patchFiles : {}) })) err(errors, 'SCOPE_VIOLATION', 'entry', 'the entry must be one of the pinned files');
+
+  const tc = m.toolchain;
+  if (!isPlainObject(tc) || tc.runtime !== 'node' || typeof tc.version !== 'string' || typeof tc.platform !== 'string' || typeof tc.arch !== 'string') err(errors, 'BAD_TYPE', 'toolchain', 'needs runtime node, version, platform and arch');
+  else if (tc.containerDigest !== null && !isDigest(tc.containerDigest)) err(errors, 'BAD_DIGEST', 'toolchain.containerDigest', 'must be null or sha256:<64 hex>');
+
+  const oracle = isPlainObject(m.oracle) ? registry.getOracle(m.oracle.id) : null;
+  if (!oracle) err(errors, 'UNKNOWN_ORACLE', 'oracle.id', 'the manifest names an oracle this build does not have');
+  else {
+    if (m.oracle.version !== oracle.version || m.oracle.logicDigest !== oracle.logicDigest) err(errors, 'ORACLE_MISMATCH', 'oracle', 'the oracle version or logic digest differs from the pinned one: this is not the oracle the manifest was made with');
+    const sc = m.scope;
+    const want = allowedScope(oracle.id);
+    if (!isPlainObject(sc) || Object.keys(sc).some((k) => !(k in want))) err(errors, 'SCOPE_VIOLATION', 'scope', 'unknown scope keys');
+    else {
+      if (JSON.stringify(sc.executes) !== JSON.stringify(want.executes)) err(errors, 'SCOPE_VIOLATION', 'scope.executes', 'a replay may execute only the oracle it names');
+      if (sc.network !== false) err(errors, 'SCOPE_VIOLATION', 'scope.network', 'replay grants no network access');
+      if (sc.writes !== 'workspace-only') err(errors, 'SCOPE_VIOLATION', 'scope.writes', 'replay writes only inside its workspace');
+    }
+    const b = m.budgets;
+    if (!isPlainObject(b)) err(errors, 'BAD_TYPE', 'budgets', 'must be an object');
+    else {
+      for (const k of Object.keys(b)) if (!REPLAY_BUDGET_KEYS.includes(k)) err(errors, 'UNKNOWN_FIELD', `budgets.${k}`, 'not a replay budget');
+      for (const k of REPLAY_BUDGET_KEYS) {
+        if (!Number.isInteger(b[k]) || b[k] < 1) err(errors, 'BAD_TYPE', `budgets.${k}`, 'must be a positive integer');
+        else if (b[k] > oracle.budgets[k]) err(errors, 'BUDGET_EXCEEDED', `budgets.${k}`, `exceeds the oracle ceiling of ${oracle.budgets[k]}`);
+      }
+    }
+  }
+  if (typeof m.entry !== 'string' || !m.entry) err(errors, 'BAD_TYPE', 'entry', 'must be a non-empty string');
+  if (m.expected !== undefined && (!isPlainObject(m.expected) || Object.keys(m.expected).some((k) => k !== 'outcome') || !EXPECTED_OUTCOMES.includes(m.expected.outcome))) err(errors, 'BAD_TYPE', 'expected', `must be { outcome: one of ${EXPECTED_OUTCOMES.join(', ')} }`);
+  if (m.id !== manifestId(m)) err(errors, 'ID_MISMATCH', 'id', 'the manifest id does not match its content');
+  return { ok: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------- prerequisites
+
+/**
+ * Typed prerequisites that are not met on this host. `resumable` is true when
+ * meeting it is something an operator can do (install a toolchain, enable the
+ * feature) and false when this build cannot meet it at all.
+ */
+export function unmetPrerequisites(m, host = environmentIdentity()) {
+  const out = [];
+  const tc = m.toolchain;
+  if (tc.containerDigest !== null) {
+    out.push({ kind: 'container-runtime', id: tc.containerDigest, state: 'unsupported', resumable: false, reason: 'container execution is not implemented in this build; the run is never executed outside the container the manifest names' });
+    out.push({ kind: 'container-image', id: tc.containerDigest, state: 'missing', resumable: false, reason: 'this build neither holds nor pulls container images' });
+    out.push({ kind: 'network', id: 'image-acquisition', state: 'denied', resumable: false, reason: 'acquiring a container image needs network access, which replay does not grant' });
+  }
+  if (tc.version !== host.version || tc.platform !== host.platform || tc.arch !== host.arch) {
+    out.push({
+      kind: 'toolchain', id: `${tc.runtime}@${tc.version} ${tc.platform}/${tc.arch}`, state: 'missing', resumable: true,
+      reason: `this host runs ${host.runtime}@${host.version} ${host.platform}/${host.arch}; the manifest pins an exact toolchain`,
+    });
+    out.push({ kind: 'network', id: 'toolchain-acquisition', state: 'denied', resumable: true, reason: 'installing the pinned toolchain needs network access, which replay does not grant; install it out of band and resume' });
+  }
+  return out;
+}
+
+function nextAttempt(resume, manifestId_) {
+  if (resume === undefined || resume === null) return { n: 1, history: [] };
+  if (!isPlainObject(resume) || resume.schema !== ATTEMPT_SCHEMA || resume.manifestId !== manifestId_) return { error: 'the attempt does not belong to this manifest' };
+  if (resume.status !== 'awaiting-prerequisites') return { error: `an attempt in status '${resume.status}' is not resumable` };
+  if (!Number.isInteger(resume.attempt) || resume.attempt < 1 || !Array.isArray(resume.history)) return { error: 'the attempt record is malformed' };
+  if (resume.attempt >= MAX_ATTEMPTS) return { error: `the attempt limit of ${MAX_ATTEMPTS} was reached` };
+  return { n: resume.attempt + 1, history: resume.history.slice(-MAX_ATTEMPTS) };
+}
+
+function attemptRecord(manifestId_, n, history, status, entry) {
+  return { schema: ATTEMPT_SCHEMA, manifestId: manifestId_, attempt: n, status, history: [...history, { attempt: n, ...entry }] };
+}
+
+/**
+ * Replay a manifest. Never throws.
+ *
+ * @param {object} bundle { manifest, fixtureFiles, patchFiles? }
+ * @param {object} [o]
+ * @param {object} [o.resume]  an attempt returned earlier with status 'awaiting-prerequisites'
+ * @param {object} [o.hostEnvironment] environment identity override (test seam)
+ * @param {object} [o.config]  assurance config (the verification-oracles feature is off by default)
+ * @param {object} [o.runOptions] passed to runOracle (test seams: deps, probeEnv, signal)
+ * @returns {Promise<object>} { status: 'completed'|'awaiting-prerequisites'|'rejected', executed, outcome, record, receipt, reproduced, prerequisites, attempt, errors }
+ */
+export async function replayManifest(bundle, o = {}) {
+  const { manifest, fixtureFiles, patchFiles = null } = bundle || {};
+  const valid = validateReplayManifest(manifest, { fixtureFiles, patchFiles });
+  if (!valid.ok) return { status: 'rejected', executed: false, outcome: null, record: null, receipt: null, reproduced: null, prerequisites: [], attempt: null, errors: valid.errors };
+
+  const step = nextAttempt(o.resume, manifest.id);
+  if (step.error) return { status: 'rejected', executed: false, outcome: null, record: null, receipt: null, reproduced: null, prerequisites: [], attempt: null, errors: [{ code: 'ATTEMPT_REJECTED', path: 'resume', message: step.error }] };
+
+  const request = {
+    oracleId: manifest.oracle.id, hypothesisId: manifest.hypothesisId, commit: manifest.repository.commit,
+    files: { ...fixtureFiles, ...(patchFiles || {}) }, entry: manifest.entry, inputs: manifest.inputs, attempt: step.n,
+    budgets: manifest.budgets,
+  };
+  const waiting = (prerequisites, outcome, reason) => {
+    const record = recordWithoutExecution(manifest.oracle.id, request, outcome, reason, registry);
+    return {
+      status: 'awaiting-prerequisites', executed: false, outcome, record, receipt: null, reproduced: null, prerequisites, errors: [],
+      attempt: attemptRecord(manifest.id, step.n, step.history, 'awaiting-prerequisites', { outcome, prerequisites: prerequisites.map((p) => `${p.kind}:${p.state}`) }),
+    };
+  };
+
+  const unmet = unmetPrerequisites(manifest, o.hostEnvironment || environmentIdentity());
+  if (unmet.length) {
+    const never = unmet.some((p) => !p.resumable);
+    return waiting(unmet, never ? 'unsupported' : 'not-run', `replay prerequisite(s) not met: ${unmet.map((p) => `${p.kind} ${p.id} (${p.state})`).join('; ')}; nothing was executed`);
+  }
+
+  const run = await runOracle(request, { config: o.config, ...(o.runOptions || {}) });
+  if (run.status === 'rejected') return { status: 'rejected', executed: false, outcome: null, record: null, receipt: null, reproduced: null, prerequisites: [], attempt: null, errors: (run.errors || []).map((m) => ({ code: 'REQUEST_REJECTED', path: '', message: m })) };
+  if (!run.executed) {
+    const feature = run.status === 'disabled';
+    const prereq = feature
+      ? [{ kind: 'feature', id: FEATURE_ID, state: 'disabled', resumable: true, reason: run.reason }]
+      : (run.prerequisites || [{ id: 'trust-boundary', reason: run.reason }]).map((p) => ({ kind: p.id === 'trust-boundary' ? 'trust-boundary' : 'oracle-prerequisite', id: p.id, state: 'unmet', resumable: false, reason: p.reason }));
+    return waiting(prereq, run.outcome === 'unsupported' ? 'unsupported' : 'not-run', run.reason);
+  }
+  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 ?? '') : '' };
+    },
+  };
+}