open-multi-agent-kit 1.0.0 → 1.2.0

package/dist/metacognition/checkpoint.js

@@ -0,0 +1,57 @@
+import { instantiateObligations } from "./obligations.js";
+import { selectAction } from "./policy.js";
+import { finishState, validateMetaState } from "./state.js";
+import { integer } from "./validation.js";
+import { evaluateVerifier } from "./verifier.js";
+/**
+ * One checkpoint evaluation. Refreshes obligations from observed atoms when
+ * provided, resolves registered predictions against fresh observations when
+ * provided, evaluates verifier mutants when provided, then selects the next
+ * action under the §14 priority table.
+ */
+export function checkpoint(input) {
+    integer(input.nowMs, "nowMs");
+    validateMetaState(input.state);
+    let state = input.state;
+    let newObligations = 0;
+    if (input.atoms && input.rules) {
+        const report = instantiateObligations(input.atoms, input.rules, input.nowMs);
+        const merged = [...state.obligations, ...report.required, ...report.candidates];
+        newObligations = report.required.length + report.candidates.length;
+        state = { ...state, obligations: merged };
+    }
+    let mismatches = 0;
+    for (const p of state.predictions) {
+        if (p.status === "resolved" && p.mismatch !== undefined && p.mismatch !== "none")
+            mismatches += 1;
+    }
+    const verifierEvaluations = [...state.verifier.evaluations];
+    if (input.mutants) {
+        for (const obligation of state.obligations) {
+            const scoped = input.mutants.filter((m) => m.obligationId === obligation.id);
+            if (scoped.length === 0)
+                continue;
+            verifierEvaluations.push(evaluateVerifier(obligation.id, input.mutants, state.verifier.runnerHealth === "healthy"));
+        }
+        state = { ...state, verifier: { ...state.verifier, evaluations: verifierEvaluations } };
+    }
+    const action = selectAction(state, input.constraints, {
+        receipt: input.receipt ?? null,
+        maxRepetitions: input.options?.maxRepetitions,
+        switchCost: input.options?.switchCost,
+        estimatedSwitchGain: input.options?.estimatedSwitchGain,
+        voiCandidates: input.options?.voiCandidates,
+        progress: input.options?.progress,
+    });
+    const finish = finishState(state, input.receipt ?? null);
+    return {
+        state: { ...state, checkpointCount: state.checkpointCount + 1 },
+        action,
+        finish,
+        newObligations,
+        newPredictions: 0,
+        mismatches,
+        verifierEvaluations,
+    };
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/metacognition/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../../src/metacognition/checkpoint.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * §9.4 checkpoint ordering: refresh obligations from host observations,\n * evaluate knowledge gaps, classify prediction mismatches, evaluate verifier\n * blind spots and runner health, then select one bounded action.\n *\n * The host calls this at a safe decision boundary — never mid-stream, and\n * never as a path for model reasoning to remove a `required` obligation.\n */\nimport type { ChangeAtom, ObligationRule } from \"./obligations.ts\";\nimport { instantiateObligations } from \"./obligations.ts\";\nimport { type ActionConstraints, type MetaAction, type MetaActionKind, selectAction } from \"./policy.ts\";\nimport type { MetaState } from \"./state.ts\";\nimport { type FinishState, finishState, validateMetaState } from \"./state.ts\";\nimport { integer } from \"./validation.ts\";\nimport { evaluateVerifier, type MutantRecord, type VerifierEvaluation } from \"./verifier.ts\";\n\nexport interface CheckpointInput {\n\treadonly state: MetaState;\n\treadonly atoms?: readonly ChangeAtom[];\n\treadonly rules?: readonly ObligationRule[];\n\treadonly nowMs: number;\n\treadonly constraints: ActionConstraints;\n\treadonly mutants?: readonly MutantRecord[];\n\treadonly receipt?: { receiptId: string; candidateHash: string; scope: string } | null;\n\treadonly options?: {\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\treadonly goalScope: string;\n\t\t\treadonly candidateFamily: string;\n\t\t\treadonly errorClass: string;\n\t\t\treadonly approach: string;\n\t\t\treadonly checkMethod: string;\n\t\t\treadonly sourceFamily: string;\n\t\t};\n\t};\n}\nexport interface CheckpointResult {\n\treadonly state: MetaState;\n\treadonly action: MetaAction;\n\treadonly finish: FinishState;\n\treadonly newObligations: number;\n\treadonly newPredictions: number;\n\treadonly mismatches: number;\n\treadonly verifierEvaluations: readonly VerifierEvaluation[];\n}\n\n/**\n * One checkpoint evaluation. Refreshes obligations from observed atoms when\n * provided, resolves registered predictions against fresh observations when\n * provided, evaluates verifier mutants when provided, then selects the next\n * action under the §14 priority table.\n */\nexport function checkpoint(input: CheckpointInput): CheckpointResult {\n\tinteger(input.nowMs, \"nowMs\");\n\tvalidateMetaState(input.state);\n\tlet state = input.state;\n\tlet newObligations = 0;\n\tif (input.atoms && input.rules) {\n\t\tconst report = instantiateObligations(input.atoms, input.rules, input.nowMs);\n\t\tconst merged = [...state.obligations, ...report.required, ...report.candidates];\n\t\tnewObligations = report.required.length + report.candidates.length;\n\t\tstate = { ...state, obligations: merged };\n\t}\n\tlet mismatches = 0;\n\tfor (const p of state.predictions) {\n\t\tif (p.status === \"resolved\" && p.mismatch !== undefined && p.mismatch !== \"none\") mismatches += 1;\n\t}\n\tconst verifierEvaluations: VerifierEvaluation[] = [...state.verifier.evaluations];\n\tif (input.mutants) {\n\t\tfor (const obligation of state.obligations) {\n\t\t\tconst scoped = input.mutants.filter((m) => m.obligationId === obligation.id);\n\t\t\tif (scoped.length === 0) continue;\n\t\t\tverifierEvaluations.push(\n\t\t\t\tevaluateVerifier(obligation.id, input.mutants, state.verifier.runnerHealth === \"healthy\"),\n\t\t\t);\n\t\t}\n\t\tstate = { ...state, verifier: { ...state.verifier, evaluations: verifierEvaluations } };\n\t}\n\tconst action = selectAction(state, input.constraints, {\n\t\treceipt: input.receipt ?? null,\n\t\tmaxRepetitions: input.options?.maxRepetitions,\n\t\tswitchCost: input.options?.switchCost,\n\t\testimatedSwitchGain: input.options?.estimatedSwitchGain,\n\t\tvoiCandidates: input.options?.voiCandidates,\n\t\tprogress: input.options?.progress,\n\t});\n\tconst finish = finishState(state, input.receipt ?? null);\n\treturn {\n\t\tstate: { ...state, checkpointCount: state.checkpointCount + 1 },\n\t\taction,\n\t\tfinish,\n\t\tnewObligations,\n\t\tnewPredictions: 0,\n\t\tmismatches,\n\t\tverifierEvaluations,\n\t};\n}\n"]}

