@descryy/core 0.3.0 → 0.5.0

package/dist/multipr/scope-store.js

@@ -1,64 +1,19 @@
 /**
- * §14.2 — persisting a change's scoped subgraph, and the one field that makes
- * two of them comparable.
- *
- * ## Why this is stored at all, when everything else derived is thrown away
- *
- * A scope looks derived. It is not, and the reason is easy to get backwards:
- * everything on the derived side regenerates because *the source still produces
- * it*. A PR scope was computed against a graph **at one commit**, and that graph
- * moves. Recomputing it later does not restore it — it answers a different
- * question and returns a plausible answer to it. Dropping it does not lose time,
- * it loses the comparison basis.
- *
- * That is why `pr_scopes` sits in `EARNED_TABLES` beside observed edges and
- * human corrections, and it is the weaker-looking member of that set in one
- * respect and the more dangerous in another: an R4 observation cannot be
- * recomputed at any price, whereas a PR scope can be recomputed **wrongly**.
- *
- * ## `graphCommitSha` is the whole design
- *
- * Two scopes are comparable only when they were computed against the same
- * graph. The schema puts that commit in the primary key so the same PR at two
- * graph states is two rows rather than one silently overwriting the other, and
- * indexes `(repo, graph_commit_sha)` because overlap scoring's only real query
- * is *every scope computed against one graph*.
- *
- * **It is a different commit from the PR's own head**, and this module renamed a
- * field to say so. `overlap.ts` originally carried one `baseSha` described as
- * "the base commit it was computed against", which is ambiguous between the two
- * and would have let a comparison key on the wrong one. The store's column
- * comment is what caught it.
- *
- * ## An incomparable pair and a non-conflicting pair look identical
- *
- * Both produce an empty overlap. The schema comment warns that a reader
- * ignoring `graph_commit_sha` "will happily overlap a scope from last week with
- * one from today and report a number" — so the refusal lives in `findOverlaps`
- * rather than here, where it also protects the caller who never touches a store.
+ * §14.2 — persisting a change's scoped subgraph. Looks derived but isn't: computed against a graph at one commit, and that graph moves — recomputing later answers a different question, so pr_scopes sits in EARNED_TABLES (worse than an R4 observation: it can be recomputed wrongly, not just never).
+ * graphCommitSha (distinct from the PR's head — a prior `baseSha` name was ambiguous) is in the primary key so two graph states are two rows, not an overwrite. An incomparable pair and a non-conflicting pair both produce empty overlap, so that refusal lives in findOverlaps, not here.
  */
 import { canonicalJson } from "@descryy/ir";
 const COLUMNS = "pr_id, repo, head_sha, graph_commit_sha, scope_json, node_count, computed_at";
-/**
- * Thrown when a stored scope cannot be turned back into one.
- *
- * A corrupt row is not an empty scope. Returning `[]` here would make a damaged
- * store indistinguishable from a PR that touched nothing, which is the
- * conflation §14.8 exists to refuse one layer up.
- */
+/** Thrown when a stored scope can't be decoded. A corrupt row is not an
+ *  empty scope — returning [] would conflate the two (§14.8 refuses this). */
 export class ScopeDecodeError extends Error {
     name = "ScopeDecodeError";
     constructor(message, options) {
         super(message, options);
     }
 }
