open-multi-agent-kit 0.99.0 → 1.2.0

package/dist/metacognition/policy.js

@@ -0,0 +1,155 @@
+/**
+ * Algorithm F — bounded metacontrol policy. Spec §9, §14.
+ *
+ * Feasibility precedes optimization: an action that is unauthorized, missing
+ * prerequisites, over budget, or out of scope is absent from the feasible set
+ * no matter how much information it promises. The baseline policy is the
+ * explicit priority table of §14, not a score-sum that folds safety
+ * constraints into a utility number.
+ */
+import { experimentValue } from "./decision.js";
+import { isStagnant, netSwitchValue, progressKey } from "./verifier.js";
+const ALL_KINDS = [
+    "inspect_local",
+    "retrieve_reference",
+    "run_discriminating_probe",
+    "strengthen_verifier",
+    "reselect_skills",
+    "revise_implementation",
+    "switch_strategy",
+    "request_required_decision",
+    "continue_object_work",
+    "finish_with_bound_receipt",
+    "stop_inconclusive",
+    "settle_safety",
+    "form_obligations",
+];
+/** §9.2: Authorized ∧ Prerequisites ∧ BudgetFits ∧ ScopeBound. */
+export function feasibleActions(state, constraints) {
+    return ALL_KINDS.filter((kind) => {
+        if (!constraints.authorizedActions.includes(kind))
+            return false;
+        if (!constraints.inScopeKinds.includes(kind))
+            return false;
+        for (const prereq of constraints.prerequisites[kind] ?? []) {
+            const met = state.obligations.some((o) => o.id === prereq && o.status === "satisfied") ||
+                state.predictions.some((p) => p.predictionId === prereq && p.status === "resolved");
+            if (!met)
+                return false;
+        }
+        const ms = constraints.actionCostsMs[kind] ?? 0;
+        const req = constraints.actionCostsRequests[kind] ?? 0;
+        return ms <= state.budget.remainingMs && req <= state.budget.remainingRequests;
+    });
+}
+/**
+ * §14 priority table — the baseline deterministic policy. Safety first, then
+ * required decisions, host-observed obligations, verifier health, prediction
+ * mismatches, verifier blind spots, stagnation, optional positive-VOI work,
+ * object work, then finish.
+ */
+export function selectAction(state, constraints, options) {
+    const feasible = new Set(feasibleActions(state, constraints));
+    const pick = (kind, reason, priority, extra) => (feasible.has(kind) ? { kind, reason, priority, ...extra } : null);
+    // 0: cancellation, authorization violation, safety constraint, binding mismatch.
+    if (state.policy.interruptionReason !== null ||
+        state.facts.candidateHash === "" ||
+        !constraints.authorizedActions.every((a) => state.policy.authorizedActions.includes(a))) {
+        return (pick("settle_safety", "safety-or-binding", 0) ?? {
+            kind: "stop_inconclusive",
+            reason: "unsafe-feasible-set",
+            priority: 0,
+        });
+    }
+    // 1: required user decision or unknown prerequisite.
+    const needsDecision = state.obligations.find((o) => o.status === "blocked-high-risk" || (o.status === "required" && o.checkMethodId === null && o.required));
+    if (needsDecision) {
+        const action = pick("request_required_decision", `required-decision:${needsDecision.id}`, 1, {
+            obligationId: needsDecision.id,
+        });
+        if (action)
+            return action;
+    }
+    // 2: host-observed new required obligation → refresh obligations, gate the step.
+    const newRequired = state.obligations.find((o) => o.status === "required" && o.coverageFraction === 0);
+    if (newRequired) {
+        const action = pick("form_obligations", `new-required:${newRequired.id}`, 2, { obligationId: newRequired.id });
+        if (action)
+            return action;
+    }
+    // 3: check execution itself invalid → diagnose environment, not code.
+    if (state.verifier.runnerHealth !== "healthy") {
+        const action = pick("inspect_local", "verifier-health-unverified", 3);
+        if (action)
+            return action;
+    }
+    // 4: prediction mismatch or adoptable evidence conflict → discriminate causes.
+    const mismatch = state.predictions.find((p) => p.status === "resolved" && p.mismatch !== undefined && p.mismatch !== "none");
+    if (mismatch && state.hypotheses.open.length > 1) {
+        const action = pick("run_discriminating_probe", `mismatch:${mismatch.predictionId}`, 4, {
+            hypothesisId: state.hypotheses.open[0],
+        });
+        if (action)
+            return action;
+    }
+    // 5: verifier blind spot on an important obligation → negative control / new check.
+    const blind = state.verifier.evaluations.find((e) => e.detectionRate === "unknown" || e.blindSpots.length > 0);
+    if (blind) {
+        const action = pick("strengthen_verifier", `blind-spot:${blind.obligationId}`, 5, {
+            obligationId: blind.obligationId,
+        });
+        if (action)
+            return action;
+    }
+    // 6: same strategy, no valid progress → switch with hysteresis, or stop.
+    const maxRep = options?.maxRepetitions ?? 3;
+    if (options?.progress && isStagnant(options.progress, state.progressHistory, maxRep)) {
+        const switchGain = netSwitchValue(options.estimatedSwitchGain ?? 0, 0, options.switchCost ?? 0);
+        if (switchGain > 0) {
+            const action = pick("switch_strategy", `stagnant:${progressKey(options.progress)}`, 6);
+            if (action)
+                return action;
+        }
+        const stop = pick("stop_inconclusive", "stagnant-no-progress", 6);
+        if (stop)
+            return stop;
+    }
+    // 7: optional information acquisition with positive VOI.
+    const voi = (options?.voiCandidates ?? [])
+        .filter((c) => c.voi > 0 && feasible.has(c.kind))
+        .sort((a, b) => b.voi - a.voi);
+    if (voi.length > 0) {
+        return (pick(voi[0].kind, `positive-voi:${voi[0].voi}`, 7) ?? {
+            kind: "stop_inconclusive",
+            reason: "no-feasible-voi-action",
+            priority: 7,
+        });
+    }
+    // 8: premises sufficient, object work remains.
+    const openRequired = state.obligations.filter((o) => o.status === "required" || o.status === "violated");
+    if (openRequired.length === 0) {
+        const action = pick("continue_object_work", "premises-satisfied", 8);
+        if (action)
+            return action;
+    }
+    // 9: object work done → verified bounded completion or inconclusive stop.
+    if (options?.receipt && openRequired.length === 0) {
+        const action = pick("finish_with_bound_receipt", `receipt:${options.receipt.receiptId}`, 9);
+        if (action)
+            return action;
+    }
+    const blocked = pick("revise_implementation", `open-obligations:${openRequired.length}`, 8) ??
+        pick("inspect_local", "open-obligations-inspect", 8);
+    if (blocked)
+        return blocked;
+    return { kind: "stop_inconclusive", reason: "no-feasible-action", priority: 9 };
+}
+/**
+ * §6.2/§6.5 VOI evaluation for one observation action. Returns the finite
+ * computation result; the caller supplies real priors and likelihoods and may
+ * include approved 2-step bundles whose joint value is computed the same way.
+ */
+export function valueOfObservation(prior, losses, likelihoodByHypothesis, cost) {
+    return experimentValue(prior, losses, likelihoodByHypothesis, cost).netValue;
+}
+//# sourceMappingURL=policy.js.map

