pilotswarm-horizon-store 0.2.2

package/dist/src/index.js

@@ -0,0 +1,21 @@
+// pilotswarm-horizon-store — public exports.
+//
+// HorizonDB-backed providers implementing the @pilotswarm/sdk fact/graph
+// contracts. The DB-less core (query-builder, graph-model) and the re-exported
+// type contracts are the stable, unit-tested surface; HorizonDBFactStore (facts
+// + search + embedder) and HorizonDBGraphStore (separate AGE-only graph provider,
+// 07 D2) are the live providers validated by the integration suite against a real
+// HorizonDB.
+export * from "./types.js";
+export * from "./query-builder.js";
+export * from "./graph-model.js";
+export * from "./config.js";
+export * from "./embedding-client.js";
+export * from "./horizon-store.js";
+export * from "./graph-store.js";
+export * from "./agent-tools.js";
+export { isTransientDbError, withDbRetry, setDbRetryHooks } from "./db-retry.js";
+export { GraphQueries, prepareAgeSession } from "./graph-queries.js";
+export { loadMigrations, runMigrations, migrationsDir, HORIZON_FACTS_LOCK_SEED, GRAPH_OWNED_MIGRATIONS, isGraphOwnedMigration } from "./horizon-migrator.js";
+export { assertExtensionsAvailable, assertFactExtensions, assertGraphExtensions, assertDurableHttpUsable, missingExtensions, missingFactExtensions, missingGraphExtensions, } from "./preconditions.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,yEAAyE;AACzE,+EAA+E;AAC/E,gFAAgF;AAChF,kFAAkF;AAClF,kFAAkF;AAClF,aAAa;AAEb,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC7J,OAAO,EACH,yBAAyB,EAAE,oBAAoB,EAAE,qBAAqB,EACtE,uBAAuB,EACvB,iBAAiB,EAAE,qBAAqB,EAAE,sBAAsB,GACnE,MAAM,oBAAoB,CAAC"}

package/dist/src/preconditions.d.ts

@@ -0,0 +1,16 @@
+/** Pieces missing BEFORE migrations run — full bundled surface (back-compat). */
+export declare function missingExtensions(pool: any): Promise<string[]>;
+/** Fact-provider missing extensions (vector / pg_textsearch / pg_durable). */
+export declare function missingFactExtensions(pool: any): Promise<string[]>;
+/** Graph-provider missing extensions (age). */
+export declare function missingGraphExtensions(pool: any): Promise<string[]>;
+/** Throw the itemized fail-fast error if any required extension is unavailable
+ *  (full bundled surface — back-compat). */
+export declare function assertExtensionsAvailable(pool: any): Promise<void>;
+/** Fail-fast for the enhanced FACT provider (vector / pg_textsearch / pg_durable). */
+export declare function assertFactExtensions(pool: any): Promise<void>;
+/** Fail-fast for the GRAPH provider (age only). */
+export declare function assertGraphExtensions(pool: any): Promise<void>;
+/** Post-migration checks: df.http present and usable by this role. */
+export declare function assertDurableHttpUsable(pool: any): Promise<void>;
+//# sourceMappingURL=preconditions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preconditions.d.ts","sourceRoot":"","sources":["../../src/preconditions.ts"],"names":[],"mappings":"AAmEA,iFAAiF;AACjF,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEpE;AAED,8EAA8E;AAC9E,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAExE;AAED,+CAA+C;AAC/C,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEzE;AAED;4CAC4C;AAC5C,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAExE;AAED,sFAAsF;AACtF,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnE;AAED,mDAAmD;AACnD,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpE;AAED,sEAAsE;AACtE,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBtE"}

package/dist/src/preconditions.js

