@descryy/core 0.1.0

package/dist/governance/budget.js

@@ -0,0 +1,101 @@
+/**
+ * The hard per-run budget — §41 rule 16, `ai-layer-plan.md` §11 (Phase 4,
+ * P17/P18). `ai-governance-spec.md` §8 names this explicitly as *not* its
+ * document's job: *"a property of the harness (Phase 4, P17/P18), not of a
+ * per-finding gate... Full spec: Phase 4 (P17), not this document."* This
+ * module is that property.
+ *
+ * *"Enforced by the runtime harness, not by the AI's own judgment of when to
+ * stop"* (`descry-ai-layer.md`, "Execution budget"). A cap the model can
+ * reason its way past is not a cap (§41 rule 16's own words) — so, same as
+ * G1–G4, this is a pure function the pipeline calls, never a prompt
+ * instruction.
+ *
+ * ## Four caps, two scopes
+ *
+ * `ai-layer-plan.md` §11 names four: *"max turns per investigation · max
+ * cost per run · max concurrent open hypotheses · max tool calls per
+ * hypothesis."* Two are per-run (cost, concurrency); two are per-hypothesis
+ * (turns, tool calls) and are checked against every currently-open
+ * hypothesis independently — one hypothesis running long does not budget-fail
+ * a sibling that has spent nothing.
+ *
+ * ## The default values
+ *
+ * `documents/architecture/investigation-budget-spec.md` (P17) is where these
+ * are ruled and justified; this module imports them from there in spirit —
+ * they are declared once, here, because the spec document is prose and this
+ * is the value the harness actually reads. A caller may always supply its
+ * own {@link InvestigationBudget}; the exported default is a starting point,
+ * tuned from data, the same convention `CLAUDE.md` already applies to node
+ * budgets.
+ */
+/**
+ * P17's ruled starting values — `documents/architecture/investigation-budget-spec.md`.
+ * Not a measurement; a starting point to tune from real runs, same as the
+ * node budgets `CLAUDE.md` already treats this way.
+ */
+export const DEFAULT_INVESTIGATION_BUDGET = {
+    maxTurnsPerInvestigation: 8,
+    maxToolCallsPerHypothesis: 6,
+    maxConcurrentOpenHypotheses: 5,
+    costCeilingPerRunUsd: 2.0,
+};
+export const BUDGET_CAP_NAMES = [
+    "maxTurnsPerInvestigation",
+    "maxToolCallsPerHypothesis",
+    "maxConcurrentOpenHypotheses",
+    "costCeilingPerRunUsd",
+];
+/**
+ * Check `usage` against `budget`. Never throws — this is a check, not an
+ * execution of the thing it is checking, same posture as G1–G4.
+ */
+export function checkRunBudget(budget, usage) {
+    const exceeded = [];
+    if (usage.costSpentUsd > budget.costCeilingPerRunUsd) {
+        exceeded.push({
+            cap: "costCeilingPerRunUsd",
+            limit: budget.costCeilingPerRunUsd,
+            actual: usage.costSpentUsd,
+        });
+    }
+    if (usage.openHypotheses.length > budget.maxConcurrentOpenHypotheses) {
+        exceeded.push({
+            cap: "maxConcurrentOpenHypotheses",
+            limit: budget.maxConcurrentOpenHypotheses,
+            actual: usage.openHypotheses.length,
+        });
+    }
+    for (const hypothesis of usage.openHypotheses) {
+        if (hypothesis.turnsSpent > budget.maxTurnsPerInvestigation) {
+            exceeded.push({
+                cap: "maxTurnsPerInvestigation",
+                limit: budget.maxTurnsPerInvestigation,
+                actual: hypothesis.turnsSpent,
+                hypothesisId: hypothesis.hypothesisId,
+            });
+        }
+        if (hypothesis.toolCallsSpent > budget.maxToolCallsPerHypothesis) {
+            exceeded.push({
+                cap: "maxToolCallsPerHypothesis",
+                limit: budget.maxToolCallsPerHypothesis,
+                actual: hypothesis.toolCallsSpent,
+                hypothesisId: hypothesis.hypothesisId,
+            });
+        }
+    }
+    return { withinBudget: exceeded.length === 0, exceeded };
+}
+/**
+ * Whether a specific hypothesis has reached its per-hypothesis round limit —
+ * the input `../../ir/src/hypothesis.ts`'s `deriveHypothesisState` needs for
+ * its `roundLimitReached` field. A thin, named convenience over
+ * {@link checkRunBudget} so a caller does not have to re-derive "does this
+ * one hypothesis's own cap show up in `exceeded`" by hand.
+ */
+export function hypothesisRoundLimitReached(budget, usage) {
+    return (usage.turnsSpent > budget.maxTurnsPerInvestigation ||
+        usage.toolCallsSpent > budget.maxToolCallsPerHypothesis);
+}
+//# sourceMappingURL=budget.js.map