package/dist/metacognition/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/metacognition/policy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Algorithm F — bounded metacontrol policy. Spec §9, §14.\n *\n * Feasibility precedes optimization: an action that is unauthorized, missing\n * prerequisites, over budget, or out of scope is absent from the feasible set\n * no matter how much information it promises. The baseline policy is the\n * explicit priority table of §14, not a score-sum that folds safety\n * constraints into a utility number.\n */\nimport { experimentValue } from \"./decision.ts\";\nimport type { MetaState } from \"./state.ts\";\nimport { isStagnant, netSwitchValue, progressKey } from \"./verifier.ts\";\n\nexport type MetaActionKind =\n\t| \"inspect_local\"\n\t| \"retrieve_reference\"\n\t| \"run_discriminating_probe\"\n\t| \"strengthen_verifier\"\n\t| \"reselect_skills\"\n\t| \"revise_implementation\"\n\t| \"switch_strategy\"\n\t| \"request_required_decision\"\n\t| \"continue_object_work\"\n\t| \"finish_with_bound_receipt\"\n\t| \"stop_inconclusive\"\n\t| \"settle_safety\"\n\t| \"form_obligations\";\n\nexport interface MetaAction {\n\treadonly kind: MetaActionKind;\n\treadonly obligationId?: string;\n\treadonly hypothesisId?: string;\n\treadonly reason: string;\n\treadonly priority: number;\n}\n\nexport interface ActionConstraints {\n\treadonly authorizedActions: readonly MetaActionKind[];\n\treadonly prerequisites: Partial<Readonly<Record<MetaActionKind, readonly string[]>>>;\n\treadonly actionCostsMs: Partial<Readonly<Record<MetaActionKind, number>>>;\n\treadonly actionCostsRequests: Partial<Readonly<Record<MetaActionKind, number>>>;\n\treadonly inScopeKinds: readonly MetaActionKind[];\n}\n\nconst ALL_KINDS: readonly MetaActionKind[] = [\n\t\"inspect_local\",\n\t\"retrieve_reference\",\n\t\"run_discriminating_probe\",\n\t\"strengthen_verifier\",\n\t\"reselect_skills\",\n\t\"revise_implementation\",\n\t\"switch_strategy\",\n\t\"request_required_decision\",\n\t\"continue_object_work\",\n\t\"finish_with_bound_receipt\",\n\t\"stop_inconclusive\",\n\t\"settle_safety\",\n\t\"form_obligations\",\n];\n\n/** §9.2: Authorized ∧ Prerequisites ∧ BudgetFits ∧ ScopeBound. */\nexport function feasibleActions(state: MetaState, constraints: ActionConstraints): MetaActionKind[] {\n\treturn ALL_KINDS.filter((kind) => {\n\t\tif (!constraints.authorizedActions.includes(kind)) return false;\n\t\tif (!constraints.inScopeKinds.includes(kind)) return false;\n\t\tfor (const prereq of constraints.prerequisites[kind] ?? []) {\n\t\t\tconst met =\n\t\t\t\tstate.obligations.some((o) => o.id === prereq && o.status === \"satisfied\") ||\n\t\t\t\tstate.predictions.some((p) => p.predictionId === prereq && p.status === \"resolved\");\n\t\t\tif (!met) return false;\n\t\t}\n\t\tconst ms = constraints.actionCostsMs[kind] ?? 0;\n\t\tconst req = constraints.actionCostsRequests[kind] ?? 0;\n\t\treturn ms <= state.budget.remainingMs && req <= state.budget.remainingRequests;\n\t});\n}\n\n/**\n * §14 priority table — the baseline deterministic policy. Safety first, then\n * required decisions, host-observed obligations, verifier health, prediction\n * mismatches, verifier blind spots, stagnation, optional positive-VOI work,\n * object work, then finish.\n */\nexport function selectAction(\n\tstate: MetaState,\n\tconstraints: ActionConstraints,\n\toptions?: {\n\t\treadonly receipt?: { receiptId: string; candidateHash: string; scope: string } | null;\n\t\treadonly maxRepetitions?: number;\n\t\treadonly switchCost?: number;\n\t\treadonly estimatedSwitchGain?: number;\n\t\treadonly voiCandidates?: readonly { kind: MetaActionKind; voi: number }[];\n\t\treadonly progress?: {\n\t\t\tgoalScope: string;\n\t\t\tcandidateFamily: string;\n\t\t\terrorClass: string;\n\t\t\tapproach: string;\n\t\t\tcheckMethod: string;\n\t\t\tsourceFamily: string;\n\t\t};\n\t},\n): MetaAction {\n\tconst feasible = new Set(feasibleActions(state, constraints));\n\tconst pick = (\n\t\tkind: MetaActionKind,\n\t\treason: string,\n\t\tpriority: number,\n\t\textra?: Partial<MetaAction>,\n\t): MetaAction | null => (feasible.has(kind) ? { kind, reason, priority, ...extra } : null);\n\n\t// 0: cancellation, authorization violation, safety constraint, binding mismatch.\n\tif (\n\t\tstate.policy.interruptionReason !== null ||\n\t\tstate.facts.candidateHash === \"\" ||\n\t\t!constraints.authorizedActions.every((a) => state.policy.authorizedActions.includes(a))\n\t) {\n\t\treturn (\n\t\t\tpick(\"settle_safety\", \"safety-or-binding\", 0) ?? {\n\t\t\t\tkind: \"stop_inconclusive\",\n\t\t\t\treason: \"unsafe-feasible-set\",\n\t\t\t\tpriority: 0,\n\t\t\t}\n\t\t);\n\t}\n\t// 1: required user decision or unknown prerequisite.\n\tconst needsDecision = state.obligations.find(\n\t\t(o) => o.status === \"blocked-high-risk\" || (o.status === \"required\" && o.checkMethodId === null && o.required),\n\t);\n\tif (needsDecision) {\n\t\tconst action = pick(\"request_required_decision\", `required-decision:${needsDecision.id}`, 1, {\n\t\t\tobligationId: needsDecision.id,\n\t\t});\n\t\tif (action) return action;\n\t}\n\t// 2: host-observed new required obligation → refresh obligations, gate the step.\n\tconst newRequired = state.obligations.find((o) => o.status === \"required\" && o.coverageFraction === 0);\n\tif (newRequired) {\n\t\tconst action = pick(\"form_obligations\", `new-required:${newRequired.id}`, 2, { obligationId: newRequired.id });\n\t\tif (action) return action;\n\t}\n\t// 3: check execution itself invalid → diagnose environment, not code.\n\tif (state.verifier.runnerHealth !== \"healthy\") {\n\t\tconst action = pick(\"inspect_local\", \"verifier-health-unverified\", 3);\n\t\tif (action) return action;\n\t}\n\t// 4: prediction mismatch or adoptable evidence conflict → discriminate causes.\n\tconst mismatch = state.predictions.find(\n\t\t(p) => p.status === \"resolved\" && p.mismatch !== undefined && p.mismatch !== \"none\",\n\t);\n\tif (mismatch && state.hypotheses.open.length > 1) {\n\t\tconst action = pick(\"run_discriminating_probe\", `mismatch:${mismatch.predictionId}`, 4, {\n\t\t\thypothesisId: state.hypotheses.open[0],\n\t\t});\n\t\tif (action) return action;\n\t}\n\t// 5: verifier blind spot on an important obligation → negative control / new check.\n\tconst blind = state.verifier.evaluations.find((e) => e.detectionRate === \"unknown\" || e.blindSpots.length > 0);\n\tif (blind) {\n\t\tconst action = pick(\"strengthen_verifier\", `blind-spot:${blind.obligationId}`, 5, {\n\t\t\tobligationId: blind.obligationId,\n\t\t});\n\t\tif (action) return action;\n\t}\n\t// 6: same strategy, no valid progress → switch with hysteresis, or stop.\n\tconst maxRep = options?.maxRepetitions ?? 3;\n\tif (options?.progress && isStagnant(options.progress, state.progressHistory, maxRep)) {\n\t\tconst switchGain = netSwitchValue(options.estimatedSwitchGain ?? 0, 0, options.switchCost ?? 0);\n\t\tif (switchGain > 0) {\n\t\t\tconst action = pick(\"switch_strategy\", `stagnant:${progressKey(options.progress)}`, 6);\n\t\t\tif (action) return action;\n\t\t}\n\t\tconst stop = pick(\"stop_inconclusive\", \"stagnant-no-progress\", 6);\n\t\tif (stop) return stop;\n\t}\n\t// 7: optional information acquisition with positive VOI.\n\tconst voi = (options?.voiCandidates ?? [])\n\t\t.filter((c) => c.voi > 0 && feasible.has(c.kind))\n\t\t.sort((a, b) => b.voi - a.voi);\n\tif (voi.length > 0) {\n\t\treturn (\n\t\t\tpick(voi[0]!.kind, `positive-voi:${voi[0]!.voi}`, 7) ?? {\n\t\t\t\tkind: \"stop_inconclusive\",\n\t\t\t\treason: \"no-feasible-voi-action\",\n\t\t\t\tpriority: 7,\n\t\t\t}\n\t\t);\n\t}\n\t// 8: premises sufficient, object work remains.\n\tconst openRequired = state.obligations.filter((o) => o.status === \"required\" || o.status === \"violated\");\n\tif (openRequired.length === 0) {\n\t\tconst action = pick(\"continue_object_work\", \"premises-satisfied\", 8);\n\t\tif (action) return action;\n\t}\n\t// 9: object work done → verified bounded completion or inconclusive stop.\n\tif (options?.receipt && openRequired.length === 0) {\n\t\tconst action = pick(\"finish_with_bound_receipt\", `receipt:${options.receipt.receiptId}`, 9);\n\t\tif (action) return action;\n\t}\n\tconst blocked =\n\t\tpick(\"revise_implementation\", `open-obligations:${openRequired.length}`, 8) ??\n\t\tpick(\"inspect_local\", \"open-obligations-inspect\", 8);\n\tif (blocked) return blocked;\n\treturn { kind: \"stop_inconclusive\", reason: \"no-feasible-action\", priority: 9 };\n}\n\n/**\n * §6.2/§6.5 VOI evaluation for one observation action. Returns the finite\n * computation result; the caller supplies real priors and likelihoods and may\n * include approved 2-step bundles whose joint value is computed the same way.\n */\nexport function valueOfObservation(\n\tprior: readonly number[],\n\tlosses: readonly (readonly number[])[],\n\tlikelihoodByHypothesis: readonly (readonly number[])[],\n\tcost: number,\n): number {\n\treturn experimentValue(prior, losses, likelihoodByHypothesis, cost).netValue;\n}\n"]}