@@ -0,0 +1,99 @@
+// pilotswarm-horizon-store — fail-fast preconditions (01-functional-spec §5.5).
+//
+// `initialize()` throws ONE precise, ITEMIZED error naming every missing piece
+// and its fix. No feature flags, no silent fallbacks: lexical is BM25 via
+// pg_textsearch (ts_rank is not a substitute), semantic needs pgvector, the
+// graph needs AGE, and the embedder needs pg_durable with df.http granted.
+import { withDbRetry } from "./db-retry.js";
+/** Extensions the enhanced FACT provider (HorizonDBFactStore) needs (07 D2):
+ *  pgvector + pg_textsearch + pg_durable. NOT age — graph is a separate provider. */
+const FACT_REQUIRED = [
+    {
+        name: "vector",
+        why: "semantic kNN over facts.embedding (pgvector)",
+        fix: "install pgvector / add 'vector' to the cluster's allow-listed extensions",
+    },
+    {
+        name: "pg_textsearch",
+        why: "BM25 lexical ranking (ts_rank is not an acceptable fallback)",
+        fix: "add 'pg_textsearch' to the cluster's allow-listed extensions",
+    },
+    {
+        name: "pg_durable",
+        why: "the durable in-database embedding loop (df.loop/df.http)",
+        fix: "add 'pg_durable' to shared_preload_libraries and the extension allow-list",
+    },
+];
+/** Extensions the GRAPH provider (HorizonDBGraphStore) needs (07 D2): AGE only,
+ *  so it can pair with a plain PgFactStore (base-facts + graph tier). */
+const GRAPH_REQUIRED = [
+    {
+        name: "age",
+        why: "the open knowledge graph (Apache AGE)",
+        fix: "install Apache AGE / add 'age' to shared_preload_libraries and the extension allow-list",
+    },
+];
+/** Union — the full bundled HorizonDB surface (back-compat). */
+const REQUIRED = [...FACT_REQUIRED, ...GRAPH_REQUIRED];
+async function missingFrom(pool, required) {
+    const { rows } = await withDbRetry("horizon_preconditions_extensions", () => pool.query(`SELECT name FROM pg_available_extensions WHERE name = ANY($1)`, [required.map((r) => r.name)]), { tries: 6 });
+    const available = new Set(rows.map((r) => r.name));
+    return required.filter((r) => !available.has(r.name)).map((r) => r.name);
+}
+function assertFrom(missing, required, surface) {
+    if (missing.length === 0)
+        return;
+    const lines = missing.map((name) => {
+        const r = required.find((x) => x.name === name);
+        return `  - ${name}: ${r.why}. Fix: ${r.fix}`;
+    });
+    throw new Error(`${surface} preconditions failed — this database is missing ${missing.length} required ` +
+        `extension(s):\n${lines.join("\n")}\n` +
+        `${surface} requires HorizonDB (or equivalent). There are no fallbacks; ` +
+        `point the connection string at a capable cluster.`);
+}
+/** Pieces missing BEFORE migrations run — full bundled surface (back-compat). */
+export async function missingExtensions(pool) {
+    return missingFrom(pool, REQUIRED);
+}
+/** Fact-provider missing extensions (vector / pg_textsearch / pg_durable). */
+export async function missingFactExtensions(pool) {
+    return missingFrom(pool, FACT_REQUIRED);
+}
+/** Graph-provider missing extensions (age). */
+export async function missingGraphExtensions(pool) {
+    return missingFrom(pool, GRAPH_REQUIRED);
+}
+/** Throw the itemized fail-fast error if any required extension is unavailable
+ *  (full bundled surface — back-compat). */
+export async function assertExtensionsAvailable(pool) {
+    assertFrom(await missingExtensions(pool), REQUIRED, "EnhancedFactStore");
+}
+/** Fail-fast for the enhanced FACT provider (vector / pg_textsearch / pg_durable). */
+export async function assertFactExtensions(pool) {
+    assertFrom(await missingFactExtensions(pool), FACT_REQUIRED, "HorizonDBFactStore");
+}
+/** Fail-fast for the GRAPH provider (age only). */
+export async function assertGraphExtensions(pool) {
+    assertFrom(await missingGraphExtensions(pool), GRAPH_REQUIRED, "HorizonDBGraphStore");
+}
+/** Post-migration checks: df.http present and usable by this role. */
+export async function assertDurableHttpUsable(pool) {
+    const { rows } = await withDbRetry("horizon_preconditions_df_http", () => pool.query(`
+        SELECT EXISTS (
+            SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+            WHERE n.nspname = 'df' AND p.proname = 'http'
+        ) AS has_http`), { tries: 6 });
+    if (!rows[0]?.has_http) {
+        throw new Error("EnhancedFactStore preconditions failed — pg_durable is installed but df.http() is absent. " +
+            "Fix: ensure pg_durable is in shared_preload_libraries (restart required) and re-run CREATE EXTENSION pg_durable.");
+    }
+    try {
+        await withDbRetry("horizon_preconditions_df_usage", () => pool.query(`SELECT df.getvar('__hz_precondition_probe')`), { tries: 6 });
+    }
+    catch (err) {
+        throw new Error("EnhancedFactStore preconditions failed — this role cannot use the df schema. " +
+            `Fix: have an admin run SELECT df.grant_usage('<role>', true, false). Underlying error: ${err?.message ?? err}`);
+    }
+}
+//# sourceMappingURL=preconditions.js.map

