open-multi-agent-kit 1.0.0 → 1.2.0

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"]}

package/dist/metacognition/retrieval.js

@@ -0,0 +1,170 @@
+/**
+ * Bounded local BM25 retrieval and the acquisition pool that owns every
+ * started promise until actual settlement.
+ *
+ * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip
+ * (src/retrieval.ts). Search hits are `candidate-only`, never auto-promoted
+ * to observations.
+ */
+import { ensure, integer, lexical, text, unique } from "./validation.js";
+/** Retrieval tokens, not a semantic-knowledge detector. Short language names survive. */
+export function retrievalTokens(value) {
+    return (value
+        .normalize("NFKC")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .match(/[\p{L}\p{N}]+(?:\+\+|#)?/gu) ?? []);
+}
+/** BM25 with positive IDF; bounded local corpus, no I/O or model call. */
+export function searchCorpus(query, corpus, limit = 8) {
+    text(query, "query", 4096);
+    integer(limit, "limit", 64);
+    ensure(corpus.length <= 5000, "corpus too large");
+    unique(corpus.map((d) => d.id), "document ids", 5000);
+    let totalChars = 0;
+    const documents = corpus.map((d) => {
+        text(d.uri, "uri");
+        ensure(typeof d.body === "string" && d.body.length <= 100_000, "document too large");
+        totalChars += d.body.length;
+        ensure(totalChars <= 10_000_000, "corpus byte/character policy exceeded");
+        const tokens = retrievalTokens(d.body);
+        const frequencies = new Map();
+        for (const token of tokens)
+            frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+        return { d, length: tokens.length, frequencies };
+    });
+    const terms = [...new Set(retrievalTokens(query))];
+    if (!terms.length || !documents.length || limit === 0)
+        return [];
+    const avgLength = Math.max(1, documents.reduce((s, d) => s + d.length, 0) / documents.length);
+    const idf = new Map(terms.map((term) => {
+        const frequency = documents.filter((d) => d.frequencies.has(term)).length;
+        return [term, Math.log(1 + (documents.length - frequency + 0.5) / (frequency + 0.5))];
+    }));
+    return documents
+        .map(({ d, length, frequencies }) => {
+        let score = 0;
+        for (const term of terms) {
+            const tf = frequencies.get(term) ?? 0;
+            score += (idf.get(term) * tf * 2.2) / (tf + 1.2 * (0.25 + (0.75 * length) / avgLength));
+        }
+        return { ...d, score, trust: "candidate-only" };
+    })
+        .filter((d) => d.score > 0)
+        .sort((a, b) => b.score - a.score || lexical(a.id, b.id))
+        .slice(0, limit);
+}
+/**
+ * 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 class AcquisitionPool {
+    now;
+    deadline;
+    maxRequests;
+    maxInFlight;
+    perRequestMs;
+    nextId = 0;
+    epoch = 0;
+    requests = 0;
+    active = new Map();
+    constructor(options) {
+        integer(options.maxRequests, "maxRequests", 100_000);
+        integer(options.maxInFlight, "maxInFlight", 64);
+        integer(options.durationMs, "durationMs", 86_400_000);
+        integer(options.perRequestMs, "perRequestMs", 86_400_000);
+        this.now = options.monotonicNow ?? (() => performance.now());
+        const start = this.now();
+        ensure(Number.isFinite(start) && start >= 0, "invalid monotonic clock");
+        this.deadline = start + options.durationMs;
+        this.maxRequests = options.maxRequests;
+        this.maxInFlight = options.maxInFlight;
+        this.perRequestMs = options.perRequestMs;
+    }
+    snapshot() {
+        return {
+            requests: this.requests,
+            active: this.active.size,
+            quarantined: [...this.active.values()].filter((e) => e.quarantined).length,
+            remainingMs: Math.max(0, Math.floor(this.deadline - this.now())),
+            epoch: this.epoch,
+        };
+    }
+    /** Invalidation requests cancellation but never resets outstanding ownership or budget. */
+    invalidate() {
+        this.epoch++;
+        for (const entry of this.active.values()) {
+            entry.quarantined = true;
+            entry.controller.abort();
+        }
+    }
+    async run(operation, parent) {
+        if (parent?.aborted)
+            return { status: "aborted" };
+        const remaining = this.deadline - this.now();
+        if (this.requests >= this.maxRequests || remaining <= 0 || this.perRequestMs === 0) {
+            return { status: "budget-exhausted" };
+        }
+        if (this.active.size >= this.maxInFlight)
+            return { status: "busy" };
+        const id = ++this.nextId, epoch = this.epoch, controller = new AbortController();
+        const entry = { controller, quarantined: false };
+        this.active.set(id, entry);
+        this.requests++;
+        const expires = this.now() + Math.min(remaining, this.perRequestMs);
+        let resolveStop;
+        const stopped = new Promise((resolve) => {
+            resolveStop = resolve;
+        });
+        const stop = (status) => {
+            if (this.active.has(id))
+                entry.quarantined = true;
+            resolveStop({ status });
+            controller.abort();
+        };
+        const onParent = () => stop("aborted");
+        const onInternal = () => {
+            if (epoch !== this.epoch)
+                resolveStop({ status: "stale" });
+        };
+        parent?.addEventListener("abort", onParent, { once: true });
+        controller.signal.addEventListener("abort", onInternal, { once: true });
+        const timer = setTimeout(() => stop("timeout"), Math.max(1, Math.ceil(expires - this.now())));
+        // Both fulfillment and rejection are owned. Late results are never promoted.
+        const task = Promise.resolve()
+            .then(() => {
+            if (controller.signal.aborted || parent?.aborted)
+                throw new Error("cancelled-before-dispatch");
+            return operation(controller.signal);
+        })
+            .then((value) => {
+            if (epoch !== this.epoch)
+                return { status: "stale" };
+            if (parent?.aborted)
+                return { status: "aborted" };
+            if (controller.signal.aborted || this.now() >= expires)
+                return { status: "timeout" };
+            return { status: "ok", value };
+        }, () => ({
+            status: epoch !== this.epoch
+                ? "stale"
+                : parent?.aborted
+                    ? "aborted"
+                    : controller.signal.aborted
+                        ? "timeout"
+                        : "error",
+        }))
+            .finally(() => {
+            this.active.delete(id);
+        });
+        try {
+            return await Promise.race([task, stopped]);
+        }
+        finally {
+            clearTimeout(timer);
+            parent?.removeEventListener("abort", onParent);
+            controller.signal.removeEventListener("abort", onInternal);
+        }
+    }
+}
+//# sourceMappingURL=retrieval.js.map

package/dist/metacognition/retrieval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval.js","sourceRoot":"","sources":["../../src/metacognition/retrieval.ts"],"names":[],"mappings":"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","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"]}

package/dist/metacognition/risk.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Finite-sample risk bounds for automation gating (Jev audit algorithm A4).
+ *
+ * A point estimate must never widen automation scope. Two failures in a
+ * hundred is not "a 2% error rate" — its one-sided 95% Clopper–Pearson upper
+ * bound is about 6.2%, and that bound is what a gate reads.
+ *
+ * Scope: this bounds the failure probability of samples drawn under the stated
+ * conditions. It is not a safety guarantee for the next action, and it assumes
+ * a fixed policy, a consistent failure event, and adequately independent
+ * samples. Three hundred repeated clicks inside one task are not three hundred
+ * independent trials; cluster by task or environment instance before using it.
+ */
+/** Regularized incomplete beta I_x(a,b). */
+export declare function regularizedIncompleteBeta(a: number, b: number, x: number): number;
+/**
+ * One-sided Clopper–Pearson upper bound on the failure probability.
+ *
+ * `U(k,n) = Beta⁻¹(1−α; k+1, n−k)` for `0 ≤ k < n`, and `1` when every trial
+ * failed. Zero trials is not zero risk: it is absent evidence, so it throws.
+ */
+export declare function clopperPearsonUpperBound(failures: number, trials: number, alpha: number): number;
+/** Closed form of {@link clopperPearsonUpperBound} when no trial failed. */
+export declare function zeroFailureUpperBound(trials: number, alpha: number): number;
+/**
+ * Smallest failure-free sample size whose upper bound meets `targetEpsilon`.
+ *
+ * `n ≥ ⌈log α / log(1−ε)⌉`, then nudged against the bound itself so a
+ * floating-point boundary cannot return a sample size that misses the target.
+ */
+export declare function minimumZeroFailureSamples(targetEpsilon: number, alpha: number): number;
+/**
+ * Bonferroni split for `thresholds × groups` comparisons on one validation set.
+ *
+ * Searching many thresholds and reporting the best keeps none of a single
+ * interval's nominal guarantee; this is the conservative correction, and it
+ * raises the required sample size on purpose.
+ */
+export declare function bonferroniAlpha(alpha: number, thresholds: number, groups: number): number;
+/**
+ * Union bound over per-step failure risks.
+ *
+ * Holds without any independence assumption, which is the point: step risks in
+ * one task are usually correlated, so multiplying them would understate the
+ * whole-task risk.
+ */
+export declare function unionBoundRisk(stepRisks: readonly number[]): number;
+//# sourceMappingURL=risk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"risk.d.ts","sourceRoot":"","sources":["../../src/metacognition/risk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAyDH,4CAA4C;AAC5C,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAOjF;AAqBD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAShG;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI3E;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAUtF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKzF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAWnE","sourcesContent":["/**\n * Finite-sample risk bounds for automation gating (Jev audit algorithm A4).\n *\n * A point estimate must never widen automation scope. Two failures in a\n * hundred is not \"a 2% error rate\" — its one-sided 95% Clopper–Pearson upper\n * bound is about 6.2%, and that bound is what a gate reads.\n *\n * Scope: this bounds the failure probability of samples drawn under the stated\n * conditions. It is not a safety guarantee for the next action, and it assumes\n * a fixed policy, a consistent failure event, and adequately independent\n * samples. Three hundred repeated clicks inside one task are not three hundred\n * independent trials; cluster by task or environment instance before using it.\n */\n\nimport { ensure } from \"./validation.ts\";\n\nconst LANCZOS_G = 7;\nconst LANCZOS_COEFFICIENTS = [\n\t0.999_999_999_999_809_93, 676.520_368_121_885_1, -1259.139_216_722_402_8, 771.323_428_777_653_13,\n\t-176.615_029_162_140_59, 12.507_343_278_686_905, -0.138_571_095_265_720_12, 9.984_369_578_019_571_6e-6,\n\t1.505_632_735_149_311_6e-7,\n] as const;\n\nfunction logGamma(x: number): number {\n\tif (x < 0.5) return Math.log(Math.PI / Math.sin(Math.PI * x)) - logGamma(1 - x);\n\tconst z = x - 1;\n\tlet a = LANCZOS_COEFFICIENTS[0];\n\tconst t = z + LANCZOS_G + 0.5;\n\tfor (const [index, coefficient] of LANCZOS_COEFFICIENTS.entries()) {\n\t\tif (index > 0) a += coefficient / (z + index);\n\t}\n\treturn 0.5 * Math.log(2 * Math.PI) + (z + 0.5) * Math.log(t) - t + Math.log(a);\n}\n\n/** Continued-fraction expansion for the incomplete beta (Lentz's method). */\nfunction betaContinuedFraction(a: number, b: number, x: number): number {\n\tconst maxIterations = 300;\n\tconst epsilon = 3e-16;\n\tconst tiny = 1e-300;\n\tconst qab = a + b;\n\tconst qap = a + 1;\n\tconst qam = a - 1;\n\tlet c = 1;\n\tlet d = 1 - (qab * x) / qap;\n\tif (Math.abs(d) < tiny) d = tiny;\n\td = 1 / d;\n\tlet h = d;\n\tfor (let m = 1; m <= maxIterations; m += 1) {\n\t\tconst m2 = 2 * m;\n\t\tlet aa = (m * (b - m) * x) / ((qam + m2) * (a + m2));\n\t\td = 1 + aa * d;\n\t\tif (Math.abs(d) < tiny) d = tiny;\n\t\tc = 1 + aa / c;\n\t\tif (Math.abs(c) < tiny) c = tiny;\n\t\td = 1 / d;\n\t\th *= d * c;\n\t\taa = (-(a + m) * (qab + m) * x) / ((a + m2) * (qap + m2));\n\t\td = 1 + aa * d;\n\t\tif (Math.abs(d) < tiny) d = tiny;\n\t\tc = 1 + aa / c;\n\t\tif (Math.abs(c) < tiny) c = tiny;\n\t\td = 1 / d;\n\t\tconst delta = d * c;\n\t\th *= delta;\n\t\tif (Math.abs(delta - 1) < epsilon) break;\n\t}\n\treturn h;\n}\n\n/** Regularized incomplete beta I_x(a,b). */\nexport function regularizedIncompleteBeta(a: number, b: number, x: number): number {\n\tif (x <= 0) return 0;\n\tif (x >= 1) return 1;\n\tconst front = Math.exp(logGamma(a + b) - logGamma(a) - logGamma(b) + a * Math.log(x) + b * Math.log1p(-x));\n\treturn x < (a + 1) / (a + b + 2)\n\t\t? (front * betaContinuedFraction(a, b, x)) / a\n\t\t: 1 - (front * betaContinuedFraction(b, a, 1 - x)) / b;\n}\n\n/** Inverse of {@link regularizedIncompleteBeta} by bisection; I_x is monotone in x. */\nfunction betaQuantile(p: number, a: number, b: number): number {\n\tlet low = 0;\n\tlet high = 1;\n\tfor (let i = 0; i < 200 && high - low > 1e-15; i += 1) {\n\t\tconst mid = (low + high) / 2;\n\t\tif (regularizedIncompleteBeta(a, b, mid) < p) low = mid;\n\t\telse high = mid;\n\t}\n\treturn (low + high) / 2;\n}\n\nfunction assertAlpha(alpha: number): void {\n\tensure(\n\t\ttypeof alpha === \"number\" && Number.isFinite(alpha) && alpha > 0 && alpha < 1,\n\t\t\"alpha must be a probability strictly between 0 and 1\",\n\t);\n}\n\n/**\n * One-sided Clopper–Pearson upper bound on the failure probability.\n *\n * `U(k,n) = Beta⁻¹(1−α; k+1, n−k)` for `0 ≤ k < n`, and `1` when every trial\n * failed. Zero trials is not zero risk: it is absent evidence, so it throws.\n */\nexport function clopperPearsonUpperBound(failures: number, trials: number, alpha: number): number {\n\tensure(Number.isSafeInteger(trials) && trials > 0, \"insufficient evidence: trials must be a positive integer\");\n\tensure(\n\t\tNumber.isSafeInteger(failures) && failures >= 0 && failures <= trials,\n\t\t\"failures must be an integer in [0, trials]\",\n\t);\n\tassertAlpha(alpha);\n\tif (failures === trials) return 1;\n\treturn betaQuantile(1 - alpha, failures + 1, trials - failures);\n}\n\n/** Closed form of {@link clopperPearsonUpperBound} when no trial failed. */\nexport function zeroFailureUpperBound(trials: number, alpha: number): number {\n\tensure(Number.isSafeInteger(trials) && trials > 0, \"insufficient evidence: trials must be a positive integer\");\n\tassertAlpha(alpha);\n\treturn -Math.expm1(Math.log(alpha) / trials);\n}\n\n/**\n * Smallest failure-free sample size whose upper bound meets `targetEpsilon`.\n *\n * `n ≥ ⌈log α / log(1−ε)⌉`, then nudged against the bound itself so a\n * floating-point boundary cannot return a sample size that misses the target.\n */\nexport function minimumZeroFailureSamples(targetEpsilon: number, alpha: number): number {\n\tensure(\n\t\ttypeof targetEpsilon === \"number\" && Number.isFinite(targetEpsilon) && targetEpsilon > 0 && targetEpsilon < 1,\n\t\t\"targetEpsilon must be strictly between 0 and 1\",\n\t);\n\tassertAlpha(alpha);\n\tlet n = Math.max(1, Math.ceil(Math.log(alpha) / Math.log1p(-targetEpsilon)));\n\twhile (zeroFailureUpperBound(n, alpha) > targetEpsilon) n += 1;\n\twhile (n > 1 && zeroFailureUpperBound(n - 1, alpha) <= targetEpsilon) n -= 1;\n\treturn n;\n}\n\n/**\n * Bonferroni split for `thresholds × groups` comparisons on one validation set.\n *\n * Searching many thresholds and reporting the best keeps none of a single\n * interval's nominal guarantee; this is the conservative correction, and it\n * raises the required sample size on purpose.\n */\nexport function bonferroniAlpha(alpha: number, thresholds: number, groups: number): number {\n\tassertAlpha(alpha);\n\tensure(Number.isSafeInteger(thresholds) && thresholds > 0, \"thresholds must be a positive integer\");\n\tensure(Number.isSafeInteger(groups) && groups > 0, \"groups must be a positive integer\");\n\treturn alpha / (thresholds * groups);\n}\n\n/**\n * Union bound over per-step failure risks.\n *\n * Holds without any independence assumption, which is the point: step risks in\n * one task are usually correlated, so multiplying them would understate the\n * whole-task risk.\n */\nexport function unionBoundRisk(stepRisks: readonly number[]): number {\n\tensure(Array.isArray(stepRisks) && stepRisks.length > 0, \"stepRisks must be a non-empty array\");\n\tlet total = 0;\n\tfor (const risk of stepRisks) {\n\t\tensure(\n\t\t\ttypeof risk === \"number\" && Number.isFinite(risk) && risk >= 0 && risk <= 1,\n\t\t\t\"each step risk must be a probability in [0, 1]\",\n\t\t);\n\t\ttotal += risk;\n\t}\n\treturn Math.min(1, total);\n}\n"]}