package/dist/metacognition/predictions.d.ts

@@ -0,0 +1,78 @@
+export type PredictionKind = "check-outcome" | "scope" | "side-effect" | "resource" | "hypothesis-outcome";
+export type EstimatorKind = "uncalibrated-model-estimate" | "validated-estimator" | "none";
+export type PredictionStatus = "registered" | "resolved" | "superseded" | "unobserved";
+export type MismatchKind = "unexpected-pass" | "unexpected-fail" | "unexpected-side-effect" | "missing-observation" | "scope-mismatch" | "none";
+export interface Prediction {
+    readonly predictionId: string;
+    readonly operationId: string;
+    readonly taskId: string;
+    readonly stageId: string;
+    readonly kind: PredictionKind;
+    readonly candidateHash: string;
+    readonly environmentHash: string;
+    readonly checkDefinitionHash: string;
+    readonly policyVersion: string;
+    readonly modelRevision: string;
+    readonly skillHashes: readonly string[];
+    readonly expectedOutcome: string;
+    /** Binary expectation for scored predictions; undefined for categorical. */
+    readonly expectedBinary?: boolean;
+    readonly probability?: number;
+    readonly estimator: EstimatorKind;
+    readonly counterevidenceCondition: string;
+    readonly hostSequence: number;
+    readonly registeredAtMs: number;
+    status: PredictionStatus;
+    readonly resolvedAtMs?: number;
+    readonly observedOutcome?: string;
+    readonly observedBinary?: boolean;
+    readonly mismatch?: MismatchKind;
+}
+export interface ScoredPrediction {
+    readonly predictionId: string;
+    readonly mismatch: MismatchKind;
+    readonly brier?: number;
+    readonly surprise?: number;
+}
+/**
+ * Register a prediction. The host calls this BEFORE the operation runs.
+ * hostSequence is a host-owned monotone counter; predictions are immutable
+ * once registered — corrections append a new record.
+ */
+export declare function registerPrediction(ledger: readonly Prediction[], prediction: Omit<Prediction, "status">): readonly Prediction[];
+/**
+ * Resolve a registered prediction against a host observation bound to the
+ * same candidate/check/environment fingerprints. Mismatched bindings reject —
+ * a prediction for one candidate cannot be scored against another.
+ */
+export declare function resolvePrediction(ledger: readonly Prediction[], predictionId: string, observation: {
+    readonly candidateHash: string;
+    readonly environmentHash: string;
+    readonly checkDefinitionHash: string;
+    readonly outcome: string;
+    readonly binaryOutcome?: boolean;
+    readonly sideEffect?: boolean;
+    readonly observedAtMs: number;
+}): {
+    ledger: readonly Prediction[];
+    scored: ScoredPrediction;
+};
+/**
+ * Mark a prediction superseded (policy/budget/target changed before outcome)
+ * or unobserved (cancelled, environment failure, late result). Neither is
+ * ever scored as a code result.
+ */
+export declare function retirePrediction(ledger: readonly Prediction[], predictionId: string, outcome: "superseded" | "unobserved"): readonly Prediction[];
+/** Categorical mismatch summary plus scored aggregates. */
+export declare function mismatchSummary(ledger: readonly Prediction[]): {
+    readonly total: number;
+    readonly resolved: number;
+    readonly byKind: Readonly<Record<MismatchKind, number>>;
+    readonly meanBrier?: number;
+    readonly meanSurprise?: number;
+    readonly surprising: readonly ScoredPrediction[];
+};
+/** §5.5: map a mismatch kind to the short control branch it triggers. */
+export declare function mismatchBranch(kind: MismatchKind): string;
+export declare function predictionFingerprint(p: Prediction): string;
+//# sourceMappingURL=predictions.d.ts.map