package/dist/src/preconditions.js.map

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

package/dist/src/query-builder.d.ts

@@ -0,0 +1,37 @@
+import type { SearchWeights } from "./types.js";
+/**
+ * Normalize the raw lexical query (BM25). The scoring function treats text as
+ * data, so we only normalize whitespace. Returns null for empty queries —
+ * callers turn that into a defined empty result, not a crash (04 L4).
+ */
+export declare function buildLexicalQuery(raw: string): string | null;
+/**
+ * Normalize a namespace ("skills") into a SQL LIKE prefix ("skills/%").
+ * Mirrors PilotSwarm's reserved knowledge namespaces.
+ */
+export declare function namespacePrefix(namespace?: string): string | null;
+export interface Candidate {
+    scopeKey: string;
+    /** Raw per-signal scores. Any subset may be present. */
+    lexical?: number;
+    semantic?: number;
+}
+export interface FusedCandidate {
+    scopeKey: string;
+    score: number;
+    signals: {
+        lexical?: number;
+        semantic?: number;
+    };
+}
+/** Min-max normalize a list of numbers into 0..1. Constant lists map to 1. */
+export declare function normalize(values: number[]): number[];
+/**
+ * Weighted-normalized-score fusion.
+ *
+ * Each signal is min-max normalized across its own candidate set, then combined
+ * with the configured weights. A candidate missing a signal contributes 0 for
+ * that signal. Returns candidates sorted by fused score descending.
+ */
+export declare function fuseWeighted(candidates: Candidate[], weights?: SearchWeights): FusedCandidate[];
+//# sourceMappingURL=query-builder.d.ts.map

package/dist/src/query-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-builder.d.ts","sourceRoot":"","sources":["../../src/query-builder.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIjE;AAID,MAAM,WAAW,SAAS;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AAID,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAUpD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,cAAc,EAAE,CAqB/F"}

package/dist/src/query-builder.js

