@descryy/core 0.3.0 → 0.5.0

package/dist/scoping/weights.js

@@ -1,65 +1,11 @@
 /**
- * Scoring configuration for diff scoping — §12.4.
- *
- * ## The one number in the architecture that cannot be used as written
- *
- * §12.3's worked example decays a `CALLS` edge by **×1.0** on its first hop and
- * by **×0.95** on its third. The 0.95 is the usable one; 1.0 is not, for two
- * independent reasons:
- *
- * 1. **It breaks the premise of the whole engine.** §12.2 argues that hop count
- *    is a poor proxy for importance and that expansion must stop on *score*. An
- *    edge weight of 1.0 means a `CALLS` chain never decays — every node reachable
- *    by calls scores exactly 1.0 forever, so the stopping rule degenerates into
- *    "stop when the budget runs out", which is hop-count scoping wearing a
- *    different name.
- * 2. **It does not terminate.** With `EdgeConfidence` at 1.0 for an R3 edge, the
- *    hop factor is exactly 1.0, and on a `CALLS` cycle the traversal never ends.
- *    DEC-028 requires the factor to be strictly inside (0, 1).
- *
- * The defaults below therefore use 0.95, and §12.3's stated outcome still holds:
- * the payment gateway three hops out survives and `logger.ts` two hops out is
- * dropped. That test discriminates on the *shape* of the decay, not on whether
- * the first hop was 1.00 or 0.95.
- *
- * ## Three parts of the architecture cannot all be true — and the resolution
- *
- * Writing this file surfaced a genuine inconsistency between §12.3, §12.4 and
- * §12.7. Any two can hold; all three cannot.
- *
- * - **§12.3** needs *high* weights. Its worked example decays `CALLS` and
- *   `PROPAGATES_TO` at ~0.95 so a three-hop chain still scores 0.90.
- * - **§12.7** tiers on *absolute* thresholds — tier 2 above 0.7, tier 4 below
- *   0.3 — which are only meaningful if a few hops of a strong edge stay high.
- *   Scale the weights down for headroom and the payment gateway §12.3 calls
- *   critical lands in tier 4, "dropped under budget pressure".
- * - **§12.4** multiplies by `ChangeCouplingFactor` and
- *   `IncidentCorrelationFactor` *at every hop*, and both are boosts above 1.0.
- *   A weight of 0.95 with any coupling above 1.053 makes the hop factor exceed
- *   1.0, at which point the score stops decaying and a cycle never terminates.
- *
- * **Resolution: the history factors adjust a node's score once, they do not
- * compound per hop.** Path decay is the product of `edgeWeight × confidence`
- * over the hops, strictly below 1 at every step, so termination is structural.
- * Coupling and incident are then applied to the node's final score.
- *
- * This keeps §12.3's numbers exactly, keeps §12.7's thresholds meaningful, and
- * keeps §12.4's terms doing the work they were introduced for. It is also more
- * defensible than the literal formula: compounding a node's incident history at
- * every hop of a path that merely *passes through* it counts the same evidence
- * repeatedly, which the multiplicative form does silently. See DEC-037.
+ * Diff-scoping weights (§12.4). §12.3's worked example uses ×1.0 for a CALLS hop, which is unusable: it never decays and doesn't terminate on a cycle. DEC-028 requires the edge factor strictly inside (0, 1); defaults use 0.95.
+ * §12.3 (high weights), §12.7 (absolute tier thresholds) and §12.4 (per-hop coupling/incident boosts) can't all hold at once — resolved by applying coupling/incident once to a node's final score, not per hop, so path decay stays structurally below 1 and terminates (DEC-037).
  */
 import { EDGE_TYPES } from "@descryy/ir";
 import { DEFAULT_FANOUT_BUCKETS, maxAttenuation } from "./fanout.js";
