@ikon85/agent-workflow-kit 0.44.1 → 0.45.0

package/src/lib/routingCatalog.mjs

@@ -1,4 +1,165 @@
 export const EVIDENCE_CATALOG_VERSION = 1;
+export const UNKNOWN_EFFORT = 'unknown';
+
+// Taxonomy — docs/research/agent-task-taxonomy-benchmark-coverage.md §1. The
+// identity stays `workload:domain:axis`, and the frontend vocabulary is a strict
+// subset of it: the generalization is additive.
+const FRONTEND_WORKLOADS = Object.freeze(['frontend-greenfield', 'frontend-repository-repair']);
+
+export const EVIDENCE_WORKLOADS = Object.freeze([
+  ...FRONTEND_WORKLOADS,
+  'repository-repair', 'repository-comprehension', 'code-transformation', 'test-authoring',
+  'greenfield-application', 'algorithmic-synthesis', 'terminal-operations', 'tool-orchestration',
+  'knowledge-deliverable', 'architecture-reasoning', 'long-horizon-autonomy',
+  'long-context-operation',
+]);
+
+// A domain segment exists only where the owner publishes a separate score for it
+// (§1.3); everything else stays `general`, so no aggregate is laundered.
+const FRONTEND_DOMAINS = Object.freeze([
+  'general', 'reference-design', 'marketing', 'analytics',
+  'product', 'game', 'simulation', 'editor',
+]);
+const GENERAL_DOMAIN = Object.freeze(['general']);
+const TOOL_ORCHESTRATION_DOMAINS = Object.freeze([
+  'general', 'airline', 'retail', 'telecom', 'banking',
+]);
+// Four axes stay frontend-scoped (§1.4); `functional` is the general
+// executable-verifier axis, exactly how `openhands-frontend` already uses it.
+const FRONTEND_SCOPED_AXES = Object.freeze([
+  'visual-fidelity', 'visual-preference', 'accessibility', 'responsive',
+]);
+const GENERAL_AXES = Object.freeze([
+  'functional', 'rubric-quality', 'answer-accuracy', 'blind-preference',
+  'policy-adherence', 'time-horizon', 'context-retention',
+]);
+export const EVIDENCE_AXES = Object.freeze([...GENERAL_AXES, ...FRONTEND_SCOPED_AXES]);
+export const FRONTEND_QUALITY_AXES = Object.freeze(['functional', ...FRONTEND_SCOPED_AXES]);
+
+// Owners publish cost per attempted task or per whole run (§6); a per-success
+// figure is Kit-derived and says so. Currency stays its own field, so `USD` plus
+// `attempt` is the researched `usd-per-attempt`.
+export const EVIDENCE_COST_UNITS = Object.freeze(['attempt', 'run', 'success-derived']);
+const DERIVED_COST_UNIT = 'success-derived';
+
+function requireWorkload(workload) {
+  if (!EVIDENCE_WORKLOADS.includes(workload)) {
+    throw new TypeError(`unknown evidence workload: ${workload}`);
+  }
+  return FRONTEND_WORKLOADS.includes(workload);
+}
+
+export function evidenceDomainsFor(workload) {
+  if (requireWorkload(workload)) return FRONTEND_DOMAINS;
+  return workload === 'tool-orchestration' ? TOOL_ORCHESTRATION_DOMAINS : GENERAL_DOMAIN;
+}
+
+export function evidenceAxesFor(workload) {
+  return requireWorkload(workload) ? EVIDENCE_AXES : GENERAL_AXES;
+}
+
+export function evidenceIdentity({ workload, domain = 'general', axis }) {
+  if (!evidenceDomainsFor(workload).includes(domain)) {
+    throw new TypeError(`evidence domain ${domain} is not scored separately for ${workload}`);
+  }
+  if (!evidenceAxesFor(workload).includes(axis)) {
+    throw new TypeError(`evidence axis ${axis} is not defined for ${workload}`);
+  }
+  return `${workload}:${domain}:${axis}`;
+}
+
+export function parseEvidenceIdentity(identity) {
+  string(identity, 'evidence identity');
+  const [workload, domain, axis, ...rest] = identity.split(':');
+  if (rest.length > 0 || !workload || !domain || !axis) {
+    throw new TypeError(`evidence identity must name workload, domain, and axis: ${identity}`);
+  }
+  evidenceIdentity({ workload, domain, axis });
+  return Object.freeze({ workload, domain, axis });
+}
+
+// The three-part decisiveness test (§0, §4): a source is decisive only when it
+// measures the exact triple and preserves effort and harness identity, and a
+// false flag names the collapsed dimension rather than hiding it in a boolean.
+// `freshness.maxAgeDays` is a Kit-side policy per source: almost no owner
+// publishes a cadence (§7.8), so the expiry is the Kit's decision, never read
+// from the owner.
+function sourceClaim(sourceId, flags, maxAgeDays, reason) {
+  const [measuresTriple, preservesEffort, preservesHarness] = flags;
+  const dimensions = ['triple', 'effort', 'harness'];
+  return Object.freeze({
+    sourceId,
+    measuresTriple,
+    preservesEffort,
+    preservesHarness,
+    collapsedDimensions: Object.freeze(dimensions.filter((_, index) => !flags[index])),
+    freshness: Object.freeze({ maxAgeDays, basis: 'kit-policy' }),
+    reason,
+  });
+}
+
+// [sourceId, [measuresTriple, preservesEffort, preservesHarness], maxAgeDays, reason]
+const SOURCE_CLAIM_ROWS = Object.freeze([
+  ['deepswe', [true, true, true], 30, 'Every row names effort, harness and run config.'],
+  ['artificial-analysis-coding-agents', [true, false, true], 30,
+    'The Coding Agent Index runs each agent on its default reasoning effort settings.'],
+  ['openhands-evaluation', [true, false, true], 60,
+    'The harness is named per row, but reasoning effort is not a reported dimension.'],
+  ['code-arena-webdev', [true, false, true], 30,
+    'Per-domain boards with the harness in the model label, but no reasoning-effort column.'],
+  ['openhands-frontend', [true, false, true], 60, 'Names its SDK harness, not the effort.'],
+  ['benchlm', [false, false, false], 7, 'An aggregator: no triple, no effort, no harness.'],
+  ['vision2web', [true, false, false], 30,
+    "The active season's leaderboard is empty, so no row preserves harness or effort."],
+  ['design2code', [true, false, false], 30, 'A static artifact: no harness, no effort.'],
+]);
+
+export const EVIDENCE_SOURCE_CLAIMS = Object.freeze(Object.fromEntries(
+  SOURCE_CLAIM_ROWS.map((row) => [row[0], sourceClaim(...row)]),
+));
+
+export function evidenceSourceClaim(sourceId) {
+  const claim = EVIDENCE_SOURCE_CLAIMS[sourceId];
+  if (!claim) throw new TypeError(`unknown evidence source: ${sourceId}`);
+  return claim;
+}
+
+export function isDecisiveEvidence(claim) {
+  object(claim, 'evidence claim');
+  return claim.measuresTriple && claim.preservesEffort && claim.preservesHarness;
+}
+
+export function evidenceFreshness({ sourceId, observedAt }) {
+  const { freshness } = evidenceSourceClaim(sourceId);
+  const observed = Date.parse(timestamp(observedAt, 'observedAt'));
+  const window = freshness.maxAgeDays * 24 * 60 * 60 * 1000;
+  return Object.freeze({
+    observedAt,
+    expiresAt: new Date(observed + window).toISOString(),
+    maxAgeDays: freshness.maxAgeDays,
+    basis: freshness.basis,
+  });
+}
+
+export function assertPublishedEffort({ sourceId, effort }) {
+  const { preservesEffort } = evidenceSourceClaim(sourceId);
+  string(effort, `${sourceId} effort`);
+  if (!preservesEffort && effort !== UNKNOWN_EFFORT) {
+    throw new TypeError(`${sourceId} does not preserve reasoning effort: effort must be `
+      + `${UNKNOWN_EFFORT}, found ${effort}`);
+  }
+  if (preservesEffort && effort === UNKNOWN_EFFORT) {
+    throw new TypeError(`${sourceId} preserves reasoning effort: a row must name it`);
+  }
+  return effort;
+}
+
+export function assertCostUnit(unit, field = 'cost.unit') {
+  if (!EVIDENCE_COST_UNITS.includes(unit)) {
+    throw new TypeError(`${field} must be one of: ${EVIDENCE_COST_UNITS.join(', ')}`);
+  }
+  return unit;
+}
 
 function object(value, field) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -21,14 +182,13 @@ function number(value, field) {
 
 function timestamp(value, field) {
   string(value, field);
-  const parsed = Date.parse(value);
-  if (!Number.isFinite(parsed)) throw new TypeError(`${field} must be an ISO timestamp`);
+  if (!Number.isFinite(Date.parse(value))) {
+    throw new TypeError(`${field} must be an ISO timestamp`);
+  }
   return value;
 }
 
-function clone(value) {
-  return structuredClone(value);
-}
+const clone = (value) => structuredClone(value);
 
 function deepFreeze(value) {
   if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
@@ -41,12 +201,40 @@ const identity = ({ providerId, modelId }) => `${providerId}:${modelId}`;
 
 function validateModel(model, index) {
   object(model, `models[${index}]`);
+  const field = `models[${index}]`;
   return {
-    providerId: string(model.providerId, `models[${index}].providerId`),
-    modelId: string(model.modelId, `models[${index}].modelId`),
+    providerId: string(model.providerId, `${field}.providerId`),
+    modelId: string(model.modelId, `${field}.modelId`),
   };
 }
 
+// A taxonomy identity is checked against the researched vocabulary; a colon-free
+// workload is a legacy aggregate that can never satisfy an evidence selection.
+const isTaxonomyIdentity = (workload) => workload.includes(':');
+
+function validateWorkloadIdentity(value, field) {
+  const workload = string(value, field);
+  if (isTaxonomyIdentity(workload)) parseEvidenceIdentity(workload);
+  return workload;
+}
+
+// An observation claiming a taxonomy identity carries the whole taxonomy
+// contract, cost unit included; a legacy aggregate keeps its free-form unit.
+function validateCost(cost, field, taxonomy) {
+  if (number(cost.amount, `${field}.amount`) < 0) {
+    throw new TypeError(`${field}.amount must be non-negative`);
+  }
+  string(cost.currency, `${field}.currency`);
+  if (!taxonomy) return string(cost.unit, `${field}.unit`);
+  assertCostUnit(cost.unit, `${field}.unit`);
+  if ((cost.derived === true) !== (cost.unit === DERIVED_COST_UNIT)) {
+    throw new TypeError(
+      `${field}: a per-completed-task value is Kit-derived and must carry derived: true`,
+    );
+  }
+  return cost.unit;
+}
+
 function validateObservation(entry, index, knownModels) {
   const field = `observations[${index}]`;
   object(entry, field);
@@ -55,7 +243,7 @@ function validateObservation(entry, index, knownModels) {
     providerId: string(entry.providerId, `${field}.providerId`),
     modelId: string(entry.modelId, `${field}.modelId`),
     effort: string(entry.effort, `${field}.effort`),
-    workload: string(entry.workload, `${field}.workload`),
+    workload: validateWorkloadIdentity(entry.workload, `${field}.workload`),
     harness: clone(object(entry.harness, `${field}.harness`)),
     score: number(entry.score, `${field}.score`),
     source: clone(object(entry.source, `${field}.source`)),
@@ -65,12 +253,9 @@ function validateObservation(entry, index, knownModels) {
   };
   string(observation.harness.id, `${field}.harness.id`);
   string(observation.harness.version, `${field}.harness.version`);
-  string(observation.source.owner, `${field}.source.owner`);
-  string(observation.source.id, `${field}.source.id`);
-  string(observation.source.url, `${field}.source.url`);
-  string(observation.source.benchmark, `${field}.source.benchmark`);
-  string(observation.source.version, `${field}.source.version`);
-  string(observation.source.snapshotHash, `${field}.source.snapshotHash`);
+  for (const key of ['owner', 'id', 'url', 'benchmark', 'version', 'snapshotHash']) {
+    string(observation.source[key], `${field}.source.${key}`);
+  }
   string(observation.uncertainty.kind, `${field}.uncertainty.kind`);
   number(observation.uncertainty.value, `${field}.uncertainty.value`);
   const observedAt = timestamp(observation.freshness.observedAt, `${field}.freshness.observedAt`);
@@ -78,10 +263,7 @@ function validateObservation(entry, index, knownModels) {
   if (Date.parse(expiresAt) <= Date.parse(observedAt)) {
     throw new TypeError(`${field}.freshness.expiresAt must follow observedAt`);
   }
-  const amount = number(observation.cost.amount, `${field}.cost.amount`);
-  if (amount < 0) throw new TypeError(`${field}.cost.amount must be non-negative`);
-  string(observation.cost.currency, `${field}.cost.currency`);
-  string(observation.cost.unit, `${field}.cost.unit`);
+  validateCost(observation.cost, `${field}.cost`, isTaxonomyIdentity(observation.workload));
   if (!knownModels.has(identity(observation))) {
     throw new TypeError(`${field} references an unknown model`);
   }
@@ -114,10 +296,5 @@ export function validateEvidenceCatalog(input) {
     }
     observationIds.add(entry.id);
   }
-  return deepFreeze({
-    schemaVersion: EVIDENCE_CATALOG_VERSION,
-    revision,
-    models,
-    observations,
-  });
+  return deepFreeze({ schemaVersion: EVIDENCE_CATALOG_VERSION, revision, models, observations });
 }

package/src/lib/routingDispatchLease.mjs

@@ -0,0 +1,253 @@
+/**
+ * The dispatch lease — the revision-bound window between deciding a route and
+ * spawning the agent that runs it.
+ *
+ * Comparing revisions before and after the handoff is not enough on its own: a
+ * comparison leaves a window between the check and the external task creation in
+ * which an authorization can be revoked, and the dispatch would still spawn. The
+ * lease closes that window from both sides. A dispatch holds it across the whole
+ * handoff, bound to the store-backed snapshot token it read; a writer must
+ * invalidate the lease or wait for it, and a lease whose revisions no longer
+ * match fails the dispatch instead of racing it.
+ *
+ * Four mechanics carry that:
+ *
+ * - **Fencing token.** Every acquisition raises a monotone counter per scope. A
+ *   holder proves itself by its token, so a holder that lost the lease can
+ *   neither continue nor release its successor's.
+ * - **Expiry.** A lease is only live until its deadline. A crashed holder
+ *   therefore cannot block a scope forever.
+ * - **Abandoned-lease recovery.** An expired lease is taken over by the next
+ *   acquirer or by a waiting writer, and the fence bump makes the abandoned
+ *   holder's next check fail rather than letting it spawn late.
+ * - **Writer fairness.** A writer queues for its turn, and while any writer is
+ *   queued no new dispatch may acquire the scope. Writers are served in the
+ *   order they queued, so a stream of dispatches can never starve a revocation.
+ *
+ * The registry is per-process mutual exclusion. What catches a mutation from
+ * *another* process is the revision binding: the lease re-reads the persisted
+ * profile generations, inventory, Access graph and catalog and recomputes the
+ * Routing policy, then compares. Both halves are needed — a cooperating writer
+ * is serialized, an uncoordinated one is detected.
+ */
+import { readAccessGraphDocument } from './routingAccessGraphStore.mjs';
+import { readComposedRoutingProfile } from './routingProfile.mjs';
+import {
+  assertRoutingSnapshotMatches,
+  assertRoutingStoreSnapshotUnchanged,
+  captureRoutingStoreSnapshot,
+} from './routingEvidenceCache.mjs';
+
+export const DISPATCH_LEASE_VERSION = 1;
+export const DEFAULT_DISPATCH_LEASE_TTL_MS = 30_000;
+export const DEFAULT_WRITER_TURN_TIMEOUT_MS = 5_000;
+
+/** The Route decision axes a lease binds: exactly what the decision named. */
+const DECISION_REVISION_FIELDS = Object.freeze(['catalog', 'accessGraph', 'policy']);
+
+const sleepMs = (ms) => new Promise((done) => { setTimeout(done, ms); });
+
+function scopeKey(value, field = 'dispatch lease key') {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+/**
+ * One registry owns the leases of one process. `now` and `ttlMs` are injected so
+ * expiry, recovery and fairness are decidable without waiting for wall time.
+ */
+export function createDispatchLeaseRegistry({
+  now = () => Date.now(),
+  ttlMs = DEFAULT_DISPATCH_LEASE_TTL_MS,
+} = {}) {
+  const scopes = new Map();
+
+  const scopeOf = (key) => {
+    const name = scopeKey(key);
+    if (!scopes.has(name)) {
+      scopes.set(name, { fencingToken: 0, lease: null, writers: [], tickets: 0 });
+    }
+    return scopes.get(name);
+  };
+  /** A lease is live only while it exists and its deadline has not passed. */
+  const live = (scope, at) => (scope.lease && at < scope.lease.expiresAt ? scope.lease : null);
+
+  function acquire({ key, holder = null, ttlMs: leaseTtlMs = ttlMs } = {}) {
+    const scope = scopeOf(key);
+    if (scope.writers.length > 0) {
+      throw new Error(`dispatch lease is reserved for a writer: ${key}`);
+    }
+    const at = now();
+    if (live(scope, at)) throw new Error(`dispatch lease is held: ${key}`);
+    // An expired lease is abandoned: the recovering acquirer fences its holder.
+    scope.fencingToken += 1;
+    scope.lease = {
+      schemaVersion: DISPATCH_LEASE_VERSION,
+      key,
+      holder,
+      fencingToken: scope.fencingToken,
+      acquiredAt: at,
+      expiresAt: at + leaseTtlMs,
+    };
+    return Object.freeze({ ...scope.lease });
+  }
+
+  /** Still ours, still live — or the dispatch fails with what went wrong. */
+  function assertHeld(lease) {
+    const current = scopes.get(lease?.key)?.lease ?? null;
+    if (!current || current.fencingToken !== lease?.fencingToken) {
+      throw new Error(`dispatch lease superseded: ${lease?.key}`);
+    }
+    if (now() >= current.expiresAt) throw new Error(`dispatch lease expired: ${lease.key}`);
+    return true;
+  }
+
+  /** Only the current holder releases; a fenced holder cannot free its successor. */
+  function release(lease) {
+    const scope = scopes.get(lease?.key);
+    if (scope?.lease && scope.lease.fencingToken === lease.fencingToken) scope.lease = null;
+    return true;
+  }
+
+  /** Queue for a write. From here on, no new dispatch may take this scope. */
+  function requestWriterTurn({ key, writerId = null } = {}) {
+    const scope = scopeOf(key);
+    scope.tickets += 1;
+    const ticket = Object.freeze({ key, writerId, sequence: scope.tickets });
+    scope.writers.push(ticket);
+    return ticket;
+  }
+
+  /**
+   * Take the turn if it is this writer's and no live lease is in the way. The
+   * grant invalidates whatever remains of an abandoned lease and raises the
+   * fence, so a stale holder can no longer spawn against the old revisions.
+   */
+  function tryBeginWrite(ticket) {
+    const scope = scopeOf(ticket?.key);
+    const head = scope.writers[0];
+    if (!head || head.sequence !== ticket.sequence) {
+      return Object.freeze({ granted: false, reason: 'writer-not-next' });
+    }
+    if (live(scope, now())) {
+      return Object.freeze({ granted: false, reason: 'dispatch-lease-held' });
+    }
+    scope.lease = null;
+    scope.fencingToken += 1;
+    return Object.freeze({ granted: true, fencingToken: scope.fencingToken });
+  }
+
+  /** Leave the queue, whether the turn was taken or given up. */
+  function endWrite(ticket) {
+    const scope = scopeOf(ticket?.key);
+    scope.writers = scope.writers.filter((queued) => queued.sequence !== ticket.sequence);
+    return true;
+  }
+
+  function inspect(key) {
+    const scope = scopeOf(key);
+    const current = live(scope, now());
+    return Object.freeze({
+      fencingToken: scope.fencingToken,
+      held: Boolean(current),
+      holder: current?.holder ?? null,
+      expiresAt: scope.lease?.expiresAt ?? null,
+      writers: scope.writers.length,
+    });
+  }
+
+  return Object.freeze({
+    acquire, assertHeld, release, requestWriterTurn, tryBeginWrite, endWrite, inspect,
+  });
+}
+
+/**
+ * Wait for a queued writer's turn. The wait is bounded by wall time, so a holder
+ * whose process died mid-dispatch cannot keep a revocation waiting forever; the
+ * timeout names the reason it was still blocked.
+ */
+export async function awaitWriteTurn(registry, ticket, options = {}) {
+  const {
+    timeoutMs = DEFAULT_WRITER_TURN_TIMEOUT_MS,
+    pollMs = 5,
+    sleep = sleepMs,
+    clock = Date.now,
+  } = options;
+  const deadline = clock() + timeoutMs;
+  for (;;) {
+    const attempt = registry.tryBeginWrite(ticket);
+    if (attempt.granted) return attempt;
+    if (clock() >= deadline) {
+      throw new Error(`dispatch lease writer timed out: ${ticket?.key} (${attempt.reason})`);
+    }
+    await sleep(pollMs);
+  }
+}
+
+/**
+ * The snapshot source over the real user-local stores: the committed profile
+ * generations plus the pinned inventory (composed and then derived into a
+ * policy), the stored Access graph, and the Evidence catalog its own reader
+ * supplies. Every `read` goes back to the bytes — nothing is cached across the
+ * handoff, because a cached read cannot see a concurrent writer.
+ */
+export function createPersistedRoutingSnapshot({
+  profileRoot, projectRoot, identity, runGit, loadInventory, inventory,
+  accessGraphFile, readCatalog, policyOptions,
+} = {}) {
+  scopeKey(accessGraphFile, 'persisted routing snapshot accessGraphFile');
+  return Object.freeze({
+    read: () => captureRoutingStoreSnapshot({
+      readProfile: () => readComposedRoutingProfile({
+        profileRoot, projectRoot, identity, runGit, loadInventory, inventory,
+      }),
+      readAccessGraph: () => readAccessGraphDocument(accessGraphFile),
+      readCatalog,
+      policyOptions,
+    }),
+  });
+}
+
+/**
+ * Open the lease for one dispatch: take the scope first, then read the store and
+ * bind the lease to what the Route decision named. A store that already moved
+ * fails here, before an adapter prepares anything, and the scope is released
+ * again — an unopened lease never leaks.
+ */
+export async function openDispatchLease({
+  registry, key, holder = null, ttlMs, snapshot, expected = null,
+}) {
+  if (!registry || typeof registry.acquire !== 'function') {
+    throw new TypeError('a dispatch lease needs a dispatch lease registry');
+  }
+  if (!snapshot || typeof snapshot.read !== 'function') {
+    throw new TypeError('a dispatch lease needs a store-backed snapshot source');
+  }
+  const lease = registry.acquire({ key, holder, ttlMs });
+  try {
+    const token = await snapshot.read();
+    if (expected) assertRoutingSnapshotMatches(expected, token, DECISION_REVISION_FIELDS);
+    registry.assertHeld(lease);
+    return Object.freeze({
+      key: lease.key,
+      holder: lease.holder,
+      fencingToken: lease.fencingToken,
+      expiresAt: lease.expiresAt,
+      token,
+      /** The spawn handoff: re-read, compare, and prove the lease is still ours. */
+      revalidate: async () => {
+        registry.assertHeld(lease);
+        const current = await snapshot.read();
+        assertRoutingStoreSnapshotUnchanged(token, current);
+        registry.assertHeld(lease);
+        return current;
+      },
+      release: () => registry.release(lease),
+    });
+  } catch (error) {
+    registry.release(lease);
+    throw error;
+  }
+}

package/src/lib/routingEvidenceCache.mjs

@@ -1,8 +1,18 @@
 import { validateEvidenceCatalog } from './routingCatalog.mjs';
 import { validateAccessGraph } from './routingAccessGraph.mjs';
 import { validateRoutingPolicy } from './routingPolicy.mjs';
+import { deriveRoutingPolicy } from './routingProfilePolicy.mjs';
 
 export const ROUTING_EVIDENCE_CACHE_VERSION = 1;
+export const ROUTING_STORE_SNAPSHOT_VERSION = 1;
+
+/** Every axis a store-backed snapshot compares, each named by what moved. */
+export const ROUTING_STORE_SNAPSHOT_FIELDS = Object.freeze([
+  'globalGeneration', 'projectGeneration', 'inventoryRevision', 'accessGraph', 'policy', 'catalog',
+]);
+
+const PROFILE_MUTATION = 'concurrent routing profile mutation';
+const CATALOG_MUTATION = 'concurrent evidence catalog mutation';
 
 function object(value, field) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -198,6 +208,74 @@ export function commitRoutingEvidenceCache({
   }, { now: refreshedAt });
 }
 
+function snapshotReader(source, field) {
+  if (typeof source[field] !== 'function') {
+    throw new TypeError(`routing store snapshot ${field} must be a function`);
+  }
+  return source[field];
+}
+
+/**
+ * The store-backed snapshot token: the revisions of the *persisted* routing
+ * inputs, taken by re-reading them. The Routing policy is recomputed from the
+ * generations and the inventory revision just read — a policy is derived and is
+ * never read back from a store — so a revision a caller merely states cannot
+ * authorize a dispatch, which comparing a resolver input with itself would allow.
+ */
+export async function captureRoutingStoreSnapshot(source) {
+  object(source, 'routing store snapshot source');
+  const [readProfile, readAccessGraph, readCatalog] = ['readProfile', 'readAccessGraph',
+    'readCatalog'].map((field) => snapshotReader(source, field));
+  const profile = await readProfile();
+  if (!profile?.global || !profile.composed) {
+    throw new Error('routing profile store carries no committed authorization');
+  }
+  const projectGeneration = profile.project?.generation ?? null;
+  const policy = deriveRoutingPolicy({
+    composed: profile.composed,
+    globalGeneration: profile.global.generation,
+    projectGeneration,
+    ...(source.policyOptions ?? {}),
+  });
+  const accessGraph = await readAccessGraph();
+  const catalog = validateEvidenceCatalog(await readCatalog());
+  return Object.freeze({
+    schemaVersion: ROUTING_STORE_SNAPSHOT_VERSION,
+    globalGeneration: profile.global.generation,
+    projectGeneration,
+    inventoryRevision: profile.composed.rosterState?.inventoryRevision
+      ?? profile.composed.inventoryRevision ?? null,
+    accessGraph: accessGraph?.revision ?? null,
+    policy: policy.revision,
+    catalog: catalog.revision,
+  });
+}
+
+/**
+ * Compare the named axes of two snapshot tokens. A moved axis names itself and
+ * fails the dispatch; the receipt reduces the message to a constant reason, so
+ * the compared values never leave this call.
+ */
+export function assertRoutingSnapshotMatches(expected, actual, fields) {
+  for (const token of [expected, actual]) object(token, 'routing store snapshot');
+  for (const field of fields) {
+    if (expected[field] === actual[field]) continue;
+    throw new Error(`${field === 'catalog' ? CATALOG_MUTATION : PROFILE_MUTATION}: `
+      + `${field} changed from ${expected[field]} to ${actual[field]}`);
+  }
+  return true;
+}
+
+/** The full-axis comparison a held lease runs before it releases the spawn. */
+export function assertRoutingStoreSnapshotUnchanged(before, after) {
+  return assertRoutingSnapshotMatches(before, after, ROUTING_STORE_SNAPSHOT_FIELDS);
+}
+
+/**
+ * The in-process check over one caller's own resolver input. It only sees a
+ * mutation this process made to that object, so it is the degenerate case for a
+ * dispatch without a store-backed lease — never the authority over the store.
+ */
 export function captureRoutingProfileSnapshot({ accessGraph, policy }) {
   const access = validateAccessGraph(accessGraph);
   const routingPolicy = validateRoutingPolicy(policy);