@descryy/core 0.1.0

package/dist/multipr/overlap.js.map

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

package/dist/multipr/scope-store.d.ts

@@ -0,0 +1,105 @@
+/**
+ * §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.
+ */
+import type { SqlDriver } from "../store/driver/driver.ts";
+import type { PrScope } from "./overlap.ts";
+/**
+ * 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.
+ */
+export declare class ScopeDecodeError extends Error {
+    readonly name = "ScopeDecodeError";
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Row access for `pr_scopes`. Thin on purpose, in the style of `reader.ts`:
+ * nothing here scores, compares or decides staleness.
+ */
+export declare class ScopeStore {
+    #private;
+    constructor(driver: SqlDriver);
+    /**
+     * 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.
+     */
+    save(scope: PrScope): void;
+    saveAll(scopes: readonly PrScope[]): void;
+    /** One scope, or `undefined` when no row exists for that exact graph state. */
+    load(repo: string, prId: string, graphCommitSha: string): PrScope | undefined;
+    /**
+     * **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.
+     */
+    loadForGraph(repo: string, graphCommitSha: string): PrScope[];
+    /**
+     * 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.
+     */
+    graphStatesFor(repo: string, prId: string): {
+        graphCommitSha: string;
+        computedAt: number;
+    }[];
+    /**
+     * 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(repo: string, prId: string): number;
+}
+//# sourceMappingURL=scope-store.d.ts.map

package/dist/multipr/scope-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-store.d.ts","sourceRoot":"","sources":["../../src/multipr/scope-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,cAAc,CAAC;AAc1D;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAsB;gBAEhC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAG3D;AAiDD;;;GAGG;AACH,qBAAa,UAAU;;gBAGT,MAAM,EAAE,SAAS;IAI7B;;;;;;;;OAQG;IACH,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAsB1B,OAAO,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAMzC,+EAA+E;IAC/E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAS7E;;;;;;;OAOG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,EAAE;IAS7D;;;;;;OAMG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE;IAU5F;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;CAK3C"}

package/dist/multipr/scope-store.js

@@ -0,0 +1,182 @@
+/**
+ * §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.
+ */
+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.
+ */
+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.
+ */
+function encodeEntry(entry) {
+    const encoded = {
+        nodeId: entry.nodeId,
+        nodeType: entry.nodeType,
+        impactScore: entry.impactScore,
+        tier: entry.tier,
+        diffType: entry.diffType,
+        resolution: entry.resolution,
+    };
+    if (entry.file !== undefined)
+        encoded["file"] = entry.file;
+    return encoded;
+}
+function decode(row) {
+    let entries;
+    try {
+        const parsed = JSON.parse(row.scope_json);
+        if (!Array.isArray(parsed)) {
+            throw new Error(`scope_json is ${typeof parsed}, expected an array of entries`);
+        }
+        entries = parsed;
+    }
+    catch (cause) {
+        throw new ScopeDecodeError(`Scope for PR ${row.pr_id} in ${row.repo} at graph ${row.graph_commit_sha} could not be ` +
+            "decoded. It is not an empty scope — a damaged row and a change that touched nothing " +
+            "are different answers.", { cause });
+    }
+    return {
+        prId: row.pr_id,
+        repo: row.repo,
+        headSha: row.head_sha,
+        graphCommitSha: row.graph_commit_sha,
+        entries,
+        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.
+ */
+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.
+     */
+    save(scope) {
+        const json = canonicalJson(scope.entries.map(encodeEntry));
+        this.#driver
+            .prepare(`INSERT INTO pr_scopes (${COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(repo, pr_id, graph_commit_sha) DO UPDATE SET
+           head_sha = excluded.head_sha,
+           scope_json = excluded.scope_json,
+           node_count = excluded.node_count,
+           computed_at = excluded.computed_at`)
+            .run(scope.prId, scope.repo, scope.headSha, scope.graphCommitSha, json, scope.entries.length, scope.computedAt);
+    }
+    saveAll(scopes) {
+        this.#driver.transaction(() => {
+            for (const scope of scopes)
+                this.save(scope);
+        });
+    }
+    /** One scope, or `undefined` when no row exists for that exact graph state. */
+    load(repo, prId, graphCommitSha) {
+        const row = this.#driver
+            .prepare(`SELECT ${COLUMNS} FROM pr_scopes WHERE repo = ? AND pr_id = ? AND graph_commit_sha = ?`)
+            .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.
+     */
+    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.
+     */
+    graphStatesFor(repo, prId) {
+        return this.#driver
+            .prepare(`SELECT graph_commit_sha, computed_at FROM pr_scopes
+         WHERE repo = ? AND pr_id = ? ORDER BY computed_at DESC`)
+            .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(repo, prId) {
+        return this.#driver
+            .prepare("DELETE FROM pr_scopes WHERE repo = ? AND pr_id = ?")
+            .run(repo, prId).changes;
+    }
+}
+//# sourceMappingURL=scope-store.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,133 @@
+/**
+ * §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.
+ */
+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.
+ */
+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.
+     */
+    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.
+     */
+    readonly base: string | "absent" | "unknown";
+    readonly resolution: ResolutionLevel;
+}
+export type NodeVerdict = "already-in-base" | "differs" | "not-compared";
+export interface NodeComparison {
+    readonly nodeId: string;
+    readonly file?: string | undefined;
+    readonly diffType: DiffType;
+    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.
+     */
+    readonly superseded: boolean;
+    readonly comparisons: readonly NodeComparison[];
+    readonly counts: {
+        readonly total: number;
+        readonly alreadyInBase: number;
+        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`.
+     */
+    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.
+     */
+    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.
+ */
+export declare function findSuperseded(candidates: readonly SupersededCandidate[], options?: SupersededOptions): SupersededReport;
+//# sourceMappingURL=superseded.d.ts.map

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

@@ -0,0 +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"}

package/dist/multipr/superseded.js

@@ -0,0 +1,128 @@
+/**
+ * §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.
+ */
+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.
+    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.
+ */
+export function findSuperseded(candidates, options = {}) {
+    const notes = [];
+    const comparisons = candidates.map((c) => ({
+        nodeId: c.nodeId,
+        file: c.file,
+        diffType: c.diffType,
+        verdict: compare(c),
+    }));
+    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.
+    const weakest = candidates.reduce((min, c) => (c.resolution < min ? c.resolution : min), 4);
+    const reliability = reliabilityCap(weakest, true);
+    let disclosure = reliabilityNote(weakest, true);
+    disclosure +=
+        options.fingerprintBasis === undefined
+            ? " The basis on which two versions were called identical was not stated by the caller, so " +
+                "no claim is made about what a difference means: it may be a behavioural change or it " +
+                "may be whitespace."
+            : ` Two versions were called identical on this basis: ${options.fingerprintBasis}. A ` +
+                "difference means only that this basis differs.";
+    const analysed = candidates.length > 0;
+    const superseded = analysed && alreadyInBase === candidates.length;
+    if (!analysed) {
+        notes.push("No node was available to compare, so this check did not run. That is not a finding that " +
+            "the change is unsuperseded — a change whose every node differs and a change nothing " +
+            "was read for are different answers.");
+    }
+    if (notCompared > 0) {
+        notes.push(`${notCompared} of ${candidates.length} node(s) could not be compared against base, so ` +
+            "supersession is not claimed however many matched. This finding tells a human to close " +
+            "a change and discard work; a missed supersession costs a redundant review, and a false " +
+            "one costs the work.");
+    }
+    if (superseded) {
+        notes.push(`Every one of the ${candidates.length} node(s) this change touches is already in this ` +
+            "state on base. The work appears to have landed by another route.");
+        notes.push(disclosure);
+    }
+    else if (alreadyInBase > 0) {
+        // The interesting middle, and the reason the verdict is not just a boolean.
+        notes.push(`${alreadyInBase} of ${candidates.length} node(s) are already in this state on base, and ` +
+            `${differs} still differ. The change is partly landed rather than superseded, and the ` +
+            "nodes that still differ are what remains of it.");
+    }
+    return {
+        superseded,
+        comparisons,
+        counts: { total: candidates.length, alreadyInBase, differs, notCompared },
+        analysed,
+        reliability,
+        disclosure,
+        notes,
+    };
+}
+//# sourceMappingURL=superseded.js.map

package/dist/multipr/superseded.js.map

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

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

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+import type { ConfirmedFact, UnresolvedRef } from "@descryy/ir";
+export interface ConfirmedFactMatch {
+    readonly ref: UnresolvedRef;
+    /**
+     * 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.
+     */
+    readonly facts: readonly ConfirmedFact[];
+}
+export interface ConfirmedFactApplication {
+    /** Rows a stored fact answers — same `(repo, blockedBy)` key, exact match. */
+    readonly answered: readonly ConfirmedFactMatch[];
+    /** 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` shares this repo's exact `(repo, blockedBy)` pair.**
+ *    `facts` entries for a different `repo` are never consulted, even when the
+ *    blockedBy text is identical — rule 3's "never an inference about a
+ *    second case," enforced structurally rather than left to caller discipline.
+ */
+export declare function applyConfirmedFacts(refs: readonly UnresolvedRef[], facts: readonly ConfirmedFact[], repo: string): ConfirmedFactApplication;
+//# sourceMappingURL=confirmed-facts.d.ts.map

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

@@ -0,0 +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;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;CAC1C;AAED,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;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,aAAa,EAAE,EAC9B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,IAAI,EAAE,MAAM,GACX,wBAAwB,CA4B1B"}