-/**
- * Default weights.
- *
- * **Tuning, not architecture.** §12 is marked `DECIDED, TUNING OPEN` and §32
- * items 1 and 4 list edge weights as values to set from real traversal data.
- * These are starting points chosen to reproduce §12.3's example, and the three
- * that matter are the ones that example names: `CALLS`, `PROPAGATES_TO` and
- * `IMPORTS`.
- */
+/** Default weights — tuning, not architecture (§12 `DECIDED, TUNING OPEN`, §32
+ *  items 1/4). Starting points chosen to reproduce §12.3's example. */
 export const DEFAULT_EDGE_WEIGHTS = {
     // Structural: a change here really does reach the other side.
     CALLS: 0.95,
@@ -69,21 +15,15 @@ export const DEFAULT_EDGE_WEIGHTS = {
     RETURNS: 0.85,
     WRITES: 0.8,
     READS: 0.75,
-    // A shape dependency is structural and real — change the type and the
-    // declaration that embeds it may stop compiling — but it is weaker than a
-    // call: the dependant names the type, it does not execute anything. Placed
-    // between READS and IMPLEMENTS, and provisional like every other value here.
+    // Shape dependency: structural but weaker than a call (names the type, doesn't execute it).
     USES_TYPE: 0.7,
     IMPLEMENTS: 0.7,
     INHERITS: 0.7,
-    // §12.3's example: an import is a weak signal and must decay fast, or
-    // `logger.ts` survives and the engine reports noise as impact.
+    // §12.3's example: must decay fast or `logger.ts` survives as noise.
     IMPORTS: 0.4,
-    // Tests are reached deliberately by the test-discovery query rather than by
-    // impact decay, so this only needs to be non-zero.
+    // Reached deliberately by test-discovery, not impact decay — just needs non-zero.
     TESTS: 0.5,
-    // History, not structure. Everything from the git source is R0 and capped at
-    // 0.5 confidence already (DEC-019); a low weight keeps it as a hint.
+    // History not structure; R0, already capped at 0.5 confidence (DEC-019) — low weight keeps it a hint.
     CHANGES_WITH: 0.35,
     INCIDENT_CORRELATED: 0.3,
     FIXED_BY: 0.3,
@@ -94,21 +34,14 @@ export const DEFAULT_SCOPING_CONFIG = {
     maxCouplingFactor: 1.3,
     maxIncidentFactor: 1.2,
     maxScore: 1,
-    // §12.3's example drops `logger.ts` at 0.16 and keeps `utils.ts` at 0.40, so
-    // the prune point sits between them. Above it, §12.7's tier 4 (below 0.3) is
-    // kept but is the first thing budget pressure discards.
+    // Between §12.3's dropped logger.ts (0.16) and kept utils.ts (0.40).
     threshold: 0.2,
 };
 export class ScopingConfigError extends Error {
     name = "ScopingConfigError";
 }
-/**
- * Refuse a configuration that could fail to terminate — DEC-028's config-load half.
- *
- * The check is per edge type because the failure is: one type's weight, boosted
- * to its declared maxima, reaching 1.0. A global average would hide exactly the
- * case that matters.
- */
+/** Refuses a config that could fail to terminate (DEC-028's config-load half).
+ *  Checked per edge type — a global average would hide one type reaching 1.0. */
 export function validateScopingConfig(config) {
     if (!(config.maxScore > 0) || config.maxScore > 1) {
         throw new ScopingConfigError(`maxScore must be within (0, 1]; got ${config.maxScore}`);
@@ -120,7 +53,7 @@ export function validateScopingConfig(config) {
     if (!(config.threshold > 0) || config.threshold >= 1) {
         throw new ScopingConfigError(`threshold must be within (0, 1); got ${config.threshold}`);
     }
-    // DEC-067's table, checked before it can reach the termination assertion.
+    // DEC-067's table, checked before the termination assertion.
     const buckets = config.fanOutBuckets;
     if (buckets.length === 0) {
         throw new ScopingConfigError("fanOutBuckets must not be empty; use a single open bucket to disable attenuation");
@@ -140,13 +73,8 @@ export function validateScopingConfig(config) {
     if (buckets[buckets.length - 1].upTo !== Number.POSITIVE_INFINITY) {
         throw new ScopingConfigError(`the last fan-out bucket must be open (upTo: Infinity), or a node above ${previous} falls in no bucket`);
     }
-    // DEC-028's config-load half, widened by DEC-067. Because history factors no
-    // longer compound per hop, the requirement is on the weight alone — and
-    // `maxConfidence` is 1.0 by definition, so a weight of 1.0 is exactly the
-    // non-terminating case. Attenuation multiplies into the same product, so a
-    // multiplier above 1.0 would make a weight that decays on its own stop
-    // decaying in transit. DEC-067 requires this check to widen *before* such a
-    // value ships, so it is written now while every multiplier is still <= 1.
+    // DEC-028's config-load half, widened by DEC-067: weight × maxAttenuation ×
+    // maxConfidence(1.0) must stay < 1, since history factors no longer compound per hop.
     const largest = maxAttenuation(buckets);
     const offenders = [];
     for (const type of EDGE_TYPES) {

package/dist/scoping/weights.js.map

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

package/dist/sources/confirmed/incidents.d.ts

@@ -1,38 +1,8 @@
-/**
- * The `IRSource` that projects developer-confirmed incidents into the graph.
- *
- * ## Why a source, and not a direct write
- *
- * A `ConfirmedIncident` lives in `.descry/config.json` because it is testimony
- * — a developer fixed something and said so, and no commit records that they
- * said it (see the type's own doc). But a store is derived data: DEC-017 drops
- * every derived table on a schema change and rebuilds from source. So a
- * confirmed incident written *only* into the graph would survive until the next
- * IR-version bump and then vanish, which is the failure the EARNED partition
- * exists to prevent — arriving through a writer that simply did not think about
- * it.
- *
- * Making this a source solves it by construction. The file is the record; the
- * graph is a projection of the record; every `analyze` re-projects. There is no
- * migration to write and no earned table to extend, and the same discipline
- * every other producer in this system already follows applies unchanged: a
- * batch in, `writeBatch` out, invalidation by producer id.
- *
- * ## Identity
- *
- * The `INCIDENT` node keys on `confirmed:<confirmedAt>:<summary>` — the moment
- * the developer said it, plus what they said. Deliberately **not** the file set:
- * node ids never contain a path (renames churn them and silently destroy
- * incident links), and a developer correcting the file list of an incident they
- * already recorded is editing one incident rather than creating a second.
- *
- * ## What it does not do
- *
- * It mints no `FIX_PATTERN` unless the record names a fixing commit, and it
- * never infers one from HEAD. "The developer confirmed an incident" and "the
- * developer confirmed which commit fixed it" are separate claims, and only the
- * second one licenses a `FIXED_BY` edge.
- */
+/** IRSource projecting developer-confirmed incidents (`.descry/config.json`)
+ *  into the graph. A source, not a direct write: a store is derived data
+ *  (DEC-017 drops it on schema bump), so a direct write would silently
+ *  vanish. `INCIDENT` keys on `confirmed:<at>:<summary>`, never the file
+ *  set (no paths in node ids). Mints `FIX_PATTERN` only when a commit is named — never inferred from HEAD. */
 import { type ConfirmedIncident, type IdentityScope, type IRSource } from "@descryy/ir";
 export declare const CONFIRMED_INCIDENT_SOURCE_ID = "confirmed-incidents";
 export declare const CONFIRMED_INCIDENT_SOURCE_VERSION = "0.1.0";

package/dist/sources/confirmed/incidents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"incidents.d.ts","sourceRoot":"","sources":["../../../src/sources/confirmed/incidents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAIlB,KAAK,QAAQ,EAEd,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,4BAA4B,wBAAwB,CAAC;AAClE,eAAO,MAAM,iCAAiC,UAAU,CAAC;AAGzD,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAClD;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAE7F;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,GAAG,QAAQ,CA0I/F"}
+{"version":3,"file":"incidents.d.ts","sourceRoot":"","sources":["../../../src/sources/confirmed/incidents.ts"],"names":[],"mappings":"AAAA;;;;8GAI8G;AAE9G,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAIlB,KAAK,QAAQ,EAEd,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,4BAA4B,wBAAwB,CAAC;AAClE,eAAO,MAAM,iCAAiC,UAAU,CAAC;AAGzD,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAClD;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAE7F;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,GAAG,QAAQ,CAsI/F"}

package/dist/sources/confirmed/incidents.js

@@ -1,38 +1,8 @@
-/**
- * The `IRSource` that projects developer-confirmed incidents into the graph.
- *
- * ## Why a source, and not a direct write
- *
- * A `ConfirmedIncident` lives in `.descry/config.json` because it is testimony
- * — a developer fixed something and said so, and no commit records that they
- * said it (see the type's own doc). But a store is derived data: DEC-017 drops
- * every derived table on a schema change and rebuilds from source. So a
- * confirmed incident written *only* into the graph would survive until the next
- * IR-version bump and then vanish, which is the failure the EARNED partition
- * exists to prevent — arriving through a writer that simply did not think about
- * it.
- *
- * Making this a source solves it by construction. The file is the record; the
- * graph is a projection of the record; every `analyze` re-projects. There is no
- * migration to write and no earned table to extend, and the same discipline
- * every other producer in this system already follows applies unchanged: a
- * batch in, `writeBatch` out, invalidation by producer id.
- *
- * ## Identity
- *
- * The `INCIDENT` node keys on `confirmed:<confirmedAt>:<summary>` — the moment
- * the developer said it, plus what they said. Deliberately **not** the file set:
- * node ids never contain a path (renames churn them and silently destroy
- * incident links), and a developer correcting the file list of an incident they
- * already recorded is editing one incident rather than creating a second.
- *
- * ## What it does not do
- *
- * It mints no `FIX_PATTERN` unless the record names a fixing commit, and it
- * never infers one from HEAD. "The developer confirmed an incident" and "the
- * developer confirmed which commit fixed it" are separate claims, and only the
- * second one licenses a `FIXED_BY` edge.
- */
+/** IRSource projecting developer-confirmed incidents (`.descry/config.json`)
+ *  into the graph. A source, not a direct write: a store is derived data
+ *  (DEC-017 drops it on schema bump), so a direct write would silently
+ *  vanish. `INCIDENT` keys on `confirmed:<at>:<summary>`, never the file
+ *  set (no paths in node ids). Mints `FIX_PATTERN` only when a commit is named — never inferred from HEAD. */
 import { fileQsp, nodeId, } from "@descryy/ir";
 export const CONFIRMED_INCIDENT_SOURCE_ID = "confirmed-incidents";
 export const CONFIRMED_INCIDENT_SOURCE_VERSION = "0.1.0";
@@ -50,9 +20,8 @@ export function createConfirmedIncidentSource(options) {
             // INCIDENT and FIX_PATTERN are workspace-scoped (DEC-054), FILE is
             // repo-scoped, and `scopeOf` picks between them per type.
             const scope = { repo, workspace: ctx.root.workspace };
-            // A record for another repository is not this batch's business. The
-            // structural refusal `applyConfirmedFacts` makes for the same reason:
-            // never an inference about a second case.
+            // A record for another repo is not this batch's business — same
+            // structural refusal `applyConfirmedFacts` makes: never infer across cases.
             const mine = options.incidents.filter((i) => i.repo === repo);
             const nodes = [];
             const edges = [];
@@ -69,9 +38,8 @@ export function createConfirmedIncidentSource(options) {
                     name: path.split("/").pop() ?? path,
                     file: path,
                     range: null,
-                    // A developer naming a path says nothing about what language it is
-                    // written in, and guessing from the extension would be a language
-                    // decision made where none may be made (DEC-026).
+                    // A path says nothing about language; guessing from extension would
+                    // be a language decision made where none may be made (DEC-026).
                     language: null,
                     producedBy: PRODUCED_BY,
                     resolution: 0,
@@ -90,9 +58,8 @@ export function createConfirmedIncidentSource(options) {
                     producedBy: PRODUCED_BY,
                     resolution: 0,
                     attrs: {
-                        // The record's own shape decides this, never the caller: a run id
-                        // is present exactly when a run witnessed the failure, and absent
-                        // exactly when a person asserted it.
+                        // The record's own shape decides this: a run id present means a
+                        // run witnessed it, absent means a person asserted it.
                         detectedVia: incident.observedInRun === undefined ? "developer-confirmed" : "runtime-observed",
                         ...(incident.observedInRun === undefined ? {} : { observedInRun: incident.observedInRun }),
                         confirmedBy: incident.confirmedBy,
@@ -158,10 +125,9 @@ export function createConfirmedIncidentSource(options) {
                 producedBy: PRODUCED_BY,
                 sourceFiles,
                 skippedFiles: [],
-                // R0. A person's sentence is not a resolution level at all — the
-                // reliability consequence lives in `humanAsserted` (DEC-223), a second
-                // and independent ceiling, and slotting testimony into the R0–R4 ladder
-                // to express it would be the overclaim that ladder exists to prevent.
+                // R0: a person's sentence isn't a resolution level. The reliability
+                // consequence lives in `humanAsserted` (DEC-223), a separate ceiling —
+                // slotting testimony into R0-R4 would be the overclaim the ladder prevents.
                 reachedResolution: 0,
                 nodes,
                 edges,

package/dist/sources/confirmed/incidents.js.map

@@ -1 +1 @@
-{"version":3,"file":"incidents.js","sourceRoot":"","sources":["../../../src/sources/confirmed/incidents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EACL,OAAO,EACP,MAAM,GASP,MAAM,aAAa,CAAC;AAErB,MAAM,CAAC,MAAM,4BAA4B,GAAG,qBAAqB,CAAC;AAClE,MAAM,CAAC,MAAM,iCAAiC,GAAG,OAAO,CAAC;AACzD,MAAM,WAAW,GAAG,GAAG,4BAA4B,IAAI,iCAAiC,EAAE,CAAC;AAQ3F,2EAA2E;AAC3E,MAAM,UAAU,mBAAmB,CAAC,KAAoB,EAAE,QAA2B;IACnF,OAAO,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,aAAa,QAAQ,CAAC,WAAW,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,CAAC;AAClG,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,OAAuC;IACnF,OAAO;QACL,EAAE,EAAE,4BAA4B;QAChC,OAAO,EAAE,iCAAiC;QAE1C,IAAI,CAAC,GAAoB;YACvB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YAC3C,mEAAmE;YACnE,0DAA0D;YAC1D,MAAM,KAAK,GAAkB,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YAErE,oEAAoE;YACpE,sEAAsE;YACtE,0CAA0C;YAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;YAE9D,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,MAAM,UAAU,GAAoB,EAAE,CAAC;YACvC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;YAElC,KAAK,MAAM,QAAQ,IAAI,IAAI;gBAAE,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK;oBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClF,MAAM,WAAW,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;YAExC,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;gBAC/B,KAAK,CAAC,IAAI,CAAC;oBACT,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;oBAC9C,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,IAAI;oBACnC,IAAI,EAAE,IAAI;oBACV,KAAK,EAAE,IAAI;oBACX,mEAAmE;oBACnE,kEAAkE;oBAClE,kDAAkD;oBAClD,QAAQ,EAAE,IAAI;oBACd,UAAU,EAAE,WAAW;oBACvB,UAAU,EAAE,CAAC;oBACb,KAAK,EAAE,EAAE;iBACV,CAAC,CAAC;YACL,CAAC;YAED,KAAK,MAAM,QAAQ,IAAI,IAAI,EAAE,CAAC;gBAC5B,MAAM,UAAU,GAAG,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACxD,KAAK,CAAC,IAAI,CAAC;oBACT,EAAE,EAAE,UAAU;oBACd,IAAI,EAAE,UAAU;oBAChB,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;oBACpC,IAAI,EAAE,IAAI;oBACV,KAAK,EAAE,IAAI;oBACX,QAAQ,EAAE,IAAI;oBACd,UAAU,EAAE,WAAW;oBACvB,UAAU,EAAE,CAAC;oBACb,KAAK,EAAE;wBACL,kEAAkE;wBAClE,kEAAkE;wBAClE,qCAAqC;wBACrC,WAAW,EAAE,QAAQ,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,kBAAkB;wBAC9F,GAAG,CAAC,QAAQ,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,QAAQ,CAAC,aAAa,EAAE,CAAC;wBAC1F,WAAW,EAAE,QAAQ,CAAC,WAAW;wBACjC,WAAW,EAAE,QAAQ,CAAC,WAAW;wBACjC,kEAAkE;wBAClE,2CAA2C;wBAC3C,GAAG,CAAC,QAAQ,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC;wBAC9E,GAAG,CAAC,QAAQ,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,QAAQ,CAAC,aAAa,EAAE,CAAC;qBAC3F;iBACF,CAAC,CAAC;gBAEH,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;oBACvD,KAAK,CAAC,IAAI,CAAC;wBACT,IAAI,EAAE,UAAU;wBAChB,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;wBAC9C,IAAI,EAAE,qBAAqB;wBAC3B,UAAU,EAAE,CAAC;wBACb,UAAU,EAAE,CAAC;wBACb,UAAU,EAAE,WAAW;wBACvB,KAAK,EAAE;4BACL,WAAW,EACT,QAAQ,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,kBAAkB;yBACpF;qBACF,CAAC,CAAC;gBACL,CAAC;gBAED,sEAAsE;gBACtE,wEAAwE;gBACxE,IAAI,QAAQ,CAAC,aAAa,KAAK,SAAS;oBAAE,SAAS;gBACnD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;gBACzE,KAAK,CAAC,IAAI,CAAC;oBACT,EAAE,EAAE,KAAK;oBACT,IAAI,EAAE,aAAa;oBACnB,IAAI,EAAE,YAAY,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;oBAClD,IAAI,EAAE,IAAI;oBACV,KAAK,EAAE,IAAI;oBACX,QAAQ,EAAE,IAAI;oBACd,UAAU,EAAE,WAAW;oBACvB,UAAU,EAAE,CAAC;oBACb,KAAK,EAAE;wBACL,SAAS,EAAE,QAAQ,CAAC,aAAa;wBACjC,WAAW,EACT,QAAQ,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,kBAAkB;qBACpF;iBACF,CAAC,CAAC;gBACH,KAAK,CAAC,IAAI,CAAC;oBACT,IAAI,EAAE,UAAU;oBAChB,EAAE,EAAE,KAAK;oBACT,IAAI,EAAE,UAAU;oBAChB,UAAU,EAAE,CAAC;oBACb,UAAU,EAAE,CAAC;oBACb,UAAU,EAAE,WAAW;oBACvB,KAAK,EAAE;wBACL,WAAW,EACT,QAAQ,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,kBAAkB;qBACpF;iBACF,CAAC,CAAC;YACL,CAAC;YAED,oEAAoE;YACpE,yEAAyE;YACzE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAC/C,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YAE7F,OAAO,OAAO,CAAC,OAAO,CAAC;gBACrB,IAAI;gBACJ,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;gBACxE,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS;gBAC7B,UAAU,EAAE,WAAW;gBACvB,WAAW;gBACX,YAAY,EAAE,EAAE;gBAChB,iEAAiE;gBACjE,uEAAuE;gBACvE,wEAAwE;gBACxE,sEAAsE;gBACtE,iBAAiB,EAAE,CAAC;gBACpB,KAAK;gBACL,KAAK;gBACL,UAAU;aACX,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"incidents.js","sourceRoot":"","sources":["../../../src/sources/confirmed/incidents.ts"],"names":[],"mappings":"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"}

package/dist/sources/git/diff.d.ts

@@ -1,48 +1,9 @@
 /**
- * `gitDiff` — a live textual diff between two refs. §18's `get_git_diff`.
- *
- * `changedFiles` (`history.ts`) already answers "which files changed" — a
- * bare path list. This answers "what changed in them" — per-file status and
- * line counts always, plus the actual unified-diff patch text when it is
- * cheap enough to hand to a model. §4's own worry ("the client's context
- * window is not yours to spend") is the reason a patch is never returned
- * unconditionally: a single large file rewrite can be tens of thousands of
- * tokens, and a caller that wanted only "did this file change and how much"
- * pays that cost with no way to decline it. `patchOmittedReason` names why,
- * rather than silently shrinking the reply — the empty-denominator rule
- * applies to a dropped patch exactly as it does to a dropped finding.
- *
- * Two size caps here, because one of them bounds nothing on its own:
- * `maxPatchBytes` per file, and `maxTotalPatchBytes` across every patch in the
- * reply. The second exists because a real 48-file branch diff, with 44 patches
- * each *under* the per-file cap, summed to 229KB and hard-failed the call —
- * the reply never reached the caller at all, which is the one failure mode a
- * disclosure cannot repair after the fact.
- *
- * And a third above this file, for the same reason one level out: the same
- * diff re-run with `maxTotalPatchBytes` correctly enforced still failed, at
- * 84,516 characters, because these two caps bound patch text and a reply is
- * not only patch text. `MAX_REPLY_BYTES` and `ToolAnswer.fitToBudget` in the
- * MCP layer bound the serialized reply itself. Nothing here needs to know
- * about that; it is noted because "the aggregate cap is enforced" was once
- * mistaken for "the call now succeeds," and they are different claims.
- *
- * One `git diff` invocation for every file at once, not one per file — a
- * PR touching fifty files would otherwise spawn fifty processes. The output
- * is a concatenation of per-file blocks, each beginning with a line
- * `diff --git a/<path> b/<path>`; parsing splits on that boundary and reads
- * the more specific `rename from`/`rename to`/`new file mode`/
- * `deleted file mode`/`Binary files … differ`/`---`/`+++` lines within each
- * block, which are unambiguous where the `diff --git` header line alone is
- * not (a path containing the literal substring `" b/"` defeats that header's
- * own regex — an accepted, narrow gap, not a silent one, since every other
- * line used here does not share it).
- */
-/**
- * The stable prefix of `patchOmittedReason` when the *total* budget, not the
- * per-file cap, is what withheld a patch. Exported so a caller can tell the
- * two apart without matching on prose it does not own.
+ * §18's `get_git_diff`: live diff, patch text only when cheap — `patchOmittedReason` names why otherwise.
+ * Two caps here (`maxPatchBytes` per file, `maxTotalPatchBytes` total) plus a third in the MCP layer
+ * (`MAX_REPLY_BYTES`) — measured real failures at 229KB and 84,516 chars before these existed.
  */
+/** Stable prefix of `patchOmittedReason` when the total budget, not the per-file cap, withheld a patch. */
 export declare const TOTAL_PATCH_BUDGET_REASON_PREFIX = "the reply's total patch budget";
 export interface GitDiffFile {
     /** Path as it is known after the change (the only path for A/M/D). */
@@ -64,35 +25,80 @@ export interface GitDiffOptions {
     readonly files?: readonly string[];
     /** A file's patch is omitted (stats are still reported) above this many bytes. Default 20,000. */
     readonly maxPatchBytes?: number;
-    /**
-     * The cap on the sum of all returned patches. Files past it keep their
-     * stats and name the budget as the reason. Default 40,000.
-     */
+    /** Cap on the sum of all returned patches; files past it keep their stats. Default 40,000. */
     readonly maxTotalPatchBytes?: number;
 }
-/**
- * `base...head` (three dots), matching `changedFiles`'s own reasoning: two
- * dots would include everything changed on `base` since the branch point,
- * misattributing someone else's history to this diff.
- */
+/** `base...head` (three dots) — two dots would include everything changed on `base` since the branch point. */
 export declare function gitDiff(cwd: string, base: string, head?: string, options?: GitDiffOptions): Promise<readonly GitDiffFile[]>;
 export interface GitWorkingTreeDiffOptions extends GitDiffOptions {
-    /**
-     * `"unstaged"` (default) — the working tree against the index (`git diff -M`),
-     * i.e. edits not yet `git add`-ed.
-     * `"staged"` — the index against `HEAD` (`git diff -M --cached`), i.e. what
-     * a commit right now would contain.
-     * `"all"` — the working tree against `HEAD` (`git diff -M HEAD`), staged and
-     * unstaged combined — everything not yet committed.
-     */
+    /** `"unstaged"` (default): tree vs. index. `"staged"`: index vs. HEAD. `"all"`: tree vs. HEAD (both). */
     readonly scope?: "unstaged" | "staged" | "all";
 }
 /**
- * The working-tree counterpart to {@link gitDiff}: a live diff against
- * uncommitted state, which no two-revision form of `git diff` can express
- * (`HEAD...HEAD` is empty by construction). Reuses the exact same block
- * parser, rename detection and patch cap `gitDiff` does — see
- * `DEC-NEXT-working-tree-diff-in-core` for why a second parser was rejected.
+ * Working-tree counterpart to {@link gitDiff}: a live diff against uncommitted state, which no
+ * two-revision `git diff` form can express. Reuses the same parser (`DEC-NEXT-working-tree-diff-in-core`).
  */
 export declare function gitWorkingTreeDiff(cwd: string, options?: GitWorkingTreeDiffOptions): Promise<readonly GitDiffFile[]>;
+export interface GitWorkingTreeChangeOptions extends GitWorkingTreeDiffOptions {
+    /**
+     * Include files git has never seen, as new-file patches.
+     *
+     * **Off by default**, so no existing caller changes behaviour by upgrading,
+     * and because it is a different question: the three scopes above all ask
+     * about files git already tracks.
+     */
+    readonly includeUntracked?: boolean;
+    /** Cap on untracked files diffed. The real count is reported regardless. */
+    readonly maxUntracked?: number;
+    /**
+     * Directory prefixes whose contents are not the change under review.
+     *
+     * The same argument as `--exclude-standard`, for state a `.gitignore` does not
+     * happen to cover. Descry writes its own graph database inside the repository
+     * and nothing gitignores it, so the first working-tree answer on a fresh
+     * checkout listed that database and its two SQLite sidecars as the
+     * developer's uncommitted change — three files they did not write, at the top
+     * of an answer about what they did.
+     *
+     * Matched as a path prefix at a segment boundary, so `.descry` excludes
+     * `.descry/graph.db` and not `src/.descryfile.ts`.
+     */
+    readonly exclude?: readonly string[];
+}
+export interface GitWorkingTreeChange {
+    readonly files: readonly GitDiffFile[];
+    /** Untracked files found, before any cap. */
+    readonly untrackedTotal: number;
+    /** True when the cap kept some of them out of `files`. */
+    readonly untrackedTruncated: boolean;
+}
+/**
+ * The working tree as a change set, including files git has never seen.
+ *
+ * ## Why untracked needs its own mechanism
+ *
+ * No form of `git diff` reports an untracked file. `git diff HEAD` compares
+ * against what the index and `HEAD` hold, and a file git has never seen is in
+ * neither — so a working-tree mode built on the scopes above alone still misses
+ * the most common shape of work in progress: a new file, written, not yet
+ * added. That is exactly the case this was built for.
+ *
+ * ## `--no-index` rather than `add -N`
+ *
+ * The usual trick is `git add -N` to give the file an intent-to-add entry, then
+ * diff normally. **It writes to the index**, and a read tool that mutates the
+ * caller's repository to answer a question is not a read tool — it would also
+ * race any real `git add` the developer runs while it works.
+ *
+ * `git diff --no-index -- /dev/null <path>` needs no index and emits exactly the
+ * `new file mode` block the shared parser already handles, with the real path.
+ * It exits non-zero when the files differ, which for this call is always, so a
+ * non-zero exit here is the success case and is read for its stdout.
+ *
+ * ## `--exclude-standard` is load-bearing
+ *
+ * Without it the first answer on any real repository is a dependency directory
+ * reported as the developer's uncommitted work.
+ */
+export declare function gitWorkingTreeChange(cwd: string, options?: GitWorkingTreeChangeOptions): Promise<GitWorkingTreeChange>;
 //# sourceMappingURL=diff.d.ts.map

package/dist/sources/git/diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/sources/git/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AA2CH;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,mCAAmC,CAAC;AAEjF,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,kGAAkG;IAClG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAmID;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,SAAS,EACb,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAEjC;AAED,MAAM,WAAW,yBAA0B,SAAQ,cAAc;IAC/D;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,QAAQ,GAAG,KAAK,CAAC;CAChD;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAIjC"}
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/sources/git/diff.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4BH,2GAA2G;AAC3G,eAAO,MAAM,gCAAgC,mCAAmC,CAAC;AAEjF,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,kGAAkG;IAClG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AA+HD,+GAA+G;AAC/G,wBAAsB,OAAO,CAC3B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,SAAS,EACb,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAEjC;AAED,MAAM,WAAW,yBAA0B,SAAQ,cAAc;IAC/D,yGAAyG;IACzG,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,QAAQ,GAAG,KAAK,CAAC;CAChD;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAIjC;AAKD,MAAM,WAAW,2BAA4B,SAAQ,yBAAyB;IAC5E;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CA6C/B"}