package/dist/governance/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/governance/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAcH;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAwB;IAC/D,wBAAwB,EAAE,CAAC;IAC3B,yBAAyB,EAAE,CAAC;IAC5B,2BAA2B,EAAE,CAAC;IAC9B,oBAAoB,EAAE,GAAG;CAC1B,CAAC;AAgBF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,0BAA0B;IAC1B,2BAA2B;IAC3B,6BAA6B;IAC7B,sBAAsB;CACd,CAAC;AAkBX;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAA2B,EAAE,KAAqB;IAC/E,MAAM,QAAQ,GAAwB,EAAE,CAAC;IAEzC,IAAI,KAAK,CAAC,YAAY,GAAG,MAAM,CAAC,oBAAoB,EAAE,CAAC;QACrD,QAAQ,CAAC,IAAI,CAAC;YACZ,GAAG,EAAE,sBAAsB;YAC3B,KAAK,EAAE,MAAM,CAAC,oBAAoB;YAClC,MAAM,EAAE,KAAK,CAAC,YAAY;SAC3B,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,CAAC,cAAc,CAAC,MAAM,GAAG,MAAM,CAAC,2BAA2B,EAAE,CAAC;QACrE,QAAQ,CAAC,IAAI,CAAC;YACZ,GAAG,EAAE,6BAA6B;YAClC,KAAK,EAAE,MAAM,CAAC,2BAA2B;YACzC,MAAM,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM;SACpC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;QAC9C,IAAI,UAAU,CAAC,UAAU,GAAG,MAAM,CAAC,wBAAwB,EAAE,CAAC;YAC5D,QAAQ,CAAC,IAAI,CAAC;gBACZ,GAAG,EAAE,0BAA0B;gBAC/B,KAAK,EAAE,MAAM,CAAC,wBAAwB;gBACtC,MAAM,EAAE,UAAU,CAAC,UAAU;gBAC7B,YAAY,EAAE,UAAU,CAAC,YAAY;aACtC,CAAC,CAAC;QACL,CAAC;QACD,IAAI,UAAU,CAAC,cAAc,GAAG,MAAM,CAAC,yBAAyB,EAAE,CAAC;YACjE,QAAQ,CAAC,IAAI,CAAC;gBACZ,GAAG,EAAE,2BAA2B;gBAChC,KAAK,EAAE,MAAM,CAAC,yBAAyB;gBACvC,MAAM,EAAE,UAAU,CAAC,cAAc;gBACjC,YAAY,EAAE,UAAU,CAAC,YAAY;aACtC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAA2B,EAC3B,KAA4B;IAE5B,OAAO,CACL,KAAK,CAAC,UAAU,GAAG,MAAM,CAAC,wBAAwB;QAClD,KAAK,CAAC,cAAc,GAAG,MAAM,CAAC,yBAAyB,CACxD,CAAC;AACJ,CAAC"}

package/dist/governance/candidate-boundary.d.ts

@@ -0,0 +1,49 @@
+/**
+ * G2 — the candidate boundary (`ai-governance-spec.md` §3, `ai-layer-plan.md` §5).
+ *
+ * **The plan (stage 6) may only contain items from the deterministic
+ * candidate set stages 3–5 produced.** Stage 5 (risk prioritization) is
+ * itself deterministic — "scores in, ordering out. Does not invent
+ * candidates" (`ai-layer-plan.md` §1) — so a plan item naming a node outside
+ * that set could only have been invented by stage 6's own model slot, and is
+ * rejected outright rather than down-ranked.
+ *
+ * Same shape as G1, one stage later, and built as the same kind of pure
+ * function: `ai-governance-spec.md` §10 — "candidate-set membership checking
+ * on the plan... no new tool surface, no new IR type." A candidate set is a
+ * set of node ids; this module does not care how stages 3–5 produced it.
+ *
+ * ## Reject the item, not the plan
+ *
+ * `ai-governance-spec.md` §3's own negative control: "a plan naming a target
+ * outside the candidate set. G2 must reject the item, not the whole plan —
+ * the rest of the plan proceeds if the remaining items are valid." So the
+ * result partitions the plan rather than failing it wholesale.
+ *
+ * `PlanItem` is deliberately the smallest shape G2 needs — one node id.
+ * Phase 3's real plan item will carry more (a rationale, a priority, a test
+ * strategy); the generic parameter lets a caller pass its real type through
+ * unchanged and get it back in `accepted`/`rejected`, rather than this
+ * module owning a plan-item type the pipeline would then have to conform to.
+ */
+/** The smallest shape G2 needs from a plan item: what node it targets. */
+export interface PlanItem {
+    readonly targetNodeId: string;
+}
+export interface RejectedPlanItem<T extends PlanItem> {
+    readonly item: T;
+    /** Plain-English, ready to append to the slot's re-run prompt verbatim. */
+    readonly reason: string;
+}
+export interface CandidateBoundaryResult<T extends PlanItem> {
+    readonly accepted: readonly T[];
+    readonly rejected: readonly RejectedPlanItem<T>[];
+}
+/**
+ * Check every item in `plan` against `candidateNodeIds` — the deterministic
+ * set stages 3–5 produced. An item whose `targetNodeId` is not in that set
+ * is rejected with a reason; the rest of the plan is unaffected. Never
+ * throws — this is a check, not an execution of the thing it is checking.
+ */
+export declare function checkCandidateBoundary<T extends PlanItem>(plan: readonly T[], candidateNodeIds: ReadonlySet<string>): CandidateBoundaryResult<T>;
+//# sourceMappingURL=candidate-boundary.d.ts.map

