@ikon85/agent-workflow-kit 0.44.2 → 0.45.0

package/src/lib/dispatchReceipt.mjs

@@ -1,29 +1,77 @@
+/**
+ * The Dispatch receipt — the runtime record proving which requested Route
+ * decision was actually applied, by which enforcement mechanism, under which
+ * policy and evidence revisions.
+ *
+ * A receipt has one of four kinds, and each validates its own field set rather
+ * than a union of everything any dispatch could ever carry. `routed-dispatch`
+ * ran the resolved route, applied matching requested field for field, and
+ * `blocked` did not run at all. `inherited-dispatch` ran the session default: it
+ * is a receipt only when it carries the *attested* applied pair and the
+ * session-default enforcement method, because the inherited pair may
+ * legitimately differ from the route that was requested. `handoff` dispatched
+ * nothing and handed the work on, so it records no applied route and no
+ * enforcement and can never read as proof that something ran.
+ *
+ * Every kind names the revisions it decided under (`policyRevision`,
+ * `catalogRevision`, `decisionAccessRevision`) plus the plan-authorization id
+ * it dispatched against; a blocked receipt additionally names
+ * `resultingAccessRevision` when the failure itself mutated the Access graph.
+ */
 export const DISPATCH_RECEIPT_VERSION = 2;
 
-const ROUTE_FIELDS = [
-  'providerId',
-  'modelId',
-  'effort',
-  'surfaceId',
-  'transportId',
-];
+export const DISPATCH_RECEIPT_KINDS = Object.freeze([
+  'routed-dispatch', 'inherited-dispatch', 'handoff', 'blocked',
+]);
 
-const ENFORCEMENT_METHODS = [
-  'per-spawn',
-  'named-agent',
-  'session-default',
-  'none',
-];
+const KIND_STATUS = Object.freeze({
+  'routed-dispatch': 'dispatched',
+  'inherited-dispatch': 'dispatched',
+  handoff: 'handoff',
+  blocked: 'blocked',
+});
+
+/** What a caller that only knows the legacy outcome axis means by its status. */
+const STATUS_KIND = Object.freeze({
+  dispatched: 'routed-dispatch', handoff: 'handoff', blocked: 'blocked',
+});
+
+const ROUTE_FIELDS = ['providerId', 'modelId', 'effort', 'surfaceId', 'transportId'];
+
+const ENFORCEMENT_METHODS = ['per-spawn', 'named-agent', 'session-default', 'none'];
 
 export const DISPATCH_PRECEDENCE = Object.freeze([
-  'explicit-argument',
-  'agent-definition-over-environment',
-  'environment-over-agent-definition',
-  'session-default',
-  'uncontrolled',
-  'unreported',
+  'explicit-argument', 'agent-definition-over-environment',
+  'environment-over-agent-definition', 'session-default', 'uncontrolled', 'unreported',
 ]);
 
+/**
+ * The readback channels that may attest an applied pair, and what each proves
+ * per axis. A channel absent from this table is not an attestation:
+ * `~/.claude/settings.json` reported `medium` for a session that ran at `xhigh`,
+ * so a configured value never attests an applied one. Claude's transcript
+ * returns `message.model` from the server while its top-level `effort` is the
+ * CLI's own record; Codex's `turn_context` is client-written throughout, so a
+ * Codex receipt cannot claim provider attestation.
+ */
+export const APPLIED_PAIR_ATTESTATION_SOURCES = Object.freeze({
+  'session-transcript': Object.freeze({ model: true, effort: false }),
+  'rollout-turn-context': Object.freeze({ model: false, effort: false }),
+});
+
+const COMMON_FIELDS = [
+  'kind', 'status', 'executionId', 'afk', 'revisions', 'authorizationId', 'dispatchedAt',
+];
+const APPLIED_FIELDS = ['requestedRoute', 'appliedRoute', 'enforcement', 'precedence'];
+
+/** The closed field set of each kind — what it may carry, and nothing else. */
+const KIND_FIELDS = Object.freeze({
+  'routed-dispatch': new Set([...COMMON_FIELDS, ...APPLIED_FIELDS]),
+  'inherited-dispatch': new Set([...COMMON_FIELDS, ...APPLIED_FIELDS, 'attestation']),
+  handoff: new Set([...COMMON_FIELDS, 'requestedRoute', 'handoff', 'reason']),
+  blocked: new Set([...COMMON_FIELDS, ...APPLIED_FIELDS, 'reason', 'resultingAccessRevision']),
+});
+
 function object(value, field) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new TypeError(`${field} must be an object`);