-/**
- * `canonicalJson` throws on `undefined` rather than dropping the key, which is
- * the right call everywhere else in this project and means an optional field
- * cannot simply be handed to it. `file` is the only one, and it is genuinely
- * absent rather than null — a scope entry for a node the graph has no path for
- * is not a scope entry with a null path.
- */
+/** canonicalJson throws on undefined rather than dropping the key. `file` is
+ *  genuinely absent, not null — a no-path node isn't a null-path entry. */
 function encodeEntry(entry) {
     const encoded = {
         nodeId: entry.nodeId,
@@ -95,24 +50,16 @@ function decode(row) {
         computedAt: row.computed_at,
     };
 }
-/**
- * Row access for `pr_scopes`. Thin on purpose, in the style of `reader.ts`:
- * nothing here scores, compares or decides staleness.
- */
+/** Row access for pr_scopes. Thin on purpose (style of reader.ts): nothing
+ *  here scores, compares or decides staleness. */
 export class ScopeStore {
     #driver;
     constructor(driver) {
         this.#driver = driver;
     }
-    /**
-     * Write a scope, replacing any row for the same `(repo, prId, graphCommitSha)`.
-     *
-     * Replacement is safe **only** because the graph commit is in the key:
-     * recomputing the same PR against the same graph must produce the same scope,
-     * so the row being replaced is equal to the one replacing it. Recomputing
-     * against a *different* graph writes a new row and leaves the old comparison
-     * basis intact, which is the entire reason the column is in the key.
-     */
+    /** Write a scope, replacing any row for (repo, prId, graphCommitSha).
+     *  Safe only because the graph commit is in the key — a different graph
+     *  writes a new row and leaves the old comparison basis intact. */
     save(scope) {
         const json = canonicalJson(scope.entries.map(encodeEntry));
         this.#driver
@@ -137,27 +84,16 @@ export class ScopeStore {
             .get(repo, prId, graphCommitSha);
         return row === undefined ? undefined : decode(row);
     }
-    /**
-     * **The query overlap scoring is for**: every scope computed against one
-     * graph, and therefore every scope that can legitimately be compared.
-     *
-     * Ordered by `pr_id` so a report is stable across runs — an unordered read
-     * makes two identical graphs produce two differently-ordered reports and
-     * turns a diff into noise.
-     */
+    /** The query overlap scoring is for: every scope computed against one
+     *  graph. Ordered by pr_id so a report is stable across runs. */
     loadForGraph(repo, graphCommitSha) {
         return this.#driver
             .prepare(`SELECT ${COLUMNS} FROM pr_scopes WHERE repo = ? AND graph_commit_sha = ? ORDER BY pr_id`)
             .all(repo, graphCommitSha)
             .map(decode);
     }
-    /**
-     * Every graph state a PR has a scope for, newest computation first.
-     *
-     * Exposed because "this PR was scoped against three different graphs" is a
-     * fact a caller may need and cannot reconstruct from `load`, which requires
-     * knowing the commit in advance.
-     */
+    /** Every graph state a PR has a scope for, newest first — not reconstructable
+     *  from `load`, which requires knowing the commit in advance. */
     graphStatesFor(repo, prId) {
         return this.#driver
             .prepare(`SELECT graph_commit_sha, computed_at FROM pr_scopes
@@ -165,14 +101,8 @@ export class ScopeStore {
             .all(repo, prId)
             .map((r) => ({ graphCommitSha: r.graph_commit_sha, computedAt: r.computed_at }));
     }
-    /**
-     * Forget a PR entirely — every graph state it was scoped against.
-     *
-     * The only legitimate deletion: a closed or merged PR is not in flight and
-     * cannot conflict with anything. Deleting a *single* graph state is not
-     * offered, because the row is the comparison basis and there is no caller who
-     * wants exactly one of them gone.
-     */
+    /** Forget a PR entirely — every graph state it was scoped against. The only
+     *  legitimate deletion: a closed/merged PR can't conflict with anything. */
     forget(repo, prId) {
         return this.#driver
             .prepare("DELETE FROM pr_scopes WHERE repo = ? AND pr_id = ?")

package/dist/multipr/scope-store.js.map

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

package/dist/multipr/superseded.d.ts

@@ -1,79 +1,18 @@
 /**
- * §14.5 — a change whose work is already in base.
- *
- * The architecture gives one sentence: *"Compare a PR's resulting code
- * (post-diff) against current base. If functionally identical, flag as
- * superseded."* Everything below is what that sentence turns into once the
- * consequences of being wrong are taken seriously.
- *
- * ## This is the one check in §14 whose finding destroys work
- *
- * Every other multi-PR check tells someone to look at something. This one tells
- * them to **close a pull request**, and a wrong answer throws away work that
- * nobody has a copy of. §14.4's auto-apply path is the documented exception to
- * approval-before-code-change and is hedged with a mandatory verify-after; this
- * check has no such gate because the action it prompts is a human's.
- *
- * So the bar is asymmetric on purpose, and it is rule 2 applied to a finding
- * rather than to an edge: **a missed supersession costs a redundant review; a
- * false one costs the work.** Concretely, `superseded` is claimed only when
- * *every* touched node was compared and *every* comparison matched. One node
- * whose base state could not be read is enough to withhold the claim — and the
- * partial result is still reported, because "9 of 10 already landed" is useful
- * to the same reader and is a different sentence.
- *
- * ## Partial supersession is the common case, not an edge case
- *
- * The realistic history is that someone landed *most* of this work in another
- * change. A binary verdict answers that with `false` and discards the only
- * interesting part. So the report is a count and a list either way, and the
- * boolean is a summary of it rather than the result itself.
- *
- * ## Three states, again, and for the same reason
- *
- * A node whose base fingerprint is absent is not a node that differs. Both
- * would make `superseded` false, and only one of them is a statement about the
- * code — the other is a statement about the reading. `BaseState` therefore has
- * an explicit `"unknown"` rather than letting a missing fingerprint mean
- * "different", which is the shape this project has now paid for seven times.
- *
- * ## What "functionally identical" is allowed to mean here
- *
- * Whatever the caller's fingerprint says, and no more. This module compares
- * opaque strings; it does not normalise whitespace, sort imports or reason
- * about equivalence, because every one of those is a judgement about a language
- * and would put language knowledge above the IR boundary. A producer that
- * fingerprints a normalised AST and one that hashes raw bytes both work here,
- * and the report states which was used so a reader is never left to assume the
- * stronger one.
+ * §14.5: flag a change already landed on base. Asymmetric bar (rule 2) — a missed supersession costs a
+ * review, a false one destroys work — so `superseded` is true only when every node compared and matched.
+ * `BaseState` distinguishes "unknown" (unread) from "absent" (deleted); compares only opaque fingerprint strings, no normalisation (IR boundary).
  */
 import type { ReliabilityClass, ResolutionLevel } from "@descryy/ir";
 import type { DiffType } from "./overlap.ts";
-/**
- * One node the change touches, with the two states to compare.
- *
- * `after` is the node as the change leaves it. `base` is the same node on the
- * target branch **now** — not at the change's merge base, which is the whole
- * point: the question is whether this work is already there today.
- */
+/** One node the change touches. `base` is the target branch **now**, not at merge-base — is the work there today. */
 export interface SupersededCandidate {
     readonly nodeId: string;
     readonly file?: string | undefined;
     readonly diffType: DiffType;
-    /**
-     * Fingerprint of the node as this change leaves it, or `"absent"` when the
-     * change deletes it.
-     */
+    /** Fingerprint as this change leaves the node, or `"absent"` when it deletes it. */
     readonly after: string | "absent";
-    /**
-     * The same node on base today: a fingerprint, `"absent"` when base does not
-     * have it, or `"unknown"` when it could not be read.
-     *
-     * **`"absent"` and `"unknown"` are different.** A node base genuinely lacks
-     * matches a deletion; a node whose base state could not be read matches
-     * nothing, and the difference decides whether a human is told to close a
-     * change.
-     */
+    /** Base today: fingerprint, `"absent"` (base lacks it), or `"unknown"` (unreadable) — the two are never conflated. */
     readonly base: string | "absent" | "unknown";
     readonly resolution: ResolutionLevel;
 }
@@ -85,12 +24,7 @@ export interface NodeComparison {
     readonly verdict: NodeVerdict;
 }
 export interface SupersededReport {
-    /**
-     * True only when every touched node was compared and every one matched.
-     *
-     * A single `not-compared` node withholds this, however many matched — the
-     * finding it feeds tells a human to discard work.
-     */
+    /** True only when every touched node was compared and matched — one `not-compared` node withholds it. */
     readonly superseded: boolean;
     readonly comparisons: readonly NodeComparison[];
     readonly counts: {
@@ -99,35 +33,16 @@ export interface SupersededReport {
         readonly differs: number;
         readonly notCompared: number;
     };
-    /**
-     * False when there was nothing to compare.
-     *
-     * **Not the same as "not superseded".** A change with no candidates and a
-     * change whose every node differs both report `superseded: false`.
-     */
+    /** False when nothing was there to compare — not the same as "not superseded" (both report `superseded: false`). */
     readonly analysed: boolean;
     readonly reliability: ReliabilityClass;
     readonly disclosure: string;
     readonly notes: readonly string[];
 }
 export interface SupersededOptions {
-    /**
-     * How the caller's fingerprints were produced — "sha256 of raw bytes",
-     * "hash of normalised AST". Carried into the disclosure verbatim.
-     *
-     * Required in substance rather than in type: omitting it produces a
-     * disclosure that says the basis was not stated, because a reader who assumes
-     * AST normalisation when the producer hashed bytes will read a `differs` as
-     * meaningful when it was whitespace.
-     */
+    /** How fingerprints were produced (e.g. "sha256 of raw bytes"), carried into the disclosure verbatim. Omitting it says so. */
     readonly fingerprintBasis?: string;
 }
-/**
- * Whether a change's work is already present on base.
- *
- * Pure over candidates: no store, no graph, no language. The caller's producer
- * decides what a fingerprint means and at what resolution it was obtained; this
- * propagates both.
- */
+/** Whether a change's work is already present on base. Pure over candidates: no store, no graph, no language. */
 export declare function findSuperseded(candidates: readonly SupersededCandidate[], options?: SupersededOptions): SupersededReport;
 //# sourceMappingURL=superseded.d.ts.map

package/dist/multipr/superseded.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"superseded.d.ts","sourceRoot":"","sources":["../../src/multipr/superseded.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,SAAS,GAAG,cAAc,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAWD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,SAAS,mBAAmB,EAAE,EAC1C,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CA2ElB"}
+{"version":3,"file":"superseded.d.ts","sourceRoot":"","sources":["../../src/multipr/superseded.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,qHAAqH;AACrH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IAClC,sHAAsH;IACtH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,SAAS,GAAG,cAAc,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,yGAAyG;IACzG,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,oHAAoH;IACpH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,8HAA8H;IAC9H,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAUD,iHAAiH;AACjH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,SAAS,mBAAmB,EAAE,EAC1C,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAyElB"}

package/dist/multipr/superseded.js

@@ -1,71 +1,20 @@
 /**
- * §14.5 — a change whose work is already in base.
- *
- * The architecture gives one sentence: *"Compare a PR's resulting code
- * (post-diff) against current base. If functionally identical, flag as
- * superseded."* Everything below is what that sentence turns into once the
- * consequences of being wrong are taken seriously.
- *
- * ## This is the one check in §14 whose finding destroys work
- *
- * Every other multi-PR check tells someone to look at something. This one tells
- * them to **close a pull request**, and a wrong answer throws away work that
- * nobody has a copy of. §14.4's auto-apply path is the documented exception to
- * approval-before-code-change and is hedged with a mandatory verify-after; this
- * check has no such gate because the action it prompts is a human's.
- *
- * So the bar is asymmetric on purpose, and it is rule 2 applied to a finding
- * rather than to an edge: **a missed supersession costs a redundant review; a
- * false one costs the work.** Concretely, `superseded` is claimed only when
- * *every* touched node was compared and *every* comparison matched. One node
- * whose base state could not be read is enough to withhold the claim — and the
- * partial result is still reported, because "9 of 10 already landed" is useful
- * to the same reader and is a different sentence.
- *
- * ## Partial supersession is the common case, not an edge case
- *
- * The realistic history is that someone landed *most* of this work in another
- * change. A binary verdict answers that with `false` and discards the only
- * interesting part. So the report is a count and a list either way, and the
- * boolean is a summary of it rather than the result itself.
- *
- * ## Three states, again, and for the same reason
- *
- * A node whose base fingerprint is absent is not a node that differs. Both
- * would make `superseded` false, and only one of them is a statement about the
- * code — the other is a statement about the reading. `BaseState` therefore has
- * an explicit `"unknown"` rather than letting a missing fingerprint mean
- * "different", which is the shape this project has now paid for seven times.
- *
- * ## What "functionally identical" is allowed to mean here
- *
- * Whatever the caller's fingerprint says, and no more. This module compares
- * opaque strings; it does not normalise whitespace, sort imports or reason
- * about equivalence, because every one of those is a judgement about a language
- * and would put language knowledge above the IR boundary. A producer that
- * fingerprints a normalised AST and one that hashes raw bytes both work here,
- * and the report states which was used so a reader is never left to assume the
- * stronger one.
+ * §14.5: flag a change already landed on base. Asymmetric bar (rule 2) — a missed supersession costs a
+ * review, a false one destroys work — so `superseded` is true only when every node compared and matched.
+ * `BaseState` distinguishes "unknown" (unread) from "absent" (deleted); compares only opaque fingerprint strings, no normalisation (IR boundary).
  */
 import { reliabilityCap, reliabilityNote } from "@descryy/ir";
 function compare(c) {
     if (c.base === "unknown")
         return "not-compared";
-    // A deletion is superseded when base has already lost the node. `after` and
-    // `base` both being "absent" is a match, not two missing values.
+    // Both "absent" is a match (deletion already landed), not two missing values.
     if (c.after === "absent")
         return c.base === "absent" ? "already-in-base" : "differs";
     if (c.base === "absent")
         return "differs";
     return c.after === c.base ? "already-in-base" : "differs";
 }
-/**
- * Whether a change's work is already present on base.
- *
- * Pure over candidates: no store, no graph, no language. The caller's producer
- * decides what a fingerprint means and at what resolution it was obtained; this
- * propagates both.
- */
+/** Whether a change's work is already present on base. Pure over candidates: no store, no graph, no language. */
 export function findSuperseded(candidates, options = {}) {
     const notes = [];
     const comparisons = candidates.map((c) => ({
@@ -77,10 +26,8 @@ export function findSuperseded(candidates, options = {}) {
     const alreadyInBase = comparisons.filter((c) => c.verdict === "already-in-base").length;
     const differs = comparisons.filter((c) => c.verdict === "differs").length;
     const notCompared = comparisons.filter((c) => c.verdict === "not-compared").length;
-    // The weakest candidate decides, as everywhere else a claim rests on several
-    // observations. Whether two fingerprints are equal is a name-level fact — it
-    // is an identity of strings, not a claim about behaviour — so R2's carve-out
-    // applies and nothing here reaches beyond what its evidence bought.
+    // The weakest candidate decides. Fingerprint equality is a name-level fact
+    // (string identity, not behaviour), so R2's carve-out applies.
     const weakest = candidates.reduce((min, c) => (c.resolution < min ? c.resolution : min), 4);
     const reliability = reliabilityCap(weakest, true);
     let disclosure = reliabilityNote(weakest, true);

package/dist/multipr/superseded.js.map

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

package/dist/query/confirmed-facts.d.ts

@@ -1,43 +1,16 @@
-/**
- * DEC-223's answer half, matching side: which refusal-ledger rows does a
- * confirmed fact actually answer?
- *
- * Deliberately does **not** mint a graph edge. Turning an answered row into a
- * real `USES_API`/etc. edge needs a target to join against — an endpoint, a
- * route — which this function has no way to resolve and which DEC-223 §6
- * named as future work, not this row. What this function owns is narrower
- * and load-bearing on its own: **which rows are answered, by what value, and
- * that the match never crosses a repo or accessor boundary it should not.**
- * A caller minting an edge from `answered` is the one obligated to pass
- * `reliabilityCap`'s `humanAsserted: true` — this function does not compute a
- * reliability class itself, because it has no resolution level to reason
- * from (`UnresolvedRef` carries none — refusals are not edges and were never
- * scored). Inventing one here would be exactly the overclaim principle 2
- * exists to prevent.
- */
+/** DEC-223's matching half: which refusal-ledger rows a confirmed fact answers. Deliberately
+ *  doesn't mint a graph edge (no target to resolve — DEC-223 §6's future work). A caller minting
+ *  one must pass `reliabilityCap`'s `humanAsserted: true` itself — refusals carry no resolution level. */
 import type { ConfirmedFact, UnresolvedRef } from "@descryy/ir";
 export interface ConfirmedFactMatch {
     readonly ref: UnresolvedRef;
-    /**
-     * True when every fact in `facts` was confirmed in a *different* repository
-     * and reaches this one only because it was declared `scope: "workspace"`.
-     *
-     * Surfaced rather than folded away: "somebody answered this here" and
-     * "somebody answered this in the frontend and said it holds workspace-wide"
-     * are different facts about what the developer actually knows, and a caller
-     * that cannot tell them apart cannot disclose the difference.
-     */
+    /** True when every fact in `facts` was confirmed in a different repo, reaching this one only via
+     *  `scope: "workspace"`. Surfaced, not folded away — "answered here" and "answered elsewhere,
+     *  declared workspace-wide" are different facts a caller must be able to disclose. */
     readonly fromAnotherRepo: boolean;
-    /**
-     * Every fact sharing this row's `(repo, blockedBy)`, regardless of
-     * `environment` — never picks one. A row's own site carries no environment
-     * of its own (the code runs in whichever environment it is deployed to),
-     * so this function cannot know which of several environment-scoped facts
-     * applies; surfacing all of them lets a caller show the split rather than
-     * silently choosing a value that might be wrong for the environment the
-     * row actually runs in. Almost always length 1 — DEC-223's own measured
-     * cases were unscoped, single-fact answers — but never assumed to be.
-     */
+    /** Every fact sharing `(repo, blockedBy)`, regardless of environment — never picks one, since
+     *  this function can't know which environment-scoped fact applies. Surfacing all lets the caller
+     *  show the split. Almost always length 1 (DEC-223's measured cases), but never assumed to be. */
     readonly facts: readonly ConfirmedFact[];
 }
 export interface ConfirmedFactApplication {
@@ -46,27 +19,8 @@ export interface ConfirmedFactApplication {
     /** Every other row: unclassified, a different class than `"value-unknown"`, or no matching fact yet. */
     readonly stillOpen: readonly UnresolvedRef[];
 }
-/**
- * Match ledger rows against confirmed facts, scoped to one repository.
- *
- * Three things keep a row out of `answered`, all deliberate:
- *
- * 1. **No `attrs.refusalClass === "value-unknown"`.** Everything else —
- *    unclassified, `capability-gap`, `out-of-scope`, `varies-per-call` — is
- *    not askable at all (DEC-242), so no fact could ever answer it; matching
- *    on `blockedBy` alone without this check would let a stored fact silently
- *    resolve a `varies-per-call` row that structurally has no single answer.
- * 2. **No `attrs.blockedBy`, or it is not a string.** Nothing to key against.
- * 3. **No fact in `facts` reaches this repository.** A fact for a different
- *    `repo` is not consulted merely because its `blockedBy` text matches —
- *    rule 3's "never an inference about a second case," enforced structurally
- *    rather than left to caller discipline. The **one** way it crosses is
- *    `reaches()` below: the person recording it declared
- *    `scope: "workspace"` under the same workspace id this session is
- *    configured with. A declaration, not an inference — see
- *    DEC-NEXT-workspace-scoped-confirmed-facts for why the alternative
- *    (any fact answers any linked repo) is unsafe: two services can both read
- *    `DATABASE_URL` and mean different things by it.
- */
+/** Matches ledger rows to confirmed facts, scoped to one repo. Excluded from `answered`: not
+ *  `refusalClass === "value-unknown"` (everything else isn't askable at all, DEC-242); no
+ *  `blockedBy`; or no fact reaches this repo (rule 3 — crossing needs declared `scope: "workspace"`, never inferred). */
 export declare function applyConfirmedFacts(refs: readonly UnresolvedRef[], facts: readonly ConfirmedFact[], repo: string, workspace?: string): ConfirmedFactApplication;
 //# sourceMappingURL=confirmed-facts.d.ts.map

package/dist/query/confirmed-facts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"confirmed-facts.d.ts","sourceRoot":"","sources":["../../src/query/confirmed-facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;CAC1C;AAiBD,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACjD,wGAAwG;IACxG,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,aAAa,EAAE,EAC9B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,wBAAwB,CA4B1B"}
+{"version":3,"file":"confirmed-facts.d.ts","sourceRoot":"","sources":["../../src/query/confirmed-facts.ts"],"names":[],"mappings":"AAAA;;0GAE0G;AAE1G,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAC5B;;0FAEsF;IACtF,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;sGAEkG;IAClG,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;CAC1C;AAWD,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACjD,wGAAwG;IACxG,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;CAC9C;AAED;;yHAEyH;AACzH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,aAAa,EAAE,EAC9B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,wBAAwB,CA4B1B"}

package/dist/query/confirmed-facts.js

@@ -1,28 +1,8 @@
-/**
- * DEC-223's answer half, matching side: which refusal-ledger rows does a
- * confirmed fact actually answer?
- *
- * Deliberately does **not** mint a graph edge. Turning an answered row into a
- * real `USES_API`/etc. edge needs a target to join against — an endpoint, a
- * route — which this function has no way to resolve and which DEC-223 §6
- * named as future work, not this row. What this function owns is narrower
- * and load-bearing on its own: **which rows are answered, by what value, and
- * that the match never crosses a repo or accessor boundary it should not.**
- * A caller minting an edge from `answered` is the one obligated to pass
- * `reliabilityCap`'s `humanAsserted: true` — this function does not compute a
- * reliability class itself, because it has no resolution level to reason
- * from (`UnresolvedRef` carries none — refusals are not edges and were never
- * scored). Inventing one here would be exactly the overclaim principle 2
- * exists to prevent.
- */
-/**
- * Does this fact answer rows in `repo`?
- *
- * Its own repository, always. Any repository in the same workspace **only**
- * when it was recorded as `scope: "workspace"` and both sides carry the same
- * non-empty workspace id — an unset workspace on either side names no
- * boundary, so nothing crosses one.
- */
+/** DEC-223's matching half: which refusal-ledger rows a confirmed fact answers. Deliberately
+ *  doesn't mint a graph edge (no target to resolve — DEC-223 §6's future work). A caller minting
+ *  one must pass `reliabilityCap`'s `humanAsserted: true` itself — refusals carry no resolution level. */
+/** Does this fact answer rows in `repo`? Its own repo always; another repo only if recorded as
+ *  `scope: "workspace"` with both sides sharing the same non-empty workspace id. */
 function reaches(fact, repo, workspace) {
     if (fact.repo === repo)
         return true;
@@ -32,28 +12,9 @@ function reaches(fact, repo, workspace) {
         return false;
     return fact.workspace === workspace;
 }
-/**
- * Match ledger rows against confirmed facts, scoped to one repository.
- *
- * Three things keep a row out of `answered`, all deliberate:
- *
- * 1. **No `attrs.refusalClass === "value-unknown"`.** Everything else —
- *    unclassified, `capability-gap`, `out-of-scope`, `varies-per-call` — is
- *    not askable at all (DEC-242), so no fact could ever answer it; matching
- *    on `blockedBy` alone without this check would let a stored fact silently
- *    resolve a `varies-per-call` row that structurally has no single answer.
- * 2. **No `attrs.blockedBy`, or it is not a string.** Nothing to key against.
- * 3. **No fact in `facts` reaches this repository.** A fact for a different
- *    `repo` is not consulted merely because its `blockedBy` text matches —
- *    rule 3's "never an inference about a second case," enforced structurally
- *    rather than left to caller discipline. The **one** way it crosses is
- *    `reaches()` below: the person recording it declared
- *    `scope: "workspace"` under the same workspace id this session is
- *    configured with. A declaration, not an inference — see
- *    DEC-NEXT-workspace-scoped-confirmed-facts for why the alternative
- *    (any fact answers any linked repo) is unsafe: two services can both read
- *    `DATABASE_URL` and mean different things by it.
- */
+/** Matches ledger rows to confirmed facts, scoped to one repo. Excluded from `answered`: not
+ *  `refusalClass === "value-unknown"` (everything else isn't askable at all, DEC-242); no
+ *  `blockedBy`; or no fact reaches this repo (rule 3 — crossing needs declared `scope: "workspace"`, never inferred). */
 export function applyConfirmedFacts(refs, facts, repo, workspace) {
     const byBlockedBy = new Map();
     for (const fact of facts) {

package/dist/query/confirmed-facts.js.map

@@ -1 +1 @@
-{"version":3,"file":"confirmed-facts.js","sourceRoot":"","sources":["../../src/query/confirmed-facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA6BH;;;;;;;GAOG;AACH,SAAS,OAAO,CAAC,IAAmB,EAAE,IAAY,EAAE,SAA6B;IAC/E,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IAC7C,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC;AACtC,CAAC;AASD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAA8B,EAC9B,KAA+B,EAC/B,IAAY,EACZ,SAAkB;IAElB,MAAM,WAAW,GAAG,IAAI,GAAG,EAA2B,CAAC;IACvD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC;YAAE,SAAS;QAC9C,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,QAAQ,KAAK,SAAS;YAAE,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;;YAC/D,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,MAAM,QAAQ,GAAyB,EAAE,CAAC;IAC1C,MAAM,SAAS,GAAoB,EAAE,CAAC;IAEtC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,YAAY,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC,cAAc,CAAC,CAAC;QACjD,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC,WAAW,CAAC,CAAC;QAC3C,IAAI,YAAY,KAAK,eAAe,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;YAC1F,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACpB,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC;QACjG,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC"}
+{"version":3,"file":"confirmed-facts.js","sourceRoot":"","sources":["../../src/query/confirmed-facts.ts"],"names":[],"mappings":"AAAA;;0GAE0G;AAgB1G;oFACoF;AACpF,SAAS,OAAO,CAAC,IAAmB,EAAE,IAAY,EAAE,SAA6B;IAC/E,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IAC7C,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC;AACtC,CAAC;AASD;;yHAEyH;AACzH,MAAM,UAAU,mBAAmB,CACjC,IAA8B,EAC9B,KAA+B,EAC/B,IAAY,EACZ,SAAkB;IAElB,MAAM,WAAW,GAAG,IAAI,GAAG,EAA2B,CAAC;IACvD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC;YAAE,SAAS;QAC9C,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,QAAQ,KAAK,SAAS;YAAE,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;;YAC/D,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,MAAM,QAAQ,GAAyB,EAAE,CAAC;IAC1C,MAAM,SAAS,GAAoB,EAAE,CAAC;IAEtC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,YAAY,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC,cAAc,CAAC,CAAC;QACjD,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC,WAAW,CAAC,CAAC;QAC3C,IAAI,YAAY,KAAK,eAAe,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;YAC1F,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACpB,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC;QACjG,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC"}