package/dist/governance/candidate-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-boundary.d.ts","sourceRoot":"","sources":["../../src/governance/candidate-boundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,QAAQ;IAClD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,QAAQ;IACzD,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;CACnD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,QAAQ,EACvD,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,GACpC,uBAAuB,CAAC,CAAC,CAAC,CAgB5B"}

package/dist/governance/candidate-boundary.js

@@ -0,0 +1,51 @@
+/**
+ * G2 — the candidate boundary (`ai-governance-spec.md` §3, `ai-layer-plan.md` §5).
+ *
+ * **The plan (stage 6) may only contain items from the deterministic
+ * candidate set stages 3–5 produced.** Stage 5 (risk prioritization) is
+ * itself deterministic — "scores in, ordering out. Does not invent
+ * candidates" (`ai-layer-plan.md` §1) — so a plan item naming a node outside
+ * that set could only have been invented by stage 6's own model slot, and is
+ * rejected outright rather than down-ranked.
+ *
+ * Same shape as G1, one stage later, and built as the same kind of pure
+ * function: `ai-governance-spec.md` §10 — "candidate-set membership checking
+ * on the plan... no new tool surface, no new IR type." A candidate set is a
+ * set of node ids; this module does not care how stages 3–5 produced it.
+ *
+ * ## Reject the item, not the plan
+ *
+ * `ai-governance-spec.md` §3's own negative control: "a plan naming a target
+ * outside the candidate set. G2 must reject the item, not the whole plan —
+ * the rest of the plan proceeds if the remaining items are valid." So the
+ * result partitions the plan rather than failing it wholesale.
+ *
+ * `PlanItem` is deliberately the smallest shape G2 needs — one node id.
+ * Phase 3's real plan item will carry more (a rationale, a priority, a test
+ * strategy); the generic parameter lets a caller pass its real type through
+ * unchanged and get it back in `accepted`/`rejected`, rather than this
+ * module owning a plan-item type the pipeline would then have to conform to.
+ */
+/**
+ * Check every item in `plan` against `candidateNodeIds` — the deterministic
+ * set stages 3–5 produced. An item whose `targetNodeId` is not in that set
+ * is rejected with a reason; the rest of the plan is unaffected. Never
+ * throws — this is a check, not an execution of the thing it is checking.
+ */
+export function checkCandidateBoundary(plan, candidateNodeIds) {
+    const accepted = [];
+    const rejected = [];
+    for (const item of plan) {
+        if (candidateNodeIds.has(item.targetNodeId)) {
+            accepted.push(item);
+        }
+        else {
+            rejected.push({
+                item,
+                reason: `target node ${item.targetNodeId} is not in the candidate set stages 3-5 produced`,
+            });
+        }
+    }
+    return { accepted, rejected };
+}
+//# sourceMappingURL=candidate-boundary.js.map

package/dist/governance/candidate-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-boundary.js","sourceRoot":"","sources":["../../src/governance/candidate-boundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAkBH;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAkB,EAClB,gBAAqC;IAErC,MAAM,QAAQ,GAAQ,EAAE,CAAC;IACzB,MAAM,QAAQ,GAA0B,EAAE,CAAC;IAE3C,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;YAC5C,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI;gBACJ,MAAM,EAAE,eAAe,IAAI,CAAC,YAAY,kDAAkD;aAC3F,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAChC,CAAC"}

