@descryy/core 0.1.0

package/dist/graph/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/graph/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAElD,wFAAwF;AACxF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,GAAG,OAAO,CAQhF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,gSAMhC,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,oBAAoB,6IAGhC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EACvD,GAAG,SAAS,EAAE,MAAM,EAAE,GACrB,MAAM,EAAE,CAKV;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWpE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAcpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/graph/merge.js

@@ -0,0 +1,131 @@
+/**
+ * The merge policy — DEC-012.
+ *
+ * Two adapters finding the same relationship produce the same edge id, by
+ * construction: `hash(from, to, type)` deliberately excludes resolution,
+ * confidence and producer. On the prior-art graphs measured for this build, 30%
+ * of edges were exact duplicates, so this is the common path rather than an
+ * edge case.
+ *
+ * ## The rule
+ *
+ *   higher `resolution` wins
+ *   → tie: higher `confidence` wins
+ *   → tie: lexicographically smaller `producedBy` wins
+ *
+ * ## What the rule refuses to do
+ *
+ * **Confidence is never combined.** Two adapters each 0.8 confident does not
+ * make 0.96, or 0.8, or anything else — there is no evidence-combination model
+ * here, the two adapters are not independent observers, and inventing a formula
+ * would silently move every impact score in §12.4 with nothing in the output to
+ * show it happened. Corroboration is recorded as a fact (`attrs.corroboratedBy`)
+ * rather than folded into a number.
+ *
+ * The third tie-break exists only to make the result independent of the order
+ * batches arrive in. Lexicographic order is arbitrary; determinism is not.
+ *
+ * ## Why the rule is written twice
+ *
+ * The merge has to hold in two places: in memory, when the Graph Builder folds
+ * several batches together, and in SQL, when a later batch upserts onto an edge
+ * an earlier one already wrote. A rule enforced in only the first is not
+ * enforced at all, because the writer is reachable directly.
+ *
+ * So it appears as a TypeScript predicate and as a SQL `WHERE` fragment, side by
+ * side, with a differential test that runs the same case table through both.
+ * Two copies with a test that they agree beats one copy that only covers one of
+ * the two paths.
+ */
+/**
+ * Should `incoming` replace `existing`?
+ *
+ * Strict: an exact tie on all three keeps what is already there, so re-ingesting
+ * the same batch is a no-op rather than a rewrite.
+ */
+export function preferIncoming(incoming, existing) {
+    if (incoming.resolution !== existing.resolution) {
+        return incoming.resolution > existing.resolution;
+    }
+    if (incoming.confidence !== existing.confidence) {
+        return incoming.confidence > existing.confidence;
+    }
+    return incoming.producedBy < existing.producedBy;
+}
+/**
+ * The same rule as a SQL `WHERE` clause on an upsert's `DO UPDATE`.
+ *
+ * `excluded` is the incoming row, `edges` the one already stored — SQLite's
+ * upsert names them that way. Kept adjacent to `preferIncoming` on purpose:
+ * `merge.test.ts` runs one case table through both and fails if they disagree.
+ */
+export const EDGE_MERGE_CONDITION = `
+  excluded.resolution > edges.resolution
+  OR (excluded.resolution = edges.resolution AND excluded.confidence > edges.confidence)
+  OR (excluded.resolution = edges.resolution
+      AND excluded.confidence = edges.confidence
+      AND excluded.produced_by < edges.produced_by)
+`;
+/** The same, for nodes. Nodes carry no confidence, so the middle key drops out. */
+export const NODE_MERGE_CONDITION = `
+  excluded.resolution > nodes.resolution
+  OR (excluded.resolution = nodes.resolution AND excluded.produced_by < nodes.produced_by)
+`;
+/**
+ * Producers that corroborated a merged item, sorted and de-duplicated.
+ *
+ * DEC-012 records this instead of combining confidence. It is not decoration:
+ * "two independent adapters agree" is a materially different statement from "one
+ * adapter is fairly sure", and it is the only form in which the graph can carry
+ * that distinction without inventing an evidence model.
+ */
+export function corroborators(existing, ...producers) {
+    const prior = existing?.["corroboratedBy"];
+    const all = new Set(Array.isArray(prior) ? prior : []);
+    for (const p of producers)
+        all.add(p);
+    return [...all].sort();
+}
+/** Merge two edges that share an id. Returns the winner, carrying corroboration. */
+export function mergeEdge(incoming, existing) {
+    const winner = preferIncoming(incoming, existing) ? incoming : existing;
+    const corroboratedBy = corroborators({ ...existing.attrs, ...incoming.attrs }, existing.producedBy, incoming.producedBy);
+    return {
+        ...winner,
+        attrs: { ...(winner.attrs ?? {}), corroboratedBy },
+    };
+}
+/**
+ * Merge two nodes that share an id.
+ *
+ * Attributes are NOT unioned. `attrs` is language- and framework-specific detail
+ * (§11A.4), so pooling two adapters' attributes would produce a node describing
+ * a thing that does not exist. The winner's attrs are kept whole and the loser is
+ * recorded as a corroborator.
+ */
+export function mergeNode(incoming, existing) {
+    const winner = preferIncoming({ ...incoming, confidence: 0 }, { ...existing, confidence: 0 })
+        ? incoming
+        : existing;
+    return {
+        ...winner,
+        attrs: {
+            ...winner.attrs,
+            corroboratedBy: corroborators(existing.attrs, existing.producedBy, incoming.producedBy),
+        },
+    };
+}
+/**
+ * The fields two nodes sharing an id must agree on.
+ *
+ * Compared as one opaque string rather than field by field. That is not only
+ * tidier: `n.language !== m.language` reads to the boundary lint as branching on
+ * a language, and the lint is right to be suspicious — the exception here is
+ * that this asks whether two nodes *disagree*, never which language either one
+ * is. Folding both fields into a fingerprint states that intent in the code
+ * rather than in a lint suppression.
+ */
+export function identityFingerprint(node) {
+    return JSON.stringify([node.type, node.language]);
+}
+//# sourceMappingURL=merge.js.map