package/dist/metacognition/predictions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predictions.d.ts","sourceRoot":"","sources":["../../src/metacognition/predictions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Algorithm B — pre-execution prediction ledger and mismatch scoring.\n * Spec: OMK_metacognitive_control_algorithms_2026-09-19.md §5.\n *\n * Predictions are registered by the host BEFORE outcomes exist and bound to\n * candidate/environment/check/policy fingerprints. Later edits append a new\n * prediction — existing records are never overwritten. Unobserved, cancelled,\n * or environment-failed outcomes stay unobserved; they are never silently\n * scored as code success or failure.\n */\nimport { brier, surprise } from \"./decision.ts\";\nimport { canonical, ensure, integer, lexical, member, text, unique } from \"./validation.ts\";\n\nexport type PredictionKind = \"check-outcome\" | \"scope\" | \"side-effect\" | \"resource\" | \"hypothesis-outcome\";\nexport type EstimatorKind = \"uncalibrated-model-estimate\" | \"validated-estimator\" | \"none\";\nexport type PredictionStatus = \"registered\" | \"resolved\" | \"superseded\" | \"unobserved\";\nexport type MismatchKind =\n\t| \"unexpected-pass\"\n\t| \"unexpected-fail\"\n\t| \"unexpected-side-effect\"\n\t| \"missing-observation\"\n\t| \"scope-mismatch\"\n\t| \"none\";\n\nexport interface Prediction {\n\treadonly predictionId: string;\n\treadonly operationId: string;\n\treadonly taskId: string;\n\treadonly stageId: string;\n\treadonly kind: PredictionKind;\n\treadonly candidateHash: string;\n\treadonly environmentHash: string;\n\treadonly checkDefinitionHash: string;\n\treadonly policyVersion: string;\n\treadonly modelRevision: string;\n\treadonly skillHashes: readonly string[];\n\treadonly expectedOutcome: string;\n\t/** Binary expectation for scored predictions; undefined for categorical. */\n\treadonly expectedBinary?: boolean;\n\treadonly probability?: number;\n\treadonly estimator: EstimatorKind;\n\treadonly counterevidenceCondition: string;\n\treadonly hostSequence: number;\n\treadonly registeredAtMs: number;\n\tstatus: PredictionStatus;\n\treadonly resolvedAtMs?: number;\n\treadonly observedOutcome?: string;\n\treadonly observedBinary?: boolean;\n\treadonly mismatch?: MismatchKind;\n}\nexport interface ScoredPrediction {\n\treadonly predictionId: string;\n\treadonly mismatch: MismatchKind;\n\treadonly brier?: number;\n\treadonly surprise?: number;\n}\n\nconst LEDGER_BOUND = 4096;\n\nfunction validatePrediction(p: Prediction): void {\n\ttext(p.predictionId, \"predictionId\", 128);\n\ttext(p.operationId, \"operationId\", 128);\n\ttext(p.taskId, \"taskId\", 128);\n\ttext(p.stageId, \"stageId\", 128);\n\tmember(p.kind, [\"check-outcome\", \"scope\", \"side-effect\", \"resource\", \"hypothesis-outcome\"], \"kind\");\n\ttext(p.candidateHash, \"candidateHash\", 128);\n\ttext(p.environmentHash, \"environmentHash\", 128);\n\ttext(p.checkDefinitionHash, \"checkDefinitionHash\", 128);\n\ttext(p.policyVersion, \"policyVersion\", 64);\n\ttext(p.modelRevision, \"modelRevision\", 128);\n\tunique(p.skillHashes, \"skillHashes\", 64);\n\ttext(p.expectedOutcome, \"expectedOutcome\", 2048);\n\ttext(p.counterevidenceCondition, \"counterevidenceCondition\", 2048);\n\tmember(p.estimator, [\"uncalibrated-model-estimate\", \"validated-estimator\", \"none\"], \"estimator\");\n\tinteger(p.hostSequence, \"hostSequence\");\n\tinteger(p.registeredAtMs, \"registeredAtMs\");\n\tif (p.probability !== undefined) {\n\t\tensure(p.probability >= 0 && p.probability <= 1, \"probability out of range\");\n\t\tensure(p.estimator !== \"none\", \"probability requires a declared estimator\");\n\t}\n\tif (p.expectedBinary !== undefined) ensure(typeof p.expectedBinary === \"boolean\", \"expectedBinary\");\n}\n\n/**\n * Register a prediction. The host calls this BEFORE the operation runs.\n * hostSequence is a host-owned monotone counter; predictions are immutable\n * once registered — corrections append a new record.\n */\nexport function registerPrediction(\n\tledger: readonly Prediction[],\n\tprediction: Omit<Prediction, \"status\">,\n): readonly Prediction[] {\n\tensure(ledger.length < LEDGER_BOUND, \"prediction ledger bound exceeded\");\n\tvalidatePrediction({ ...prediction, status: \"registered\" });\n\tensure(!ledger.some((p) => p.predictionId === prediction.predictionId), \"duplicate predictionId\");\n\treturn [...ledger, { ...prediction, status: \"registered\" }];\n}\n\n/**\n * Resolve a registered prediction against a host observation bound to the\n * same candidate/check/environment fingerprints. Mismatched bindings reject —\n * a prediction for one candidate cannot be scored against another.\n */\nexport function resolvePrediction(\n\tledger: readonly Prediction[],\n\tpredictionId: string,\n\tobservation: {\n\t\treadonly candidateHash: string;\n\t\treadonly environmentHash: string;\n\t\treadonly checkDefinitionHash: string;\n\t\treadonly outcome: string;\n\t\treadonly binaryOutcome?: boolean;\n\t\treadonly sideEffect?: boolean;\n\t\treadonly observedAtMs: number;\n\t},\n): { ledger: readonly Prediction[]; scored: ScoredPrediction } {\n\ttext(predictionId, \"predictionId\", 128);\n\tconst index = ledger.findIndex((p) => p.predictionId === predictionId);\n\tensure(index >= 0, \"unknown predictionId\");\n\tconst p = ledger[index]!;\n\tensure(p.status === \"registered\", `prediction ${predictionId} is ${p.status}`);\n\tensure(observation.candidateHash === p.candidateHash, \"candidate binding mismatch\");\n\tensure(observation.environmentHash === p.environmentHash, \"environment binding mismatch\");\n\tensure(observation.checkDefinitionHash === p.checkDefinitionHash, \"check binding mismatch\");\n\tinteger(observation.observedAtMs, \"observedAtMs\");\n\tensure(observation.observedAtMs >= p.registeredAtMs, \"observation predates registration\");\n\tlet mismatch: MismatchKind = \"none\";\n\tlet score: number | undefined;\n\tlet surpriseScore: number | undefined;\n\tif (observation.binaryOutcome !== undefined && p.expectedBinary !== undefined) {\n\t\tconst outcome: 0 | 1 = observation.binaryOutcome ? 1 : 0;\n\t\tconst expected: 0 | 1 = p.expectedBinary ? 1 : 0;\n\t\tif (outcome !== expected) mismatch = p.kind === \"check-outcome\" ? \"unexpected-fail\" : \"unexpected-side-effect\";\n\t\tif (p.probability !== undefined) {\n\t\t\tscore = brier(p.probability, outcome);\n\t\t\tsurpriseScore = surprise(p.probability, outcome);\n\t\t}\n\t} else if (observation.outcome !== p.expectedOutcome) {\n\t\tmismatch = p.kind === \"scope\" ? \"scope-mismatch\" : \"unexpected-fail\";\n\t}\n\tif (observation.sideEffect === true && p.kind !== \"side-effect\" && mismatch === \"none\") {\n\t\tmismatch = \"unexpected-side-effect\";\n\t}\n\tconst resolved: Prediction = {\n\t\t...p,\n\t\tstatus: \"resolved\",\n\t\tresolvedAtMs: observation.observedAtMs,\n\t\tobservedOutcome: observation.outcome,\n\t\tobservedBinary: observation.binaryOutcome,\n\t\tmismatch,\n\t};\n\tconst next = ledger.slice();\n\tnext[index] = resolved;\n\treturn { ledger: next, scored: { predictionId, mismatch, brier: score, surprise: surpriseScore } };\n}\n\n/**\n * Mark a prediction superseded (policy/budget/target changed before outcome)\n * or unobserved (cancelled, environment failure, late result). Neither is\n * ever scored as a code result.\n */\nexport function retirePrediction(\n\tledger: readonly Prediction[],\n\tpredictionId: string,\n\toutcome: \"superseded\" | \"unobserved\",\n): readonly Prediction[] {\n\tconst index = ledger.findIndex((p) => p.predictionId === predictionId);\n\tensure(index >= 0, \"unknown predictionId\");\n\tconst p = ledger[index]!;\n\tensure(p.status === \"registered\", `prediction ${predictionId} is ${p.status}`);\n\tconst next = ledger.slice();\n\tnext[index] = { ...p, status: outcome };\n\treturn next;\n}\n\n/** Categorical mismatch summary plus scored aggregates. */\nexport function mismatchSummary(ledger: readonly Prediction[]): {\n\treadonly total: number;\n\treadonly resolved: number;\n\treadonly byKind: Readonly<Record<MismatchKind, number>>;\n\treadonly meanBrier?: number;\n\treadonly meanSurprise?: number;\n\treadonly surprising: readonly ScoredPrediction[];\n} {\n\tconst byKind: Record<MismatchKind, number> = {\n\t\t\"unexpected-pass\": 0,\n\t\t\"unexpected-fail\": 0,\n\t\t\"unexpected-side-effect\": 0,\n\t\t\"missing-observation\": 0,\n\t\t\"scope-mismatch\": 0,\n\t\tnone: 0,\n\t};\n\tconst surprising: ScoredPrediction[] = [];\n\tlet brierSum = 0,\n\t\tsurpriseSum = 0,\n\t\tscored = 0;\n\tfor (const p of ledger) {\n\t\tif (p.status !== \"resolved\") continue;\n\t\tconst kind = p.mismatch ?? \"none\";\n\t\tbyKind[kind] += 1;\n\t\tif (p.observedBinary !== undefined && p.probability !== undefined) {\n\t\t\tconst outcome: 0 | 1 = p.observedBinary ? 1 : 0;\n\t\t\tbrierSum += brier(p.probability, outcome);\n\t\t\tsurpriseSum += surprise(p.probability, outcome);\n\t\t\tscored += 1;\n\t\t\tif (kind !== \"none\") {\n\t\t\t\tsurprising.push({\n\t\t\t\t\tpredictionId: p.predictionId,\n\t\t\t\t\tmismatch: kind,\n\t\t\t\t\tbrier: brier(p.probability, outcome),\n\t\t\t\t\tsurprise: surprise(p.probability, outcome),\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t}\n\tsurprising.sort((a, b) => (b.surprise ?? 0) - (a.surprise ?? 0) || lexical(a.predictionId, b.predictionId));\n\treturn {\n\t\ttotal: ledger.length,\n\t\tresolved: scored,\n\t\tbyKind,\n\t\tmeanBrier: scored > 0 ? brierSum / scored : undefined,\n\t\tmeanSurprise: scored > 0 ? surpriseSum / scored : undefined,\n\t\tsurprising,\n\t};\n}\n\n/** §5.5: map a mismatch kind to the short control branch it triggers. */\nexport function mismatchBranch(kind: MismatchKind): string {\n\tswitch (kind) {\n\t\tcase \"scope-mismatch\":\n\t\t\treturn \"impact-analysis-and-obligation-refresh\";\n\t\tcase \"unexpected-fail\":\n\t\t\treturn \"cause-hypothesis-discrimination\";\n\t\tcase \"unexpected-pass\":\n\t\t\treturn \"verifier-evaluation\";\n\t\tcase \"unexpected-side-effect\":\n\t\t\treturn \"boundary-and-permission-review\";\n\t\tcase \"missing-observation\":\n\t\t\treturn \"coverage-gap-registration\";\n\t\tcase \"none\":\n\t\t\treturn \"continue\";\n\t}\n}\n\nexport function predictionFingerprint(p: Prediction): string {\n\treturn canonical([\n\t\tp.operationId,\n\t\tp.taskId,\n\t\tp.stageId,\n\t\tp.candidateHash,\n\t\tp.environmentHash,\n\t\tp.checkDefinitionHash,\n\t\tp.policyVersion,\n\t\tp.modelRevision,\n\t]);\n}\n"]}

