open-multi-agent-kit 0.96.1 → 0.97.0

package/dist/core/reasoning-router-promotion.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Promotion gate for learned reasoning-router weights.
+ *
+ * The router already produces a feedback ledger (`router-feedback-collector.ts`)
+ * and an offline calibration stack (`scripts/reasoning-router/`: calibration,
+ * held-out evaluation, golden diffing, and McNemar's exact test). What was
+ * missing is the decision policy that makes automatic promotion trustworthy:
+ * without it the loop is open and every weight change is a judgement call.
+ *
+ * This module is that policy, as a pure total function. It deliberately refuses
+ * to promote on anything short of unanimous evidence:
+ *
+ * - a statistically significant win on the held-in gold set (McNemar's exact
+ *   test), computed by the caller and passed in;
+ * - enough discordant pairs for that test to mean anything;
+ * - the candidate — not the baseline — winning those pairs;
+ * - no accuracy regression on a held-out split the calibration never saw;
+ * - no unreviewed behavior changes surfaced by golden diffing; and
+ * - an explicit human approval.
+ *
+ * "The agent tried again" is not the same as "the harness improved", so a
+ * candidate that merely fails to be worse is rejected, and malformed evidence
+ * fails closed rather than defaulting to promotion.
+ */
+/** Held-in McNemar outcome. Wins are counted in discordant pairs only. */
+export interface RouterHeldInEvidence {
+    /** Rows the baseline classified correctly and the candidate got wrong. */
+    readonly baselineWins: number;
+    /** Rows the candidate classified correctly and the baseline got wrong. */
+    readonly candidateWins: number;
+    readonly pValue: number;
+    readonly significant: boolean;
+}
+/** Accuracy on a split withheld from calibration. */
+export interface RouterHoldoutEvidence {
+    readonly baselineCorrect: number;
+    readonly candidateCorrect: number;
+    readonly total: number;
+}
+/** Everything the gate is allowed to consider. */
+export interface RouterPromotionEvidence {
+    readonly heldIn: RouterHeldInEvidence;
+    readonly holdout: RouterHoldoutEvidence;
+    /** Golden-diff changes still unreviewed at decision time. */
+    readonly goldenChanges: number;
+    /** True only when a human explicitly approved this exact candidate. */
+    readonly humanApproved: boolean;
+}
+/** Tunable thresholds. Loosening these can never authorize a regression. */
+export interface RouterPromotionPolicy {
+    /** Minimum discordant pairs before McNemar's verdict is trusted. */
+    readonly minDiscordant: number;
+    /** Minimum held-out rows before "no regression" is meaningful. */
+    readonly minHoldout: number;
+    /** Maximum unreviewed golden-diff changes tolerated. */
+    readonly maxGoldenChanges: number;
+    readonly requireHumanApproval: boolean;
+}
+export type RouterPromotionBlocker = "malformed_evidence" | "insufficient_discordant_pairs" | "mcnemar_not_significant" | "candidate_not_favored" | "holdout_regression" | "insufficient_holdout" | "unreviewed_behavior_changes" | "human_approval_missing";
+export interface RouterPromotionVerdict {
+    readonly promote: boolean;
+    /** Every independent reason promotion was refused, in evaluation order. */
+    readonly blockers: readonly RouterPromotionBlocker[];
+}
+/**
+ * Conservative defaults. `minDiscordant` of 20 keeps McNemar from ruling on a
+ * handful of pairs; `maxGoldenChanges` of 0 means a reviewer accepts behavior
+ * changes by regenerating the golden set, never by tolerating drift.
+ *
+ * `minHoldout` is 40 because the router gold set freezes 42 holdout rows (6 per
+ * class × 7 classes). A higher bar would be unsatisfiable rather than strict,
+ * and a gate that can never pass is a gate nobody runs.
+ */
+export declare const DEFAULT_ROUTER_PROMOTION_POLICY: RouterPromotionPolicy;
+/**
+ * Decide whether a candidate weight set may replace the active one.
+ *
+ * Returns every independent blocker rather than the first, so one calibration
+ * run reports the full distance to promotion instead of revealing it one
+ * rejection at a time. Malformed evidence short-circuits: the gate never
+ * reasons about numbers it cannot trust.
+ */
+export declare function evaluateRouterPromotion(evidence: RouterPromotionEvidence, policy?: RouterPromotionPolicy): RouterPromotionVerdict;
+//# sourceMappingURL=reasoning-router-promotion.d.ts.map

package/dist/core/reasoning-router-promotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-router-promotion.d.ts","sourceRoot":"","sources":["../../src/core/reasoning-router-promotion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC9B;AAED,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CAChC;AAED,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACrC,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,MAAM,sBAAsB,GAC/B,oBAAoB,GACpB,+BAA+B,GAC/B,yBAAyB,GACzB,uBAAuB,GACvB,oBAAoB,GACpB,sBAAsB,GACtB,6BAA6B,GAC7B,wBAAwB,CAAC;AAE5B,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACrD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,EAAE,qBAK7C,CAAC;AAeF;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,uBAAuB,EACjC,MAAM,GAAE,qBAAuD,GAC7D,sBAAsB,CA+BxB","sourcesContent":["/**\n * Promotion gate for learned reasoning-router weights.\n *\n * The router already produces a feedback ledger (`router-feedback-collector.ts`)\n * and an offline calibration stack (`scripts/reasoning-router/`: calibration,\n * held-out evaluation, golden diffing, and McNemar's exact test). What was\n * missing is the decision policy that makes automatic promotion trustworthy:\n * without it the loop is open and every weight change is a judgement call.\n *\n * This module is that policy, as a pure total function. It deliberately refuses\n * to promote on anything short of unanimous evidence:\n *\n * - a statistically significant win on the held-in gold set (McNemar's exact\n *   test), computed by the caller and passed in;\n * - enough discordant pairs for that test to mean anything;\n * - the candidate — not the baseline — winning those pairs;\n * - no accuracy regression on a held-out split the calibration never saw;\n * - no unreviewed behavior changes surfaced by golden diffing; and\n * - an explicit human approval.\n *\n * \"The agent tried again\" is not the same as \"the harness improved\", so a\n * candidate that merely fails to be worse is rejected, and malformed evidence\n * fails closed rather than defaulting to promotion.\n */\n\n/** Held-in McNemar outcome. Wins are counted in discordant pairs only. */\nexport interface RouterHeldInEvidence {\n\t/** Rows the baseline classified correctly and the candidate got wrong. */\n\treadonly baselineWins: number;\n\t/** Rows the candidate classified correctly and the baseline got wrong. */\n\treadonly candidateWins: number;\n\treadonly pValue: number;\n\treadonly significant: boolean;\n}\n\n/** Accuracy on a split withheld from calibration. */\nexport interface RouterHoldoutEvidence {\n\treadonly baselineCorrect: number;\n\treadonly candidateCorrect: number;\n\treadonly total: number;\n}\n\n/** Everything the gate is allowed to consider. */\nexport interface RouterPromotionEvidence {\n\treadonly heldIn: RouterHeldInEvidence;\n\treadonly holdout: RouterHoldoutEvidence;\n\t/** Golden-diff changes still unreviewed at decision time. */\n\treadonly goldenChanges: number;\n\t/** True only when a human explicitly approved this exact candidate. */\n\treadonly humanApproved: boolean;\n}\n\n/** Tunable thresholds. Loosening these can never authorize a regression. */\nexport interface RouterPromotionPolicy {\n\t/** Minimum discordant pairs before McNemar's verdict is trusted. */\n\treadonly minDiscordant: number;\n\t/** Minimum held-out rows before \"no regression\" is meaningful. */\n\treadonly minHoldout: number;\n\t/** Maximum unreviewed golden-diff changes tolerated. */\n\treadonly maxGoldenChanges: number;\n\treadonly requireHumanApproval: boolean;\n}\n\nexport type RouterPromotionBlocker =\n\t| \"malformed_evidence\"\n\t| \"insufficient_discordant_pairs\"\n\t| \"mcnemar_not_significant\"\n\t| \"candidate_not_favored\"\n\t| \"holdout_regression\"\n\t| \"insufficient_holdout\"\n\t| \"unreviewed_behavior_changes\"\n\t| \"human_approval_missing\";\n\nexport interface RouterPromotionVerdict {\n\treadonly promote: boolean;\n\t/** Every independent reason promotion was refused, in evaluation order. */\n\treadonly blockers: readonly RouterPromotionBlocker[];\n}\n\n/**\n * Conservative defaults. `minDiscordant` of 20 keeps McNemar from ruling on a\n * handful of pairs; `maxGoldenChanges` of 0 means a reviewer accepts behavior\n * changes by regenerating the golden set, never by tolerating drift.\n *\n * `minHoldout` is 40 because the router gold set freezes 42 holdout rows (6 per\n * class × 7 classes). A higher bar would be unsatisfiable rather than strict,\n * and a gate that can never pass is a gate nobody runs.\n */\nexport const DEFAULT_ROUTER_PROMOTION_POLICY: RouterPromotionPolicy = {\n\tmaxGoldenChanges: 0,\n\tminDiscordant: 20,\n\tminHoldout: 40,\n\trequireHumanApproval: true,\n};\n\nfunction isCount(value: number): boolean {\n\treturn Number.isFinite(value) && value >= 0;\n}\n\nfunction isMalformed(evidence: RouterPromotionEvidence): boolean {\n\tconst { goldenChanges, heldIn, holdout } = evidence;\n\tif (!isCount(heldIn.baselineWins) || !isCount(heldIn.candidateWins)) return true;\n\tif (!Number.isFinite(heldIn.pValue) || heldIn.pValue < 0 || heldIn.pValue > 1) return true;\n\tif (!isCount(holdout.baselineCorrect) || !isCount(holdout.candidateCorrect) || !isCount(holdout.total)) return true;\n\tif (holdout.baselineCorrect > holdout.total || holdout.candidateCorrect > holdout.total) return true;\n\treturn !isCount(goldenChanges);\n}\n\n/**\n * Decide whether a candidate weight set may replace the active one.\n *\n * Returns every independent blocker rather than the first, so one calibration\n * run reports the full distance to promotion instead of revealing it one\n * rejection at a time. Malformed evidence short-circuits: the gate never\n * reasons about numbers it cannot trust.\n */\nexport function evaluateRouterPromotion(\n\tevidence: RouterPromotionEvidence,\n\tpolicy: RouterPromotionPolicy = DEFAULT_ROUTER_PROMOTION_POLICY,\n): RouterPromotionVerdict {\n\tif (isMalformed(evidence)) {\n\t\treturn { blockers: [\"malformed_evidence\"], promote: false };\n\t}\n\n\tconst { goldenChanges, heldIn, holdout, humanApproved } = evidence;\n\tconst blockers: RouterPromotionBlocker[] = [];\n\n\tif (heldIn.baselineWins + heldIn.candidateWins < policy.minDiscordant) {\n\t\tblockers.push(\"insufficient_discordant_pairs\");\n\t}\n\tif (!heldIn.significant) {\n\t\tblockers.push(\"mcnemar_not_significant\");\n\t}\n\tif (heldIn.candidateWins <= heldIn.baselineWins) {\n\t\tblockers.push(\"candidate_not_favored\");\n\t}\n\tif (holdout.total < policy.minHoldout) {\n\t\tblockers.push(\"insufficient_holdout\");\n\t}\n\tif (holdout.candidateCorrect < holdout.baselineCorrect) {\n\t\tblockers.push(\"holdout_regression\");\n\t}\n\tif (goldenChanges > policy.maxGoldenChanges) {\n\t\tblockers.push(\"unreviewed_behavior_changes\");\n\t}\n\tif (policy.requireHumanApproval && !humanApproved) {\n\t\tblockers.push(\"human_approval_missing\");\n\t}\n\n\treturn { blockers, promote: blockers.length === 0 };\n}\n"]}

