open-multi-agent-kit 1.0.0 → 1.2.2

package/dist/metacognition/risk.js

@@ -0,0 +1,179 @@
+/**
+ * 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 = 1000;
+    const epsilon = 1e-14;
+    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 && Number.isFinite(h))
+            return h;
+    }
+    throw new RangeError("incomplete beta failed to converge");
+}
+/** Regularized incomplete beta I_x(a,b). */
+export function regularizedIncompleteBeta(a, b, x) {
+    ensure(Number.isFinite(a) && a > 0 && Number.isFinite(b) && b > 0 && Number.isFinite(a + b), "invalid beta shapes");
+    ensure(Number.isFinite(x) && x >= 0 && x <= 1, "beta x must be in [0,1]");
+    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));
+    const result = x < (a + 1) / (a + b + 2)
+        ? (front * betaContinuedFraction(a, b, x)) / a
+        : 1 - (front * betaContinuedFraction(b, a, 1 - x)) / b;
+    if (!Number.isFinite(result) || result < 0 || result > 1)
+        throw new RangeError("invalid incomplete beta result");
+    return result;
+}
+/** Invert the survival probability directly; never round 1-alpha to one. */
+function betaUpperQuantile(alpha, a, b) {
+    let low = 0;
+    let high = 1;
+    for (let i = 0; i < 200; i += 1) {
+        const mid = low + (high - low) / 2;
+        if (mid === low || mid === high)
+            break;
+        if (regularizedIncompleteBeta(b, a, 1 - mid) > alpha)
+            low = mid;
+        else
+            high = mid;
+    }
+    // Upper endpoint of the numerical bracket, not an interval-arithmetic proof.
+    return high;
+}
+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;
+    if (failures === 0)
+        return zeroFailureUpperBound(trials, alpha);
+    return betaUpperQuantile(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");
+    const comparisons = thresholds * groups;
+    ensure(Number.isSafeInteger(comparisons), "comparison count overflow");
+    const adjusted = alpha / comparisons;
+    ensure(adjusted > 0 && Number.isFinite(adjusted), "adjusted alpha underflow");
+    return adjusted;
+}
+/**
+ * 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 = 1000;\n\tconst epsilon = 1e-14;\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 && Number.isFinite(h)) return h;\n\t}\n\tthrow new RangeError(\"incomplete beta failed to converge\");\n}\n\n/** Regularized incomplete beta I_x(a,b). */\nexport function regularizedIncompleteBeta(a: number, b: number, x: number): number {\n\tensure(Number.isFinite(a) && a > 0 && Number.isFinite(b) && b > 0 && Number.isFinite(a + b), \"invalid beta shapes\");\n\tensure(Number.isFinite(x) && x >= 0 && x <= 1, \"beta x must be in [0,1]\");\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\tconst result =\n\t\tx < (a + 1) / (a + b + 2)\n\t\t\t? (front * betaContinuedFraction(a, b, x)) / a\n\t\t\t: 1 - (front * betaContinuedFraction(b, a, 1 - x)) / b;\n\tif (!Number.isFinite(result) || result < 0 || result > 1) throw new RangeError(\"invalid incomplete beta result\");\n\treturn result;\n}\n\n/** Invert the survival probability directly; never round 1-alpha to one. */\nfunction betaUpperQuantile(alpha: number, a: number, b: number): number {\n\tlet low = 0;\n\tlet high = 1;\n\tfor (let i = 0; i < 200; i += 1) {\n\t\tconst mid = low + (high - low) / 2;\n\t\tif (mid === low || mid === high) break;\n\t\tif (regularizedIncompleteBeta(b, a, 1 - mid) > alpha) low = mid;\n\t\telse high = mid;\n\t}\n\t// Upper endpoint of the numerical bracket, not an interval-arithmetic proof.\n\treturn high;\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\tif (failures === 0) return zeroFailureUpperBound(trials, alpha);\n\treturn betaUpperQuantile(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\tconst comparisons = thresholds * groups;\n\tensure(Number.isSafeInteger(comparisons), \"comparison count overflow\");\n\tconst adjusted = alpha / comparisons;\n\tensure(adjusted > 0 && Number.isFinite(adjusted), \"adjusted alpha underflow\");\n\treturn adjusted;\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,81 @@
+/**
+ * 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.
+ *
+ * WP05 (docs/06_METACOGNITION_BRIDGE.md): every translation is loss-aware.
+ * Each claim and observation maps to `mapped`, `partial`, or `rejected`.
+ * What the previous mapper silently did — collapse claimIds to the first,
+ * force sequence 0, substitute checkId with receiptId/invalidation keys,
+ * stamp observedAtMs with bridge time, fabricate expiry as now+1, rebind any
+ * evidence to the current candidate, coerce unknown polarity to a boolean —
+ * is now either preserved verbatim or declared in `loss`, never repeated.
+ *
+ * It only translates; it never relaxes trust floors, never admits a model's
+ * JSON as runner truth, and never fabricates completion.
+ */
+import { type ClaimNode, type ObservationSource } from "omk-protocol";
+import { type BridgeObservation, type ClaimMapResult, type ObservationMapResult, type RuntimeBridgeResult } from "./bridge-result.ts";
+import type { Claim, SourceIdentity, Stage } from "./knowledge.ts";
+/** ClaimNode → kernel Claim. Severity maps to impact; leaves keep their check demands. */
+export declare function mapClaim(node: ClaimNode, stage: Stage, binding: string): ClaimMapResult;
+/** Context every observation edge is translated against. */
+export interface ObservationMapContext {
+    /** `candidateHash@environmentHash` of the *current* candidate — never assigned to foreign evidence. */
+    readonly binding: string;
+    readonly nowMs: number;
+    readonly generation?: number;
+    /** Leaf claims already mapped, id → kernel claim. Unresolvable ids are declared loss. */
+    readonly claimById: ReadonlyMap<string, Claim>;
+    /** Per-claim trust floor; a missing floor defaults to `deterministic_validator`. */
+    readonly claimFloors: ReadonlyMap<string, ObservationSource>;
+    readonly sources: readonly SourceIdentity[];
+}
+/**
+ * ObservationNode → kernel observations.
+ *
+ * The result carries every emitted edge (one per resolvable claim — the
+ * explicit relation table docs/06 asks for) or the declared reason none
+ * could be emitted. No edge is ever emitted with fabricated provenance.
+ */
+export declare function mapObservation(node: BridgeObservation, ctx: ObservationMapContext): ObservationMapResult;
+export interface RuntimeBridgeInput {
+    readonly taskId: string;
+    readonly stageId: string;
+    readonly goalScope: string;
+    readonly targetArtifact: string;
+    readonly candidateHash: string;
+    readonly environmentHash: string;
+    /** Current ledger generation; compared with each observation's own when present. */
+    readonly generation?: number;
+    readonly claims: readonly ClaimNode[];
+    readonly observations: readonly BridgeObservation[];
+    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;
+    }[];
+    /** Extra admissible source identities beyond the built-in registry. */
+    readonly sources?: readonly SourceIdentity[];
+}
+/** Build kernel inputs plus a MetaState for one safe checkpoint. Host-owned inputs only. */
+export declare function toMetaState(input: RuntimeBridgeInput): RuntimeBridgeResult;
+/** 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;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,KAAK,SAAS,EAA0B,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC9F,OAAO,EAEN,KAAK,iBAAiB,EAEtB,KAAK,cAAc,EAGnB,KAAK,oBAAoB,EAEzB,KAAK,mBAAmB,EACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAoB,KAAK,EAAe,cAAc,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAalG,4FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAoCvF;AAED,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACrC,yGAAuG;IACvG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,2FAAyF;IACzF,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC/C,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC7D,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC5C;AAQD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAE,qBAAqB,GAAG,oBAAoB,CA2IxG;AAED,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,oFAAoF;IACpF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpD,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;IACJ,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AA2ED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,CA0I1E;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.\n *\n * WP05 (docs/06_METACOGNITION_BRIDGE.md): every translation is loss-aware.\n * Each claim and observation maps to `mapped`, `partial`, or `rejected`.\n * What the previous mapper silently did — collapse claimIds to the first,\n * force sequence 0, substitute checkId with receiptId/invalidation keys,\n * stamp observedAtMs with bridge time, fabricate expiry as now+1, rebind any\n * evidence to the current candidate, coerce unknown polarity to a boolean —\n * is now either preserved verbatim or declared in `loss`, never repeated.\n *\n * It only translates; it never relaxes trust floors, never admits a model's\n * JSON as runner truth, and never fabricates completion.\n */\nimport { type ClaimNode, OBSERVATION_TRUST_RANK, type ObservationSource } from \"omk-protocol\";\nimport {\n\ttype BridgeLoss,\n\ttype BridgeObservation,\n\ttype BridgePolarity,\n\ttype ClaimMapResult,\n\tlossOf,\n\tmergeBridgeLoss,\n\ttype ObservationMapResult,\n\ttype RuntimeBridgeOutput,\n\ttype RuntimeBridgeResult,\n} from \"./bridge-result.ts\";\nimport { createCalibrationStore } from \"./calibration.ts\";\nimport type { CheckObservation, Claim, Observation, SourceIdentity, Stage } from \"./knowledge.ts\";\nimport type { MetaState } from \"./state.ts\";\nimport { canonical, 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\nconst UNKNOWN_POLARITY: readonly BridgePolarity[] = [\"unknown\", \"neutral\", \"inconclusive\"];\nconst isUnknownPolarity = (p: BridgePolarity): boolean => UNKNOWN_POLARITY.includes(p);\n\n/** ClaimNode → kernel Claim. Severity maps to impact; leaves keep their check demands. */\nexport function mapClaim(node: ClaimNode, stage: Stage, binding: string): ClaimMapResult {\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\tconst needsUserDecision = node.trustFloor === \"model_narrative\";\n\t// A leaf needs at least one kernel evidence predicate. Checks come from\n\t// invalidationKeys; multi-witness demands and keyless leaves need\n\t// reference families; model-narrative floors need a decision.\n\tconst needsReference =\n\t\tnode.invalidationKeys.length === 0 && !needsUserDecision ? true : (node.requiredWitnesses ?? 1) > 1;\n\tconst claim: Claim = {\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,\n\t\trequiresVersion: false,\n\t\tversion: null,\n\t\tminSourceFamilies: Math.max(node.requiredWitnesses ?? 1, 1),\n\t\trequiredCheckIds: node.invalidationKeys,\n\t\tneedsUserDecision,\n\t\tpublicQuery: null,\n\t};\n\tif (node.scopeSensitive === true) {\n\t\treturn {\n\t\t\tstatus: \"partial\",\n\t\t\tclaim,\n\t\t\tloss: lossOf({ lostFields: [`claim:${node.claimId}.scopeSensitive`] }),\n\t\t};\n\t}\n\treturn { status: \"mapped\", claim };\n}\n\n/** Context every observation edge is translated against. */\nexport interface ObservationMapContext {\n\t/** `candidateHash@environmentHash` of the *current* candidate — never assigned to foreign evidence. */\n\treadonly binding: string;\n\treadonly nowMs: number;\n\treadonly generation?: number;\n\t/** Leaf claims already mapped, id → kernel claim. Unresolvable ids are declared loss. */\n\treadonly claimById: ReadonlyMap<string, Claim>;\n\t/** Per-claim trust floor; a missing floor defaults to `deterministic_validator`. */\n\treadonly claimFloors: ReadonlyMap<string, ObservationSource>;\n\treadonly sources: readonly SourceIdentity[];\n}\n\nconst floorRank = (floors: ReadonlyMap<string, ObservationSource>, claimId: string): number =>\n\tOBSERVATION_TRUST_RANK[floors.get(claimId) ?? \"deterministic_validator\"];\n\nconst findSource = (sources: readonly SourceIdentity[], id: string): SourceIdentity | undefined =>\n\tsources.find((s) => s.id === id);\n\n/**\n * ObservationNode → kernel observations.\n *\n * The result carries every emitted edge (one per resolvable claim — the\n * explicit relation table docs/06 asks for) or the declared reason none\n * could be emitted. No edge is ever emitted with fabricated provenance.\n */\nexport function mapObservation(node: BridgeObservation, ctx: ObservationMapContext): ObservationMapResult {\n\ttext(node.observationId, \"observationId\", 256);\n\ttext(node.sourceRoot, \"sourceRoot\", 512);\n\ttext(node.environmentDigest, \"environmentDigest\", 256);\n\tmember(node.source, Object.keys(OBSERVATION_TRUST_RANK), \"observation source\");\n\tinteger(ctx.nowMs, \"nowMs\");\n\tif (node.claimIds.length === 0) {\n\t\treturn { status: \"rejected\", reason: `${node.observationId}: no claim ids` };\n\t}\n\t// Clock and generation conflicts reject outright — docs/06 lists\n\t// generation moves, future timestamps and expiry as invalid on arrival.\n\tif (node.generation !== undefined && ctx.generation !== undefined && node.generation !== ctx.generation) {\n\t\treturn { status: \"rejected\", reason: `${node.observationId}: generation-mismatch` };\n\t}\n\tif (node.observedAtMs !== undefined && node.observedAtMs > ctx.nowMs) {\n\t\treturn { status: \"rejected\", reason: `${node.observationId}: future-observation` };\n\t}\n\tconst expiresAtMs = node.validUntil !== undefined ? ISO_MS(node.validUntil) : undefined;\n\tif (expiresAtMs !== undefined && expiresAtMs <= ctx.nowMs) {\n\t\treturn { status: \"rejected\", reason: `${node.observationId}: expired-observation` };\n\t}\n\tif (expiresAtMs !== undefined && node.observedAtMs !== undefined && expiresAtMs < node.observedAtMs) {\n\t\treturn { status: \"rejected\", reason: `${node.observationId}: invalid-validity-interval` };\n\t}\n\t// Binding: equal ⇒ kept, different ⇒ rejected, absent ⇒ unknownBindings.\n\t// The one thing that never happens is reattaching foreign or unbound\n\t// evidence to ctx.binding.\n\tif (node.binding !== undefined && node.binding !== ctx.binding) {\n\t\treturn { status: \"rejected\", reason: `${node.observationId}: binding-mismatch` };\n\t}\n\t// Polarity must be expressible by the kind this observation maps to.\n\tconst checkIds = [...new Set([...(node.checkId ? [node.checkId] : []), ...(node.checkIds ?? [])])];\n\tconst isCheck = node.receiptId !== undefined || checkIds.length > 0;\n\tconst isDecision = !isCheck && (node.source === \"model_narrative\" || node.actorId !== undefined);\n\tif (isUnknownPolarity(node.polarity) && !isCheck) {\n\t\treturn { status: \"rejected\", reason: `${node.observationId}: unexpressible-polarity` };\n\t}\n\t// Fields required to emit an edge without fabrication. Absent provenance\n\t// is declared loss; the edge is not emitted.\n\tconst missing: string[] = [];\n\tif (node.observedAtMs === undefined) missing.push(\"observedAtMs\");\n\tif (expiresAtMs === undefined) missing.push(\"validUntil\");\n\tif (isCheck) {\n\t\tif (checkIds.length === 0) missing.push(\"checkId\");\n\t\tif (node.sequence === undefined) missing.push(\"sequence\");\n\t}\n\tconst lostFields: string[] = missing.map((f) => `${node.observationId}.${f}`);\n\tconst unknownBindings: string[] = [];\n\tif (node.binding === undefined) unknownBindings.push(node.observationId);\n\tconst blockedByMissing = missing.length > 0 || node.binding === undefined;\n\n\tconst observations: Observation[] = [];\n\tconst usedSources = new Map<string, SourceIdentity>();\n\tconst unmappedClaims: string[] = [];\n\tconst family =\n\t\tnode.sourceFamily ?? node.independenceGroup ?? findSource(ctx.sources, node.source)?.family ?? node.source;\n\t// Edge ids stay unique when one observation emits several edges.\n\tconst edgeCount = node.claimIds.filter((c) => ctx.claimById.has(c)).length * Math.max(checkIds.length, 1);\n\tconst multi = edgeCount > 1;\n\tfor (const claimId of node.claimIds) {\n\t\tconst claim = ctx.claimById.get(claimId);\n\t\tif (!claim) {\n\t\t\tunmappedClaims.push(`${node.observationId}->${claimId}`);\n\t\t\tcontinue;\n\t\t}\n\t\tif (OBSERVATION_TRUST_RANK[node.source] < floorRank(ctx.claimFloors, claimId)) {\n\t\t\tunmappedClaims.push(`${node.observationId}->${claimId}`);\n\t\t\tcontinue;\n\t\t}\n\t\tif (blockedByMissing) continue; // declared above; emitted only with full provenance\n\t\t// Guaranteed present by the missing-fields computation above. `ensure`\n\t\t// narrows for the compiler and fails loudly instead of defaulting.\n\t\tensure(node.observedAtMs !== undefined, `${node.observationId}: observedAtMs required`);\n\t\tensure(expiresAtMs !== undefined, `${node.observationId}: validUntil required`);\n\t\tensure(node.binding !== undefined, `${node.observationId}: binding required`);\n\t\tconst base = {\n\t\t\tid: node.observationId,\n\t\t\tclaimId,\n\t\t\tbinding: node.binding,\n\t\t\tobservedAtMs: node.observedAtMs,\n\t\t\texpiresAtMs,\n\t\t};\n\t\tif (isCheck) {\n\t\t\tensure(node.sequence !== undefined, `${node.observationId}: sequence required`);\n\t\t\tconst verdict: CheckObservation[\"verdict\"] =\n\t\t\t\tnode.polarity === \"supports\" ? \"pass\" : node.polarity === \"violates\" ? \"fail\" : \"pending\";\n\t\t\tfor (const checkId of checkIds) {\n\t\t\t\tobservations.push({\n\t\t\t\t\t...base,\n\t\t\t\t\tid: multi ? `${node.observationId}#${claimId}#${checkId}` : node.observationId,\n\t\t\t\t\tkind: \"check\",\n\t\t\t\t\trunnerId: node.source,\n\t\t\t\t\tcheckId,\n\t\t\t\t\tsequence: node.sequence,\n\t\t\t\t\tverdict,\n\t\t\t\t});\n\t\t\t}\n\t\t} else if (isDecision) {\n\t\t\tobservations.push({\n\t\t\t\t...base,\n\t\t\t\tid: multi ? `${node.observationId}#${claimId}` : node.observationId,\n\t\t\t\tkind: \"decision\",\n\t\t\t\tactorId: node.actorId ?? \"model\",\n\t\t\t\taccepted: node.polarity === \"supports\",\n\t\t\t});\n\t\t} else {\n\t\t\t// Synthesized identity carries the witness's independence group so\n\t\t\t// the kernel counts families, not citation count.\n\t\t\tconst sourceId = `${node.source}@${family}`;\n\t\t\tif (!usedSources.has(sourceId)) {\n\t\t\t\tconst registered = findSource(ctx.sources, node.source);\n\t\t\t\tusedSources.set(sourceId, {\n\t\t\t\t\tid: sourceId,\n\t\t\t\t\tfamily,\n\t\t\t\t\tkind: registered?.kind === \"model\" || registered === undefined ? \"community\" : registered.kind,\n\t\t\t\t});\n\t\t\t}\n\t\t\tobservations.push({\n\t\t\t\t...base,\n\t\t\t\tid: multi ? `${node.observationId}#${claimId}` : node.observationId,\n\t\t\t\tkind: \"reference\",\n\t\t\t\tsourceId,\n\t\t\t\tversion: null,\n\t\t\t\tstance: node.polarity === \"supports\" ? \"support\" : \"refute\",\n\t\t\t\tdocumentDigest: node.environmentDigest,\n\t\t\t\tlocator: node.sourceRoot,\n\t\t\t});\n\t\t}\n\t}\n\tconst sources = [...usedSources.values()];\n\tif (lostFields.length === 0 && unknownBindings.length === 0 && unmappedClaims.length === 0) {\n\t\treturn { status: \"mapped\", observations, sources };\n\t}\n\treturn {\n\t\tstatus: \"partial\",\n\t\tobservations,\n\t\tsources,\n\t\tloss: lossOf({ lostFields, unmappedClaims, unknownBindings }),\n\t};\n}\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\t/** Current ledger generation; compared with each observation's own when present. */\n\treadonly generation?: number;\n\treadonly claims: readonly ClaimNode[];\n\treadonly observations: readonly BridgeObservation[];\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\t/** Extra admissible source identities beyond the built-in registry. */\n\treadonly sources?: readonly SourceIdentity[];\n}\n\n/** Witness pairs that conflict on independence or polarity. */\nfunction familyConflicts(\n\tedges: readonly Observation[],\n\trejected: readonly { id: string; reason: string }[],\n\tinputs: readonly BridgeObservation[],\n\tclaimById: ReadonlyMap<string, Claim>,\n): string[] {\n\tconst conflicts: string[] = [];\n\tconst byClaim = new Map<string, Observation[]>();\n\tfor (const e of edges) byClaim.set(e.claimId, [...(byClaim.get(e.claimId) ?? []), e]);\n\tfor (const [claimId, list] of byClaim) {\n\t\t// Opposing witnesses (support vs refute / pass vs fail) from the same\n\t\t// source family on one claim.\n\t\tconst signs = new Map<string, Set<string>>();\n\t\tfor (const e of list) {\n\t\t\tconst fam = e.kind === \"reference\" ? e.sourceId : e.kind === \"check\" ? e.runnerId : e.actorId;\n\t\t\tconst sign =\n\t\t\t\te.kind === \"reference\"\n\t\t\t\t\t? e.stance\n\t\t\t\t\t: e.kind === \"check\"\n\t\t\t\t\t\t? e.verdict === \"pending\"\n\t\t\t\t\t\t\t? \"pending\"\n\t\t\t\t\t\t\t: e.verdict === \"pass\"\n\t\t\t\t\t\t\t\t? \"support\"\n\t\t\t\t\t\t\t\t: \"refute\"\n\t\t\t\t\t\t: e.accepted\n\t\t\t\t\t\t\t? \"support\"\n\t\t\t\t\t\t\t: \"refute\";\n\t\t\tsigns.set(fam, new Set([...(signs.get(fam) ?? []), sign]));\n\t\t}\n\t\tfor (const [fam, s] of signs) {\n\t\t\tif (s.has(\"support\") && s.has(\"refute\")) conflicts.push(`conflicting-witness:${claimId}:${fam}`);\n\t\t}\n\t}\n\t// Same (claim, family) cited by several distinct observations duplicates\n\t// one independence group — counted once by the kernel, declared here.\n\tconst cited = new Map<string, Set<string>>();\n\tfor (const o of inputs) {\n\t\tif (rejected.some((r) => r.id === o.observationId)) continue;\n\t\tfor (const claimId of o.claimIds) {\n\t\t\tif (!claimById.has(claimId)) continue;\n\t\t\tconst key = `${claimId}|${o.sourceFamily ?? o.independenceGroup ?? o.source}`;\n\t\t\tcited.set(key, new Set([...(cited.get(key) ?? []), o.observationId]));\n\t\t}\n\t}\n\tfor (const [key, ids] of cited) {\n\t\tif (ids.size > 1) conflicts.push(`duplicate-citation:${key}`);\n\t}\n\treturn conflicts.sort(lexical);\n}\n\n/**\n * Check edges sharing (claimId, binding, checkId, sequence) must agree\n * verbatim — the kernel `ensure`s that and would throw. Conflicting slots\n * are ledger corruption: suppress *all* edges in the slot (admit neither)\n * and leave the conflict declared in sourceFamilyConflicts.\n */\nfunction suppressConflictingSequences(edges: readonly Observation[]): Observation[] {\n\tconst slots = new Map<string, Observation[]>();\n\tfor (const e of edges) {\n\t\tif (e.kind !== \"check\") continue;\n\t\tconst key = canonical([e.claimId, e.binding, e.checkId, e.sequence]);\n\t\tslots.set(key, [...(slots.get(key) ?? []), e]);\n\t}\n\tconst drop = new Set<string>();\n\tfor (const list of slots.values()) {\n\t\tif (new Set(list.map((e) => canonical(e))).size > 1) {\n\t\t\tfor (const e of list) drop.add(e.id);\n\t\t}\n\t}\n\treturn edges.filter((e) => !drop.has(e.id));\n}\n\n/** Build kernel inputs plus a MetaState for one safe checkpoint. Host-owned inputs only. */\nexport function toMetaState(input: RuntimeBridgeInput): RuntimeBridgeResult {\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\tconst binding = `${input.candidateHash}@${input.environmentHash}`;\n\t// Only leaf claims map to kernel claims — compound satisfaction is the\n\t// protocol layer's job, and is now declared instead of dropped silently.\n\tconst compoundIds = input.claims.filter((c) => c.satisfaction.inputs.length > 0).map((c) => c.claimId);\n\tconst leafClaims = input.claims.filter((c) => c.satisfaction.inputs.length === 0);\n\tconst claimById = new Map<string, Claim>();\n\tconst claimLosses: BridgeLoss[] = [];\n\tfor (const c of leafClaims) {\n\t\tconst m = mapClaim(c, input.stage, binding);\n\t\tif (m.status === \"rejected\") {\n\t\t\tclaimLosses.push(lossOf({ unmappedClaims: [`claim:${c.claimId}`], rejectedObservations: [] }));\n\t\t\tcontinue;\n\t\t}\n\t\tclaimById.set(c.claimId, m.claim);\n\t\tif (m.status === \"partial\") claimLosses.push(m.loss);\n\t}\n\tconst kernelClaims = [...claimById.values()].sort((a, b) => lexical(a.id, b.id));\n\tconst claimFloors = new Map(leafClaims.map((c) => [c.claimId, c.trustFloor] as const));\n\tconst baseSources = sourceIdentities(input.sources ?? []);\n\tconst ctx: ObservationMapContext = {\n\t\tbinding,\n\t\tnowMs: input.nowMs,\n\t\tgeneration: input.generation,\n\t\tclaimById,\n\t\tclaimFloors,\n\t\tsources: baseSources,\n\t};\n\tconst emitted: Observation[] = [];\n\tconst usedSources = new Map<string, SourceIdentity>();\n\tconst obsLosses: BridgeLoss[] = [];\n\tconst rejectedObs: { id: string; reason: string }[] = [];\n\tfor (const o of input.observations) {\n\t\tconst r = mapObservation(o, ctx);\n\t\tif (r.status === \"rejected\") {\n\t\t\trejectedObs.push({ id: o.observationId, reason: r.reason });\n\t\t\tcontinue;\n\t\t}\n\t\temitted.push(...r.observations);\n\t\tfor (const s of r.sources) usedSources.set(s.id, s);\n\t\tif (r.status === \"partial\") obsLosses.push(r.loss);\n\t}\n\tconst kernelObservations = suppressConflictingSequences(emitted);\n\tconst bridgeLoss = mergeBridgeLoss([...claimLosses, ...obsLosses]);\n\tconst conflicts = familyConflicts(emitted, rejectedObs, input.observations, claimById);\n\tconst loss: BridgeLoss = {\n\t\t...bridgeLoss,\n\t\tunmappedClaims: [...bridgeLoss.unmappedClaims, ...compoundIds.map((id) => `claim:${id}`)].sort(lexical),\n\t\tsourceFamilyConflicts: [...bridgeLoss.sourceFamilyConflicts, ...conflicts].sort(lexical),\n\t\trejectedObservations: [...bridgeLoss.rejectedObservations, ...rejectedObs].sort((a, b) => lexical(a.id, b.id)),\n\t};\n\tconst requiredIds = new Set(input.claims.filter((c) => c.severity === \"required\").map((c) => c.claimId));\n\tconst touched = new Set<string>();\n\tfor (const u of loss.unmappedClaims) {\n\t\tfor (const id of requiredIds) {\n\t\t\tif (u === `claim:${id}` || u.endsWith(`->${id}`)) touched.add(id);\n\t\t}\n\t}\n\tfor (const obsId of loss.unknownBindings) {\n\t\tconst src = input.observations.find((o) => o.observationId === obsId);\n\t\tfor (const c of src?.claimIds ?? []) if (requiredIds.has(c)) touched.add(c);\n\t}\n\tfor (const r of loss.rejectedObservations) {\n\t\tconst src = input.observations.find((o) => o.observationId === r.id);\n\t\tfor (const c of src?.claimIds ?? []) if (requiredIds.has(c)) touched.add(c);\n\t}\n\tfor (const f of loss.lostFields) {\n\t\tif (f.startsWith(\"claim:\")) {\n\t\t\tconst id = f.slice(\"claim:\".length).split(\".\")[0] ?? \"\";\n\t\t\tif (requiredIds.has(id)) touched.add(id);\n\t\t\tcontinue;\n\t\t}\n\t\tconst obsId = f.split(\".\")[0] ?? \"\";\n\t\tconst src = input.observations.find((o) => o.observationId === obsId);\n\t\tfor (const c of src?.claimIds ?? []) if (requiredIds.has(c)) touched.add(c);\n\t}\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\tconst sources = [...new Map([...baseSources, ...usedSources.values()].map((s) => [s.id, s])).values()];\n\tconst value: RuntimeBridgeOutput = { state, claims: kernelClaims, observations: kernelObservations, sources };\n\tconst empty =\n\t\tloss.lostFields.length === 0 &&\n\t\tloss.unmappedClaims.length === 0 &&\n\t\tloss.unknownBindings.length === 0 &&\n\t\tloss.sourceFamilyConflicts.length === 0 &&\n\t\tloss.rejectedObservations.length === 0;\n\tif (empty) return { status: \"mapped\", value };\n\treturn {\n\t\tstatus: \"partial\",\n\t\tvalue,\n\t\tloss,\n\t\ttouchesRequiredClaims: [...touched].sort(lexical),\n\t};\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"]}