package/dist/metacognition/predictions.js

@@ -0,0 +1,181 @@
+/**
+ * Algorithm B — pre-execution prediction ledger and mismatch scoring.
+ * Spec: OMK_metacognitive_control_algorithms_2026-09-19.md §5.
+ *
+ * Predictions are registered by the host BEFORE outcomes exist and bound to
+ * candidate/environment/check/policy fingerprints. Later edits append a new
+ * prediction — existing records are never overwritten. Unobserved, cancelled,
+ * or environment-failed outcomes stay unobserved; they are never silently
+ * scored as code success or failure.
+ */
+import { brier, surprise } from "./decision.js";
+import { canonical, ensure, integer, lexical, member, text, unique } from "./validation.js";
+const LEDGER_BOUND = 4096;
+function validatePrediction(p) {
+    text(p.predictionId, "predictionId", 128);
+    text(p.operationId, "operationId", 128);
+    text(p.taskId, "taskId", 128);
+    text(p.stageId, "stageId", 128);
+    member(p.kind, ["check-outcome", "scope", "side-effect", "resource", "hypothesis-outcome"], "kind");
+    text(p.candidateHash, "candidateHash", 128);
+    text(p.environmentHash, "environmentHash", 128);
+    text(p.checkDefinitionHash, "checkDefinitionHash", 128);
+    text(p.policyVersion, "policyVersion", 64);
+    text(p.modelRevision, "modelRevision", 128);
+    unique(p.skillHashes, "skillHashes", 64);
+    text(p.expectedOutcome, "expectedOutcome", 2048);
+    text(p.counterevidenceCondition, "counterevidenceCondition", 2048);
+    member(p.estimator, ["uncalibrated-model-estimate", "validated-estimator", "none"], "estimator");
+    integer(p.hostSequence, "hostSequence");
+    integer(p.registeredAtMs, "registeredAtMs");
+    if (p.probability !== undefined) {
+        ensure(p.probability >= 0 && p.probability <= 1, "probability out of range");
+        ensure(p.estimator !== "none", "probability requires a declared estimator");
+    }
+    if (p.expectedBinary !== undefined)
+        ensure(typeof p.expectedBinary === "boolean", "expectedBinary");
+}
+/**
+ * Register a prediction. The host calls this BEFORE the operation runs.
+ * hostSequence is a host-owned monotone counter; predictions are immutable
+ * once registered — corrections append a new record.
+ */
+export function registerPrediction(ledger, prediction) {
+    ensure(ledger.length < LEDGER_BOUND, "prediction ledger bound exceeded");
+    validatePrediction({ ...prediction, status: "registered" });
+    ensure(!ledger.some((p) => p.predictionId === prediction.predictionId), "duplicate predictionId");
+    return [...ledger, { ...prediction, status: "registered" }];
+}
+/**
+ * Resolve a registered prediction against a host observation bound to the
+ * same candidate/check/environment fingerprints. Mismatched bindings reject —
+ * a prediction for one candidate cannot be scored against another.
+ */
+export function resolvePrediction(ledger, predictionId, observation) {
+    text(predictionId, "predictionId", 128);
+    const index = ledger.findIndex((p) => p.predictionId === predictionId);
+    ensure(index >= 0, "unknown predictionId");
+    const p = ledger[index];
+    ensure(p.status === "registered", `prediction ${predictionId} is ${p.status}`);
+    ensure(observation.candidateHash === p.candidateHash, "candidate binding mismatch");
+    ensure(observation.environmentHash === p.environmentHash, "environment binding mismatch");
+    ensure(observation.checkDefinitionHash === p.checkDefinitionHash, "check binding mismatch");
+    integer(observation.observedAtMs, "observedAtMs");
+    ensure(observation.observedAtMs >= p.registeredAtMs, "observation predates registration");
+    let mismatch = "none";
+    let score;
+    let surpriseScore;
+    if (observation.binaryOutcome !== undefined && p.expectedBinary !== undefined) {
+        const outcome = observation.binaryOutcome ? 1 : 0;
+        const expected = p.expectedBinary ? 1 : 0;
+        if (outcome !== expected)
+            mismatch = p.kind === "check-outcome" ? "unexpected-fail" : "unexpected-side-effect";
+        if (p.probability !== undefined) {
+            score = brier(p.probability, outcome);
+            surpriseScore = surprise(p.probability, outcome);
+        }
+    }
+    else if (observation.outcome !== p.expectedOutcome) {
+        mismatch = p.kind === "scope" ? "scope-mismatch" : "unexpected-fail";
+    }
+    if (observation.sideEffect === true && p.kind !== "side-effect" && mismatch === "none") {
+        mismatch = "unexpected-side-effect";
+    }
+    const resolved = {
+        ...p,
+        status: "resolved",
+        resolvedAtMs: observation.observedAtMs,
+        observedOutcome: observation.outcome,
+        observedBinary: observation.binaryOutcome,
+        mismatch,
+    };
+    const next = ledger.slice();
+    next[index] = resolved;
+    return { ledger: next, scored: { predictionId, mismatch, brier: score, surprise: surpriseScore } };
+}
+/**
+ * Mark a prediction superseded (policy/budget/target changed before outcome)
+ * or unobserved (cancelled, environment failure, late result). Neither is
+ * ever scored as a code result.
+ */
+export function retirePrediction(ledger, predictionId, outcome) {
+    const index = ledger.findIndex((p) => p.predictionId === predictionId);
+    ensure(index >= 0, "unknown predictionId");
+    const p = ledger[index];
+    ensure(p.status === "registered", `prediction ${predictionId} is ${p.status}`);
+    const next = ledger.slice();
+    next[index] = { ...p, status: outcome };
+    return next;
+}
+/** Categorical mismatch summary plus scored aggregates. */
+export function mismatchSummary(ledger) {
+    const byKind = {
+        "unexpected-pass": 0,
+        "unexpected-fail": 0,
+        "unexpected-side-effect": 0,
+        "missing-observation": 0,
+        "scope-mismatch": 0,
+        none: 0,
+    };
+    const surprising = [];
+    let brierSum = 0, surpriseSum = 0, scored = 0;
+    for (const p of ledger) {
+        if (p.status !== "resolved")
+            continue;
+        const kind = p.mismatch ?? "none";
+        byKind[kind] += 1;
+        if (p.observedBinary !== undefined && p.probability !== undefined) {
+            const outcome = p.observedBinary ? 1 : 0;
+            brierSum += brier(p.probability, outcome);
+            surpriseSum += surprise(p.probability, outcome);
+            scored += 1;
+            if (kind !== "none") {
+                surprising.push({
+                    predictionId: p.predictionId,
+                    mismatch: kind,
+                    brier: brier(p.probability, outcome),
+                    surprise: surprise(p.probability, outcome),
+                });
+            }
+        }
+    }
+    surprising.sort((a, b) => (b.surprise ?? 0) - (a.surprise ?? 0) || lexical(a.predictionId, b.predictionId));
+    return {
+        total: ledger.length,
+        resolved: scored,
+        byKind,
+        meanBrier: scored > 0 ? brierSum / scored : undefined,
+        meanSurprise: scored > 0 ? surpriseSum / scored : undefined,
+        surprising,
+    };
+}
+/** §5.5: map a mismatch kind to the short control branch it triggers. */
+export function mismatchBranch(kind) {
+    switch (kind) {
+        case "scope-mismatch":
+            return "impact-analysis-and-obligation-refresh";
+        case "unexpected-fail":
+            return "cause-hypothesis-discrimination";
+        case "unexpected-pass":
+            return "verifier-evaluation";
+        case "unexpected-side-effect":
+            return "boundary-and-permission-review";
+        case "missing-observation":
+            return "coverage-gap-registration";
+        case "none":
+            return "continue";
+    }
+}
+export function predictionFingerprint(p) {
+    return canonical([
+        p.operationId,
+        p.taskId,
+        p.stageId,
+        p.candidateHash,
+        p.environmentHash,
+        p.checkDefinitionHash,
+        p.policyVersion,
+        p.modelRevision,
+    ]);
+}
+//# sourceMappingURL=predictions.js.map