package/dist/core/reasoning-router-promotion.js

@@ -0,0 +1,92 @@
+/**
+ * Promotion gate for learned reasoning-router weights.
+ *
+ * The router already produces a feedback ledger (`router-feedback-collector.ts`)
+ * and an offline calibration stack (`scripts/reasoning-router/`: calibration,
+ * held-out evaluation, golden diffing, and McNemar's exact test). What was
+ * missing is the decision policy that makes automatic promotion trustworthy:
+ * without it the loop is open and every weight change is a judgement call.
+ *
+ * This module is that policy, as a pure total function. It deliberately refuses
+ * to promote on anything short of unanimous evidence:
+ *
+ * - a statistically significant win on the held-in gold set (McNemar's exact
+ *   test), computed by the caller and passed in;
+ * - enough discordant pairs for that test to mean anything;
+ * - the candidate — not the baseline — winning those pairs;
+ * - no accuracy regression on a held-out split the calibration never saw;
+ * - no unreviewed behavior changes surfaced by golden diffing; and
+ * - an explicit human approval.
+ *
+ * "The agent tried again" is not the same as "the harness improved", so a
+ * candidate that merely fails to be worse is rejected, and malformed evidence
+ * fails closed rather than defaulting to promotion.
+ */
+/**
+ * Conservative defaults. `minDiscordant` of 20 keeps McNemar from ruling on a
+ * handful of pairs; `maxGoldenChanges` of 0 means a reviewer accepts behavior
+ * changes by regenerating the golden set, never by tolerating drift.
+ *
+ * `minHoldout` is 40 because the router gold set freezes 42 holdout rows (6 per
+ * class × 7 classes). A higher bar would be unsatisfiable rather than strict,
+ * and a gate that can never pass is a gate nobody runs.
+ */
+export const DEFAULT_ROUTER_PROMOTION_POLICY = {
+    maxGoldenChanges: 0,
+    minDiscordant: 20,
+    minHoldout: 40,
+    requireHumanApproval: true,
+};
+function isCount(value) {
+    return Number.isFinite(value) && value >= 0;
+}
+function isMalformed(evidence) {
+    const { goldenChanges, heldIn, holdout } = evidence;
+    if (!isCount(heldIn.baselineWins) || !isCount(heldIn.candidateWins))
+        return true;
+    if (!Number.isFinite(heldIn.pValue) || heldIn.pValue < 0 || heldIn.pValue > 1)
+        return true;
+    if (!isCount(holdout.baselineCorrect) || !isCount(holdout.candidateCorrect) || !isCount(holdout.total))
+        return true;
+    if (holdout.baselineCorrect > holdout.total || holdout.candidateCorrect > holdout.total)
+        return true;
+    return !isCount(goldenChanges);
+}
+/**
+ * Decide whether a candidate weight set may replace the active one.
+ *
+ * Returns every independent blocker rather than the first, so one calibration
+ * run reports the full distance to promotion instead of revealing it one
+ * rejection at a time. Malformed evidence short-circuits: the gate never
+ * reasons about numbers it cannot trust.
+ */
+export function evaluateRouterPromotion(evidence, policy = DEFAULT_ROUTER_PROMOTION_POLICY) {
+    if (isMalformed(evidence)) {
+        return { blockers: ["malformed_evidence"], promote: false };
+    }
+    const { goldenChanges, heldIn, holdout, humanApproved } = evidence;
+    const blockers = [];
+    if (heldIn.baselineWins + heldIn.candidateWins < policy.minDiscordant) {
+        blockers.push("insufficient_discordant_pairs");
+    }
+    if (!heldIn.significant) {
+        blockers.push("mcnemar_not_significant");
+    }
+    if (heldIn.candidateWins <= heldIn.baselineWins) {
+        blockers.push("candidate_not_favored");
+    }
+    if (holdout.total < policy.minHoldout) {
+        blockers.push("insufficient_holdout");
+    }
+    if (holdout.candidateCorrect < holdout.baselineCorrect) {
+        blockers.push("holdout_regression");
+    }
+    if (goldenChanges > policy.maxGoldenChanges) {
+        blockers.push("unreviewed_behavior_changes");
+    }
+    if (policy.requireHumanApproval && !humanApproved) {
+        blockers.push("human_approval_missing");
+    }
+    return { blockers, promote: blockers.length === 0 };
+}
+//# sourceMappingURL=reasoning-router-promotion.js.map

package/dist/core/reasoning-router-promotion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-router-promotion.js","sourceRoot":"","sources":["../../src/core/reasoning-router-promotion.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Promotion gate for learned reasoning-router weights.\n *\n * The router already produces a feedback ledger (`router-feedback-collector.ts`)\n * and an offline calibration stack (`scripts/reasoning-router/`: calibration,\n * held-out evaluation, golden diffing, and McNemar's exact test). What was\n * missing is the decision policy that makes automatic promotion trustworthy:\n * without it the loop is open and every weight change is a judgement call.\n *\n * This module is that policy, as a pure total function. It deliberately refuses\n * to promote on anything short of unanimous evidence:\n *\n * - a statistically significant win on the held-in gold set (McNemar's exact\n *   test), computed by the caller and passed in;\n * - enough discordant pairs for that test to mean anything;\n * - the candidate — not the baseline — winning those pairs;\n * - no accuracy regression on a held-out split the calibration never saw;\n * - no unreviewed behavior changes surfaced by golden diffing; and\n * - an explicit human approval.\n *\n * \"The agent tried again\" is not the same as \"the harness improved\", so a\n * candidate that merely fails to be worse is rejected, and malformed evidence\n * fails closed rather than defaulting to promotion.\n */\n\n/** Held-in McNemar outcome. Wins are counted in discordant pairs only. */\nexport interface RouterHeldInEvidence {\n\t/** Rows the baseline classified correctly and the candidate got wrong. */\n\treadonly baselineWins: number;\n\t/** Rows the candidate classified correctly and the baseline got wrong. */\n\treadonly candidateWins: number;\n\treadonly pValue: number;\n\treadonly significant: boolean;\n}\n\n/** Accuracy on a split withheld from calibration. */\nexport interface RouterHoldoutEvidence {\n\treadonly baselineCorrect: number;\n\treadonly candidateCorrect: number;\n\treadonly total: number;\n}\n\n/** Everything the gate is allowed to consider. */\nexport interface RouterPromotionEvidence {\n\treadonly heldIn: RouterHeldInEvidence;\n\treadonly holdout: RouterHoldoutEvidence;\n\t/** Golden-diff changes still unreviewed at decision time. */\n\treadonly goldenChanges: number;\n\t/** True only when a human explicitly approved this exact candidate. */\n\treadonly humanApproved: boolean;\n}\n\n/** Tunable thresholds. Loosening these can never authorize a regression. */\nexport interface RouterPromotionPolicy {\n\t/** Minimum discordant pairs before McNemar's verdict is trusted. */\n\treadonly minDiscordant: number;\n\t/** Minimum held-out rows before \"no regression\" is meaningful. */\n\treadonly minHoldout: number;\n\t/** Maximum unreviewed golden-diff changes tolerated. */\n\treadonly maxGoldenChanges: number;\n\treadonly requireHumanApproval: boolean;\n}\n\nexport type RouterPromotionBlocker =\n\t| \"malformed_evidence\"\n\t| \"insufficient_discordant_pairs\"\n\t| \"mcnemar_not_significant\"\n\t| \"candidate_not_favored\"\n\t| \"holdout_regression\"\n\t| \"insufficient_holdout\"\n\t| \"unreviewed_behavior_changes\"\n\t| \"human_approval_missing\";\n\nexport interface RouterPromotionVerdict {\n\treadonly promote: boolean;\n\t/** Every independent reason promotion was refused, in evaluation order. */\n\treadonly blockers: readonly RouterPromotionBlocker[];\n}\n\n/**\n * Conservative defaults. `minDiscordant` of 20 keeps McNemar from ruling on a\n * handful of pairs; `maxGoldenChanges` of 0 means a reviewer accepts behavior\n * changes by regenerating the golden set, never by tolerating drift.\n *\n * `minHoldout` is 40 because the router gold set freezes 42 holdout rows (6 per\n * class × 7 classes). A higher bar would be unsatisfiable rather than strict,\n * and a gate that can never pass is a gate nobody runs.\n */\nexport const DEFAULT_ROUTER_PROMOTION_POLICY: RouterPromotionPolicy = {\n\tmaxGoldenChanges: 0,\n\tminDiscordant: 20,\n\tminHoldout: 40,\n\trequireHumanApproval: true,\n};\n\nfunction isCount(value: number): boolean {\n\treturn Number.isFinite(value) && value >= 0;\n}\n\nfunction isMalformed(evidence: RouterPromotionEvidence): boolean {\n\tconst { goldenChanges, heldIn, holdout } = evidence;\n\tif (!isCount(heldIn.baselineWins) || !isCount(heldIn.candidateWins)) return true;\n\tif (!Number.isFinite(heldIn.pValue) || heldIn.pValue < 0 || heldIn.pValue > 1) return true;\n\tif (!isCount(holdout.baselineCorrect) || !isCount(holdout.candidateCorrect) || !isCount(holdout.total)) return true;\n\tif (holdout.baselineCorrect > holdout.total || holdout.candidateCorrect > holdout.total) return true;\n\treturn !isCount(goldenChanges);\n}\n\n/**\n * Decide whether a candidate weight set may replace the active one.\n *\n * Returns every independent blocker rather than the first, so one calibration\n * run reports the full distance to promotion instead of revealing it one\n * rejection at a time. Malformed evidence short-circuits: the gate never\n * reasons about numbers it cannot trust.\n */\nexport function evaluateRouterPromotion(\n\tevidence: RouterPromotionEvidence,\n\tpolicy: RouterPromotionPolicy = DEFAULT_ROUTER_PROMOTION_POLICY,\n): RouterPromotionVerdict {\n\tif (isMalformed(evidence)) {\n\t\treturn { blockers: [\"malformed_evidence\"], promote: false };\n\t}\n\n\tconst { goldenChanges, heldIn, holdout, humanApproved } = evidence;\n\tconst blockers: RouterPromotionBlocker[] = [];\n\n\tif (heldIn.baselineWins + heldIn.candidateWins < policy.minDiscordant) {\n\t\tblockers.push(\"insufficient_discordant_pairs\");\n\t}\n\tif (!heldIn.significant) {\n\t\tblockers.push(\"mcnemar_not_significant\");\n\t}\n\tif (heldIn.candidateWins <= heldIn.baselineWins) {\n\t\tblockers.push(\"candidate_not_favored\");\n\t}\n\tif (holdout.total < policy.minHoldout) {\n\t\tblockers.push(\"insufficient_holdout\");\n\t}\n\tif (holdout.candidateCorrect < holdout.baselineCorrect) {\n\t\tblockers.push(\"holdout_regression\");\n\t}\n\tif (goldenChanges > policy.maxGoldenChanges) {\n\t\tblockers.push(\"unreviewed_behavior_changes\");\n\t}\n\tif (policy.requireHumanApproval && !humanApproved) {\n\t\tblockers.push(\"human_approval_missing\");\n\t}\n\n\treturn { blockers, promote: blockers.length === 0 };\n}\n"]}

