pilotswarm-horizon-store 0.2.2

package/README.md

@@ -0,0 +1,154 @@
+# `pilotswarm-horizon-store`
+
+Optional HorizonDB-backed providers for PilotSwarm enhanced facts/search and the
+open knowledge graph. The package is published alongside `pilotswarm-sdk` and is
+intended for apps that keep stock PostgreSQL as the PilotSwarm runtime store while
+opting into HorizonDB for knowledge retrieval and graph-backed harvester workflows.
+
+## What this is
+
+An **optional, enhanced read interface** over the PilotSwarm Facts Store, built
+exclusively on **Azure HorizonDB** (preview) capabilities:
+
+| HorizonDB capability | Role here |
+| --- | --- |
+| `pg_textsearch` | Ranked lexical recall (upgrade over today's `LIKE` / `key_pattern`) |
+| HTTP embedding endpoint | In-DB embedding generation via a configurable endpoint + semantic (vector ANN) recall |
+| Apache AGE | Relationship/lineage graph overlay (structure only) |
+| `pg_durable` | Durable, idle-aware maintenance pipeline (embeddings only) |
+
+> **Embeddings come from a configurable HTTP endpoint, not HorizonDB's built-in
+> `aiModelManagement`.** You pass an OpenAI/Azure-OpenAI-compatible embeddings
+> endpoint to the provider; the `pg_durable` loop calls it over HTTP from inside
+> the database (`sql/006`), and a Node fallback (`embedPending()`) covers
+> clusters without the `http` extension. See [CRAWLER-SPEC.md](./CRAWLER-SPEC.md) §3.
+
+## Hard design rules (carried from PilotSwarm)
+
+1. **The `facts` table stays authoritative.** tsvector, vector, and AGE are
+   *derived indexes/overlays* — never the source of truth. The graph stores
+   **ids and structure, never fact values or ACLs**.
+2. **Governance is unchanged.** Scope (`scope_key`), `shared` / `transient`,
+   namespace ACLs, and spawn-tree visibility are still enforced by stored
+   procedures. Search modes are extra `AND` clauses inside the existing
+   visibility filter — they can only narrow what a caller already sees.
+3. **Determinism boundary.** Anything LLM/IO (embedding, distillation,
+   relatedness) runs as a `pg_durable` **activity**, never inline orchestration.
+4. **Rebuildable.** Every derived artifact (tsvector, embeddings, AGE graph)
+   can be dropped and rebuilt from `facts` rows.
+
+## Layout
+
+```
+packages/horizon-store/
+  SPEC.md            ← the design: data model, compute/API/frequency, scenarios
+  CRAWLER.md         ← open, ontology-free LLM graph crawler (entities + free-form relationships)
+  CRAWLER-SPEC.md    ← implementation contract: API, schema, compute tiers, PG mailing-list example
+  src/
+    types.ts          ← EnhancedFactStore + GraphCrawlerInterface contracts + DTOs
+    config.ts         ← provider config incl. the embedding HTTP endpoint
+    embedding-client.ts ← Node-side embeddings client (query-time + test reference)
+    query-builder.ts  ← DB-less hybrid ranking/fusion + SQL fragment builders (unit-tested)
+    graph-model.ts    ← DB-less open-graph quality core: canonicalize, predicate, confidence (unit-tested)
+    migrations.ts     ← Node-runnable schema + AGE setup (mirrors sql/001–005)
+    http-embedding.ts ← Node-runnable in-DB HTTP embedding pipeline (mirrors sql/006)
+    horizon-store.ts  ← HorizonFactStore: drop-in EnhancedFactStore + open-graph crawler
+    agent-tools.ts    ← optional agent tools (search / related / graph) for injection
+    index.ts          ← public exports
+  sql/
+    001_enrich_facts.sql  ← tsvector + embedding columns + indexes
+    002_age_graph.sql     ← AGE node/edge model + structural backfill
+    003_search_procs.sql  ← facts_search_facts + related/lineage procs
+    004_pipelines.sql     ← pg_durable maintenance pipeline (embeddings only)
+    005_open_graph.sql    ← open Entity / REL / EVIDENCED_BY graph for the crawler
+    006_embeddings_http.sql ← in-DB HTTP embedding pipeline (replaces aiModelManagement)
+  poc/                ← runnable harnesses (lexical/hybrid/crawler run DB-less today)
+  test/               ← DB-less unit tests (run in CI without HorizonDB)
+    integration/      ← live tests against a real HorizonDB (skip without HORIZON_DATABASE_URL)
+```
+
+## Drop-in replacement
+
+`HorizonFactStore` implements the full PilotSwarm `FactStore` API
+(`storeFact` / `readFacts` / `deleteFact` / stats / …) with identical semantics,
+so it can replace `PgFactStore` anywhere. It **adds** retrieval methods
+(`searchFacts` / `relatedFacts` / `lineageFacts`) and the open-graph crawler
+(`upsertEntity` / `assertRelationship` / …). Apps opt into the extras; nothing
+in the base behavior changes.
+
+```js
+import { HorizonFactStore, createFactsTools } from "pilotswarm-horizon-store";
+
+const store = await HorizonFactStore.create({
+  connectionString: process.env.HORIZON_DATABASE_URL,
+  embedding: { url: EMBED_URL, model: "text-embedding-3-small", dim: 1536, apiKey: KEY },
+});
+await store.initialize();
+
+// ...use exactly like the existing FactStore, plus:
+await store.searchFacts("jsonb subscripting", { mode: "hybrid" }, { unrestricted: true });
+
+// Optionally inject tools into your agents:
+const tools = createFactsTools(store, { graphWrite: true }); // spread into worker.registerTools([...])
+```
+
+## Running
+
+```bash
+cd packages/horizon-store
+npm install
+npm run build
+npm test                 # DB-less unit tests — no HorizonDB needed
+npm run poc:crawler      # open-graph harvest scenario — runs DB-less today
+
+# Live integration tests against a real HorizonDB (auto-skip if unset):
+export HORIZON_DATABASE_URL=postgres://user:pw@host/db
+npm run test:integration # pg_durable HTTP embeddings, AGE Cypher, full provider
+```
+
+## Evaluation
+
+The incubator ships a two-axis evaluation surface — **system** evals (is the
+harvest correct, durable, fast?) and **quality** evals (does the graph actually
+help an LLM answer better than parametric knowledge + live web?). The full system
+overview — how the harvester builds the KB and how every eval tier fits together —
+is in [docs/harvester-and-eval.md](./docs/harvester-and-eval.md).
+
+| Tier | Where | What it proves |
+| --- | --- | --- |
+| Scenario (system) | [eval/README.md](./eval/README.md) | Cold/incremental harvest, replay determinism, scoped publication, reader fact-pivot |
+| Quality (single model) | [eval/graph-quality.mjs](./eval/graph-quality.mjs) | Graph arm vs parametric+web baseline, blind-judged against corpus ground truth |
+| **Quality (cross-model sweep)** | [eval/sweep/](./eval/sweep/) | A 3×3×3 **harvester × query × judge** tensor that isolates judge bias |
+
+### Cross-model sweep
+
+The sweep answers "is the graph really better, or just a lucky model / biased
+judge?" by sweeping three independent axes into a score tensor and generating a
+bias-aware report grounded in a deterministic numeric summary. Latest run
+(`pgsql-hackers-recent`, N=8 questions/cell, 216 graded rows):
+
+> **graph 4.76 vs baseline 2.42** (Δ +2.34 on a 1–5 scale), graph winning 163/216
+> head-to-head with no judge able to flip the verdict — and it holds with the
+> graph answers being *shorter* than the baseline. Honestly deflated to a
+> ~+1.8–2.0 *substantive* edge once baseline web-timeout failures are separated
+> out (see the report's methodology + caveats).
+
+- Results: [eval/sweep/REPORT.md](./eval/sweep/REPORT.md) (narrative) + [eval/sweep/summary.json](./eval/sweep/summary.json) (authoritative numbers).
+- Run + interpret: skill [horizon-facts-eval-sweep/SKILL.md](../../.github/skills/horizon-facts-eval-sweep/SKILL.md) and agent [horizon-facts-eval-sweep.agent.md](../../.github/agents/horizon-facts-eval-sweep.agent.md) (commands + manual graph-validation queries).
+- The bulky per-cell intermediates (`scores/`, `transcripts/`, `logs/`) are gitignored and regenerable; the driver, config, pinned `questions.json`, and final `REPORT.md` / `summary.json` are tracked, so any run reproduces.
+
+## Specs & docs
+
+**Enhanced facts store (this incubator):**
+[SPEC.md](./SPEC.md) (base design) ·
+[CRAWLER.md](./CRAWLER.md) / [CRAWLER-SPEC.md](./CRAWLER-SPEC.md) (open-graph crawler) ·
+[GAP-ANALYSIS.md](./GAP-ANALYSIS.md).
+Upstream provider contract + tool/test specs:
+[docs/proposals/enhancedfactstore/](../../docs/proposals/enhancedfactstore/)
+(`01-functional-spec` · `02-api-reference` · `03-design` · `04-test-spec` ·
+`05-tools-spec` · `06-provider-test-plan`).
+
+**Harvester & evaluation:**
+[docs/harvester-and-eval.md](./docs/harvester-and-eval.md) (full system overview) ·
+[eval/README.md](./eval/README.md) (scenario tier) ·
+[eval/sweep/REPORT.md](./eval/sweep/REPORT.md) (latest cross-model sweep).

package/dist/src/agent-tools.d.ts

@@ -0,0 +1,32 @@
+import type { AccessContext, GraphStore } from "./types.js";
+import type { HorizonDBFactStore } from "./horizon-store.js";
+export interface AgentTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    handler: (args: any) => Promise<unknown>;
+}
+export type Role = "reader" | "harvester";
+export interface FactsToolsOptions {
+    /** Which bundle to build. Default "reader". */
+    role?: Role;
+    /**
+     * Access context resolver for the READER-scoped tools. Default:
+     * unrestricted (single-tenant). Override for multi-tenant sessions.
+     * The crawl-queue tools never use it — they are privileged by contract.
+     */
+    resolveAccess?: (args: any) => AccessContext;
+    /** Agent identity recorded on graph writes. Default "harvester". */
+    agentId?: string;
+    /**
+     * When true, the privileged `facts_read_uncrawled` queue tool only returns
+     * facts that already have an embedding; un-embedded facts are skipped this
+     * turn and reappear once the in-DB embed loop catches up. This is a HARVEST
+     * POLICY set by the host (not an LLM-controlled argument): enable it when
+     * embeddings are configured so the harvester can similarity-refine the
+     * graph from each fact's stored vector.
+     */
+    embeddedOnly?: boolean;
+}
+export declare function createFactsTools(factStore: HorizonDBFactStore, graphStore: GraphStore | undefined, opts?: FactsToolsOptions): AgentTool[];
+//# sourceMappingURL=agent-tools.d.ts.map

package/dist/src/agent-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tools.d.ts","sourceRoot":"","sources":["../../src/agent-tools.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACR,aAAa,EAAE,UAAU,EAC5B,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,MAAM,WAAW,SAAS;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5C;AAED,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1C,MAAM,WAAW,iBAAiB;IAC9B,+CAA+C;IAC/C,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,aAAa,CAAC;IAC7C,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,gBAAgB,CAC5B,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,IAAI,GAAE,iBAAsB,GAC7B,SAAS,EAAE,CA0Rb"}

package/dist/src/agent-tools.js

@@ -0,0 +1,263 @@
+// pilotswarm-horizon-store — LLM-facing agent tools (05-tools-spec).
+//
+// Tool names and contracts follow docs/proposals/enhancedfactstore/05-tools-spec.md
+// exactly: `facts_*` over the facts store, `graph_*` over the open graph. Two
+// role bundles over the same corpus:
+//
+//   READER    — facts_search / facts_similar / facts_read + the graph READ tools.
+//   HARVESTER — everything the reader gets, plus the PRIVILEGED crawl-queue
+//               tools (facts_read_uncrawled / facts_mark_crawled) and the graph
+//               WRITE tools. Crawling sees ALL facts across scopes by design
+//               (01 §6.6); only grant this bundle to the trusted harvester role.
+//
+// Descriptors are host-agnostic (name + JSON-schema + handler), mapping onto
+// PilotSwarm's defineTool() shape.
+export function createFactsTools(factStore, graphStore, opts = {}) {
+    const role = opts.role ?? "reader";
+    const access = opts.resolveAccess ?? (() => ({ unrestricted: true }));
+    const agentId = opts.agentId ?? "harvester";
+    const embeddedOnly = opts.embeddedOnly ?? false;
+    const tools = [];
+    // ── §1 retrieval (reader + harvester) ────────────────────────────────────
+    tools.push({
+        name: "facts_search",
+        description: "Search facts by a query over the FACTS STORE ONLY. The query shape depends on mode: " +
+            "lexical = BM25 — pass KEYWORDS/terms, not a sentence; semantic = natural language (embedded); " +
+            "hybrid = a short keyword-rich phrase, used both ways. There is NO graph mode — use graph_search_nodes. " +
+            "Returned scopeKey values are the natural seeds for graph_search_nodes.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Keywords for lexical, natural language for semantic, keyword-rich phrase for hybrid." },
+                mode: { type: "string", enum: ["lexical", "semantic", "hybrid"], description: "Default hybrid." },
+                namespace: { type: "string", description: "Key-prefix filter, e.g. 'archive/pgsql-hackers'." },
+                tags: { type: "array", items: { type: "string" }, description: "Restrict to facts carrying all these tags." },
+                limit: { type: "number", description: "Max results (default 20)." },
+            },
+            required: ["query"],
+        },
+        handler: (a) => {
+            const o = { mode: a.mode, namespace: a.namespace, tags: a.tags, limit: a.limit };
+            return factStore.searchFacts(a.query, o, access(a));
+        },
+    });
+    tools.push({
+        name: "facts_similar",
+        description: "Given a fact you already have, return the semantically nearest other facts " +
+            "(vector kNN over the fact's stored embedding — no query text, no re-embedding). Anchor excluded.",
+        parameters: {
+            type: "object",
+            properties: {
+                scopeKey: { type: "string", description: "The anchor fact's scope_key." },
+                k: { type: "number", description: "Top-k neighbours (default 8)." },
+                minScore: { type: "number", description: "Drop neighbours below this cosine score (0..1)." },
+            },
+            required: ["scopeKey"],
+        },
+        handler: (a) => factStore.similarFacts(a.scopeKey, { k: a.k, minScore: a.minScore }, access(a)),
+    });
+    tools.push({
+        name: "facts_read",
+        description: "Read facts directly by key/scopeKeys/tags/scope — no ranking. Use scopeKeys to resolve the " +
+            "evidence arrays returned by graph tools back into facts. scope: 'descendants' reads the spawn-tree (lineage).",
+        parameters: {
+            type: "object",
+            properties: {
+                keyPattern: { type: "string", description: "Key prefix/pattern filter." },
+                scopeKeys: { type: "array", items: { type: "string" }, description: "Explicit fact scope_keys (e.g. graph evidence). Inaccessible/unknown keys are silently omitted." },
+                tags: { type: "array", items: { type: "string" } },
+                scope: { type: "string", enum: ["accessible", "shared", "session", "descendants"], description: "Default accessible." },
+                limit: { type: "number" },
+            },
+        },
+        handler: (a) => factStore.readFacts({ keyPattern: a.keyPattern, scopeKeys: a.scopeKeys, tags: a.tags, scope: a.scope, limit: a.limit }, access(a)),
+    });
+    // ── §3 graph read (reader + harvester) — only when a graph is configured ──
+    if (graphStore) {
+        tools.push({
+            name: "graph_search_nodes",
+            description: "Find / expand graph nodes. RESOLVE step (does this entity exist? — use kind + nameLike before every " +
+                "create) and PIVOT step (seeds = fact scope_keys from facts_search pivot via EVIDENCED_BY; node keys " +
+                "expand directly; depth bounds the hops). Each hit carries its EVIDENCED_BY fact scope_keys — feed " +
+                "evidence straight into facts_read.",
+            parameters: {
+                type: "object",
+                properties: {
+                    kind: { type: "string", description: "Free-text node kind filter ('person', 'patch', …)." },
+                    nameLike: { type: "string", description: "Lexical match on node name or any alias. The resolve key." },
+                    seeds: { type: "array", items: { type: "string" }, description: "Fact scope_keys OR node keys to anchor from." },
+                    depth: { type: "number", description: "Hops to expand from seeds (1..5)." },
+                    limit: { type: "number" },
+                },
+            },
+            handler: (a) => graphStore.searchGraphNodes({ kind: a.kind, nameLike: a.nameLike, seeds: a.seeds, depth: a.depth, limit: a.limit }, access(a)),
+        });
+        tools.push({
+            name: "graph_search_edges",
+            description: "Find edges, two ways only: anchor-and-explore (set fromKey and/or toKey) or exact-predicate " +
+                "(predicate/predicateKey, exact equality — no fuzzy match).",
+            parameters: {
+                type: "object",
+                properties: {
+                    predicate: { type: "string", description: "EXACT predicate text." },
+                    predicateKey: { type: "string", description: "EXACT normalized key (preferred, surface-stable)." },
+                    fromKey: { type: "string" },
+                    toKey: { type: "string" },
+                    minConfidence: { type: "number" },
+                    limit: { type: "number" },
+                },
+            },
+            handler: (a) => graphStore.searchGraphEdges(a, access(a)),
+        });
+        tools.push({
+            name: "graph_neighbourhood",
+            description: "Bounded subgraph around a node — 'show me everything connected to X'.",
+            parameters: {
+                type: "object",
+                properties: {
+                    nodeKey: { type: "string" },
+                    depth: { type: "number", description: "Hops (clamped 1..5)." },
+                },
+                required: ["nodeKey", "depth"],
+            },
+            handler: (a) => graphStore.graphNeighbourhood(a.nodeKey, a.depth, access(a)),
+        });
+    }
+    if (role !== "harvester")
+        return tools;
+    // Crawl-queue + graph-write are harvester tools that only make sense with a
+    // graph to harvest into (07 §1.5) — gate them on graphStore presence.
+    if (graphStore) {
+        // ── §2 crawl queue (HARVESTER ONLY — privileged, all scopes) ─────────────
+        tools.push({
+            name: "facts_read_uncrawled",
+            description: "PRIVILEGED work queue: facts not yet incorporated into the graph (new or edited since last crawl), " +
+                "across ALL scopes. Keep each fact's scopeKey and etag — both are the receipt facts_mark_crawled needs.",
+            parameters: {
+                type: "object",
+                properties: {
+                    namespace: { type: "string", description: "Restrict the queue to a key prefix." },
+                    limit: { type: "number", description: "Max facts this batch (default 20)." },
+                },
+            },
+            handler: (a) => factStore.readUncrawledFacts({ namespace: a.namespace, limit: a.limit, embeddedOnly }),
+        });
+        tools.push({
+            name: "facts_mark_crawled",
+            description: "Stamp facts as incorporated so they leave the queue. Pass each fact's scopeKey and etag from facts_read_uncrawled. " +
+                "A skipped stamp means the fact was already marked, changed since your read, or no longer exists; re-read if needed.",
+            parameters: {
+                type: "object",
+                properties: {
+                    stamps: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                scopeKey: { type: "string" },
+                                etag: { type: "number" },
+                            },
+                            required: ["scopeKey", "etag"],
+                        },
+                    },
+                },
+                required: ["stamps"],
+            },
+            handler: (a) => factStore.markFactsCrawled(a.stamps),
+        });
+        tools.push({
+            name: "graph_remove_evidence",
+            description: "Reconcile a soft-deleted fact with the graph: remove this fact scopeKey from node EVIDENCED_BY anchors " +
+                "and edge evidence arrays, deleting graph nodes/edges that become evidence-less. Call this for " +
+                "facts_read_uncrawled rows where deletedAt/deleted_at is set, then mark the fact crawled with its scopeKey and etag.",
+            parameters: {
+                type: "object",
+                properties: {
+                    scopeKey: { type: "string", description: "Deleted fact scopeKey from facts_read_uncrawled." },
+                    namespace: { type: "string", description: "Optional graph namespace guard." },
+                },
+                required: ["scopeKey"],
+            },
+            handler: (a) => graphStore.removeGraphEvidence(a.scopeKey, { namespace: a.namespace }),
+        });
+        // ── §4 graph write (HARVESTER ONLY) ──────────────────────────────────────
+        tools.push({
+            name: "graph_upsert_node",
+            description: "Create a node, or merge into an existing one (idempotent; aliases and evidence union in). " +
+                "RESOLVE BEFORE YOU CREATE: graph_search_nodes by nameLike first. Evidence is optional in the " +
+                "contract, but pass the source fact's scope_key — it is the provenance, and what makes " +
+                "reinforcement dedup work. The graph is SHARED: anything you incorporate is visible to every reader.",
+            parameters: {
+                type: "object",
+                properties: {
+                    kind: { type: "string", description: "Free text: person, patch, code_file, thread…" },
+                    name: { type: "string", description: "Canonical surface form." },
+                    aliases: { type: "array", items: { type: "string" }, description: "Other observed surface forms." },
+                    evidence: { type: "array", items: { type: "string" }, description: "Fact scope_keys justifying this node. Pass the source fact." },
+                },
+                required: ["kind", "name"],
+            },
+            handler: (a) => graphStore.upsertGraphNode({ ...a, agentId }),
+        });
+        tools.push({
+            name: "graph_upsert_edge",
+            description: "Assert a free-text relationship, or reinforce an existing one. Re-stating the same " +
+                "(fromKey, predicate, toKey) does not duplicate — it bumps observations and combines confidence " +
+                "(noisy-OR) ONLY when you bring new evidence; same-evidence replays are harmless no-ops. " +
+                "Pass RESOLVED nodeKeys, not raw names. One verb per relationship.",
+            parameters: {
+                type: "object",
+                properties: {
+                    fromKey: { type: "string", description: "Source node key (from graph_upsert_node / graph_search_nodes)." },
+                    toKey: { type: "string", description: "Target node key." },
+                    predicate: { type: "string", description: "Free-text verb, e.g. 'revives argument from'." },
+                    confidence: { type: "number", description: "0..1 for THIS observation (default 1.0)." },
+                    evidence: { type: "array", items: { type: "string" }, description: "Fact scope_keys justifying the edge. Pass the source fact." },
+                },
+                required: ["fromKey", "toKey", "predicate"],
+            },
+            handler: (a) => graphStore.upsertGraphEdge({ ...a, agentId }),
+        });
+        tools.push({
+            name: "graph_merge_nodes",
+            description: "Entity resolution: fold a duplicate node into the survivor (union aliases, repoint edges, delete " +
+                "the duplicate). Use when you discover two nodes are the same entity after the fact.",
+            parameters: {
+                type: "object",
+                properties: {
+                    fromKey: { type: "string", description: "Duplicate to remove." },
+                    intoKey: { type: "string", description: "Survivor to keep." },
+                    reason: { type: "string", description: "Why they're the same (audit)." },
+                },
+                required: ["fromKey", "intoKey", "reason"],
+            },
+            handler: async (a) => { await graphStore.mergeGraphNodes(a.fromKey, a.intoKey, a.reason); return { merged: true }; },
+        });
+        tools.push({
+            name: "graph_delete_node",
+            description: "Remove a node and all its edges (DETACH DELETE). No cascade to facts.",
+            parameters: {
+                type: "object",
+                properties: { nodeKey: { type: "string" } },
+                required: ["nodeKey"],
+            },
+            handler: async (a) => ({ deleted: await graphStore.deleteGraphNode(a.nodeKey) }),
+        });
+        tools.push({
+            name: "graph_delete_edge",
+            description: "Remove one exact edge triple. Returns whether something matched.",
+            parameters: {
+                type: "object",
+                properties: {
+                    fromKey: { type: "string" },
+                    toKey: { type: "string" },
+                    predicateKey: { type: "string" },
+                },
+                required: ["fromKey", "toKey", "predicateKey"],
+            },
+            handler: async (a) => ({ deleted: await graphStore.deleteGraphEdge(a.fromKey, a.toKey, a.predicateKey) }),
+        });
+    }
+    return tools;
+}
+//# sourceMappingURL=agent-tools.js.map