package/dist/graph/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../../src/graph/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAWH;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAmB,EAAE,QAAmB;IACrE,IAAI,QAAQ,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU,EAAE,CAAC;QAChD,OAAO,QAAQ,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;IACnD,CAAC;IACD,IAAI,QAAQ,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU,EAAE,CAAC;QAChD,OAAO,QAAQ,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;IACnD,CAAC;IACD,OAAO,QAAQ,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;CAMnC,CAAC;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;CAGnC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAuD,EACvD,GAAG,SAAmB;IAEtB,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC,gBAAgB,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAS,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAkB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7E,KAAK,MAAM,CAAC,IAAI,SAAS;QAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtC,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,QAAgB;IAC1D,MAAM,MAAM,GAAG,cAAc,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IACxE,MAAM,cAAc,GAAG,aAAa,CAClC,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE,EACxC,QAAQ,CAAC,UAAU,EACnB,QAAQ,CAAC,UAAU,CACpB,CAAC;IACF,OAAO;QACL,GAAG,MAAM;QACT,KAAK,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,cAAc,EAAE;KACnD,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,QAAgB;IAC1D,MAAM,MAAM,GAAG,cAAc,CAC3B,EAAE,GAAG,QAAQ,EAAE,UAAU,EAAE,CAAC,EAAE,EAC9B,EAAE,GAAG,QAAQ,EAAE,UAAU,EAAE,CAAC,EAAE,CAC/B;QACC,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,QAAQ,CAAC;IACb,OAAO;QACL,GAAG,MAAM;QACT,KAAK,EAAE;YACL,GAAG,MAAM,CAAC,KAAK;YACf,cAAc,EAAE,aAAa,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC;SACxF;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;AACpD,CAAC"}

package/dist/graph/persist.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Writing a built graph back out, split by producer.
+ *
+ * `buildGraph` merges many producers into one graph; `writeBatch` invalidates
+ * and writes **one producer's** rows at a time, because DEC-014's invalidation
+ * rule is per-adapter — re-running the Python adapter must not evict the
+ * TypeScript adapter's rows. So the merged graph has to be partitioned back
+ * before it can be stored.
+ *
+ * That partition was written out by hand in every bench script that has ever
+ * stored a graph, identically, five times. It is not a measurement concern: it
+ * is the engine's own write path, and the MCP server needs it too. Lifted here
+ * so there is one copy and one place for it to be wrong.
+ *
+ * ## The subtlety worth stating
+ *
+ * The rows written for a producer are the **post-merge** ones, not the batch's
+ * originals. A node supplied by two adapters is merged (DEC-012) and the merged
+ * row carries the winning `producedBy`; writing the pre-merge originals would
+ * store the losing version under the loser's producer and then let the next
+ * incremental run resurrect it. Filtering the merged graph by `producedBy` is
+ * what makes the store agree with the builder.
+ *
+ * A batch that contributed nothing after the merge is still written, with empty
+ * rows, on purpose: that is how a re-run that *removes* a symbol evicts the row
+ * it used to own. Skipping empty batches would make deletions invisible.
+ */
+import type { IRBatch } from "@descryy/ir";
+import type { SqlDriver } from "../store/driver/driver.ts";
+import { type WriteOptions, type WriteResult } from "../store/writer.ts";
+import type { BuildResult } from "./build.ts";
+export interface PersistResult {
+    readonly writes: readonly WriteResult[];
+    readonly nodesWritten: number;
+    readonly edgesWritten: number;
+    readonly unresolvedWritten: number;
+    /** Union of every write's evictions — files a replaced run covered and this one did not. */
+    readonly evictedFiles: readonly string[];
+    readonly orphanedEdges: number;
+}
+export declare function persistGraph(driver: SqlDriver, batches: readonly IRBatch[], built: BuildResult, options?: WriteOptions): PersistResult;
+//# sourceMappingURL=persist.d.ts.map

