open-multi-agent-kit 0.97.0 → 0.98.0

package/dist/core/prompt-settlement.d.ts

@@ -1,3 +1,4 @@
+import type { SessionTerminationKind } from "./session-termination.ts";
 /**
  * Prompt settlement coordinator (OMK v0.97.x roadmap §16, M4/PR6).
  *
@@ -8,9 +9,9 @@
  * M4 completion sound, notifications) must treat it as a UX signal, never a
  * correctness signal (§3 non-goals).
  *
- * The reducer is a pure function over an immutable state (§16.5). Shard and
- * child counters are wired by M5/M6; they participate in the contract now so
- * those slices only add signal call sites.
+ * The reducer is a pure function over immutable state (§16.5). Shard and child
+ * counters are reserved in the contract, but no production signal call sites
+ * wire them yet; any future live M5/M6 path must add those calls before use.
  */
 export type PromptSettlementOutcome = "completed" | "failed" | "aborted";
 /** §16.2 prompt run identity. */
@@ -65,6 +66,8 @@ export type PromptSettlementSignal = {
 } | {
     readonly kind: "emitted";
 };
+/** Map the final typed termination onto the prompt UX outcome. */
+export declare function resolvePromptSettlementOutcome(fallback: PromptSettlementOutcome, terminationKind: SessionTerminationKind | undefined): PromptSettlementOutcome;
 export declare function createPromptSettlementState(promptRunId: string, startedAtEpochMs: number): PromptSettlementState;
 /** Pure reducer (§16.5). Counters clamp at zero; terminal and emitted are latching. */
 export declare function reducePromptSettlement(state: PromptSettlementState, signal: PromptSettlementSignal): PromptSettlementState;

package/dist/core/prompt-settlement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-settlement.d.ts","sourceRoot":"","sources":["../../src/core/prompt-settlement.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Prompt settlement coordinator (OMK v0.97.x roadmap §16, M4/PR6).\n *\n * `agent_end` is NOT final (§16.1): provider retries, compaction retries,\n * durable-goal continuations, steering/follow-up queues, shards, and child\n * subagents may still run. `prompt_settled` fires only when the reducer's\n * §16.4 conditions all hold, exactly once per promptRunId. Consumers (the\n * M4 completion sound, notifications) must treat it as a UX signal, never a\n * correctness signal (§3 non-goals).\n *\n * The reducer is a pure function over an immutable state (§16.5). Shard and\n * child counters are wired by M5/M6; they participate in the contract now so\n * those slices only add signal call sites.\n */\n\nexport type PromptSettlementOutcome = \"completed\" | \"failed\" | \"aborted\";\n\n/** §16.2 prompt run identity. */\nexport interface PromptRunRef {\n\treadonly promptRunId: string;\n\treadonly sessionId: string;\n\treadonly startedAt: string;\n\treadonly lineageId?: string;\n}\n\n/** §16.3 settlement contract. */\nexport interface PromptSettledEvent {\n\treadonly type: \"prompt_settled\";\n\treadonly promptRunId: string;\n\treadonly outcome: PromptSettlementOutcome;\n\treadonly durationMs: number;\n\treadonly terminationKind?: string;\n}\n\n/** §16.5 coordinator state. */\nexport interface PromptSettlementState {\n\treadonly promptRunId: string;\n\treadonly startedAtEpochMs: number;\n\treadonly activeProviderAttempts: number;\n\treadonly activeTools: number;\n\treadonly activeShards: number;\n\treadonly activeChildren: number;\n\treadonly queuedContinuations: number;\n\treadonly terminal?: {\n\t\treadonly outcome: PromptSettlementOutcome;\n\t\treadonly terminationKind?: string;\n\t};\n\treadonly emitted: boolean;\n}\n\nexport type PromptSettlementSignal =\n\t| { readonly kind: \"provider_attempt\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"tool\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"shard\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"child\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"continuation\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"terminal\"; readonly outcome: PromptSettlementOutcome; readonly terminationKind?: string }\n\t| { readonly kind: \"emitted\" };\n\nexport function createPromptSettlementState(promptRunId: string, startedAtEpochMs: number): PromptSettlementState {\n\treturn {\n\t\tpromptRunId,\n\t\tstartedAtEpochMs,\n\t\tactiveProviderAttempts: 0,\n\t\tactiveTools: 0,\n\t\tactiveShards: 0,\n\t\tactiveChildren: 0,\n\t\tqueuedContinuations: 0,\n\t\temitted: false,\n\t};\n}\n\n/** Pure reducer (§16.5). Counters clamp at zero; terminal and emitted are latching. */\nexport function reducePromptSettlement(\n\tstate: PromptSettlementState,\n\tsignal: PromptSettlementSignal,\n): PromptSettlementState {\n\tswitch (signal.kind) {\n\t\tcase \"provider_attempt\":\n\t\t\treturn { ...state, activeProviderAttempts: clampCount(state.activeProviderAttempts + signal.delta) };\n\t\tcase \"tool\":\n\t\t\treturn { ...state, activeTools: clampCount(state.activeTools + signal.delta) };\n\t\tcase \"shard\":\n\t\t\treturn { ...state, activeShards: clampCount(state.activeShards + signal.delta) };\n\t\tcase \"child\":\n\t\t\treturn { ...state, activeChildren: clampCount(state.activeChildren + signal.delta) };\n\t\tcase \"continuation\":\n\t\t\treturn { ...state, queuedContinuations: clampCount(state.queuedContinuations + signal.delta) };\n\t\tcase \"terminal\":\n\t\t\t// First terminal outcome wins; later reclassification never flips it (§15.3).\n\t\t\tif (state.terminal !== undefined) {\n\t\t\t\treturn state;\n\t\t\t}\n\t\t\treturn { ...state, terminal: { outcome: signal.outcome, terminationKind: signal.terminationKind } };\n\t\tcase \"emitted\":\n\t\t\treturn { ...state, emitted: true };\n\t\tdefault: {\n\t\t\tconst exhaustive: never = signal;\n\t\t\treturn exhaustive;\n\t\t}\n\t}\n}\n\n/** §16.4: every condition must hold before `prompt_settled` may emit. */\nexport function shouldEmitPromptSettled(state: PromptSettlementState): boolean {\n\treturn (\n\t\tstate.terminal !== undefined &&\n\t\t!state.emitted &&\n\t\tstate.activeProviderAttempts === 0 &&\n\t\tstate.activeTools === 0 &&\n\t\tstate.activeShards === 0 &&\n\t\tstate.activeChildren === 0 &&\n\t\tstate.queuedContinuations === 0\n\t);\n}\n\n/**\n * Build the event when (and only when) §16.4 holds, marking the state\n * emitted so the same sequence can never yield a second event.\n */\nexport function settlePromptIfReady(\n\tstate: PromptSettlementState,\n\tnowEpochMs: number,\n): { readonly state: PromptSettlementState; readonly event: PromptSettledEvent | null } {\n\tif (!shouldEmitPromptSettled(state) || state.terminal === undefined) {\n\t\treturn { state, event: null };\n\t}\n\tconst event: PromptSettledEvent = {\n\t\ttype: \"prompt_settled\",\n\t\tpromptRunId: state.promptRunId,\n\t\toutcome: state.terminal.outcome,\n\t\tdurationMs: Math.max(0, nowEpochMs - state.startedAtEpochMs),\n\t\t...(state.terminal.terminationKind !== undefined ? { terminationKind: state.terminal.terminationKind } : {}),\n\t};\n\treturn { state: reducePromptSettlement(state, { kind: \"emitted\" }), event };\n}\n\nfunction clampCount(value: number): number {\n\treturn Math.max(0, value);\n}\n"]}
+{"version":3,"file":"prompt-settlement.d.ts","sourceRoot":"","sources":["../../src/core/prompt-settlement.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SessionTerminationKind } from \"./session-termination.ts\";\n\n/**\n * Prompt settlement coordinator (OMK v0.97.x roadmap §16, M4/PR6).\n *\n * `agent_end` is NOT final (§16.1): provider retries, compaction retries,\n * durable-goal continuations, steering/follow-up queues, shards, and child\n * subagents may still run. `prompt_settled` fires only when the reducer's\n * §16.4 conditions all hold, exactly once per promptRunId. Consumers (the\n * M4 completion sound, notifications) must treat it as a UX signal, never a\n * correctness signal (§3 non-goals).\n *\n * The reducer is a pure function over immutable state (§16.5). Shard and child\n * counters are reserved in the contract, but no production signal call sites\n * wire them yet; any future live M5/M6 path must add those calls before use.\n */\n\nexport type PromptSettlementOutcome = \"completed\" | \"failed\" | \"aborted\";\n\n/** §16.2 prompt run identity. */\nexport interface PromptRunRef {\n\treadonly promptRunId: string;\n\treadonly sessionId: string;\n\treadonly startedAt: string;\n\treadonly lineageId?: string;\n}\n\n/** §16.3 settlement contract. */\nexport interface PromptSettledEvent {\n\treadonly type: \"prompt_settled\";\n\treadonly promptRunId: string;\n\treadonly outcome: PromptSettlementOutcome;\n\treadonly durationMs: number;\n\treadonly terminationKind?: string;\n}\n\n/** §16.5 coordinator state. */\nexport interface PromptSettlementState {\n\treadonly promptRunId: string;\n\treadonly startedAtEpochMs: number;\n\treadonly activeProviderAttempts: number;\n\treadonly activeTools: number;\n\treadonly activeShards: number;\n\treadonly activeChildren: number;\n\treadonly queuedContinuations: number;\n\treadonly terminal?: {\n\t\treadonly outcome: PromptSettlementOutcome;\n\t\treadonly terminationKind?: string;\n\t};\n\treadonly emitted: boolean;\n}\n\nexport type PromptSettlementSignal =\n\t| { readonly kind: \"provider_attempt\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"tool\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"shard\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"child\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"continuation\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"terminal\"; readonly outcome: PromptSettlementOutcome; readonly terminationKind?: string }\n\t| { readonly kind: \"emitted\" };\n\n/** Map the final typed termination onto the prompt UX outcome. */\nexport function resolvePromptSettlementOutcome(\n\tfallback: PromptSettlementOutcome,\n\tterminationKind: SessionTerminationKind | undefined,\n): PromptSettlementOutcome {\n\tif (terminationKind === \"user_abort\" || terminationKind === \"provider_abort\") return \"aborted\";\n\tif (fallback !== \"completed\") return fallback;\n\tif (terminationKind === undefined || terminationKind === \"completed\") return \"completed\";\n\treturn \"failed\";\n}\n\nexport function createPromptSettlementState(promptRunId: string, startedAtEpochMs: number): PromptSettlementState {\n\treturn {\n\t\tpromptRunId,\n\t\tstartedAtEpochMs,\n\t\tactiveProviderAttempts: 0,\n\t\tactiveTools: 0,\n\t\tactiveShards: 0,\n\t\tactiveChildren: 0,\n\t\tqueuedContinuations: 0,\n\t\temitted: false,\n\t};\n}\n\n/** Pure reducer (§16.5). Counters clamp at zero; terminal and emitted are latching. */\nexport function reducePromptSettlement(\n\tstate: PromptSettlementState,\n\tsignal: PromptSettlementSignal,\n): PromptSettlementState {\n\tswitch (signal.kind) {\n\t\tcase \"provider_attempt\":\n\t\t\treturn { ...state, activeProviderAttempts: clampCount(state.activeProviderAttempts + signal.delta) };\n\t\tcase \"tool\":\n\t\t\treturn { ...state, activeTools: clampCount(state.activeTools + signal.delta) };\n\t\tcase \"shard\":\n\t\t\treturn { ...state, activeShards: clampCount(state.activeShards + signal.delta) };\n\t\tcase \"child\":\n\t\t\treturn { ...state, activeChildren: clampCount(state.activeChildren + signal.delta) };\n\t\tcase \"continuation\":\n\t\t\treturn { ...state, queuedContinuations: clampCount(state.queuedContinuations + signal.delta) };\n\t\tcase \"terminal\":\n\t\t\t// First terminal outcome wins; later reclassification never flips it (§15.3).\n\t\t\tif (state.terminal !== undefined) {\n\t\t\t\treturn state;\n\t\t\t}\n\t\t\treturn { ...state, terminal: { outcome: signal.outcome, terminationKind: signal.terminationKind } };\n\t\tcase \"emitted\":\n\t\t\treturn { ...state, emitted: true };\n\t\tdefault: {\n\t\t\tconst exhaustive: never = signal;\n\t\t\treturn exhaustive;\n\t\t}\n\t}\n}\n\n/** §16.4: every condition must hold before `prompt_settled` may emit. */\nexport function shouldEmitPromptSettled(state: PromptSettlementState): boolean {\n\treturn (\n\t\tstate.terminal !== undefined &&\n\t\t!state.emitted &&\n\t\tstate.activeProviderAttempts === 0 &&\n\t\tstate.activeTools === 0 &&\n\t\tstate.activeShards === 0 &&\n\t\tstate.activeChildren === 0 &&\n\t\tstate.queuedContinuations === 0\n\t);\n}\n\n/**\n * Build the event when (and only when) §16.4 holds, marking the state\n * emitted so the same sequence can never yield a second event.\n */\nexport function settlePromptIfReady(\n\tstate: PromptSettlementState,\n\tnowEpochMs: number,\n): { readonly state: PromptSettlementState; readonly event: PromptSettledEvent | null } {\n\tif (!shouldEmitPromptSettled(state) || state.terminal === undefined) {\n\t\treturn { state, event: null };\n\t}\n\tconst event: PromptSettledEvent = {\n\t\ttype: \"prompt_settled\",\n\t\tpromptRunId: state.promptRunId,\n\t\toutcome: state.terminal.outcome,\n\t\tdurationMs: Math.max(0, nowEpochMs - state.startedAtEpochMs),\n\t\t...(state.terminal.terminationKind !== undefined ? { terminationKind: state.terminal.terminationKind } : {}),\n\t};\n\treturn { state: reducePromptSettlement(state, { kind: \"emitted\" }), event };\n}\n\nfunction clampCount(value: number): number {\n\treturn Math.max(0, value);\n}\n"]}