package/dist/src/agent-tools.js.map

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

package/dist/src/config.d.ts

@@ -0,0 +1,93 @@
+import type { EmbeddingEndpointConfig } from "./types.js";
+export type { EmbeddingEndpointConfig } from "./types.js";
+import type { PoolConfig } from "pg";
+export interface HorizonFactsConfig {
+    /** PostgreSQL/HorizonDB connection string. */
+    connectionString: string;
+    /** Relational schema for the facts table + procs. Default "horizon_facts". */
+    schema?: string;
+    /** AGE graph name. Default "horizon_facts". */
+    graphName?: string;
+    /**
+     * Embedding endpoint (provider-neutral, see EmbeddingEndpointConfig).
+     * Required for semantic/hybrid search and for this provider's in-DB embedding
+     * pipeline. Lexical + graph work without it. When provided, initialize()
+     * configures AND auto-starts the eternal in-DB embed loop (idempotent +
+     * advisory-locked, so repeated/concurrent instantiations never duplicate it).
+     */
+    embedding?: EmbeddingEndpointConfig;
+    /**
+     * Dimension of the vector(N) column, fixed at migration time. Defaults to
+     * embedding?.dim ?? 1536. configureEmbedder() rejects endpoints whose dim
+     * differs (a dim change requires a column migration + full re-embed).
+     */
+    embeddingDim?: number;
+    /**
+     * Vector ANN index method. "diskann" uses Azure's pg_diskann (must be
+     * allow-listed in the cluster's azure.extensions parameter group); "hnsw"
+     * uses pgvector's built-in HNSW; "auto" (default) prefers diskann and falls
+     * back to hnsw when pg_diskann is unavailable.
+     */
+    annIndex?: "diskann" | "hnsw" | "auto";
+    /**
+        * Max pool connections. Default 16. The graph layer issues several
+     * sequential Cypher statements per upsert, and the harvester fires graph
+     * tool calls in parallel; a small pool serializes those behind a few
+     * connections and connection-queue wait dominates latency (a pool of 3 was
+        * measured ~2-4x slower than 10 under concurrency=8). Override per-cluster
+     * with HORIZON_POOL_MAX, bearing in mind the cluster's max_connections.
+     */
+    poolMax?: number;
+    /** AAD / managed-identity auth (mirrors PilotSwarm's PgFactStore). */
+    useManagedIdentity?: boolean;
+    aadUser?: string;
+    /**
+     * Relational schema OWNED BY THE GRAPH PROVIDER for the namespace registry
+     * sidecar (graph-fact-search enhancements). MUST differ from the AGE graph
+     * name (`graphName`) — `create_graph()` creates a Postgres schema named after
+     * the graph, so reusing it would put the sidecar INSIDE the AGE-managed
+     * schema (droppable by drop_graph). Also distinct from the facts `schema`,
+     * since the graph store may run against a database with no facts schema at
+     * all. Defaults to `${graphName}_registry`. Override with
+     * HORIZON_GRAPH_REGISTRY_SCHEMA.
+     */
+    registrySchema?: string;
+    /**
+     * TTL (ms) for the in-provider namespace-list cache. The namespace set is
+     * small and changes rarely; the provider caches a single full snapshot and
+     * filters in memory. Writes invalidate the snapshot in-process; other
+     * workers converge within the TTL. Default 60000 (one minute). Set 0 to
+     * disable caching (always reload) — useful in tests.
+     */
+    namespaceCacheTtlMs?: number;
+}
+export declare const DEFAULT_SCHEMA = "horizon_facts";
+export declare const DEFAULT_GRAPH = "horizon_facts";
+export declare const DEFAULT_POOL_MAX = 16;
+export declare const DEFAULT_CONNECTION_TIMEOUT_MS = 15000;
+export declare const DEFAULT_NAMESPACE_CACHE_TTL_MS = 60000;
+/** Resolve config from explicit values, falling back to HORIZON_* env vars. */
+export declare function resolveConfig(partial?: Partial<HorizonFactsConfig>): HorizonFactsConfig;
+/**
+ * Build a `pg.PoolConfig` from a HorizonDB connection string, normalizing TLS
+ * the same way the PilotSwarm SDK's `pg-pool-factory` does for the CMS / facts
+ * pools, so a HorizonDB URL behaves here exactly like `DATABASE_URL` does there.
+ *
+ * Why this is needed: HorizonDB requires SSL, but its certificate chain is not in
+ * Node's default trust store, and `pg` v8 treats `sslmode=require` (and
+ * `prefer` / `verify-ca` / `verify-full`) as `verify-full` — which rejects the
+ * chain with `self-signed certificate in certificate chain`. The SDK factory
+ * handles this for `DATABASE_URL` by stripping `sslmode` from the URL and setting
+ * `ssl: { rejectUnauthorized: false }` on the pool config. This provider builds
+ * its OWN raw pools (it keeps its runtime dep surface to `pg` only and does not
+ * import the SDK), so without this helper a natural `?sslmode=require` URL fails
+ * here while the identical URL works for `DATABASE_URL` — the asymmetry that
+ * previously forced callers to hand-append `uselibpqcompat=true`.
+ *
+ * Encrypt-but-don't-verify matches libpq's `sslmode=require` semantics and the
+ * SDK's existing posture (this is not a new weakening — it is the same choice the
+ * CMS/facts pools already make). For full CA verification against a non-preview
+ * cluster, present a trusted chain and pass a URL without an `sslmode` param.
+ */
+export declare function buildPoolConfig(connectionString: string, max: number): PoolConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/src/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAErC,MAAM,WAAW,kBAAkB;IAC/B,8CAA8C;IAC9C,gBAAgB,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IACvC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,eAAO,MAAM,cAAc,kBAAkB,CAAC;AAC9C,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAC7C,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,6BAA6B,QAAS,CAAC;AACpD,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAyBrD,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,OAAO,GAAE,OAAO,CAAC,kBAAkB,CAAM,GAAG,kBAAkB,CAgC3F;AAKD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,gBAAgB,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAwBjF"}