open-multi-agent-kit 0.99.0 → 1.2.0

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

package/dist/metacognition/risk.js

@@ -0,0 +1,165 @@
+/**
+ * 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.
+ */
+import { ensure } from "./validation.js";
+const LANCZOS_G = 7;
+const LANCZOS_COEFFICIENTS = [
+    0.999_999_999_999_809_93, 676.520_368_121_885_1, -1259.139_216_722_402_8, 771.323_428_777_653_13,
+    -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,
+    1.505_632_735_149_311_6e-7,
+];
+function logGamma(x) {
+    if (x < 0.5)
+        return Math.log(Math.PI / Math.sin(Math.PI * x)) - logGamma(1 - x);
+    const z = x - 1;
+    let a = LANCZOS_COEFFICIENTS[0];
+    const t = z + LANCZOS_G + 0.5;
+    for (const [index, coefficient] of LANCZOS_COEFFICIENTS.entries()) {
+        if (index > 0)
+            a += coefficient / (z + index);
+    }
+    return 0.5 * Math.log(2 * Math.PI) + (z + 0.5) * Math.log(t) - t + Math.log(a);
+}
+/** Continued-fraction expansion for the incomplete beta (Lentz's method). */
+function betaContinuedFraction(a, b, x) {
+    const maxIterations = 300;
+    const epsilon = 3e-16;
+    const tiny = 1e-300;
+    const qab = a + b;
+    const qap = a + 1;
+    const qam = a - 1;
+    let c = 1;
+    let d = 1 - (qab * x) / qap;
+    if (Math.abs(d) < tiny)
+        d = tiny;
+    d = 1 / d;
+    let h = d;
+    for (let m = 1; m <= maxIterations; m += 1) {
+        const m2 = 2 * m;
+        let aa = (m * (b - m) * x) / ((qam + m2) * (a + m2));
+        d = 1 + aa * d;
+        if (Math.abs(d) < tiny)
+            d = tiny;
+        c = 1 + aa / c;
+        if (Math.abs(c) < tiny)
+            c = tiny;
+        d = 1 / d;
+        h *= d * c;
+        aa = (-(a + m) * (qab + m) * x) / ((a + m2) * (qap + m2));
+        d = 1 + aa * d;
+        if (Math.abs(d) < tiny)
+            d = tiny;
+        c = 1 + aa / c;
+        if (Math.abs(c) < tiny)
+            c = tiny;
+        d = 1 / d;
+        const delta = d * c;
+        h *= delta;
+        if (Math.abs(delta - 1) < epsilon)
+            break;
+    }
+    return h;
+}
+/** Regularized incomplete beta I_x(a,b). */
+export function regularizedIncompleteBeta(a, b, x) {
+    if (x <= 0)
+        return 0;
+    if (x >= 1)
+        return 1;
+    const front = Math.exp(logGamma(a + b) - logGamma(a) - logGamma(b) + a * Math.log(x) + b * Math.log1p(-x));
+    return x < (a + 1) / (a + b + 2)
+        ? (front * betaContinuedFraction(a, b, x)) / a
+        : 1 - (front * betaContinuedFraction(b, a, 1 - x)) / b;
+}
+/** Inverse of {@link regularizedIncompleteBeta} by bisection; I_x is monotone in x. */
+function betaQuantile(p, a, b) {
+    let low = 0;
+    let high = 1;
+    for (let i = 0; i < 200 && high - low > 1e-15; i += 1) {
+        const mid = (low + high) / 2;
+        if (regularizedIncompleteBeta(a, b, mid) < p)
+            low = mid;
+        else
+            high = mid;
+    }
+    return (low + high) / 2;
+}
+function assertAlpha(alpha) {
+    ensure(typeof alpha === "number" && Number.isFinite(alpha) && alpha > 0 && alpha < 1, "alpha must be a probability strictly between 0 and 1");
+}
+/**
+ * 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 function clopperPearsonUpperBound(failures, trials, alpha) {
+    ensure(Number.isSafeInteger(trials) && trials > 0, "insufficient evidence: trials must be a positive integer");
+    ensure(Number.isSafeInteger(failures) && failures >= 0 && failures <= trials, "failures must be an integer in [0, trials]");
+    assertAlpha(alpha);
+    if (failures === trials)
+        return 1;
+    return betaQuantile(1 - alpha, failures + 1, trials - failures);
+}
+/** Closed form of {@link clopperPearsonUpperBound} when no trial failed. */
+export function zeroFailureUpperBound(trials, alpha) {
+    ensure(Number.isSafeInteger(trials) && trials > 0, "insufficient evidence: trials must be a positive integer");
+    assertAlpha(alpha);
+    return -Math.expm1(Math.log(alpha) / trials);
+}
+/**
+ * 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 function minimumZeroFailureSamples(targetEpsilon, alpha) {
+    ensure(typeof targetEpsilon === "number" && Number.isFinite(targetEpsilon) && targetEpsilon > 0 && targetEpsilon < 1, "targetEpsilon must be strictly between 0 and 1");
+    assertAlpha(alpha);
+    let n = Math.max(1, Math.ceil(Math.log(alpha) / Math.log1p(-targetEpsilon)));
+    while (zeroFailureUpperBound(n, alpha) > targetEpsilon)
+        n += 1;
+    while (n > 1 && zeroFailureUpperBound(n - 1, alpha) <= targetEpsilon)
+        n -= 1;
+    return n;
+}
+/**
+ * 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 function bonferroniAlpha(alpha, thresholds, groups) {
+    assertAlpha(alpha);
+    ensure(Number.isSafeInteger(thresholds) && thresholds > 0, "thresholds must be a positive integer");
+    ensure(Number.isSafeInteger(groups) && groups > 0, "groups must be a positive integer");
+    return alpha / (thresholds * groups);
+}
+/**
+ * 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 function unionBoundRisk(stepRisks) {
+    ensure(Array.isArray(stepRisks) && stepRisks.length > 0, "stepRisks must be a non-empty array");
+    let total = 0;
+    for (const risk of stepRisks) {
+        ensure(typeof risk === "number" && Number.isFinite(risk) && risk >= 0 && risk <= 1, "each step risk must be a probability in [0, 1]");
+        total += risk;
+    }
+    return Math.min(1, total);
+}
+//# sourceMappingURL=risk.js.map

package/dist/metacognition/risk.js.map

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

package/dist/metacognition/route-economics.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Cost- and latency-aware route selection (Jev audit algorithm A5).
+ *
+ * Adding a selector call only pays if it *replaces* work. Inserting one in
+ * front of an existing free-text step adds a semantic inference instead of
+ * removing one, so routes are compared on a single utility:
+ *
+ *   U_r = q_r − λ_C·(C_r/C_0) − λ_L·(L_r/L_0)
+ *
+ * Safety and permission are deliberately not terms in that utility. They are a
+ * hard filter, because a cheap unsafe route must never win on weights.
+ *
+ * Latency is measured over the whole step, not the model call: when operator
+ * approval dominates, a faster decision step barely moves the total. Amdahl's
+ * bound is included so that limit is explicit rather than assumed away.
+ */
+export interface RouteCandidate {
+    readonly id: string;
+    /** Probability this route completes the step correctly. */
+    readonly completionProbability: number;
+    readonly costUsd: number;
+    readonly latencyMs: number;
+    /** Policy and permission verdict. A false value is a veto, not a penalty. */
+    readonly approved: boolean;
+}
+export interface RouteUnits {
+    readonly costUnit: number;
+    readonly latencyUnit: number;
+    readonly costWeight: number;
+    readonly latencyWeight: number;
+}
+/** Dimensionless utility; cost and latency are normalized before weighting. */
+export declare function routeUtility(route: RouteCandidate, units: RouteUnits): number;
+/**
+ * Highest-utility approved route, or null when nothing is approved.
+ *
+ * Returning null rather than the best unapproved route keeps "we may not do
+ * this" distinct from "this is expensive".
+ */
+export declare function selectRoute(routes: readonly RouteCandidate[], units: RouteUnits): RouteCandidate | null;
+export interface StepPhases {
+    readonly queueMs: number;
+    readonly observeMs: number;
+    readonly packMs: number;
+    readonly decideMs: number;
+    readonly approvalMs: number;
+    readonly executeMs: number;
+    readonly verifyMs: number;
+    readonly recoveryMs: number;
+}
+/** Whole-step duration. Model response time is one term among eight. */
+export declare function stepDuration(phases: StepPhases): number;
+/**
+ * Amdahl bound: S = 1 / ((1−f) + f/s).
+ *
+ * `speedup` may be Infinity to ask what an instantaneous step would buy — the
+ * answer is still capped by the fraction it occupies, which is the point.
+ */
+export declare function overallSpeedup(improvableFraction: number, speedup: number): number;
+export interface FallbackCosts {
+    readonly selectorCost: number;
+    readonly verificationCost: number;
+    readonly fallbackProbability: number;
+    readonly fallbackCost: number;
+}
+/**
+ * E[C] = c_J + c_V + p_F·c_L.
+ *
+ * A cost decomposition, not an independence claim. Compare it against the
+ * incumbent path's cost under the same success and safety conditions; if it is
+ * larger, the cheap path is not cheap.
+ */
+export declare function fallbackExpectedCost(costs: FallbackCosts): number;
+export interface ReselectionInput {
+    /** Attempts already spent on this observation fingerprint. */
+    readonly attemptsForFingerprint: number;
+    readonly maxAttempts: number;
+    /** True when recovery changed the cause, not merely retried the same question. */
+    readonly causeChanged: boolean;
+}
+export type ReselectionDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: "attempt-budget-exhausted";
+};
+/**
+ * Damp selector/model ping-pong on one observation generation.
+ *
+ * Re-asking the same question about the same state only adds calls. A further
+ * attempt is admitted when the budget remains, or when recovery genuinely
+ * changed the cause. The budget is a configured value, not a claimed optimum.
+ */
+export declare function reselectionAllowed(input: ReselectionInput): ReselectionDecision;
+//# sourceMappingURL=route-economics.d.ts.map