package/dist/metacognition/context7.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Fixed-origin Context7 GET adapter with explicit egress approval.
+ *
+ * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip
+ * (src/context7.ts). Every attempted HTTP request consumes a shared
+ * AcquisitionPool permit; there is no retry, redirect-following, or
+ * auto-selection of the first result. Returned `rules` fields are data, never
+ * promoted to instructions.
+ */
+import type { AcquisitionPool, AcquisitionResult } from "./retrieval.ts";
+export interface Context7Options {
+    readonly apiKey: string;
+    readonly enabled: boolean;
+    readonly approvedLibraryNames: readonly string[];
+    readonly approvedLibraryIds: readonly string[];
+    readonly approvedQueries: readonly string[];
+    readonly pool: AcquisitionPool;
+    readonly maxResponseBytes?: number;
+    readonly fetchImpl?: typeof fetch;
+}
+export interface LibraryCandidate {
+    readonly id: string;
+    readonly title: string;
+    readonly versions: readonly string[];
+}
+export interface DocumentationCandidate {
+    readonly uri: string;
+    readonly body: string;
+    readonly requestedLibraryId: string;
+    readonly trust: "candidate-only";
+}
+/** Fixed-origin GET adapter. In OMK prefer routing equivalent requests through admitted MCP tools. */
+export declare class Context7Client {
+    private readonly key;
+    private readonly enabled;
+    private readonly names;
+    private readonly ids;
+    private readonly queries;
+    private readonly pool;
+    private readonly fetcher;
+    private readonly limit;
+    constructor(options: Context7Options);
+    resolveLibraries(name: string, query: string, signal?: AbortSignal): Promise<AcquisitionResult<readonly LibraryCandidate[]>>;
+    getDocumentation(id: string, query: string, signal?: AbortSignal): Promise<AcquisitionResult<readonly DocumentationCandidate[]>>;
+    private authorize;
+    private get;
+}
+//# sourceMappingURL=context7.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context7.d.ts","sourceRoot":"","sources":["../../src/metacognition/context7.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGzE,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAClC;AACD,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AACD,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;CACjC;AACD,sGAAsG;AACtG,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,YAAY,OAAO,EAAE,eAAe,EAanC;IACD,gBAAgB,CACf,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,iBAAiB,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAAC,CAkBzD;IACD,gBAAgB,CACf,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,iBAAiB,CAAC,SAAS,sBAAsB,EAAE,CAAC,CAAC,CAqC/D;IACD,OAAO,CAAC,SAAS;YAKH,GAAG;CAiDjB","sourcesContent":["/**\n * Fixed-origin Context7 GET adapter with explicit egress approval.\n *\n * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip\n * (src/context7.ts). Every attempted HTTP request consumes a shared\n * AcquisitionPool permit; there is no retry, redirect-following, or\n * auto-selection of the first result. Returned `rules` fields are data, never\n * promoted to instructions.\n */\nimport type { AcquisitionPool, AcquisitionResult } from \"./retrieval.ts\";\nimport { ensure, integer, text } from \"./validation.ts\";\n\nexport interface Context7Options {\n\treadonly apiKey: string;\n\treadonly enabled: boolean;\n\treadonly approvedLibraryNames: readonly string[];\n\treadonly approvedLibraryIds: readonly string[];\n\treadonly approvedQueries: readonly string[];\n\treadonly pool: AcquisitionPool;\n\treadonly maxResponseBytes?: number;\n\treadonly fetchImpl?: typeof fetch;\n}\nexport interface LibraryCandidate {\n\treadonly id: string;\n\treadonly title: string;\n\treadonly versions: readonly string[];\n}\nexport interface DocumentationCandidate {\n\treadonly uri: string;\n\treadonly body: string;\n\treadonly requestedLibraryId: string;\n\treadonly trust: \"candidate-only\";\n}\n/** Fixed-origin GET adapter. In OMK prefer routing equivalent requests through admitted MCP tools. */\nexport class Context7Client {\n\tprivate readonly key: string;\n\tprivate readonly enabled: boolean;\n\tprivate readonly names: ReadonlySet<string>;\n\tprivate readonly ids: ReadonlySet<string>;\n\tprivate readonly queries: ReadonlySet<string>;\n\tprivate readonly pool: AcquisitionPool;\n\tprivate readonly fetcher: typeof fetch;\n\tprivate readonly limit: number;\n\tconstructor(options: Context7Options) {\n\t\ttext(options.apiKey, \"apiKey\", 4096);\n\t\tensure(typeof options.enabled === \"boolean\", \"enabled must be boolean\");\n\t\tthis.limit = options.maxResponseBytes ?? 200_000;\n\t\tinteger(this.limit, \"maxResponseBytes\", 2_000_000);\n\t\tensure(this.limit > 0, \"response limit must be positive\");\n\t\tthis.key = options.apiKey;\n\t\tthis.enabled = options.enabled;\n\t\tthis.names = new Set(options.approvedLibraryNames);\n\t\tthis.ids = new Set(options.approvedLibraryIds);\n\t\tthis.queries = new Set(options.approvedQueries);\n\t\tthis.pool = options.pool;\n\t\tthis.fetcher = options.fetchImpl ?? fetch;\n\t}\n\tresolveLibraries(\n\t\tname: string,\n\t\tquery: string,\n\t\tsignal?: AbortSignal,\n\t): Promise<AcquisitionResult<readonly LibraryCandidate[]>> {\n\t\tthis.authorize(query);\n\t\ttext(name, \"libraryName\", 500);\n\t\tensure(this.names.has(name), \"unapproved library name\");\n\t\treturn this.pool.run(async (abort) => {\n\t\t\tconst payload = await this.get(\"/api/v2/libs/search\", { libraryName: name, query }, abort);\n\t\t\tconst object = record(payload);\n\t\t\tensure(Array.isArray(object.results), \"invalid search response\");\n\t\t\tensure(object.results.length <= 256, \"too many library candidates\");\n\t\t\treturn object.results.map((raw): LibraryCandidate => {\n\t\t\t\tconst candidate = record(raw);\n\t\t\t\tconst id = string(candidate.id),\n\t\t\t\t\ttitle = string(candidate.title);\n\t\t\t\tconst versions = candidate.versions ?? [];\n\t\t\t\tensure(Array.isArray(versions) && versions.every((v) => typeof v === \"string\"), \"invalid versions\");\n\t\t\t\treturn { id, title, versions: versions as string[] };\n\t\t\t});\n\t\t}, signal);\n\t}\n\tgetDocumentation(\n\t\tid: string,\n\t\tquery: string,\n\t\tsignal?: AbortSignal,\n\t): Promise<AcquisitionResult<readonly DocumentationCandidate[]>> {\n\t\tthis.authorize(query);\n\t\ttext(id, \"libraryId\", 500);\n\t\tensure(this.ids.has(id), \"unapproved library id: validate identity/version before retrieval\");\n\t\treturn this.pool.run(async (abort) => {\n\t\t\tconst object = record(await this.get(\"/api/v2/context\", { libraryId: id, query, type: \"json\" }, abort));\n\t\t\tconst info = object.infoSnippets,\n\t\t\t\tcode = object.codeSnippets;\n\t\t\tensure(Array.isArray(info) && Array.isArray(code), \"invalid documentation response\");\n\t\t\tensure(info.length + code.length <= 256, \"too many snippets\");\n\t\t\tconst result: DocumentationCandidate[] = [];\n\t\t\tconst add = (uri: unknown, body: string): void => {\n\t\t\t\tif (typeof uri !== \"string\") return;\n\t\t\t\tlet parsed: URL;\n\t\t\t\ttry {\n\t\t\t\t\tparsed = new URL(uri);\n\t\t\t\t} catch {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\t// Metadata only, never followed. Reject executable/non-web references.\n\t\t\t\tif (parsed.protocol !== \"https:\" || parsed.username || parsed.password) return;\n\t\t\t\tresult.push({ uri: parsed.href, body, requestedLibraryId: id, trust: \"candidate-only\" });\n\t\t\t};\n\t\t\tfor (const raw of info) {\n\t\t\t\tconst v = record(raw);\n\t\t\t\tadd(v.pageId, string(v.content));\n\t\t\t}\n\t\t\tfor (const raw of code) {\n\t\t\t\tconst v = record(raw);\n\t\t\t\tconst list = v.codeList;\n\t\t\t\tensure(Array.isArray(list), \"invalid codeList\");\n\t\t\t\tconst body = list.map((item) => string(record(item).code)).join(\"\\n\\n\");\n\t\t\t\tadd(v.codeId, body);\n\t\t\t}\n\t\t\t// The response's optional `rules` field is deliberately not promoted to instructions.\n\t\t\treturn result;\n\t\t}, signal);\n\t}\n\tprivate authorize(query: string): void {\n\t\tensure(this.enabled, \"remote acquisition disabled\");\n\t\ttext(query, \"public query\", 500);\n\t\tensure(this.queries.has(query), \"query has not been approved for egress\");\n\t}\n\tprivate async get(path: string, parameters: Record<string, string>, signal: AbortSignal): Promise<unknown> {\n\t\tconst url = new URL(path, \"https://context7.com\");\n\t\tfor (const [key, value] of Object.entries(parameters)) url.searchParams.set(key, value);\n\t\tconst response = await this.fetcher(url, {\n\t\t\tmethod: \"GET\",\n\t\t\tredirect: \"error\",\n\t\t\tsignal,\n\t\t\theaders: { Authorization: `Bearer ${this.key}`, Accept: \"application/json\" },\n\t\t});\n\t\t// No retry here: every attempted HTTP request must acquire a fresh shared budget slot.\n\t\tif (response.status !== 200) {\n\t\t\tif (response.body) await response.body.cancel();\n\t\t\tthrow new Error(`context7-http-${response.status}`);\n\t\t}\n\t\tconst contentType = response.headers.get(\"content-type\") ?? \"\";\n\t\tif (!contentType.includes(\"application/json\")) {\n\t\t\tif (response.body) await response.body.cancel();\n\t\t\tthrow new Error(\"unexpected response content type\");\n\t\t}\n\t\tensure(response.body !== null, \"missing response body\");\n\t\tconst reader = response.body.getReader();\n\t\tlet bytes = 0;\n\t\tconst chunks: Uint8Array[] = [];\n\t\ttry {\n\t\t\twhile (true) {\n\t\t\t\tconst next = await reader.read();\n\t\t\t\tif (next.done) break;\n\t\t\t\tbytes += next.value.byteLength;\n\t\t\t\tensure(bytes <= this.limit, \"response byte budget exceeded\");\n\t\t\t\tchunks.push(next.value);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tawait reader.cancel();\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\treader.releaseLock();\n\t\t}\n\t\tconst joined = new Uint8Array(bytes);\n\t\tlet at = 0;\n\t\tfor (const chunk of chunks) {\n\t\t\tjoined.set(chunk, at);\n\t\t\tat += chunk.byteLength;\n\t\t}\n\t\ttry {\n\t\t\treturn JSON.parse(new TextDecoder(\"utf-8\", { fatal: true }).decode(joined)) as unknown;\n\t\t} catch {\n\t\t\tthrow new Error(\"malformed context7 response body\");\n\t\t}\n\t}\n}\nfunction record(value: unknown): Record<string, unknown> {\n\tensure(value !== null && typeof value === \"object\" && !Array.isArray(value), \"expected response object\");\n\treturn value as Record<string, unknown>;\n}\nfunction string(value: unknown): string {\n\tensure(typeof value === \"string\", \"expected response string\");\n\treturn value;\n}\n"]}