package/dist/metacognition/predictions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"predictions.js","sourceRoot":"","sources":["../../src/metacognition/predictions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Algorithm B — pre-execution prediction ledger and mismatch scoring.\n * Spec: OMK_metacognitive_control_algorithms_2026-09-19.md §5.\n *\n * Predictions are registered by the host BEFORE outcomes exist and bound to\n * candidate/environment/check/policy fingerprints. Later edits append a new\n * prediction — existing records are never overwritten. Unobserved, cancelled,\n * or environment-failed outcomes stay unobserved; they are never silently\n * scored as code success or failure.\n */\nimport { brier, surprise } from \"./decision.ts\";\nimport { canonical, ensure, integer, lexical, member, text, unique } from \"./validation.ts\";\n\nexport type PredictionKind = \"check-outcome\" | \"scope\" | \"side-effect\" | \"resource\" | \"hypothesis-outcome\";\nexport type EstimatorKind = \"uncalibrated-model-estimate\" | \"validated-estimator\" | \"none\";\nexport type PredictionStatus = \"registered\" | \"resolved\" | \"superseded\" | \"unobserved\";\nexport type MismatchKind =\n\t| \"unexpected-pass\"\n\t| \"unexpected-fail\"\n\t| \"unexpected-side-effect\"\n\t| \"missing-observation\"\n\t| \"scope-mismatch\"\n\t| \"none\";\n\nexport interface Prediction {\n\treadonly predictionId: string;\n\treadonly operationId: string;\n\treadonly taskId: string;\n\treadonly stageId: string;\n\treadonly kind: PredictionKind;\n\treadonly candidateHash: string;\n\treadonly environmentHash: string;\n\treadonly checkDefinitionHash: string;\n\treadonly policyVersion: string;\n\treadonly modelRevision: string;\n\treadonly skillHashes: readonly string[];\n\treadonly expectedOutcome: string;\n\t/** Binary expectation for scored predictions; undefined for categorical. */\n\treadonly expectedBinary?: boolean;\n\treadonly probability?: number;\n\treadonly estimator: EstimatorKind;\n\treadonly counterevidenceCondition: string;\n\treadonly hostSequence: number;\n\treadonly registeredAtMs: number;\n\tstatus: PredictionStatus;\n\treadonly resolvedAtMs?: number;\n\treadonly observedOutcome?: string;\n\treadonly observedBinary?: boolean;\n\treadonly mismatch?: MismatchKind;\n}\nexport interface ScoredPrediction {\n\treadonly predictionId: string;\n\treadonly mismatch: MismatchKind;\n\treadonly brier?: number;\n\treadonly surprise?: number;\n}\n\nconst LEDGER_BOUND = 4096;\n\nfunction validatePrediction(p: Prediction): void {\n\ttext(p.predictionId, \"predictionId\", 128);\n\ttext(p.operationId, \"operationId\", 128);\n\ttext(p.taskId, \"taskId\", 128);\n\ttext(p.stageId, \"stageId\", 128);\n\tmember(p.kind, [\"check-outcome\", \"scope\", \"side-effect\", \"resource\", \"hypothesis-outcome\"], \"kind\");\n\ttext(p.candidateHash, \"candidateHash\", 128);\n\ttext(p.environmentHash, \"environmentHash\", 128);\n\ttext(p.checkDefinitionHash, \"checkDefinitionHash\", 128);\n\ttext(p.policyVersion, \"policyVersion\", 64);\n\ttext(p.modelRevision, \"modelRevision\", 128);\n\tunique(p.skillHashes, \"skillHashes\", 64);\n\ttext(p.expectedOutcome, \"expectedOutcome\", 2048);\n\ttext(p.counterevidenceCondition, \"counterevidenceCondition\", 2048);\n\tmember(p.estimator, [\"uncalibrated-model-estimate\", \"validated-estimator\", \"none\"], \"estimator\");\n\tinteger(p.hostSequence, \"hostSequence\");\n\tinteger(p.registeredAtMs, \"registeredAtMs\");\n\tif (p.probability !== undefined) {\n\t\tensure(p.probability >= 0 && p.probability <= 1, \"probability out of range\");\n\t\tensure(p.estimator !== \"none\", \"probability requires a declared estimator\");\n\t}\n\tif (p.expectedBinary !== undefined) ensure(typeof p.expectedBinary === \"boolean\", \"expectedBinary\");\n}\n\n/**\n * Register a prediction. The host calls this BEFORE the operation runs.\n * hostSequence is a host-owned monotone counter; predictions are immutable\n * once registered — corrections append a new record.\n */\nexport function registerPrediction(\n\tledger: readonly Prediction[],\n\tprediction: Omit<Prediction, \"status\">,\n): readonly Prediction[] {\n\tensure(ledger.length < LEDGER_BOUND, \"prediction ledger bound exceeded\");\n\tvalidatePrediction({ ...prediction, status: \"registered\" });\n\tensure(!ledger.some((p) => p.predictionId === prediction.predictionId), \"duplicate predictionId\");\n\treturn [...ledger, { ...prediction, status: \"registered\" }];\n}\n\n/**\n * Resolve a registered prediction against a host observation bound to the\n * same candidate/check/environment fingerprints. Mismatched bindings reject —\n * a prediction for one candidate cannot be scored against another.\n */\nexport function resolvePrediction(\n\tledger: readonly Prediction[],\n\tpredictionId: string,\n\tobservation: {\n\t\treadonly candidateHash: string;\n\t\treadonly environmentHash: string;\n\t\treadonly checkDefinitionHash: string;\n\t\treadonly outcome: string;\n\t\treadonly binaryOutcome?: boolean;\n\t\treadonly sideEffect?: boolean;\n\t\treadonly observedAtMs: number;\n\t},\n): { ledger: readonly Prediction[]; scored: ScoredPrediction } {\n\ttext(predictionId, \"predictionId\", 128);\n\tconst index = ledger.findIndex((p) => p.predictionId === predictionId);\n\tensure(index >= 0, \"unknown predictionId\");\n\tconst p = ledger[index]!;\n\tensure(p.status === \"registered\", `prediction ${predictionId} is ${p.status}`);\n\tensure(observation.candidateHash === p.candidateHash, \"candidate binding mismatch\");\n\tensure(observation.environmentHash === p.environmentHash, \"environment binding mismatch\");\n\tensure(observation.checkDefinitionHash === p.checkDefinitionHash, \"check binding mismatch\");\n\tinteger(observation.observedAtMs, \"observedAtMs\");\n\tensure(observation.observedAtMs >= p.registeredAtMs, \"observation predates registration\");\n\tlet mismatch: MismatchKind = \"none\";\n\tlet score: number | undefined;\n\tlet surpriseScore: number | undefined;\n\tif (observation.binaryOutcome !== undefined && p.expectedBinary !== undefined) {\n\t\tconst outcome: 0 | 1 = observation.binaryOutcome ? 1 : 0;\n\t\tconst expected: 0 | 1 = p.expectedBinary ? 1 : 0;\n\t\tif (outcome !== expected) mismatch = p.kind === \"check-outcome\" ? \"unexpected-fail\" : \"unexpected-side-effect\";\n\t\tif (p.probability !== undefined) {\n\t\t\tscore = brier(p.probability, outcome);\n\t\t\tsurpriseScore = surprise(p.probability, outcome);\n\t\t}\n\t} else if (observation.outcome !== p.expectedOutcome) {\n\t\tmismatch = p.kind === \"scope\" ? \"scope-mismatch\" : \"unexpected-fail\";\n\t}\n\tif (observation.sideEffect === true && p.kind !== \"side-effect\" && mismatch === \"none\") {\n\t\tmismatch = \"unexpected-side-effect\";\n\t}\n\tconst resolved: Prediction = {\n\t\t...p,\n\t\tstatus: \"resolved\",\n\t\tresolvedAtMs: observation.observedAtMs,\n\t\tobservedOutcome: observation.outcome,\n\t\tobservedBinary: observation.binaryOutcome,\n\t\tmismatch,\n\t};\n\tconst next = ledger.slice();\n\tnext[index] = resolved;\n\treturn { ledger: next, scored: { predictionId, mismatch, brier: score, surprise: surpriseScore } };\n}\n\n/**\n * Mark a prediction superseded (policy/budget/target changed before outcome)\n * or unobserved (cancelled, environment failure, late result). Neither is\n * ever scored as a code result.\n */\nexport function retirePrediction(\n\tledger: readonly Prediction[],\n\tpredictionId: string,\n\toutcome: \"superseded\" | \"unobserved\",\n): readonly Prediction[] {\n\tconst index = ledger.findIndex((p) => p.predictionId === predictionId);\n\tensure(index >= 0, \"unknown predictionId\");\n\tconst p = ledger[index]!;\n\tensure(p.status === \"registered\", `prediction ${predictionId} is ${p.status}`);\n\tconst next = ledger.slice();\n\tnext[index] = { ...p, status: outcome };\n\treturn next;\n}\n\n/** Categorical mismatch summary plus scored aggregates. */\nexport function mismatchSummary(ledger: readonly Prediction[]): {\n\treadonly total: number;\n\treadonly resolved: number;\n\treadonly byKind: Readonly<Record<MismatchKind, number>>;\n\treadonly meanBrier?: number;\n\treadonly meanSurprise?: number;\n\treadonly surprising: readonly ScoredPrediction[];\n} {\n\tconst byKind: Record<MismatchKind, number> = {\n\t\t\"unexpected-pass\": 0,\n\t\t\"unexpected-fail\": 0,\n\t\t\"unexpected-side-effect\": 0,\n\t\t\"missing-observation\": 0,\n\t\t\"scope-mismatch\": 0,\n\t\tnone: 0,\n\t};\n\tconst surprising: ScoredPrediction[] = [];\n\tlet brierSum = 0,\n\t\tsurpriseSum = 0,\n\t\tscored = 0;\n\tfor (const p of ledger) {\n\t\tif (p.status !== \"resolved\") continue;\n\t\tconst kind = p.mismatch ?? \"none\";\n\t\tbyKind[kind] += 1;\n\t\tif (p.observedBinary !== undefined && p.probability !== undefined) {\n\t\t\tconst outcome: 0 | 1 = p.observedBinary ? 1 : 0;\n\t\t\tbrierSum += brier(p.probability, outcome);\n\t\t\tsurpriseSum += surprise(p.probability, outcome);\n\t\t\tscored += 1;\n\t\t\tif (kind !== \"none\") {\n\t\t\t\tsurprising.push({\n\t\t\t\t\tpredictionId: p.predictionId,\n\t\t\t\t\tmismatch: kind,\n\t\t\t\t\tbrier: brier(p.probability, outcome),\n\t\t\t\t\tsurprise: surprise(p.probability, outcome),\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t}\n\tsurprising.sort((a, b) => (b.surprise ?? 0) - (a.surprise ?? 0) || lexical(a.predictionId, b.predictionId));\n\treturn {\n\t\ttotal: ledger.length,\n\t\tresolved: scored,\n\t\tbyKind,\n\t\tmeanBrier: scored > 0 ? brierSum / scored : undefined,\n\t\tmeanSurprise: scored > 0 ? surpriseSum / scored : undefined,\n\t\tsurprising,\n\t};\n}\n\n/** §5.5: map a mismatch kind to the short control branch it triggers. */\nexport function mismatchBranch(kind: MismatchKind): string {\n\tswitch (kind) {\n\t\tcase \"scope-mismatch\":\n\t\t\treturn \"impact-analysis-and-obligation-refresh\";\n\t\tcase \"unexpected-fail\":\n\t\t\treturn \"cause-hypothesis-discrimination\";\n\t\tcase \"unexpected-pass\":\n\t\t\treturn \"verifier-evaluation\";\n\t\tcase \"unexpected-side-effect\":\n\t\t\treturn \"boundary-and-permission-review\";\n\t\tcase \"missing-observation\":\n\t\t\treturn \"coverage-gap-registration\";\n\t\tcase \"none\":\n\t\t\treturn \"continue\";\n\t}\n}\n\nexport function predictionFingerprint(p: Prediction): string {\n\treturn canonical([\n\t\tp.operationId,\n\t\tp.taskId,\n\t\tp.stageId,\n\t\tp.candidateHash,\n\t\tp.environmentHash,\n\t\tp.checkDefinitionHash,\n\t\tp.policyVersion,\n\t\tp.modelRevision,\n\t]);\n}\n"]}