package/dist/core/reasoning-router-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reasoning-router-resolver.d.ts","sourceRoot":"","sources":["../../src/core/reasoning-router-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,mDAAmD;AACnD,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEnH,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElG,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAAyD,CAAC;AAE/G,iIAAiI;AACjI,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAQ1F,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,SAAS,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAItE,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,QAAQ,IAAI,CAAC;AAC1B,2EAA2E;AAC3E,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAM7C;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,aAAa,EAAE,GAAG,aAAa,CAU9G;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACvC,SAAS,EAAE,kBAAkB,EAC7B,eAAe,EAAE,SAAS,aAAa,EAAE,EACzC,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EACzD,eAAe,EAAE,MAAM,GACrB,aAAa,CAoBf","sourcesContent":["/**\n * Shared resolver core for the v4 reasoning router: canonical task-class ->\n * ThinkingLevel rule table, lane-step adjustment, ladder-index clamping, and\n * bounded bias/hint/escalation resolution logic.\n *\n * Deterministic, side-effect-free: no clock, randomness, or I/O.\n */\n\nimport type { ThinkingLevel } from \"omk-agent-core\";\n\n/** The 7-class union used by the v4 classifier. */\nexport type ReasoningTaskClass = \"trivial\" | \"simple-edit\" | \"code-gen\" | \"debug\" | \"refactor\" | \"review\" | \"plan\";\n\n/** The 6-lane union used by the v4 classifier. */\nexport type ReasoningLane = \"planner\" | \"security\" | \"explorer\" | \"coder\" | \"reviewer\" | \"tester\";\n\n/** Reasoning ladder used for targets and clamping. Intentionally excludes \"off\". */\nexport const REASONING_LADDER: readonly ThinkingLevel[] = [\"minimal\", \"low\", \"medium\", \"high\", \"xhigh\", \"max\"];\n\n/** Static rule table: task class -> recommended ThinkingLevel (before lane adjustment, bias, hint, escalation, and clamping). */\nexport const TASK_CLASS_THINKING_LEVELS: Readonly<Record<ReasoningTaskClass, ThinkingLevel>> = {\n\ttrivial: \"minimal\",\n\t\"simple-edit\": \"low\",\n\t\"code-gen\": \"medium\",\n\tdebug: \"high\",\n\trefactor: \"high\",\n\treview: \"high\",\n\tplan: \"xhigh\",\n};\n\n/** Lane adjustment in ladder steps: planner/security escalate, explorer de-escalates. */\nexport const LANE_STEP: Readonly<Partial<Record<ReasoningLane, 1 | -1>>> = {\n\tplanner: 1,\n\tsecurity: 1,\n\texplorer: -1,\n};\n\n/** Maximum magnitude of the learning/consult bias (ladder steps). */\nexport const BIAS_MAX = 2;\n/** Confidence floor at which an override hint is fused into the target. */\nexport const HINT_CONFIDENCE_THRESHOLD = 0.7;\n\nfunction clampToLadderIndex(index: number): number {\n\treturn Math.max(0, Math.min(index, REASONING_LADDER.length - 1));\n}\n\n/**\n * Clamp a target ladder index to capability: the highest level in\n * `availableLevels` that is <= the target; if no available level is at/below\n * the target, return the lowest available reasoning level. Never invents a\n * level outside `availableLevels`. `\"off\"` is only returned when\n * `availableLevels` is empty (callers are expected to bypass the router\n * entirely for models with `reasoning: false`).\n */\nexport function clampToAvailable(targetIndex: number, availableLevels: readonly ThinkingLevel[]): ThinkingLevel {\n\tconst availableOnLadder = REASONING_LADDER.filter((level) => availableLevels.includes(level));\n\tif (availableOnLadder.length === 0) {\n\t\treturn availableLevels[0] ?? \"off\";\n\t}\n\tfor (let i = targetIndex; i >= 0; i--) {\n\t\tconst candidate = REASONING_LADDER[i];\n\t\tif (availableOnLadder.includes(candidate)) return candidate;\n\t}\n\treturn availableOnLadder[0];\n}\n\n/**\n * Canonical resolver core for v4.\n *\n * Pipeline: base rule table -> lane step -> bounded bias [-BIAS_MAX,+BIAS_MAX]\n * -> optional hint fusion (bounded ±BIAS_MAX steps toward hint.level, only\n * when hint.confidence >= HINT_CONFIDENCE_THRESHOLD) -> non-negative\n * escalationSteps bump -> clamp to availableLevels.\n */\nexport function resolveThinkingLevelCore(\n\ttaskClass: ReasoningTaskClass,\n\tavailableLevels: readonly ThinkingLevel[],\n\tlaneType: ReasoningLane | undefined,\n\tbias: number,\n\thint: { level: ThinkingLevel; confidence: number } | null,\n\tescalationSteps: number,\n): ThinkingLevel {\n\tconst baseIndex = REASONING_LADDER.indexOf(TASK_CLASS_THINKING_LEVELS[taskClass]);\n\tconst laneStep = laneType ? (LANE_STEP[laneType] ?? 0) : 0;\n\tconst biasClamped = Math.max(-BIAS_MAX, Math.min(BIAS_MAX, bias));\n\tlet targetIndex = clampToLadderIndex(baseIndex + laneStep + biasClamped);\n\n\tif (hint !== null && hint.confidence >= HINT_CONFIDENCE_THRESHOLD) {\n\t\tconst hintIndex = REASONING_LADDER.indexOf(hint.level);\n\t\tif (hintIndex >= 0) {\n\t\t\tconst delta = hintIndex - targetIndex;\n\t\t\tconst step = Math.max(-BIAS_MAX, Math.min(BIAS_MAX, delta));\n\t\t\ttargetIndex = clampToLadderIndex(targetIndex + step);\n\t\t}\n\t}\n\n\tif (escalationSteps > 0) {\n\t\ttargetIndex = clampToLadderIndex(targetIndex + escalationSteps);\n\t}\n\n\treturn clampToAvailable(targetIndex, availableLevels);\n}\n"]}
+{"version":3,"file":"reasoning-router-resolver.d.ts","sourceRoot":"","sources":["../../src/core/reasoning-router-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,mDAAmD;AACnD,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEnH,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElG,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAAkE,CAAC;AAExH,iIAAiI;AACjI,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAQ1F,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,SAAS,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAItE,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,QAAQ,IAAI,CAAC;AAC1B,2EAA2E;AAC3E,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAM7C;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,aAAa,EAAE,GAAG,aAAa,CAU9G;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACvC,SAAS,EAAE,kBAAkB,EAC7B,eAAe,EAAE,SAAS,aAAa,EAAE,EACzC,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EACzD,eAAe,EAAE,MAAM,GACrB,aAAa,CAoBf","sourcesContent":["/**\n * Shared resolver core for the v4 reasoning router: canonical task-class ->\n * ThinkingLevel rule table, lane-step adjustment, ladder-index clamping, and\n * bounded bias/hint/escalation resolution logic.\n *\n * Deterministic, side-effect-free: no clock, randomness, or I/O.\n */\n\nimport type { ThinkingLevel } from \"omk-agent-core\";\n\n/** The 7-class union used by the v4 classifier. */\nexport type ReasoningTaskClass = \"trivial\" | \"simple-edit\" | \"code-gen\" | \"debug\" | \"refactor\" | \"review\" | \"plan\";\n\n/** The 6-lane union used by the v4 classifier. */\nexport type ReasoningLane = \"planner\" | \"security\" | \"explorer\" | \"coder\" | \"reviewer\" | \"tester\";\n\n/** Reasoning ladder used for targets and clamping. Intentionally excludes \"off\". */\nexport const REASONING_LADDER: readonly ThinkingLevel[] = [\"minimal\", \"low\", \"medium\", \"high\", \"xhigh\", \"max\", \"ultra\"];\n\n/** Static rule table: task class -> recommended ThinkingLevel (before lane adjustment, bias, hint, escalation, and clamping). */\nexport const TASK_CLASS_THINKING_LEVELS: Readonly<Record<ReasoningTaskClass, ThinkingLevel>> = {\n\ttrivial: \"minimal\",\n\t\"simple-edit\": \"low\",\n\t\"code-gen\": \"medium\",\n\tdebug: \"high\",\n\trefactor: \"high\",\n\treview: \"high\",\n\tplan: \"xhigh\",\n};\n\n/** Lane adjustment in ladder steps: planner/security escalate, explorer de-escalates. */\nexport const LANE_STEP: Readonly<Partial<Record<ReasoningLane, 1 | -1>>> = {\n\tplanner: 1,\n\tsecurity: 1,\n\texplorer: -1,\n};\n\n/** Maximum magnitude of the learning/consult bias (ladder steps). */\nexport const BIAS_MAX = 2;\n/** Confidence floor at which an override hint is fused into the target. */\nexport const HINT_CONFIDENCE_THRESHOLD = 0.7;\n\nfunction clampToLadderIndex(index: number): number {\n\treturn Math.max(0, Math.min(index, REASONING_LADDER.length - 1));\n}\n\n/**\n * Clamp a target ladder index to capability: the highest level in\n * `availableLevels` that is <= the target; if no available level is at/below\n * the target, return the lowest available reasoning level. Never invents a\n * level outside `availableLevels`. `\"off\"` is only returned when\n * `availableLevels` is empty (callers are expected to bypass the router\n * entirely for models with `reasoning: false`).\n */\nexport function clampToAvailable(targetIndex: number, availableLevels: readonly ThinkingLevel[]): ThinkingLevel {\n\tconst availableOnLadder = REASONING_LADDER.filter((level) => availableLevels.includes(level));\n\tif (availableOnLadder.length === 0) {\n\t\treturn availableLevels[0] ?? \"off\";\n\t}\n\tfor (let i = targetIndex; i >= 0; i--) {\n\t\tconst candidate = REASONING_LADDER[i];\n\t\tif (availableOnLadder.includes(candidate)) return candidate;\n\t}\n\treturn availableOnLadder[0];\n}\n\n/**\n * Canonical resolver core for v4.\n *\n * Pipeline: base rule table -> lane step -> bounded bias [-BIAS_MAX,+BIAS_MAX]\n * -> optional hint fusion (bounded ±BIAS_MAX steps toward hint.level, only\n * when hint.confidence >= HINT_CONFIDENCE_THRESHOLD) -> non-negative\n * escalationSteps bump -> clamp to availableLevels.\n */\nexport function resolveThinkingLevelCore(\n\ttaskClass: ReasoningTaskClass,\n\tavailableLevels: readonly ThinkingLevel[],\n\tlaneType: ReasoningLane | undefined,\n\tbias: number,\n\thint: { level: ThinkingLevel; confidence: number } | null,\n\tescalationSteps: number,\n): ThinkingLevel {\n\tconst baseIndex = REASONING_LADDER.indexOf(TASK_CLASS_THINKING_LEVELS[taskClass]);\n\tconst laneStep = laneType ? (LANE_STEP[laneType] ?? 0) : 0;\n\tconst biasClamped = Math.max(-BIAS_MAX, Math.min(BIAS_MAX, bias));\n\tlet targetIndex = clampToLadderIndex(baseIndex + laneStep + biasClamped);\n\n\tif (hint !== null && hint.confidence >= HINT_CONFIDENCE_THRESHOLD) {\n\t\tconst hintIndex = REASONING_LADDER.indexOf(hint.level);\n\t\tif (hintIndex >= 0) {\n\t\t\tconst delta = hintIndex - targetIndex;\n\t\t\tconst step = Math.max(-BIAS_MAX, Math.min(BIAS_MAX, delta));\n\t\t\ttargetIndex = clampToLadderIndex(targetIndex + step);\n\t\t}\n\t}\n\n\tif (escalationSteps > 0) {\n\t\ttargetIndex = clampToLadderIndex(targetIndex + escalationSteps);\n\t}\n\n\treturn clampToAvailable(targetIndex, availableLevels);\n}\n"]}

package/dist/core/reasoning-router-resolver.js

@@ -6,7 +6,7 @@
  * Deterministic, side-effect-free: no clock, randomness, or I/O.
  */
 /** Reasoning ladder used for targets and clamping. Intentionally excludes "off". */
-export const REASONING_LADDER = ["minimal", "low", "medium", "high", "xhigh", "max"];
+export const REASONING_LADDER = ["minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
 /** Static rule table: task class -> recommended ThinkingLevel (before lane adjustment, bias, hint, escalation, and clamping). */
 export const TASK_CLASS_THINKING_LEVELS = {
     trivial: "minimal",

package/dist/core/reasoning-router-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"reasoning-router-resolver.js","sourceRoot":"","sources":["../../src/core/reasoning-router-resolver.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared resolver core for the v4 reasoning router: canonical task-class ->\n * ThinkingLevel rule table, lane-step adjustment, ladder-index clamping, and\n * bounded bias/hint/escalation resolution logic.\n *\n * Deterministic, side-effect-free: no clock, randomness, or I/O.\n */\n\nimport type { ThinkingLevel } from \"omk-agent-core\";\n\n/** The 7-class union used by the v4 classifier. */\nexport type ReasoningTaskClass = \"trivial\" | \"simple-edit\" | \"code-gen\" | \"debug\" | \"refactor\" | \"review\" | \"plan\";\n\n/** The 6-lane union used by the v4 classifier. */\nexport type ReasoningLane = \"planner\" | \"security\" | \"explorer\" | \"coder\" | \"reviewer\" | \"tester\";\n\n/** Reasoning ladder used for targets and clamping. Intentionally excludes \"off\". */\nexport const REASONING_LADDER: readonly ThinkingLevel[] = [\"minimal\", \"low\", \"medium\", \"high\", \"xhigh\", \"max\"];\n\n/** Static rule table: task class -> recommended ThinkingLevel (before lane adjustment, bias, hint, escalation, and clamping). */\nexport const TASK_CLASS_THINKING_LEVELS: Readonly<Record<ReasoningTaskClass, ThinkingLevel>> = {\n\ttrivial: \"minimal\",\n\t\"simple-edit\": \"low\",\n\t\"code-gen\": \"medium\",\n\tdebug: \"high\",\n\trefactor: \"high\",\n\treview: \"high\",\n\tplan: \"xhigh\",\n};\n\n/** Lane adjustment in ladder steps: planner/security escalate, explorer de-escalates. */\nexport const LANE_STEP: Readonly<Partial<Record<ReasoningLane, 1 | -1>>> = {\n\tplanner: 1,\n\tsecurity: 1,\n\texplorer: -1,\n};\n\n/** Maximum magnitude of the learning/consult bias (ladder steps). */\nexport const BIAS_MAX = 2;\n/** Confidence floor at which an override hint is fused into the target. */\nexport const HINT_CONFIDENCE_THRESHOLD = 0.7;\n\nfunction clampToLadderIndex(index: number): number {\n\treturn Math.max(0, Math.min(index, REASONING_LADDER.length - 1));\n}\n\n/**\n * Clamp a target ladder index to capability: the highest level in\n * `availableLevels` that is <= the target; if no available level is at/below\n * the target, return the lowest available reasoning level. Never invents a\n * level outside `availableLevels`. `\"off\"` is only returned when\n * `availableLevels` is empty (callers are expected to bypass the router\n * entirely for models with `reasoning: false`).\n */\nexport function clampToAvailable(targetIndex: number, availableLevels: readonly ThinkingLevel[]): ThinkingLevel {\n\tconst availableOnLadder = REASONING_LADDER.filter((level) => availableLevels.includes(level));\n\tif (availableOnLadder.length === 0) {\n\t\treturn availableLevels[0] ?? \"off\";\n\t}\n\tfor (let i = targetIndex; i >= 0; i--) {\n\t\tconst candidate = REASONING_LADDER[i];\n\t\tif (availableOnLadder.includes(candidate)) return candidate;\n\t}\n\treturn availableOnLadder[0];\n}\n\n/**\n * Canonical resolver core for v4.\n *\n * Pipeline: base rule table -> lane step -> bounded bias [-BIAS_MAX,+BIAS_MAX]\n * -> optional hint fusion (bounded ±BIAS_MAX steps toward hint.level, only\n * when hint.confidence >= HINT_CONFIDENCE_THRESHOLD) -> non-negative\n * escalationSteps bump -> clamp to availableLevels.\n */\nexport function resolveThinkingLevelCore(\n\ttaskClass: ReasoningTaskClass,\n\tavailableLevels: readonly ThinkingLevel[],\n\tlaneType: ReasoningLane | undefined,\n\tbias: number,\n\thint: { level: ThinkingLevel; confidence: number } | null,\n\tescalationSteps: number,\n): ThinkingLevel {\n\tconst baseIndex = REASONING_LADDER.indexOf(TASK_CLASS_THINKING_LEVELS[taskClass]);\n\tconst laneStep = laneType ? (LANE_STEP[laneType] ?? 0) : 0;\n\tconst biasClamped = Math.max(-BIAS_MAX, Math.min(BIAS_MAX, bias));\n\tlet targetIndex = clampToLadderIndex(baseIndex + laneStep + biasClamped);\n\n\tif (hint !== null && hint.confidence >= HINT_CONFIDENCE_THRESHOLD) {\n\t\tconst hintIndex = REASONING_LADDER.indexOf(hint.level);\n\t\tif (hintIndex >= 0) {\n\t\t\tconst delta = hintIndex - targetIndex;\n\t\t\tconst step = Math.max(-BIAS_MAX, Math.min(BIAS_MAX, delta));\n\t\t\ttargetIndex = clampToLadderIndex(targetIndex + step);\n\t\t}\n\t}\n\n\tif (escalationSteps > 0) {\n\t\ttargetIndex = clampToLadderIndex(targetIndex + escalationSteps);\n\t}\n\n\treturn clampToAvailable(targetIndex, availableLevels);\n}\n"]}
+{"version":3,"file":"reasoning-router-resolver.js","sourceRoot":"","sources":["../../src/core/reasoning-router-resolver.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared resolver core for the v4 reasoning router: canonical task-class ->\n * ThinkingLevel rule table, lane-step adjustment, ladder-index clamping, and\n * bounded bias/hint/escalation resolution logic.\n *\n * Deterministic, side-effect-free: no clock, randomness, or I/O.\n */\n\nimport type { ThinkingLevel } from \"omk-agent-core\";\n\n/** The 7-class union used by the v4 classifier. */\nexport type ReasoningTaskClass = \"trivial\" | \"simple-edit\" | \"code-gen\" | \"debug\" | \"refactor\" | \"review\" | \"plan\";\n\n/** The 6-lane union used by the v4 classifier. */\nexport type ReasoningLane = \"planner\" | \"security\" | \"explorer\" | \"coder\" | \"reviewer\" | \"tester\";\n\n/** Reasoning ladder used for targets and clamping. Intentionally excludes \"off\". */\nexport const REASONING_LADDER: readonly ThinkingLevel[] = [\"minimal\", \"low\", \"medium\", \"high\", \"xhigh\", \"max\", \"ultra\"];\n\n/** Static rule table: task class -> recommended ThinkingLevel (before lane adjustment, bias, hint, escalation, and clamping). */\nexport const TASK_CLASS_THINKING_LEVELS: Readonly<Record<ReasoningTaskClass, ThinkingLevel>> = {\n\ttrivial: \"minimal\",\n\t\"simple-edit\": \"low\",\n\t\"code-gen\": \"medium\",\n\tdebug: \"high\",\n\trefactor: \"high\",\n\treview: \"high\",\n\tplan: \"xhigh\",\n};\n\n/** Lane adjustment in ladder steps: planner/security escalate, explorer de-escalates. */\nexport const LANE_STEP: Readonly<Partial<Record<ReasoningLane, 1 | -1>>> = {\n\tplanner: 1,\n\tsecurity: 1,\n\texplorer: -1,\n};\n\n/** Maximum magnitude of the learning/consult bias (ladder steps). */\nexport const BIAS_MAX = 2;\n/** Confidence floor at which an override hint is fused into the target. */\nexport const HINT_CONFIDENCE_THRESHOLD = 0.7;\n\nfunction clampToLadderIndex(index: number): number {\n\treturn Math.max(0, Math.min(index, REASONING_LADDER.length - 1));\n}\n\n/**\n * Clamp a target ladder index to capability: the highest level in\n * `availableLevels` that is <= the target; if no available level is at/below\n * the target, return the lowest available reasoning level. Never invents a\n * level outside `availableLevels`. `\"off\"` is only returned when\n * `availableLevels` is empty (callers are expected to bypass the router\n * entirely for models with `reasoning: false`).\n */\nexport function clampToAvailable(targetIndex: number, availableLevels: readonly ThinkingLevel[]): ThinkingLevel {\n\tconst availableOnLadder = REASONING_LADDER.filter((level) => availableLevels.includes(level));\n\tif (availableOnLadder.length === 0) {\n\t\treturn availableLevels[0] ?? \"off\";\n\t}\n\tfor (let i = targetIndex; i >= 0; i--) {\n\t\tconst candidate = REASONING_LADDER[i];\n\t\tif (availableOnLadder.includes(candidate)) return candidate;\n\t}\n\treturn availableOnLadder[0];\n}\n\n/**\n * Canonical resolver core for v4.\n *\n * Pipeline: base rule table -> lane step -> bounded bias [-BIAS_MAX,+BIAS_MAX]\n * -> optional hint fusion (bounded ±BIAS_MAX steps toward hint.level, only\n * when hint.confidence >= HINT_CONFIDENCE_THRESHOLD) -> non-negative\n * escalationSteps bump -> clamp to availableLevels.\n */\nexport function resolveThinkingLevelCore(\n\ttaskClass: ReasoningTaskClass,\n\tavailableLevels: readonly ThinkingLevel[],\n\tlaneType: ReasoningLane | undefined,\n\tbias: number,\n\thint: { level: ThinkingLevel; confidence: number } | null,\n\tescalationSteps: number,\n): ThinkingLevel {\n\tconst baseIndex = REASONING_LADDER.indexOf(TASK_CLASS_THINKING_LEVELS[taskClass]);\n\tconst laneStep = laneType ? (LANE_STEP[laneType] ?? 0) : 0;\n\tconst biasClamped = Math.max(-BIAS_MAX, Math.min(BIAS_MAX, bias));\n\tlet targetIndex = clampToLadderIndex(baseIndex + laneStep + biasClamped);\n\n\tif (hint !== null && hint.confidence >= HINT_CONFIDENCE_THRESHOLD) {\n\t\tconst hintIndex = REASONING_LADDER.indexOf(hint.level);\n\t\tif (hintIndex >= 0) {\n\t\t\tconst delta = hintIndex - targetIndex;\n\t\t\tconst step = Math.max(-BIAS_MAX, Math.min(BIAS_MAX, delta));\n\t\t\ttargetIndex = clampToLadderIndex(targetIndex + step);\n\t\t}\n\t}\n\n\tif (escalationSteps > 0) {\n\t\ttargetIndex = clampToLadderIndex(targetIndex + escalationSteps);\n\t}\n\n\treturn clampToAvailable(targetIndex, availableLevels);\n}\n"]}

package/dist/core/resource-admission-config.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Governor rollout mode (§7.4). Mode enforcement (probe/record/cap wiring)
+ * lands in later milestones; the type is part of the layer-1 contract.
+ */
+export type ResourceGovernorMode = "off" | "observe" | "adaptive" | "strict";
+export interface ResourceAdmissionThresholds {
+    readonly constrainedAvailableMemoryMiB: number;
+    readonly criticalAvailableMemoryMiB: number;
+    readonly constrainedDiskFreeMiB: number;
+    readonly criticalDiskFreeMiB: number;
+    readonly constrainedHeapRatio: number;
+    readonly criticalHeapRatio: number;
+    readonly busyCpuPercent: number;
+}
+export interface ResourcePressureCaps {
+    readonly maxToolConcurrency: number;
+    readonly maxParallelLanes: number;
+    readonly maxHeavyProcesses: number;
+}
+export interface ResourceAdmissionCapTable {
+    readonly normal: ResourcePressureCaps;
+    readonly constrained: ResourcePressureCaps;
+    readonly critical: ResourcePressureCaps;
+}
+export interface ResourceAdmissionConfig {
+    readonly thresholds: ResourceAdmissionThresholds;
+    readonly caps: ResourceAdmissionCapTable;
+}
+/** §6.7 default thresholds. */
+export declare const DEFAULT_RESOURCE_ADMISSION_THRESHOLDS: ResourceAdmissionThresholds;
+/** §7.2 default caps per pressure tier. */
+export declare const DEFAULT_RESOURCE_ADMISSION_CAP_TABLE: ResourceAdmissionCapTable;
+export declare const DEFAULT_RESOURCE_ADMISSION_CONFIG: ResourceAdmissionConfig;
+export type ResourceAdmissionConfigOverrides = {
+    thresholds?: Partial<ResourceAdmissionThresholds>;
+    caps?: {
+        normal?: Partial<ResourcePressureCaps>;
+        constrained?: Partial<ResourcePressureCaps>;
+        critical?: Partial<ResourcePressureCaps>;
+    };
+};
+export interface ResolvedResourceAdmissionConfig {
+    readonly config: ResourceAdmissionConfig;
+    /** §18.1: explicit errors over silent clamps. Non-empty means fail-closed defaults were applied. */
+    readonly errors: readonly string[];
+}
+/**
+ * Validate overrides against §18.1 and merge them over the defaults.
+ * Any validation error fails closed: the full default config is returned
+ * together with the explicit error list (startup diagnostics are the
+ * caller's responsibility in later slices).
+ */
+export declare function resolveResourceAdmissionConfig(overrides?: ResourceAdmissionConfigOverrides): ResolvedResourceAdmissionConfig;
+export declare function validateResourceAdmissionConfig(config: ResourceAdmissionConfig): readonly string[];
+//# sourceMappingURL=resource-admission-config.d.ts.map

package/dist/core/resource-admission-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-admission-config.d.ts","sourceRoot":"","sources":["../../src/core/resource-admission-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE7E,MAAM,WAAW,2BAA2B;IAC3C,QAAQ,CAAC,6BAA6B,EAAE,MAAM,CAAC;IAC/C,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;IAC5C,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;CACxC;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,UAAU,EAAE,2BAA2B,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;CACzC;AAED,gCAA+B;AAC/B,eAAO,MAAM,qCAAqC,EAAE,2BAQnD,CAAC;AAEF,4CAA2C;AAC3C,eAAO,MAAM,oCAAoC,EAAE,yBAIlD,CAAC;AAEF,eAAO,MAAM,iCAAiC,EAAE,uBAG/C,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG;IAC9C,UAAU,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAClD,IAAI,CAAC,EAAE;QACN,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;QACvC,WAAW,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;QAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;KACzC,CAAC;CACF,CAAC;AAEF,MAAM,WAAW,+BAA+B;IAC/C,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,qGAAoG;IACpG,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAKD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC7C,SAAS,CAAC,EAAE,gCAAgC,GAC1C,+BAA+B,CAcjC;AAED,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,uBAAuB,GAAG,SAAS,MAAM,EAAE,CA0DlG","sourcesContent":["/**\n * Governor rollout mode (§7.4). Mode enforcement (probe/record/cap wiring)\n * lands in later milestones; the type is part of the layer-1 contract.\n */\nexport type ResourceGovernorMode = \"off\" | \"observe\" | \"adaptive\" | \"strict\";\n\nexport interface ResourceAdmissionThresholds {\n\treadonly constrainedAvailableMemoryMiB: number;\n\treadonly criticalAvailableMemoryMiB: number;\n\treadonly constrainedDiskFreeMiB: number;\n\treadonly criticalDiskFreeMiB: number;\n\treadonly constrainedHeapRatio: number;\n\treadonly criticalHeapRatio: number;\n\treadonly busyCpuPercent: number;\n}\n\nexport interface ResourcePressureCaps {\n\treadonly maxToolConcurrency: number;\n\treadonly maxParallelLanes: number;\n\treadonly maxHeavyProcesses: number;\n}\n\nexport interface ResourceAdmissionCapTable {\n\treadonly normal: ResourcePressureCaps;\n\treadonly constrained: ResourcePressureCaps;\n\treadonly critical: ResourcePressureCaps;\n}\n\nexport interface ResourceAdmissionConfig {\n\treadonly thresholds: ResourceAdmissionThresholds;\n\treadonly caps: ResourceAdmissionCapTable;\n}\n\n/** §6.7 default thresholds. */\nexport const DEFAULT_RESOURCE_ADMISSION_THRESHOLDS: ResourceAdmissionThresholds = {\n\tconstrainedAvailableMemoryMiB: 1536,\n\tcriticalAvailableMemoryMiB: 512,\n\tconstrainedDiskFreeMiB: 4096,\n\tcriticalDiskFreeMiB: 1024,\n\tconstrainedHeapRatio: 0.75,\n\tcriticalHeapRatio: 0.85,\n\tbusyCpuPercent: 85,\n};\n\n/** §7.2 default caps per pressure tier. */\nexport const DEFAULT_RESOURCE_ADMISSION_CAP_TABLE: ResourceAdmissionCapTable = {\n\tnormal: { maxToolConcurrency: 4, maxParallelLanes: 4, maxHeavyProcesses: 2 },\n\tconstrained: { maxToolConcurrency: 2, maxParallelLanes: 2, maxHeavyProcesses: 1 },\n\tcritical: { maxToolConcurrency: 1, maxParallelLanes: 1, maxHeavyProcesses: 1 },\n};\n\nexport const DEFAULT_RESOURCE_ADMISSION_CONFIG: ResourceAdmissionConfig = {\n\tthresholds: DEFAULT_RESOURCE_ADMISSION_THRESHOLDS,\n\tcaps: DEFAULT_RESOURCE_ADMISSION_CAP_TABLE,\n};\n\nexport type ResourceAdmissionConfigOverrides = {\n\tthresholds?: Partial<ResourceAdmissionThresholds>;\n\tcaps?: {\n\t\tnormal?: Partial<ResourcePressureCaps>;\n\t\tconstrained?: Partial<ResourcePressureCaps>;\n\t\tcritical?: Partial<ResourcePressureCaps>;\n\t};\n};\n\nexport interface ResolvedResourceAdmissionConfig {\n\treadonly config: ResourceAdmissionConfig;\n\t/** §18.1: explicit errors over silent clamps. Non-empty means fail-closed defaults were applied. */\n\treadonly errors: readonly string[];\n}\n\nconst MIN_CAP = 1;\nconst MAX_CAP = 64;\n\n/**\n * Validate overrides against §18.1 and merge them over the defaults.\n * Any validation error fails closed: the full default config is returned\n * together with the explicit error list (startup diagnostics are the\n * caller's responsibility in later slices).\n */\nexport function resolveResourceAdmissionConfig(\n\toverrides?: ResourceAdmissionConfigOverrides,\n): ResolvedResourceAdmissionConfig {\n\tconst merged: ResourceAdmissionConfig = {\n\t\tthresholds: { ...DEFAULT_RESOURCE_ADMISSION_THRESHOLDS, ...overrides?.thresholds },\n\t\tcaps: {\n\t\t\tnormal: { ...DEFAULT_RESOURCE_ADMISSION_CAP_TABLE.normal, ...overrides?.caps?.normal },\n\t\t\tconstrained: { ...DEFAULT_RESOURCE_ADMISSION_CAP_TABLE.constrained, ...overrides?.caps?.constrained },\n\t\t\tcritical: { ...DEFAULT_RESOURCE_ADMISSION_CAP_TABLE.critical, ...overrides?.caps?.critical },\n\t\t},\n\t};\n\tconst errors = validateResourceAdmissionConfig(merged);\n\tif (errors.length > 0) {\n\t\treturn { config: DEFAULT_RESOURCE_ADMISSION_CONFIG, errors };\n\t}\n\treturn { config: merged, errors };\n}\n\nexport function validateResourceAdmissionConfig(config: ResourceAdmissionConfig): readonly string[] {\n\tconst errors: string[] = [];\n\tconst { thresholds, caps } = config;\n\n\tconst positiveMiB: ReadonlyArray<readonly [string, number]> = [\n\t\t[\"constrainedAvailableMemoryMiB\", thresholds.constrainedAvailableMemoryMiB],\n\t\t[\"criticalAvailableMemoryMiB\", thresholds.criticalAvailableMemoryMiB],\n\t\t[\"constrainedDiskFreeMiB\", thresholds.constrainedDiskFreeMiB],\n\t\t[\"criticalDiskFreeMiB\", thresholds.criticalDiskFreeMiB],\n\t];\n\tfor (const [name, value] of positiveMiB) {\n\t\tif (!Number.isSafeInteger(value) || value <= 0) {\n\t\t\terrors.push(`resourceGovernor.${name}: must be a positive safe integer, got ${String(value)}`);\n\t\t}\n\t}\n\tif (thresholds.criticalAvailableMemoryMiB > thresholds.constrainedAvailableMemoryMiB) {\n\t\terrors.push(\"resourceGovernor.criticalAvailableMemoryMiB: must be <= constrainedAvailableMemoryMiB\");\n\t}\n\tif (thresholds.criticalDiskFreeMiB > thresholds.constrainedDiskFreeMiB) {\n\t\terrors.push(\"resourceGovernor.criticalDiskFreeMiB: must be <= constrainedDiskFreeMiB\");\n\t}\n\tfor (const [name, value] of [\n\t\t[\"constrainedHeapRatio\", thresholds.constrainedHeapRatio],\n\t\t[\"criticalHeapRatio\", thresholds.criticalHeapRatio],\n\t] as const) {\n\t\tif (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0 || value > 1) {\n\t\t\terrors.push(`resourceGovernor.${name}: must be within (0, 1], got ${String(value)}`);\n\t\t}\n\t}\n\tif (thresholds.criticalHeapRatio < thresholds.constrainedHeapRatio) {\n\t\terrors.push(\"resourceGovernor.criticalHeapRatio: must be >= constrainedHeapRatio\");\n\t}\n\tif (\n\t\t!Number.isFinite(thresholds.busyCpuPercent) ||\n\t\tthresholds.busyCpuPercent < 1 ||\n\t\tthresholds.busyCpuPercent > 100\n\t) {\n\t\terrors.push(`resourceGovernor.busyCpuPercent: must be within [1, 100], got ${String(thresholds.busyCpuPercent)}`);\n\t}\n\n\tconst capFields = [\"maxToolConcurrency\", \"maxParallelLanes\", \"maxHeavyProcesses\"] as const;\n\tfor (const tier of [\"normal\", \"constrained\", \"critical\"] as const) {\n\t\tfor (const field of capFields) {\n\t\t\tconst value = caps[tier][field];\n\t\t\tif (!Number.isSafeInteger(value) || value < MIN_CAP || value > MAX_CAP) {\n\t\t\t\terrors.push(\n\t\t\t\t\t`resourceGovernor.caps.${tier}.${field}: must be an integer within [${MIN_CAP}, ${MAX_CAP}], got ${String(value)}`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\t// §4.4 / §18.1 monotonicity: normalCap >= constrainedCap >= criticalCap.\n\tfor (const field of capFields) {\n\t\tif (caps.normal[field] < caps.constrained[field] || caps.constrained[field] < caps.critical[field]) {\n\t\t\terrors.push(`resourceGovernor.caps.${field}: requires normal >= constrained >= critical`);\n\t\t}\n\t}\n\treturn errors;\n}\n"]}