package/dist/metacognition/context7.js

@@ -0,0 +1,154 @@
+import { ensure, integer, text } from "./validation.js";
+/** Fixed-origin GET adapter. In OMK prefer routing equivalent requests through admitted MCP tools. */
+export class Context7Client {
+    key;
+    enabled;
+    names;
+    ids;
+    queries;
+    pool;
+    fetcher;
+    limit;
+    constructor(options) {
+        text(options.apiKey, "apiKey", 4096);
+        ensure(typeof options.enabled === "boolean", "enabled must be boolean");
+        this.limit = options.maxResponseBytes ?? 200_000;
+        integer(this.limit, "maxResponseBytes", 2_000_000);
+        ensure(this.limit > 0, "response limit must be positive");
+        this.key = options.apiKey;
+        this.enabled = options.enabled;
+        this.names = new Set(options.approvedLibraryNames);
+        this.ids = new Set(options.approvedLibraryIds);
+        this.queries = new Set(options.approvedQueries);
+        this.pool = options.pool;
+        this.fetcher = options.fetchImpl ?? fetch;
+    }
+    resolveLibraries(name, query, signal) {
+        this.authorize(query);
+        text(name, "libraryName", 500);
+        ensure(this.names.has(name), "unapproved library name");
+        return this.pool.run(async (abort) => {
+            const payload = await this.get("/api/v2/libs/search", { libraryName: name, query }, abort);
+            const object = record(payload);
+            ensure(Array.isArray(object.results), "invalid search response");
+            ensure(object.results.length <= 256, "too many library candidates");
+            return object.results.map((raw) => {
+                const candidate = record(raw);
+                const id = string(candidate.id), title = string(candidate.title);
+                const versions = candidate.versions ?? [];
+                ensure(Array.isArray(versions) && versions.every((v) => typeof v === "string"), "invalid versions");
+                return { id, title, versions: versions };
+            });
+        }, signal);
+    }
+    getDocumentation(id, query, signal) {
+        this.authorize(query);
+        text(id, "libraryId", 500);
+        ensure(this.ids.has(id), "unapproved library id: validate identity/version before retrieval");
+        return this.pool.run(async (abort) => {
+            const object = record(await this.get("/api/v2/context", { libraryId: id, query, type: "json" }, abort));
+            const info = object.infoSnippets, code = object.codeSnippets;
+            ensure(Array.isArray(info) && Array.isArray(code), "invalid documentation response");
+            ensure(info.length + code.length <= 256, "too many snippets");
+            const result = [];
+            const add = (uri, body) => {
+                if (typeof uri !== "string")
+                    return;
+                let parsed;
+                try {
+                    parsed = new URL(uri);
+                }
+                catch {
+                    return;
+                }
+                // Metadata only, never followed. Reject executable/non-web references.
+                if (parsed.protocol !== "https:" || parsed.username || parsed.password)
+                    return;
+                result.push({ uri: parsed.href, body, requestedLibraryId: id, trust: "candidate-only" });
+            };
+            for (const raw of info) {
+                const v = record(raw);
+                add(v.pageId, string(v.content));
+            }
+            for (const raw of code) {
+                const v = record(raw);
+                const list = v.codeList;
+                ensure(Array.isArray(list), "invalid codeList");
+                const body = list.map((item) => string(record(item).code)).join("\n\n");
+                add(v.codeId, body);
+            }
+            // The response's optional `rules` field is deliberately not promoted to instructions.
+            return result;
+        }, signal);
+    }
+    authorize(query) {
+        ensure(this.enabled, "remote acquisition disabled");
+        text(query, "public query", 500);
+        ensure(this.queries.has(query), "query has not been approved for egress");
+    }
+    async get(path, parameters, signal) {
+        const url = new URL(path, "https://context7.com");
+        for (const [key, value] of Object.entries(parameters))
+            url.searchParams.set(key, value);
+        const response = await this.fetcher(url, {
+            method: "GET",
+            redirect: "error",
+            signal,
+            headers: { Authorization: `Bearer ${this.key}`, Accept: "application/json" },
+        });
+        // No retry here: every attempted HTTP request must acquire a fresh shared budget slot.
+        if (response.status !== 200) {
+            if (response.body)
+                await response.body.cancel();
+            throw new Error(`context7-http-${response.status}`);
+        }
+        const contentType = response.headers.get("content-type") ?? "";
+        if (!contentType.includes("application/json")) {
+            if (response.body)
+                await response.body.cancel();
+            throw new Error("unexpected response content type");
+        }
+        ensure(response.body !== null, "missing response body");
+        const reader = response.body.getReader();
+        let bytes = 0;
+        const chunks = [];
+        try {
+            while (true) {
+                const next = await reader.read();
+                if (next.done)
+                    break;
+                bytes += next.value.byteLength;
+                ensure(bytes <= this.limit, "response byte budget exceeded");
+                chunks.push(next.value);
+            }
+        }
+        catch (error) {
+            await reader.cancel();
+            throw error;
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const joined = new Uint8Array(bytes);
+        let at = 0;
+        for (const chunk of chunks) {
+            joined.set(chunk, at);
+            at += chunk.byteLength;
+        }
+        try {
+            return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(joined));
+        }
+        catch {
+            throw new Error("malformed context7 response body");
+        }
+    }
+}
+function record(value) {
+    ensure(value !== null && typeof value === "object" && !Array.isArray(value), "expected response object");
+    return value;
+}
+function string(value) {
+    ensure(typeof value === "string", "expected response string");
+    return value;
+}
+//# sourceMappingURL=context7.js.map

