codex-workflow-v2 2.0.0-beta.12.9 → 2.0.0-beta.13

package/dist/src/observed-routes.d.ts

@@ -0,0 +1,114 @@
+import type { WorkflowService } from './workflow.js';
+import { type CliCommand } from './cli-actions.js';
+export declare const OBSERVED_ROUTE_MATRIX_VERSION: 2;
+export type ObservedRouteId = 'observed.observation-blocked' | 'observed.observation-repair' | 'observed.adoption' | 'observed.dependency-recovery' | 'observed.corrective-continuation' | 'observed.worker-authority' | 'observed.step-execution' | 'observed.strict-review' | 'observed.task-lifecycle' | 'observed.project-knowledge' | 'observed.discovery-remediation' | 'observed.milestone-lifecycle' | 'observed.manual-boundary';
+type ExecutorRef = Extract<keyof WorkflowService, string>;
+type InventorySupport = 'executable' | 'diagnostic' | 'unsupported';
+type Support = 'executable-witnessed' | 'unwitnessed' | 'unsupported';
+export interface ObservedActionBinding {
+    action: string;
+    support: InventorySupport;
+    cliBinding: CliCommand | null;
+    executorRefs: readonly ExecutorRef[];
+}
+export interface ObservedRouteDefinition {
+    routeId: ObservedRouteId;
+    priority: number;
+    predicateRef: string;
+    actions: readonly ObservedActionBinding[];
+    successorWitness: {
+        kind: 'reachable';
+        routeIds: readonly ObservedRouteId[];
+        evidence: string;
+    } | {
+        kind: 'terminal';
+        evidence: string;
+    };
+}
+export interface ObservedTransitionWitnessContract {
+    action: CliCommand;
+    executorRef: ExecutorRef;
+    successorActions: readonly string[];
+}
+export type ObservedRouteClassWitnessContract = {
+    routeId: ObservedRouteId;
+    action: CliCommand;
+    kind: 'transition';
+    executorRef: ExecutorRef;
+    successorActions: readonly string[];
+} | {
+    routeId: ObservedRouteId;
+    action: string;
+    kind: 'terminal';
+    executorRef: null;
+    successorActions: readonly [];
+};
+/**
+ * These are the only executable route claims in beta.13. The release E2E must
+ * execute every row as fresh next -> named WorkflowService method -> fresh next.
+ */
+export declare const OBSERVED_ROUTE_WITNESS_CONTRACTS: readonly ObservedTransitionWitnessContract[];
+/**
+ * B13-A14 is a class-level claim, not a claim that every known action has an
+ * executable E2E. Each Signal-observed class has exactly one production
+ * transition witness or one real terminal observation. Other known actions
+ * remain explicit in OBSERVED_UNWITNESSED_ACTIONS/OBSERVED_UNSUPPORTED_ACTIONS.
+ */
+export declare const OBSERVED_ROUTE_CLASS_WITNESS_CONTRACTS: readonly ObservedRouteClassWitnessContract[];
+/** Claimed route classes only; action-level coverage remains explicitly bounded below. */
+export declare const OBSERVED_ROUTE_MATRIX: readonly ObservedRouteDefinition[];
+export declare const OBSERVED_UNWITNESSED_ACTIONS: {
+    action: string;
+    routeId: ObservedRouteId;
+    reason: string;
+}[];
+export declare const OBSERVED_UNSUPPORTED_ACTIONS: {
+    action: string;
+    routeId: ObservedRouteId;
+    reason: string;
+}[];
+export declare const OBSERVED_ROUTE_MATRIX_FINGERPRINT: string;
+export interface ObservedRouteMetadata {
+    matrixVersion: typeof OBSERVED_ROUTE_MATRIX_VERSION;
+    matrixFingerprint: string;
+    routeId: ObservedRouteId;
+    priority: number;
+    predicateRef: string;
+    routeFingerprint: string;
+    actionSupport: Support;
+    cliBinding: CliCommand | null;
+    executorRefs: readonly ExecutorRef[];
+    successorWitness: ObservedRouteDefinition['successorWitness'] | {
+        kind: 'unwitnessed';
+        evidence: string;
+    };
+    coverageBoundary: 'signal-observed-route-class-witnesses';
+}
+export declare function validateObservedRouteMatrix(): void;
+export declare function observedRouteMetadataForAction(action: string): ObservedRouteMetadata;
+export declare function verifyObservedRouteTransitionWitness(input: {
+    before: Record<string, unknown>;
+    executorRef: ExecutorRef;
+    after: Record<string, unknown>;
+}): {
+    action: string;
+    successorAction: string;
+    witnessFingerprint: string;
+};
+export declare function verifyObservedRouteClassTransitionWitness(input: {
+    before: Record<string, unknown>;
+    executorRef: ExecutorRef;
+    after: Record<string, unknown>;
+}): {
+    routeId: ObservedRouteId;
+    action: string;
+    successorAction: string;
+    witnessFingerprint: string;
+};
+export declare function verifyObservedRouteTerminalWitness(next: Record<string, unknown>): {
+    routeId: ObservedRouteId;
+    action: string;
+    witnessFingerprint: string;
+};
+export declare function withObservedRouteMetadata(next: Record<string, unknown>): Record<string, unknown>;
+export {};