package/dist/graph/persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist.d.ts","sourceRoot":"","sources":["../../src/graph/persist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAc,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,4FAA4F;IAC5F,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,SAAS,OAAO,EAAE,EAC3B,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,YAAiB,GACzB,aAAa,CA6Bf"}

package/dist/graph/persist.js

@@ -0,0 +1,52 @@
+/**
+ * Writing a built graph back out, split by producer.
+ *
+ * `buildGraph` merges many producers into one graph; `writeBatch` invalidates
+ * and writes **one producer's** rows at a time, because DEC-014's invalidation
+ * rule is per-adapter — re-running the Python adapter must not evict the
+ * TypeScript adapter's rows. So the merged graph has to be partitioned back
+ * before it can be stored.
+ *
+ * That partition was written out by hand in every bench script that has ever
+ * stored a graph, identically, five times. It is not a measurement concern: it
+ * is the engine's own write path, and the MCP server needs it too. Lifted here
+ * so there is one copy and one place for it to be wrong.
+ *
+ * ## The subtlety worth stating
+ *
+ * The rows written for a producer are the **post-merge** ones, not the batch's
+ * originals. A node supplied by two adapters is merged (DEC-012) and the merged
+ * row carries the winning `producedBy`; writing the pre-merge originals would
+ * store the losing version under the loser's producer and then let the next
+ * incremental run resurrect it. Filtering the merged graph by `producedBy` is
+ * what makes the store agree with the builder.
+ *
+ * A batch that contributed nothing after the merge is still written, with empty
+ * rows, on purpose: that is how a re-run that *removes* a symbol evicts the row
+ * it used to own. Skipping empty batches would make deletions invisible.
+ */
+import { writeBatch } from "../store/writer.js";
+export function persistGraph(driver, batches, built, options = {}) {
+    const writes = [];
+    const evicted = new Set();
+    for (const batch of batches) {
+        writes.push(writeBatch(driver, {
+            ...batch,
+            nodes: built.nodes.filter((node) => node.producedBy === batch.producedBy),
+            edges: built.edges.filter((edge) => edge.producedBy === batch.producedBy),
+            unresolved: built.unresolved.filter((ref) => ref.producedBy === batch.producedBy),
+        }, options));
+    }
+    for (const write of writes)
+        for (const file of write.evictedFiles)
+            evicted.add(file);
+    return {
+        writes,
+        nodesWritten: writes.reduce((n, w) => n + w.nodesWritten, 0),
+        edgesWritten: writes.reduce((n, w) => n + w.edgesWritten, 0),
+        unresolvedWritten: writes.reduce((n, w) => n + w.unresolvedWritten, 0),
+        evictedFiles: [...evicted].sort(),
+        orphanedEdges: writes.reduce((n, w) => n + w.orphanedEdges, 0),
+    };
+}
+//# sourceMappingURL=persist.js.map

package/dist/graph/persist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist.js","sourceRoot":"","sources":["../../src/graph/persist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,EAAE,UAAU,EAAuC,MAAM,oBAAoB,CAAC;AAarF,MAAM,UAAU,YAAY,CAC1B,MAAiB,EACjB,OAA2B,EAC3B,KAAkB,EAClB,UAAwB,EAAE;IAE1B,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,CAAC,IAAI,CACT,UAAU,CACR,MAAM,EACN;YACE,GAAG,KAAK;YACR,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU,CAAC;YACzE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU,CAAC;YACzE,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU,CAAC;SAClF,EACD,OAAO,CACR,CACF,CAAC;IACJ,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,MAAM;QAAE,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,YAAY;YAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAErF,OAAO;QACL,MAAM;QACN,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;QAC5D,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;QAC5D,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,iBAAiB,EAAE,CAAC,CAAC;QACtE,YAAY,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE;QACjC,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC;KAC/D,CAAC;AACJ,CAAC"}

