@ikon85/agent-workflow-kit 0.44.1 → 0.45.0

package/src/lib/routingIntent.mjs

@@ -1,4 +1,5 @@
-export const ROUTING_INTENT_VERSION = 1;
+export const ROUTING_INTENT_VERSION = 2;
+export const ROUTING_INTENT_LEGACY_VERSION = 1;
 
 export const ROUTING_WORKLOADS = Object.freeze([
   'judgment',
@@ -12,7 +13,62 @@ export const ROUTING_REASONING = Object.freeze([
   'light',
 ]);
 
-const FIELDS = new Set(['version', 'workload', 'reasoning', 'evidenceSelection']);
+export const ROUTING_TASK_SHAPES = Object.freeze([
+  'single-step',
+  'multi-step',
+  'long-horizon',
+]);
+
+export const ROUTING_RISKS = Object.freeze([
+  'low',
+  'moderate',
+  'high',
+]);
+
+export const ROUTING_AUTONOMY_REQUIREMENTS = Object.freeze([
+  'supervised',
+  'afk',
+]);
+
+export const ROUTING_CONTEXT_NEEDS = Object.freeze([
+  'focused',
+  'repository',
+  'long-context',
+]);
+
+// A v1 intent proves nothing about the dimensions v2 adds, so the migration
+// records every field it had to default. Autonomy is fail-closed — a migrated
+// intent never claims an unattended run the user never authorized. The other
+// three take the neutral middle of their scale so the migration neither
+// inflates nor understates the work.
+export const ROUTING_INTENT_MIGRATION_DEFAULTS = Object.freeze({
+  taskShape: 'multi-step',
+  risk: 'moderate',
+  autonomyRequirement: 'supervised',
+  contextNeed: 'repository',
+});
+
+const DIMENSIONS = Object.freeze([
+  Object.freeze({ field: 'workload', key: 'routing-intent', allowed: ROUTING_WORKLOADS }),
+  Object.freeze({ field: 'reasoning', key: 'reasoning-intent', allowed: ROUTING_REASONING }),
+  Object.freeze({ field: 'taskShape', key: 'task-shape', allowed: ROUTING_TASK_SHAPES }),
+  Object.freeze({ field: 'risk', key: 'risk', allowed: ROUTING_RISKS }),
+  Object.freeze({
+    field: 'autonomyRequirement',
+    key: 'autonomy-requirement',
+    allowed: ROUTING_AUTONOMY_REQUIREMENTS,
+  }),
+  Object.freeze({ field: 'contextNeed', key: 'context-need', allowed: ROUTING_CONTEXT_NEEDS }),
+]);
+
+const VERSION_KEY = 'intent-version';
+const EVIDENCE_SELECTION_KEY = 'evidence-selection';
+const FIELDS = new Set([
+  'version',
+  ...DIMENSIONS.map((dimension) => dimension.field),
+  'evidenceSelection',
+]);
+const LEGACY_FIELDS = new Set(['version', 'workload', 'reasoning', 'evidenceSelection']);
 const EVIDENCE_SELECTION_FIELDS = new Set(['workload', 'domain', 'axes']);
 
 function requireEnum(value, allowed, field) {
@@ -71,23 +127,133 @@ export function evidenceSelectionMatchesObservation(input, observationWorkload)
     && selection.axes.includes(axis);
 }
 
-export function validateRoutingIntent(input) {
+function requireIntentDocument(input, allowedFields) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) {
     throw new TypeError('routing intent must be an object');
   }
   for (const field of Object.keys(input)) {
-    if (!FIELDS.has(field)) throw new TypeError(`unknown routing intent field: ${field}`);
+    if (!allowedFields.has(field)) throw new TypeError(`unknown routing intent field: ${field}`);
+  }
+  return input;
+}
+
+export function validateRoutingIntent(input) {
+  if (input && typeof input === 'object' && !Array.isArray(input)
+      && input.version === ROUTING_INTENT_LEGACY_VERSION) {
+    return migrateRoutingIntent(input).intent;
   }
+  requireIntentDocument(input, FIELDS);
   if (input.version !== ROUTING_INTENT_VERSION) {
-    throw new TypeError(`routing intent version must be ${ROUTING_INTENT_VERSION}`);
+    throw new TypeError(
+      `routing intent version must be ${ROUTING_INTENT_LEGACY_VERSION} or ${ROUTING_INTENT_VERSION}`,
+    );
+  }
+  const intent = { version: ROUTING_INTENT_VERSION };
+  for (const { field, allowed } of DIMENSIONS) {
+    intent[field] = requireEnum(input[field], allowed, field);
   }
-  const intent = {
-    version: ROUTING_INTENT_VERSION,
-    workload: requireEnum(input.workload, ROUTING_WORKLOADS, 'workload'),
-    reasoning: requireEnum(input.reasoning, ROUTING_REASONING, 'reasoning'),
-  };
   if (input.evidenceSelection !== undefined) {
     intent.evidenceSelection = validateEvidenceSelection(input.evidenceSelection);
   }
   return Object.freeze(intent);
 }
+
+export function migrateRoutingIntent(input) {
+  if (input && typeof input === 'object' && !Array.isArray(input)
+      && input.version === ROUTING_INTENT_VERSION) {
+    return Object.freeze({
+      intent: validateRoutingIntent(input),
+      fromVersion: ROUTING_INTENT_VERSION,
+      defaulted: Object.freeze([]),
+    });
+  }
+  requireIntentDocument(input, LEGACY_FIELDS);
+  if (input.version !== ROUTING_INTENT_LEGACY_VERSION) {
+    throw new TypeError(
+      `routing intent version must be ${ROUTING_INTENT_LEGACY_VERSION} or ${ROUTING_INTENT_VERSION}`,
+    );
+  }
+  // A v1 document cannot carry any v2 dimension, so every one of them is defaulted.
+  const defaulted = Object.freeze(Object.keys(ROUTING_INTENT_MIGRATION_DEFAULTS));
+  return Object.freeze({
+    intent: validateRoutingIntent({
+      ...input,
+      version: ROUTING_INTENT_VERSION,
+      ...ROUTING_INTENT_MIGRATION_DEFAULTS,
+    }),
+    fromVersion: ROUTING_INTENT_LEGACY_VERSION,
+    defaulted,
+  });
+}
+
+function serializeEvidenceSelection(selection) {
+  for (const segment of [selection.workload, selection.domain, ...selection.axes]) {
+    if (segment.includes(',')) {
+      throw new TypeError('evidence selection axis must not contain a comma');
+    }
+  }
+  return `${selection.workload}:${selection.domain}:${selection.axes.join(',')}`;
+}
+
+export function serializeRoutingIntent(input) {
+  const intent = validateRoutingIntent(input);
+  const lines = [`${VERSION_KEY}: ${intent.version}`];
+  for (const { field, key } of DIMENSIONS) lines.push(`${key}: ${intent[field]}`);
+  if (intent.evidenceSelection !== undefined) {
+    lines.push(`${EVIDENCE_SELECTION_KEY}: ${serializeEvidenceSelection(intent.evidenceSelection)}`);
+  }
+  return lines.join('\n');
+}
+
+const ISSUE_KEYS = new Map([
+  ...DIMENSIONS.map(({ key, field }) => [key, field]),
+  [VERSION_KEY, 'version'],
+  [EVIDENCE_SELECTION_KEY, 'evidenceSelection'],
+]);
+const INTENT_LINE = /^\s*([a-z][a-z-]*)\s*:\s*(\S.*?)\s*$/;
+const WORKLOAD_KEY = DIMENSIONS[0].key;
+
+// Only the one blank-line-delimited block that names the workload key is read,
+// so an unrelated `risk:` line elsewhere in an issue body can never be mistaken
+// for a Routing intent dimension.
+function readIntentBlock(text) {
+  if (typeof text !== 'string') throw new TypeError('routing intent block must be a string');
+  const blocks = text.split(/\n[ \t]*\n/).filter((block) => block
+    .split('\n')
+    .some((line) => INTENT_LINE.exec(line)?.[1] === WORKLOAD_KEY));
+  if (blocks.length === 0) {
+    throw new TypeError(`routing intent block must name ${WORKLOAD_KEY}`);
+  }
+  if (blocks.length > 1) throw new TypeError('routing intent block must appear once');
+  const document = {};
+  for (const line of blocks[0].split('\n')) {
+    const match = INTENT_LINE.exec(line);
+    if (!match || !ISSUE_KEYS.has(match[1])) continue;
+    const field = ISSUE_KEYS.get(match[1]);
+    if (document[field] !== undefined) {
+      throw new TypeError(`duplicate routing intent field: ${match[1]}`);
+    }
+    document[field] = match[2];
+  }
+  return document;
+}
+
+function parseEvidenceSelection(value) {
+  const [workload, domain, axes, ...rest] = value.split(':');
+  if (rest.length > 0 || !workload || !domain || !axes) {
+    throw new TypeError(`${EVIDENCE_SELECTION_KEY} must name workload, domain, and axes`);
+  }
+  return { workload, domain, axes: axes.split(',') };
+}
+
+export function parseRoutingIntent(text) {
+  const document = readIntentBlock(text);
+  const version = document.version === undefined
+    ? ROUTING_INTENT_LEGACY_VERSION
+    : Number(document.version);
+  const decoded = { ...document, version };
+  if (document.evidenceSelection !== undefined) {
+    decoded.evidenceSelection = parseEvidenceSelection(document.evidenceSelection);
+  }
+  return migrateRoutingIntent(decoded);
+}

package/src/lib/routingIntentClassifier.mjs

@@ -0,0 +1,137 @@
+/**
+ * Intent resolution — the first of the two stages a dispatch runs through.
+ *
+ * Stage one resolves *what the work is*: an explicit Routing intent stated in
+ * the issue or the task wins, and only when none is stated does a
+ * provider-neutral workflow classifier derive one. Stage two — route selection
+ * against the Evidence catalog and the Standard route — happens elsewhere, in
+ * the resolver, and never runs backwards: **a route is never an intent source.**
+ * This module therefore knows nothing about models, efforts, surfaces or
+ * transports, and rejects a caller that tries to feed one in, because a signal
+ * named after a route would let a chosen model justify the intent that chose it.
+ *
+ * The classifier is a total, inspectable table over five declared workflow
+ * signals. Four of them map one-to-one onto an intent dimension; `reasoning` is
+ * the one dimension a workflow cannot state without opinionating, so it is
+ * derived from what the unit produces and what a wrong answer costs.
+ */
+import {
+  ROUTING_INTENT_VERSION,
+  migrateRoutingIntent,
+  parseRoutingIntent,
+  validateRoutingIntent,
+} from './routingIntent.mjs';
+
+/** The provider-neutral facts a delegating workflow already knows about a unit. */
+export const WORKFLOW_SIGNAL_VOCABULARY = Object.freeze({
+  outcome: Object.freeze(['decision', 'implementation', 'transformation']),
+  steps: Object.freeze(['single', 'several', 'session-spanning']),
+  blastRadius: Object.freeze(['contained', 'shared', 'irreversible']),
+  supervision: Object.freeze(['attended', 'unattended']),
+  breadth: Object.freeze(['single-file', 'repository', 'cross-repository']),
+});
+
+const SIGNAL_DIMENSIONS = Object.freeze({
+  outcome: Object.freeze({
+    field: 'workload',
+    values: Object.freeze({
+      decision: 'judgment', implementation: 'development', transformation: 'mechanical',
+    }),
+  }),
+  steps: Object.freeze({
+    field: 'taskShape',
+    values: Object.freeze({
+      single: 'single-step', several: 'multi-step', 'session-spanning': 'long-horizon',
+    }),
+  }),
+  blastRadius: Object.freeze({
+    field: 'risk',
+    values: Object.freeze({ contained: 'low', shared: 'moderate', irreversible: 'high' }),
+  }),
+  supervision: Object.freeze({
+    field: 'autonomyRequirement',
+    values: Object.freeze({ attended: 'supervised', unattended: 'afk' }),
+  }),
+  breadth: Object.freeze({
+    field: 'contextNeed',
+    values: Object.freeze({
+      'single-file': 'focused', repository: 'repository', 'cross-repository': 'long-context',
+    }),
+  }),
+});
+
+/**
+ * The vocabulary of the other stage. A signal named after any of these is not a
+ * typo to correct but a route leaking into intent resolution, so it is named as
+ * such rather than reported as an unknown field.
+ */
+const ROUTE_FIELDS = Object.freeze(new Set([
+  'route', 'model', 'modelId', 'effort', 'provider', 'providerId',
+  'surface', 'surfaceId', 'transport', 'transportId', 'accessPathId', 'pair',
+]));
+
+function plainObject(value, field) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${field} must be an object`);
+  }
+  return value;
+}
+
+/**
+ * How much reasoning the unit is worth. Judgment work has no decisive evidence
+ * and always reasons deeply; the other two escalate with the blast radius, so a
+ * mechanical change that cannot be taken back stops being treated as mechanical.
+ */
+function derivedReasoning(workload, risk) {
+  if (workload === 'judgment') return 'deep';
+  if (workload === 'development') return risk === 'high' ? 'deep' : 'balanced';
+  return risk === 'low' ? 'light' : 'balanced';
+}
+
+export function classifyWorkflowIntent(input) {
+  plainObject(input, 'workflow signals');
+  for (const field of Object.keys(input)) {
+    if (ROUTE_FIELDS.has(field)) {
+      throw new TypeError(`a route is never an intent source: ${field}`);
+    }
+    if (!(field in SIGNAL_DIMENSIONS)) throw new TypeError(`unknown workflow signal: ${field}`);
+  }
+  const document = { version: ROUTING_INTENT_VERSION };
+  for (const [signal, { field, values }] of Object.entries(SIGNAL_DIMENSIONS)) {
+    const mapped = Object.hasOwn(values, input[signal]) ? values[input[signal]] : undefined;
+    if (mapped === undefined) {
+      throw new TypeError(`${signal} must be one of: ${WORKFLOW_SIGNAL_VOCABULARY[signal].join(', ')}`);
+    }
+    document[field] = mapped;
+  }
+  document.reasoning = derivedReasoning(document.workload, document.risk);
+  return validateRoutingIntent(document);
+}
+
+/**
+ * The resolved Routing intent plus how it was resolved, so a Dispatch plan can
+ * show that an intent was stated rather than guessed — and which dimensions a
+ * migrated v1 intent never carried.
+ */
+export function resolveRoutingIntent(input) {
+  plainObject(input, 'intent resolution input');
+  const explicit = input.explicit ?? null;
+  if (explicit !== null) {
+    // A stated intent may be a document or the block an issue body carries; a
+    // legacy one migrates and reports every dimension it could not have stated.
+    const stated = typeof explicit === 'string'
+      ? parseRoutingIntent(explicit)
+      : migrateRoutingIntent(explicit);
+    return Object.freeze({
+      source: 'explicit', intent: stated.intent, defaulted: stated.defaulted,
+    });
+  }
+  if (input.signals == null) {
+    throw new TypeError('intent resolution needs an explicit intent or workflow signals');
+  }
+  return Object.freeze({
+    source: 'classifier',
+    intent: classifyWorkflowIntent(input.signals),
+    defaulted: Object.freeze([]),
+  });
+}

package/src/lib/routingInventory/snapshots/claude.json

@@ -0,0 +1,49 @@
+{
+  "snapshotVersion": 1,
+  "surface": "claude-code",
+  "provider": "anthropic",
+  "provenance": {
+    "sourceKind": "maintainer-reading",
+    "sourceRef": "claude --help model and effort domains, Claude Code 2.1.220; the surface publishes no machine-readable model inventory, so this half is pinned by maintainer reading rather than by a fetch",
+    "capturedAt": "2026-07-28",
+    "integrity": "sha256-B2mGRS1jnYS_2JCmvkZum0vV-yliwOGS1Gtu_1Ghv2k"
+  },
+  "models": [
+    {
+      "modelId": "opus",
+      "identifiers": ["opus", "opus[1m]", "claude-opus-5", "claude-opus-5[1m]"],
+      "effortAxis": true,
+      "efforts": ["low", "medium", "high", "xhigh", "max"],
+      "defaultEffort": null,
+      "visibility": "list",
+      "effortSource": "cli-effort-domain; applied effort attested by per-spawn readback in verify-spike 18c"
+    },
+    {
+      "modelId": "sonnet",
+      "identifiers": ["sonnet"],
+      "effortAxis": true,
+      "efforts": ["low", "medium", "high", "xhigh", "max"],
+      "defaultEffort": null,
+      "visibility": "list",
+      "effortSource": "cli-effort-domain"
+    },
+    {
+      "modelId": "haiku",
+      "identifiers": ["haiku"],
+      "effortAxis": false,
+      "efforts": [],
+      "defaultEffort": null,
+      "visibility": "list",
+      "effortSource": "attested absent: a haiku run records no effort because none is applied"
+    },
+    {
+      "modelId": "fable",
+      "identifiers": ["fable", "claude-fable-5"],
+      "effortAxis": true,
+      "efforts": ["low", "medium", "high", "xhigh", "max"],
+      "defaultEffort": null,
+      "visibility": "list",
+      "effortSource": "cli-effort-domain"
+    }
+  ]
+}

package/src/lib/routingInventory/snapshots/codex.json

@@ -0,0 +1,109 @@
+{
+  "snapshotVersion": 1,
+  "surface": "codex",
+  "provider": "openai",
+  "provenance": {
+    "sourceKind": "capability-cache",
+    "sourceRef": "local Codex capability cache (models_cache.json) fetched under the existing subscription login, ETag-versioned; client 0.145.0",
+    "capturedAt": "2026-07-28",
+    "integrity": "sha256-SS-M-6oo94SpVYbsyIw7-SfiEf_pQyGmX5RaFWACtns"
+  },
+  "models": [
+    {
+      "modelId": "gpt-5.6-sol",
+      "identifiers": ["gpt-5.6-sol"],
+      "effortAxis": true,
+      "efforts": ["low", "medium", "high", "xhigh", "max", "ultra"],
+      "defaultEffort": "low",
+      "visibility": "list",
+      "supportedInApi": true,
+      "contextWindow": 272000,
+      "maxContextWindow": 272000,
+      "effortSource": "capability-cache"
+    },
+    {
+      "modelId": "gpt-5.6-terra",
+      "identifiers": ["gpt-5.6-terra"],
+      "effortAxis": true,
+      "efforts": ["low", "medium", "high", "xhigh", "max", "ultra"],
+      "defaultEffort": "medium",
+      "visibility": "list",
+      "supportedInApi": true,
+      "contextWindow": 272000,
+      "maxContextWindow": 272000,
+      "effortSource": "capability-cache"
+    },
+    {
+      "modelId": "gpt-5.6-luna",
+      "identifiers": ["gpt-5.6-luna"],
+      "effortAxis": true,
+      "efforts": ["low", "medium", "high", "xhigh", "max"],
+      "defaultEffort": "medium",
+      "visibility": "list",
+      "supportedInApi": true,
+      "contextWindow": 272000,
+      "maxContextWindow": 272000,
+      "effortSource": "capability-cache"
+    },
+    {
+      "modelId": "gpt-5.5",
+      "identifiers": ["gpt-5.5"],
+      "effortAxis": true,
+      "efforts": ["low", "medium", "high", "xhigh"],
+      "defaultEffort": "medium",
+      "visibility": "list",
+      "supportedInApi": true,
+      "contextWindow": 272000,
+      "maxContextWindow": 272000,
+      "effortSource": "capability-cache"
+    },
+    {
+      "modelId": "gpt-5.4",
+      "identifiers": ["gpt-5.4"],
+      "effortAxis": true,
+      "efforts": ["low", "medium", "high", "xhigh"],
+      "defaultEffort": "medium",
+      "visibility": "list",
+      "supportedInApi": true,
+      "contextWindow": 272000,
+      "maxContextWindow": 1000000,
+      "effortSource": "capability-cache"
+    },
+    {
+      "modelId": "gpt-5.4-mini",
+      "identifiers": ["gpt-5.4-mini"],
+      "effortAxis": true,
+      "efforts": ["low", "medium", "high", "xhigh"],
+      "defaultEffort": "medium",
+      "visibility": "list",
+      "supportedInApi": true,
+      "contextWindow": 272000,
+      "maxContextWindow": 272000,
+      "effortSource": "capability-cache"
+    },
+    {
+      "modelId": "gpt-5.3-codex-spark",
+      "identifiers": ["gpt-5.3-codex-spark"],
+      "effortAxis": true,
+      "efforts": ["low", "medium", "high", "xhigh"],
+      "defaultEffort": "high",
+      "visibility": "list",
+      "supportedInApi": false,
+      "contextWindow": 128000,
+      "maxContextWindow": 128000,
+      "effortSource": "capability-cache"
+    },
+    {
+      "modelId": "codex-auto-review",
+      "identifiers": ["codex-auto-review"],
+      "effortAxis": true,
+      "efforts": ["low", "medium", "high", "xhigh"],
+      "defaultEffort": "medium",
+      "visibility": "hide",
+      "supportedInApi": true,
+      "contextWindow": 272000,
+      "maxContextWindow": 1000000,
+      "effortSource": "capability-cache"
+    }
+  ]
+}

package/src/lib/routingInventory.mjs

@@ -0,0 +1,182 @@
+/**
+ * The pinned Model inventory: every model-and-effort pair the Kit knows about,
+ * per agent surface, read from provenance-hashed source snapshots committed
+ * beside this module.
+ *
+ * Pinned, not live. Release preparation stays deterministic and offline: this
+ * module only reads local files, never a provider API. Refreshing a snapshot is
+ * a separate maintainer step.
+ *
+ * Unfiltered by construction. The inventory lists every known pair, including
+ * pairs the local machine cannot reach and models a surface hides from its own
+ * picker. Local detection feeds Access-graph attestation and the presentation
+ * order of a setup list — never authorization. Authorization is the Model
+ * roster, and it lives in the Routing profile.
+ *
+ * The digest covers the capability payload (surface, provider, snapshot
+ * version, captured date, source kind, and the model records), not the free
+ * prose of `provenance.sourceRef`: publish-time scrubbing rewrites prose but
+ * must never touch a capability fact. It is written in the self-describing
+ * `sha256-<base64url>` integrity form, so a shipped digest reads as a digest
+ * rather than as an unexplained high-entropy string.
+ */
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Snapshot files, in the order that fixes pair order. */
+export const INVENTORY_SNAPSHOT_FILES = Object.freeze(['claude.json', 'codex.json']);
+
+export const INVENTORY_SNAPSHOT_VERSION = 1;
+
+/** Untested access is attested `unknown`; detection alone never promotes it. */
+export const UNTESTED_ACCESS = 'unknown';
+
+const DEFAULT_SNAPSHOT_DIR = fileURLToPath(
+  new URL('./routingInventory/snapshots/', import.meta.url),
+);
+
+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);
+}
+
+const sha256 = (text) => `sha256-${createHash('sha256').update(text).digest('base64url')}`;
+
+/** Digest of a snapshot's capability payload — the value `provenance.integrity` pins. */
+export function snapshotDigest(snapshot) {
+  return sha256(canonical({
+    snapshotVersion: snapshot.snapshotVersion,
+    surface: snapshot.surface,
+    provider: snapshot.provider,
+    capturedAt: snapshot.provenance?.capturedAt ?? null,
+    sourceKind: snapshot.provenance?.sourceKind ?? null,
+    models: snapshot.models,
+  }));
+}
+
+function assertModel(file, model) {
+  const fail = (reason) => {
+    throw new Error(`routing inventory snapshot ${file}: ${reason}`);
+  };
+  if (!model || typeof model.modelId !== 'string' || !model.modelId) fail('a model has no modelId');
+  if (!Array.isArray(model.identifiers) || !model.identifiers.includes(model.modelId)) {
+    fail(`model ${model.modelId} does not list its own identifier`);
+  }
+  if (typeof model.effortAxis !== 'boolean') fail(`model ${model.modelId} has no effortAxis`);
+  if (!Array.isArray(model.efforts)) fail(`model ${model.modelId} has no effort domain`);
+  if (model.effortAxis === (model.efforts.length === 0)) {
+    fail(`model ${model.modelId} contradicts its effort axis`);
+  }
+  if (new Set(model.efforts).size !== model.efforts.length) {
+    fail(`model ${model.modelId} repeats an effort`);
+  }
+  const fallback = model.defaultEffort ?? null;
+  if (fallback !== null && !model.efforts.includes(fallback)) {
+    fail(`model ${model.modelId} defaults to an effort outside its domain`);
+  }
+}
+
+function assertSnapshot(file, snapshot) {
+  const fail = (reason) => {
+    throw new Error(`routing inventory snapshot ${file}: ${reason}`);
+  };
+  if (snapshot?.snapshotVersion !== INVENTORY_SNAPSHOT_VERSION) {
+    fail(`unsupported snapshot version ${snapshot?.snapshotVersion}`);
+  }
+  for (const field of ['surface', 'provider']) {
+    if (typeof snapshot[field] !== 'string' || !snapshot[field]) fail(`missing ${field}`);
+  }
+  if (!Array.isArray(snapshot.models) || !snapshot.models.length) fail('lists no model');
+  for (const model of snapshot.models) assertModel(file, model);
+  if (snapshotDigest(snapshot) !== snapshot.provenance?.integrity) {
+    fail('payload does not match its recorded provenance hash');
+  }
+}
+
+async function readSnapshot(snapshotDir, file) {
+  let raw;
+  try {
+    raw = await readFile(join(snapshotDir, file), 'utf8');
+  } catch (error) {
+    throw new Error(`routing inventory snapshot ${file} is unreadable: ${error.code ?? error.message}`);
+  }
+  let snapshot;
+  try {
+    snapshot = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`routing inventory snapshot ${file} is not valid JSON: ${error.message}`);
+  }
+  assertSnapshot(file, snapshot);
+  return snapshot;
+}
+
+function pairsOf(snapshot) {
+  return snapshot.models.flatMap((model) => {
+    const efforts = model.effortAxis ? model.efforts : [null];
+    return efforts.map((effort) => Object.freeze({
+      surface: snapshot.surface,
+      provider: snapshot.provider,
+      modelId: model.modelId,
+      effort,
+    }));
+  });
+}
+
+/**
+ * Read the pinned inventory. Fails closed: an unreadable, malformed, or
+ * tampered snapshot throws instead of yielding a partial pair list.
+ */
+export async function loadRoutingInventory({ snapshotDir = DEFAULT_SNAPSHOT_DIR } = {}) {
+  const snapshots = [];
+  for (const file of INVENTORY_SNAPSHOT_FILES) {
+    snapshots.push(Object.freeze({ file, ...await readSnapshot(snapshotDir, file) }));
+  }
+  const revision = sha256(canonical(snapshots.map(({ file, provenance }) => ({
+    file, digest: provenance.integrity,
+  }))));
+  return Object.freeze({
+    revision,
+    snapshots: Object.freeze(snapshots),
+    pairs: Object.freeze(snapshots.flatMap(pairsOf)),
+  });
+}
+
+function detectedSurfaceIds(surfaces) {
+  return new Set(surfaces
+    .map((surface) => (typeof surface === 'string' ? surface : (surface?.detected ? surface.id : null)))
+    .filter(Boolean));
+}
+
+/**
+ * Order the inventory for presentation and derive its Access-graph attestation
+ * input. Detected surfaces sort first; nothing is ever removed, and every
+ * attestation stays `unknown` until a probe proves otherwise.
+ */
+export function presentInventory(inventory, surfaces = []) {
+  const detected = detectedSurfaceIds(surfaces);
+  const ordered = inventory.pairs
+    .map((pair, index) => ({ pair, index }))
+    .sort((a, b) => (Number(detected.has(b.pair.surface)) - Number(detected.has(a.pair.surface)))
+      || (a.index - b.index))
+    .map(({ pair }) => pair);
+  if (ordered.length !== inventory.pairs.length) {
+    throw new Error('presentation reordered the inventory into a different pair set');
+  }
+  return Object.freeze({
+    pairs: Object.freeze(ordered),
+    attestations: Object.freeze(ordered.map((pair) => Object.freeze({
+      surface: pair.surface,
+      provider: pair.provider,
+      modelId: pair.modelId,
+      effort: pair.effort,
+      detectedSurface: detected.has(pair.surface),
+      access: UNTESTED_ACCESS,
+    }))),
+  });
+}