package/dist/src/observed-routes.js

@@ -0,0 +1,545 @@
+import { WorkflowError } from './errors.js';
+import { isCliCommand } from './cli-actions.js';
+import { hashCanonical } from './lifecycle/fingerprint.js';
+export const OBSERVED_ROUTE_MATRIX_VERSION = 2;
+const executable = (action, ...executorRefs) => ({ action, support: 'executable', cliBinding: action, executorRefs });
+const diagnostic = (action) => ({ action, support: 'diagnostic', cliBinding: action, executorRefs: [] });
+const unsupported = (action) => ({ action, support: 'unsupported', cliBinding: null, executorRefs: [] });
+/** Signal-observed inventory only; entries are not release claims without an executable witness. */
+const OBSERVED_ROUTE_INVENTORY = [
+    {
+        routeId: 'observed.observation-blocked', priority: 1300,
+        predicateRef: 'WorkflowService.next/status.observation.kind=blocked',
+        actions: [unsupported('blocked')],
+        successorWitness: { kind: 'terminal', evidence: 'No safe Core transition is advertised.' },
+    },
+    {
+        routeId: 'observed.observation-repair', priority: 1200,
+        predicateRef: 'WorkflowService.next/status.observation.kind=repair',
+        actions: [
+            executable('milestone recover', 'recoverMilestoneTransactions'),
+            executable('locks repair', 'repairStaleWriterLease'),
+            executable('task corrective-replan-recover', 'recoverCorrectiveReplan'),
+            executable('task corrective-yield-recover', 'recoverCorrectiveYield'),
+        ],
+        successorWitness: {
+            kind: 'reachable', routeIds: ['observed.dependency-recovery', 'observed.task-lifecycle'],
+            evidence: 'Successful scoped repair is followed by fresh next.',
+        },
+    },
+    {
+        routeId: 'observed.adoption', priority: 1100,
+        predicateRef: 'WorkflowService.next/status.adoption.status!=applied',
+        actions: [
+            executable('state adoption-apply', 'applyAdoption'),
+            unsupported('restore safe boundary, then state adoption-prepare'),
+        ],
+        successorWitness: {
+            kind: 'reachable', routeIds: ['observed.project-knowledge'],
+            evidence: 'Applied adoption exposes Project Knowledge posture.',
+        },
+    },
+    {
+        routeId: 'observed.dependency-recovery', priority: 1000,
+        predicateRef: 'WorkflowService.next/dependency recovery preflights',
+        actions: [
+            executable('task historical-step-provenance-recover', 'recoverHistoricalStepProvenance'),
+            executable('update historical-step-dependency-recover', 'recoverHistoricalStepDependencyProvenance'),
+            executable('update plan-integrity-dependency-recover', 'recoverPlanIntegrityDependencyProvenance'),
+            executable('update dependency-provenance-recover', 'recoverDependencyProvenance'),
+            executable('update downstream-proof-dependency-recover', 'recoverActiveDownstreamProofDependencyProvenance'),
+            executable('update downstream-proof-replan-dependency-recover', 'recoverDownstreamProofReplanDependencyProvenance'),
+        ],
+        successorWitness: {
+            kind: 'reachable', routeIds: ['observed.corrective-continuation'],
+            evidence: 'Compatibility recovery preserves the Task and requires fresh next.',
+        },
+    },
+    {
+        routeId: 'observed.corrective-continuation', priority: 900,
+        predicateRef: 'WorkflowService.nextForTaskWithDelegation/corrective overlays',
+        actions: [
+            executable('task downstream-proof-replan-recover', 'recoverDownstreamProofReplan'),
+            executable('task plan-integrity-recover', 'recoverPlanIntegrity'),
+            executable('task remediation-mode-recover', 'recoverRemediationMode'),
+            executable('task corrective-decision-recover', 'recoverStepCorrectiveDecision'),
+            executable('task downstream-proof-recover', 'recoverDownstreamProof'),
+            executable('task corrective-decision', 'recordStepCorrectiveDecision'),
+            executable('task corrective-yield', 'executeCorrectiveYield'),
+            executable('task corrective-replan-prepare', 'prepareCorrectiveReplan'),
+            executable('task stop-override-prepare', 'prepareTaskStopOverride'),
+        ],
+        successorWitness: {
+            kind: 'reachable', routeIds: ['observed.task-lifecycle'],
+            evidence: 'Signal recovery replays reached replacement planning or Task continuation.',
+        },
+    },
+    {
+        routeId: 'observed.worker-authority', priority: 800,
+        predicateRef: 'WorkflowService.nextForTaskWithDelegation/C1 and credential overlays',
+        actions: [
+            executable('task handoff-prepare', 'handoffTask'),
+            executable('task handoff-replace', 'handoffTask'),
+            executable('task claim', 'claimTask'),
+            executable('task writer-credential-replace', 'replaceClaimedWriterCredential'),
+        ],
+        successorWitness: {
+            kind: 'reachable', routeIds: ['observed.step-execution'],
+            evidence: 'Usable claimed writer authority makes the Step executable.',
+        },
+    },
+    {
+        routeId: 'observed.step-execution', priority: 700,
+        predicateRef: 'nextForTask/active or runnable Step',
+        actions: [executable('task run', 'runStep'), executable('task step-complete', 'completeStep')],
+        successorWitness: {
+            kind: 'reachable', routeIds: ['observed.strict-review'],
+            evidence: 'Completion reaches strict review when required, otherwise Task lifecycle.',
+        },
+    },
+    {
+        routeId: 'observed.strict-review', priority: 600,
+        predicateRef: 'WorkflowService.nextForTaskWithDelegation/strict review overlays',
+        actions: [
+            executable('task step-review', 'reviewStep'),
+            executable('task review-launch', 'recordReview'),
+        ],
+        successorWitness: {
+            kind: 'reachable', routeIds: ['observed.task-lifecycle'],
+            evidence: 'Approval advances; findings return the same Task through corrective routing.',
+        },
+    },
+    {
+        routeId: 'observed.task-lifecycle', priority: 500,
+        predicateRef: 'nextForTask/task.status',
+        actions: [
+            executable('task plan-set', 'setTaskPlan'),
+            executable('task plan-risk-audit', 'recordPlanRiskAudit'),
+            executable('task authorize', 'authorizeTask'),
+            executable('task start', 'startTask'),
+            executable('task submit', 'submitTask'),
+            executable('task result-set', 'setTaskResult'),
+            executable('task accept', 'acceptTask'),
+            executable('task sync-base', 'syncTaskBase'),
+            executable('task merge', 'mergeTask'),
+            executable('task merge-confirm', 'confirmExternalMerge'),
+        ],
+        successorWitness: {
+            kind: 'reachable', routeIds: ['observed.milestone-lifecycle'],
+            evidence: 'A merged Task is consumed by Milestone dependency/progress navigation.',
+        },
+    },
+    {
+        routeId: 'observed.project-knowledge', priority: 400,
+        predicateRef: 'WorkflowService.next/Project Knowledge posture',
+        actions: [
+            executable('project-memory scan', 'scanKnowledgeMap'),
+            executable('project-memory reconcile', 'reconcileKnowledgeMap'),
+            executable('project-memory approve', 'approveKnowledgeMap'),
+            executable('task context-refresh', 'refreshTaskContext'),
+            executable('task knowledge-rebind', 'rebindTaskKnowledge'),
+        ],
+        successorWitness: {
+            kind: 'reachable', routeIds: ['observed.discovery-remediation'],
+            evidence: 'Current approved knowledge permits Discovery or bound-Task navigation.',
+        },
+    },
+    {
+        routeId: 'observed.discovery-remediation', priority: 300,
+        predicateRef: 'WorkflowService.next/active Discovery or audited remediation',
+        actions: [
+            executable('discovery start', 'startDiscovery'),
+            executable('discovery update', 'updateDiscovery'),
+            executable('discovery materialize', 'materializeTask', 'materializeMilestone'),
+            executable('milestone remediation-materialize', 'materializeAuditedRemediationTask'),
+        ],
+        successorWitness: {
+            kind: 'reachable', routeIds: ['observed.task-lifecycle'],
+            evidence: 'Materialization creates an entity selected by fresh next.',
+        },
+    },
+    {
+        routeId: 'observed.milestone-lifecycle', priority: 200,
+        predicateRef: 'WorkflowService.next/active Milestone status',
+        actions: [
+            executable('milestone plan-set', 'setMilestonePlan'),
+            executable('milestone authorize', 'authorizeMilestone'),
+            executable('milestone validate', 'validateMilestone'),
+        ],
+        successorWitness: {
+            kind: 'reachable', routeIds: ['observed.manual-boundary'],
+            evidence: 'Validation reaches the explicit final acceptance boundary.',
+        },
+    },
+    {
+        routeId: 'observed.manual-boundary', priority: 100,
+        predicateRef: 'WorkflowService.next/non-executable instruction',
+        actions: [
+            diagnostic('doctor'),
+            unsupported('milestone initial-assembly'),
+            unsupported('restore clean base, then milestone validate'),
+            unsupported('milestone accept using delegated approval or await explicit human final acceptance'),
+            unsupported('await explicit human final acceptance'),
+            unsupported('complete required Tasks, then milestone validate'),
+            unsupported('milestone plan-set or milestone cancel'),
+            unsupported('none'),
+        ],
+        successorWitness: { kind: 'terminal', evidence: 'Automation stops or reads structured options.' },
+    },
+];
+/**
+ * These are the only executable route claims in beta.13. The release E2E must
+ * execute every row as fresh next -> named WorkflowService method -> fresh next.
+ */
+export const OBSERVED_ROUTE_WITNESS_CONTRACTS = [
+    { action: 'milestone recover', executorRef: 'recoverMilestoneTransactions', successorActions: ['milestone authorize'] },
+    { action: 'state adoption-apply', executorRef: 'applyAdoption', successorActions: ['discovery start'] },
+    { action: 'task historical-step-provenance-recover', executorRef: 'recoverHistoricalStepProvenance', successorActions: ['task step-complete'] },
+    { action: 'task plan-integrity-recover', executorRef: 'recoverPlanIntegrity', successorActions: ['task run'] },
+    { action: 'project-memory reconcile', executorRef: 'reconcileKnowledgeMap', successorActions: ['project-memory approve'] },
+    { action: 'milestone authorize', executorRef: 'authorizeMilestone', successorActions: ['task plan-set'] },
+    { action: 'discovery start', executorRef: 'startDiscovery', successorActions: ['discovery update'] },
+    { action: 'discovery update', executorRef: 'updateDiscovery', successorActions: ['discovery materialize'] },
+    { action: 'discovery materialize', executorRef: 'materializeTask', successorActions: ['task plan-set'] },
+    { action: 'task plan-set', executorRef: 'setTaskPlan', successorActions: ['task plan-risk-audit'] },
+    { action: 'task plan-risk-audit', executorRef: 'recordPlanRiskAudit', successorActions: ['task authorize'] },
+    { action: 'task authorize', executorRef: 'authorizeTask', successorActions: ['task start'] },
+    { action: 'task start', executorRef: 'startTask', successorActions: ['task run'] },
+    { action: 'task run', executorRef: 'runStep', successorActions: ['task step-complete'] },
+    { action: 'task step-complete', executorRef: 'completeStep', successorActions: ['task submit'] },
+    { action: 'task submit', executorRef: 'submitTask', successorActions: ['task review-launch'] },
+    { action: 'task review-launch', executorRef: 'recordReview', successorActions: ['task result-set'] },
+    { action: 'task result-set', executorRef: 'setTaskResult', successorActions: ['task accept'] },
+    { action: 'task accept', executorRef: 'acceptTask', successorActions: ['task writer-credential-replace'] },
+    { action: 'task writer-credential-replace', executorRef: 'replaceClaimedWriterCredential', successorActions: ['task merge'] },
+    { action: 'task merge', executorRef: 'mergeTask', successorActions: ['none', 'discovery start'] },
+];
+/**
+ * B13-A14 is a class-level claim, not a claim that every known action has an
+ * executable E2E. Each Signal-observed class has exactly one production
+ * transition witness or one real terminal observation. Other known actions
+ * remain explicit in OBSERVED_UNWITNESSED_ACTIONS/OBSERVED_UNSUPPORTED_ACTIONS.
+ */
+export const OBSERVED_ROUTE_CLASS_WITNESS_CONTRACTS = [
+    {
+        routeId: 'observed.observation-blocked', action: 'blocked', kind: 'terminal',
+        executorRef: null, successorActions: [],
+    },
+    {
+        routeId: 'observed.observation-repair', action: 'milestone recover', kind: 'transition',
+        executorRef: 'recoverMilestoneTransactions', successorActions: ['milestone authorize'],
+    },
+    {
+        routeId: 'observed.adoption', action: 'state adoption-apply', kind: 'transition',
+        executorRef: 'applyAdoption', successorActions: ['discovery start'],
+    },
+    {
+        routeId: 'observed.dependency-recovery', action: 'task historical-step-provenance-recover', kind: 'transition',
+        executorRef: 'recoverHistoricalStepProvenance', successorActions: ['task step-complete'],
+    },
+    {
+        routeId: 'observed.corrective-continuation', action: 'task plan-integrity-recover', kind: 'transition',
+        executorRef: 'recoverPlanIntegrity', successorActions: ['task run'],
+    },
+    {
+        routeId: 'observed.worker-authority', action: 'task writer-credential-replace', kind: 'transition',
+        executorRef: 'replaceClaimedWriterCredential', successorActions: ['task merge'],
+    },
+    {
+        routeId: 'observed.step-execution', action: 'task run', kind: 'transition',
+        executorRef: 'runStep', successorActions: ['task step-complete'],
+    },
+    {
+        routeId: 'observed.strict-review', action: 'task review-launch', kind: 'transition',
+        executorRef: 'recordReview', successorActions: ['task result-set'],
+    },
+    {
+        routeId: 'observed.task-lifecycle', action: 'task plan-set', kind: 'transition',
+        executorRef: 'setTaskPlan', successorActions: ['task plan-risk-audit'],
+    },
+    {
+        routeId: 'observed.project-knowledge', action: 'project-memory reconcile', kind: 'transition',
+        executorRef: 'reconcileKnowledgeMap', successorActions: ['project-memory approve'],
+    },
+    {
+        routeId: 'observed.discovery-remediation', action: 'discovery start', kind: 'transition',
+        executorRef: 'startDiscovery', successorActions: ['discovery update'],
+    },
+    {
+        routeId: 'observed.milestone-lifecycle', action: 'milestone authorize', kind: 'transition',
+        executorRef: 'authorizeMilestone', successorActions: ['task plan-set'],
+    },
+    {
+        routeId: 'observed.manual-boundary', action: 'milestone initial-assembly', kind: 'terminal',
+        executorRef: null, successorActions: [],
+    },
+];
+const WITNESS_CONTRACT_BY_ACTION = new Map(OBSERVED_ROUTE_WITNESS_CONTRACTS.map((contract) => [contract.action, contract]));
+const CLASS_WITNESS_BY_ROUTE = new Map(OBSERVED_ROUTE_CLASS_WITNESS_CONTRACTS.map((contract) => [contract.routeId, contract]));
+function inventoryRouteIdForAction(action) {
+    return OBSERVED_ROUTE_INVENTORY.find((route) => route.actions.some((binding) => binding.action === action))?.routeId;
+}
+/** Claimed route classes only; action-level coverage remains explicitly bounded below. */
+export const OBSERVED_ROUTE_MATRIX = OBSERVED_ROUTE_INVENTORY
+    .map((route) => {
+    const classWitness = CLASS_WITNESS_BY_ROUTE.get(route.routeId);
+    return {
+        ...route,
+        predicateRef: `WorkflowService.next.action===${JSON.stringify(classWitness?.action)}`,
+        actions: route.actions.filter((binding) => binding.action === classWitness?.action),
+        successorWitness: classWitness?.kind === 'terminal'
+            ? {
+                kind: 'terminal',
+                evidence: 'Fresh production next returned the exact non-executable terminal observation.',
+            }
+            : {
+                kind: 'reachable',
+                routeIds: [...new Set(classWitness?.successorActions
+                        .map((action) => inventoryRouteIdForAction(action))
+                        .filter((routeId) => Boolean(routeId)) ?? [])],
+                evidence: classWitness
+                    ? `Fresh production next -> WorkflowService.${classWitness.executorRef} -> fresh production next.`
+                    : 'Missing class witness.',
+            },
+    };
+})
+    .filter((route) => route.actions.length > 0);
+export const OBSERVED_UNWITNESSED_ACTIONS = OBSERVED_ROUTE_INVENTORY.flatMap((route) => route.actions
+    .filter((binding) => binding.support !== 'unsupported' && !WITNESS_CONTRACT_BY_ACTION.has(binding.action))
+    .map((binding) => ({
+    action: binding.action,
+    routeId: route.routeId,
+    reason: 'Known Signal-observed route has no executable next/executor/successor witness in beta.13.',
+})));
+export const OBSERVED_UNSUPPORTED_ACTIONS = OBSERVED_ROUTE_INVENTORY.flatMap((route) => route.actions.filter((binding) => binding.support === 'unsupported').map((binding) => ({
+    action: binding.action,
+    routeId: route.routeId,
+    reason: binding.action === 'blocked'
+        ? 'No safe Core transition is advertised for this observation.'
+        : binding.action === 'milestone initial-assembly'
+            ? 'This is an option-bearing navigation node, not a CLI command.'
+            : 'This is a manual instruction or terminal marker, not one executable CLI binding.',
+})));
+export const OBSERVED_ROUTE_MATRIX_FINGERPRINT = hashCanonical({
+    version: OBSERVED_ROUTE_MATRIX_VERSION,
+    routes: OBSERVED_ROUTE_MATRIX,
+    witnessContracts: OBSERVED_ROUTE_WITNESS_CONTRACTS,
+    classWitnessContracts: OBSERVED_ROUTE_CLASS_WITNESS_CONTRACTS,
+    unwitnessed: OBSERVED_UNWITNESSED_ACTIONS,
+    unsupported: OBSERVED_UNSUPPORTED_ACTIONS,
+});
+export function validateObservedRouteMatrix() {
+    const routeIds = new Set();
+    const priorities = new Set();
+    const actions = new Set();
+    let previousPriority = Number.POSITIVE_INFINITY;
+    for (const route of OBSERVED_ROUTE_MATRIX) {
+        if (routeIds.has(route.routeId))
+            throw new TypeError(`Duplicate observed route id: ${route.routeId}`);
+        routeIds.add(route.routeId);
+        if (!Number.isInteger(route.priority) || route.priority < 1 || priorities.has(route.priority)) {
+            throw new TypeError(`Observed route priority must be a unique positive integer: ${route.priority}`);
+        }
+        if (route.priority >= previousPriority) {
+            throw new TypeError('Observed route matrix must be ordered by strict descending priority.');
+        }
+        priorities.add(route.priority);
+        previousPriority = route.priority;
+        if (route.actions.length !== 1)
+            throw new TypeError(`Observed route class ${route.routeId} must have one representative action.`);
+        const classWitness = CLASS_WITNESS_BY_ROUTE.get(route.routeId);
+        if (!classWitness || route.actions[0]?.action !== classWitness.action) {
+            throw new TypeError(`Observed route class has no exact witness contract: ${route.routeId}`);
+        }
+        for (const binding of route.actions) {
+            if (actions.has(binding.action))
+                throw new TypeError(`Advertised action has multiple routes: ${binding.action}`);
+            actions.add(binding.action);
+            if (classWitness.kind === 'terminal') {
+                if (binding.support !== 'unsupported' || binding.cliBinding !== null
+                    || binding.executorRefs.length > 0 || route.successorWitness.kind !== 'terminal') {
+                    throw new TypeError(`Terminal route class claims an executable transition: ${binding.action}`);
+                }
+            }
+            else {
+                const witness = WITNESS_CONTRACT_BY_ACTION.get(binding.action);
+                if (!witness || binding.support !== 'executable' || binding.cliBinding !== witness.action
+                    || !isCliCommand(witness.action) || !binding.executorRefs.includes(witness.executorRef)
+                    || witness.executorRef !== classWitness.executorRef
+                    || witness.successorActions.length === 0
+                    || witness.successorActions.some((action) => !classWitness.successorActions.includes(action))) {
+                    throw new TypeError(`Witnessed route has no exact CLI/executor/successor contract: ${binding.action}`);
+                }
+            }
+        }
+    }
+    if (routeIds.size !== OBSERVED_ROUTE_CLASS_WITNESS_CONTRACTS.length
+        || routeIds.size !== OBSERVED_ROUTE_INVENTORY.length) {
+        throw new TypeError('Every Signal-observed route class must have exactly one class-level witness.');
+    }
+    const knownActions = new Set(OBSERVED_ROUTE_INVENTORY.flatMap((route) => route.actions.map((binding) => binding.action)));
+    for (const witness of OBSERVED_ROUTE_WITNESS_CONTRACTS) {
+        if (!knownActions.has(witness.action)) {
+            throw new TypeError(`Observed route witness is absent from the known inventory: ${witness.action}`);
+        }
+        for (const successorAction of witness.successorActions) {
+            if (!knownActions.has(successorAction)) {
+                throw new TypeError(`Observed route successor action is unresolved: ${successorAction}`);
+            }
+        }
+    }
+    for (const route of OBSERVED_ROUTE_MATRIX) {
+        const classWitness = CLASS_WITNESS_BY_ROUTE.get(route.routeId);
+        if (classWitness.kind === 'terminal') {
+            if (route.successorWitness.kind !== 'terminal') {
+                throw new TypeError(`Terminal class has no terminal observation: ${route.routeId}`);
+            }
+            continue;
+        }
+        if (route.successorWitness.kind !== 'reachable' || route.successorWitness.routeIds.length === 0) {
+            throw new TypeError(`Transition class has no reachable fresh-next successor: ${route.routeId}`);
+        }
+        for (const successor of route.successorWitness.routeIds) {
+            if (!routeIds.has(successor))
+                throw new TypeError(`Observed route successor is unresolved: ${successor}`);
+        }
+    }
+    const unclaimedActions = new Set([
+        ...OBSERVED_UNWITNESSED_ACTIONS.map((entry) => entry.action),
+        ...OBSERVED_UNSUPPORTED_ACTIONS.map((entry) => entry.action),
+    ]);
+    const witnessedActions = new Set(OBSERVED_ROUTE_WITNESS_CONTRACTS.map((entry) => entry.action));
+    for (const action of knownActions) {
+        if (witnessedActions.has(action) === unclaimedActions.has(action)) {
+            throw new TypeError(`Known observed action must be exactly one of witnessed or unclaimed: ${action}`);
+        }
+    }
+}
+export function observedRouteMetadataForAction(action) {
+    validateObservedRouteMatrix();
+    const matches = OBSERVED_ROUTE_INVENTORY.flatMap((route) => route.actions
+        .filter((binding) => binding.action === action)
+        .map((binding) => ({ route, binding })));
+    if (matches.length !== 1) {
+        throw new WorkflowError('STATE_CORRUPT', 'Workflow next attempted to advertise an unknown or ambiguous action.', {
+            action,
+            matchCount: matches.length,
+            matrixVersion: OBSERVED_ROUTE_MATRIX_VERSION,
+            matrixFingerprint: OBSERVED_ROUTE_MATRIX_FINGERPRINT,
+        });
+    }
+    const { route, binding } = matches[0];
+    const witness = WITNESS_CONTRACT_BY_ACTION.get(action);
+    const classWitness = CLASS_WITNESS_BY_ROUTE.get(route.routeId);
+    const witnessedSuccessor = witness ? {
+        kind: 'reachable',
+        routeIds: [...new Set(witness.successorActions.map((successorAction) => OBSERVED_ROUTE_INVENTORY.find((candidate) => candidate.actions.some((candidateBinding) => candidateBinding.action === successorAction))?.routeId)
+                .filter((routeId) => Boolean(routeId)))],
+        evidence: `Executable next -> WorkflowService.${witness.executorRef} -> fresh next witness.`,
+    } : null;
+    return {
+        matrixVersion: OBSERVED_ROUTE_MATRIX_VERSION,
+        matrixFingerprint: OBSERVED_ROUTE_MATRIX_FINGERPRINT,
+        routeId: route.routeId,
+        priority: route.priority,
+        predicateRef: witness || classWitness?.action === action
+            ? `WorkflowService.next.action===${JSON.stringify(action)}`
+            : 'unclaimed',
+        routeFingerprint: hashCanonical({
+            version: OBSERVED_ROUTE_MATRIX_VERSION,
+            routeId: route.routeId,
+            action,
+            witness: witness ?? null,
+        }),
+        actionSupport: witness
+            ? 'executable-witnessed'
+            : binding.support === 'unsupported'
+                ? 'unsupported'
+                : 'unwitnessed',
+        cliBinding: witness ? witness.action : null,
+        executorRefs: witness ? [witness.executorRef] : [],
+        successorWitness: witnessedSuccessor ?? (classWitness?.kind === 'terminal' && classWitness.action === action
+            ? { kind: 'terminal', evidence: 'Fresh production next returned the exact terminal observation.' }
+            : action === 'none'
+                ? { kind: 'terminal', evidence: 'Terminal marker with no executor.' }
+                : {
+                    kind: 'unwitnessed',
+                    evidence: binding.support === 'unsupported'
+                        ? 'Manual instruction or blocked boundary with no single executable transition.'
+                        : 'Known route is not claimed until an executable next/executor/successor E2E exists.',
+                }),
+        coverageBoundary: 'signal-observed-route-class-witnesses',
+    };
+}
+export function verifyObservedRouteTransitionWitness(input) {
+    const action = input.before.action;
+    const successorAction = input.after.action;
+    if (typeof action !== 'string' || typeof successorAction !== 'string') {
+        throw new TypeError('Observed transition witness requires fresh before and after actions.');
+    }
+    const witness = WITNESS_CONTRACT_BY_ACTION.get(action);
+    if (!witness || witness.executorRef !== input.executorRef) {
+        throw new TypeError(`Observed transition witness does not match the claimed production executor: ${action}.`);
+    }
+    if (!witness.successorActions.includes(successorAction)) {
+        throw new TypeError(`Observed transition witness reached unsupported successor ${successorAction} after ${action}.`);
+    }
+    const metadata = observedRouteMetadataForAction(action);
+    const beforeRoute = input.before.route;
+    if (!beforeRoute || beforeRoute.routeFingerprint !== metadata.routeFingerprint) {
+        throw new TypeError(`Observed transition witness does not start from fresh route metadata: ${action}.`);
+    }
+    return {
+        action,
+        successorAction,
+        witnessFingerprint: hashCanonical({
+            matrixFingerprint: OBSERVED_ROUTE_MATRIX_FINGERPRINT,
+            routeFingerprint: metadata.routeFingerprint,
+            executorRef: input.executorRef,
+            successorAction,
+        }),
+    };
+}
+export function verifyObservedRouteClassTransitionWitness(input) {
+    const witness = verifyObservedRouteTransitionWitness(input);
+    const routeId = observedRouteMetadataForAction(witness.action).routeId;
+    const classWitness = CLASS_WITNESS_BY_ROUTE.get(routeId);
+    if (!classWitness || classWitness.kind !== 'transition' || classWitness.action !== witness.action
+        || classWitness.executorRef !== input.executorRef
+        || !classWitness.successorActions.includes(witness.successorAction)) {
+        throw new TypeError(`Transition is not the representative witness for observed route class ${routeId}.`);
+    }
+    return { routeId, ...witness };
+}
+export function verifyObservedRouteTerminalWitness(next) {
+    const action = next.action;
+    if (typeof action !== 'string')
+        throw new TypeError('Terminal route witness requires a fresh next action.');
+    const metadata = observedRouteMetadataForAction(action);
+    const route = next.route;
+    const classWitness = CLASS_WITNESS_BY_ROUTE.get(metadata.routeId);
+    if (!route || route.routeFingerprint !== metadata.routeFingerprint
+        || !classWitness || classWitness.kind !== 'terminal' || classWitness.action !== action) {
+        throw new TypeError(`Observation is not the representative terminal witness for ${metadata.routeId}.`);
+    }
+    return {
+        routeId: metadata.routeId,
+        action,
+        witnessFingerprint: hashCanonical({
+            matrixFingerprint: OBSERVED_ROUTE_MATRIX_FINGERPRINT,
+            routeFingerprint: metadata.routeFingerprint,
+            terminal: true,
+        }),
+    };
+}
+export function withObservedRouteMetadata(next) {
+    const action = next.action;
+    if (typeof action !== 'string' || action.trim().length === 0) {
+        throw new WorkflowError('STATE_CORRUPT', 'Workflow next produced no advertised action.', {
+            matrixVersion: OBSERVED_ROUTE_MATRIX_VERSION,
+            matrixFingerprint: OBSERVED_ROUTE_MATRIX_FINGERPRINT,
+        });
+    }
+    return { ...next, route: observedRouteMetadataForAction(action) };
+}
+//# sourceMappingURL=observed-routes.js.map