package/dist/graph/runtime-confirmation.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Runtime confirmation — architecture §11B.3, the R4 half of the moat.
+ *
+ * > *"A purely static code-graph tool is capped at R3 permanently. It has no
+ * > runtime. This is the one accuracy source that cannot be copied without
+ * > also building the testing half, and it should be treated as the core
+ * > technical moat rather than the graph itself."* — §11B.3
+ *
+ * The schema has held `observed_edges` and `edge_corrections` since the store
+ * was first written, both on the EARNED side of DEC-017's partition, both
+ * carrying a comment explaining why they cannot be recomputed. **Nothing read
+ * or wrote either one.** This module is what they were for.
+ *
+ * ## The three arrows §11B.3 draws, and where each one lands
+ *
+ * | Observation | What happens |
+ * | --- | --- |
+ * | confirms an edge the graph already has, below R4 | **promote** to R4, `observed_by_run` set |
+ * | confirms an edge the graph does not have | **create** it at R4 — "recall gap closed" |
+ * | denies an edge the graph has, below R4 | **correct** it: an `edge_corrections` row, and a {@link GraphDefectRecord} out |
+ *
+ * ## Why a denial demotes confidence and does not delete the edge
+ *
+ * `edges` is DERIVED. Deleting a row there is undone by the next index, which
+ * regenerates the identical guess from the identical source and has no memory
+ * of the run that disproved it — the correction would evaporate exactly when
+ * it was needed again. §11B.5 already states the answer: corrections are
+ * *"stored as graph overrides keyed by stable node IDs, surviving re-index and
+ * adapter upgrades."* So the durable statement is the `edge_corrections` row,
+ * and the effect on the derived graph is a confidence demotion that
+ * {@link reapplyEarnedOverlays} re-applies after every rebuild.
+ *
+ * Demotion rather than deletion is also DEC-284's own stated direction — *"it
+ * fails toward demote, which is the safe direction"* — and it keeps rule 2
+ * intact from the other side: a wrong edge stops being load-bearing without
+ * the graph asserting a *new* fact (that the call does not exist) that no
+ * single observation actually establishes.
+ *
+ * ## What this module refuses to do
+ *
+ * - **Invent a node.** An observation naming a node this graph does not hold
+ *   is refused with its reason, never created. Rule 2, and the same posture
+ *   `correlateExecution` takes one layer down for an ambiguous resolution.
+ * - **Adjudicate R4 against R4.** A denial against an edge already at R4 is
+ *   two runtime observations disagreeing across time — a staleness question
+ *   whose policy is decided (DEC-284 + a 7-day backstop) but whose consumer
+ *   does not exist yet. `contradiction.ts` excludes the case by construction
+ *   and this module reports it as {@link RuntimeConfirmationResult.staleR4}
+ *   rather than laundering it through a path that looks decided.
+ * - **Judge a finding.** Resolution has no opinion on confidence (RT-027).
+ *   Nothing here reads or writes a finding, a hypothesis or a category.
+ *
+ * @see `packages/ir/src/contradiction.ts` — the pure detection this persists.
+ * @see `documents/plans/ai-layer-plan.md` §10 — *"the valuable half."*
+ */
+import { type EdgeType, type GraphDefectRecord, type RuntimeEdgeObservation } from "@descryy/ir";
+import type { SqlDriver } from "../store/driver/driver.ts";
+/** One observation this pass declined to act on, with the resolver's own reason. */
+export interface RuntimeObservationRefusal {
+    readonly from: string;
+    readonly to: string;
+    readonly edgeType: EdgeType;
+    readonly reason: string;
+}
+/** A denial aimed at an edge already at R4 — out of scope here. See the module doc. */
+export interface StaleR4Observation {
+    readonly edgeId: string;
+    readonly observedByRun: string | null;
+    readonly detail: string;
+}
+export interface RuntimeConfirmationInput {
+    /** The run that witnessed these observations. Becomes `edges.observed_by_run` and `observed_edges.run_id`. */
+    readonly runId: string;
+    /** The commit the observed application was built from. Stored so a later reader can tell whether the code has moved under the observation. */
+    readonly commitSha: string;
+    readonly observations: readonly RuntimeEdgeObservation[];
+}
+export interface RuntimeConfirmationResult {
+    /** Edge ids that moved from below R4 up to R4. */
+    readonly promoted: readonly string[];
+    /** Edge ids created at R4 because no static producer found them. */
+    readonly created: readonly string[];
+    /** Edge ids already at R4 and observed again — reported, never silently dropped. */
+    readonly confirmed: readonly string[];
+    /** Denials of a sub-R4 edge, shaped for the independent edge-precision check. */
+    readonly contradictions: readonly GraphDefectRecord[];
+    readonly staleR4: readonly StaleR4Observation[];
+    readonly refused: readonly RuntimeObservationRefusal[];
+}
+/** One row of the EARNED R4 ledger. */
+export interface ObservedEdgeRow {
+    readonly edgeId: string;
+    readonly runId: string;
+    readonly from: string;
+    readonly to: string;
+    readonly edgeType: EdgeType;
+    readonly commitSha: string;
+    readonly observedAt: number;
+}
+/** One row of the EARNED correction ledger (§11B.5). */
+export interface EdgeCorrectionRow {
+    readonly edgeId: string;
+    readonly verdict: "wrong" | "right";
+    readonly reason: string;
+    readonly correctedAt: number;
+}
+/**
+ * A clock, injected so a test can pin `observed_at`/`corrected_at`. Same shape
+ * the store's own tests already use.
+ */
+export interface Clock {
+    now(): number;
+}
+/**
+ * Apply a run's edge observations to the graph, writing the earned record and
+ * projecting it onto the derived edges in one transaction.
+ *
+ * Pure with respect to its inputs and total over them: every observation lands
+ * in exactly one of the six result arrays, so a caller can account for all of
+ * them without inspecting the store. Never throws for an observation it cannot
+ * act on — that is a refusal, per the five-result-states rule the tool contract
+ * applies one layer up.
+ */
+export declare function applyRuntimeObservations(driver: SqlDriver, input: RuntimeConfirmationInput, clock?: Clock): RuntimeConfirmationResult;
+/**
+ * Re-project the EARNED ledgers onto a freshly rebuilt derived graph.
+ *
+ * **This is what makes the DEC-017 partition pay.** `dropDerived()` removes
+ * `edges` and leaves `observed_edges`/`edge_corrections` standing; a re-index
+ * then regenerates the same static guesses, at their static resolutions, with
+ * no memory of any run. Without this call the moat is silently reset on every
+ * rebuild — the edges would be back at R2 and the R4 rows would sit in a table
+ * nothing consults, which is indistinguishable from never having observed
+ * anything.
+ *
+ * Observations whose endpoints no longer exist are reported as refusals rather
+ * than recreated: the code moved, and re-minting a node from an old run's
+ * record would be the same rule-2 violation one rebuild later.
+ */
+export declare function reapplyEarnedOverlays(driver: SqlDriver): RuntimeConfirmationResult;
+/** Every row of the EARNED R4 ledger, oldest first, optionally for one run. */
+export declare function observedEdges(driver: SqlDriver, options?: {
+    readonly runId?: string;
+}): ObservedEdgeRow[];
+/** Every row of the EARNED correction ledger (§11B.5), oldest first. */
+export declare function edgeCorrections(driver: SqlDriver): EdgeCorrectionRow[];
+/**
+ * Record a human's verdict on an edge — §11B.5's other producer.
+ *
+ * *"On one team's codebase, a few hundred corrections buy more accuracy than a
+ * quarter of parser work."* Same table the runtime's own denials land in, on
+ * purpose: an edge is wrong or it is not, and who noticed does not change what
+ * the graph should do about it. The `reason` is the correction's provenance and
+ * is never summarised.
+ */
+export declare function recordEdgeCorrection(driver: SqlDriver, input: {
+    readonly from: string;
+    readonly to: string;
+    readonly edgeType: EdgeType;
+    readonly verdict: "wrong" | "right";
+    readonly reason: string;
+}, clock?: Clock): {
+    readonly edgeId: string;
+};
+/** The `producedBy` every runtime-minted edge carries. Provenance is load-bearing (§11A.5). */
+export declare const RUNTIME_ADAPTER_ID = "runtime-confirmation";
+export declare const RUNTIME_ADAPTER_VERSION = "1";
+export declare const RUNTIME_PRODUCER = "runtime-confirmation@1";
+//# sourceMappingURL=runtime-confirmation.d.ts.map

package/dist/graph/runtime-confirmation.d.ts.map

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