package/dist/metacognition/retrieval.d.ts

@@ -0,0 +1,53 @@
+export interface CorpusDocument {
+    readonly id: string;
+    readonly uri: string;
+    readonly body: string;
+}
+export interface SearchHit extends CorpusDocument {
+    readonly score: number;
+    readonly trust: "candidate-only";
+}
+/** Retrieval tokens, not a semantic-knowledge detector. Short language names survive. */
+export declare function retrievalTokens(value: string): string[];
+/** BM25 with positive IDF; bounded local corpus, no I/O or model call. */
+export declare function searchCorpus(query: string, corpus: readonly CorpusDocument[], limit?: number): SearchHit[];
+export type AcquisitionResult<T> = {
+    readonly status: "ok";
+    readonly value: T;
+} | {
+    readonly status: "budget-exhausted" | "busy" | "timeout" | "aborted" | "stale" | "error";
+};
+export interface AcquisitionOptions {
+    readonly maxRequests: number;
+    readonly maxInFlight: number;
+    readonly durationMs: number;
+    readonly perRequestMs: number;
+    readonly monotonicNow?: () => number;
+}
+/**
+ * Owns every started promise until actual settlement, including noncooperative requests.
+ * The scope is per host-approved run. It is not a billing or process-isolation boundary.
+ */
+export declare class AcquisitionPool {
+    private readonly now;
+    private readonly deadline;
+    private readonly maxRequests;
+    private readonly maxInFlight;
+    private readonly perRequestMs;
+    private nextId;
+    private epoch;
+    private requests;
+    private readonly active;
+    constructor(options: AcquisitionOptions);
+    snapshot(): {
+        requests: number;
+        active: number;
+        quarantined: number;
+        remainingMs: number;
+        epoch: number;
+    };
+    /** Invalidation requests cancellation but never resets outstanding ownership or budget. */
+    invalidate(): void;
+    run<T>(operation: (signal: AbortSignal) => Promise<T>, parent?: AbortSignal): Promise<AcquisitionResult<T>>;
+}
+//# sourceMappingURL=retrieval.d.ts.map