package/dist/governance/escalation.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Escalation — §41 rule 17, `ai-layer-plan.md` §11 (Phase 4, P17/P18).
+ *
+ * *"AI must escalate to the developer rather than keep investigating
+ * when..."* — three conditions named in the architecture (budget exhausted,
+ * a hypothesis stuck past its round limit, unresolved graph/runtime
+ * contradiction), widened to five in the plan's own §11: *"budget exhausted
+ * with hypotheses open · unresolved contradictory evidence · a fact only a
+ * human holds · an action gate reached · every hypothesis refuted with the
+ * anomaly unexplained."*
+ *
+ * Same shape as {@link "./budget.ts"} and G1–G4: a pure function over
+ * caller-supplied facts, evaluated outside the model, never a prompt telling
+ * the model when to stop. `ai-layer-plan.md` §0's own words, one layer up:
+ * *"a rule the model can reason its way past is not a rule."*
+ *
+ * ## Four of five inputs are not computed here
+ *
+ * Only the budget trigger is derivable from `./budget.ts`'s own output.
+ * The other four name conditions this module has no way to detect on its
+ * own, and deliberately does not try to:
+ *
+ * - **Unresolved contradictory evidence** — §10's graph-vs-runtime
+ *   contradiction machinery (P21) is what detects a contradiction at all;
+ *   this module only reacts to the caller having found one.
+ * - **A fact only a human holds** — inherits the `questions` MCP tool /
+ *   `ConfirmedFact` machinery (`packages/core/src/query/refusal-questions.ts`,
+ *   `confirmed-facts.ts`) already built for a different stage. Whether an
+ *   open, unanswered question exists is that machinery's own state, not
+ *   something recomputed here.
+ * - **An action gate reached** — G5 (`ai-tool-contract.md` §7's two-call
+ *   handshake) already governs whether a write may proceed; this module
+ *   just names the fact of having reached it as one more reason to stop and
+ *   hand control back.
+ * - **Every hypothesis refuted, anomaly unexplained** — depends on every
+ *   open hypothesis's terminal state (`../../ir/src/hypothesis.ts`) plus a
+ *   judgement that no other explanation covers the original anomaly. The
+ *   "no other explanation" half is not a fact this module can derive from a
+ *   list of rejected hypotheses alone, so it stays a caller-supplied flag.
+ */
+export declare const ESCALATION_TRIGGERS: readonly ["budget-exhausted-with-hypotheses-open", "unresolved-contradictory-evidence", "fact-only-a-human-holds", "action-gate-reached", "every-hypothesis-refuted-unexplained"];
+export type EscalationTrigger = (typeof ESCALATION_TRIGGERS)[number];
+export interface EscalationCheckInput {
+    /** From `checkRunBudget(...).withinBudget === false` (`./budget.ts`). */
+    readonly budgetExceeded: boolean;
+    /** How many hypotheses are currently `investigating` or `supported` — not `candidate`, not terminal. */
+    readonly openHypothesesCount: number;
+    /** Caller-supplied: §10's contradiction machinery (P21) found a graph/runtime disagreement it could not resolve within the round limit. */
+    readonly hasUnresolvedContradiction: boolean;
+    /** Caller-supplied: the `questions`/`ConfirmedFact` machinery has an open, unanswered question this investigation needs to proceed. */
+    readonly hasUnansweredHumanQuestion: boolean;
+    /** Caller-supplied: G5 (the action gate) has been reached and needs developer approval before any write. */
+    readonly actionGateReached: boolean;
+    /** Caller-supplied: every hypothesis this run opened has reached `rejected`, and the anomaly that started the investigation still has no confirmed or supported explanation. */
+    readonly allHypothesesRejectedAnomalyUnexplained: boolean;
+}
+/**
+ * Check `input` against all five triggers. Never throws — a check, not an
+ * execution of the thing it is checking. More than one trigger may fire in
+ * the same call; an empty result means the loop may keep running.
+ */
+export declare function checkEscalation(input: EscalationCheckInput): readonly EscalationTrigger[];
+//# sourceMappingURL=escalation.d.ts.map

package/dist/governance/escalation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation.d.ts","sourceRoot":"","sources":["../../src/governance/escalation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,eAAO,MAAM,mBAAmB,mLAMtB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,wGAAwG;IACxG,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,2IAA2I;IAC3I,QAAQ,CAAC,0BAA0B,EAAE,OAAO,CAAC;IAC7C,uIAAuI;IACvI,QAAQ,CAAC,0BAA0B,EAAE,OAAO,CAAC;IAC7C,4GAA4G;IAC5G,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,gLAAgL;IAChL,QAAQ,CAAC,uCAAuC,EAAE,OAAO,CAAC;CAC3D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,SAAS,iBAAiB,EAAE,CAoBzF"}

package/dist/governance/escalation.js