package/dist/metacognition/context7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context7.js","sourceRoot":"","sources":["../../src/metacognition/context7.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Fixed-origin Context7 GET adapter with explicit egress approval.\n *\n * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip\n * (src/context7.ts). Every attempted HTTP request consumes a shared\n * AcquisitionPool permit; there is no retry, redirect-following, or\n * auto-selection of the first result. Returned `rules` fields are data, never\n * promoted to instructions.\n */\nimport type { AcquisitionPool, AcquisitionResult } from \"./retrieval.ts\";\nimport { ensure, integer, text } from \"./validation.ts\";\n\nexport interface Context7Options {\n\treadonly apiKey: string;\n\treadonly enabled: boolean;\n\treadonly approvedLibraryNames: readonly string[];\n\treadonly approvedLibraryIds: readonly string[];\n\treadonly approvedQueries: readonly string[];\n\treadonly pool: AcquisitionPool;\n\treadonly maxResponseBytes?: number;\n\treadonly fetchImpl?: typeof fetch;\n}\nexport interface LibraryCandidate {\n\treadonly id: string;\n\treadonly title: string;\n\treadonly versions: readonly string[];\n}\nexport interface DocumentationCandidate {\n\treadonly uri: string;\n\treadonly body: string;\n\treadonly requestedLibraryId: string;\n\treadonly trust: \"candidate-only\";\n}\n/** Fixed-origin GET adapter. In OMK prefer routing equivalent requests through admitted MCP tools. */\nexport class Context7Client {\n\tprivate readonly key: string;\n\tprivate readonly enabled: boolean;\n\tprivate readonly names: ReadonlySet<string>;\n\tprivate readonly ids: ReadonlySet<string>;\n\tprivate readonly queries: ReadonlySet<string>;\n\tprivate readonly pool: AcquisitionPool;\n\tprivate readonly fetcher: typeof fetch;\n\tprivate readonly limit: number;\n\tconstructor(options: Context7Options) {\n\t\ttext(options.apiKey, \"apiKey\", 4096);\n\t\tensure(typeof options.enabled === \"boolean\", \"enabled must be boolean\");\n\t\tthis.limit = options.maxResponseBytes ?? 200_000;\n\t\tinteger(this.limit, \"maxResponseBytes\", 2_000_000);\n\t\tensure(this.limit > 0, \"response limit must be positive\");\n\t\tthis.key = options.apiKey;\n\t\tthis.enabled = options.enabled;\n\t\tthis.names = new Set(options.approvedLibraryNames);\n\t\tthis.ids = new Set(options.approvedLibraryIds);\n\t\tthis.queries = new Set(options.approvedQueries);\n\t\tthis.pool = options.pool;\n\t\tthis.fetcher = options.fetchImpl ?? fetch;\n\t}\n\tresolveLibraries(\n\t\tname: string,\n\t\tquery: string,\n\t\tsignal?: AbortSignal,\n\t): Promise<AcquisitionResult<readonly LibraryCandidate[]>> {\n\t\tthis.authorize(query);\n\t\ttext(name, \"libraryName\", 500);\n\t\tensure(this.names.has(name), \"unapproved library name\");\n\t\treturn this.pool.run(async (abort) => {\n\t\t\tconst payload = await this.get(\"/api/v2/libs/search\", { libraryName: name, query }, abort);\n\t\t\tconst object = record(payload);\n\t\t\tensure(Array.isArray(object.results), \"invalid search response\");\n\t\t\tensure(object.results.length <= 256, \"too many library candidates\");\n\t\t\treturn object.results.map((raw): LibraryCandidate => {\n\t\t\t\tconst candidate = record(raw);\n\t\t\t\tconst id = string(candidate.id),\n\t\t\t\t\ttitle = string(candidate.title);\n\t\t\t\tconst versions = candidate.versions ?? [];\n\t\t\t\tensure(Array.isArray(versions) && versions.every((v) => typeof v === \"string\"), \"invalid versions\");\n\t\t\t\treturn { id, title, versions: versions as string[] };\n\t\t\t});\n\t\t}, signal);\n\t}\n\tgetDocumentation(\n\t\tid: string,\n\t\tquery: string,\n\t\tsignal?: AbortSignal,\n\t): Promise<AcquisitionResult<readonly DocumentationCandidate[]>> {\n\t\tthis.authorize(query);\n\t\ttext(id, \"libraryId\", 500);\n\t\tensure(this.ids.has(id), \"unapproved library id: validate identity/version before retrieval\");\n\t\treturn this.pool.run(async (abort) => {\n\t\t\tconst object = record(await this.get(\"/api/v2/context\", { libraryId: id, query, type: \"json\" }, abort));\n\t\t\tconst info = object.infoSnippets,\n\t\t\t\tcode = object.codeSnippets;\n\t\t\tensure(Array.isArray(info) && Array.isArray(code), \"invalid documentation response\");\n\t\t\tensure(info.length + code.length <= 256, \"too many snippets\");\n\t\t\tconst result: DocumentationCandidate[] = [];\n\t\t\tconst add = (uri: unknown, body: string): void => {\n\t\t\t\tif (typeof uri !== \"string\") return;\n\t\t\t\tlet parsed: URL;\n\t\t\t\ttry {\n\t\t\t\t\tparsed = new URL(uri);\n\t\t\t\t} catch {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\t// Metadata only, never followed. Reject executable/non-web references.\n\t\t\t\tif (parsed.protocol !== \"https:\" || parsed.username || parsed.password) return;\n\t\t\t\tresult.push({ uri: parsed.href, body, requestedLibraryId: id, trust: \"candidate-only\" });\n\t\t\t};\n\t\t\tfor (const raw of info) {\n\t\t\t\tconst v = record(raw);\n\t\t\t\tadd(v.pageId, string(v.content));\n\t\t\t}\n\t\t\tfor (const raw of code) {\n\t\t\t\tconst v = record(raw);\n\t\t\t\tconst list = v.codeList;\n\t\t\t\tensure(Array.isArray(list), \"invalid codeList\");\n\t\t\t\tconst body = list.map((item) => string(record(item).code)).join(\"\\n\\n\");\n\t\t\t\tadd(v.codeId, body);\n\t\t\t}\n\t\t\t// The response's optional `rules` field is deliberately not promoted to instructions.\n\t\t\treturn result;\n\t\t}, signal);\n\t}\n\tprivate authorize(query: string): void {\n\t\tensure(this.enabled, \"remote acquisition disabled\");\n\t\ttext(query, \"public query\", 500);\n\t\tensure(this.queries.has(query), \"query has not been approved for egress\");\n\t}\n\tprivate async get(path: string, parameters: Record<string, string>, signal: AbortSignal): Promise<unknown> {\n\t\tconst url = new URL(path, \"https://context7.com\");\n\t\tfor (const [key, value] of Object.entries(parameters)) url.searchParams.set(key, value);\n\t\tconst response = await this.fetcher(url, {\n\t\t\tmethod: \"GET\",\n\t\t\tredirect: \"error\",\n\t\t\tsignal,\n\t\t\theaders: { Authorization: `Bearer ${this.key}`, Accept: \"application/json\" },\n\t\t});\n\t\t// No retry here: every attempted HTTP request must acquire a fresh shared budget slot.\n\t\tif (response.status !== 200) {\n\t\t\tif (response.body) await response.body.cancel();\n\t\t\tthrow new Error(`context7-http-${response.status}`);\n\t\t}\n\t\tconst contentType = response.headers.get(\"content-type\") ?? \"\";\n\t\tif (!contentType.includes(\"application/json\")) {\n\t\t\tif (response.body) await response.body.cancel();\n\t\t\tthrow new Error(\"unexpected response content type\");\n\t\t}\n\t\tensure(response.body !== null, \"missing response body\");\n\t\tconst reader = response.body.getReader();\n\t\tlet bytes = 0;\n\t\tconst chunks: Uint8Array[] = [];\n\t\ttry {\n\t\t\twhile (true) {\n\t\t\t\tconst next = await reader.read();\n\t\t\t\tif (next.done) break;\n\t\t\t\tbytes += next.value.byteLength;\n\t\t\t\tensure(bytes <= this.limit, \"response byte budget exceeded\");\n\t\t\t\tchunks.push(next.value);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tawait reader.cancel();\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\treader.releaseLock();\n\t\t}\n\t\tconst joined = new Uint8Array(bytes);\n\t\tlet at = 0;\n\t\tfor (const chunk of chunks) {\n\t\t\tjoined.set(chunk, at);\n\t\t\tat += chunk.byteLength;\n\t\t}\n\t\ttry {\n\t\t\treturn JSON.parse(new TextDecoder(\"utf-8\", { fatal: true }).decode(joined)) as unknown;\n\t\t} catch {\n\t\t\tthrow new Error(\"malformed context7 response body\");\n\t\t}\n\t}\n}\nfunction record(value: unknown): Record<string, unknown> {\n\tensure(value !== null && typeof value === \"object\" && !Array.isArray(value), \"expected response object\");\n\treturn value as Record<string, unknown>;\n}\nfunction string(value: unknown): string {\n\tensure(typeof value === \"string\", \"expected response string\");\n\treturn value;\n}\n"]}