package/dist/core/resource-admission-config.js

@@ -0,0 +1,97 @@
+/** §6.7 default thresholds. */
+export const DEFAULT_RESOURCE_ADMISSION_THRESHOLDS = {
+    constrainedAvailableMemoryMiB: 1536,
+    criticalAvailableMemoryMiB: 512,
+    constrainedDiskFreeMiB: 4096,
+    criticalDiskFreeMiB: 1024,
+    constrainedHeapRatio: 0.75,
+    criticalHeapRatio: 0.85,
+    busyCpuPercent: 85,
+};
+/** §7.2 default caps per pressure tier. */
+export const DEFAULT_RESOURCE_ADMISSION_CAP_TABLE = {
+    normal: { maxToolConcurrency: 4, maxParallelLanes: 4, maxHeavyProcesses: 2 },
+    constrained: { maxToolConcurrency: 2, maxParallelLanes: 2, maxHeavyProcesses: 1 },
+    critical: { maxToolConcurrency: 1, maxParallelLanes: 1, maxHeavyProcesses: 1 },
+};
+export const DEFAULT_RESOURCE_ADMISSION_CONFIG = {
+    thresholds: DEFAULT_RESOURCE_ADMISSION_THRESHOLDS,
+    caps: DEFAULT_RESOURCE_ADMISSION_CAP_TABLE,
+};
+const MIN_CAP = 1;
+const MAX_CAP = 64;
+/**
+ * Validate overrides against §18.1 and merge them over the defaults.
+ * Any validation error fails closed: the full default config is returned
+ * together with the explicit error list (startup diagnostics are the
+ * caller's responsibility in later slices).
+ */
+export function resolveResourceAdmissionConfig(overrides) {
+    const merged = {
+        thresholds: { ...DEFAULT_RESOURCE_ADMISSION_THRESHOLDS, ...overrides?.thresholds },
+        caps: {
+            normal: { ...DEFAULT_RESOURCE_ADMISSION_CAP_TABLE.normal, ...overrides?.caps?.normal },
+            constrained: { ...DEFAULT_RESOURCE_ADMISSION_CAP_TABLE.constrained, ...overrides?.caps?.constrained },
+            critical: { ...DEFAULT_RESOURCE_ADMISSION_CAP_TABLE.critical, ...overrides?.caps?.critical },
+        },
+    };
+    const errors = validateResourceAdmissionConfig(merged);
+    if (errors.length > 0) {
+        return { config: DEFAULT_RESOURCE_ADMISSION_CONFIG, errors };
+    }
+    return { config: merged, errors };
+}
+export function validateResourceAdmissionConfig(config) {
+    const errors = [];
+    const { thresholds, caps } = config;
+    const positiveMiB = [
+        ["constrainedAvailableMemoryMiB", thresholds.constrainedAvailableMemoryMiB],
+        ["criticalAvailableMemoryMiB", thresholds.criticalAvailableMemoryMiB],
+        ["constrainedDiskFreeMiB", thresholds.constrainedDiskFreeMiB],
+        ["criticalDiskFreeMiB", thresholds.criticalDiskFreeMiB],
+    ];
+    for (const [name, value] of positiveMiB) {
+        if (!Number.isSafeInteger(value) || value <= 0) {
+            errors.push(`resourceGovernor.${name}: must be a positive safe integer, got ${String(value)}`);
+        }
+    }
+    if (thresholds.criticalAvailableMemoryMiB > thresholds.constrainedAvailableMemoryMiB) {
+        errors.push("resourceGovernor.criticalAvailableMemoryMiB: must be <= constrainedAvailableMemoryMiB");
+    }
+    if (thresholds.criticalDiskFreeMiB > thresholds.constrainedDiskFreeMiB) {
+        errors.push("resourceGovernor.criticalDiskFreeMiB: must be <= constrainedDiskFreeMiB");
+    }
+    for (const [name, value] of [
+        ["constrainedHeapRatio", thresholds.constrainedHeapRatio],
+        ["criticalHeapRatio", thresholds.criticalHeapRatio],
+    ]) {
+        if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > 1) {
+            errors.push(`resourceGovernor.${name}: must be within (0, 1], got ${String(value)}`);
+        }
+    }
+    if (thresholds.criticalHeapRatio < thresholds.constrainedHeapRatio) {
+        errors.push("resourceGovernor.criticalHeapRatio: must be >= constrainedHeapRatio");
+    }
+    if (!Number.isFinite(thresholds.busyCpuPercent) ||
+        thresholds.busyCpuPercent < 1 ||
+        thresholds.busyCpuPercent > 100) {
+        errors.push(`resourceGovernor.busyCpuPercent: must be within [1, 100], got ${String(thresholds.busyCpuPercent)}`);
+    }
+    const capFields = ["maxToolConcurrency", "maxParallelLanes", "maxHeavyProcesses"];
+    for (const tier of ["normal", "constrained", "critical"]) {
+        for (const field of capFields) {
+            const value = caps[tier][field];
+            if (!Number.isSafeInteger(value) || value < MIN_CAP || value > MAX_CAP) {
+                errors.push(`resourceGovernor.caps.${tier}.${field}: must be an integer within [${MIN_CAP}, ${MAX_CAP}], got ${String(value)}`);
+            }
+        }
+    }
+    // §4.4 / §18.1 monotonicity: normalCap >= constrainedCap >= criticalCap.
+    for (const field of capFields) {
+        if (caps.normal[field] < caps.constrained[field] || caps.constrained[field] < caps.critical[field]) {
+            errors.push(`resourceGovernor.caps.${field}: requires normal >= constrained >= critical`);
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=resource-admission-config.js.map

package/dist/core/resource-admission-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-admission-config.js","sourceRoot":"","sources":["../../src/core/resource-admission-config.ts"],"names":[],"mappings":"AAiCA,gCAA+B;AAC/B,MAAM,CAAC,MAAM,qCAAqC,GAAgC;IACjF,6BAA6B,EAAE,IAAI;IACnC,0BAA0B,EAAE,GAAG;IAC/B,sBAAsB,EAAE,IAAI;IAC5B,mBAAmB,EAAE,IAAI;IACzB,oBAAoB,EAAE,IAAI;IAC1B,iBAAiB,EAAE,IAAI;IACvB,cAAc,EAAE,EAAE;CAClB,CAAC;AAEF,4CAA2C;AAC3C,MAAM,CAAC,MAAM,oCAAoC,GAA8B;IAC9E,MAAM,EAAE,EAAE,kBAAkB,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE;IAC5E,WAAW,EAAE,EAAE,kBAAkB,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE;IACjF,QAAQ,EAAE,EAAE,kBAAkB,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE;CAC9E,CAAC;AAEF,MAAM,CAAC,MAAM,iCAAiC,GAA4B;IACzE,UAAU,EAAE,qCAAqC;IACjD,IAAI,EAAE,oCAAoC;CAC1C,CAAC;AAiBF,MAAM,OAAO,GAAG,CAAC,CAAC;AAClB,MAAM,OAAO,GAAG,EAAE,CAAC;AAEnB;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B,CAC7C,SAA4C,EACV;IAClC,MAAM,MAAM,GAA4B;QACvC,UAAU,EAAE,EAAE,GAAG,qCAAqC,EAAE,GAAG,SAAS,EAAE,UAAU,EAAE;QAClF,IAAI,EAAE;YACL,MAAM,EAAE,EAAE,GAAG,oCAAoC,CAAC,MAAM,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE;YACtF,WAAW,EAAE,EAAE,GAAG,oCAAoC,CAAC,WAAW,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE;YACrG,QAAQ,EAAE,EAAE,GAAG,oCAAoC,CAAC,QAAQ,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE;SAC5F;KACD,CAAC;IACF,MAAM,MAAM,GAAG,+BAA+B,CAAC,MAAM,CAAC,CAAC;IACvD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,iCAAiC,EAAE,MAAM,EAAE,CAAC;IAC9D,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAAA,CAClC;AAED,MAAM,UAAU,+BAA+B,CAAC,MAA+B,EAAqB;IACnG,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;IAEpC,MAAM,WAAW,GAA6C;QAC7D,CAAC,+BAA+B,EAAE,UAAU,CAAC,6BAA6B,CAAC;QAC3E,CAAC,4BAA4B,EAAE,UAAU,CAAC,0BAA0B,CAAC;QACrE,CAAC,wBAAwB,EAAE,UAAU,CAAC,sBAAsB,CAAC;QAC7D,CAAC,qBAAqB,EAAE,UAAU,CAAC,mBAAmB,CAAC;KACvD,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC;QACzC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YAChD,MAAM,CAAC,IAAI,CAAC,oBAAoB,IAAI,0CAA0C,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAChG,CAAC;IACF,CAAC;IACD,IAAI,UAAU,CAAC,0BAA0B,GAAG,UAAU,CAAC,6BAA6B,EAAE,CAAC;QACtF,MAAM,CAAC,IAAI,CAAC,uFAAuF,CAAC,CAAC;IACtG,CAAC;IACD,IAAI,UAAU,CAAC,mBAAmB,GAAG,UAAU,CAAC,sBAAsB,EAAE,CAAC;QACxE,MAAM,CAAC,IAAI,CAAC,yEAAyE,CAAC,CAAC;IACxF,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI;QAC3B,CAAC,sBAAsB,EAAE,UAAU,CAAC,oBAAoB,CAAC;QACzD,CAAC,mBAAmB,EAAE,UAAU,CAAC,iBAAiB,CAAC;KAC1C,EAAE,CAAC;QACZ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACrF,MAAM,CAAC,IAAI,CAAC,oBAAoB,IAAI,gCAAgC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtF,CAAC;IACF,CAAC;IACD,IAAI,UAAU,CAAC,iBAAiB,GAAG,UAAU,CAAC,oBAAoB,EAAE,CAAC;QACpE,MAAM,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;IACpF,CAAC;IACD,IACC,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,cAAc,CAAC;QAC3C,UAAU,CAAC,cAAc,GAAG,CAAC;QAC7B,UAAU,CAAC,cAAc,GAAG,GAAG,EAC9B,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,iEAAiE,MAAM,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;IACnH,CAAC;IAED,MAAM,SAAS,GAAG,CAAC,oBAAoB,EAAE,kBAAkB,EAAE,mBAAmB,CAAU,CAAC;IAC3F,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,UAAU,CAAU,EAAE,CAAC;QACnE,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;YAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC;YAChC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,OAAO,IAAI,KAAK,GAAG,OAAO,EAAE,CAAC;gBACxE,MAAM,CAAC,IAAI,CACV,yBAAyB,IAAI,IAAI,KAAK,gCAAgC,OAAO,KAAK,OAAO,UAAU,MAAM,CAAC,KAAK,CAAC,EAAE,CAClH,CAAC;YACH,CAAC;QACF,CAAC;IACF,CAAC;IACD,2EAAyE;IACzE,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;QAC/B,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACpG,MAAM,CAAC,IAAI,CAAC,yBAAyB,KAAK,8CAA8C,CAAC,CAAC;QAC3F,CAAC;IACF,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACd","sourcesContent":["/**\n * Governor rollout mode (§7.4). Mode enforcement (probe/record/cap wiring)\n * lands in later milestones; the type is part of the layer-1 contract.\n */\nexport type ResourceGovernorMode = \"off\" | \"observe\" | \"adaptive\" | \"strict\";\n\nexport interface ResourceAdmissionThresholds {\n\treadonly constrainedAvailableMemoryMiB: number;\n\treadonly criticalAvailableMemoryMiB: number;\n\treadonly constrainedDiskFreeMiB: number;\n\treadonly criticalDiskFreeMiB: number;\n\treadonly constrainedHeapRatio: number;\n\treadonly criticalHeapRatio: number;\n\treadonly busyCpuPercent: number;\n}\n\nexport interface ResourcePressureCaps {\n\treadonly maxToolConcurrency: number;\n\treadonly maxParallelLanes: number;\n\treadonly maxHeavyProcesses: number;\n}\n\nexport interface ResourceAdmissionCapTable {\n\treadonly normal: ResourcePressureCaps;\n\treadonly constrained: ResourcePressureCaps;\n\treadonly critical: ResourcePressureCaps;\n}\n\nexport interface ResourceAdmissionConfig {\n\treadonly thresholds: ResourceAdmissionThresholds;\n\treadonly caps: ResourceAdmissionCapTable;\n}\n\n/** §6.7 default thresholds. */\nexport const DEFAULT_RESOURCE_ADMISSION_THRESHOLDS: ResourceAdmissionThresholds = {\n\tconstrainedAvailableMemoryMiB: 1536,\n\tcriticalAvailableMemoryMiB: 512,\n\tconstrainedDiskFreeMiB: 4096,\n\tcriticalDiskFreeMiB: 1024,\n\tconstrainedHeapRatio: 0.75,\n\tcriticalHeapRatio: 0.85,\n\tbusyCpuPercent: 85,\n};\n\n/** §7.2 default caps per pressure tier. */\nexport const DEFAULT_RESOURCE_ADMISSION_CAP_TABLE: ResourceAdmissionCapTable = {\n\tnormal: { maxToolConcurrency: 4, maxParallelLanes: 4, maxHeavyProcesses: 2 },\n\tconstrained: { maxToolConcurrency: 2, maxParallelLanes: 2, maxHeavyProcesses: 1 },\n\tcritical: { maxToolConcurrency: 1, maxParallelLanes: 1, maxHeavyProcesses: 1 },\n};\n\nexport const DEFAULT_RESOURCE_ADMISSION_CONFIG: ResourceAdmissionConfig = {\n\tthresholds: DEFAULT_RESOURCE_ADMISSION_THRESHOLDS,\n\tcaps: DEFAULT_RESOURCE_ADMISSION_CAP_TABLE,\n};\n\nexport type ResourceAdmissionConfigOverrides = {\n\tthresholds?: Partial<ResourceAdmissionThresholds>;\n\tcaps?: {\n\t\tnormal?: Partial<ResourcePressureCaps>;\n\t\tconstrained?: Partial<ResourcePressureCaps>;\n\t\tcritical?: Partial<ResourcePressureCaps>;\n\t};\n};\n\nexport interface ResolvedResourceAdmissionConfig {\n\treadonly config: ResourceAdmissionConfig;\n\t/** §18.1: explicit errors over silent clamps. Non-empty means fail-closed defaults were applied. */\n\treadonly errors: readonly string[];\n}\n\nconst MIN_CAP = 1;\nconst MAX_CAP = 64;\n\n/**\n * Validate overrides against §18.1 and merge them over the defaults.\n * Any validation error fails closed: the full default config is returned\n * together with the explicit error list (startup diagnostics are the\n * caller's responsibility in later slices).\n */\nexport function resolveResourceAdmissionConfig(\n\toverrides?: ResourceAdmissionConfigOverrides,\n): ResolvedResourceAdmissionConfig {\n\tconst merged: ResourceAdmissionConfig = {\n\t\tthresholds: { ...DEFAULT_RESOURCE_ADMISSION_THRESHOLDS, ...overrides?.thresholds },\n\t\tcaps: {\n\t\t\tnormal: { ...DEFAULT_RESOURCE_ADMISSION_CAP_TABLE.normal, ...overrides?.caps?.normal },\n\t\t\tconstrained: { ...DEFAULT_RESOURCE_ADMISSION_CAP_TABLE.constrained, ...overrides?.caps?.constrained },\n\t\t\tcritical: { ...DEFAULT_RESOURCE_ADMISSION_CAP_TABLE.critical, ...overrides?.caps?.critical },\n\t\t},\n\t};\n\tconst errors = validateResourceAdmissionConfig(merged);\n\tif (errors.length > 0) {\n\t\treturn { config: DEFAULT_RESOURCE_ADMISSION_CONFIG, errors };\n\t}\n\treturn { config: merged, errors };\n}\n\nexport function validateResourceAdmissionConfig(config: ResourceAdmissionConfig): readonly string[] {\n\tconst errors: string[] = [];\n\tconst { thresholds, caps } = config;\n\n\tconst positiveMiB: ReadonlyArray<readonly [string, number]> = [\n\t\t[\"constrainedAvailableMemoryMiB\", thresholds.constrainedAvailableMemoryMiB],\n\t\t[\"criticalAvailableMemoryMiB\", thresholds.criticalAvailableMemoryMiB],\n\t\t[\"constrainedDiskFreeMiB\", thresholds.constrainedDiskFreeMiB],\n\t\t[\"criticalDiskFreeMiB\", thresholds.criticalDiskFreeMiB],\n\t];\n\tfor (const [name, value] of positiveMiB) {\n\t\tif (!Number.isSafeInteger(value) || value <= 0) {\n\t\t\terrors.push(`resourceGovernor.${name}: must be a positive safe integer, got ${String(value)}`);\n\t\t}\n\t}\n\tif (thresholds.criticalAvailableMemoryMiB > thresholds.constrainedAvailableMemoryMiB) {\n\t\terrors.push(\"resourceGovernor.criticalAvailableMemoryMiB: must be <= constrainedAvailableMemoryMiB\");\n\t}\n\tif (thresholds.criticalDiskFreeMiB > thresholds.constrainedDiskFreeMiB) {\n\t\terrors.push(\"resourceGovernor.criticalDiskFreeMiB: must be <= constrainedDiskFreeMiB\");\n\t}\n\tfor (const [name, value] of [\n\t\t[\"constrainedHeapRatio\", thresholds.constrainedHeapRatio],\n\t\t[\"criticalHeapRatio\", thresholds.criticalHeapRatio],\n\t] as const) {\n\t\tif (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0 || value > 1) {\n\t\t\terrors.push(`resourceGovernor.${name}: must be within (0, 1], got ${String(value)}`);\n\t\t}\n\t}\n\tif (thresholds.criticalHeapRatio < thresholds.constrainedHeapRatio) {\n\t\terrors.push(\"resourceGovernor.criticalHeapRatio: must be >= constrainedHeapRatio\");\n\t}\n\tif (\n\t\t!Number.isFinite(thresholds.busyCpuPercent) ||\n\t\tthresholds.busyCpuPercent < 1 ||\n\t\tthresholds.busyCpuPercent > 100\n\t) {\n\t\terrors.push(`resourceGovernor.busyCpuPercent: must be within [1, 100], got ${String(thresholds.busyCpuPercent)}`);\n\t}\n\n\tconst capFields = [\"maxToolConcurrency\", \"maxParallelLanes\", \"maxHeavyProcesses\"] as const;\n\tfor (const tier of [\"normal\", \"constrained\", \"critical\"] as const) {\n\t\tfor (const field of capFields) {\n\t\t\tconst value = caps[tier][field];\n\t\t\tif (!Number.isSafeInteger(value) || value < MIN_CAP || value > MAX_CAP) {\n\t\t\t\terrors.push(\n\t\t\t\t\t`resourceGovernor.caps.${tier}.${field}: must be an integer within [${MIN_CAP}, ${MAX_CAP}], got ${String(value)}`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\t// §4.4 / §18.1 monotonicity: normalCap >= constrainedCap >= criticalCap.\n\tfor (const field of capFields) {\n\t\tif (caps.normal[field] < caps.constrained[field] || caps.constrained[field] < caps.critical[field]) {\n\t\t\terrors.push(`resourceGovernor.caps.${field}: requires normal >= constrained >= critical`);\n\t\t}\n\t}\n\treturn errors;\n}\n"]}

