open-multi-agent-kit 1.0.0 → 1.2.0

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":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,MAAM,SAAS,GAAG,CAAC,CAAC;AACpB,MAAM,oBAAoB,GAAG;IAC5B,wBAAwB,EAAE,qBAAqB,EAAE,CAAC,sBAAsB,EAAE,sBAAsB;IAChG,CAAC,sBAAsB,EAAE,sBAAsB,EAAE,CAAC,wBAAwB,EAAE,0BAA0B;IACtG,0BAA0B;CACjB,CAAC;AAEX,SAAS,QAAQ,CAAC,CAAS,EAAU;IACpC,IAAI,CAAC,GAAG,GAAG;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAChF,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,IAAI,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,GAAG,GAAG,CAAC;IAC9B,KAAK,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,oBAAoB,CAAC,OAAO,EAAE,EAAE,CAAC;QACnE,IAAI,KAAK,GAAG,CAAC;YAAE,CAAC,IAAI,WAAW,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAAA,CAC/E;AAED,6EAA6E;AAC7E,SAAS,qBAAqB,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS,EAAU;IACvE,MAAM,aAAa,GAAG,GAAG,CAAC;IAC1B,MAAM,OAAO,GAAG,KAAK,CAAC;IACtB,MAAM,IAAI,GAAG,MAAM,CAAC;IACpB,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClB,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClB,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;IAC5B,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI;QAAE,CAAC,GAAG,IAAI,CAAC;IACjC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACV,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,aAAa,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QACjB,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrD,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACf,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,CAAC,GAAG,IAAI,CAAC;QACjC,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACf,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,CAAC,GAAG,IAAI,CAAC;QACjC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACV,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACX,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;QAC1D,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACf,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,CAAC,GAAG,IAAI,CAAC;QACjC,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACf,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,CAAC,GAAG,IAAI,CAAC;QACjC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACV,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC,IAAI,KAAK,CAAC;QACX,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,OAAO;YAAE,MAAM;IAC1C,CAAC;IACD,OAAO,CAAC,CAAC;AAAA,CACT;AAED,4CAA4C;AAC5C,MAAM,UAAU,yBAAyB,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS,EAAU;IAClF,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACrB,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACrB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3G,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC,CAAC,CAAC,KAAK,GAAG,qBAAqB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAC9C,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,qBAAqB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAAA,CACxD;AAED,uFAAuF;AACvF,SAAS,YAAY,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS,EAAU;IAC9D,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,IAAI,IAAI,GAAG,GAAG,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACvD,MAAM,GAAG,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,yBAAyB,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;YAAE,GAAG,GAAG,GAAG,CAAC;;YACnD,IAAI,GAAG,GAAG,CAAC;IACjB,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;AAAA,CACxB;AAED,SAAS,WAAW,CAAC,KAAa,EAAQ;IACzC,MAAM,CACL,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,EAC7E,sDAAsD,CACtD,CAAC;AAAA,CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAgB,EAAE,MAAc,EAAE,KAAa,EAAU;IACjG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,0DAA0D,CAAC,CAAC;IAC/G,MAAM,CACL,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,IAAI,QAAQ,IAAI,MAAM,EACrE,4CAA4C,CAC5C,CAAC;IACF,WAAW,CAAC,KAAK,CAAC,CAAC;IACnB,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,CAAC,CAAC;IAClC,OAAO,YAAY,CAAC,CAAC,GAAG,KAAK,EAAE,QAAQ,GAAG,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;AAAA,CAChE;AAED,4EAA4E;AAC5E,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,KAAa,EAAU;IAC5E,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,0DAA0D,CAAC,CAAC;IAC/G,WAAW,CAAC,KAAK,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,CAAC;AAAA,CAC7C;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,aAAqB,EAAE,KAAa,EAAU;IACvF,MAAM,CACL,OAAO,aAAa,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC,IAAI,aAAa,GAAG,CAAC,EAC7G,gDAAgD,CAChD,CAAC;IACF,WAAW,CAAC,KAAK,CAAC,CAAC;IACnB,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAC7E,OAAO,qBAAqB,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,aAAa;QAAE,CAAC,IAAI,CAAC,CAAC;IAC/D,OAAO,CAAC,GAAG,CAAC,IAAI,qBAAqB,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,IAAI,aAAa;QAAE,CAAC,IAAI,CAAC,CAAC;IAC7E,OAAO,CAAC,CAAC;AAAA,CACT;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,UAAkB,EAAE,MAAc,EAAU;IAC1F,WAAW,CAAC,KAAK,CAAC,CAAC;IACnB,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,uCAAuC,CAAC,CAAC;IACpG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,mCAAmC,CAAC,CAAC;IACxF,OAAO,KAAK,GAAG,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC;AAAA,CACrC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,SAA4B,EAAU;IACpE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,qCAAqC,CAAC,CAAC;IAChG,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC9B,MAAM,CACL,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAC3E,gDAAgD,CAChD,CAAC;QACF,KAAK,IAAI,IAAI,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAAA,CAC1B","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"]}