@@ -0,0 +1,72 @@
+/**
+ * Escalation — §41 rule 17, `ai-layer-plan.md` §11 (Phase 4, P17/P18).
+ *
+ * *"AI must escalate to the developer rather than keep investigating
+ * when..."* — three conditions named in the architecture (budget exhausted,
+ * a hypothesis stuck past its round limit, unresolved graph/runtime
+ * contradiction), widened to five in the plan's own §11: *"budget exhausted
+ * with hypotheses open · unresolved contradictory evidence · a fact only a
+ * human holds · an action gate reached · every hypothesis refuted with the
+ * anomaly unexplained."*
+ *
+ * Same shape as {@link "./budget.ts"} and G1–G4: a pure function over
+ * caller-supplied facts, evaluated outside the model, never a prompt telling
+ * the model when to stop. `ai-layer-plan.md` §0's own words, one layer up:
+ * *"a rule the model can reason its way past is not a rule."*
+ *
+ * ## Four of five inputs are not computed here
+ *
+ * Only the budget trigger is derivable from `./budget.ts`'s own output.
+ * The other four name conditions this module has no way to detect on its
+ * own, and deliberately does not try to:
+ *
+ * - **Unresolved contradictory evidence** — §10's graph-vs-runtime
+ *   contradiction machinery (P21) is what detects a contradiction at all;
+ *   this module only reacts to the caller having found one.
+ * - **A fact only a human holds** — inherits the `questions` MCP tool /
+ *   `ConfirmedFact` machinery (`packages/core/src/query/refusal-questions.ts`,
+ *   `confirmed-facts.ts`) already built for a different stage. Whether an
+ *   open, unanswered question exists is that machinery's own state, not
+ *   something recomputed here.
+ * - **An action gate reached** — G5 (`ai-tool-contract.md` §7's two-call
+ *   handshake) already governs whether a write may proceed; this module
+ *   just names the fact of having reached it as one more reason to stop and
+ *   hand control back.
+ * - **Every hypothesis refuted, anomaly unexplained** — depends on every
+ *   open hypothesis's terminal state (`../../ir/src/hypothesis.ts`) plus a
+ *   judgement that no other explanation covers the original anomaly. The
+ *   "no other explanation" half is not a fact this module can derive from a
+ *   list of rejected hypotheses alone, so it stays a caller-supplied flag.
+ */
+export const ESCALATION_TRIGGERS = [
+    "budget-exhausted-with-hypotheses-open",
+    "unresolved-contradictory-evidence",
+    "fact-only-a-human-holds",
+    "action-gate-reached",
+    "every-hypothesis-refuted-unexplained",
+];
+/**
+ * Check `input` against all five triggers. Never throws — a check, not an
+ * execution of the thing it is checking. More than one trigger may fire in
+ * the same call; an empty result means the loop may keep running.
+ */
+export function checkEscalation(input) {
+    const triggers = [];
+    if (input.budgetExceeded && input.openHypothesesCount > 0) {
+        triggers.push("budget-exhausted-with-hypotheses-open");
+    }
+    if (input.hasUnresolvedContradiction) {
+        triggers.push("unresolved-contradictory-evidence");
+    }
+    if (input.hasUnansweredHumanQuestion) {
+        triggers.push("fact-only-a-human-holds");
+    }
+    if (input.actionGateReached) {
+        triggers.push("action-gate-reached");
+    }
+    if (input.allHypothesesRejectedAnomalyUnexplained) {
+        triggers.push("every-hypothesis-refuted-unexplained");
+    }
+    return triggers;
+}
+//# sourceMappingURL=escalation.js.map

package/dist/governance/escalation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation.js","sourceRoot":"","sources":["../../src/governance/escalation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,uCAAuC;IACvC,mCAAmC;IACnC,yBAAyB;IACzB,qBAAqB;IACrB,sCAAsC;CAC9B,CAAC;AAmBX;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2B;IACzD,MAAM,QAAQ,GAAwB,EAAE,CAAC;IAEzC,IAAI,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,EAAE,CAAC;QAC1D,QAAQ,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,KAAK,CAAC,0BAA0B,EAAE,CAAC;QACrC,QAAQ,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,KAAK,CAAC,0BAA0B,EAAE,CAAC;QACrC,QAAQ,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAC5B,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,KAAK,CAAC,uCAAuC,EAAE,CAAC;QAClD,QAAQ,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/governance/fact-boundary.d.ts