package/dist/metacognition/retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval.d.ts","sourceRoot":"","sources":["../../src/metacognition/retrieval.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AACD,MAAM,WAAW,SAAU,SAAQ,cAAc;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;CACjC;AACD,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAQvD;AACD,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,cAAc,EAAE,EAAE,KAAK,SAAI,GAAG,SAAS,EAAE,CAyCrG;AAED,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC5C;IAAE,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;CAAE,CAAC;AAChG,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;CACrC;AACD;;;GAGG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4E;IACnG,YAAY,OAAO,EAAE,kBAAkB,EAYtC;IACD,QAAQ,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAQxG;IACD,2FAA2F;IAC3F,UAAU,IAAI,IAAI,CAMjB;IACK,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAgEhH;CACD","sourcesContent":["/**\n * Bounded local BM25 retrieval and the acquisition pool that owns every\n * started promise until actual settlement.\n *\n * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip\n * (src/retrieval.ts). Search hits are `candidate-only`, never auto-promoted\n * to observations.\n */\nimport { ensure, integer, lexical, text, unique } from \"./validation.ts\";\n\nexport interface CorpusDocument {\n\treadonly id: string;\n\treadonly uri: string;\n\treadonly body: string;\n}\nexport interface SearchHit extends CorpusDocument {\n\treadonly score: number;\n\treadonly trust: \"candidate-only\";\n}\n/** Retrieval tokens, not a semantic-knowledge detector. Short language names survive. */\nexport function retrievalTokens(value: string): string[] {\n\treturn (\n\t\tvalue\n\t\t\t.normalize(\"NFKC\")\n\t\t\t.replace(/([a-z0-9])([A-Z])/g, \"$1 $2\")\n\t\t\t.toLowerCase()\n\t\t\t.match(/[\\p{L}\\p{N}]+(?:\\+\\+|#)?/gu) ?? []\n\t);\n}\n/** BM25 with positive IDF; bounded local corpus, no I/O or model call. */\nexport function searchCorpus(query: string, corpus: readonly CorpusDocument[], limit = 8): SearchHit[] {\n\ttext(query, \"query\", 4096);\n\tinteger(limit, \"limit\", 64);\n\tensure(corpus.length <= 5000, \"corpus too large\");\n\tunique(\n\t\tcorpus.map((d) => d.id),\n\t\t\"document ids\",\n\t\t5000,\n\t);\n\tlet totalChars = 0;\n\tconst documents = corpus.map((d) => {\n\t\ttext(d.uri, \"uri\");\n\t\tensure(typeof d.body === \"string\" && d.body.length <= 100_000, \"document too large\");\n\t\ttotalChars += d.body.length;\n\t\tensure(totalChars <= 10_000_000, \"corpus byte/character policy exceeded\");\n\t\tconst tokens = retrievalTokens(d.body);\n\t\tconst frequencies = new Map<string, number>();\n\t\tfor (const token of tokens) frequencies.set(token, (frequencies.get(token) ?? 0) + 1);\n\t\treturn { d, length: tokens.length, frequencies };\n\t});\n\tconst terms = [...new Set(retrievalTokens(query))];\n\tif (!terms.length || !documents.length || limit === 0) return [];\n\tconst avgLength = Math.max(1, documents.reduce((s, d) => s + d.length, 0) / documents.length);\n\tconst idf = new Map(\n\t\tterms.map((term) => {\n\t\t\tconst frequency = documents.filter((d) => d.frequencies.has(term)).length;\n\t\t\treturn [term, Math.log(1 + (documents.length - frequency + 0.5) / (frequency + 0.5))] as const;\n\t\t}),\n\t);\n\treturn documents\n\t\t.map(({ d, length, frequencies }): SearchHit => {\n\t\t\tlet score = 0;\n\t\t\tfor (const term of terms) {\n\t\t\t\tconst tf = frequencies.get(term) ?? 0;\n\t\t\t\tscore += (idf.get(term)! * tf * 2.2) / (tf + 1.2 * (0.25 + (0.75 * length) / avgLength));\n\t\t\t}\n\t\t\treturn { ...d, score, trust: \"candidate-only\" };\n\t\t})\n\t\t.filter((d) => d.score > 0)\n\t\t.sort((a, b) => b.score - a.score || lexical(a.id, b.id))\n\t\t.slice(0, limit);\n}\n\nexport type AcquisitionResult<T> =\n\t| { readonly status: \"ok\"; readonly value: T }\n\t| { readonly status: \"budget-exhausted\" | \"busy\" | \"timeout\" | \"aborted\" | \"stale\" | \"error\" };\nexport interface AcquisitionOptions {\n\treadonly maxRequests: number;\n\treadonly maxInFlight: number;\n\treadonly durationMs: number;\n\treadonly perRequestMs: number;\n\treadonly monotonicNow?: () => number;\n}\n/**\n * Owns every started promise until actual settlement, including noncooperative requests.\n * The scope is per host-approved run. It is not a billing or process-isolation boundary.\n */\nexport class AcquisitionPool {\n\tprivate readonly now: () => number;\n\tprivate readonly deadline: number;\n\tprivate readonly maxRequests: number;\n\tprivate readonly maxInFlight: number;\n\tprivate readonly perRequestMs: number;\n\tprivate nextId = 0;\n\tprivate epoch = 0;\n\tprivate requests = 0;\n\tprivate readonly active = new Map<number, { controller: AbortController; quarantined: boolean }>();\n\tconstructor(options: AcquisitionOptions) {\n\t\tinteger(options.maxRequests, \"maxRequests\", 100_000);\n\t\tinteger(options.maxInFlight, \"maxInFlight\", 64);\n\t\tinteger(options.durationMs, \"durationMs\", 86_400_000);\n\t\tinteger(options.perRequestMs, \"perRequestMs\", 86_400_000);\n\t\tthis.now = options.monotonicNow ?? (() => performance.now());\n\t\tconst start = this.now();\n\t\tensure(Number.isFinite(start) && start >= 0, \"invalid monotonic clock\");\n\t\tthis.deadline = start + options.durationMs;\n\t\tthis.maxRequests = options.maxRequests;\n\t\tthis.maxInFlight = options.maxInFlight;\n\t\tthis.perRequestMs = options.perRequestMs;\n\t}\n\tsnapshot(): { requests: number; active: number; quarantined: number; remainingMs: number; epoch: number } {\n\t\treturn {\n\t\t\trequests: this.requests,\n\t\t\tactive: this.active.size,\n\t\t\tquarantined: [...this.active.values()].filter((e) => e.quarantined).length,\n\t\t\tremainingMs: Math.max(0, Math.floor(this.deadline - this.now())),\n\t\t\tepoch: this.epoch,\n\t\t};\n\t}\n\t/** Invalidation requests cancellation but never resets outstanding ownership or budget. */\n\tinvalidate(): void {\n\t\tthis.epoch++;\n\t\tfor (const entry of this.active.values()) {\n\t\t\tentry.quarantined = true;\n\t\t\tentry.controller.abort();\n\t\t}\n\t}\n\tasync run<T>(operation: (signal: AbortSignal) => Promise<T>, parent?: AbortSignal): Promise<AcquisitionResult<T>> {\n\t\tif (parent?.aborted) return { status: \"aborted\" };\n\t\tconst remaining = this.deadline - this.now();\n\t\tif (this.requests >= this.maxRequests || remaining <= 0 || this.perRequestMs === 0) {\n\t\t\treturn { status: \"budget-exhausted\" };\n\t\t}\n\t\tif (this.active.size >= this.maxInFlight) return { status: \"busy\" };\n\t\tconst id = ++this.nextId,\n\t\t\tepoch = this.epoch,\n\t\t\tcontroller = new AbortController();\n\t\tconst entry = { controller, quarantined: false };\n\t\tthis.active.set(id, entry);\n\t\tthis.requests++;\n\t\tconst expires = this.now() + Math.min(remaining, this.perRequestMs);\n\t\tlet resolveStop!: (result: AcquisitionResult<T>) => void;\n\t\tconst stopped = new Promise<AcquisitionResult<T>>((resolve) => {\n\t\t\tresolveStop = resolve;\n\t\t});\n\t\tconst stop = (status: \"aborted\" | \"timeout\" | \"stale\"): void => {\n\t\t\tif (this.active.has(id)) entry.quarantined = true;\n\t\t\tresolveStop({ status });\n\t\t\tcontroller.abort();\n\t\t};\n\t\tconst onParent = (): void => stop(\"aborted\");\n\t\tconst onInternal = (): void => {\n\t\t\tif (epoch !== this.epoch) resolveStop({ status: \"stale\" });\n\t\t};\n\t\tparent?.addEventListener(\"abort\", onParent, { once: true });\n\t\tcontroller.signal.addEventListener(\"abort\", onInternal, { once: true });\n\t\tconst timer = setTimeout(() => stop(\"timeout\"), Math.max(1, Math.ceil(expires - this.now())));\n\t\t// Both fulfillment and rejection are owned. Late results are never promoted.\n\t\tconst task = Promise.resolve()\n\t\t\t.then(() => {\n\t\t\t\tif (controller.signal.aborted || parent?.aborted) throw new Error(\"cancelled-before-dispatch\");\n\t\t\t\treturn operation(controller.signal);\n\t\t\t})\n\t\t\t.then(\n\t\t\t\t(value): AcquisitionResult<T> => {\n\t\t\t\t\tif (epoch !== this.epoch) return { status: \"stale\" };\n\t\t\t\t\tif (parent?.aborted) return { status: \"aborted\" };\n\t\t\t\t\tif (controller.signal.aborted || this.now() >= expires) return { status: \"timeout\" };\n\t\t\t\t\treturn { status: \"ok\", value };\n\t\t\t\t},\n\t\t\t\t(): AcquisitionResult<T> => ({\n\t\t\t\t\tstatus:\n\t\t\t\t\t\tepoch !== this.epoch\n\t\t\t\t\t\t\t? \"stale\"\n\t\t\t\t\t\t\t: parent?.aborted\n\t\t\t\t\t\t\t\t? \"aborted\"\n\t\t\t\t\t\t\t\t: controller.signal.aborted\n\t\t\t\t\t\t\t\t\t? \"timeout\"\n\t\t\t\t\t\t\t\t\t: \"error\",\n\t\t\t\t}),\n\t\t\t)\n\t\t\t.finally(() => {\n\t\t\t\tthis.active.delete(id);\n\t\t\t});\n\t\ttry {\n\t\t\treturn await Promise.race([task, stopped]);\n\t\t} finally {\n\t\t\tclearTimeout(timer);\n\t\t\tparent?.removeEventListener(\"abort\", onParent);\n\t\t\tcontroller.signal.removeEventListener(\"abort\", onInternal);\n\t\t}\n\t}\n}\n"]}