@ikon85/agent-workflow-kit 0.44.1 → 0.45.0

package/src/lib/routingAccessGraph.mjs

@@ -1,4 +1,23 @@
-export const ACCESS_GRAPH_VERSION = 1;
+/**
+ * The Access graph — the user-local map of native and cross-provider paths by
+ * which an agent surface can reach a model runtime, together with dated
+ * capability attestations.
+ *
+ * A path identifies a model-AND-effort pair, so only an exact pair match
+ * resolves and availability is attested per pair rather than per model.
+ * Detection is never authorization: a freshly built path is `unknown`, and only
+ * a user-authorized capability probe promotes it to `available` or writes a
+ * dated `unavailable` attestation. `unknown` is not a deadlock — a supervised
+ * run may take the `verification-required` route to produce the proof, while an
+ * AFK dispatch stays blocked until that proof exists.
+ *
+ * Only a deterministic unsupported or authorization failure may mutate
+ * availability. A timeout, rate limit, malformed response or transient provider
+ * failure leaves the path `unknown`, so one bad minute cannot poison the graph.
+ */
+import { createHash } from 'node:crypto';
+
+export const ACCESS_GRAPH_VERSION = 2;
 
 export const ROUTE_AVAILABILITY = Object.freeze([
   'available',
@@ -13,17 +32,24 @@ export const ENFORCEMENT_METHODS = Object.freeze([
   'none',
 ]);
 
+/** What one pair may do next, once the graph has been consulted. */
+export const ACCESS_ROUTE_STATES = Object.freeze([
+  'ready',
+  'verification-required',
+  'blocked',
+]);
+
 const PATH_FIELDS = new Set([
-  'id',
-  'surfaceId',
-  'providerId',
-  'modelId',
-  'transportId',
-  'availability',
-  'enforcement',
-  'capabilityEvidence',
+  'id', 'surfaceId', 'providerId', 'modelId', 'effort', 'transportId',
+  'availability', 'enforcement', 'capabilityEvidence', 'attestation',
 ]);
 
+const ATTESTATION_FIELDS = new Set([
+  'result', 'failureKind', 'probeId', 'authorizationId', 'observedAt', 'expiresAt',
+]);
+
+const CAPABILITY_IDENTITY = ['surfaceId', 'providerId', 'modelId', 'transportId'];
+
 function object(value, field) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new TypeError(`${field} must be an object`);
@@ -49,6 +75,22 @@ function timestamp(value, field) {
   return value;
 }
 
+function dated(input, field) {
+  const observedAt = timestamp(input.observedAt, `${field}.observedAt`);
+  const expiresAt = timestamp(input.expiresAt, `${field}.expiresAt`);
+  if (Date.parse(expiresAt) <= Date.parse(observedAt)) {
+    throw new TypeError(`${field}.expiresAt must follow observedAt`);
+  }
+  return { observedAt, expiresAt };
+}
+
+function closedFields(value, allowed, message) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new TypeError(`${message}: ${key}`);
+  }
+  return value;
+}
+
 function deepFreeze(value) {
   if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
   Object.freeze(value);
@@ -56,35 +98,83 @@ function deepFreeze(value) {
   return value;
 }
 
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort()
+      .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+/** The pair identity of a path: surface, provider, model, effort, transport. */
+export function accessPairKey(path) {
+  return JSON.stringify([
+    path.surfaceId, path.providerId, path.modelId, path.effort ?? null, path.transportId,
+  ]);
+}
+
+/** Content-derived revision: an unchanged graph keeps its revision. */
+export function deriveAccessGraphRevision(paths) {
+  return `sha256-${createHash('sha256').update(canonical(paths)).digest('base64url')}`;
+}
+
+function validateAttestation(input, field, availability) {
+  const attestation = `${field}.attestation`;
+  if (input == null) {
+    if (availability !== 'unknown') {
+      throw new TypeError(`${field}.availability requires a dated attestation`);
+    }
+    return null;
+  }
+  if (availability === 'unknown') {
+    throw new TypeError(`${field}: unknown availability must carry no attestation`);
+  }
+  object(input, attestation);
+  closedFields(input, ATTESTATION_FIELDS, 'unknown access attestation field');
+  const result = oneOf(input.result, ['available', 'unavailable'], `${attestation}.result`);
+  if (result !== availability) {
+    throw new TypeError(`${attestation} result must match the recorded availability`);
+  }
+  const failureKind = input.failureKind == null
+    ? null
+    : string(input.failureKind, `${attestation}.failureKind`);
+  if ((result === 'unavailable') !== (failureKind !== null)) {
+    throw new TypeError(`${attestation}.failureKind belongs to an unavailable attestation only`);
+  }
+  return {
+    result,
+    failureKind,
+    probeId: string(input.probeId, `${attestation}.probeId`),
+    authorizationId: string(input.authorizationId, `${attestation}.authorizationId`),
+    ...dated(input, attestation),
+  };
+}
+
 function validatePath(path, index) {
   const field = `paths[${index}]`;
   object(path, field);
-  for (const key of Object.keys(path)) {
-    if (!PATH_FIELDS.has(key)) throw new TypeError(`unknown access path field: ${key}`);
-  }
+  closedFields(path, PATH_FIELDS, 'unknown access path field');
   const enforcement = object(path.enforcement, `${field}.enforcement`);
   const evidence = object(path.capabilityEvidence, `${field}.capabilityEvidence`);
-  const observedAt = timestamp(evidence.observedAt, `${field}.capabilityEvidence.observedAt`);
-  const expiresAt = timestamp(evidence.expiresAt, `${field}.capabilityEvidence.expiresAt`);
-  if (Date.parse(expiresAt) <= Date.parse(observedAt)) {
-    throw new TypeError(`${field}.capabilityEvidence.expiresAt must follow observedAt`);
-  }
+  const availability = oneOf(path.availability, ROUTE_AVAILABILITY, `${field}.availability`);
   return {
     id: string(path.id, `${field}.id`),
     surfaceId: string(path.surfaceId, `${field}.surfaceId`),
     providerId: string(path.providerId, `${field}.providerId`),
     modelId: string(path.modelId, `${field}.modelId`),
+    effort: path.effort === null ? null : string(path.effort, `${field}.effort`),
     transportId: string(path.transportId, `${field}.transportId`),
-    availability: oneOf(path.availability, ROUTE_AVAILABILITY, `${field}.availability`),
+    availability,
     enforcement: {
       model: oneOf(enforcement.model, ENFORCEMENT_METHODS, `${field}.enforcement.model`),
       effort: oneOf(enforcement.effort, ENFORCEMENT_METHODS, `${field}.enforcement.effort`),
     },
     capabilityEvidence: {
       revision: string(evidence.revision, `${field}.capabilityEvidence.revision`),
-      observedAt,
-      expiresAt,
+      ...dated(evidence, `${field}.capabilityEvidence`),
     },
+    attestation: validateAttestation(path.attestation, field, availability),
   };
 }
 
@@ -97,9 +187,164 @@ export function validateAccessGraph(input) {
   if (!Array.isArray(input.paths)) throw new TypeError('access graph paths must be an array');
   const paths = input.paths.map(validatePath);
   const ids = new Set();
+  const pairs = new Set();
   for (const path of paths) {
     if (ids.has(path.id)) throw new TypeError(`duplicate access path: ${path.id}`);
     ids.add(path.id);
+    const pair = accessPairKey(path);
+    if (pairs.has(pair)) {
+      throw new TypeError(`duplicate access pair: ${path.modelId}+${path.effort ?? 'none'}`);
+    }
+    pairs.add(pair);
   }
   return deepFreeze({ schemaVersion: ACCESS_GRAPH_VERSION, revision, paths });
 }
+
+/** Validate a path list and stamp it with its content-derived revision. */
+export function sealAccessGraph(paths) {
+  const validated = validateAccessGraph({
+    schemaVersion: ACCESS_GRAPH_VERSION,
+    revision: 'derived',
+    paths,
+  });
+  return validateAccessGraph({
+    ...validated,
+    revision: deriveAccessGraphRevision(validated.paths),
+  });
+}
+
+/** Exact pair match. A requested effort the path never attested never matches. */
+export function accessPathMatchesPair(path, pair) {
+  if (!path || !pair) return false;
+  if (path.providerId !== pair.providerId || path.modelId !== pair.modelId) return false;
+  if ((path.effort ?? null) !== (pair.effort ?? null)) return false;
+  if (pair.surfaceId !== undefined && path.surfaceId !== pair.surfaceId) return false;
+  if (pair.transportId !== undefined && path.transportId !== pair.transportId) return false;
+  return true;
+}
+
+export function selectAccessPaths(graph, pair) {
+  return validateAccessGraph(graph).paths.filter((path) => accessPathMatchesPair(path, pair));
+}
+
+/**
+ * The executable state of one pair: attested access is `ready`, untested access
+ * is `verification-required` for a supervised run and blocked for an AFK one.
+ */
+export function resolveAccessRoute(graph, pair, { afk = false } = {}) {
+  const matches = selectAccessPaths(graph, pair);
+  const label = `${pair?.providerId}:${pair?.modelId}:${pair?.effort ?? 'none'}`;
+  if (matches.length === 0) {
+    return Object.freeze({ state: 'blocked', path: null, reason: `pair-not-attested:${label}` });
+  }
+  const available = matches.find((path) => path.availability === 'available');
+  if (available) {
+    return Object.freeze({ state: 'ready', path: available, reason: `access-attested:${available.id}` });
+  }
+  const untested = matches.find((path) => path.availability === 'unknown');
+  if (untested) {
+    return Object.freeze(afk
+      ? { state: 'blocked', path: untested, reason: `afk-requires-attested-access:${untested.id}` }
+      : { state: 'verification-required', path: untested, reason: `access-unknown:${untested.id}` });
+  }
+  return Object.freeze({
+    state: 'blocked',
+    path: matches[0],
+    reason: `route-unavailable:${matches[0].id}`,
+  });
+}
+
+/**
+ * Assemble surface-adapter attestations into a graph. A path whose capability
+ * the surface could not attest never becomes dispatchable, a pair outside the
+ * model's effort domain is refused, and a previously recorded availability is
+ * carried forward so a rebuild never silently rewrites authorization.
+ */
+export function buildAccessGraph({ attestations, previous = null, effortDomains = null } = {}) {
+  if (!Array.isArray(attestations)) {
+    throw new TypeError('access graph attestations must be an array');
+  }
+  const prior = previous == null
+    ? new Map()
+    : new Map(validateAccessGraph(previous).paths.map((path) => [accessPairKey(path), path]));
+  const paths = [];
+  for (const [index, record] of attestations.entries()) {
+    const field = `attestations[${index}]`;
+    object(record, field);
+    if (record.attested !== true) continue;
+    const providerId = string(record.providerId, `${field}.providerId`);
+    const modelId = string(record.modelId, `${field}.modelId`);
+    const effort = record.effort == null ? null : string(record.effort, `${field}.effort`);
+    const domain = effortDomains?.[`${providerId}:${modelId}`];
+    if (Array.isArray(domain) && !domain.includes(effort)) {
+      throw new TypeError(
+        `${field}.effort is outside the model effort domain: ${modelId}+${effort ?? 'none'}`,
+      );
+    }
+    const path = {
+      id: record.id,
+      surfaceId: record.surfaceId,
+      providerId,
+      modelId,
+      effort,
+      transportId: record.transportId,
+      availability: 'unknown',
+      enforcement: record.enforcement,
+      capabilityEvidence: record.capabilityEvidence,
+      attestation: null,
+    };
+    const carried = prior.get(accessPairKey(path));
+    if (carried) {
+      path.availability = carried.availability;
+      path.attestation = carried.attestation;
+    }
+    paths.push(path);
+  }
+  return sealAccessGraph(paths);
+}
+
+/** Adapter-side identity match: surface, provider, model and transport. */
+export function capabilityPathMatchesIdentity(path, route) {
+  return CAPABILITY_IDENTITY.every((field) => path?.[field] === route?.[field]);
+}
+
+/** Adapter-side pair match: identity plus the exact attested effort. */
+export function capabilityPathMatchesPair(path, route) {
+  const applied = path?.effort?.applied;
+  return capabilityPathMatchesIdentity(path, route)
+    && typeof applied === 'string'
+    && applied !== 'unknown'
+    && applied === route?.effort;
+}
+
+/**
+ * Pick the capability path for a requested route: the exact pair when one
+ * exists, otherwise the identity match, so an unattested control still reports
+ * its own verification failure instead of looking like a missing route.
+ */
+export function selectCapabilityPath(paths, route) {
+  const candidates = paths.filter((path) => capabilityPathMatchesIdentity(path, route));
+  if (candidates.length === 0) return null;
+  return candidates.find((path) => capabilityPathMatchesPair(path, route)) ?? candidates[0];
+}
+
+/** Turn one normalized surface-capability path into an Access-graph attestation. */
+export function attestAccessPath(path, { revision, observedAt, expiresAt } = {}) {
+  const capabilityEvidence = Object.freeze({
+    revision: string(revision, 'capability attestation revision'),
+    ...dated({ observedAt, expiresAt }, 'capability attestation'),
+  });
+  const attested = path.verified === true;
+  return Object.freeze({
+    id: path.id,
+    surfaceId: path.surfaceId,
+    providerId: path.providerId,
+    modelId: path.modelId,
+    effort: attested ? path.effort.applied : null,
+    transportId: path.transportId,
+    attested,
+    attestationFailures: Object.freeze([...path.verificationFailures]),
+    enforcement: Object.freeze({ model: path.model.method, effort: path.effort.method }),
+    capabilityEvidence,
+  });
+}

package/src/lib/routingAccessGraphStore.mjs

@@ -0,0 +1,300 @@
+/**
+ * The Access-graph store — the locked, atomic, revisioned home of the user-local
+ * Access graph, plus the capability-probe lifecycle that moves one pair from
+ * `unknown` to `available` or `unavailable`.
+ *
+ * Every write is compare-and-swap against the revision the caller read, so two
+ * concurrent dispatches cannot each record an attestation the other never saw.
+ * A stale expected revision is rejected, never merged; a held lock fails the
+ * write instead of racing it; and a document that will not parse fails closed
+ * rather than resetting the graph to empty.
+ *
+ * Only a deterministic unsupported or authorization failure may mutate
+ * availability. Every other probe failure returns the graph untouched, so one
+ * bad minute cannot poison it.
+ */
+import { mkdir, readFile, rmdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { writeAtomic } from './atomicWrite.mjs';
+import {
+  buildAccessGraph,
+  resolveAccessRoute,
+  sealAccessGraph,
+  validateAccessGraph,
+} from './routingAccessGraph.mjs';
+
+/** User-local routing evidence: owner-only, like every other routing document. */
+const STORE_MODE = 0o600;
+const LOCK_TIMEOUT_MS = 2000;
+const LOCK_POLL_MS = 10;
+
+/**
+ * The probe failure taxonomy, typed by what a failure actually proves.
+ * `deterministic` kinds are the only ones allowed to mutate availability.
+ */
+export const PROBE_FAILURE_KINDS = Object.freeze({
+  'unsupported-model': 'deterministic',
+  'unsupported-effort': 'deterministic',
+  'not-authorized': 'deterministic',
+  timeout: 'transient',
+  'rate-limited': 'transient',
+  'malformed-response': 'transient',
+  'provider-failure': 'transient',
+});
+
+const PROBE_FIELDS = new Set(['id', 'sideEffectFree', 'cost']);
+
+const AUTHORIZATION_FIELDS = new Set(['id', 'actor', 'grantedAt']);
+
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+
+function object(value, field) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${field} must be an object`);
+  }
+  return value;
+}
+
+function string(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function timestamp(value, field) {
+  string(value, field);
+  if (!Number.isFinite(Date.parse(value))) throw new TypeError(`${field} must be an ISO timestamp`);
+  return value;
+}
+
+function closedFields(value, allowed, message) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new TypeError(`${message}: ${key}`);
+  }
+  return value;
+}
+
+/**
+ * A capability probe is minimal, side-effect-free and cost-visible, and it
+ * carries no consumer task data — the closed field set is what enforces that.
+ */
+export function validateCapabilityProbe(probe) {
+  object(probe, 'capability probe');
+  closedFields(probe, PROBE_FIELDS, 'capability probe must carry no consumer task data');
+  if (probe.sideEffectFree !== true) {
+    throw new TypeError('capability probe must be side-effect-free');
+  }
+  const cost = object(probe.cost, 'capability probe cost');
+  if (!Number.isFinite(cost.amount) || cost.amount < 0) {
+    throw new TypeError('capability probe cost.amount must be a non-negative number');
+  }
+  return Object.freeze({
+    id: string(probe.id, 'capability probe id'),
+    sideEffectFree: true,
+    cost: Object.freeze({
+      amount: cost.amount,
+      currency: string(cost.currency, 'capability probe cost.currency'),
+      unit: string(cost.unit, 'capability probe cost.unit'),
+    }),
+  });
+}
+
+/** A probe only runs, and only mutates the graph, under a named authorization. */
+export function validateProbeAuthorization(authorization) {
+  object(authorization, 'probe authorization');
+  closedFields(authorization, AUTHORIZATION_FIELDS, 'unknown probe authorization field');
+  return Object.freeze({
+    id: string(authorization.id, 'probe authorization id'),
+    actor: string(authorization.actor, 'probe authorization actor'),
+    grantedAt: timestamp(authorization.grantedAt, 'probe authorization grantedAt'),
+  });
+}
+
+/** Type one probe failure. Anything untyped stays transient by construction. */
+export function classifyProbeFailure(kind) {
+  const named = typeof kind === 'string' && kind.trim() !== '' ? kind : 'unclassified';
+  const determinism = PROBE_FAILURE_KINDS[named] === 'deterministic'
+    ? 'deterministic'
+    : 'transient';
+  return Object.freeze({
+    kind: named,
+    determinism,
+    mutatesAvailability: determinism === 'deterministic',
+  });
+}
+
+function attestedPaths(paths, index, attestation) {
+  return paths.map((path, position) => (position === index
+    ? { ...path, availability: attestation.result, attestation }
+    : path));
+}
+
+/**
+ * Apply one authorized probe result to a graph. Success attests `available`, a
+ * deterministic failure writes the dated `unavailable` attestation, and every
+ * other failure returns the graph untouched.
+ */
+export function applyProbeOutcome(graph, outcome) {
+  const current = validateAccessGraph(graph);
+  object(outcome, 'probe outcome');
+  const pathId = string(outcome.pathId, 'probe outcome pathId');
+  const probe = validateCapabilityProbe(outcome.probe);
+  const authorization = validateProbeAuthorization(outcome.authorization);
+  const observedAt = timestamp(outcome.observedAt, 'probe outcome observedAt');
+  const expiresAt = timestamp(outcome.expiresAt, 'probe outcome expiresAt');
+  if (outcome.result !== 'succeeded' && outcome.result !== 'failed') {
+    throw new TypeError('probe outcome result must be one of: succeeded, failed');
+  }
+  const index = current.paths.findIndex((path) => path.id === pathId);
+  if (index < 0) throw new TypeError(`probe outcome names an unknown access path: ${pathId}`);
+  const failure = outcome.result === 'failed' ? classifyProbeFailure(outcome.failureKind) : null;
+  if (failure && !failure.mutatesAvailability) {
+    return Object.freeze({
+      graph: current,
+      changed: false,
+      availability: current.paths[index].availability,
+      failure,
+      reason: `probe-inconclusive:${failure.kind}`,
+    });
+  }
+  const availability = outcome.result === 'succeeded' ? 'available' : 'unavailable';
+  const next = sealAccessGraph(attestedPaths(current.paths, index, {
+    result: availability,
+    failureKind: failure?.kind ?? null,
+    probeId: probe.id,
+    authorizationId: authorization.id,
+    observedAt,
+    expiresAt,
+  }));
+  return Object.freeze({
+    graph: next,
+    changed: next.revision !== current.revision,
+    availability,
+    failure,
+    reason: `probe-${availability}:${pathId}`,
+  });
+}
+
+/** Read the stored graph. Missing is `null`; unreadable or invalid throws. */
+export async function readAccessGraphDocument(file) {
+  let raw;
+  try {
+    raw = await readFile(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`access graph document is not valid JSON: ${file}`);
+  }
+  const graph = validateAccessGraph(parsed);
+  return Object.freeze({ graph, revision: graph.revision });
+}
+
+async function withStoreLock(file, lockTimeoutMs, run) {
+  const lock = `${file}.lock`;
+  const deadline = Date.now() + lockTimeoutMs;
+  for (;;) {
+    try {
+      await mkdir(lock);
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      if (Date.now() >= deadline) throw new Error(`access graph store is locked: ${lock}`);
+      await sleep(LOCK_POLL_MS);
+    }
+  }
+  try {
+    return await run();
+  } finally {
+    await rmdir(lock).catch(() => {});
+  }
+}
+
+/**
+ * Compare-and-swap write. `expectedRevision` is the revision the caller read,
+ * or `null` for a first write; anything else is a stale write and is rejected.
+ */
+export async function writeAccessGraphDocument(file, graph, options = {}) {
+  const next = validateAccessGraph(graph);
+  const { expectedRevision, lockTimeoutMs = LOCK_TIMEOUT_MS } = options;
+  if (expectedRevision !== null && typeof expectedRevision !== 'string') {
+    throw new TypeError('access graph write requires an expected revision (null for a first write)');
+  }
+  await mkdir(dirname(file), { recursive: true });
+  return withStoreLock(file, lockTimeoutMs, async () => {
+    const found = (await readAccessGraphDocument(file))?.revision ?? null;
+    if (found !== expectedRevision) {
+      throw new Error(
+        `stale access graph revision: expected ${expectedRevision ?? 'none'}, `
+        + `found ${found ?? 'none'}`,
+      );
+    }
+    await writeAtomic(file, `${JSON.stringify(next, null, 2)}\n`, STORE_MODE);
+    return Object.freeze({ path: file, graph: next, revision: next.revision });
+  });
+}
+
+/**
+ * Rebuild the graph from the current surface attestations and store it. An
+ * unchanged rebuild is a no-op: the revision is content-derived, so nothing is
+ * written and every recorded attestation survives.
+ */
+export async function reconcileAccessGraph({
+  file,
+  attestations,
+  effortDomains = null,
+  lockTimeoutMs = LOCK_TIMEOUT_MS,
+}) {
+  const current = await readAccessGraphDocument(file);
+  const next = buildAccessGraph({
+    attestations,
+    previous: current?.graph ?? null,
+    effortDomains,
+  });
+  if (current?.revision === next.revision) {
+    return Object.freeze({ graph: current.graph, revision: current.revision, changed: false });
+  }
+  const written = await writeAccessGraphDocument(file, next, {
+    expectedRevision: current?.revision ?? null,
+    lockTimeoutMs,
+  });
+  return Object.freeze({ graph: written.graph, revision: written.revision, changed: true });
+}
+
+/**
+ * Ask what one pair may do now. A supervised run gets the validated probe to
+ * run; an AFK run stays blocked until the proof exists.
+ */
+export async function planCapabilityProbe({ file, pair, afk = false, probe }) {
+  const validated = validateCapabilityProbe(probe);
+  const current = await readAccessGraphDocument(file);
+  if (!current) throw new Error(`access graph document is missing: ${file}`);
+  const route = resolveAccessRoute(current.graph, pair, { afk });
+  return Object.freeze({
+    ...route,
+    revision: current.revision,
+    probe: route.state === 'verification-required' ? validated : null,
+  });
+}
+
+/**
+ * Record one authorized probe result. A deterministic failure writes the dated
+ * unavailable attestation; every other failure leaves the stored graph alone.
+ */
+export async function recordProbeOutcome({ file, outcome, lockTimeoutMs = LOCK_TIMEOUT_MS }) {
+  const current = await readAccessGraphDocument(file);
+  if (!current) throw new Error(`access graph document is missing: ${file}`);
+  const applied = applyProbeOutcome(current.graph, outcome);
+  if (!applied.changed) return Object.freeze({ ...applied, revision: current.revision });
+  const written = await writeAccessGraphDocument(file, applied.graph, {
+    expectedRevision: current.revision,
+    lockTimeoutMs,
+  });
+  return Object.freeze({ ...applied, revision: written.revision });
+}