package/dist/metacognition/route-economics.js

@@ -0,0 +1,110 @@
+/**
+ * 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.
+ */
+import { ensure } from "./validation.js";
+function assertUnits(units) {
+    ensure(Number.isFinite(units.costUnit) && units.costUnit > 0, "costUnit must be positive");
+    ensure(Number.isFinite(units.latencyUnit) && units.latencyUnit > 0, "latencyUnit must be positive");
+    ensure(Number.isFinite(units.costWeight) && units.costWeight >= 0, "costWeight must be nonnegative");
+    ensure(Number.isFinite(units.latencyWeight) && units.latencyWeight >= 0, "latencyWeight must be nonnegative");
+}
+/** Dimensionless utility; cost and latency are normalized before weighting. */
+export function routeUtility(route, units) {
+    ensure(Number.isFinite(route.completionProbability) &&
+        route.completionProbability >= 0 &&
+        route.completionProbability <= 1, "completionProbability must be in [0,1]");
+    ensure(Number.isFinite(route.costUsd) && route.costUsd >= 0, "costUsd must be nonnegative");
+    ensure(Number.isFinite(route.latencyMs) && route.latencyMs >= 0, "latencyMs must be nonnegative");
+    assertUnits(units);
+    return (route.completionProbability -
+        units.costWeight * (route.costUsd / units.costUnit) -
+        units.latencyWeight * (route.latencyMs / units.latencyUnit));
+}
+/**
+ * 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 function selectRoute(routes, units) {
+    ensure(Array.isArray(routes) && routes.length > 0, "routes must be a non-empty array");
+    let best;
+    let bestUtility = Number.NEGATIVE_INFINITY;
+    for (const route of routes) {
+        if (!route.approved)
+            continue;
+        const utility = routeUtility(route, units);
+        const better = utility > bestUtility || (utility === bestUtility && best !== undefined && route.id < best.id);
+        if (best === undefined || better) {
+            best = route;
+            bestUtility = utility;
+        }
+    }
+    return best ?? null;
+}
+/** Whole-step duration. Model response time is one term among eight. */
+export function stepDuration(phases) {
+    let total = 0;
+    for (const [label, value] of Object.entries(phases)) {
+        ensure(Number.isFinite(value) && value >= 0, `${label} must be a nonnegative finite number`);
+        total += value;
+    }
+    return total;
+}
+/**
+ * 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 function overallSpeedup(improvableFraction, speedup) {
+    ensure(Number.isFinite(improvableFraction) && improvableFraction >= 0 && improvableFraction <= 1, "improvableFraction must be in [0,1]");
+    ensure(typeof speedup === "number" && !Number.isNaN(speedup) && speedup >= 1, "speedup must be at least 1");
+    const remaining = 1 - improvableFraction;
+    const improved = speedup === Number.POSITIVE_INFINITY ? 0 : improvableFraction / speedup;
+    return 1 / (remaining + improved);
+}
+/**
+ * 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 function fallbackExpectedCost(costs) {
+    ensure(Number.isFinite(costs.selectorCost) && costs.selectorCost >= 0, "selectorCost must be nonnegative");
+    ensure(Number.isFinite(costs.verificationCost) && costs.verificationCost >= 0, "verificationCost must be nonnegative");
+    ensure(Number.isFinite(costs.fallbackCost) && costs.fallbackCost >= 0, "fallbackCost must be nonnegative");
+    ensure(Number.isFinite(costs.fallbackProbability) && costs.fallbackProbability >= 0 && costs.fallbackProbability <= 1, "fallbackProbability must be in [0,1]");
+    return costs.selectorCost + costs.verificationCost + costs.fallbackProbability * costs.fallbackCost;
+}
+/**
+ * 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 function reselectionAllowed(input) {
+    ensure(Number.isSafeInteger(input.attemptsForFingerprint) && input.attemptsForFingerprint >= 0, "attemptsForFingerprint must be a nonnegative integer");
+    ensure(Number.isSafeInteger(input.maxAttempts) && input.maxAttempts > 0, "maxAttempts must be a positive integer");
+    if (input.causeChanged)
+        return { allowed: true };
+    if (input.attemptsForFingerprint < input.maxAttempts)
+        return { allowed: true };
+    return { allowed: false, reason: "attempt-budget-exhausted" };
+}
+//# sourceMappingURL=route-economics.js.map

package/dist/metacognition/route-economics.js.map

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

package/dist/metacognition/runtime-bridge.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Runtime bridge — §13 "기존 완료 판정 호출부": projects host-owned OMK
+ * runtime artifacts (protocol ClaimGraph claims, ObservationNodes, waiver
+ * records, workspace/session facts) onto the metacognition kernel's input
+ * types. It only translates; it never relaxes trust floors, never admits a
+ * model's JSON as runner truth, and never fabricates completion.
+ */
+import type { ClaimNode, ObservationNode } from "omk-protocol";
+import type { CheckObservation, Claim, DecisionObservation, ReferenceObservation, SourceIdentity, Stage } from "./knowledge.ts";
+import type { MetaState } from "./state.ts";
+/** ClaimNode → kernel Claim. Severity maps to impact; leaves keep their check demands. */
+export declare function toKernelClaim(node: ClaimNode, stage: Stage, binding: string): Claim;
+/** ObservationNode → kernel observation. Trust floor rank maps to source admissibility. */
+export declare function toKernelObservation(node: ObservationNode, binding: string, nowMs: number, claimById?: ReadonlyMap<string, Claim>): CheckObservation | ReferenceObservation | DecisionObservation;
+export interface RuntimeBridgeOutput {
+    readonly state: MetaState;
+    readonly claims: readonly Claim[];
+    readonly observations: readonly (CheckObservation | ReferenceObservation | DecisionObservation)[];
+}
+export interface RuntimeBridgeInput {
+    readonly taskId: string;
+    readonly stageId: string;
+    readonly goalScope: string;
+    readonly targetArtifact: string;
+    readonly candidateHash: string;
+    readonly environmentHash: string;
+    readonly claims: readonly ClaimNode[];
+    readonly observations: readonly ObservationNode[];
+    readonly trustedRunnerIds: readonly string[];
+    readonly decisionActorIds: readonly string[];
+    readonly authorizedActions: readonly string[];
+    readonly budget: {
+        remainingMs: number;
+        remainingRequests: number;
+        remainingTokens: number;
+        remainingConcurrent: number;
+    };
+    readonly policyVersion: string;
+    readonly modelRevision: string;
+    readonly interruptionReason?: string | null;
+    readonly stage: Stage;
+    readonly nowMs: number;
+    readonly progressHistory?: readonly {
+        key: string;
+        newEvidence: boolean;
+        resolvedObligations: number;
+        newValidChecks: number;
+    }[];
+}
+/** Build kernel inputs plus a MetaState for one safe checkpoint. Host-owned inputs only. */
+export declare function toMetaState(input: RuntimeBridgeInput): RuntimeBridgeOutput;
+/** Sources admitted for reference evidence: only repository/official qualify. */
+export declare function sourceIdentities(overrides?: readonly SourceIdentity[]): readonly SourceIdentity[];
+//# sourceMappingURL=runtime-bridge.d.ts.map