package/dist/core/prompt-settlement.js

@@ -1,17 +1,13 @@
-/**
- * Prompt settlement coordinator (OMK v0.97.x roadmap §16, M4/PR6).
- *
- * `agent_end` is NOT final (§16.1): provider retries, compaction retries,
- * durable-goal continuations, steering/follow-up queues, shards, and child
- * subagents may still run. `prompt_settled` fires only when the reducer's
- * §16.4 conditions all hold, exactly once per promptRunId. Consumers (the
- * M4 completion sound, notifications) must treat it as a UX signal, never a
- * correctness signal (§3 non-goals).
- *
- * The reducer is a pure function over an immutable state (§16.5). Shard and
- * child counters are wired by M5/M6; they participate in the contract now so
- * those slices only add signal call sites.
- */
+/** Map the final typed termination onto the prompt UX outcome. */
+export function resolvePromptSettlementOutcome(fallback, terminationKind) {
+    if (terminationKind === "user_abort" || terminationKind === "provider_abort")
+        return "aborted";
+    if (fallback !== "completed")
+        return fallback;
+    if (terminationKind === undefined || terminationKind === "completed")
+        return "completed";
+    return "failed";
+}
 export function createPromptSettlementState(promptRunId, startedAtEpochMs) {
     return {
         promptRunId,

package/dist/core/prompt-settlement.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-settlement.js","sourceRoot":"","sources":["../../src/core/prompt-settlement.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Prompt settlement coordinator (OMK v0.97.x roadmap §16, M4/PR6).\n *\n * `agent_end` is NOT final (§16.1): provider retries, compaction retries,\n * durable-goal continuations, steering/follow-up queues, shards, and child\n * subagents may still run. `prompt_settled` fires only when the reducer's\n * §16.4 conditions all hold, exactly once per promptRunId. Consumers (the\n * M4 completion sound, notifications) must treat it as a UX signal, never a\n * correctness signal (§3 non-goals).\n *\n * The reducer is a pure function over an immutable state (§16.5). Shard and\n * child counters are wired by M5/M6; they participate in the contract now so\n * those slices only add signal call sites.\n */\n\nexport type PromptSettlementOutcome = \"completed\" | \"failed\" | \"aborted\";\n\n/** §16.2 prompt run identity. */\nexport interface PromptRunRef {\n\treadonly promptRunId: string;\n\treadonly sessionId: string;\n\treadonly startedAt: string;\n\treadonly lineageId?: string;\n}\n\n/** §16.3 settlement contract. */\nexport interface PromptSettledEvent {\n\treadonly type: \"prompt_settled\";\n\treadonly promptRunId: string;\n\treadonly outcome: PromptSettlementOutcome;\n\treadonly durationMs: number;\n\treadonly terminationKind?: string;\n}\n\n/** §16.5 coordinator state. */\nexport interface PromptSettlementState {\n\treadonly promptRunId: string;\n\treadonly startedAtEpochMs: number;\n\treadonly activeProviderAttempts: number;\n\treadonly activeTools: number;\n\treadonly activeShards: number;\n\treadonly activeChildren: number;\n\treadonly queuedContinuations: number;\n\treadonly terminal?: {\n\t\treadonly outcome: PromptSettlementOutcome;\n\t\treadonly terminationKind?: string;\n\t};\n\treadonly emitted: boolean;\n}\n\nexport type PromptSettlementSignal =\n\t| { readonly kind: \"provider_attempt\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"tool\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"shard\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"child\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"continuation\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"terminal\"; readonly outcome: PromptSettlementOutcome; readonly terminationKind?: string }\n\t| { readonly kind: \"emitted\" };\n\nexport function createPromptSettlementState(promptRunId: string, startedAtEpochMs: number): PromptSettlementState {\n\treturn {\n\t\tpromptRunId,\n\t\tstartedAtEpochMs,\n\t\tactiveProviderAttempts: 0,\n\t\tactiveTools: 0,\n\t\tactiveShards: 0,\n\t\tactiveChildren: 0,\n\t\tqueuedContinuations: 0,\n\t\temitted: false,\n\t};\n}\n\n/** Pure reducer (§16.5). Counters clamp at zero; terminal and emitted are latching. */\nexport function reducePromptSettlement(\n\tstate: PromptSettlementState,\n\tsignal: PromptSettlementSignal,\n): PromptSettlementState {\n\tswitch (signal.kind) {\n\t\tcase \"provider_attempt\":\n\t\t\treturn { ...state, activeProviderAttempts: clampCount(state.activeProviderAttempts + signal.delta) };\n\t\tcase \"tool\":\n\t\t\treturn { ...state, activeTools: clampCount(state.activeTools + signal.delta) };\n\t\tcase \"shard\":\n\t\t\treturn { ...state, activeShards: clampCount(state.activeShards + signal.delta) };\n\t\tcase \"child\":\n\t\t\treturn { ...state, activeChildren: clampCount(state.activeChildren + signal.delta) };\n\t\tcase \"continuation\":\n\t\t\treturn { ...state, queuedContinuations: clampCount(state.queuedContinuations + signal.delta) };\n\t\tcase \"terminal\":\n\t\t\t// First terminal outcome wins; later reclassification never flips it (§15.3).\n\t\t\tif (state.terminal !== undefined) {\n\t\t\t\treturn state;\n\t\t\t}\n\t\t\treturn { ...state, terminal: { outcome: signal.outcome, terminationKind: signal.terminationKind } };\n\t\tcase \"emitted\":\n\t\t\treturn { ...state, emitted: true };\n\t\tdefault: {\n\t\t\tconst exhaustive: never = signal;\n\t\t\treturn exhaustive;\n\t\t}\n\t}\n}\n\n/** §16.4: every condition must hold before `prompt_settled` may emit. */\nexport function shouldEmitPromptSettled(state: PromptSettlementState): boolean {\n\treturn (\n\t\tstate.terminal !== undefined &&\n\t\t!state.emitted &&\n\t\tstate.activeProviderAttempts === 0 &&\n\t\tstate.activeTools === 0 &&\n\t\tstate.activeShards === 0 &&\n\t\tstate.activeChildren === 0 &&\n\t\tstate.queuedContinuations === 0\n\t);\n}\n\n/**\n * Build the event when (and only when) §16.4 holds, marking the state\n * emitted so the same sequence can never yield a second event.\n */\nexport function settlePromptIfReady(\n\tstate: PromptSettlementState,\n\tnowEpochMs: number,\n): { readonly state: PromptSettlementState; readonly event: PromptSettledEvent | null } {\n\tif (!shouldEmitPromptSettled(state) || state.terminal === undefined) {\n\t\treturn { state, event: null };\n\t}\n\tconst event: PromptSettledEvent = {\n\t\ttype: \"prompt_settled\",\n\t\tpromptRunId: state.promptRunId,\n\t\toutcome: state.terminal.outcome,\n\t\tdurationMs: Math.max(0, nowEpochMs - state.startedAtEpochMs),\n\t\t...(state.terminal.terminationKind !== undefined ? { terminationKind: state.terminal.terminationKind } : {}),\n\t};\n\treturn { state: reducePromptSettlement(state, { kind: \"emitted\" }), event };\n}\n\nfunction clampCount(value: number): number {\n\treturn Math.max(0, value);\n}\n"]}
+{"version":3,"file":"prompt-settlement.js","sourceRoot":"","sources":["../../src/core/prompt-settlement.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SessionTerminationKind } from \"./session-termination.ts\";\n\n/**\n * Prompt settlement coordinator (OMK v0.97.x roadmap §16, M4/PR6).\n *\n * `agent_end` is NOT final (§16.1): provider retries, compaction retries,\n * durable-goal continuations, steering/follow-up queues, shards, and child\n * subagents may still run. `prompt_settled` fires only when the reducer's\n * §16.4 conditions all hold, exactly once per promptRunId. Consumers (the\n * M4 completion sound, notifications) must treat it as a UX signal, never a\n * correctness signal (§3 non-goals).\n *\n * The reducer is a pure function over immutable state (§16.5). Shard and child\n * counters are reserved in the contract, but no production signal call sites\n * wire them yet; any future live M5/M6 path must add those calls before use.\n */\n\nexport type PromptSettlementOutcome = \"completed\" | \"failed\" | \"aborted\";\n\n/** §16.2 prompt run identity. */\nexport interface PromptRunRef {\n\treadonly promptRunId: string;\n\treadonly sessionId: string;\n\treadonly startedAt: string;\n\treadonly lineageId?: string;\n}\n\n/** §16.3 settlement contract. */\nexport interface PromptSettledEvent {\n\treadonly type: \"prompt_settled\";\n\treadonly promptRunId: string;\n\treadonly outcome: PromptSettlementOutcome;\n\treadonly durationMs: number;\n\treadonly terminationKind?: string;\n}\n\n/** §16.5 coordinator state. */\nexport interface PromptSettlementState {\n\treadonly promptRunId: string;\n\treadonly startedAtEpochMs: number;\n\treadonly activeProviderAttempts: number;\n\treadonly activeTools: number;\n\treadonly activeShards: number;\n\treadonly activeChildren: number;\n\treadonly queuedContinuations: number;\n\treadonly terminal?: {\n\t\treadonly outcome: PromptSettlementOutcome;\n\t\treadonly terminationKind?: string;\n\t};\n\treadonly emitted: boolean;\n}\n\nexport type PromptSettlementSignal =\n\t| { readonly kind: \"provider_attempt\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"tool\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"shard\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"child\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"continuation\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"terminal\"; readonly outcome: PromptSettlementOutcome; readonly terminationKind?: string }\n\t| { readonly kind: \"emitted\" };\n\n/** Map the final typed termination onto the prompt UX outcome. */\nexport function resolvePromptSettlementOutcome(\n\tfallback: PromptSettlementOutcome,\n\tterminationKind: SessionTerminationKind | undefined,\n): PromptSettlementOutcome {\n\tif (terminationKind === \"user_abort\" || terminationKind === \"provider_abort\") return \"aborted\";\n\tif (fallback !== \"completed\") return fallback;\n\tif (terminationKind === undefined || terminationKind === \"completed\") return \"completed\";\n\treturn \"failed\";\n}\n\nexport function createPromptSettlementState(promptRunId: string, startedAtEpochMs: number): PromptSettlementState {\n\treturn {\n\t\tpromptRunId,\n\t\tstartedAtEpochMs,\n\t\tactiveProviderAttempts: 0,\n\t\tactiveTools: 0,\n\t\tactiveShards: 0,\n\t\tactiveChildren: 0,\n\t\tqueuedContinuations: 0,\n\t\temitted: false,\n\t};\n}\n\n/** Pure reducer (§16.5). Counters clamp at zero; terminal and emitted are latching. */\nexport function reducePromptSettlement(\n\tstate: PromptSettlementState,\n\tsignal: PromptSettlementSignal,\n): PromptSettlementState {\n\tswitch (signal.kind) {\n\t\tcase \"provider_attempt\":\n\t\t\treturn { ...state, activeProviderAttempts: clampCount(state.activeProviderAttempts + signal.delta) };\n\t\tcase \"tool\":\n\t\t\treturn { ...state, activeTools: clampCount(state.activeTools + signal.delta) };\n\t\tcase \"shard\":\n\t\t\treturn { ...state, activeShards: clampCount(state.activeShards + signal.delta) };\n\t\tcase \"child\":\n\t\t\treturn { ...state, activeChildren: clampCount(state.activeChildren + signal.delta) };\n\t\tcase \"continuation\":\n\t\t\treturn { ...state, queuedContinuations: clampCount(state.queuedContinuations + signal.delta) };\n\t\tcase \"terminal\":\n\t\t\t// First terminal outcome wins; later reclassification never flips it (§15.3).\n\t\t\tif (state.terminal !== undefined) {\n\t\t\t\treturn state;\n\t\t\t}\n\t\t\treturn { ...state, terminal: { outcome: signal.outcome, terminationKind: signal.terminationKind } };\n\t\tcase \"emitted\":\n\t\t\treturn { ...state, emitted: true };\n\t\tdefault: {\n\t\t\tconst exhaustive: never = signal;\n\t\t\treturn exhaustive;\n\t\t}\n\t}\n}\n\n/** §16.4: every condition must hold before `prompt_settled` may emit. */\nexport function shouldEmitPromptSettled(state: PromptSettlementState): boolean {\n\treturn (\n\t\tstate.terminal !== undefined &&\n\t\t!state.emitted &&\n\t\tstate.activeProviderAttempts === 0 &&\n\t\tstate.activeTools === 0 &&\n\t\tstate.activeShards === 0 &&\n\t\tstate.activeChildren === 0 &&\n\t\tstate.queuedContinuations === 0\n\t);\n}\n\n/**\n * Build the event when (and only when) §16.4 holds, marking the state\n * emitted so the same sequence can never yield a second event.\n */\nexport function settlePromptIfReady(\n\tstate: PromptSettlementState,\n\tnowEpochMs: number,\n): { readonly state: PromptSettlementState; readonly event: PromptSettledEvent | null } {\n\tif (!shouldEmitPromptSettled(state) || state.terminal === undefined) {\n\t\treturn { state, event: null };\n\t}\n\tconst event: PromptSettledEvent = {\n\t\ttype: \"prompt_settled\",\n\t\tpromptRunId: state.promptRunId,\n\t\toutcome: state.terminal.outcome,\n\t\tdurationMs: Math.max(0, nowEpochMs - state.startedAtEpochMs),\n\t\t...(state.terminal.terminationKind !== undefined ? { terminationKind: state.terminal.terminationKind } : {}),\n\t};\n\treturn { state: reducePromptSettlement(state, { kind: \"emitted\" }), event };\n}\n\nfunction clampCount(value: number): number {\n\treturn Math.max(0, value);\n}\n"]}

package/dist/core/reasoning-router-promotion.d.ts

@@ -10,6 +10,10 @@
  * This module is that policy, as a pure total function. It deliberately refuses
  * to promote on anything short of unanimous evidence:
  *
+ * - outcomes that survived a two-run replay, so a flipped measurement is never
+ *   credited as a win (see `reasoning-router-replay-stability.ts`);
+ * - a comparison against the frozen reference policy rather than an opponent
+ *   the caller picked, which is what stops baseline shopping;
  * - a statistically significant win on the held-in gold set (McNemar's exact
  *   test), computed by the caller and passed in;
  * - enough discordant pairs for that test to mean anything;
@@ -37,10 +41,31 @@ export interface RouterHoldoutEvidence {
     readonly candidateCorrect: number;
     readonly total: number;
 }
+/** How much of the evidence survived repeated identical replays. */
+export interface RouterStabilityEvidence {
+    /** Rows replayed under both policies, whatever bucket they landed in. */
+    readonly evaluated: number;
+    /** Rows withheld because repeated observations disagreed. */
+    readonly unstable: number;
+    /** Independent observations per row behind the credited outcomes. */
+    readonly replays: number;
+}
+/**
+ * What the candidate was measured against.
+ *
+ * `frozen_reference` is the shipped policy that learning never updates. A
+ * candidate that only beats an opponent the caller chose has demonstrated
+ * nothing, so the gate refuses to reason about `ad_hoc` comparisons.
+ */
+export type RouterBaselineKind = "frozen_reference" | "ad_hoc";
 /** Everything the gate is allowed to consider. */
 export interface RouterPromotionEvidence {
     readonly heldIn: RouterHeldInEvidence;
     readonly holdout: RouterHoldoutEvidence;
+    /** Replay agreement behind every credited outcome. */
+    readonly stability: RouterStabilityEvidence;
+    /** Which opponent produced `heldIn` and `holdout`. */
+    readonly baselineKind: RouterBaselineKind;
     /** Golden-diff changes still unreviewed at decision time. */
     readonly goldenChanges: number;
     /** True only when a human explicitly approved this exact candidate. */
@@ -54,9 +79,15 @@ export interface RouterPromotionPolicy {
     readonly minHoldout: number;
     /** Maximum unreviewed golden-diff changes tolerated. */
     readonly maxGoldenChanges: number;
+    /** Independent replays required per row before any outcome carries credit. */
+    readonly minReplays: number;
+    /** Maximum rows allowed to disagree across replays. */
+    readonly maxUnstable: number;
+    /** Require the frozen reference policy as the comparison opponent. */
+    readonly requireFrozenBaseline: boolean;
     readonly requireHumanApproval: boolean;
 }
-export type RouterPromotionBlocker = "malformed_evidence" | "insufficient_discordant_pairs" | "mcnemar_not_significant" | "candidate_not_favored" | "holdout_regression" | "insufficient_holdout" | "unreviewed_behavior_changes" | "human_approval_missing";
+export type RouterPromotionBlocker = "malformed_evidence" | "insufficient_replays" | "unstable_evidence" | "baseline_not_frozen" | "insufficient_discordant_pairs" | "mcnemar_not_significant" | "candidate_not_favored" | "holdout_regression" | "insufficient_holdout" | "unreviewed_behavior_changes" | "human_approval_missing";
 export interface RouterPromotionVerdict {
     readonly promote: boolean;
     /** Every independent reason promotion was refused, in evaluation order. */
@@ -70,6 +101,11 @@ export interface RouterPromotionVerdict {
  * `minHoldout` is 40 because the router gold set freezes 42 holdout rows (6 per
  * class × 7 classes). A higher bar would be unsatisfiable rather than strict,
  * and a gate that can never pass is a gate nobody runs.
+ *
+ * `minReplays` of 2 is the two-run rule: one observation cannot be checked for
+ * stability at all. `maxUnstable` of 0 follows from what instability means here
+ * — the routing path is deterministic, so a single disagreeing row is a defect
+ * in the measurement, not an acceptable error rate to average over.
  */
 export declare const DEFAULT_ROUTER_PROMOTION_POLICY: RouterPromotionPolicy;
 /**
@@ -79,6 +115,10 @@ export declare const DEFAULT_ROUTER_PROMOTION_POLICY: RouterPromotionPolicy;
  * run reports the full distance to promotion instead of revealing it one
  * rejection at a time. Malformed evidence short-circuits: the gate never
  * reasons about numbers it cannot trust.
+ *
+ * Evidence-integrity blockers are reported ahead of statistical ones. A p-value
+ * computed over unstable rows or against the wrong opponent is not a weaker
+ * result, it is a result about nothing, and the report should say so first.
  */
 export declare function evaluateRouterPromotion(evidence: RouterPromotionEvidence, policy?: RouterPromotionPolicy): RouterPromotionVerdict;
 //# sourceMappingURL=reasoning-router-promotion.d.ts.map

package/dist/core/reasoning-router-promotion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reasoning-router-promotion.d.ts","sourceRoot":"","sources":["../../src/core/reasoning-router-promotion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC9B;AAED,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CAChC;AAED,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACrC,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,MAAM,sBAAsB,GAC/B,oBAAoB,GACpB,+BAA+B,GAC/B,yBAAyB,GACzB,uBAAuB,GACvB,oBAAoB,GACpB,sBAAsB,GACtB,6BAA6B,GAC7B,wBAAwB,CAAC;AAE5B,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACrD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,EAAE,qBAK7C,CAAC;AAeF;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,uBAAuB,EACjC,MAAM,GAAE,qBAAuD,GAC7D,sBAAsB,CA+BxB","sourcesContent":["/**\n * Promotion gate for learned reasoning-router weights.\n *\n * The router already produces a feedback ledger (`router-feedback-collector.ts`)\n * and an offline calibration stack (`scripts/reasoning-router/`: calibration,\n * held-out evaluation, golden diffing, and McNemar's exact test). What was\n * missing is the decision policy that makes automatic promotion trustworthy:\n * without it the loop is open and every weight change is a judgement call.\n *\n * This module is that policy, as a pure total function. It deliberately refuses\n * to promote on anything short of unanimous evidence:\n *\n * - a statistically significant win on the held-in gold set (McNemar's exact\n *   test), computed by the caller and passed in;\n * - enough discordant pairs for that test to mean anything;\n * - the candidate — not the baseline — winning those pairs;\n * - no accuracy regression on a held-out split the calibration never saw;\n * - no unreviewed behavior changes surfaced by golden diffing; and\n * - an explicit human approval.\n *\n * \"The agent tried again\" is not the same as \"the harness improved\", so a\n * candidate that merely fails to be worse is rejected, and malformed evidence\n * fails closed rather than defaulting to promotion.\n */\n\n/** Held-in McNemar outcome. Wins are counted in discordant pairs only. */\nexport interface RouterHeldInEvidence {\n\t/** Rows the baseline classified correctly and the candidate got wrong. */\n\treadonly baselineWins: number;\n\t/** Rows the candidate classified correctly and the baseline got wrong. */\n\treadonly candidateWins: number;\n\treadonly pValue: number;\n\treadonly significant: boolean;\n}\n\n/** Accuracy on a split withheld from calibration. */\nexport interface RouterHoldoutEvidence {\n\treadonly baselineCorrect: number;\n\treadonly candidateCorrect: number;\n\treadonly total: number;\n}\n\n/** Everything the gate is allowed to consider. */\nexport interface RouterPromotionEvidence {\n\treadonly heldIn: RouterHeldInEvidence;\n\treadonly holdout: RouterHoldoutEvidence;\n\t/** Golden-diff changes still unreviewed at decision time. */\n\treadonly goldenChanges: number;\n\t/** True only when a human explicitly approved this exact candidate. */\n\treadonly humanApproved: boolean;\n}\n\n/** Tunable thresholds. Loosening these can never authorize a regression. */\nexport interface RouterPromotionPolicy {\n\t/** Minimum discordant pairs before McNemar's verdict is trusted. */\n\treadonly minDiscordant: number;\n\t/** Minimum held-out rows before \"no regression\" is meaningful. */\n\treadonly minHoldout: number;\n\t/** Maximum unreviewed golden-diff changes tolerated. */\n\treadonly maxGoldenChanges: number;\n\treadonly requireHumanApproval: boolean;\n}\n\nexport type RouterPromotionBlocker =\n\t| \"malformed_evidence\"\n\t| \"insufficient_discordant_pairs\"\n\t| \"mcnemar_not_significant\"\n\t| \"candidate_not_favored\"\n\t| \"holdout_regression\"\n\t| \"insufficient_holdout\"\n\t| \"unreviewed_behavior_changes\"\n\t| \"human_approval_missing\";\n\nexport interface RouterPromotionVerdict {\n\treadonly promote: boolean;\n\t/** Every independent reason promotion was refused, in evaluation order. */\n\treadonly blockers: readonly RouterPromotionBlocker[];\n}\n\n/**\n * Conservative defaults. `minDiscordant` of 20 keeps McNemar from ruling on a\n * handful of pairs; `maxGoldenChanges` of 0 means a reviewer accepts behavior\n * changes by regenerating the golden set, never by tolerating drift.\n *\n * `minHoldout` is 40 because the router gold set freezes 42 holdout rows (6 per\n * class × 7 classes). A higher bar would be unsatisfiable rather than strict,\n * and a gate that can never pass is a gate nobody runs.\n */\nexport const DEFAULT_ROUTER_PROMOTION_POLICY: RouterPromotionPolicy = {\n\tmaxGoldenChanges: 0,\n\tminDiscordant: 20,\n\tminHoldout: 40,\n\trequireHumanApproval: true,\n};\n\nfunction isCount(value: number): boolean {\n\treturn Number.isFinite(value) && value >= 0;\n}\n\nfunction isMalformed(evidence: RouterPromotionEvidence): boolean {\n\tconst { goldenChanges, heldIn, holdout } = evidence;\n\tif (!isCount(heldIn.baselineWins) || !isCount(heldIn.candidateWins)) return true;\n\tif (!Number.isFinite(heldIn.pValue) || heldIn.pValue < 0 || heldIn.pValue > 1) return true;\n\tif (!isCount(holdout.baselineCorrect) || !isCount(holdout.candidateCorrect) || !isCount(holdout.total)) return true;\n\tif (holdout.baselineCorrect > holdout.total || holdout.candidateCorrect > holdout.total) return true;\n\treturn !isCount(goldenChanges);\n}\n\n/**\n * Decide whether a candidate weight set may replace the active one.\n *\n * Returns every independent blocker rather than the first, so one calibration\n * run reports the full distance to promotion instead of revealing it one\n * rejection at a time. Malformed evidence short-circuits: the gate never\n * reasons about numbers it cannot trust.\n */\nexport function evaluateRouterPromotion(\n\tevidence: RouterPromotionEvidence,\n\tpolicy: RouterPromotionPolicy = DEFAULT_ROUTER_PROMOTION_POLICY,\n): RouterPromotionVerdict {\n\tif (isMalformed(evidence)) {\n\t\treturn { blockers: [\"malformed_evidence\"], promote: false };\n\t}\n\n\tconst { goldenChanges, heldIn, holdout, humanApproved } = evidence;\n\tconst blockers: RouterPromotionBlocker[] = [];\n\n\tif (heldIn.baselineWins + heldIn.candidateWins < policy.minDiscordant) {\n\t\tblockers.push(\"insufficient_discordant_pairs\");\n\t}\n\tif (!heldIn.significant) {\n\t\tblockers.push(\"mcnemar_not_significant\");\n\t}\n\tif (heldIn.candidateWins <= heldIn.baselineWins) {\n\t\tblockers.push(\"candidate_not_favored\");\n\t}\n\tif (holdout.total < policy.minHoldout) {\n\t\tblockers.push(\"insufficient_holdout\");\n\t}\n\tif (holdout.candidateCorrect < holdout.baselineCorrect) {\n\t\tblockers.push(\"holdout_regression\");\n\t}\n\tif (goldenChanges > policy.maxGoldenChanges) {\n\t\tblockers.push(\"unreviewed_behavior_changes\");\n\t}\n\tif (policy.requireHumanApproval && !humanApproved) {\n\t\tblockers.push(\"human_approval_missing\");\n\t}\n\n\treturn { blockers, promote: blockers.length === 0 };\n}\n"]}
+{"version":3,"file":"reasoning-router-promotion.d.ts","sourceRoot":"","sources":["../../src/core/reasoning-router-promotion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC9B;AAED,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACvC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,kBAAkB,GAAG,QAAQ,CAAC;AAE/D,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,uBAAuB,CAAC;IAC5C,sDAAsD;IACtD,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CAChC;AAED,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACrC,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,MAAM,sBAAsB,GAC/B,oBAAoB,GACpB,sBAAsB,GACtB,mBAAmB,GACnB,qBAAqB,GACrB,+BAA+B,GAC/B,yBAAyB,GACzB,uBAAuB,GACvB,oBAAoB,GACpB,sBAAsB,GACtB,6BAA6B,GAC7B,wBAAwB,CAAC;AAE5B,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACrD;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,+BAA+B,EAAE,qBAQ7C,CAAC;AAiBF;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,uBAAuB,EACjC,MAAM,GAAE,qBAAuD,GAC7D,sBAAsB,CAwCxB","sourcesContent":["/**\n * Promotion gate for learned reasoning-router weights.\n *\n * The router already produces a feedback ledger (`router-feedback-collector.ts`)\n * and an offline calibration stack (`scripts/reasoning-router/`: calibration,\n * held-out evaluation, golden diffing, and McNemar's exact test). What was\n * missing is the decision policy that makes automatic promotion trustworthy:\n * without it the loop is open and every weight change is a judgement call.\n *\n * This module is that policy, as a pure total function. It deliberately refuses\n * to promote on anything short of unanimous evidence:\n *\n * - outcomes that survived a two-run replay, so a flipped measurement is never\n *   credited as a win (see `reasoning-router-replay-stability.ts`);\n * - a comparison against the frozen reference policy rather than an opponent\n *   the caller picked, which is what stops baseline shopping;\n * - a statistically significant win on the held-in gold set (McNemar's exact\n *   test), computed by the caller and passed in;\n * - enough discordant pairs for that test to mean anything;\n * - the candidate — not the baseline — winning those pairs;\n * - no accuracy regression on a held-out split the calibration never saw;\n * - no unreviewed behavior changes surfaced by golden diffing; and\n * - an explicit human approval.\n *\n * \"The agent tried again\" is not the same as \"the harness improved\", so a\n * candidate that merely fails to be worse is rejected, and malformed evidence\n * fails closed rather than defaulting to promotion.\n */\n\n/** Held-in McNemar outcome. Wins are counted in discordant pairs only. */\nexport interface RouterHeldInEvidence {\n\t/** Rows the baseline classified correctly and the candidate got wrong. */\n\treadonly baselineWins: number;\n\t/** Rows the candidate classified correctly and the baseline got wrong. */\n\treadonly candidateWins: number;\n\treadonly pValue: number;\n\treadonly significant: boolean;\n}\n\n/** Accuracy on a split withheld from calibration. */\nexport interface RouterHoldoutEvidence {\n\treadonly baselineCorrect: number;\n\treadonly candidateCorrect: number;\n\treadonly total: number;\n}\n\n/** How much of the evidence survived repeated identical replays. */\nexport interface RouterStabilityEvidence {\n\t/** Rows replayed under both policies, whatever bucket they landed in. */\n\treadonly evaluated: number;\n\t/** Rows withheld because repeated observations disagreed. */\n\treadonly unstable: number;\n\t/** Independent observations per row behind the credited outcomes. */\n\treadonly replays: number;\n}\n\n/**\n * What the candidate was measured against.\n *\n * `frozen_reference` is the shipped policy that learning never updates. A\n * candidate that only beats an opponent the caller chose has demonstrated\n * nothing, so the gate refuses to reason about `ad_hoc` comparisons.\n */\nexport type RouterBaselineKind = \"frozen_reference\" | \"ad_hoc\";\n\n/** Everything the gate is allowed to consider. */\nexport interface RouterPromotionEvidence {\n\treadonly heldIn: RouterHeldInEvidence;\n\treadonly holdout: RouterHoldoutEvidence;\n\t/** Replay agreement behind every credited outcome. */\n\treadonly stability: RouterStabilityEvidence;\n\t/** Which opponent produced `heldIn` and `holdout`. */\n\treadonly baselineKind: RouterBaselineKind;\n\t/** Golden-diff changes still unreviewed at decision time. */\n\treadonly goldenChanges: number;\n\t/** True only when a human explicitly approved this exact candidate. */\n\treadonly humanApproved: boolean;\n}\n\n/** Tunable thresholds. Loosening these can never authorize a regression. */\nexport interface RouterPromotionPolicy {\n\t/** Minimum discordant pairs before McNemar's verdict is trusted. */\n\treadonly minDiscordant: number;\n\t/** Minimum held-out rows before \"no regression\" is meaningful. */\n\treadonly minHoldout: number;\n\t/** Maximum unreviewed golden-diff changes tolerated. */\n\treadonly maxGoldenChanges: number;\n\t/** Independent replays required per row before any outcome carries credit. */\n\treadonly minReplays: number;\n\t/** Maximum rows allowed to disagree across replays. */\n\treadonly maxUnstable: number;\n\t/** Require the frozen reference policy as the comparison opponent. */\n\treadonly requireFrozenBaseline: boolean;\n\treadonly requireHumanApproval: boolean;\n}\n\nexport type RouterPromotionBlocker =\n\t| \"malformed_evidence\"\n\t| \"insufficient_replays\"\n\t| \"unstable_evidence\"\n\t| \"baseline_not_frozen\"\n\t| \"insufficient_discordant_pairs\"\n\t| \"mcnemar_not_significant\"\n\t| \"candidate_not_favored\"\n\t| \"holdout_regression\"\n\t| \"insufficient_holdout\"\n\t| \"unreviewed_behavior_changes\"\n\t| \"human_approval_missing\";\n\nexport interface RouterPromotionVerdict {\n\treadonly promote: boolean;\n\t/** Every independent reason promotion was refused, in evaluation order. */\n\treadonly blockers: readonly RouterPromotionBlocker[];\n}\n\n/**\n * Conservative defaults. `minDiscordant` of 20 keeps McNemar from ruling on a\n * handful of pairs; `maxGoldenChanges` of 0 means a reviewer accepts behavior\n * changes by regenerating the golden set, never by tolerating drift.\n *\n * `minHoldout` is 40 because the router gold set freezes 42 holdout rows (6 per\n * class × 7 classes). A higher bar would be unsatisfiable rather than strict,\n * and a gate that can never pass is a gate nobody runs.\n *\n * `minReplays` of 2 is the two-run rule: one observation cannot be checked for\n * stability at all. `maxUnstable` of 0 follows from what instability means here\n * — the routing path is deterministic, so a single disagreeing row is a defect\n * in the measurement, not an acceptable error rate to average over.\n */\nexport const DEFAULT_ROUTER_PROMOTION_POLICY: RouterPromotionPolicy = {\n\tmaxGoldenChanges: 0,\n\tmaxUnstable: 0,\n\tminDiscordant: 20,\n\tminHoldout: 40,\n\tminReplays: 2,\n\trequireFrozenBaseline: true,\n\trequireHumanApproval: true,\n};\n\nfunction isCount(value: number): boolean {\n\treturn Number.isFinite(value) && value >= 0;\n}\n\nfunction isMalformed(evidence: RouterPromotionEvidence): boolean {\n\tconst { goldenChanges, heldIn, holdout, stability } = evidence;\n\tif (!isCount(heldIn.baselineWins) || !isCount(heldIn.candidateWins)) return true;\n\tif (!Number.isFinite(heldIn.pValue) || heldIn.pValue < 0 || heldIn.pValue > 1) return true;\n\tif (!isCount(holdout.baselineCorrect) || !isCount(holdout.candidateCorrect) || !isCount(holdout.total)) return true;\n\tif (holdout.baselineCorrect > holdout.total || holdout.candidateCorrect > holdout.total) return true;\n\tif (!isCount(stability.evaluated) || !isCount(stability.unstable) || !isCount(stability.replays)) return true;\n\tif (stability.unstable > stability.evaluated) return true;\n\treturn !isCount(goldenChanges);\n}\n\n/**\n * Decide whether a candidate weight set may replace the active one.\n *\n * Returns every independent blocker rather than the first, so one calibration\n * run reports the full distance to promotion instead of revealing it one\n * rejection at a time. Malformed evidence short-circuits: the gate never\n * reasons about numbers it cannot trust.\n *\n * Evidence-integrity blockers are reported ahead of statistical ones. A p-value\n * computed over unstable rows or against the wrong opponent is not a weaker\n * result, it is a result about nothing, and the report should say so first.\n */\nexport function evaluateRouterPromotion(\n\tevidence: RouterPromotionEvidence,\n\tpolicy: RouterPromotionPolicy = DEFAULT_ROUTER_PROMOTION_POLICY,\n): RouterPromotionVerdict {\n\tif (isMalformed(evidence)) {\n\t\treturn { blockers: [\"malformed_evidence\"], promote: false };\n\t}\n\n\tconst { baselineKind, goldenChanges, heldIn, holdout, humanApproved, stability } = evidence;\n\tconst blockers: RouterPromotionBlocker[] = [];\n\n\tif (stability.replays < policy.minReplays) {\n\t\tblockers.push(\"insufficient_replays\");\n\t}\n\tif (stability.unstable > policy.maxUnstable) {\n\t\tblockers.push(\"unstable_evidence\");\n\t}\n\tif (policy.requireFrozenBaseline && baselineKind !== \"frozen_reference\") {\n\t\tblockers.push(\"baseline_not_frozen\");\n\t}\n\tif (heldIn.baselineWins + heldIn.candidateWins < policy.minDiscordant) {\n\t\tblockers.push(\"insufficient_discordant_pairs\");\n\t}\n\tif (!heldIn.significant) {\n\t\tblockers.push(\"mcnemar_not_significant\");\n\t}\n\tif (heldIn.candidateWins <= heldIn.baselineWins) {\n\t\tblockers.push(\"candidate_not_favored\");\n\t}\n\tif (holdout.total < policy.minHoldout) {\n\t\tblockers.push(\"insufficient_holdout\");\n\t}\n\tif (holdout.candidateCorrect < holdout.baselineCorrect) {\n\t\tblockers.push(\"holdout_regression\");\n\t}\n\tif (goldenChanges > policy.maxGoldenChanges) {\n\t\tblockers.push(\"unreviewed_behavior_changes\");\n\t}\n\tif (policy.requireHumanApproval && !humanApproved) {\n\t\tblockers.push(\"human_approval_missing\");\n\t}\n\n\treturn { blockers, promote: blockers.length === 0 };\n}\n"]}

package/dist/core/reasoning-router-promotion.js

@@ -10,6 +10,10 @@
  * This module is that policy, as a pure total function. It deliberately refuses
  * to promote on anything short of unanimous evidence:
  *
+ * - outcomes that survived a two-run replay, so a flipped measurement is never
+ *   credited as a win (see `reasoning-router-replay-stability.ts`);
+ * - a comparison against the frozen reference policy rather than an opponent
+ *   the caller picked, which is what stops baseline shopping;
  * - a statistically significant win on the held-in gold set (McNemar's exact
  *   test), computed by the caller and passed in;
  * - enough discordant pairs for that test to mean anything;
@@ -30,18 +34,26 @@
  * `minHoldout` is 40 because the router gold set freezes 42 holdout rows (6 per
  * class × 7 classes). A higher bar would be unsatisfiable rather than strict,
  * and a gate that can never pass is a gate nobody runs.
+ *
+ * `minReplays` of 2 is the two-run rule: one observation cannot be checked for
+ * stability at all. `maxUnstable` of 0 follows from what instability means here
+ * — the routing path is deterministic, so a single disagreeing row is a defect
+ * in the measurement, not an acceptable error rate to average over.
  */
 export const DEFAULT_ROUTER_PROMOTION_POLICY = {
     maxGoldenChanges: 0,
+    maxUnstable: 0,
     minDiscordant: 20,
     minHoldout: 40,
+    minReplays: 2,
+    requireFrozenBaseline: true,
     requireHumanApproval: true,
 };
 function isCount(value) {
     return Number.isFinite(value) && value >= 0;
 }
 function isMalformed(evidence) {
-    const { goldenChanges, heldIn, holdout } = evidence;
+    const { goldenChanges, heldIn, holdout, stability } = evidence;
     if (!isCount(heldIn.baselineWins) || !isCount(heldIn.candidateWins))
         return true;
     if (!Number.isFinite(heldIn.pValue) || heldIn.pValue < 0 || heldIn.pValue > 1)
@@ -50,6 +62,10 @@ function isMalformed(evidence) {
         return true;
     if (holdout.baselineCorrect > holdout.total || holdout.candidateCorrect > holdout.total)
         return true;
+    if (!isCount(stability.evaluated) || !isCount(stability.unstable) || !isCount(stability.replays))
+        return true;
+    if (stability.unstable > stability.evaluated)
+        return true;
     return !isCount(goldenChanges);
 }
 /**
@@ -59,13 +75,26 @@ function isMalformed(evidence) {
  * run reports the full distance to promotion instead of revealing it one
  * rejection at a time. Malformed evidence short-circuits: the gate never
  * reasons about numbers it cannot trust.
+ *
+ * Evidence-integrity blockers are reported ahead of statistical ones. A p-value
+ * computed over unstable rows or against the wrong opponent is not a weaker
+ * result, it is a result about nothing, and the report should say so first.
  */
 export function evaluateRouterPromotion(evidence, policy = DEFAULT_ROUTER_PROMOTION_POLICY) {
     if (isMalformed(evidence)) {
         return { blockers: ["malformed_evidence"], promote: false };
     }
-    const { goldenChanges, heldIn, holdout, humanApproved } = evidence;
+    const { baselineKind, goldenChanges, heldIn, holdout, humanApproved, stability } = evidence;
     const blockers = [];
+    if (stability.replays < policy.minReplays) {
+        blockers.push("insufficient_replays");
+    }
+    if (stability.unstable > policy.maxUnstable) {
+        blockers.push("unstable_evidence");
+    }
+    if (policy.requireFrozenBaseline && baselineKind !== "frozen_reference") {
+        blockers.push("baseline_not_frozen");
+    }
     if (heldIn.baselineWins + heldIn.candidateWins < policy.minDiscordant) {
         blockers.push("insufficient_discordant_pairs");
     }

package/dist/core/reasoning-router-promotion.js.map

@@ -1 +1 @@
-{"version":3,"file":"reasoning-router-promotion.js","sourceRoot":"","sources":["../../src/core/reasoning-router-promotion.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Promotion gate for learned reasoning-router weights.\n *\n * The router already produces a feedback ledger (`router-feedback-collector.ts`)\n * and an offline calibration stack (`scripts/reasoning-router/`: calibration,\n * held-out evaluation, golden diffing, and McNemar's exact test). What was\n * missing is the decision policy that makes automatic promotion trustworthy:\n * without it the loop is open and every weight change is a judgement call.\n *\n * This module is that policy, as a pure total function. It deliberately refuses\n * to promote on anything short of unanimous evidence:\n *\n * - a statistically significant win on the held-in gold set (McNemar's exact\n *   test), computed by the caller and passed in;\n * - enough discordant pairs for that test to mean anything;\n * - the candidate — not the baseline — winning those pairs;\n * - no accuracy regression on a held-out split the calibration never saw;\n * - no unreviewed behavior changes surfaced by golden diffing; and\n * - an explicit human approval.\n *\n * \"The agent tried again\" is not the same as \"the harness improved\", so a\n * candidate that merely fails to be worse is rejected, and malformed evidence\n * fails closed rather than defaulting to promotion.\n */\n\n/** Held-in McNemar outcome. Wins are counted in discordant pairs only. */\nexport interface RouterHeldInEvidence {\n\t/** Rows the baseline classified correctly and the candidate got wrong. */\n\treadonly baselineWins: number;\n\t/** Rows the candidate classified correctly and the baseline got wrong. */\n\treadonly candidateWins: number;\n\treadonly pValue: number;\n\treadonly significant: boolean;\n}\n\n/** Accuracy on a split withheld from calibration. */\nexport interface RouterHoldoutEvidence {\n\treadonly baselineCorrect: number;\n\treadonly candidateCorrect: number;\n\treadonly total: number;\n}\n\n/** Everything the gate is allowed to consider. */\nexport interface RouterPromotionEvidence {\n\treadonly heldIn: RouterHeldInEvidence;\n\treadonly holdout: RouterHoldoutEvidence;\n\t/** Golden-diff changes still unreviewed at decision time. */\n\treadonly goldenChanges: number;\n\t/** True only when a human explicitly approved this exact candidate. */\n\treadonly humanApproved: boolean;\n}\n\n/** Tunable thresholds. Loosening these can never authorize a regression. */\nexport interface RouterPromotionPolicy {\n\t/** Minimum discordant pairs before McNemar's verdict is trusted. */\n\treadonly minDiscordant: number;\n\t/** Minimum held-out rows before \"no regression\" is meaningful. */\n\treadonly minHoldout: number;\n\t/** Maximum unreviewed golden-diff changes tolerated. */\n\treadonly maxGoldenChanges: number;\n\treadonly requireHumanApproval: boolean;\n}\n\nexport type RouterPromotionBlocker =\n\t| \"malformed_evidence\"\n\t| \"insufficient_discordant_pairs\"\n\t| \"mcnemar_not_significant\"\n\t| \"candidate_not_favored\"\n\t| \"holdout_regression\"\n\t| \"insufficient_holdout\"\n\t| \"unreviewed_behavior_changes\"\n\t| \"human_approval_missing\";\n\nexport interface RouterPromotionVerdict {\n\treadonly promote: boolean;\n\t/** Every independent reason promotion was refused, in evaluation order. */\n\treadonly blockers: readonly RouterPromotionBlocker[];\n}\n\n/**\n * Conservative defaults. `minDiscordant` of 20 keeps McNemar from ruling on a\n * handful of pairs; `maxGoldenChanges` of 0 means a reviewer accepts behavior\n * changes by regenerating the golden set, never by tolerating drift.\n *\n * `minHoldout` is 40 because the router gold set freezes 42 holdout rows (6 per\n * class × 7 classes). A higher bar would be unsatisfiable rather than strict,\n * and a gate that can never pass is a gate nobody runs.\n */\nexport const DEFAULT_ROUTER_PROMOTION_POLICY: RouterPromotionPolicy = {\n\tmaxGoldenChanges: 0,\n\tminDiscordant: 20,\n\tminHoldout: 40,\n\trequireHumanApproval: true,\n};\n\nfunction isCount(value: number): boolean {\n\treturn Number.isFinite(value) && value >= 0;\n}\n\nfunction isMalformed(evidence: RouterPromotionEvidence): boolean {\n\tconst { goldenChanges, heldIn, holdout } = evidence;\n\tif (!isCount(heldIn.baselineWins) || !isCount(heldIn.candidateWins)) return true;\n\tif (!Number.isFinite(heldIn.pValue) || heldIn.pValue < 0 || heldIn.pValue > 1) return true;\n\tif (!isCount(holdout.baselineCorrect) || !isCount(holdout.candidateCorrect) || !isCount(holdout.total)) return true;\n\tif (holdout.baselineCorrect > holdout.total || holdout.candidateCorrect > holdout.total) return true;\n\treturn !isCount(goldenChanges);\n}\n\n/**\n * Decide whether a candidate weight set may replace the active one.\n *\n * Returns every independent blocker rather than the first, so one calibration\n * run reports the full distance to promotion instead of revealing it one\n * rejection at a time. Malformed evidence short-circuits: the gate never\n * reasons about numbers it cannot trust.\n */\nexport function evaluateRouterPromotion(\n\tevidence: RouterPromotionEvidence,\n\tpolicy: RouterPromotionPolicy = DEFAULT_ROUTER_PROMOTION_POLICY,\n): RouterPromotionVerdict {\n\tif (isMalformed(evidence)) {\n\t\treturn { blockers: [\"malformed_evidence\"], promote: false };\n\t}\n\n\tconst { goldenChanges, heldIn, holdout, humanApproved } = evidence;\n\tconst blockers: RouterPromotionBlocker[] = [];\n\n\tif (heldIn.baselineWins + heldIn.candidateWins < policy.minDiscordant) {\n\t\tblockers.push(\"insufficient_discordant_pairs\");\n\t}\n\tif (!heldIn.significant) {\n\t\tblockers.push(\"mcnemar_not_significant\");\n\t}\n\tif (heldIn.candidateWins <= heldIn.baselineWins) {\n\t\tblockers.push(\"candidate_not_favored\");\n\t}\n\tif (holdout.total < policy.minHoldout) {\n\t\tblockers.push(\"insufficient_holdout\");\n\t}\n\tif (holdout.candidateCorrect < holdout.baselineCorrect) {\n\t\tblockers.push(\"holdout_regression\");\n\t}\n\tif (goldenChanges > policy.maxGoldenChanges) {\n\t\tblockers.push(\"unreviewed_behavior_changes\");\n\t}\n\tif (policy.requireHumanApproval && !humanApproved) {\n\t\tblockers.push(\"human_approval_missing\");\n\t}\n\n\treturn { blockers, promote: blockers.length === 0 };\n}\n"]}
+{"version":3,"file":"reasoning-router-promotion.js","sourceRoot":"","sources":["../../src/core/reasoning-router-promotion.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Promotion gate for learned reasoning-router weights.\n *\n * The router already produces a feedback ledger (`router-feedback-collector.ts`)\n * and an offline calibration stack (`scripts/reasoning-router/`: calibration,\n * held-out evaluation, golden diffing, and McNemar's exact test). What was\n * missing is the decision policy that makes automatic promotion trustworthy:\n * without it the loop is open and every weight change is a judgement call.\n *\n * This module is that policy, as a pure total function. It deliberately refuses\n * to promote on anything short of unanimous evidence:\n *\n * - outcomes that survived a two-run replay, so a flipped measurement is never\n *   credited as a win (see `reasoning-router-replay-stability.ts`);\n * - a comparison against the frozen reference policy rather than an opponent\n *   the caller picked, which is what stops baseline shopping;\n * - a statistically significant win on the held-in gold set (McNemar's exact\n *   test), computed by the caller and passed in;\n * - enough discordant pairs for that test to mean anything;\n * - the candidate — not the baseline — winning those pairs;\n * - no accuracy regression on a held-out split the calibration never saw;\n * - no unreviewed behavior changes surfaced by golden diffing; and\n * - an explicit human approval.\n *\n * \"The agent tried again\" is not the same as \"the harness improved\", so a\n * candidate that merely fails to be worse is rejected, and malformed evidence\n * fails closed rather than defaulting to promotion.\n */\n\n/** Held-in McNemar outcome. Wins are counted in discordant pairs only. */\nexport interface RouterHeldInEvidence {\n\t/** Rows the baseline classified correctly and the candidate got wrong. */\n\treadonly baselineWins: number;\n\t/** Rows the candidate classified correctly and the baseline got wrong. */\n\treadonly candidateWins: number;\n\treadonly pValue: number;\n\treadonly significant: boolean;\n}\n\n/** Accuracy on a split withheld from calibration. */\nexport interface RouterHoldoutEvidence {\n\treadonly baselineCorrect: number;\n\treadonly candidateCorrect: number;\n\treadonly total: number;\n}\n\n/** How much of the evidence survived repeated identical replays. */\nexport interface RouterStabilityEvidence {\n\t/** Rows replayed under both policies, whatever bucket they landed in. */\n\treadonly evaluated: number;\n\t/** Rows withheld because repeated observations disagreed. */\n\treadonly unstable: number;\n\t/** Independent observations per row behind the credited outcomes. */\n\treadonly replays: number;\n}\n\n/**\n * What the candidate was measured against.\n *\n * `frozen_reference` is the shipped policy that learning never updates. A\n * candidate that only beats an opponent the caller chose has demonstrated\n * nothing, so the gate refuses to reason about `ad_hoc` comparisons.\n */\nexport type RouterBaselineKind = \"frozen_reference\" | \"ad_hoc\";\n\n/** Everything the gate is allowed to consider. */\nexport interface RouterPromotionEvidence {\n\treadonly heldIn: RouterHeldInEvidence;\n\treadonly holdout: RouterHoldoutEvidence;\n\t/** Replay agreement behind every credited outcome. */\n\treadonly stability: RouterStabilityEvidence;\n\t/** Which opponent produced `heldIn` and `holdout`. */\n\treadonly baselineKind: RouterBaselineKind;\n\t/** Golden-diff changes still unreviewed at decision time. */\n\treadonly goldenChanges: number;\n\t/** True only when a human explicitly approved this exact candidate. */\n\treadonly humanApproved: boolean;\n}\n\n/** Tunable thresholds. Loosening these can never authorize a regression. */\nexport interface RouterPromotionPolicy {\n\t/** Minimum discordant pairs before McNemar's verdict is trusted. */\n\treadonly minDiscordant: number;\n\t/** Minimum held-out rows before \"no regression\" is meaningful. */\n\treadonly minHoldout: number;\n\t/** Maximum unreviewed golden-diff changes tolerated. */\n\treadonly maxGoldenChanges: number;\n\t/** Independent replays required per row before any outcome carries credit. */\n\treadonly minReplays: number;\n\t/** Maximum rows allowed to disagree across replays. */\n\treadonly maxUnstable: number;\n\t/** Require the frozen reference policy as the comparison opponent. */\n\treadonly requireFrozenBaseline: boolean;\n\treadonly requireHumanApproval: boolean;\n}\n\nexport type RouterPromotionBlocker =\n\t| \"malformed_evidence\"\n\t| \"insufficient_replays\"\n\t| \"unstable_evidence\"\n\t| \"baseline_not_frozen\"\n\t| \"insufficient_discordant_pairs\"\n\t| \"mcnemar_not_significant\"\n\t| \"candidate_not_favored\"\n\t| \"holdout_regression\"\n\t| \"insufficient_holdout\"\n\t| \"unreviewed_behavior_changes\"\n\t| \"human_approval_missing\";\n\nexport interface RouterPromotionVerdict {\n\treadonly promote: boolean;\n\t/** Every independent reason promotion was refused, in evaluation order. */\n\treadonly blockers: readonly RouterPromotionBlocker[];\n}\n\n/**\n * Conservative defaults. `minDiscordant` of 20 keeps McNemar from ruling on a\n * handful of pairs; `maxGoldenChanges` of 0 means a reviewer accepts behavior\n * changes by regenerating the golden set, never by tolerating drift.\n *\n * `minHoldout` is 40 because the router gold set freezes 42 holdout rows (6 per\n * class × 7 classes). A higher bar would be unsatisfiable rather than strict,\n * and a gate that can never pass is a gate nobody runs.\n *\n * `minReplays` of 2 is the two-run rule: one observation cannot be checked for\n * stability at all. `maxUnstable` of 0 follows from what instability means here\n * — the routing path is deterministic, so a single disagreeing row is a defect\n * in the measurement, not an acceptable error rate to average over.\n */\nexport const DEFAULT_ROUTER_PROMOTION_POLICY: RouterPromotionPolicy = {\n\tmaxGoldenChanges: 0,\n\tmaxUnstable: 0,\n\tminDiscordant: 20,\n\tminHoldout: 40,\n\tminReplays: 2,\n\trequireFrozenBaseline: true,\n\trequireHumanApproval: true,\n};\n\nfunction isCount(value: number): boolean {\n\treturn Number.isFinite(value) && value >= 0;\n}\n\nfunction isMalformed(evidence: RouterPromotionEvidence): boolean {\n\tconst { goldenChanges, heldIn, holdout, stability } = evidence;\n\tif (!isCount(heldIn.baselineWins) || !isCount(heldIn.candidateWins)) return true;\n\tif (!Number.isFinite(heldIn.pValue) || heldIn.pValue < 0 || heldIn.pValue > 1) return true;\n\tif (!isCount(holdout.baselineCorrect) || !isCount(holdout.candidateCorrect) || !isCount(holdout.total)) return true;\n\tif (holdout.baselineCorrect > holdout.total || holdout.candidateCorrect > holdout.total) return true;\n\tif (!isCount(stability.evaluated) || !isCount(stability.unstable) || !isCount(stability.replays)) return true;\n\tif (stability.unstable > stability.evaluated) return true;\n\treturn !isCount(goldenChanges);\n}\n\n/**\n * Decide whether a candidate weight set may replace the active one.\n *\n * Returns every independent blocker rather than the first, so one calibration\n * run reports the full distance to promotion instead of revealing it one\n * rejection at a time. Malformed evidence short-circuits: the gate never\n * reasons about numbers it cannot trust.\n *\n * Evidence-integrity blockers are reported ahead of statistical ones. A p-value\n * computed over unstable rows or against the wrong opponent is not a weaker\n * result, it is a result about nothing, and the report should say so first.\n */\nexport function evaluateRouterPromotion(\n\tevidence: RouterPromotionEvidence,\n\tpolicy: RouterPromotionPolicy = DEFAULT_ROUTER_PROMOTION_POLICY,\n): RouterPromotionVerdict {\n\tif (isMalformed(evidence)) {\n\t\treturn { blockers: [\"malformed_evidence\"], promote: false };\n\t}\n\n\tconst { baselineKind, goldenChanges, heldIn, holdout, humanApproved, stability } = evidence;\n\tconst blockers: RouterPromotionBlocker[] = [];\n\n\tif (stability.replays < policy.minReplays) {\n\t\tblockers.push(\"insufficient_replays\");\n\t}\n\tif (stability.unstable > policy.maxUnstable) {\n\t\tblockers.push(\"unstable_evidence\");\n\t}\n\tif (policy.requireFrozenBaseline && baselineKind !== \"frozen_reference\") {\n\t\tblockers.push(\"baseline_not_frozen\");\n\t}\n\tif (heldIn.baselineWins + heldIn.candidateWins < policy.minDiscordant) {\n\t\tblockers.push(\"insufficient_discordant_pairs\");\n\t}\n\tif (!heldIn.significant) {\n\t\tblockers.push(\"mcnemar_not_significant\");\n\t}\n\tif (heldIn.candidateWins <= heldIn.baselineWins) {\n\t\tblockers.push(\"candidate_not_favored\");\n\t}\n\tif (holdout.total < policy.minHoldout) {\n\t\tblockers.push(\"insufficient_holdout\");\n\t}\n\tif (holdout.candidateCorrect < holdout.baselineCorrect) {\n\t\tblockers.push(\"holdout_regression\");\n\t}\n\tif (goldenChanges > policy.maxGoldenChanges) {\n\t\tblockers.push(\"unreviewed_behavior_changes\");\n\t}\n\tif (policy.requireHumanApproval && !humanApproved) {\n\t\tblockers.push(\"human_approval_missing\");\n\t}\n\n\treturn { blockers, promote: blockers.length === 0 };\n}\n"]}

package/dist/core/reasoning-router-replay-stability.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Two-run stability filter for reasoning-router promotion evidence.
+ *
+ * A promotion gate is only as trustworthy as the outcomes it credits. Routing
+ * evaluations are paired comparisons, and paired comparisons are cheap to fool:
+ * if the measured outcome of a row can flip between two identical replays, then
+ * a "win" on that row may be measurement noise rather than a better policy.
+ * Published routing evaluations report exactly this — a non-trivial share of
+ * model/question pairs score differently when the identical matrix is re-run —
+ * so a credit rule that ignores rerun disagreement will happily promote noise.
+ *
+ * This module implements the rule that closes that hole: a row carries credit
+ * only when it was observed at least `minReplays` times under each policy and
+ * every one of those observations agreed. Rows that disagree are withheld, not
+ * majority-voted — a flipped observation means the measurement is unreliable,
+ * not that the majority is the truth.
+ *
+ * For a deterministic classifier every row is stable by construction, so the
+ * filter is also a determinism attestation: if nondeterminism ever leaks into
+ * the routing path (iteration order, clock, randomness), rows start landing in
+ * the unstable bucket and the gate refuses to promote instead of crediting a
+ * coin flip.
+ *
+ * Pure and total: no I/O, no global state, no prompt text.
+ */
+/** Independent observations required per side before a row may carry credit. */
+export declare const DEFAULT_REPLAY_MIN = 2;
+/** One evaluated row, replayed independently under each policy. */
+export interface RouterReplayRow {
+    readonly rowId: string;
+    /** True when the row belongs to the frozen held-out split. */
+    readonly holdout: boolean;
+    /** Correctness observed on each independent replay under the baseline. */
+    readonly baselineReplays: readonly boolean[];
+    /** Correctness observed on each independent replay under the candidate. */
+    readonly candidateReplays: readonly boolean[];
+}
+/** A row whose replays agreed, so its outcome may carry promotion credit. */
+export interface RouterStableOutcome {
+    readonly rowId: string;
+    readonly holdout: boolean;
+    readonly baselineCorrect: boolean;
+    readonly candidateCorrect: boolean;
+}
+/** Credit-eligible outcomes plus why every other row was withheld. */
+export interface RouterReplayStability {
+    readonly stable: readonly RouterStableOutcome[];
+    /** Rows considered, whatever bucket they landed in. */
+    readonly evaluated: number;
+    /** Rows withheld because repeated observations disagreed. */
+    readonly unstable: number;
+    /** Rows withheld because one side was observed too few times to judge. */
+    readonly insufficientReplays: number;
+    readonly minReplays: number;
+}
+/**
+ * Partition replayed rows into credit-eligible outcomes and withheld rows.
+ *
+ * Insufficient replays outrank disagreement: a row observed once is not stable
+ * evidence that happens to agree with itself, it is evidence that was never
+ * tested for stability at all. Reporting the two buckets separately keeps that
+ * distinction visible to the gate, which fails closed on either.
+ */
+export declare function summarizeReplayStability(rows: readonly RouterReplayRow[], minReplays?: number): RouterReplayStability;
+//# sourceMappingURL=reasoning-router-replay-stability.d.ts.map

package/dist/core/reasoning-router-replay-stability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-router-replay-stability.d.ts","sourceRoot":"","sources":["../../src/core/reasoning-router-replay-stability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7C,2EAA2E;IAC3E,QAAQ,CAAC,gBAAgB,EAAE,SAAS,OAAO,EAAE,CAAC;CAC9C;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACnC;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAChD,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAgBD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACvC,IAAI,EAAE,SAAS,eAAe,EAAE,EAChC,UAAU,GAAE,MAA2B,GACrC,qBAAqB,CA2BvB","sourcesContent":["/**\n * Two-run stability filter for reasoning-router promotion evidence.\n *\n * A promotion gate is only as trustworthy as the outcomes it credits. Routing\n * evaluations are paired comparisons, and paired comparisons are cheap to fool:\n * if the measured outcome of a row can flip between two identical replays, then\n * a \"win\" on that row may be measurement noise rather than a better policy.\n * Published routing evaluations report exactly this — a non-trivial share of\n * model/question pairs score differently when the identical matrix is re-run —\n * so a credit rule that ignores rerun disagreement will happily promote noise.\n *\n * This module implements the rule that closes that hole: a row carries credit\n * only when it was observed at least `minReplays` times under each policy and\n * every one of those observations agreed. Rows that disagree are withheld, not\n * majority-voted — a flipped observation means the measurement is unreliable,\n * not that the majority is the truth.\n *\n * For a deterministic classifier every row is stable by construction, so the\n * filter is also a determinism attestation: if nondeterminism ever leaks into\n * the routing path (iteration order, clock, randomness), rows start landing in\n * the unstable bucket and the gate refuses to promote instead of crediting a\n * coin flip.\n *\n * Pure and total: no I/O, no global state, no prompt text.\n */\n\n/** Independent observations required per side before a row may carry credit. */\nexport const DEFAULT_REPLAY_MIN = 2;\n\n/** One evaluated row, replayed independently under each policy. */\nexport interface RouterReplayRow {\n\treadonly rowId: string;\n\t/** True when the row belongs to the frozen held-out split. */\n\treadonly holdout: boolean;\n\t/** Correctness observed on each independent replay under the baseline. */\n\treadonly baselineReplays: readonly boolean[];\n\t/** Correctness observed on each independent replay under the candidate. */\n\treadonly candidateReplays: readonly boolean[];\n}\n\n/** A row whose replays agreed, so its outcome may carry promotion credit. */\nexport interface RouterStableOutcome {\n\treadonly rowId: string;\n\treadonly holdout: boolean;\n\treadonly baselineCorrect: boolean;\n\treadonly candidateCorrect: boolean;\n}\n\n/** Credit-eligible outcomes plus why every other row was withheld. */\nexport interface RouterReplayStability {\n\treadonly stable: readonly RouterStableOutcome[];\n\t/** Rows considered, whatever bucket they landed in. */\n\treadonly evaluated: number;\n\t/** Rows withheld because repeated observations disagreed. */\n\treadonly unstable: number;\n\t/** Rows withheld because one side was observed too few times to judge. */\n\treadonly insufficientReplays: number;\n\treadonly minReplays: number;\n}\n\n/** Verdict for one side of one row. */\ntype ReplayVerdict =\n\t| { readonly kind: \"agreed\"; readonly correct: boolean }\n\t| { readonly kind: \"disagreed\" }\n\t| { readonly kind: \"insufficient\" };\n\nfunction judgeReplays(replays: readonly boolean[], minReplays: number): ReplayVerdict {\n\tconst [first, ...rest] = replays;\n\tif (first === undefined || replays.length < minReplays) {\n\t\treturn { kind: \"insufficient\" };\n\t}\n\treturn rest.every((replay) => replay === first) ? { correct: first, kind: \"agreed\" } : { kind: \"disagreed\" };\n}\n\n/**\n * Partition replayed rows into credit-eligible outcomes and withheld rows.\n *\n * Insufficient replays outrank disagreement: a row observed once is not stable\n * evidence that happens to agree with itself, it is evidence that was never\n * tested for stability at all. Reporting the two buckets separately keeps that\n * distinction visible to the gate, which fails closed on either.\n */\nexport function summarizeReplayStability(\n\trows: readonly RouterReplayRow[],\n\tminReplays: number = DEFAULT_REPLAY_MIN,\n): RouterReplayStability {\n\tconst stable: RouterStableOutcome[] = [];\n\tlet unstable = 0;\n\tlet insufficientReplays = 0;\n\n\tfor (const row of rows) {\n\t\tconst baseline = judgeReplays(row.baselineReplays, minReplays);\n\t\tconst candidate = judgeReplays(row.candidateReplays, minReplays);\n\n\t\tif (baseline.kind === \"insufficient\" || candidate.kind === \"insufficient\") {\n\t\t\tinsufficientReplays++;\n\t\t\tcontinue;\n\t\t}\n\t\tif (baseline.kind === \"disagreed\" || candidate.kind === \"disagreed\") {\n\t\t\tunstable++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tstable.push({\n\t\t\tbaselineCorrect: baseline.correct,\n\t\t\tcandidateCorrect: candidate.correct,\n\t\t\tholdout: row.holdout,\n\t\t\trowId: row.rowId,\n\t\t});\n\t}\n\n\treturn { evaluated: rows.length, insufficientReplays, minReplays, stable, unstable };\n}\n"]}

package/dist/core/reasoning-router-replay-stability.js

@@ -0,0 +1,67 @@
+/**
+ * Two-run stability filter for reasoning-router promotion evidence.
+ *
+ * A promotion gate is only as trustworthy as the outcomes it credits. Routing
+ * evaluations are paired comparisons, and paired comparisons are cheap to fool:
+ * if the measured outcome of a row can flip between two identical replays, then
+ * a "win" on that row may be measurement noise rather than a better policy.
+ * Published routing evaluations report exactly this — a non-trivial share of
+ * model/question pairs score differently when the identical matrix is re-run —
+ * so a credit rule that ignores rerun disagreement will happily promote noise.
+ *
+ * This module implements the rule that closes that hole: a row carries credit
+ * only when it was observed at least `minReplays` times under each policy and
+ * every one of those observations agreed. Rows that disagree are withheld, not
+ * majority-voted — a flipped observation means the measurement is unreliable,
+ * not that the majority is the truth.
+ *
+ * For a deterministic classifier every row is stable by construction, so the
+ * filter is also a determinism attestation: if nondeterminism ever leaks into
+ * the routing path (iteration order, clock, randomness), rows start landing in
+ * the unstable bucket and the gate refuses to promote instead of crediting a
+ * coin flip.
+ *
+ * Pure and total: no I/O, no global state, no prompt text.
+ */
+/** Independent observations required per side before a row may carry credit. */
+export const DEFAULT_REPLAY_MIN = 2;
+function judgeReplays(replays, minReplays) {
+    const [first, ...rest] = replays;
+    if (first === undefined || replays.length < minReplays) {
+        return { kind: "insufficient" };
+    }
+    return rest.every((replay) => replay === first) ? { correct: first, kind: "agreed" } : { kind: "disagreed" };
+}
+/**
+ * Partition replayed rows into credit-eligible outcomes and withheld rows.
+ *
+ * Insufficient replays outrank disagreement: a row observed once is not stable
+ * evidence that happens to agree with itself, it is evidence that was never
+ * tested for stability at all. Reporting the two buckets separately keeps that
+ * distinction visible to the gate, which fails closed on either.
+ */
+export function summarizeReplayStability(rows, minReplays = DEFAULT_REPLAY_MIN) {
+    const stable = [];
+    let unstable = 0;
+    let insufficientReplays = 0;
+    for (const row of rows) {
+        const baseline = judgeReplays(row.baselineReplays, minReplays);
+        const candidate = judgeReplays(row.candidateReplays, minReplays);
+        if (baseline.kind === "insufficient" || candidate.kind === "insufficient") {
+            insufficientReplays++;
+            continue;
+        }
+        if (baseline.kind === "disagreed" || candidate.kind === "disagreed") {
+            unstable++;
+            continue;
+        }
+        stable.push({
+            baselineCorrect: baseline.correct,
+            candidateCorrect: candidate.correct,
+            holdout: row.holdout,
+            rowId: row.rowId,
+        });
+    }
+    return { evaluated: rows.length, insufficientReplays, minReplays, stable, unstable };
+}
+//# sourceMappingURL=reasoning-router-replay-stability.js.map

package/dist/core/reasoning-router-replay-stability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-router-replay-stability.js","sourceRoot":"","sources":["../../src/core/reasoning-router-replay-stability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAuCpC,SAAS,YAAY,CAAC,OAA2B,EAAE,UAAkB,EAAiB;IACrF,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC;IACjC,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;QACxD,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IACjC,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AAAA,CAC7G;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACvC,IAAgC,EAChC,UAAU,GAAW,kBAAkB,EACf;IACxB,MAAM,MAAM,GAA0B,EAAE,CAAC;IACzC,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,mBAAmB,GAAG,CAAC,CAAC;IAE5B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;QAC/D,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC;QAEjE,IAAI,QAAQ,CAAC,IAAI,KAAK,cAAc,IAAI,SAAS,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YAC3E,mBAAmB,EAAE,CAAC;YACtB,SAAS;QACV,CAAC;QACD,IAAI,QAAQ,CAAC,IAAI,KAAK,WAAW,IAAI,SAAS,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACrE,QAAQ,EAAE,CAAC;YACX,SAAS;QACV,CAAC;QAED,MAAM,CAAC,IAAI,CAAC;YACX,eAAe,EAAE,QAAQ,CAAC,OAAO;YACjC,gBAAgB,EAAE,SAAS,CAAC,OAAO;YACnC,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,KAAK,EAAE,GAAG,CAAC,KAAK;SAChB,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAAA,CACrF","sourcesContent":["/**\n * Two-run stability filter for reasoning-router promotion evidence.\n *\n * A promotion gate is only as trustworthy as the outcomes it credits. Routing\n * evaluations are paired comparisons, and paired comparisons are cheap to fool:\n * if the measured outcome of a row can flip between two identical replays, then\n * a \"win\" on that row may be measurement noise rather than a better policy.\n * Published routing evaluations report exactly this — a non-trivial share of\n * model/question pairs score differently when the identical matrix is re-run —\n * so a credit rule that ignores rerun disagreement will happily promote noise.\n *\n * This module implements the rule that closes that hole: a row carries credit\n * only when it was observed at least `minReplays` times under each policy and\n * every one of those observations agreed. Rows that disagree are withheld, not\n * majority-voted — a flipped observation means the measurement is unreliable,\n * not that the majority is the truth.\n *\n * For a deterministic classifier every row is stable by construction, so the\n * filter is also a determinism attestation: if nondeterminism ever leaks into\n * the routing path (iteration order, clock, randomness), rows start landing in\n * the unstable bucket and the gate refuses to promote instead of crediting a\n * coin flip.\n *\n * Pure and total: no I/O, no global state, no prompt text.\n */\n\n/** Independent observations required per side before a row may carry credit. */\nexport const DEFAULT_REPLAY_MIN = 2;\n\n/** One evaluated row, replayed independently under each policy. */\nexport interface RouterReplayRow {\n\treadonly rowId: string;\n\t/** True when the row belongs to the frozen held-out split. */\n\treadonly holdout: boolean;\n\t/** Correctness observed on each independent replay under the baseline. */\n\treadonly baselineReplays: readonly boolean[];\n\t/** Correctness observed on each independent replay under the candidate. */\n\treadonly candidateReplays: readonly boolean[];\n}\n\n/** A row whose replays agreed, so its outcome may carry promotion credit. */\nexport interface RouterStableOutcome {\n\treadonly rowId: string;\n\treadonly holdout: boolean;\n\treadonly baselineCorrect: boolean;\n\treadonly candidateCorrect: boolean;\n}\n\n/** Credit-eligible outcomes plus why every other row was withheld. */\nexport interface RouterReplayStability {\n\treadonly stable: readonly RouterStableOutcome[];\n\t/** Rows considered, whatever bucket they landed in. */\n\treadonly evaluated: number;\n\t/** Rows withheld because repeated observations disagreed. */\n\treadonly unstable: number;\n\t/** Rows withheld because one side was observed too few times to judge. */\n\treadonly insufficientReplays: number;\n\treadonly minReplays: number;\n}\n\n/** Verdict for one side of one row. */\ntype ReplayVerdict =\n\t| { readonly kind: \"agreed\"; readonly correct: boolean }\n\t| { readonly kind: \"disagreed\" }\n\t| { readonly kind: \"insufficient\" };\n\nfunction judgeReplays(replays: readonly boolean[], minReplays: number): ReplayVerdict {\n\tconst [first, ...rest] = replays;\n\tif (first === undefined || replays.length < minReplays) {\n\t\treturn { kind: \"insufficient\" };\n\t}\n\treturn rest.every((replay) => replay === first) ? { correct: first, kind: \"agreed\" } : { kind: \"disagreed\" };\n}\n\n/**\n * Partition replayed rows into credit-eligible outcomes and withheld rows.\n *\n * Insufficient replays outrank disagreement: a row observed once is not stable\n * evidence that happens to agree with itself, it is evidence that was never\n * tested for stability at all. Reporting the two buckets separately keeps that\n * distinction visible to the gate, which fails closed on either.\n */\nexport function summarizeReplayStability(\n\trows: readonly RouterReplayRow[],\n\tminReplays: number = DEFAULT_REPLAY_MIN,\n): RouterReplayStability {\n\tconst stable: RouterStableOutcome[] = [];\n\tlet unstable = 0;\n\tlet insufficientReplays = 0;\n\n\tfor (const row of rows) {\n\t\tconst baseline = judgeReplays(row.baselineReplays, minReplays);\n\t\tconst candidate = judgeReplays(row.candidateReplays, minReplays);\n\n\t\tif (baseline.kind === \"insufficient\" || candidate.kind === \"insufficient\") {\n\t\t\tinsufficientReplays++;\n\t\t\tcontinue;\n\t\t}\n\t\tif (baseline.kind === \"disagreed\" || candidate.kind === \"disagreed\") {\n\t\t\tunstable++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tstable.push({\n\t\t\tbaselineCorrect: baseline.correct,\n\t\t\tcandidateCorrect: candidate.correct,\n\t\t\tholdout: row.holdout,\n\t\t\trowId: row.rowId,\n\t\t});\n\t}\n\n\treturn { evaluated: rows.length, insufficientReplays, minReplays, stable, unstable };\n}\n"]}

package/dist/core/reasoning-router-v4-weights.d.ts

@@ -64,11 +64,11 @@ export interface RouterWeightsV4 {
     readonly intentSkeleton: number;
     /** Bump to "code-gen" for a bare "add" keyword, gated by !localEdit. */
     readonly addKeyword: number;
-    /** Bump to the class matching `history[0]`, if supplied (v4-new; 0 under DEFAULT_WEIGHTS_V4, inert until calibrated). */
+    /** Bump to the class matching `history[0]`, if supplied (default 2; gated on existing prompt evidence). */
     readonly multiTurnPrior: number;
-    /** Linear per-bucket bump applied to debug/review/plan under context pressure (v4-new; 0 under DEFAULT_WEIGHTS_V4, inert until calibrated). */
+    /** Linear per-bucket bump applied to debug/review/plan under context pressure (default 1). */
     readonly pressureBucket: number;
-    /** Bump to the class matching an externally supplied judge vote, if any (v4-new; 0 under DEFAULT_WEIGHTS_V4, inert until calibrated). */
+    /** Bump to an externally supplied judge vote, if any (default 2; gated on existing prompt evidence). */
     readonly judgeVote: number;
     /** Bounded look-back window (characters) for negation-cue gating, never crossing a .,;!? boundary. */
     readonly negationWindowChars: number;
@@ -80,9 +80,9 @@ export interface RouterWeightsV4 {
 /**
  * Calibrated default preset. The named weights below are the production v4
  * scorer configuration covered by
- * test/suite/regressions/013-reasoning-router-v4-accuracy.test.ts. Extension
- * fields (`multiTurnPrior`, `pressureBucket`, `judgeVote`) are wired but inert
- * until a future calibration changes them.
+ * test/suite/regressions/013-reasoning-router-v4-accuracy.test.ts. The bounded
+ * extension fields (`multiTurnPrior`, `pressureBucket`, `judgeVote`) are active
+ * only after the base scorer finds prompt evidence; zero-score fallbacks ignore them.
  */
 export declare const DEFAULT_WEIGHTS_V4: RouterWeightsV4;
 //# sourceMappingURL=reasoning-router-v4-weights.d.ts.map