package/dist/core/resource-admission.d.ts

@@ -0,0 +1,81 @@
+import { type HostResourceSnapshot } from "./host-resource-snapshot.ts";
+import { type ResourceAdmissionConfig, type ResourceAdmissionThresholds } from "./resource-admission-config.ts";
+export type { ResolvedResourceAdmissionConfig, ResourceAdmissionCapTable, ResourceAdmissionConfig, ResourceAdmissionConfigOverrides, ResourceAdmissionThresholds, ResourceGovernorMode, ResourcePressureCaps, } from "./resource-admission-config.ts";
+export { DEFAULT_RESOURCE_ADMISSION_CAP_TABLE, DEFAULT_RESOURCE_ADMISSION_CONFIG, DEFAULT_RESOURCE_ADMISSION_THRESHOLDS, resolveResourceAdmissionConfig, validateResourceAdmissionConfig, } from "./resource-admission-config.ts";
+/**
+ * Pure resource admission policy (OMK v0.97.x roadmap §6.6-§7, M1/PR1).
+ *
+ * This module maps an immutable {@link HostResourceSnapshot} to an immutable
+ * {@link ResourceAdmissionDecision}. It is deterministic (clock and id are
+ * injectable), side-effect free, and performs no scheduler wiring — the
+ * decision only becomes scheduler authority in later milestones (M2+).
+ *
+ * Policy invariants (verified by property tests, roadmap §23.2):
+ * - Monotonic degradation (§4.4): worse memory/disk/CPU never improves
+ *   pressure and never raises a cap.
+ * - Conservative unknown handling (§4.3): a known critical fact wins; a
+ *   missing key probe (memory, disk, heap) degrades to `constrained`; only a
+ *   fully healthy snapshot is `normal`.
+ * - CPU alone never produces `critical` (§6.7): CPU pressure throttles,
+ *   while memory/disk/heap may block heavy admission.
+ * - User cap precedence (§7.3): effective caps never exceed configured caps,
+ *   and `0 = unlimited` settings are limited to the admission cap.
+ */
+export declare const RESOURCE_ADMISSION_VERSION: 1;
+export type ResourcePressure = "normal" | "constrained" | "critical";
+export type ResourceAdmissionAction = "allow" | "throttle" | "defer-heavy";
+export type ResourceReasonCode = "resource.memory.low" | "resource.memory.critical" | "resource.disk.low" | "resource.disk.critical" | "resource.cpu.busy" | "resource.heap.high" | "resource.heap.critical" | "resource.probe.partial" | "resource.probe.timeout";
+export interface ResourceAdmissionDecision {
+    readonly schemaVersion: typeof RESOURCE_ADMISSION_VERSION;
+    readonly decisionId: string;
+    readonly snapshotDigest: string;
+    readonly pressure: ResourcePressure;
+    readonly action: ResourceAdmissionAction;
+    readonly maxToolConcurrency: number;
+    readonly maxParallelLanes: number;
+    readonly maxHeavyProcesses: number;
+    readonly reasons: readonly ResourceReasonCode[];
+    readonly decidedAt: string;
+}
+/** Bounded model-facing hint (§6.2). Never expose the raw snapshot to the model. */
+export interface ModelResourceBudgetHint {
+    readonly pressure: ResourcePressure;
+    readonly maxToolConcurrency: number;
+    readonly maxParallelLanes: number;
+    readonly maxHeavyProcesses: number;
+    readonly reasons: readonly ResourceReasonCode[];
+}
+/** Total order for pressure levels: `normal` (0) < `constrained` (1) < `critical` (2). */
+export declare function resourcePressureRank(pressure: ResourcePressure): number;
+export interface ResourcePressureEvaluation {
+    readonly pressure: ResourcePressure;
+    readonly reasons: readonly ResourceReasonCode[];
+}
+/**
+ * Derive pressure and reason codes from a snapshot (§4.3, §6.6, §6.7).
+ * Pure and monotonic: strictly worse inputs never yield a better pressure.
+ */
+export declare function evaluateResourcePressure(snapshot: HostResourceSnapshot, thresholds?: ResourceAdmissionThresholds): ResourcePressureEvaluation;
+/**
+ * Existing user settings that admission must never exceed (§7.3).
+ * `0` or `undefined` means "unlimited" and is limited to the admission cap.
+ */
+export interface ConfiguredResourceCaps {
+    readonly maxToolConcurrency?: number;
+    readonly maxParallelLanes?: number;
+    readonly maxHeavyProcesses?: number;
+}
+export interface ResourceAdmissionInput {
+    readonly snapshot: HostResourceSnapshot;
+    readonly config?: ResourceAdmissionConfig;
+    readonly configuredCaps?: ConfiguredResourceCaps;
+    /** Injectable for deterministic tests; defaults to a UUID-based id. */
+    readonly decisionId?: string;
+    /** Injectable ISO timestamp; defaults to the current time. */
+    readonly decidedAt?: string;
+}
+/** Map a snapshot to an immutable admission decision (§7.1-§7.3). */
+export declare function decideResourceAdmission(input: ResourceAdmissionInput): ResourceAdmissionDecision;
+/** Bounded hint for the model (§6.2). Carries no raw host values. */
+export declare function toModelResourceBudgetHint(decision: ResourceAdmissionDecision): ModelResourceBudgetHint;
+//# sourceMappingURL=resource-admission.d.ts.map