package/dist/metacognition/route-economics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-economics.d.ts","sourceRoot":"","sources":["../../src/metacognition/route-economics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAC/B;AASD,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAe7E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,EAAE,KAAK,EAAE,UAAU,GAAG,cAAc,GAAG,IAAI,CAcvG;AAED,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAOvD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,kBAAkB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CASlF;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAYjE;AAED,MAAM,WAAW,gBAAgB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,MAAM,mBAAmB,GAC5B;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAA;CAAE,CAAC;AAE5E;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,GAAG,mBAAmB,CAS/E","sourcesContent":["/**\n * Cost- and latency-aware route selection (Jev audit algorithm A5).\n *\n * Adding a selector call only pays if it *replaces* work. Inserting one in\n * front of an existing free-text step adds a semantic inference instead of\n * removing one, so routes are compared on a single utility:\n *\n *   U_r = q_r − λ_C·(C_r/C_0) − λ_L·(L_r/L_0)\n *\n * Safety and permission are deliberately not terms in that utility. They are a\n * hard filter, because a cheap unsafe route must never win on weights.\n *\n * Latency is measured over the whole step, not the model call: when operator\n * approval dominates, a faster decision step barely moves the total. Amdahl's\n * bound is included so that limit is explicit rather than assumed away.\n */\n\nimport { ensure } from \"./validation.ts\";\n\nexport interface RouteCandidate {\n\treadonly id: string;\n\t/** Probability this route completes the step correctly. */\n\treadonly completionProbability: number;\n\treadonly costUsd: number;\n\treadonly latencyMs: number;\n\t/** Policy and permission verdict. A false value is a veto, not a penalty. */\n\treadonly approved: boolean;\n}\n\nexport interface RouteUnits {\n\treadonly costUnit: number;\n\treadonly latencyUnit: number;\n\treadonly costWeight: number;\n\treadonly latencyWeight: number;\n}\n\nfunction assertUnits(units: RouteUnits): void {\n\tensure(Number.isFinite(units.costUnit) && units.costUnit > 0, \"costUnit must be positive\");\n\tensure(Number.isFinite(units.latencyUnit) && units.latencyUnit > 0, \"latencyUnit must be positive\");\n\tensure(Number.isFinite(units.costWeight) && units.costWeight >= 0, \"costWeight must be nonnegative\");\n\tensure(Number.isFinite(units.latencyWeight) && units.latencyWeight >= 0, \"latencyWeight must be nonnegative\");\n}\n\n/** Dimensionless utility; cost and latency are normalized before weighting. */\nexport function routeUtility(route: RouteCandidate, units: RouteUnits): number {\n\tensure(\n\t\tNumber.isFinite(route.completionProbability) &&\n\t\t\troute.completionProbability >= 0 &&\n\t\t\troute.completionProbability <= 1,\n\t\t\"completionProbability must be in [0,1]\",\n\t);\n\tensure(Number.isFinite(route.costUsd) && route.costUsd >= 0, \"costUsd must be nonnegative\");\n\tensure(Number.isFinite(route.latencyMs) && route.latencyMs >= 0, \"latencyMs must be nonnegative\");\n\tassertUnits(units);\n\treturn (\n\t\troute.completionProbability -\n\t\tunits.costWeight * (route.costUsd / units.costUnit) -\n\t\tunits.latencyWeight * (route.latencyMs / units.latencyUnit)\n\t);\n}\n\n/**\n * Highest-utility approved route, or null when nothing is approved.\n *\n * Returning null rather than the best unapproved route keeps \"we may not do\n * this\" distinct from \"this is expensive\".\n */\nexport function selectRoute(routes: readonly RouteCandidate[], units: RouteUnits): RouteCandidate | null {\n\tensure(Array.isArray(routes) && routes.length > 0, \"routes must be a non-empty array\");\n\tlet best: RouteCandidate | undefined;\n\tlet bestUtility = Number.NEGATIVE_INFINITY;\n\tfor (const route of routes) {\n\t\tif (!route.approved) continue;\n\t\tconst utility = routeUtility(route, units);\n\t\tconst better = utility > bestUtility || (utility === bestUtility && best !== undefined && route.id < best.id);\n\t\tif (best === undefined || better) {\n\t\t\tbest = route;\n\t\t\tbestUtility = utility;\n\t\t}\n\t}\n\treturn best ?? null;\n}\n\nexport interface StepPhases {\n\treadonly queueMs: number;\n\treadonly observeMs: number;\n\treadonly packMs: number;\n\treadonly decideMs: number;\n\treadonly approvalMs: number;\n\treadonly executeMs: number;\n\treadonly verifyMs: number;\n\treadonly recoveryMs: number;\n}\n\n/** Whole-step duration. Model response time is one term among eight. */\nexport function stepDuration(phases: StepPhases): number {\n\tlet total = 0;\n\tfor (const [label, value] of Object.entries(phases)) {\n\t\tensure(Number.isFinite(value) && value >= 0, `${label} must be a nonnegative finite number`);\n\t\ttotal += value;\n\t}\n\treturn total;\n}\n\n/**\n * Amdahl bound: S = 1 / ((1−f) + f/s).\n *\n * `speedup` may be Infinity to ask what an instantaneous step would buy — the\n * answer is still capped by the fraction it occupies, which is the point.\n */\nexport function overallSpeedup(improvableFraction: number, speedup: number): number {\n\tensure(\n\t\tNumber.isFinite(improvableFraction) && improvableFraction >= 0 && improvableFraction <= 1,\n\t\t\"improvableFraction must be in [0,1]\",\n\t);\n\tensure(typeof speedup === \"number\" && !Number.isNaN(speedup) && speedup >= 1, \"speedup must be at least 1\");\n\tconst remaining = 1 - improvableFraction;\n\tconst improved = speedup === Number.POSITIVE_INFINITY ? 0 : improvableFraction / speedup;\n\treturn 1 / (remaining + improved);\n}\n\nexport interface FallbackCosts {\n\treadonly selectorCost: number;\n\treadonly verificationCost: number;\n\treadonly fallbackProbability: number;\n\treadonly fallbackCost: number;\n}\n\n/**\n * E[C] = c_J + c_V + p_F·c_L.\n *\n * A cost decomposition, not an independence claim. Compare it against the\n * incumbent path's cost under the same success and safety conditions; if it is\n * larger, the cheap path is not cheap.\n */\nexport function fallbackExpectedCost(costs: FallbackCosts): number {\n\tensure(Number.isFinite(costs.selectorCost) && costs.selectorCost >= 0, \"selectorCost must be nonnegative\");\n\tensure(\n\t\tNumber.isFinite(costs.verificationCost) && costs.verificationCost >= 0,\n\t\t\"verificationCost must be nonnegative\",\n\t);\n\tensure(Number.isFinite(costs.fallbackCost) && costs.fallbackCost >= 0, \"fallbackCost must be nonnegative\");\n\tensure(\n\t\tNumber.isFinite(costs.fallbackProbability) && costs.fallbackProbability >= 0 && costs.fallbackProbability <= 1,\n\t\t\"fallbackProbability must be in [0,1]\",\n\t);\n\treturn costs.selectorCost + costs.verificationCost + costs.fallbackProbability * costs.fallbackCost;\n}\n\nexport interface ReselectionInput {\n\t/** Attempts already spent on this observation fingerprint. */\n\treadonly attemptsForFingerprint: number;\n\treadonly maxAttempts: number;\n\t/** True when recovery changed the cause, not merely retried the same question. */\n\treadonly causeChanged: boolean;\n}\n\nexport type ReselectionDecision =\n\t| { readonly allowed: true }\n\t| { readonly allowed: false; readonly reason: \"attempt-budget-exhausted\" };\n\n/**\n * Damp selector/model ping-pong on one observation generation.\n *\n * Re-asking the same question about the same state only adds calls. A further\n * attempt is admitted when the budget remains, or when recovery genuinely\n * changed the cause. The budget is a configured value, not a claimed optimum.\n */\nexport function reselectionAllowed(input: ReselectionInput): ReselectionDecision {\n\tensure(\n\t\tNumber.isSafeInteger(input.attemptsForFingerprint) && input.attemptsForFingerprint >= 0,\n\t\t\"attemptsForFingerprint must be a nonnegative integer\",\n\t);\n\tensure(Number.isSafeInteger(input.maxAttempts) && input.maxAttempts > 0, \"maxAttempts must be a positive integer\");\n\tif (input.causeChanged) return { allowed: true };\n\tif (input.attemptsForFingerprint < input.maxAttempts) return { allowed: true };\n\treturn { allowed: false, reason: \"attempt-budget-exhausted\" };\n}\n"]}