@@ -0,0 +1,77 @@
+/**
+ * G1 — the fact boundary (`ai-governance-spec.md` §2, `ai-layer-plan.md` §5).
+ *
+ * **No fact enters the model's context unless a tool produced it. No fact
+ * leaves a model slot unless it references something a tool returned.**
+ *
+ * This is the first of the two gates P9 builds (`ai-governance-spec.md` §10):
+ * "citation-checking on every slot output... a pure function over
+ * already-recorded tool calls... no new tool surface, no new IR type."
+ *
+ * ## Why a citation is `{ seq }`, not `{ runId, seq }`
+ *
+ * `recorded_calls`'s primary key is `(run_id, seq)` (`../recording/schema.ts`),
+ * and the gate is defined as checking a claim "against **this run's own**
+ * recorded tool calls" — the run is the boundary, not a parameter a slot
+ * output gets to name. `checkFactBoundary` takes the `RecordedRun` it is
+ * checking against and a citation carries only `seq`. A citation naming a
+ * call from a different run does not fail because the run id mismatches —
+ * it fails because no call with that `seq` exists in *this* run's own
+ * ordered list, which is the same failure as a fabricated seq and needs no
+ * separate case (negative control 7, `ai-layer-plan.md` §9 layer 5).
+ *
+ * ## Why a whole claim is rejected on any unresolved citation
+ *
+ * A claim with two citations, one real and one fabricated, is not "half
+ * true." §41.1 (never invent graph facts) does not have a partial-credit
+ * form, so one bad citation invalidates the claim it was attached to, not
+ * just itself — the same posture `ai-tool-contract.md`'s invariants take
+ * toward a payload that "looks complete."
+ *
+ * ## Path is a key array, not a string
+ *
+ * `data.callers[0]` is a plausible citation shape, but parsing that string
+ * back into a traversal is a small grammar this gate does not need to own.
+ * `readonly (string | number)[]` says the same thing with no parser and no
+ * ambiguity about what `[0]` means against an object vs. an array.
+ */
+import type { RecordedRun } from "../recording/reader.ts";
+/** One segment of a citation path: an object key or an array index. */
+export type CitationPathSegment = string | number;
+/**
+ * A pointer at one fact a tool call actually returned, within the run being
+ * checked. `seq` names the call (`recorded_calls.seq`); `path`, when given,
+ * narrows the citation to a field within that call's `result` rather than
+ * the whole envelope. Omitted `path` cites the whole result.
+ */
+export interface Citation {
+    readonly seq: number;
+    readonly path?: readonly CitationPathSegment[];
+}
+/** One factual assertion a model slot's output makes. */
+export interface FactualClaim {
+    readonly text: string;
+    /** Empty means uncited — rejected outright, never treated as an implicit whole-run citation. */
+    readonly citations: readonly Citation[];
+}
+/** What a slot output looks like from G1's point of view — nothing else about it matters here. */
+export interface SlotOutput {
+    readonly claims: readonly FactualClaim[];
+}
+export interface RejectedClaim {
+    readonly claim: FactualClaim;
+    /** Plain-English, one per failure — ready to append to the slot's re-run prompt verbatim. */
+    readonly reasons: readonly string[];
+}
+export interface FactBoundaryResult {
+    readonly accepted: readonly FactualClaim[];
+    readonly rejected: readonly RejectedClaim[];
+}
+/**
+ * Check every claim in `output` against `run`'s own recorded calls. A claim
+ * with no citations, or with any citation that does not resolve, is
+ * rejected with its reasons; everything else is accepted. Never throws —
+ * this is a check, not an execution of the thing it is checking.
+ */
+export declare function checkFactBoundary(output: SlotOutput, run: RecordedRun): FactBoundaryResult;
+//# sourceMappingURL=fact-boundary.d.ts.map

package/dist/governance/fact-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-boundary.d.ts","sourceRoot":"","sources":["../../src/governance/fact-boundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAgB,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAExE,uEAAuE;AACvE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAChD;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;CACzC;AAED,kGAAkG;AAClG,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AA2BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,WAAW,GAAG,kBAAkB,CAwB1F"}

package/dist/governance/fact-boundary.js

