pilotswarm-horizon-store 0.2.2

package/dist/src/graph-queries.js

@@ -0,0 +1,727 @@
+// pilotswarm-horizon-store — typed Cypher layer (AGE).
+//
+// ALL graph access goes through this module (03-design §1: graph access is a
+// typed Cypher layer in TypeScript, not plpgsql-wrapped Cypher). The data
+// model (03-design §2.2):
+//
+//   (:GraphNode {node_key, kind, name, aliases, namespace, created_by})
+//       -[:REL {predicate, predicate_key, confidence, observations,
+//               evidence[], asserted_by[], namespace, model}]-> (:GraphNode)
+//       -[:EVIDENCED_BY]-> (:Fact {scope_key})
+//
+// Evidence has two physical forms: a NODE's evidence is a real EVIDENCED_BY
+// edge to a content-free :Fact anchor (traversable — the seed pivot matches
+// it); a REL edge's evidence is a property array (property graphs have no
+// edge-to-edge links). Both surface as `evidence: string[]`, ACL-filtered to
+// the caller at result assembly (01 §6.1a). Inaccessible fact SEEDS are
+// ignored (treated as unknown).
+//
+// AGE quirks encapsulated here: no parameterized cypher (escaped literals via
+// sql-util), no `any(x IN ...)` predicate (list comprehension instead), no
+// startNode/endNode/UNWIND on var-length paths (edges re-matched over the
+// reachable key set).
+import { scopeKeyAccessible } from "./types.js";
+import { cypherStr, cypherNum, cypherStrList } from "./sql-util.js";
+import { withDbRetry, isLabelCreationRaceError } from "./db-retry.js";
+import { nodeKeyOf, predicateKey as makePredicateKey, mergeAliases, decideEdgeUpsert, reinforceConfidence, clamp01 } from "./graph-model.js";
+const FACT_SEED = /^(shared|session):/;
+/**
+ * Reserved namespace token for the unscoped partition (graph-fact-search
+ * enhancements). `default` is NOT a literal namespace: it maps to "no namespace"
+ * (NULL) on writes and to `namespace IS NULL` on reads. Matched case-insensitively
+ * as a whole token, so a real corpus like `corpus/default-config` is unaffected.
+ */
+const DEFAULT_GRAPH_NAMESPACE = "default";
+function isDefaultNamespaceToken(namespace) {
+    return namespace?.trim().replace(/\/+$/g, "").toLowerCase() === DEFAULT_GRAPH_NAMESPACE;
+}
+function normalizeNamespace(namespace) {
+    const clean = namespace?.trim().replace(/\/+$/g, "") ?? "";
+    if (clean.length === 0)
+        return null;
+    // `default` is the reserved unscoped/NULL partition, never a stored namespace.
+    if (clean.toLowerCase() === DEFAULT_GRAPH_NAMESPACE)
+        return null;
+    return clean;
+}
+function namespacePredicate(alias, namespace) {
+    if (isDefaultNamespaceToken(namespace))
+        return `${alias}.namespace IS NULL`;
+    const ns = normalizeNamespace(namespace);
+    if (!ns)
+        return null;
+    return `(${alias}.namespace = ${cypherStr(ns)} OR ${alias}.namespace STARTS WITH ${cypherStr(`${ns}/`)})`;
+}
+function namespaceMatches(value, namespace) {
+    if (isDefaultNamespaceToken(namespace)) {
+        // default == unscoped: the record matches only when it has no namespace.
+        return value == null || (typeof value === "string" && normalizeNamespace(value) === null);
+    }
+    const ns = normalizeNamespace(namespace);
+    if (!ns)
+        return true;
+    const current = typeof value === "string" ? normalizeNamespace(value) : null;
+    return current === ns || current?.startsWith(`${ns}/`) === true;
+}
+function namespaceProp(namespace) {
+    const ns = normalizeNamespace(namespace);
+    return ns ? `, namespace: ${cypherStr(ns)}` : "";
+}
+function namespaceSet(alias, namespace) {
+    // A PROVIDED-but-unscoped namespace (`default` / empty / whitespace) clears
+    // the property, re-homing the record into the NULL/default partition. An
+    // OMITTED namespace (undefined) leaves the existing property untouched.
+    if (namespace !== undefined && normalizeNamespace(namespace) === null) {
+        return `, ${alias}.namespace = NULL`;
+    }
+    const ns = normalizeNamespace(namespace);
+    return ns ? `, ${alias}.namespace = ${cypherStr(ns)}` : "";
+}
+function edgeNamespacePredicate(namespace) {
+    if (isDefaultNamespaceToken(namespace)) {
+        // Mirror the concrete edge semantics (edge OR either endpoint) for the
+        // unscoped partition: match when the edge or either endpoint is NULL.
+        return `(r.namespace IS NULL OR a.namespace IS NULL OR b.namespace IS NULL)`;
+    }
+    const ns = normalizeNamespace(namespace);
+    if (!ns)
+        return null;
+    const exact = cypherStr(ns);
+    const prefix = cypherStr(`${ns}/`);
+    return `(` +
+        `r.namespace = ${exact} OR r.namespace STARTS WITH ${prefix} OR ` +
+        `a.namespace = ${exact} OR a.namespace STARTS WITH ${prefix} OR ` +
+        `b.namespace = ${exact} OR b.namespace STARTS WITH ${prefix}` +
+        `)`;
+}
+/**
+ * Load the AGE shared library for this session. On managed Postgres where age
+ * is preloaded via shared_preload_libraries, an explicit LOAD is rejected with
+ * `access to library "age" is not allowed` — tolerated, since preloaded means
+ * there is nothing to do.
+ */
+export async function prepareAgeSession(client) {
+    try {
+        await client.query(`LOAD 'age'`);
+    }
+    catch (err) {
+        const msg = String(err?.message ?? "");
+        if (!/access to library "age" is not allowed/i.test(msg))
+            throw err;
+    }
+    await client.query(`SET search_path = ag_catalog, "$user", public`);
+}
+/** Parse a scalar agtype column value into a JS value. */
+export function ag(v) {
+    if (v == null)
+        return v;
+    if (typeof v !== "string")
+        return v;
+    const stripped = v.replace(/::[a-z]+$/i, "");
+    try {
+        return JSON.parse(stripped);
+    }
+    catch {
+        return stripped;
+    }
+}
+/** Parse an agtype array column into string[]. */
+export function agArr(v) {
+    const parsed = ag(v);
+    return Array.isArray(parsed) ? parsed.map(String) : [];
+}
+/**
+ * Typed Cypher layer (AGE). Provides the GraphStore READ/WRITE method bodies;
+ * `HorizonDBGraphStore` wraps this with the lifecycle (initialize/close) to form
+ * the full `GraphStore` provider (07 D2). This inner class deliberately does NOT
+ * implement the lifecycle, so it is not itself a `GraphStore`.
+ */
+export class GraphQueries {
+    pool;
+    graphName;
+    // Physical connections whose AGE session is already prepared (LOAD age +
+    // search_path). Keyed on the pg client object, which the pool reuses per
+    // physical connection — so the (otherwise per-checkout) setup runs ONCE per
+    // connection instead of on every graph op. On a remote cluster that removes
+    // ~2 round trips (a wasted LOAD attempt + SET) from every upsert. A reset
+    // connection yields a NEW client object → re-prepared automatically, and a
+    // stale-but-cached connection self-heals: its query fails transiently,
+    // withDbRetry re-acquires a fresh (unprepared) client, and we prepare that.
+    prepared = new WeakSet();
+    constructor(pool, graphName) {
+        this.pool = pool;
+        this.graphName = graphName;
+    }
+    async withAge(fn) {
+        // Retry the whole acquire+run on transient HorizonDB CONNECTION drops
+        // (needs a fresh client). The AGE label-creation race is handled one
+        // level down in cypher() — that one can retry on the same client.
+        return withDbRetry("graph_cypher", async () => {
+            const client = await this.pool.connect();
+            try {
+                if (!this.prepared.has(client)) {
+                    await prepareAgeSession(client);
+                    this.prepared.add(client);
+                }
+                return await fn(client);
+            }
+            finally {
+                client.release();
+            }
+        });
+    }
+    async cypher(client, query, columns) {
+        // AGE requires a non-empty column list even for write-only queries
+        // (DELETE/DETACH DELETE return no rows) — use a dummy column then.
+        const colDefs = (columns.length > 0 ? columns : ["_ok"]).map((c) => `${c} agtype`).join(", ");
+        // Wrap the generated Cypher in a dollar-quoted SQL literal whose tag is
+        // GUARANTEED absent from the query. cypherStr() escapes quotes/backslashes
+        // INSIDE Cypher string literals, but it does not (and cannot) escape the
+        // SQL `$$` delimiter — a value containing `$$` would otherwise terminate
+        // a fixed `$$ ... $$` wrapper early and inject SQL. A computed tag closes
+        // that hole.
+        let tag = "$cy$";
+        if (query.includes(tag)) {
+            let i = 0;
+            do {
+                tag = `$cy${i++}$`;
+            } while (query.includes(tag));
+        }
+        const sql = `SELECT * FROM cypher(${cypherStr(this.graphName)}, ${tag} ${query} ${tag}) AS (${colDefs})`;
+        // AGE creates a label's backing table LAZILY on the first CREATE/MERGE
+        // that references it. Concurrent first-references to the same label race
+        // that internal CREATE TABLE; the loser aborts the whole statement
+        // (nothing persisted) with EITHER 42P07 `relation "<label>" already
+        // exists` OR 23505 on a pg_catalog index (e.g. pg_class_relname_nsp_index).
+        // The label now EXISTS, so re-running the SAME statement on the same
+        // client succeeds (each cypher call is its own autocommit statement, so a
+        // prior failure does not poison the connection). We only retry this
+        // label-race class — every other error surfaces. Label-agnostic on
+        // purpose: labels are owned by the layer above us.
+        const { rows } = await withDbRetry("graph_label_race", () => client.query(sql), { isRetryable: isLabelCreationRaceError });
+        return rows;
+    }
+    // ─── reads ────────────────────────────────────────────────────────────────
+    async searchGraphNodes(q, access) {
+        const limit = Math.max(1, Math.min(Math.trunc(q.limit ?? 50), 500));
+        const depth = Math.max(1, Math.min(Math.trunc(q.depth ?? 1), 5));
+        return this.withAge(async (c) => {
+            const found = new Map();
+            const collect = (rows) => {
+                for (const r of rows) {
+                    const nodeKey = ag(r.node_key);
+                    if (!found.has(nodeKey)) {
+                        const namespace = ag(r.namespace);
+                        found.set(nodeKey, {
+                            nodeKey,
+                            kind: ag(r.kind),
+                            name: ag(r.name),
+                            ...(typeof namespace === "string" ? { namespace } : {}),
+                            aliases: agArr(r.aliases),
+                        });
+                    }
+                }
+            };
+            const RET = `RETURN DISTINCT n.node_key, n.kind, n.name, n.namespace, n.aliases`;
+            const COLS = ["node_key", "kind", "name", "namespace", "aliases"];
+            const seeds = q.seeds ?? [];
+            if (seeds.length > 0) {
+                // Inaccessible fact seeds are IGNORED — byte-identical to unknown
+                // seeds, so seeding cannot probe private facts (01 §6.5).
+                const factSeeds = seeds.filter((s) => FACT_SEED.test(s) && scopeKeyAccessible(s, access));
+                const nodeSeeds = seeds.filter((s) => !FACT_SEED.test(s));
+                const baseKeys = new Set();
+                if (factSeeds.length > 0) {
+                    const rows = await this.cypher(c, `MATCH (f:Fact)<-[:EVIDENCED_BY]-(n:GraphNode)
+                         WHERE f.scope_key IN ${cypherStrList(factSeeds)} ${RET}`, COLS);
+                    collect(rows);
+                    for (const r of rows)
+                        baseKeys.add(ag(r.node_key));
+                }
+                if (nodeSeeds.length > 0) {
+                    const rows = await this.cypher(c, `MATCH (n:GraphNode) WHERE n.node_key IN ${cypherStrList(nodeSeeds)} ${RET}`, COLS);
+                    collect(rows);
+                    for (const r of rows)
+                        baseKeys.add(ag(r.node_key));
+                }
+                if (baseKeys.size > 0 && depth >= 1) {
+                    const rows = await this.cypher(c, `MATCH (s:GraphNode)-[:REL*1..${depth}]-(n:GraphNode)
+                         WHERE s.node_key IN ${cypherStrList([...baseKeys])} ${RET}`, COLS);
+                    collect(rows);
+                }
+                // kind/nameLike/namespace combine as post-filters when seeds anchor the query.
+                if (q.kind || q.nameLike || q.namespace) {
+                    const kindNorm = q.kind;
+                    const pat = q.nameLike?.toLowerCase();
+                    for (const [k, n] of [...found]) {
+                        if (kindNorm && n.kind !== kindNorm) {
+                            found.delete(k);
+                            continue;
+                        }
+                        if (!namespaceMatches(n.namespace, q.namespace)) {
+                            found.delete(k);
+                            continue;
+                        }
+                        if (pat) {
+                            const hay = [n.name, ...n.aliases].map((x) => x.toLowerCase());
+                            if (!hay.some((x) => x.includes(pat)))
+                                found.delete(k);
+                        }
+                    }
+                }
+            }
+            else {
+                const filters = [];
+                if (q.kind)
+                    filters.push(`n.kind = ${cypherStr(q.kind)}`);
+                const ns = namespacePredicate("n", q.namespace);
+                if (ns)
+                    filters.push(ns);
+                if (q.nameLike) {
+                    const pat = cypherStr(q.nameLike.toLowerCase());
+                    // AGE lacks `any(x IN list WHERE ...)`; use list comprehension.
+                    filters.push(`(toLower(n.name) CONTAINS ${pat} OR size([a IN n.aliases WHERE toLower(a) CONTAINS ${pat}]) > 0)`);
+                }
+                const where = filters.length ? `WHERE ${filters.join(" AND ")}` : "";
+                collect(await this.cypher(c, `MATCH (n:GraphNode) ${where} ${RET} LIMIT ${cypherNum(limit)}`, COLS));
+            }
+            const hits = [...found.values()].slice(0, limit);
+            const evidence = await this.evidenceFor(c, hits.map((h) => h.nodeKey), access);
+            return hits.map((h) => ({ ...h, evidence: evidence.get(h.nodeKey) ?? [] }));
+        });
+    }
+    /**
+     * Idempotent, duplicate-anchor-proof evidence linking. A naive
+     * `MERGE (f:Fact {scope_key}) MERGE (e)-[:EVIDENCED_BY]->(f)` is NOT safe
+     * here: AGE has no unique constraints, so concurrent upserts can race the
+     * anchor MERGE into duplicate :Fact nodes — after which a later MERGE
+     * binds EVERY duplicate and mints extra edges. Instead: skip when any
+     * edge already exists; bind exactly ONE anchor (WITH … LIMIT 1) or create
+     * it when none exists.
+     */
+    async linkEvidenceAnchor(client, nodeKey, scopeKey) {
+        const linked = await this.cypher(client, `MATCH (e:GraphNode { node_key: ${cypherStr(nodeKey)} })-[:EVIDENCED_BY]->(f:Fact { scope_key: ${cypherStr(scopeKey)} })
+             RETURN f.scope_key LIMIT 1`, ["scope_key"]);
+        if (linked.length > 0)
+            return;
+        const anchored = await this.cypher(client, `MATCH (e:GraphNode { node_key: ${cypherStr(nodeKey)} })
+             MATCH (f:Fact { scope_key: ${cypherStr(scopeKey)} })
+             WITH e, f LIMIT 1
+             CREATE (e)-[:EVIDENCED_BY]->(f) RETURN f.scope_key`, ["scope_key"]);
+        if (anchored.length === 0) {
+            await this.cypher(client, `MATCH (e:GraphNode { node_key: ${cypherStr(nodeKey)} })
+                 CREATE (f:Fact { scope_key: ${cypherStr(scopeKey)} })
+                 CREATE (e)-[:EVIDENCED_BY]->(f) RETURN f.scope_key`, ["scope_key"]);
+        }
+    }
+    /** EVIDENCED_BY scopeKeys per node, ACL-filtered (01 §6.1a), deduped
+     * (duplicate anchors must never surface as duplicate evidence keys). */
+    async evidenceFor(client, nodeKeys, access) {
+        const out = new Map();
+        if (nodeKeys.length === 0)
+            return out;
+        const rows = await this.cypher(client, `MATCH (n:GraphNode)-[:EVIDENCED_BY]->(f:Fact)
+             WHERE n.node_key IN ${cypherStrList(nodeKeys)}
+             RETURN n.node_key, f.scope_key`, ["node_key", "scope_key"]);
+        for (const r of rows) {
+            const nk = ag(r.node_key);
+            const sk = ag(r.scope_key);
+            if (!scopeKeyAccessible(sk, access))
+                continue; // traversal saw it; the caller doesn't
+            const arr = out.get(nk) ?? [];
+            if (!arr.includes(sk))
+                arr.push(sk);
+            out.set(nk, arr);
+        }
+        return out;
+    }
+    async searchGraphEdges(q, access) {
+        const filters = [];
+        const pk = q.predicateKey ?? (q.predicate ? makePredicateKey(q.predicate) : undefined);
+        if (pk)
+            filters.push(`r.predicate_key = ${cypherStr(pk)}`);
+        if (q.fromKey)
+            filters.push(`a.node_key = ${cypherStr(q.fromKey)}`);
+        if (q.toKey)
+            filters.push(`b.node_key = ${cypherStr(q.toKey)}`);
+        const ns = edgeNamespacePredicate(q.namespace);
+        if (ns)
+            filters.push(ns);
+        if (q.minConfidence != null)
+            filters.push(`r.confidence >= ${cypherNum(q.minConfidence)}`);
+        const where = filters.length ? `WHERE ${filters.join(" AND ")}` : "";
+        const limit = cypherNum(Math.max(1, Math.min(Math.trunc(q.limit ?? 50), 500)));
+        return this.withAge(async (c) => {
+            const rows = await this.cypher(c, `MATCH (a:GraphNode)-[r:REL]->(b:GraphNode) ${where}
+                 RETURN a.node_key, b.node_key, r.predicate, r.predicate_key, r.namespace, r.confidence, r.observations, r.evidence
+                 LIMIT ${limit}`, ["from_key", "to_key", "predicate", "predicate_key", "namespace", "confidence", "observations", "evidence"]);
+            return rows.map((r) => ({
+                fromKey: ag(r.from_key), toKey: ag(r.to_key), predicate: ag(r.predicate),
+                predicateKey: ag(r.predicate_key), namespace: ag(r.namespace) ?? undefined,
+                confidence: Number(ag(r.confidence)),
+                observations: Number(ag(r.observations)),
+                evidence: agArr(r.evidence).filter((sk) => scopeKeyAccessible(sk, access)),
+            }));
+        });
+    }
+    async graphNeighbourhood(nodeKey, depth, _access, opts = {}) {
+        const d = Math.max(1, Math.min(Math.trunc(depth), 5));
+        return this.withAge(async (c) => {
+            const ns = namespacePredicate("n", opts.namespace);
+            const nodeRows = await this.cypher(c, `MATCH (e:GraphNode { node_key: ${cypherStr(nodeKey)} })-[:REL*1..${d}]-(n:GraphNode)
+                 ${ns ? `WHERE ${ns}` : ""}
+                 RETURN DISTINCT n.node_key, n.kind, n.name, n.namespace`, ["node_key", "kind", "name", "namespace"]);
+            const nodes = nodeRows.map((r) => {
+                const namespace = ag(r.namespace);
+                return {
+                    nodeKey: ag(r.node_key),
+                    kind: ag(r.kind),
+                    name: ag(r.name),
+                    ...(typeof namespace === "string" ? { namespace } : {}),
+                };
+            });
+            if (nodes.length === 0)
+                return { nodes: [], edges: [] };
+            // Edges among the reachable set (+ anchor); avoids AGE-unsupported
+            // startNode/endNode/UNWIND on variable-length paths.
+            const keys = [...new Set([nodeKey, ...nodes.map((n) => n.nodeKey)])];
+            const list = cypherStrList(keys);
+            const edgeRows = await this.cypher(c, `MATCH (a:GraphNode)-[r:REL]->(b:GraphNode)
+                 WHERE a.node_key IN ${list} AND b.node_key IN ${list}
+                 RETURN a.node_key, b.node_key, r.predicate, r.namespace, r.confidence`, ["from_key", "to_key", "predicate", "namespace", "confidence"]);
+            return {
+                nodes,
+                edges: edgeRows.map((r) => {
+                    const namespace = ag(r.namespace);
+                    return {
+                        fromKey: ag(r.from_key), toKey: ag(r.to_key),
+                        predicate: ag(r.predicate),
+                        ...(typeof namespace === "string" ? { namespace } : {}),
+                        confidence: Number(ag(r.confidence)),
+                    };
+                }),
+            };
+        });
+    }
+    /**
+     * Cheap whole-graph counts for `graph_stats` (enhancedfactstore 07 P5):
+     * a single `count()` Cypher per axis instead of a client-side fan-out.
+     * AGE has no edge-only catalog, so edges are counted via a directed match.
+     */
+    async graphStats(opts = {}) {
+        return this.withAge(async (c) => {
+            const nodeFilters = [namespacePredicate("n", opts.namespace)].filter(Boolean);
+            const nodeWhere = nodeFilters.length ? `WHERE ${nodeFilters.join(" AND ")}` : "";
+            const edgeFilters = [edgeNamespacePredicate(opts.namespace)].filter(Boolean);
+            const edgeWhere = edgeFilters.length ? `WHERE ${edgeFilters.join(" AND ")}` : "";
+            const nodeRows = await this.cypher(c, `MATCH (n:GraphNode) ${nodeWhere} RETURN count(n) AS c`, ["c"]);
+            const edgeRows = await this.cypher(c, `MATCH (a:GraphNode)-[r]->(b:GraphNode) ${edgeWhere} RETURN count(r) AS c`, ["c"]);
+            return {
+                nodeCount: Number(ag(nodeRows[0]?.c) ?? 0),
+                edgeCount: Number(ag(edgeRows[0]?.c) ?? 0),
+            };
+        });
+    }
+    // ─── writes ───────────────────────────────────────────────────────────────
+    async upsertGraphNode(n) {
+        if (!n.kind?.trim() || !n.name?.trim()) {
+            throw new Error("upsertGraphNode requires non-empty kind and name");
+        }
+        if (!n.agentId)
+            throw new Error("upsertGraphNode requires agentId");
+        const key = nodeKeyOf(n.kind, n.name);
+        return this.withAge(async (c) => {
+            const existing = await this.cypher(c, `MATCH (e:GraphNode { node_key: ${cypherStr(key)} }) RETURN e.aliases, e.namespace`, ["aliases", "namespace"]);
+            const incomingAliases = mergeAliases(n.aliases ?? [], [n.name]);
+            let ref;
+            if (existing.length > 0) {
+                const merged = mergeAliases(agArr(existing[0].aliases), incomingAliases);
+                // An explicitly provided namespace wins (including `default`/empty,
+                // which normalizes to null = unscoped); only when OMITTED do we
+                // preserve the node's existing namespace.
+                const namespace = n.namespace !== undefined
+                    ? normalizeNamespace(n.namespace)
+                    : normalizeNamespace(ag(existing[0].namespace));
+                await this.cypher(c, `MATCH (e:GraphNode { node_key: ${cypherStr(key)} })
+                     SET e.aliases = ${cypherStrList(merged)}, e.updated_at = timestamp()${namespaceSet("e", n.namespace)}
+                     RETURN e.node_key`, ["node_key"]);
+                ref = { nodeKey: key, kind: n.kind, name: n.name, ...(namespace ? { namespace } : {}), aliases: merged, created: false };
+            }
+            else {
+                const namespace = normalizeNamespace(n.namespace);
+                await this.cypher(c, `CREATE (e:GraphNode { node_key: ${cypherStr(key)}, kind: ${cypherStr(n.kind)},
+                        name: ${cypherStr(n.name)}, aliases: ${cypherStrList(incomingAliases)}${namespaceProp(n.namespace)},
+                        created_by: ${cypherStr(n.agentId)} }) RETURN e.node_key`, ["node_key"]);
+                ref = { nodeKey: key, kind: n.kind, name: n.name, ...(namespace ? { namespace } : {}), aliases: incomingAliases, created: true };
+            }
+            // Node evidence = real EVIDENCED_BY edges to lazy :Fact anchors
+            // (03-design §2.2). Unioned on every upsert.
+            for (const sk of new Set(n.evidence ?? [])) {
+                await this.linkEvidenceAnchor(c, key, sk);
+            }
+            return ref;
+        });
+    }
+    async upsertGraphEdge(e) {
+        if (!e.fromKey || !e.toKey)
+            throw new Error("upsertGraphEdge requires fromKey and toKey");
+        if (e.fromKey === e.toKey)
+            throw new Error("self-referential edge rejected");
+        if (!e.predicate?.trim())
+            throw new Error("upsertGraphEdge requires a predicate");
+        if (!e.agentId)
+            throw new Error("upsertGraphEdge requires agentId");
+        const conf = e.confidence ?? 1.0;
+        if (typeof conf !== "number" || conf < 0 || conf > 1)
+            throw new Error("confidence must be in [0,1]");
+        const pk = makePredicateKey(e.predicate);
+        return this.withAge(async (c) => {
+            // Both endpoints must exist (02 §6).
+            const ends = await this.cypher(c, `MATCH (n:GraphNode) WHERE n.node_key IN ${cypherStrList([e.fromKey, e.toKey])}
+                 RETURN n.node_key`, ["node_key"]);
+            const present = new Set(ends.map((r) => ag(r.node_key)));
+            for (const k of [e.fromKey, e.toKey]) {
+                if (!present.has(k))
+                    throw new Error(`upsertGraphEdge: endpoint node not found: ${k}`);
+            }
+            const MATCH_EDGE = `MATCH (a:GraphNode { node_key: ${cypherStr(e.fromKey)} })` +
+                `-[rel:REL { predicate_key: ${cypherStr(pk)} }]->` +
+                `(b:GraphNode { node_key: ${cypherStr(e.toKey)} })`;
+            const existingRows = await this.cypher(c, `${MATCH_EDGE} RETURN rel.confidence, rel.observations, rel.evidence, rel.namespace`, ["confidence", "observations", "evidence", "namespace"]);
+            const existing = existingRows.length > 0
+                ? {
+                    confidence: Number(ag(existingRows[0].confidence)),
+                    observations: Number(ag(existingRows[0].observations)),
+                    evidence: agArr(existingRows[0].evidence),
+                    namespace: normalizeNamespace(ag(existingRows[0].namespace)),
+                }
+                : null;
+            const d = decideEdgeUpsert({ confidence: conf, evidence: e.evidence }, existing);
+            if (d.action === "create") {
+                await this.cypher(c, `MATCH (a:GraphNode { node_key: ${cypherStr(e.fromKey)} }), (b:GraphNode { node_key: ${cypherStr(e.toKey)} })
+                     CREATE (a)-[rel:REL { predicate: ${cypherStr(e.predicate)}, predicate_key: ${cypherStr(pk)},
+                        confidence: ${cypherNum(d.confidence)}, observations: ${cypherNum(d.observations)},
+                        asserted_by: ${cypherStrList([e.agentId])}, evidence: ${cypherStrList(d.evidence)}${namespaceProp(e.namespace)},
+                        model: ${cypherStr(e.model ?? "")}, first_seen: timestamp(), last_seen: timestamp() }]->(b)
+                     RETURN rel.predicate_key`, ["predicate_key"]);
+            }
+            else if (d.action === "reinforce") {
+                await this.cypher(c, `${MATCH_EDGE}
+                     SET rel.confidence = ${cypherNum(d.confidence)}, rel.observations = ${cypherNum(d.observations)},
+                         rel.evidence = ${cypherStrList(d.evidence)}, rel.last_seen = timestamp()${namespaceSet("rel", e.namespace)}
+                     RETURN rel.predicate_key`, ["predicate_key"]);
+            }
+            // action === "noop": already-known evidence only — leave untouched (GR7).
+            const namespace = normalizeNamespace(e.namespace) ?? existing?.namespace ?? undefined;
+            return {
+                fromKey: e.fromKey, toKey: e.toKey, predicate: e.predicate, predicateKey: pk,
+                ...(namespace ? { namespace } : {}),
+                confidence: d.confidence, observations: d.observations,
+                reinforced: d.action === "reinforce",
+            };
+        });
+    }
+    async mergeGraphNodes(fromKey, intoKey, reason, opts = {}) {
+        await this.withAge(async (c) => {
+            const ns = namespacePredicate("e", opts.namespace);
+            const dup = await this.cypher(c, `MATCH (e:GraphNode { node_key: ${cypherStr(fromKey)} }) ${ns ? `WHERE ${ns}` : ""} RETURN e.aliases`, ["aliases"]);
+            if (dup.length === 0)
+                return; // nothing to merge
+            const survivorNs = namespacePredicate("e", opts.namespace);
+            const survivor = await this.cypher(c, `MATCH (e:GraphNode { node_key: ${cypherStr(intoKey)} }) ${survivorNs ? `WHERE ${survivorNs}` : ""} RETURN e.aliases`, ["aliases"]);
+            if (survivor.length === 0)
+                throw new Error(`mergeGraphNodes: merge target not found: ${intoKey}`);
+            // 1. Union aliases onto the survivor (+ audit note).
+            const merged = mergeAliases(agArr(survivor[0].aliases), agArr(dup[0].aliases));
+            await this.cypher(c, `MATCH (s:GraphNode { node_key: ${cypherStr(intoKey)} })
+                 SET s.aliases = ${cypherStrList(merged)}, s.merged_note = ${cypherStr(reason)}
+                 RETURN s.node_key`, ["node_key"]);
+            // 2. Repoint REL edges, HARDENED against duplicate triples (03 §7):
+            //    when the survivor already has the same (other, predicate_key)
+            //    edge, COMBINE (evidence union, observations sum, noisy-OR)
+            //    instead of creating a second edge. AGE has no APOC refactor,
+            //    so this is read-decide-write per edge.
+            const repoint = async (direction) => {
+                const match = direction === "out"
+                    ? `MATCH (d:GraphNode { node_key: ${cypherStr(fromKey)} })-[r:REL]->(t:GraphNode)`
+                    : `MATCH (t:GraphNode)-[r:REL]->(d:GraphNode { node_key: ${cypherStr(fromKey)} })`;
+                const rows = await this.cypher(c, `${match} RETURN t.node_key, r.predicate, r.predicate_key, r.confidence, r.observations, r.evidence`, ["other_key", "predicate", "predicate_key", "confidence", "observations", "evidence"]);
+                for (const r of rows) {
+                    const other = ag(r.other_key);
+                    if (other === intoKey)
+                        continue; // dup↔survivor edge: drop, never self-loop
+                    const pk = ag(r.predicate_key);
+                    const fromK = direction === "out" ? intoKey : other;
+                    const toK = direction === "out" ? other : intoKey;
+                    const ex = await this.cypher(c, `MATCH (a:GraphNode { node_key: ${cypherStr(fromK)} })-[rel:REL { predicate_key: ${cypherStr(pk)} }]->(b:GraphNode { node_key: ${cypherStr(toK)} })
+                         RETURN rel.confidence, rel.observations, rel.evidence`, ["confidence", "observations", "evidence"]);
+                    if (ex.length > 0) {
+                        // Evidence-aware combine (same principle as GR7): when the
+                        // duplicate edge brings NO novel evidence, the survivor
+                        // already absorbed it — drop the dup edge without summing
+                        // observations / noisy-OR-ing again, so a replayed merge
+                        // cannot double-count. Evidence-less duplicates can't be
+                        // deduped and still combine.
+                        const exEv = agArr(ex[0].evidence);
+                        const dupEv = agArr(r.evidence);
+                        const known = new Set(exEv);
+                        const novel = dupEv.filter((e) => !known.has(e));
+                        if (dupEv.length > 0 && novel.length === 0)
+                            continue;
+                        const conf = reinforceConfidence(Number(ag(ex[0].confidence)), Number(ag(r.confidence)));
+                        const obs = Number(ag(ex[0].observations)) + Number(ag(r.observations));
+                        const ev = [...exEv, ...novel];
+                        await this.cypher(c, `MATCH (a:GraphNode { node_key: ${cypherStr(fromK)} })-[rel:REL { predicate_key: ${cypherStr(pk)} }]->(b:GraphNode { node_key: ${cypherStr(toK)} })
+                             SET rel.confidence = ${cypherNum(clamp01(conf))}, rel.observations = ${cypherNum(obs)},
+                                 rel.evidence = ${cypherStrList(ev)}
+                             RETURN rel.predicate_key`, ["predicate_key"]);
+                    }
+                    else {
+                        await this.cypher(c, `MATCH (a:GraphNode { node_key: ${cypherStr(fromK)} }), (b:GraphNode { node_key: ${cypherStr(toK)} })
+                             CREATE (a)-[rel:REL { predicate: ${cypherStr(ag(r.predicate))}, predicate_key: ${cypherStr(pk)},
+                                confidence: ${cypherNum(Number(ag(r.confidence)))}, observations: ${cypherNum(Number(ag(r.observations)))},
+                                evidence: ${cypherStrList(agArr(r.evidence))} }]->(b)
+                             RETURN rel.predicate_key`, ["predicate_key"]);
+                    }
+                }
+            };
+            await repoint("out");
+            await repoint("in");
+            // 3. Repoint node evidence (EVIDENCED_BY anchors) onto the survivor.
+            const anchors = await this.cypher(c, `MATCH (d:GraphNode { node_key: ${cypherStr(fromKey)} })-[:EVIDENCED_BY]->(f:Fact)
+                 RETURN f.scope_key`, ["scope_key"]);
+            for (const r of anchors) {
+                await this.linkEvidenceAnchor(c, intoKey, ag(r.scope_key));
+            }
+            // 4. Remove the duplicate (and all its remaining edges).
+            await this.cypher(c, `MATCH (d:GraphNode { node_key: ${cypherStr(fromKey)} }) DETACH DELETE d`, []);
+        });
+    }
+    async deleteGraphNode(nodeKey, opts = {}) {
+        return this.withAge(async (c) => {
+            const ns = namespacePredicate("e", opts.namespace);
+            const exists = await this.cypher(c, `MATCH (e:GraphNode { node_key: ${cypherStr(nodeKey)} }) ${ns ? `WHERE ${ns}` : ""} RETURN e.node_key`, ["node_key"]);
+            if (exists.length === 0)
+                return false;
+            await this.cypher(c, `MATCH (e:GraphNode { node_key: ${cypherStr(nodeKey)} }) ${ns ? `WHERE ${ns}` : ""} DETACH DELETE e`, []);
+            return true;
+        });
+    }
+    async deleteGraphEdge(fromKey, toKey, predicateKey, opts = {}) {
+        return this.withAge(async (c) => {
+            const MATCH = `MATCH (a:GraphNode { node_key: ${cypherStr(fromKey)} })` +
+                `-[r:REL { predicate_key: ${cypherStr(predicateKey)} }]->` +
+                `(b:GraphNode { node_key: ${cypherStr(toKey)} })`;
+            const ns = edgeNamespacePredicate(opts.namespace);
+            const where = ns ? ` WHERE ${ns}` : "";
+            const exists = await this.cypher(c, `${MATCH}${where} RETURN r.predicate_key`, ["predicate_key"]);
+            if (exists.length === 0)
+                return false;
+            await this.cypher(c, `${MATCH}${where} DELETE r`, []);
+            return true;
+        });
+    }
+    async removeGraphEvidence(scopeKey, opts = {}) {
+        if (!scopeKey?.trim())
+            throw new Error("removeGraphEvidence requires scopeKey");
+        return this.withAge(async (c) => {
+            let nodeEvidenceRemoved = 0;
+            let edgeEvidenceRemoved = 0;
+            let nodesDeleted = 0;
+            let edgesDeleted = 0;
+            const nodeNs = namespacePredicate("n", opts.namespace);
+            const nodeRows = await this.cypher(c, `MATCH (n:GraphNode)-[:EVIDENCED_BY]->(f:Fact { scope_key: ${cypherStr(scopeKey)} })
+                 ${nodeNs ? `WHERE ${nodeNs}` : ""}
+                 RETURN DISTINCT n.node_key`, ["node_key"]);
+            const nodeKeys = [...new Set(nodeRows.map((r) => ag(r.node_key)).filter(Boolean))];
+            if (nodeKeys.length > 0) {
+                const removed = await this.cypher(c, `MATCH (n:GraphNode)-[ev:EVIDENCED_BY]->(f:Fact { scope_key: ${cypherStr(scopeKey)} })
+                     WHERE n.node_key IN ${cypherStrList(nodeKeys)}
+                     DELETE ev
+                     RETURN count(ev) AS c`, ["c"]);
+                nodeEvidenceRemoved = Number(ag(removed[0]?.c) ?? 0);
+            }
+            const edgeNs = edgeNamespacePredicate(opts.namespace);
+            const edgeRows = await this.cypher(c, `MATCH (a:GraphNode)-[r:REL]->(b:GraphNode)
+                 WHERE ${edgeNs ? `${edgeNs} AND ` : ""}${cypherStr(scopeKey)} IN r.evidence
+                 RETURN a.node_key, b.node_key, r.predicate_key, r.evidence`, ["from_key", "to_key", "predicate_key", "evidence"]);
+            for (const row of edgeRows) {
+                const fromKey = ag(row.from_key);
+                const toKey = ag(row.to_key);
+                const predicateKey = ag(row.predicate_key);
+                const evidence = agArr(row.evidence);
+                const nextEvidence = evidence.filter((sk) => sk !== scopeKey);
+                edgeEvidenceRemoved += evidence.length - nextEvidence.length;
+                if (nextEvidence.length === 0) {
+                    const ns = edgeNamespacePredicate(opts.namespace);
+                    await this.cypher(c, `MATCH (a:GraphNode { node_key: ${cypherStr(fromKey)} })-[r:REL { predicate_key: ${cypherStr(predicateKey)} }]->(b:GraphNode { node_key: ${cypherStr(toKey)} })
+                         ${ns ? `WHERE ${ns}` : ""}
+                         DELETE r`, []);
+                    edgesDeleted += 1;
+                }
+                else {
+                    await this.cypher(c, `MATCH (a:GraphNode { node_key: ${cypherStr(fromKey)} })-[r:REL { predicate_key: ${cypherStr(predicateKey)} }]->(b:GraphNode { node_key: ${cypherStr(toKey)} })
+                         SET r.evidence = ${cypherStrList(nextEvidence)}
+                         RETURN r.predicate_key`, ["predicate_key"]);
+                }
+            }
+            for (const nodeKey of nodeKeys) {
+                // Only delete a node that is now FULLY orphaned. A node can lose its
+                // own EVIDENCED_BY anchors while still being an endpoint of edges that
+                // other live facts evidence — a bare DETACH DELETE would silently
+                // destroy those still-evidenced edges (H2). The edge pass above has
+                // already removed edges that became evidence-less, so any REL edge
+                // that survives here is still validly evidenced: keep the node.
+                const remaining = await this.cypher(c, `MATCH (n:GraphNode { node_key: ${cypherStr(nodeKey)} })-[:EVIDENCED_BY]->(f:Fact)
+                     RETURN f.scope_key LIMIT 1`, ["scope_key"]);
+                if (remaining.length > 0)
+                    continue;
+                const stillLinked = await this.cypher(c, `MATCH (n:GraphNode { node_key: ${cypherStr(nodeKey)} })-[r:REL]-()
+                     RETURN r.predicate_key LIMIT 1`, ["predicate_key"]);
+                if (stillLinked.length > 0)
+                    continue;
+                await this.cypher(c, `MATCH (n:GraphNode { node_key: ${cypherStr(nodeKey)} }) DETACH DELETE n`, []);
+                nodesDeleted += 1;
+            }
+            return { scopeKey, nodeEvidenceRemoved, edgeEvidenceRemoved, nodesDeleted, edgesDeleted };
+        });
+    }
+    /**
+     * Drop graph data for an EXACT namespace (graph-fact-search enhancements,
+     * `deleteGraphNamespace`). NOT subtree: only records whose own namespace
+     * equals `namespace` are removed — child namespaces are deleted explicitly.
+     * Edges with this namespace are removed first; then nodes with this
+     * namespace are DETACH DELETEd (which also clears their remaining edges and
+     * EVIDENCED_BY anchors). Idempotent / re-runnable. Refuses the reserved
+     * `default` token / empty (the NULL partition is never bulk-deleted).
+     */
+    async deleteNamespaceData(namespace) {
+        const ns = normalizeNamespace(namespace);
+        if (!ns) {
+            throw new Error("deleteNamespaceData requires a concrete namespace (not 'default' or empty)");
+        }
+        const exact = cypherStr(ns);
+        return this.withAge(async (c) => {
+            // Edges removed = edges whose OWN namespace is exactly this namespace
+            // OR edges incident to a node in this namespace (those vanish when the
+            // node is DETACH DELETEd). Counting both keeps edgesDeleted honest:
+            // deleting a namespace's nodes also drops edges that reach into other
+            // namespaces — an unavoidable consequence of removing an endpoint.
+            const edgeMatch = `MATCH (a:GraphNode)-[r:REL]->(b:GraphNode) ` +
+                `WHERE r.namespace = ${exact} OR a.namespace = ${exact} OR b.namespace = ${exact}`;
+            const edgeCountRows = await this.cypher(c, `${edgeMatch} RETURN count(r) AS c`, ["c"]);
+            const edgesDeleted = Number(ag(edgeCountRows[0]?.c) ?? 0);
+            if (edgesDeleted > 0) {
+                await this.cypher(c, `${edgeMatch} DELETE r`, []);
+            }
+            // Nodes whose namespace is EXACTLY this namespace (not subtree).
+            const nodeCountRows = await this.cypher(c, `MATCH (n:GraphNode) WHERE n.namespace = ${exact} RETURN count(n) AS c`, ["c"]);
+            const nodesDeleted = Number(ag(nodeCountRows[0]?.c) ?? 0);
+            if (nodesDeleted > 0) {
+                await this.cypher(c, `MATCH (n:GraphNode) WHERE n.namespace = ${exact} DETACH DELETE n`, []);
+            }
+            return { nodesDeleted, edgesDeleted };
+        });
+    }
+}
+//# sourceMappingURL=graph-queries.js.map