package/dist/metacognition/decision.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Minimum expected loss over a finite set of terminal decisions.
+ * losses[d][h] is the loss of decision d when hypothesis h is true.
+ */
+export declare function bayesRisk(prior: readonly number[], losses: readonly (readonly number[])[]): number;
+export interface ExperimentBranch {
+    readonly outcome: number;
+    readonly probability: number;
+    readonly posterior: readonly number[];
+    readonly risk: number;
+}
+export interface ExperimentValue {
+    readonly before: number;
+    readonly expectedAfter: number;
+    readonly grossValue: number;
+    readonly cost: number;
+    readonly netValue: number;
+    readonly branches: readonly ExperimentBranch[];
+}
+/**
+ * One-step value of information: Bayes risk before minus expected Bayes risk
+ * after observing the experiment outcome, minus the experiment cost.
+ * likelihoodByHypothesis[h][o] = P(outcome o | hypothesis h).
+ * Zero-probability outcomes are skipped; the caller must treat an actually
+ * observed impossible outcome as a model mismatch, never renormalize it away.
+ */
+export declare function experimentValue(prior: readonly number[], losses: readonly (readonly number[])[], likelihoodByHypothesis: readonly (readonly number[])[], cost: number): ExperimentValue;
+/** Brier score for one binary event. */
+export declare function brier(predicted: number, outcome: 0 | 1): number;
+/** Negative log-likelihood surprise for one binary event (epsilon-clamped). */
+export declare function surprise(predicted: number, outcome: 0 | 1, epsilon?: number): number;
+/**
+ * Beta posterior mean for an independent binary task outcome under a fixed
+ * policy in a homogeneous condition bucket. The prior (alpha, beta) must be
+ * declared by the host; this is not a learned-calibration claim.
+ */
+export declare function betaPosteriorMean(alpha: number, beta: number, successes: number, failures: number): number;
+/**
+ * CUSUM-style drift accumulator over per-observation losses in one condition
+ * bucket. Returns the new accumulator value; the caller compares it against
+ * a host-declared threshold h_g. Not a guaranteed false-alarm rate.
+ */
+export declare function driftStatistic(previous: number, loss: number, referenceMean: number, slack: number): number;
+//# sourceMappingURL=decision.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../../src/metacognition/decision.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,GAAG,MAAM,CAclG;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AACD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC/C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACtC,sBAAsB,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACtD,IAAI,EAAE,MAAM,GACV,eAAe,CA8BjB;AAED,wCAAwC;AACxC,wBAAgB,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,MAAM,CAI/D;AAED,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,SAAQ,GAAG,MAAM,CAMnF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO1G;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM3G","sourcesContent":["/**\n * Finite decision-model arithmetic for metacognitive control.\n *\n * TypeScript port of docs/OMK_meta_algorithm_checks_2026-09-19.zip\n * (check_examples.py) — the numerical checks referenced by\n * OMK_metacognitive_control_algorithms_2026-09-19.md §5.3, §6.2.\n *\n * These are illustrative finite-model computations, NOT measured OMK risk\n * estimates. Callers must supply real, defensible probabilities; this module\n * only guarantees the arithmetic is correct and rejects malformed inputs.\n */\nimport { ensure, finite, probability, probabilityVector } from \"./validation.ts\";\n\n/**\n * Minimum expected loss over a finite set of terminal decisions.\n * losses[d][h] is the loss of decision d when hypothesis h is true.\n */\nexport function bayesRisk(prior: readonly number[], losses: readonly (readonly number[])[]): number {\n\tprobabilityVector(prior, \"prior\");\n\tensure(losses.length > 0, \"at least one terminal decision is required\");\n\tlet best = Number.POSITIVE_INFINITY;\n\tfor (const row of losses) {\n\t\tensure(row.length === prior.length, \"loss row must match hypotheses\");\n\t\tlet risk = 0;\n\t\tfor (let h = 0; h < prior.length; h++) {\n\t\t\tfinite(row[h]!, \"loss\");\n\t\t\trisk += prior[h]! * row[h]!;\n\t\t}\n\t\tif (risk < best) best = risk;\n\t}\n\treturn best;\n}\n\nexport interface ExperimentBranch {\n\treadonly outcome: number;\n\treadonly probability: number;\n\treadonly posterior: readonly number[];\n\treadonly risk: number;\n}\nexport interface ExperimentValue {\n\treadonly before: number;\n\treadonly expectedAfter: number;\n\treadonly grossValue: number;\n\treadonly cost: number;\n\treadonly netValue: number;\n\treadonly branches: readonly ExperimentBranch[];\n}\n\n/**\n * One-step value of information: Bayes risk before minus expected Bayes risk\n * after observing the experiment outcome, minus the experiment cost.\n * likelihoodByHypothesis[h][o] = P(outcome o | hypothesis h).\n * Zero-probability outcomes are skipped; the caller must treat an actually\n * observed impossible outcome as a model mismatch, never renormalize it away.\n */\nexport function experimentValue(\n\tprior: readonly number[],\n\tlosses: readonly (readonly number[])[],\n\tlikelihoodByHypothesis: readonly (readonly number[])[],\n\tcost: number,\n): ExperimentValue {\n\tprobabilityVector(prior, \"prior\");\n\tfinite(cost, \"cost\");\n\tconst rows = likelihoodByHypothesis.map((row) => {\n\t\tprobabilityVector(row, \"likelihood\");\n\t\treturn row;\n\t});\n\tensure(rows.length === prior.length, \"likelihood matrix must match hypotheses\");\n\tensure(new Set(rows.map((r) => r.length)).size === 1, \"likelihood matrix shape mismatch\");\n\tconst outcomeCount = rows[0]!.length;\n\tconst before = bayesRisk(prior, losses);\n\tconst branches: ExperimentBranch[] = [];\n\tlet expectedAfter = 0;\n\tfor (let outcome = 0; outcome < outcomeCount; outcome++) {\n\t\tconst masses = prior.map((p, h) => p * rows[h]![outcome]!);\n\t\tconst marginal = masses.reduce((a, b) => a + b, 0);\n\t\tif (marginal === 0) continue;\n\t\tconst posterior = masses.map((m) => m / marginal);\n\t\tconst after = bayesRisk(posterior, losses);\n\t\texpectedAfter += marginal * after;\n\t\tbranches.push({ outcome, probability: marginal, posterior, risk: after });\n\t}\n\treturn {\n\t\tbefore,\n\t\texpectedAfter,\n\t\tgrossValue: before - expectedAfter,\n\t\tcost,\n\t\tnetValue: before - expectedAfter - cost,\n\t\tbranches,\n\t};\n}\n\n/** Brier score for one binary event. */\nexport function brier(predicted: number, outcome: 0 | 1): number {\n\tprobability(predicted, \"predicted\");\n\tconst p = outcome === 1 ? predicted : 1 - predicted;\n\treturn (1 - p) ** 2;\n}\n\n/** Negative log-likelihood surprise for one binary event (epsilon-clamped). */\nexport function surprise(predicted: number, outcome: 0 | 1, epsilon = 1e-12): number {\n\tprobability(predicted, \"predicted\");\n\tfinite(epsilon, \"epsilon\", 1);\n\tensure(epsilon > 0, \"epsilon must be positive\");\n\tconst p = outcome === 1 ? predicted : 1 - predicted;\n\treturn -Math.log(Math.max(epsilon, p));\n}\n\n/**\n * Beta posterior mean for an independent binary task outcome under a fixed\n * policy in a homogeneous condition bucket. The prior (alpha, beta) must be\n * declared by the host; this is not a learned-calibration claim.\n */\nexport function betaPosteriorMean(alpha: number, beta: number, successes: number, failures: number): number {\n\tfinite(alpha, \"alpha\", 1e9);\n\tfinite(beta, \"beta\", 1e9);\n\tensure(alpha > 0 && beta > 0, \"beta prior parameters must be positive\");\n\tfinite(successes, \"successes\", 1e12);\n\tfinite(failures, \"failures\", 1e12);\n\treturn (alpha + successes) / (alpha + beta + successes + failures);\n}\n\n/**\n * CUSUM-style drift accumulator over per-observation losses in one condition\n * bucket. Returns the new accumulator value; the caller compares it against\n * a host-declared threshold h_g. Not a guaranteed false-alarm rate.\n */\nexport function driftStatistic(previous: number, loss: number, referenceMean: number, slack: number): number {\n\tfinite(previous, \"previous\");\n\tfinite(loss, \"loss\");\n\tfinite(referenceMean, \"referenceMean\");\n\tfinite(slack, \"slack\");\n\treturn Math.max(0, previous + loss - referenceMean - slack);\n}\n"]}