package/dist/core/resource-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-admission.d.ts","sourceRoot":"","sources":["../../src/core/resource-admission.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport {\n\tcomputeHostResourceSnapshotDigest,\n\teffectiveAvailableMemoryBytes,\n\ttype HostResourceSnapshot,\n} from \"./host-resource-snapshot.ts\";\nimport {\n\tDEFAULT_RESOURCE_ADMISSION_CONFIG,\n\tDEFAULT_RESOURCE_ADMISSION_THRESHOLDS,\n\ttype ResourceAdmissionConfig,\n\ttype ResourceAdmissionThresholds,\n} from \"./resource-admission-config.ts\";\n\nexport type {\n\tResolvedResourceAdmissionConfig,\n\tResourceAdmissionCapTable,\n\tResourceAdmissionConfig,\n\tResourceAdmissionConfigOverrides,\n\tResourceAdmissionThresholds,\n\tResourceGovernorMode,\n\tResourcePressureCaps,\n} from \"./resource-admission-config.ts\";\nexport {\n\tDEFAULT_RESOURCE_ADMISSION_CAP_TABLE,\n\tDEFAULT_RESOURCE_ADMISSION_CONFIG,\n\tDEFAULT_RESOURCE_ADMISSION_THRESHOLDS,\n\tresolveResourceAdmissionConfig,\n\tvalidateResourceAdmissionConfig,\n} from \"./resource-admission-config.ts\";\n\n/**\n * Pure resource admission policy (OMK v0.97.x roadmap §6.6-§7, M1/PR1).\n *\n * This module maps an immutable {@link HostResourceSnapshot} to an immutable\n * {@link ResourceAdmissionDecision}. It is deterministic (clock and id are\n * injectable), side-effect free, and performs no scheduler wiring — the\n * decision only becomes scheduler authority in later milestones (M2+).\n *\n * Policy invariants (verified by property tests, roadmap §23.2):\n * - Monotonic degradation (§4.4): worse memory/disk/CPU never improves\n *   pressure and never raises a cap.\n * - Conservative unknown handling (§4.3): a known critical fact wins; a\n *   missing key probe (memory, disk, heap) degrades to `constrained`; only a\n *   fully healthy snapshot is `normal`.\n * - CPU alone never produces `critical` (§6.7): CPU pressure throttles,\n *   while memory/disk/heap may block heavy admission.\n * - User cap precedence (§7.3): effective caps never exceed configured caps,\n *   and `0 = unlimited` settings are limited to the admission cap.\n */\n\nexport const RESOURCE_ADMISSION_VERSION = 1 as const;\n\nexport type ResourcePressure = \"normal\" | \"constrained\" | \"critical\";\n\nexport type ResourceAdmissionAction = \"allow\" | \"throttle\" | \"defer-heavy\";\n\nexport type ResourceReasonCode =\n\t| \"resource.memory.low\"\n\t| \"resource.memory.critical\"\n\t| \"resource.disk.low\"\n\t| \"resource.disk.critical\"\n\t| \"resource.cpu.busy\"\n\t| \"resource.heap.high\"\n\t| \"resource.heap.critical\"\n\t| \"resource.probe.partial\"\n\t| \"resource.probe.timeout\";\n\nexport interface ResourceAdmissionDecision {\n\treadonly schemaVersion: typeof RESOURCE_ADMISSION_VERSION;\n\treadonly decisionId: string;\n\treadonly snapshotDigest: string;\n\treadonly pressure: ResourcePressure;\n\treadonly action: ResourceAdmissionAction;\n\n\treadonly maxToolConcurrency: number;\n\treadonly maxParallelLanes: number;\n\treadonly maxHeavyProcesses: number;\n\n\treadonly reasons: readonly ResourceReasonCode[];\n\treadonly decidedAt: string;\n}\n\n/** Bounded model-facing hint (§6.2). Never expose the raw snapshot to the model. */\nexport interface ModelResourceBudgetHint {\n\treadonly pressure: ResourcePressure;\n\treadonly maxToolConcurrency: number;\n\treadonly maxParallelLanes: number;\n\treadonly maxHeavyProcesses: number;\n\treadonly reasons: readonly ResourceReasonCode[];\n}\n\nconst MIB = 1024 * 1024;\nconst MIN_CAP = 1;\nconst PRESSURE_RANK: Record<ResourcePressure, number> = { normal: 0, constrained: 1, critical: 2 };\nconst RANK_TO_PRESSURE: readonly ResourcePressure[] = [\"normal\", \"constrained\", \"critical\"];\n/** §7 action mapping: allow at normal, throttle at constrained, defer heavy work at critical. */\nconst ACTION_BY_PRESSURE: Record<ResourcePressure, ResourceAdmissionAction> = {\n\tnormal: \"allow\",\n\tconstrained: \"throttle\",\n\tcritical: \"defer-heavy\",\n};\n\n/** Total order for pressure levels: `normal` (0) < `constrained` (1) < `critical` (2). */\nexport function resourcePressureRank(pressure: ResourcePressure): number {\n\treturn PRESSURE_RANK[pressure];\n}\n\nexport interface ResourcePressureEvaluation {\n\treadonly pressure: ResourcePressure;\n\treadonly reasons: readonly ResourceReasonCode[];\n}\n\n/**\n * Derive pressure and reason codes from a snapshot (§4.3, §6.6, §6.7).\n * Pure and monotonic: strictly worse inputs never yield a better pressure.\n */\nexport function evaluateResourcePressure(\n\tsnapshot: HostResourceSnapshot,\n\tthresholds: ResourceAdmissionThresholds = DEFAULT_RESOURCE_ADMISSION_THRESHOLDS,\n): ResourcePressureEvaluation {\n\tconst reasons: ResourceReasonCode[] = [];\n\tlet rank = PRESSURE_RANK.normal;\n\tconst escalate = (target: ResourcePressure, reason: ResourceReasonCode): void => {\n\t\treasons.push(reason);\n\t\trank = Math.max(rank, PRESSURE_RANK[target]);\n\t};\n\n\tconst memory = effectiveAvailableMemoryBytes(snapshot);\n\tif (memory !== null) {\n\t\tif (memory < thresholds.criticalAvailableMemoryMiB * MIB) {\n\t\t\tescalate(\"critical\", \"resource.memory.critical\");\n\t\t} else if (memory < thresholds.constrainedAvailableMemoryMiB * MIB) {\n\t\t\tescalate(\"constrained\", \"resource.memory.low\");\n\t\t}\n\t}\n\n\tconst disk = snapshot.workspaceAvailableBytes;\n\tif (disk !== null) {\n\t\tif (disk < thresholds.criticalDiskFreeMiB * MIB) {\n\t\t\tescalate(\"critical\", \"resource.disk.critical\");\n\t\t} else if (disk < thresholds.constrainedDiskFreeMiB * MIB) {\n\t\t\tescalate(\"constrained\", \"resource.disk.low\");\n\t\t}\n\t}\n\n\tconst heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;\n\tif (heapRatio !== null) {\n\t\tif (heapRatio >= thresholds.criticalHeapRatio) {\n\t\t\tescalate(\"critical\", \"resource.heap.critical\");\n\t\t} else if (heapRatio >= thresholds.constrainedHeapRatio) {\n\t\t\tescalate(\"constrained\", \"resource.heap.high\");\n\t\t}\n\t}\n\n\t// §6.7: CPU pressure only throttles; it can never be critical on its own.\n\tif (snapshot.systemCpuPercent !== null && snapshot.systemCpuPercent >= thresholds.busyCpuPercent) {\n\t\tescalate(\"constrained\", \"resource.cpu.busy\");\n\t}\n\n\t// §4.3 conservative unknown handling. Key probes are the heavy-admission\n\t// authorities (memory, disk, heap); a missing one degrades to constrained.\n\tif (memory === null || disk === null || heapRatio === null) {\n\t\tescalate(\"constrained\", \"resource.probe.partial\");\n\t}\n\t// §21: any probe timeout keeps the prompt going but never reports normal.\n\tif (snapshot.diagnostics.some((code) => code.endsWith(\".timeout\"))) {\n\t\tescalate(\"constrained\", \"resource.probe.timeout\");\n\t}\n\n\treturn { pressure: RANK_TO_PRESSURE[rank] ?? \"critical\", reasons };\n}\n\n/**\n * Existing user settings that admission must never exceed (§7.3).\n * `0` or `undefined` means \"unlimited\" and is limited to the admission cap.\n */\nexport interface ConfiguredResourceCaps {\n\treadonly maxToolConcurrency?: number;\n\treadonly maxParallelLanes?: number;\n\treadonly maxHeavyProcesses?: number;\n}\n\nexport interface ResourceAdmissionInput {\n\treadonly snapshot: HostResourceSnapshot;\n\treadonly config?: ResourceAdmissionConfig;\n\treadonly configuredCaps?: ConfiguredResourceCaps;\n\t/** Injectable for deterministic tests; defaults to a UUID-based id. */\n\treadonly decisionId?: string;\n\t/** Injectable ISO timestamp; defaults to the current time. */\n\treadonly decidedAt?: string;\n}\n\n/** Map a snapshot to an immutable admission decision (§7.1-§7.3). */\nexport function decideResourceAdmission(input: ResourceAdmissionInput): ResourceAdmissionDecision {\n\tconst config = input.config ?? DEFAULT_RESOURCE_ADMISSION_CONFIG;\n\tconst { pressure, reasons } = evaluateResourcePressure(input.snapshot, config.thresholds);\n\tconst tier = config.caps[pressure];\n\treturn {\n\t\tschemaVersion: RESOURCE_ADMISSION_VERSION,\n\t\tdecisionId: input.decisionId ?? `res-adm-${randomUUID()}`,\n\t\tsnapshotDigest: computeHostResourceSnapshotDigest(input.snapshot),\n\t\tpressure,\n\t\taction: ACTION_BY_PRESSURE[pressure],\n\t\tmaxToolConcurrency: effectiveCap(input.configuredCaps?.maxToolConcurrency, tier.maxToolConcurrency),\n\t\tmaxParallelLanes: effectiveCap(input.configuredCaps?.maxParallelLanes, tier.maxParallelLanes),\n\t\tmaxHeavyProcesses: effectiveCap(input.configuredCaps?.maxHeavyProcesses, tier.maxHeavyProcesses),\n\t\treasons,\n\t\tdecidedAt: input.decidedAt ?? new Date().toISOString(),\n\t};\n}\n\n/** Bounded hint for the model (§6.2). Carries no raw host values. */\nexport function toModelResourceBudgetHint(decision: ResourceAdmissionDecision): ModelResourceBudgetHint {\n\treturn {\n\t\tpressure: decision.pressure,\n\t\tmaxToolConcurrency: decision.maxToolConcurrency,\n\t\tmaxParallelLanes: decision.maxParallelLanes,\n\t\tmaxHeavyProcesses: decision.maxHeavyProcesses,\n\t\treasons: decision.reasons,\n\t};\n}\n\n/** §7.3: `min(configured, admission)`, where configured `0`/absent means unlimited. */\nfunction effectiveCap(configured: number | undefined, admission: number): number {\n\tconst admitted = Math.max(MIN_CAP, Math.floor(admission));\n\tif (typeof configured !== \"number\" || !Number.isFinite(configured) || configured <= 0) {\n\t\treturn admitted;\n\t}\n\treturn Math.max(MIN_CAP, Math.min(Math.floor(configured), admitted));\n}\n"]}