@@ -0,0 +1,91 @@
+/**
+ * G1 — the fact boundary (`ai-governance-spec.md` §2, `ai-layer-plan.md` §5).
+ *
+ * **No fact enters the model's context unless a tool produced it. No fact
+ * leaves a model slot unless it references something a tool returned.**
+ *
+ * This is the first of the two gates P9 builds (`ai-governance-spec.md` §10):
+ * "citation-checking on every slot output... a pure function over
+ * already-recorded tool calls... no new tool surface, no new IR type."
+ *
+ * ## Why a citation is `{ seq }`, not `{ runId, seq }`
+ *
+ * `recorded_calls`'s primary key is `(run_id, seq)` (`../recording/schema.ts`),
+ * and the gate is defined as checking a claim "against **this run's own**
+ * recorded tool calls" — the run is the boundary, not a parameter a slot
+ * output gets to name. `checkFactBoundary` takes the `RecordedRun` it is
+ * checking against and a citation carries only `seq`. A citation naming a
+ * call from a different run does not fail because the run id mismatches —
+ * it fails because no call with that `seq` exists in *this* run's own
+ * ordered list, which is the same failure as a fabricated seq and needs no
+ * separate case (negative control 7, `ai-layer-plan.md` §9 layer 5).
+ *
+ * ## Why a whole claim is rejected on any unresolved citation
+ *
+ * A claim with two citations, one real and one fabricated, is not "half
+ * true." §41.1 (never invent graph facts) does not have a partial-credit
+ * form, so one bad citation invalidates the claim it was attached to, not
+ * just itself — the same posture `ai-tool-contract.md`'s invariants take
+ * toward a payload that "looks complete."
+ *
+ * ## Path is a key array, not a string
+ *
+ * `data.callers[0]` is a plausible citation shape, but parsing that string
+ * back into a traversal is a small grammar this gate does not need to own.
+ * `readonly (string | number)[]` says the same thing with no parser and no
+ * ambiguity about what `[0]` means against an object vs. an array.
+ */
+function resolvesWithin(value, path) {
+    let cursor = value;
+    for (const key of path) {
+        if (cursor === null || typeof cursor !== "object")
+            return false;
+        if (Array.isArray(cursor)) {
+            if (typeof key !== "number" || !Number.isInteger(key) || key < 0 || key >= cursor.length)
+                return false;
+        }
+        else if (!Object.hasOwn(cursor, key)) {
+            return false;
+        }
+        cursor = cursor[key];
+    }
+    return true;
+}
+function checkCitation(citation, callsBySeq) {
+    const call = callsBySeq.get(citation.seq);
+    if (call === undefined) {
+        return `citation seq ${citation.seq} does not match any tool call recorded in this run`;
+    }
+    if (citation.path !== undefined && !resolvesWithin(call.result, citation.path)) {
+        return `citation seq ${citation.seq} path ${JSON.stringify(citation.path)} does not resolve within that call's result`;
+    }
+    return null;
+}
+/**
+ * Check every claim in `output` against `run`'s own recorded calls. A claim
+ * with no citations, or with any citation that does not resolve, is
+ * rejected with its reasons; everything else is accepted. Never throws —
+ * this is a check, not an execution of the thing it is checking.
+ */
+export function checkFactBoundary(output, run) {
+    const callsBySeq = new Map(run.calls.map((call) => [call.seq, call]));
+    const accepted = [];
+    const rejected = [];
+    for (const claim of output.claims) {
+        if (claim.citations.length === 0) {
+            rejected.push({ claim, reasons: ["no citation for this claim"] });
+            continue;
+        }
+        const reasons = claim.citations
+            .map((citation) => checkCitation(citation, callsBySeq))
+            .filter((reason) => reason !== null);
+        if (reasons.length === 0) {
+            accepted.push(claim);
+        }
+        else {
+            rejected.push({ claim, reasons });
+        }
+    }
+    return { accepted, rejected };
+}
+//# sourceMappingURL=fact-boundary.js.map

package/dist/governance/fact-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-boundary.js","sourceRoot":"","sources":["../../src/governance/fact-boundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAyCH,SAAS,cAAc,CAAC,KAAc,EAAE,IAAoC;IAC1E,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAChE,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,GAAG,IAAI,MAAM,CAAC,MAAM;gBAAE,OAAO,KAAK,CAAC;QACzG,CAAC;aAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;YACvC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,GAAI,MAA+C,CAAC,GAAG,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,aAAa,CAAC,QAAkB,EAAE,UAA6C;IACtF,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,gBAAgB,QAAQ,CAAC,GAAG,oDAAoD,CAAC;IAC1F,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/E,OAAO,gBAAgB,QAAQ,CAAC,GAAG,SAAS,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,6CAA6C,CAAC;IACzH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAkB,EAAE,GAAgB;IACpE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAEtE,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAoB,EAAE,CAAC;IAErC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,4BAA4B,CAAC,EAAE,CAAC,CAAC;YAClE,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS;aAC5B,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;aACtD,MAAM,CAAC,CAAC,MAAM,EAAoB,EAAE,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC;QAEzD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAChC,CAAC"}