package/dist/metacognition/decision.js

@@ -0,0 +1,111 @@
+/**
+ * Finite decision-model arithmetic for metacognitive control.
+ *
+ * TypeScript port of docs/OMK_meta_algorithm_checks_2026-09-19.zip
+ * (check_examples.py) — the numerical checks referenced by
+ * OMK_metacognitive_control_algorithms_2026-09-19.md §5.3, §6.2.
+ *
+ * These are illustrative finite-model computations, NOT measured OMK risk
+ * estimates. Callers must supply real, defensible probabilities; this module
+ * only guarantees the arithmetic is correct and rejects malformed inputs.
+ */
+import { ensure, finite, probability, probabilityVector } from "./validation.js";
+/**
+ * Minimum expected loss over a finite set of terminal decisions.
+ * losses[d][h] is the loss of decision d when hypothesis h is true.
+ */
+export function bayesRisk(prior, losses) {
+    probabilityVector(prior, "prior");
+    ensure(losses.length > 0, "at least one terminal decision is required");
+    let best = Number.POSITIVE_INFINITY;
+    for (const row of losses) {
+        ensure(row.length === prior.length, "loss row must match hypotheses");
+        let risk = 0;
+        for (let h = 0; h < prior.length; h++) {
+            finite(row[h], "loss");
+            risk += prior[h] * row[h];
+        }
+        if (risk < best)
+            best = risk;
+    }
+    return best;
+}
+/**
+ * One-step value of information: Bayes risk before minus expected Bayes risk
+ * after observing the experiment outcome, minus the experiment cost.
+ * likelihoodByHypothesis[h][o] = P(outcome o | hypothesis h).
+ * Zero-probability outcomes are skipped; the caller must treat an actually
+ * observed impossible outcome as a model mismatch, never renormalize it away.
+ */
+export function experimentValue(prior, losses, likelihoodByHypothesis, cost) {
+    probabilityVector(prior, "prior");
+    finite(cost, "cost");
+    const rows = likelihoodByHypothesis.map((row) => {
+        probabilityVector(row, "likelihood");
+        return row;
+    });
+    ensure(rows.length === prior.length, "likelihood matrix must match hypotheses");
+    ensure(new Set(rows.map((r) => r.length)).size === 1, "likelihood matrix shape mismatch");
+    const outcomeCount = rows[0].length;
+    const before = bayesRisk(prior, losses);
+    const branches = [];
+    let expectedAfter = 0;
+    for (let outcome = 0; outcome < outcomeCount; outcome++) {
+        const masses = prior.map((p, h) => p * rows[h][outcome]);
+        const marginal = masses.reduce((a, b) => a + b, 0);
+        if (marginal === 0)
+            continue;
+        const posterior = masses.map((m) => m / marginal);
+        const after = bayesRisk(posterior, losses);
+        expectedAfter += marginal * after;
+        branches.push({ outcome, probability: marginal, posterior, risk: after });
+    }
+    return {
+        before,
+        expectedAfter,
+        grossValue: before - expectedAfter,
+        cost,
+        netValue: before - expectedAfter - cost,
+        branches,
+    };
+}
+/** Brier score for one binary event. */
+export function brier(predicted, outcome) {
+    probability(predicted, "predicted");
+    const p = outcome === 1 ? predicted : 1 - predicted;
+    return (1 - p) ** 2;
+}
+/** Negative log-likelihood surprise for one binary event (epsilon-clamped). */
+export function surprise(predicted, outcome, epsilon = 1e-12) {
+    probability(predicted, "predicted");
+    finite(epsilon, "epsilon", 1);
+    ensure(epsilon > 0, "epsilon must be positive");
+    const p = outcome === 1 ? predicted : 1 - predicted;
+    return -Math.log(Math.max(epsilon, p));
+}
+/**
+ * Beta posterior mean for an independent binary task outcome under a fixed
+ * policy in a homogeneous condition bucket. The prior (alpha, beta) must be
+ * declared by the host; this is not a learned-calibration claim.
+ */
+export function betaPosteriorMean(alpha, beta, successes, failures) {
+    finite(alpha, "alpha", 1e9);
+    finite(beta, "beta", 1e9);
+    ensure(alpha > 0 && beta > 0, "beta prior parameters must be positive");
+    finite(successes, "successes", 1e12);
+    finite(failures, "failures", 1e12);
+    return (alpha + successes) / (alpha + beta + successes + failures);
+}
+/**
+ * CUSUM-style drift accumulator over per-observation losses in one condition
+ * bucket. Returns the new accumulator value; the caller compares it against
+ * a host-declared threshold h_g. Not a guaranteed false-alarm rate.
+ */
+export function driftStatistic(previous, loss, referenceMean, slack) {
+    finite(previous, "previous");
+    finite(loss, "loss");
+    finite(referenceMean, "referenceMean");
+    finite(slack, "slack");
+    return Math.max(0, previous + loss - referenceMean - slack);
+}
+//# sourceMappingURL=decision.js.map