@@ -0,0 +1,82 @@
+// pilotswarm-horizon-store — DB-less core.
+//
+// This module holds the parts of the read path that do NOT need a database:
+//   - query/namespace fragment normalization (unit-testable)
+//   - candidate fusion (combining lexical/semantic candidates into a single
+//     ranked list). There is NO graph signal: searchFacts is facts-store-only
+//     (01-functional-spec §4.2); graph retrieval is the separate GraphStore.
+//
+// Keeping these pure makes the fusion algorithm A/B-testable offline and keeps
+// the HorizonDB adapter thin.
+// ─── query/namespace normalization ──────────────────────────────────────────
+/**
+ * Normalize the raw lexical query (BM25). The scoring function treats text as
+ * data, so we only normalize whitespace. Returns null for empty queries —
+ * callers turn that into a defined empty result, not a crash (04 L4).
+ */
+export function buildLexicalQuery(raw) {
+    const trimmed = (raw ?? "").replace(/\s+/g, " ").trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Normalize a namespace ("skills") into a SQL LIKE prefix ("skills/%").
+ * Mirrors PilotSwarm's reserved knowledge namespaces.
+ */
+export function namespacePrefix(namespace) {
+    if (!namespace)
+        return null;
+    const clean = namespace.replace(/\/+$/, "");
+    return clean.length > 0 ? `${clean}/%` : null;
+}
+const DEFAULT_WEIGHTS = { lexical: 1, semantic: 1 };
+/** Min-max normalize a list of numbers into 0..1. Constant lists map to 1. */
+export function normalize(values) {
+    if (values.length === 0)
+        return [];
+    let min = Infinity;
+    let max = -Infinity;
+    for (const v of values) {
+        if (v < min)
+            min = v;
+        if (v > max)
+            max = v;
+    }
+    if (max === min)
+        return values.map(() => (max === 0 ? 0 : 1));
+    return values.map((v) => (v - min) / (max - min));
+}
+/**
+ * Weighted-normalized-score fusion.
+ *
+ * Each signal is min-max normalized across its own candidate set, then combined
+ * with the configured weights. A candidate missing a signal contributes 0 for
+ * that signal. Returns candidates sorted by fused score descending.
+ */
+export function fuseWeighted(candidates, weights) {
+    const w = { ...DEFAULT_WEIGHTS, ...(weights ?? {}) };
+    const lexNorm = normByKey(candidates, "lexical");
+    const semNorm = normByKey(candidates, "semantic");
+    const fused = candidates.map((c) => {
+        const signals = {};
+        let score = 0;
+        if (c.lexical !== undefined) {
+            signals.lexical = c.lexical;
+            score += w.lexical * (lexNorm.get(c.scopeKey) ?? 0);
+        }
+        if (c.semantic !== undefined) {
+            signals.semantic = c.semantic;
+            score += w.semantic * (semNorm.get(c.scopeKey) ?? 0);
+        }
+        return { scopeKey: c.scopeKey, score, signals };
+    });
+    return fused.sort((a, b) => b.score - a.score || a.scopeKey.localeCompare(b.scopeKey));
+}
+// ─── helpers ────────────────────────────────────────────────────────────────
+function normByKey(candidates, signal) {
+    const present = candidates.filter((c) => typeof c[signal] === "number");
+    const norm = normalize(present.map((c) => c[signal]));
+    const out = new Map();
+    present.forEach((c, i) => out.set(c.scopeKey, norm[i]));
+    return out;
+}
+//# sourceMappingURL=query-builder.js.map

package/dist/src/query-builder.js.map

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

package/dist/src/sql-util.d.ts

@@ -0,0 +1,20 @@
+/** Quote a SQL identifier (schema/table/graph). Rejects anything non-trivial. */
+export declare function ident(name: string): string;
+/**
+ * Escape a JS string as a single-quoted AGE Cypher string literal.
+ *
+ * These literals are consumed by AGE's Cypher (openCypher) parser inside
+ * `cypher(graph, $$ ... $$)`, NOT by the SQL parser — so a single quote is
+ * escaped with a backslash (`\'`), the Cypher way, NOT by SQL-style doubling
+ * (`''`). Doubling produces `'Andres''s VM'`, which the Cypher parser reads as
+ * the string `'Andres'` followed by stray tokens → `syntax error at or near
+ * "'s VM'"` (verified against live AGE), silently dropping the write. Backslash
+ * is escaped first so the quote-escape we add is not itself re-escaped; NULs are
+ * stripped.
+ */
+export declare function cypherStr(value: string): string;
+/** Render a number safely as a Cypher numeric literal. */
+export declare function cypherNum(n: number): string;
+/** Render a string[] as a Cypher list literal of escaped strings. */
+export declare function cypherStrList(values: string[]): string;
+//# sourceMappingURL=sql-util.d.ts.map

package/dist/src/sql-util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-util.d.ts","sourceRoot":"","sources":["../../src/sql-util.ts"],"names":[],"mappings":"AAOA,iFAAiF;AACjF,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3C;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAEtD"}

package/dist/src/sql-util.js

@@ -0,0 +1,40 @@
+// pilotswarm-horizon-store — small SQL helpers for the adapter.
+//
+// AGE Cypher cannot be fully parameterized through pg bind params (the cypher()
+// function takes a literal query string), so the adapter must build Cypher with
+// embedded literals. These helpers make that safe: every value is escaped, and
+// identifiers are validated against a strict allowlist.
+/** Quote a SQL identifier (schema/table/graph). Rejects anything non-trivial. */
+export function ident(name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new Error(`unsafe SQL identifier: ${JSON.stringify(name)}`);
+    }
+    return `"${name}"`;
+}
+/**
+ * Escape a JS string as a single-quoted AGE Cypher string literal.
+ *
+ * These literals are consumed by AGE's Cypher (openCypher) parser inside
+ * `cypher(graph, $$ ... $$)`, NOT by the SQL parser — so a single quote is
+ * escaped with a backslash (`\'`), the Cypher way, NOT by SQL-style doubling
+ * (`''`). Doubling produces `'Andres''s VM'`, which the Cypher parser reads as
+ * the string `'Andres'` followed by stray tokens → `syntax error at or near
+ * "'s VM'"` (verified against live AGE), silently dropping the write. Backslash
+ * is escaped first so the quote-escape we add is not itself re-escaped; NULs are
+ * stripped.
+ */
+export function cypherStr(value) {
+    const cleaned = String(value).replace(/\u0000/g, "");
+    return `'${cleaned.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+/** Render a number safely as a Cypher numeric literal. */
+export function cypherNum(n) {
+    if (!Number.isFinite(n))
+        throw new Error(`non-finite number in cypher: ${n}`);
+    return String(n);
+}
+/** Render a string[] as a Cypher list literal of escaped strings. */
+export function cypherStrList(values) {
+    return `[${values.map(cypherStr).join(", ")}]`;
+}
+//# sourceMappingURL=sql-util.js.map

package/dist/src/sql-util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-util.js","sourceRoot":"","sources":["../../src/sql-util.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,wDAAwD;AAExD,iFAAiF;AACjF,MAAM,UAAU,KAAK,CAAC,IAAY;IAC9B,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,IAAI,IAAI,GAAG,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACnC,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACrD,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC;AACtE,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,SAAS,CAAC,CAAS;IAC/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,EAAE,CAAC,CAAC;IAC9E,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AACrB,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,aAAa,CAAC,MAAgB;IAC1C,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AACnD,CAAC"}

package/dist/src/types.d.ts

@@ -0,0 +1,16 @@
+export type { FactRecord, StoreFactInput, StoredFactResult, ReadFactsQuery, DeleteFactInput, DeletedFactResult, DeletedFactsResult, FactsNamespace, FactsStatsRow, FactsTombstoneStats, ForcePurgeFactsInput, AccessContext, FactStore, CrawledFactStamp, EnhancedFactStore, FactsCapabilities, SearchMode, SearchWeights, SearchOpts, SimilarOpts, ScoredFact, SearchResult, EmbedderStatus, EmbedderLoopStatus, EmbeddingEndpointConfig, GraphStore, GraphNodeInput, GraphEdgeInput, GraphNamespaceQuery, GraphNodeQuery, GraphEdgeQuery, GraphNodeRef, GraphNodeHit, GraphEdgeRef, GraphEdgeHit, GraphEvidenceRemovalResult, SubGraph, GraphNamespaceFrontmatter, GraphNamespaceInfo, GraphNamespaceInput, GraphNamespaceListQuery, GraphNamespaceDeleteResult, } from "pilotswarm-sdk";
+import type { AccessContext } from "pilotswarm-sdk";
+/**
+ * Whether a fact scope_key is readable under the given access context, decided
+ * purely from the key's shape: `shared:` always passes; `session:<id>:` passes
+ * iff `<id>` is the reader's or a granted session; unrestricted passes all.
+ * Malformed `session:` keys fail closed. (Mirror of the SDK helper; kept local
+ * to avoid a runtime dependency on the SDK barrel.)
+ */
+export declare function scopeKeyAccessible(scopeKey: string, access?: AccessContext): boolean;
+/**
+ * @deprecated The graph is its own interface `GraphStore` (07 D2). Alias kept
+ * for the provider's internal back-compat; prefer `GraphStore`.
+ */
+export type { GraphStore as GraphInterface } from "pilotswarm-sdk";
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAUA,YAAY,EAER,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,SAAS,EACT,gBAAgB,EAEhB,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,UAAU,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,uBAAuB,EAEvB,UAAU,EACV,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,0BAA0B,EAC1B,QAAQ,EAER,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,0BAA0B,GAC7B,MAAM,gBAAgB,CAAC;AAOxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAYpF;AAED;;;GAGG;AACH,YAAY,EAAE,UAAU,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/src/types.js

@@ -0,0 +1,35 @@
+// pilotswarm-horizon-store — type contracts.
+//
+// These contracts are OWNED BY THE SDK (`pilotswarm-sdk`, enhancedfactstore 07
+// P1). This module re-exports them so the provider's own files keep importing
+// from a single local `./types.js` while the DEFINITIONS live in the SDK. The
+// provider IMPLEMENTS these contracts; it does not define them.
+//
+// Type-only re-exports (no runtime cost; no import cycle — the SDK does not
+// depend on this package).
+/**
+ * Whether a fact scope_key is readable under the given access context, decided
+ * purely from the key's shape: `shared:` always passes; `session:<id>:` passes
+ * iff `<id>` is the reader's or a granted session; unrestricted passes all.
+ * Malformed `session:` keys fail closed. (Mirror of the SDK helper; kept local
+ * to avoid a runtime dependency on the SDK barrel.)
+ */
+export function scopeKeyAccessible(scopeKey, access) {
+    if (access?.unrestricted)
+        return true;
+    if (scopeKey.startsWith("shared:"))
+        return true;
+    if (scopeKey.startsWith("session:")) {
+        const rest = scopeKey.slice("session:".length);
+        const sep = rest.indexOf(":");
+        if (sep <= 0)
+            return false;
+        const sessionId = rest.slice(0, sep);
+        if (access?.readerSessionId && sessionId === access.readerSessionId)
+            return true;
+        if (access?.grantedSessionIds?.includes(sessionId))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,8EAA8E;AAC9E,gEAAgE;AAChE,EAAE;AACF,4EAA4E;AAC5E,2BAA2B;AA0D3B;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,MAAsB;IACvE,IAAI,MAAM,EAAE,YAAY;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,QAAQ,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,GAAG,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACrC,IAAI,MAAM,EAAE,eAAe,IAAI,SAAS,KAAK,MAAM,CAAC,eAAe;YAAE,OAAO,IAAI,CAAC;QACjF,IAAI,MAAM,EAAE,iBAAiB,EAAE,QAAQ,CAAC,SAAS,CAAC;YAAE,OAAO,IAAI,CAAC;IACpE,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/migrations/0001_facts_table.sql

@@ -0,0 +1,77 @@
+-- 0001_facts_table — base facts table (PilotSwarm parity) + enrichment columns
+-- + the write-resets-pending-state trigger (03-design §2.1).
+--
+-- Tokens substituted by horizon-migrator: {{SCHEMA}}, {{EMBEDDING_DIM}}.
+
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE IF NOT EXISTS "{{SCHEMA}}".facts (
+    id          BIGSERIAL PRIMARY KEY,
+    scope_key   TEXT NOT NULL UNIQUE,
+    key         TEXT NOT NULL,
+    value       JSONB NOT NULL,
+    agent_id    TEXT,
+    session_id  TEXT,
+    shared      BOOLEAN NOT NULL DEFAULT FALSE,
+    transient   BOOLEAN NOT NULL DEFAULT FALSE,
+    tags        TEXT[] NOT NULL DEFAULT '{}',
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    CHECK (NOT (shared AND transient)),
+
+    -- Enrichment (EnhancedFactStore): all derived/rebuildable.
+    -- The embeddable/searchable text: key + the conventional value fields.
+    -- (immutable expression required for a generated column: || + coalesce)
+    search_text TEXT GENERATED ALWAYS AS (
+        coalesce(key, '')
+            || ' ' || coalesce(value->>'name', '')
+            || ' ' || coalesce(value->>'description', '')
+            || ' ' || coalesce(value->>'text', '')
+            || ' ' || coalesce(value->>'body', '')
+            || ' ' || coalesce(value->>'subject', '')
+    ) STORED,
+    content_hash       TEXT,                                   -- trigger-maintained (NOT generated:
+                                                               -- a BEFORE trigger must read+reset on change)
+    last_crawled_at    TIMESTAMPTZ,                            -- NULL ⇒ pending crawl
+    embedding          vector({{EMBEDDING_DIM}}),              -- NULL until embedded
+    embedded_at        TIMESTAMPTZ,
+    embedding_model    TEXT,
+    last_embedded_hash TEXT
+);
+
+-- Base indexes (SDK parity).
+CREATE INDEX IF NOT EXISTS idx_facts_key       ON "{{SCHEMA}}".facts (key);
+CREATE INDEX IF NOT EXISTS idx_facts_tags      ON "{{SCHEMA}}".facts USING GIN (tags);
+CREATE INDEX IF NOT EXISTS idx_facts_session   ON "{{SCHEMA}}".facts (session_id);
+CREATE INDEX IF NOT EXISTS idx_facts_agent     ON "{{SCHEMA}}".facts (agent_id);
+CREATE INDEX IF NOT EXISTS idx_facts_shared    ON "{{SCHEMA}}".facts (shared);
+CREATE INDEX IF NOT EXISTS idx_facts_transient ON "{{SCHEMA}}".facts (transient);
+
+-- Work-queue indexes.
+CREATE INDEX IF NOT EXISTS idx_facts_uncrawled
+    ON "{{SCHEMA}}".facts (id) WHERE last_crawled_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_facts_needs_embedding
+    ON "{{SCHEMA}}".facts (id) WHERE embedding IS NULL;
+
+-- Write-resets-pending-state (01-functional-spec §6.6, 03-design §2.1):
+-- recompute content_hash from the embeddable content; when it changes,
+-- (a) reset last_crawled_at → NULL so the harvester re-crawls, and
+-- (b) leave last_embedded_hash stale so the embedder re-embeds.
+-- Identical-content writes change NOTHING (C4).
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_touch() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE
+    new_hash TEXT;
+BEGIN
+    new_hash := md5(coalesce(NEW.key, '') || E'\x1f' || coalesce(NEW.value::text, ''));
+    IF TG_OP = 'INSERT' OR new_hash IS DISTINCT FROM OLD.content_hash THEN
+        NEW.content_hash := new_hash;
+        NEW.last_crawled_at := NULL;
+    END IF;
+    RETURN NEW;
+END $$;
+
+DROP TRIGGER IF EXISTS facts_touch ON "{{SCHEMA}}".facts;
+CREATE TRIGGER facts_touch
+    BEFORE INSERT OR UPDATE ON "{{SCHEMA}}".facts
+    FOR EACH ROW EXECUTE FUNCTION "{{SCHEMA}}".facts_touch();

package/migrations/0002_indexes.sql

@@ -0,0 +1,27 @@
+-- 0002_indexes — ANN index over facts.embedding + the lexical (BM25) index.
+--
+-- ANN: prefer pg_diskann (better recall/latency at scale on HorizonDB), fall
+-- back to pgvector HNSW when pg_diskann is not allow-listed. Both share the
+-- vector_cosine_ops opclass and the <=> operator, so the search procs are
+-- identical either way.
+--
+-- Tokens: {{SCHEMA}}.
+
+DO $$
+BEGIN
+    BEGIN
+        CREATE EXTENSION IF NOT EXISTS pg_diskann CASCADE;
+        EXECUTE 'CREATE INDEX IF NOT EXISTS idx_facts_embedding ON "{{SCHEMA}}".facts USING diskann (embedding vector_cosine_ops)';
+    EXCEPTION WHEN OTHERS THEN
+        EXECUTE 'CREATE INDEX IF NOT EXISTS idx_facts_embedding ON "{{SCHEMA}}".facts USING hnsw (embedding vector_cosine_ops)';
+    END;
+END $$;
+
+-- Lexical (BM25) — pg_textsearch is a fail-fast precondition (01 §5.5).
+-- Verified on live HorizonDB (pg_textsearch 1.3.0-dev): index AM `bm25`
+-- requires WITH (text_config); `col <@> to_bm25query(q, idx)` returns the
+-- NEGATIVE BM25 score (ascending order = best first; 0 = no match).
+CREATE EXTENSION IF NOT EXISTS pg_textsearch;
+
+CREATE INDEX IF NOT EXISTS idx_facts_lexical
+    ON "{{SCHEMA}}".facts USING bm25 (search_text) WITH (text_config = 'english');

package/migrations/0003_age_bootstrap.sql

@@ -0,0 +1,13 @@
+-- 0003_age_bootstrap — AGE extension + the per-deployment graph.
+--
+-- Tokens: {{GRAPH_NAME}}. NOTE: create_graph() creates a Postgres schema named
+-- after the graph, so the graph name MUST differ from the facts schema name.
+
+CREATE EXTENSION IF NOT EXISTS age;
+
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM ag_catalog.ag_graph WHERE name = '{{GRAPH_NAME}}') THEN
+        PERFORM ag_catalog.create_graph('{{GRAPH_NAME}}');
+    END IF;
+END $$;