package/dist/governance/finding-funnel.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The governance funnel — architecture §20.1.
+ *
+ * > *"Without this layer, a run that surfaces 200 findings gets read by
+ * > nobody. Volume without governance is functionally the same as no output at
+ * > all."*
+ *
+ * §20.1 draws a five-filter funnel ending in a hard cap. Two of its boxes had
+ * no implementation anywhere: **F2, "known false positives from the feedback
+ * store,"** and **the HARD CAP itself**, whose value architecture §32 item 6
+ * has carried as a blank since the document was written (*"Hard cap value —
+ * how many findings is 'a few'"*, Tuning, *"set from early runs"*).
+ *
+ * `CLAUDE.md` rule 5 — *"a few high-confidence findings, never an exhaustive
+ * maybe-list"* — is the rule aimed most directly at what this whole category
+ * of tool gets wrong, and it was the one rule with no number behind it. Three
+ * per-check caps of 25 existed (`contracts/orphans.ts`, `validation/rollback.ts`,
+ * `validation/env.ts`), which is not the same thing: three checks at 25 present
+ * 75 items and nothing objects.
+ *
+ * ## The cap values, and where they come from
+ *
+ * §20.1 states its own worked example in prose: *"Twenty-seven possible issues
+ * get ignored. Three confirmed issues plus two worth checking get acted on
+ * immediately."* **Three plus two is five**, and that is `pr`'s cap — read off
+ * the architecture rather than invented.
+ *
+ * The other three are scaled to their trigger the same way `NODE_BUDGETS`
+ * already is, and for the same reason: an IDE hover and a nightly sweep are
+ * not the same reading surface. **Starting values, not measurements** —
+ * `CLAUDE.md`'s standing convention for every number in this project.
+ *
+ * ## What this module deliberately does not own
+ *
+ * - **It does not assign a category.** Only G4 does (`ai-governance-spec.md`
+ *   §11). This runs strictly after, on already-categorised findings, and
+ *   reorders and truncates them without touching a single field.
+ * - **It does not store dismissals.** `isDismissed` is a caller-supplied
+ *   predicate. The ledger is `descry-desktop`'s (§21.3 puts the feedback store
+ *   next to the runs it belongs to); the *filter* is governance and belongs
+ *   here, next to G1–G4.
+ * - **It never silently drops anything.** Every finding that entered leaves in
+ *   exactly one of `reported` / `unconfirmed` / `suppressed`, and the count it
+ *   truncated is a structured field with a rendered sentence — the same rule
+ *   `ai-tool-contract.md` §4 technique 5 applies one layer down (*"a capped
+ *   result that looks complete is the same defect as a zero that looks like a
+ *   finding"*).
+ */
+import { type Finding } from "@descryy/ir";
+import type { Trigger } from "../scoping/tiers.ts";
+/**
+ * How many findings one run may report, per trigger.
+ *
+ * `pr` is architecture §20.1's own arithmetic (3 confirmed + 2 worth
+ * checking). The rest are scaled to the reading surface, the same shape
+ * `NODE_BUDGETS` uses, and are starting values pending real runs to tune from.
+ */
+export declare const FINDING_CAPS: {
+    /** A hover is one line of screen. More than one finding there is a list nobody reads. */
+    readonly "ide-hover": 1;
+    /** A developer is mid-push and blocked. Only the strongest survive. */
+    readonly "pre-push": 3;
+    /** §20.1's own worked example. */
+    readonly pr: 5;
+    /** Someone opened a report deliberately and is reading it. Looser, still capped. */
+    readonly nightly: 10;
+};
+export interface FindingFunnelOptions {
+    readonly trigger: Trigger;
+    /**
+     * F2. `true` suppresses the finding. Supplied by the caller's feedback store
+     * — see the module doc for why the ledger is not here.
+     */
+    readonly isDismissed?: (finding: Finding) => boolean;
+    /** Overrides the trigger's cap. For a caller that has measured its own; not a way to opt out. */
+    readonly cap?: number;
+}
+export interface FindingTruncation {
+    readonly total: number;
+    readonly shown: number;
+    readonly dropped: number;
+    /** A rendered sentence when anything was dropped, `null` when nothing was. Never omitted silently. */
+    readonly disclosure: string | null;
+}
+export interface FindingFunnelResult {
+    /** The capped, ranked, confident list — what a developer reads first. */
+    readonly reported: readonly Finding[];
+    /** §20.1's own parallel list. Not capped: it is already labelled as unproven. */
+    readonly unconfirmed: readonly Finding[];
+    /** Removed by F2, kept so the run can say what it hid and why that is not a silence. */
+    readonly suppressed: readonly Finding[];
+    readonly truncation: FindingTruncation;
+}
+/**
+ * Run §20.1's funnel over one run's findings.
+ *
+ * Pure and total: same input, same output, and every input finding appears in
+ * exactly one output list. Deterministic ordering — required by
+ * `ai-layer-plan.md` §9 layer 6's replay guarantee, so ties break on the
+ * finding's own fingerprint rather than on input order.
+ */
+export declare function runFindingFunnel(findings: readonly Finding[], options: FindingFunnelOptions): FindingFunnelResult;
+/**
+ * Re-exported so a caller wiring the funnel and its ledger imports one module.
+ * The implementation lives in `@descryy/ir`'s identity module — see
+ * `DEC-NEXT-edge-id-prefix-split` for why an identity gets exactly one home.
+ */
+export { findingFingerprint } from "@descryy/ir";
+//# sourceMappingURL=finding-funnel.d.ts.map