package/dist/metacognition/decision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.js","sourceRoot":"","sources":["../../src/metacognition/decision.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Finite decision-model arithmetic for metacognitive control.\n *\n * TypeScript port of docs/OMK_meta_algorithm_checks_2026-09-19.zip\n * (check_examples.py) — the numerical checks referenced by\n * OMK_metacognitive_control_algorithms_2026-09-19.md §5.3, §6.2.\n *\n * These are illustrative finite-model computations, NOT measured OMK risk\n * estimates. Callers must supply real, defensible probabilities; this module\n * only guarantees the arithmetic is correct and rejects malformed inputs.\n */\nimport { ensure, finite, probability, probabilityVector } from \"./validation.ts\";\n\n/**\n * Minimum expected loss over a finite set of terminal decisions.\n * losses[d][h] is the loss of decision d when hypothesis h is true.\n */\nexport function bayesRisk(prior: readonly number[], losses: readonly (readonly number[])[]): number {\n\tprobabilityVector(prior, \"prior\");\n\tensure(losses.length > 0, \"at least one terminal decision is required\");\n\tlet best = Number.POSITIVE_INFINITY;\n\tfor (const row of losses) {\n\t\tensure(row.length === prior.length, \"loss row must match hypotheses\");\n\t\tlet risk = 0;\n\t\tfor (let h = 0; h < prior.length; h++) {\n\t\t\tfinite(row[h]!, \"loss\");\n\t\t\trisk += prior[h]! * row[h]!;\n\t\t}\n\t\tif (risk < best) best = risk;\n\t}\n\treturn best;\n}\n\nexport interface ExperimentBranch {\n\treadonly outcome: number;\n\treadonly probability: number;\n\treadonly posterior: readonly number[];\n\treadonly risk: number;\n}\nexport interface ExperimentValue {\n\treadonly before: number;\n\treadonly expectedAfter: number;\n\treadonly grossValue: number;\n\treadonly cost: number;\n\treadonly netValue: number;\n\treadonly branches: readonly ExperimentBranch[];\n}\n\n/**\n * One-step value of information: Bayes risk before minus expected Bayes risk\n * after observing the experiment outcome, minus the experiment cost.\n * likelihoodByHypothesis[h][o] = P(outcome o | hypothesis h).\n * Zero-probability outcomes are skipped; the caller must treat an actually\n * observed impossible outcome as a model mismatch, never renormalize it away.\n */\nexport function experimentValue(\n\tprior: readonly number[],\n\tlosses: readonly (readonly number[])[],\n\tlikelihoodByHypothesis: readonly (readonly number[])[],\n\tcost: number,\n): ExperimentValue {\n\tprobabilityVector(prior, \"prior\");\n\tfinite(cost, \"cost\");\n\tconst rows = likelihoodByHypothesis.map((row) => {\n\t\tprobabilityVector(row, \"likelihood\");\n\t\treturn row;\n\t});\n\tensure(rows.length === prior.length, \"likelihood matrix must match hypotheses\");\n\tensure(new Set(rows.map((r) => r.length)).size === 1, \"likelihood matrix shape mismatch\");\n\tconst outcomeCount = rows[0]!.length;\n\tconst before = bayesRisk(prior, losses);\n\tconst branches: ExperimentBranch[] = [];\n\tlet expectedAfter = 0;\n\tfor (let outcome = 0; outcome < outcomeCount; outcome++) {\n\t\tconst masses = prior.map((p, h) => p * rows[h]![outcome]!);\n\t\tconst marginal = masses.reduce((a, b) => a + b, 0);\n\t\tif (marginal === 0) continue;\n\t\tconst posterior = masses.map((m) => m / marginal);\n\t\tconst after = bayesRisk(posterior, losses);\n\t\texpectedAfter += marginal * after;\n\t\tbranches.push({ outcome, probability: marginal, posterior, risk: after });\n\t}\n\treturn {\n\t\tbefore,\n\t\texpectedAfter,\n\t\tgrossValue: before - expectedAfter,\n\t\tcost,\n\t\tnetValue: before - expectedAfter - cost,\n\t\tbranches,\n\t};\n}\n\n/** Brier score for one binary event. */\nexport function brier(predicted: number, outcome: 0 | 1): number {\n\tprobability(predicted, \"predicted\");\n\tconst p = outcome === 1 ? predicted : 1 - predicted;\n\treturn (1 - p) ** 2;\n}\n\n/** Negative log-likelihood surprise for one binary event (epsilon-clamped). */\nexport function surprise(predicted: number, outcome: 0 | 1, epsilon = 1e-12): number {\n\tprobability(predicted, \"predicted\");\n\tfinite(epsilon, \"epsilon\", 1);\n\tensure(epsilon > 0, \"epsilon must be positive\");\n\tconst p = outcome === 1 ? predicted : 1 - predicted;\n\treturn -Math.log(Math.max(epsilon, p));\n}\n\n/**\n * Beta posterior mean for an independent binary task outcome under a fixed\n * policy in a homogeneous condition bucket. The prior (alpha, beta) must be\n * declared by the host; this is not a learned-calibration claim.\n */\nexport function betaPosteriorMean(alpha: number, beta: number, successes: number, failures: number): number {\n\tfinite(alpha, \"alpha\", 1e9);\n\tfinite(beta, \"beta\", 1e9);\n\tensure(alpha > 0 && beta > 0, \"beta prior parameters must be positive\");\n\tfinite(successes, \"successes\", 1e12);\n\tfinite(failures, \"failures\", 1e12);\n\treturn (alpha + successes) / (alpha + beta + successes + failures);\n}\n\n/**\n * CUSUM-style drift accumulator over per-observation losses in one condition\n * bucket. Returns the new accumulator value; the caller compares it against\n * a host-declared threshold h_g. Not a guaranteed false-alarm rate.\n */\nexport function driftStatistic(previous: number, loss: number, referenceMean: number, slack: number): number {\n\tfinite(previous, \"previous\");\n\tfinite(loss, \"loss\");\n\tfinite(referenceMean, \"referenceMean\");\n\tfinite(slack, \"slack\");\n\treturn Math.max(0, previous + loss - referenceMean - slack);\n}\n"]}

package/dist/metacognition/evaluation.d.ts