@@ -31,6 +79,13 @@ function object(value, field) {
   return value;
 }
 
+function closedFields(value, allowed, message) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) throw new TypeError(`${message}: ${key}`);
+  }
+  return value;
+}
+
 function string(value, field) {
   if (typeof value !== 'string' || value.trim() === '') {
     throw new TypeError(`${field} must be a non-empty string`);
@@ -38,6 +93,8 @@ function string(value, field) {
   return value;
 }
 
+const optionalString = (value, field) => (value == null ? null : string(value, field));
+
 function timestamp(value, field) {
   string(value, field);
   if (!Number.isFinite(Date.parse(value))) throw new TypeError(`${field} must be an ISO timestamp`);
@@ -45,42 +102,31 @@ function timestamp(value, field) {
 }
 
 function route(input, field) {
-  object(input, field);
-  for (const key of Object.keys(input)) {
-    if (!ROUTE_FIELDS.includes(key)) throw new TypeError(`unknown ${field} field: ${key}`);
-  }
+  closedFields(object(input, field), ROUTE_FIELDS, `unknown ${field} field`);
   return Object.freeze(Object.fromEntries(
     ROUTE_FIELDS.map((key) => [key, string(input[key], `${field}.${key}`)]),
   ));
 }
 
-function enforcement(input) {
-  object(input, 'enforcement');
+const optionalRoute = (input, field) => (input == null ? null : route(input, field));
+
+function pair(input, field, allowed) {
+  object(input, field);
   const result = {};
-  for (const field of ['model', 'effort']) {
-    if (!ENFORCEMENT_METHODS.includes(input[field])) {
-      throw new TypeError(`${field} enforcement must be one of: ${ENFORCEMENT_METHODS.join(', ')}`);
+  for (const axis of ['model', 'effort']) {
+    if (!allowed.includes(input[axis])) {
+      throw new TypeError(`${axis} ${field} must be one of: ${allowed.join(', ')}`);
     }
-    result[field] = input[field];
+    result[axis] = input[axis];
   }
   return Object.freeze(result);
 }
 
+const enforcement = (input) => pair(input, 'enforcement', ENFORCEMENT_METHODS);
+
 function precedence(input) {
-  if (input == null) {
-    return Object.freeze({ model: 'unreported', effort: 'unreported' });
-  }
-  object(input, 'precedence');
-  const result = {};
-  for (const field of ['model', 'effort']) {
-    if (!DISPATCH_PRECEDENCE.includes(input[field])) {
-      throw new TypeError(
-        `${field} precedence must be one of: ${DISPATCH_PRECEDENCE.join(', ')}`,
-      );
-    }
-    result[field] = input[field];
-  }
-  return Object.freeze(result);
+  if (input == null) return Object.freeze({ model: 'unreported', effort: 'unreported' });
+  return pair(input, 'precedence', DISPATCH_PRECEDENCE);
 }
 
 function revisions(input) {
@@ -92,42 +138,84 @@ function revisions(input) {
   });
 }
 
-function blockedReceipt(input) {
-  const requestedRoute = input.requestedRoute == null
-    ? null
-    : route(input.requestedRoute, 'requestedRoute');
-  const appliedRoute = input.appliedRoute == null
-    ? null
-    : route(input.appliedRoute, 'appliedRoute');
-  if (appliedRoute !== null && requestedRoute === null) {
-    throw new TypeError('blocked applied route requires a requested route');
+/** The kind a caller asked for, or the one its legacy status still implies. */
+function receiptKind(input) {
+  if (input.kind == null) {
+    const derived = STATUS_KIND[input.status];
+    if (derived) return derived;
+    throw new TypeError(
+      `dispatch receipt needs a kind, or a status of: ${Object.keys(STATUS_KIND).join(', ')}`,
+    );
   }
-  const appliedEnforcement = input.enforcement == null ? null : enforcement(input.enforcement);
-  const appliedPrecedence = input.precedence == null ? null : precedence(input.precedence);
-  if (appliedRoute !== null && (appliedEnforcement === null || appliedPrecedence === null)) {
-    throw new TypeError('blocked applied route requires enforcement and precedence');
+  if (!DISPATCH_RECEIPT_KINDS.includes(input.kind)) {
+    throw new TypeError(
+      `dispatch receipt kind must be one of: ${DISPATCH_RECEIPT_KINDS.join(', ')}`,
+    );
   }
-  return Object.freeze({
+  if (input.status != null && input.status !== KIND_STATUS[input.kind]) {
+    throw new TypeError(`${input.kind} receipt status must be ${KIND_STATUS[input.kind]}`);
+  }
+  return input.kind;
+}
+
+/**
+ * `resultingAccessRevision` is the Access-graph revision *after* a failure
+ * mutated the graph, so it belongs to a blocked receipt and must differ from the
+ * decision's own — repeating that one names a mutation that never happened.
+ */
+function namedRevisions(input, kind, decided) {
+  const resulting = optionalString(input.resultingAccessRevision, 'resultingAccessRevision');
+  if (resulting !== null && resulting === decided.accessGraph) {
+    throw new TypeError('resultingAccessRevision names no access graph mutation');
+  }
+  return {
+    catalogRevision: decided.catalog,
+    decisionAccessRevision: decided.accessGraph,
+    policyRevision: decided.policy,
+    resultingAccessRevision: kind === 'blocked' ? resulting : null,
+  };
+}
+
+function baseReceipt(input, kind) {
+  const decided = revisions(input.revisions);
+  return {
     schemaVersion: DISPATCH_RECEIPT_VERSION,
+    kind,
     executionId: string(input.executionId, 'executionId'),
-    status: 'blocked',
+    status: KIND_STATUS[kind],
     afk: input.afk === true,
-    requestedRoute,
-    appliedRoute,
-    enforcement: appliedEnforcement,
-    precedence: appliedPrecedence,
-    revisions: revisions(input.revisions),
+    requestedRoute: null, appliedRoute: null, enforcement: null, precedence: null,
+    attestation: null, handoff: null,
+    revisions: decided,
+    ...namedRevisions(input, kind, decided),
+    authorizationId: optionalString(input.authorizationId, 'authorizationId'),
     dispatchedAt: timestamp(input.dispatchedAt, 'dispatchedAt'),
-    reason: string(input.reason, 'reason'),
-  });
+    reason: null,
+  };
 }
 
-export function createDispatchReceipt(input) {
-  object(input, 'dispatch receipt');
-  if (input.status === 'blocked') return blockedReceipt(input);
-  if (input.status !== 'dispatched') {
-    throw new TypeError('dispatch receipt status must be dispatched or blocked');
+/** The attested applied pair: which channel read it back, and what that proves. */
+function appliedPairAttestation(input, appliedRoute) {
+  if (input == null) throw new TypeError('inherited dispatch requires an attested applied pair');
+  const sources = Object.keys(APPLIED_PAIR_ATTESTATION_SOURCES);
+  closedFields(object(input, 'attestation'),
+    ['source', 'model', 'effort', 'observedAt'], 'unknown attestation field');
+  if (!sources.includes(input.source)) {
+    throw new TypeError(`attestation source must be one of: ${sources.join(', ')}`);
+  }
+  const model = string(input.model, 'attestation.model');
+  const effort = string(input.effort, 'attestation.effort');
+  if (model !== appliedRoute.modelId || effort !== appliedRoute.effort) {
+    throw new Error('attested applied pair differs from the applied route');
   }
+  return Object.freeze({
+    source: input.source, model, effort,
+    observedAt: timestamp(input.observedAt, 'attestation.observedAt'),
+    providerAttested: APPLIED_PAIR_ATTESTATION_SOURCES[input.source],
+  });
+}
+
+function routedDispatch(input, base) {
   const requestedRoute = route(input.requestedRoute, 'requestedRoute');
   const appliedRoute = route(input.appliedRoute, 'appliedRoute');
   for (const field of ROUTE_FIELDS) {
@@ -135,28 +223,77 @@ export function createDispatchReceipt(input) {
       throw new Error(`applied route differs from requested route: ${field}`);
     }
   }
-  const appliedEnforcement = enforcement(input.enforcement);
-  const appliedPrecedence = precedence(input.precedence);
-  if (input.afk === true
-      && (appliedEnforcement.model === 'none' || appliedEnforcement.effort === 'none')) {
+  const applied = enforcement(input.enforcement);
+  const order = precedence(input.precedence);
+  if (base.afk && (applied.model === 'none' || applied.effort === 'none')) {
     throw new Error('AFK dispatch requires enforced model and effort selection');
   }
-  if (input.afk === true
-      && Object.values(appliedPrecedence).some((value) =>
-        value === 'uncontrolled' || value === 'unreported')) {
+  if (base.afk && Object.values(order).some((value) =>
+    value === 'uncontrolled' || value === 'unreported')) {
     throw new Error('AFK dispatch requires verified environment precedence');
   }
-  return Object.freeze({
-    schemaVersion: DISPATCH_RECEIPT_VERSION,
-    executionId: string(input.executionId, 'executionId'),
-    status: 'dispatched',
-    afk: input.afk === true,
-    requestedRoute,
+  return { ...base, requestedRoute, appliedRoute, enforcement: applied, precedence: order };
+}
+
+/**
+ * Inheritance is the constrained non-AFK path: the applied pair is whatever the
+ * session already runs, so it proves nothing without its attestation.
+ */
+function inheritedDispatch(input, base) {
+  const appliedRoute = route(input.appliedRoute, 'appliedRoute');
+  const applied = enforcement(input.enforcement);
+  if (applied.model !== 'session-default' || applied.effort !== 'session-default') {
+    throw new TypeError('inherited dispatch requires the session-default enforcement method');
+  }
+  if (base.afk) throw new Error('AFK dispatch cannot inherit a session default');
+  return {
+    ...base,
+    requestedRoute: optionalRoute(input.requestedRoute, 'requestedRoute'),
     appliedRoute,
-    enforcement: appliedEnforcement,
-    precedence: appliedPrecedence,
-    revisions: revisions(input.revisions),
-    dispatchedAt: timestamp(input.dispatchedAt, 'dispatchedAt'),
-    reason: null,
-  });
+    enforcement: applied,
+    precedence: precedence(input.precedence),
+    attestation: appliedPairAttestation(input.attestation, appliedRoute),
+  };
+}
+
+function handoffReceipt(input, base) {
+  const target = closedFields(object(input.handoff, 'handoff'), ['to'], 'unknown handoff field');
+  return {
+    ...base,
+    requestedRoute: optionalRoute(input.requestedRoute, 'requestedRoute'),
+    handoff: Object.freeze({ to: string(target.to, 'handoff.to') }),
+    reason: string(input.reason, 'reason'),
+  };
+}
+
+function blockedReceipt(input, base) {
+  const requestedRoute = optionalRoute(input.requestedRoute, 'requestedRoute');
+  const appliedRoute = optionalRoute(input.appliedRoute, 'appliedRoute');
+  if (appliedRoute !== null && requestedRoute === null) {
+    throw new TypeError('blocked applied route requires a requested route');
+  }
+  const applied = input.enforcement == null ? null : enforcement(input.enforcement);
+  const order = input.precedence == null ? null : precedence(input.precedence);
+  if (appliedRoute !== null && (applied === null || order === null)) {
+    throw new TypeError('blocked applied route requires enforcement and precedence');
+  }
+  return {
+    ...base,
+    requestedRoute, appliedRoute, enforcement: applied, precedence: order,
+    reason: string(input.reason, 'reason'),
+  };
+}
+
+const BUILDERS = Object.freeze({
+  'routed-dispatch': routedDispatch,
+  'inherited-dispatch': inheritedDispatch,
+  handoff: handoffReceipt,
+  blocked: blockedReceipt,
+});
+
+export function createDispatchReceipt(input) {
+  object(input, 'dispatch receipt');
+  const kind = receiptKind(input);
+  closedFields(input, [...KIND_FIELDS[kind]], `unknown ${kind} receipt field`);
+  return Object.freeze(BUILDERS[kind](input, baseReceipt(input, kind)));
 }

package/src/lib/frontendWorkloads.mjs

@@ -2,46 +2,47 @@ import {
   evidenceWorkloadIdentity,
   validateEvidenceSelection,
 } from './routingIntent.mjs';
+import {
+  FRONTEND_QUALITY_AXES,
+  evidenceDomainsFor,
+  evidenceIdentity,
+  evidenceSourceClaim,
+} from './routingCatalog.mjs';
 
-const FRONTEND_DOMAINS = new Set([
-  'general',
-  'reference-design',
-  'marketing',
-  'analytics',
-  'product',
-  'game',
-  'simulation',
-  'editor',
+// The frontend vocabulary is a strict subset of the researched taxonomy
+// (docs/research/agent-task-taxonomy-benchmark-coverage.md §1.1): it reads its
+// domains and quality axes from the catalog rather than restating them.
+const FRONTEND_WORKLOADS = Object.freeze([
+  'frontend-greenfield',
+  'frontend-repository-repair',
 ]);
+const FRONTEND_DOMAINS = new Set(evidenceDomainsFor(FRONTEND_WORKLOADS[0]));
+const QUALITY_AXES = new Set(FRONTEND_QUALITY_AXES);
 
-const QUALITY_AXES = new Set([
-  'visual-preference',
-  'visual-fidelity',
-  'functional',
-  'accessibility',
-  'responsive',
-]);
+// Each source carries the three-part decisiveness test instead of a boolean, so
+// a collapsed dimension is named rather than hidden (§4).
+const frontendClaim = (sourceId, { workloads, axes }) => Object.freeze({
+  workloads: Object.freeze(workloads),
+  axes: Object.freeze(axes),
+  ...evidenceSourceClaim(sourceId),
+});
 
 export const FRONTEND_SOURCE_CLAIMS = Object.freeze({
-  'code-arena-webdev': Object.freeze({
-    workloads: Object.freeze(['frontend-greenfield']),
-    axes: Object.freeze(['visual-preference']),
-    decisive: true,
+  'code-arena-webdev': frontendClaim('code-arena-webdev', {
+    workloads: ['frontend-greenfield'],
+    axes: ['visual-preference'],
   }),
-  'openhands-frontend': Object.freeze({
-    workloads: Object.freeze(['frontend-repository-repair']),
-    axes: Object.freeze(['functional']),
-    decisive: true,
+  'openhands-frontend': frontendClaim('openhands-frontend', {
+    workloads: ['frontend-repository-repair'],
+    axes: ['functional'],
   }),
-  vision2web: Object.freeze({
-    workloads: Object.freeze(['frontend-greenfield']),
-    axes: Object.freeze(['visual-fidelity', 'functional', 'responsive']),
-    decisive: false,
+  vision2web: frontendClaim('vision2web', {
+    workloads: ['frontend-greenfield'],
+    axes: ['visual-fidelity', 'functional', 'responsive'],
   }),
-  design2code: Object.freeze({
-    workloads: Object.freeze(['frontend-greenfield']),
-    axes: Object.freeze(['visual-fidelity']),
-    decisive: false,
+  design2code: frontendClaim('design2code', {
+    workloads: ['frontend-greenfield'],
+    axes: ['visual-fidelity'],
   }),
 });
 
@@ -111,13 +112,14 @@ export function classifyFrontendWorkload(input) {
 }
 
 export function frontendEvidenceWorkload({ workload, frontendDomain = 'general', axis }) {
-  if (!['frontend-greenfield', 'frontend-repository-repair'].includes(workload)) {
+  if (!FRONTEND_WORKLOADS.includes(workload)) {
     throw new TypeError(`unknown frontend evidence workload: ${workload}`);
   }
   if (!FRONTEND_DOMAINS.has(frontendDomain)) {
     throw new TypeError(`unknown frontend domain: ${frontendDomain}`);
   }
   if (!QUALITY_AXES.has(axis)) throw new TypeError(`unknown frontend quality axis: ${axis}`);
+  evidenceIdentity({ workload, domain: frontendDomain, axis });
   return evidenceWorkloadIdentity({
     workload,
     domain: frontendDomain,