package/dist/metacognition/runtime-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-bridge.d.ts","sourceRoot":"","sources":["../../src/metacognition/runtime-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,KAAK,EACX,gBAAgB,EAChB,KAAK,EACL,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,KAAK,EACL,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAS5C,4FAA0F;AAC1F,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAsBnF;AAED,6FAA2F;AAC3F,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,GACpC,gBAAgB,GAAG,oBAAoB,GAAG,mBAAmB,CAiC/D;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,gBAAgB,GAAG,oBAAoB,GAAG,mBAAmB,CAAC,EAAE,CAAC;CAClG;AACD,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,SAAS,eAAe,EAAE,CAAC;IAClD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;QACxB,mBAAmB,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS;QACnC,GAAG,EAAE,MAAM,CAAC;QACZ,WAAW,EAAE,OAAO,CAAC;QACrB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,cAAc,EAAE,MAAM,CAAC;KACvB,EAAE,CAAC;CACJ;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,CAwD1E;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,SAAS,GAAE,SAAS,cAAc,EAAO,GAAG,SAAS,cAAc,EAAE,CAWrG","sourcesContent":["/**\n * Runtime bridge — §13 \"기존 완료 판정 호출부\": projects host-owned OMK\n * runtime artifacts (protocol ClaimGraph claims, ObservationNodes, waiver\n * records, workspace/session facts) onto the metacognition kernel's input\n * types. It only translates; it never relaxes trust floors, never admits a\n * model's JSON as runner truth, and never fabricates completion.\n */\nimport type { ClaimNode, ObservationNode } from \"omk-protocol\";\nimport { createCalibrationStore } from \"./calibration.ts\";\nimport type {\n\tCheckObservation,\n\tClaim,\n\tDecisionObservation,\n\tReferenceObservation,\n\tSourceIdentity,\n\tStage,\n} from \"./knowledge.ts\";\nimport type { MetaState } from \"./state.ts\";\nimport { ensure, integer, lexical, member, text } from \"./validation.ts\";\n\nconst ISO_MS = (iso: string): number => {\n\tconst ms = Date.parse(iso);\n\tensure(Number.isFinite(ms), `invalid ISO timestamp: ${iso}`);\n\treturn ms;\n};\n\n/** ClaimNode → kernel Claim. Severity maps to impact; leaves keep their check demands. */\nexport function toKernelClaim(node: ClaimNode, stage: Stage, binding: string): Claim {\n\ttext(node.claimId, \"claimId\", 256);\n\ttext(node.statement, \"statement\", 2048);\n\tmember(stage, [\"before-change\", \"after-change\"], \"stage\");\n\tlet impact = 100;\n\tif (node.kind === \"safety\") impact = 1_000;\n\telse if (node.severity === \"required\") impact = 500;\n\treturn {\n\t\tid: node.claimId,\n\t\tbinding,\n\t\tphase: node.kind === \"requirement\" || node.kind === \"safety\" ? \"precondition\" : \"postcondition\",\n\t\tstatement: node.statement,\n\t\trequired: node.severity === \"required\",\n\t\timpact,\n\t\tneedsReference: false,\n\t\trequiresVersion: false,\n\t\tversion: null,\n\t\tminSourceFamilies: node.requiredWitnesses ?? 1,\n\t\trequiredCheckIds: node.invalidationKeys,\n\t\tneedsUserDecision: node.trustFloor === \"model_narrative\",\n\t\tpublicQuery: null,\n\t};\n}\n\n/** ObservationNode → kernel observation. Trust floor rank maps to source admissibility. */\nexport function toKernelObservation(\n\tnode: ObservationNode,\n\tbinding: string,\n\tnowMs: number,\n\tclaimById?: ReadonlyMap<string, Claim>,\n): CheckObservation | ReferenceObservation | DecisionObservation {\n\ttext(node.observationId, \"observationId\", 256);\n\ttext(binding, \"binding\", 512);\n\tinteger(nowMs, \"nowMs\");\n\tconst observedAtMs = nowMs;\n\tconst expiresAtMs = node.validUntil !== undefined ? ISO_MS(node.validUntil) : nowMs + 1;\n\tconst claimId = node.claimIds[0] ?? \"\";\n\tconst base = { id: node.observationId, claimId, binding, observedAtMs, expiresAtMs };\n\tif (node.receiptId !== undefined) {\n\t\t// checkId is the claim's required check predicate (its invalidation key),\n\t\t// not the receipt id — receipts are evidence artifacts, checkIds are obligations.\n\t\tconst checkId = claimById?.get(claimId)?.requiredCheckIds[0] ?? node.receiptId;\n\t\treturn {\n\t\t\t...base,\n\t\t\tkind: \"check\",\n\t\t\trunnerId: node.source,\n\t\t\tcheckId,\n\t\t\tsequence: 0,\n\t\t\tverdict: node.polarity === \"supports\" ? \"pass\" : \"fail\",\n\t\t};\n\t}\n\tif (node.source === \"model_narrative\") {\n\t\treturn { ...base, kind: \"decision\", actorId: \"model\", accepted: node.polarity === \"supports\" };\n\t}\n\treturn {\n\t\t...base,\n\t\tkind: \"reference\",\n\t\tsourceId: node.source,\n\t\tversion: null,\n\t\tstance: node.polarity === \"supports\" ? \"support\" : \"refute\",\n\t\tdocumentDigest: node.environmentDigest,\n\t\tlocator: node.sourceRoot,\n\t};\n}\n\nexport interface RuntimeBridgeOutput {\n\treadonly state: MetaState;\n\treadonly claims: readonly Claim[];\n\treadonly observations: readonly (CheckObservation | ReferenceObservation | DecisionObservation)[];\n}\nexport interface RuntimeBridgeInput {\n\treadonly taskId: string;\n\treadonly stageId: string;\n\treadonly goalScope: string;\n\treadonly targetArtifact: string;\n\treadonly candidateHash: string;\n\treadonly environmentHash: string;\n\treadonly claims: readonly ClaimNode[];\n\treadonly observations: readonly ObservationNode[];\n\treadonly trustedRunnerIds: readonly string[];\n\treadonly decisionActorIds: readonly string[];\n\treadonly authorizedActions: readonly string[];\n\treadonly budget: {\n\t\tremainingMs: number;\n\t\tremainingRequests: number;\n\t\tremainingTokens: number;\n\t\tremainingConcurrent: number;\n\t};\n\treadonly policyVersion: string;\n\treadonly modelRevision: string;\n\treadonly interruptionReason?: string | null;\n\treadonly stage: Stage;\n\treadonly nowMs: number;\n\treadonly progressHistory?: readonly {\n\t\tkey: string;\n\t\tnewEvidence: boolean;\n\t\tresolvedObligations: number;\n\t\tnewValidChecks: number;\n\t}[];\n}\n\n/** Build kernel inputs plus a MetaState for one safe checkpoint. Host-owned inputs only. */\nexport function toMetaState(input: RuntimeBridgeInput): RuntimeBridgeOutput {\n\ttext(input.taskId, \"taskId\", 128);\n\ttext(input.stageId, \"stageId\", 128);\n\ttext(input.goalScope, \"goalScope\", 256);\n\ttext(input.targetArtifact, \"targetArtifact\", 512);\n\ttext(input.candidateHash, \"candidateHash\", 128);\n\ttext(input.environmentHash, \"environmentHash\", 128);\n\ttext(input.policyVersion, \"policyVersion\", 64);\n\ttext(input.modelRevision, \"modelRevision\", 128);\n\tinteger(input.nowMs, \"nowMs\");\n\tensure(input.claims.length <= 128 && input.observations.length <= 4096, \"runtime bridge input too large\");\n\t// Only leaf claims map to kernel claims — compound satisfaction is the\n\t// protocol layer's job, not a kernel evidence predicate.\n\tconst binding = `${input.candidateHash}@${input.environmentHash}`;\n\tconst leafClaims = input.claims.filter((c) => c.satisfaction.inputs.length === 0);\n\tconst claimById = new Map(leafClaims.map((c) => [c.claimId, toKernelClaim(c, input.stage, binding)]));\n\tconst kernelClaims = [...claimById.values()].sort((a, b) => lexical(a.id, b.id));\n\tconst kernelObservations = input.observations.map((o) => toKernelObservation(o, binding, input.nowMs, claimById));\n\tconst state: MetaState = {\n\t\tgoal: {\n\t\t\ttaskId: input.taskId,\n\t\t\tstageId: input.stageId,\n\t\t\ttargetArtifact: input.targetArtifact,\n\t\t\tgoalScope: input.goalScope,\n\t\t},\n\t\tfacts: {\n\t\t\tcandidateHash: input.candidateHash,\n\t\t\tenvironmentHash: input.environmentHash,\n\t\t\tchangeScope: [input.targetArtifact],\n\t\t\tanalyzerCoverage: \"unknown\",\n\t\t},\n\t\tobligations: [],\n\t\tevidence: { report: null, adoptedSourceIds: [] },\n\t\tpredictions: [],\n\t\thypotheses: { open: [], discriminatorCandidates: [], modelMismatch: false },\n\t\tcalibration: createCalibrationStore({\n\t\t\tminSamples: 5,\n\t\t\tpriorAlpha: 1,\n\t\t\tpriorBeta: 1,\n\t\t\treferenceMean: 0.3,\n\t\t\tslack: 0.15,\n\t\t\tthreshold: 3,\n\t\t}),\n\t\tverifier: { evaluations: [], runnerHealth: \"unverified\" },\n\t\tbudget: input.budget,\n\t\tpolicy: {\n\t\t\tpolicyVersion: input.policyVersion,\n\t\t\tauthorizedActions: input.authorizedActions,\n\t\t\trequiredApprovals: [],\n\t\t\tinterruptionReason: input.interruptionReason ?? null,\n\t\t},\n\t\thostSequence: 0,\n\t\tprogressHistory: input.progressHistory ?? [],\n\t\tcheckpointCount: 0,\n\t};\n\treturn { state, claims: kernelClaims, observations: kernelObservations };\n}\n\n/** Sources admitted for reference evidence: only repository/official qualify. */\nexport function sourceIdentities(overrides: readonly SourceIdentity[] = []): readonly SourceIdentity[] {\n\treturn [\n\t\t{ id: \"deterministic_validator\", family: \"host\", kind: \"repository\" },\n\t\t{ id: \"workspace_witness\", family: \"host\", kind: \"repository\" },\n\t\t{ id: \"trusted_attestation\", family: \"attestation\", kind: \"official\" },\n\t\t{ id: \"effect_reconciliation\", family: \"host\", kind: \"repository\" },\n\t\t{ id: \"independent_review\", family: \"review\", kind: \"official\" },\n\t\t{ id: \"self_review\", family: \"model\", kind: \"model\" },\n\t\t{ id: \"model_narrative\", family: \"model\", kind: \"model\" },\n\t\t...overrides,\n\t];\n}\n"]}