@@ -0,0 +1,73 @@
+/** One logged decision for DR evaluation. Single checkpoint, not a trajectory. */
+export interface LoggedDecision {
+    readonly contextHash: string;
+    readonly action: string;
+    readonly reward: number;
+    /** Logged selection probability under the recording policy. Required, never imputed. */
+    readonly propensity: number;
+}
+export interface DRInput {
+    readonly decisions: readonly LoggedDecision[];
+    /** π(a|x): the evaluated policy's action for each logged context. */
+    readonly evaluatedActions: readonly string[];
+    /** r̂(x,a): reward model per context-action pair. */
+    readonly rewardModel: readonly (readonly number[])[];
+}
+export interface DREstimate {
+    readonly value: number;
+    readonly n: number;
+    readonly clipped: number;
+    /** Contexts where the evaluated action had zero logged support — excluded, never imputed. */
+    readonly unsupported: number;
+}
+/**
+ * Single-decision Doubly Robust estimate:
+ * V̂_DR(π) = 1/n Σ [ Σ_a π(a|x_i)r̂(x_i,a) + (π(a_i|x_i)/μ(a_i|x_i))(r_i - r̂(x_i,a_i)) ].
+ * Deterministic logging policies that never tried an action cannot evaluate
+ * that action post-hoc — those rows are excluded and counted.
+ */
+export declare function doublyRobustEstimate(input: DRInput, maxWeight?: number): DREstimate;
+/** §11.3 experience memory — failure mechanism and discrimination, not essays. */
+export interface ExperienceRecord {
+    readonly recordId: string;
+    readonly conditions: {
+        readonly modelRevision: string;
+        readonly toolchain: string;
+        readonly environmentHash: string;
+        readonly taskBand: string;
+    };
+    readonly failureMechanism: string;
+    readonly firstWrongExpectation: string;
+    readonly discriminatingObservation: string;
+    readonly appliedFixOrStrategy: string;
+    readonly checksBefore: readonly string[];
+    readonly checksAfter: readonly string[];
+    readonly knownCounterexamples: readonly string[];
+    readonly applicabilityConditions: readonly string[];
+    readonly evidenceRefs: readonly string[];
+    readonly policyVersion: string;
+    readonly skillHashes: readonly string[];
+}
+export declare function validateExperienceRecord(r: ExperienceRecord): void;
+/** §15.3 completion metrics. Zero denominators are `undefined`, never 0 or 1. */
+export interface OutcomeCounts {
+    readonly declaredComplete: number;
+    readonly independentFailAmongDeclared: number;
+    readonly allTasks: number;
+    readonly succeeded: number;
+    readonly abstained: number;
+    readonly totalCost: number;
+}
+export declare function completionMetrics(c: OutcomeCounts): {
+    readonly falseCompletionDeclared?: number;
+    readonly falseCompletionAll?: number;
+    readonly successRate?: number;
+    readonly abstainRate?: number;
+    readonly meanCost?: number;
+};
+/** §15.3 hidden-obligation detection with false alarms, for held-out requirements. */
+export declare function hiddenObligationMetrics(detected: number, totalHidden: number, falseAlarms: number): {
+    readonly detectionRate?: number;
+    readonly falseAlarms: number;
+};
+//# sourceMappingURL=evaluation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evaluation.d.ts","sourceRoot":"","sources":["../../src/metacognition/evaluation.ts"],"names":[],"mappings":"AAWA,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AACD,MAAM,WAAW,OAAO;IACvB,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IAC9C,sEAAqE;IACrE,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,sDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;CACrD;AACD,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+FAA6F;IAC7F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,SAAK,GAAG,UAAU,CAkC/E;AAED,qFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE;QACpB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IAC3C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,QAAQ,CAAC,uBAAuB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpD,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AACD,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAiBlE;AAED,kFAAiF;AACjF,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,4BAA4B,EAAE,MAAM,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AACD,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,aAAa,GAAG;IACpD,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B,CAmBA;AAED,uFAAsF;AACtF,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GACjB;IACF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B,CASA","sourcesContent":["/**\n * §11 causal strategy evaluation + §15 outcome metrics.\n *\n * Doubly Robust estimation is a second-stage offline tool over logged\n * single-checkpoint decisions: it needs real logged propensities, action\n * support, and rewards — never probabilities invented after the fact.\n * Completion metrics report false-completion alongside success/abstain rates,\n * because a policy that never completes can trivially zero false completions.\n */\nimport { ensure, finite, integer, probability, text } from \"./validation.ts\";\n\n/** One logged decision for DR evaluation. Single checkpoint, not a trajectory. */\nexport interface LoggedDecision {\n\treadonly contextHash: string;\n\treadonly action: string;\n\treadonly reward: number;\n\t/** Logged selection probability under the recording policy. Required, never imputed. */\n\treadonly propensity: number;\n}\nexport interface DRInput {\n\treadonly decisions: readonly LoggedDecision[];\n\t/** π(a|x): the evaluated policy's action for each logged context. */\n\treadonly evaluatedActions: readonly string[];\n\t/** r̂(x,a): reward model per context-action pair. */\n\treadonly rewardModel: readonly (readonly number[])[];\n}\nexport interface DREstimate {\n\treadonly value: number;\n\treadonly n: number;\n\treadonly clipped: number;\n\t/** Contexts where the evaluated action had zero logged support — excluded, never imputed. */\n\treadonly unsupported: number;\n}\n\n/**\n * Single-decision Doubly Robust estimate:\n * V̂_DR(π) = 1/n Σ [ Σ_a π(a|x_i)r̂(x_i,a) + (π(a_i|x_i)/μ(a_i|x_i))(r_i - r̂(x_i,a_i)) ].\n * Deterministic logging policies that never tried an action cannot evaluate\n * that action post-hoc — those rows are excluded and counted.\n */\nexport function doublyRobustEstimate(input: DRInput, maxWeight = 50): DREstimate {\n\tconst { decisions, evaluatedActions, rewardModel } = input;\n\tinteger(decisions.length, \"decisions\", 1_000_000);\n\tensure(decisions.length > 0, \"no logged decisions\");\n\tensure(evaluatedActions.length === decisions.length, \"evaluated action count mismatch\");\n\tensure(rewardModel.length === decisions.length, \"reward model row mismatch\");\n\tfinite(maxWeight, \"maxWeight\", 1e9);\n\tlet sum = 0,\n\t\tclipped = 0,\n\t\tunsupported = 0,\n\t\tusable = 0;\n\tfor (let i = 0; i < decisions.length; i++) {\n\t\tconst d = decisions[i]!;\n\t\ttext(d.contextHash, \"contextHash\", 256);\n\t\ttext(d.action, \"action\", 128);\n\t\tfinite(d.reward, \"reward\");\n\t\tprobability(d.propensity, \"propensity\");\n\t\ttext(evaluatedActions[i]!, \"evaluated action\", 128);\n\t\tconst rewards = rewardModel[i]!;\n\t\tensure(rewards.length > 0, \"reward model row empty\");\n\t\tfor (const r of rewards) finite(r, \"reward model value\");\n\t\t// Contexts may carry several logged actions; μ is per recorded decision.\n\t\tconst modelMean = rewards.reduce((a, b) => a + b, 0) / rewards.length;\n\t\tif (d.propensity === 0 && d.action === evaluatedActions[i]) {\n\t\t\tunsupported++;\n\t\t\tcontinue;\n\t\t}\n\t\tusable++;\n\t\tconst weight = d.action === evaluatedActions[i] ? Math.min(maxWeight, 1 / d.propensity) : 0;\n\t\tif (weight === maxWeight) clipped++;\n\t\tsum += modelMean + weight * (d.reward - modelMean);\n\t}\n\tensure(usable > 0, \"no decisions with logged support for the evaluated policy\");\n\treturn { value: sum / usable, n: usable, clipped, unsupported };\n}\n\n/** §11.3 experience memory — failure mechanism and discrimination, not essays. */\nexport interface ExperienceRecord {\n\treadonly recordId: string;\n\treadonly conditions: {\n\t\treadonly modelRevision: string;\n\t\treadonly toolchain: string;\n\t\treadonly environmentHash: string;\n\t\treadonly taskBand: string;\n\t};\n\treadonly failureMechanism: string;\n\treadonly firstWrongExpectation: string;\n\treadonly discriminatingObservation: string;\n\treadonly appliedFixOrStrategy: string;\n\treadonly checksBefore: readonly string[];\n\treadonly checksAfter: readonly string[];\n\treadonly knownCounterexamples: readonly string[];\n\treadonly applicabilityConditions: readonly string[];\n\treadonly evidenceRefs: readonly string[];\n\treadonly policyVersion: string;\n\treadonly skillHashes: readonly string[];\n}\nexport function validateExperienceRecord(r: ExperienceRecord): void {\n\ttext(r.recordId, \"recordId\", 128);\n\ttext(r.failureMechanism, \"failureMechanism\", 2048);\n\ttext(r.firstWrongExpectation, \"firstWrongExpectation\", 2048);\n\ttext(r.discriminatingObservation, \"discriminatingObservation\", 2048);\n\ttext(r.appliedFixOrStrategy, \"appliedFixOrStrategy\", 2048);\n\ttext(r.policyVersion, \"policyVersion\", 64);\n\tfor (const list of [\n\t\tr.checksBefore,\n\t\tr.checksAfter,\n\t\tr.knownCounterexamples,\n\t\tr.applicabilityConditions,\n\t\tr.evidenceRefs,\n\t\tr.skillHashes,\n\t]) {\n\t\tensure(Array.isArray(list) && list.length <= 128, \"experience record list bound\");\n\t}\n}\n\n/** §15.3 completion metrics. Zero denominators are `undefined`, never 0 or 1. */\nexport interface OutcomeCounts {\n\treadonly declaredComplete: number;\n\treadonly independentFailAmongDeclared: number;\n\treadonly allTasks: number;\n\treadonly succeeded: number;\n\treadonly abstained: number;\n\treadonly totalCost: number;\n}\nexport function completionMetrics(c: OutcomeCounts): {\n\treadonly falseCompletionDeclared?: number;\n\treadonly falseCompletionAll?: number;\n\treadonly successRate?: number;\n\treadonly abstainRate?: number;\n\treadonly meanCost?: number;\n} {\n\tinteger(c.declaredComplete, \"declaredComplete\");\n\tinteger(c.independentFailAmongDeclared, \"independentFail\");\n\tinteger(c.allTasks, \"allTasks\");\n\tinteger(c.succeeded, \"succeeded\");\n\tinteger(c.abstained, \"abstained\");\n\tfinite(c.totalCost, \"totalCost\");\n\tensure(c.independentFailAmongDeclared <= c.declaredComplete, \"fail count exceeds declared\");\n\tensure(\n\t\tc.declaredComplete <= c.allTasks && c.succeeded <= c.allTasks && c.abstained <= c.allTasks,\n\t\t\"counts exceed task total\",\n\t);\n\treturn {\n\t\tfalseCompletionDeclared: c.declaredComplete > 0 ? c.independentFailAmongDeclared / c.declaredComplete : undefined,\n\t\tfalseCompletionAll: c.allTasks > 0 ? c.independentFailAmongDeclared / c.allTasks : undefined,\n\t\tsuccessRate: c.allTasks > 0 ? c.succeeded / c.allTasks : undefined,\n\t\tabstainRate: c.allTasks > 0 ? c.abstained / c.allTasks : undefined,\n\t\tmeanCost: c.allTasks > 0 ? c.totalCost / c.allTasks : undefined,\n\t};\n}\n\n/** §15.3 hidden-obligation detection with false alarms, for held-out requirements. */\nexport function hiddenObligationMetrics(\n\tdetected: number,\n\ttotalHidden: number,\n\tfalseAlarms: number,\n): {\n\treadonly detectionRate?: number;\n\treadonly falseAlarms: number;\n} {\n\tinteger(detected, \"detected\");\n\tinteger(totalHidden, \"totalHidden\");\n\tinteger(falseAlarms, \"falseAlarms\");\n\tensure(detected <= totalHidden, \"detected exceeds hidden total\");\n\treturn {\n\t\tdetectionRate: totalHidden > 0 ? detected / totalHidden : undefined,\n\t\tfalseAlarms,\n\t};\n}\n"]}