pilotswarm-horizon-store 0.2.2

package/dist/src/config.js

@@ -0,0 +1,120 @@
+// pilotswarm-horizon-store — provider configuration.
+//
+// The EnhancedFactStore is configured with a connection string and, optionally,
+// an EMBEDDING ENDPOINT. The embedding endpoint is a DATABASE-AGNOSTIC contract:
+// it describes an OpenAI/Azure-OpenAI-compatible HTTP embeddings API and says
+// nothing about how any particular provider invokes it. A provider records this
+// endpoint and embeds facts however it likes — the HorizonDB provider calls it
+// in-database via pg_durable's df.http() background loop, but an AlloyDB- or
+// any-Postgres-based provider could consume the exact same config and call it
+// from a trigger, a sidecar, or host-side code. PilotSwarm only passes the
+// endpoint; the mechanism is the provider's concern.
+//
+// The SAME endpoint config is also usable Node-side (see embedding-client.ts)
+// for query-time embedding and for tests that don't depend on any in-database
+// HTTP path.
+export const DEFAULT_SCHEMA = "horizon_facts";
+export const DEFAULT_GRAPH = "horizon_facts";
+export const DEFAULT_POOL_MAX = 16;
+export const DEFAULT_CONNECTION_TIMEOUT_MS = 15_000;
+export const DEFAULT_NAMESPACE_CACHE_TTL_MS = 60_000;
+function resolveConnectionTimeoutMillis() {
+    const raw = process.env.HORIZON_CONNECTION_TIMEOUT_MS;
+    if (raw == null || raw === "")
+        return DEFAULT_CONNECTION_TIMEOUT_MS;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`HORIZON_CONNECTION_TIMEOUT_MS must be a non-negative number, got ${JSON.stringify(raw)}`);
+    }
+    return Math.trunc(value);
+}
+/** Resolve + validate the namespace cache TTL (ms). Rejects NaN / negative. */
+function resolveNamespaceCacheTtl(explicit) {
+    const envRaw = process.env.HORIZON_NAMESPACE_CACHE_TTL_MS;
+    const raw = explicit ?? (envRaw != null && envRaw !== "" ? Number(envRaw) : undefined);
+    if (raw == null)
+        return DEFAULT_NAMESPACE_CACHE_TTL_MS;
+    if (!Number.isFinite(raw) || raw < 0) {
+        throw new Error(`namespaceCacheTtlMs / HORIZON_NAMESPACE_CACHE_TTL_MS must be a non-negative number, got ${JSON.stringify(envRaw ?? explicit)}`);
+    }
+    return raw;
+}
+/** Resolve config from explicit values, falling back to HORIZON_* env vars. */
+export function resolveConfig(partial = {}) {
+    const connectionString = partial.connectionString ?? process.env.HORIZON_DATABASE_URL ?? "";
+    if (!connectionString) {
+        throw new Error("HorizonDBFactStore requires a connectionString (or HORIZON_DATABASE_URL env var).");
+    }
+    // The embedding endpoint must be passed EXPLICITLY (no env-var fallback):
+    // an implicit endpoint can silently conflict with the store's vector(N)
+    // dimension, and config provenance should be the host's choice (02 §1b).
+    const embedding = partial.embedding;
+    const graphName = partial.graphName ?? DEFAULT_GRAPH;
+    return {
+        connectionString,
+        schema: partial.schema ?? DEFAULT_SCHEMA,
+        graphName,
+        registrySchema: partial.registrySchema ?? process.env.HORIZON_GRAPH_REGISTRY_SCHEMA ?? `${graphName}_registry`,
+        embedding,
+        embeddingDim: partial.embeddingDim ?? embedding?.dim ?? 1536,
+        annIndex: partial.annIndex
+            ?? process.env.HORIZON_ANN_INDEX
+            ?? "auto",
+        poolMax: partial.poolMax
+            ?? (process.env.HORIZON_POOL_MAX ? Number(process.env.HORIZON_POOL_MAX) : undefined)
+            ?? DEFAULT_POOL_MAX,
+        namespaceCacheTtlMs: resolveNamespaceCacheTtl(partial.namespaceCacheTtlMs),
+        useManagedIdentity: partial.useManagedIdentity,
+        aadUser: partial.aadUser,
+    };
+}
+/** sslmode values that mean "use TLS" (mirrors the PilotSwarm SDK pg-pool-factory). */
+const SSL_REQUIRING_MODES = ["require", "prefer", "verify-ca", "verify-full"];
+/**
+ * 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 function buildPoolConfig(connectionString, max) {
+    let needsSsl = false;
+    let sanitized = connectionString;
+    try {
+        const url = new URL(connectionString);
+        needsSsl = SSL_REQUIRING_MODES.includes(url.searchParams.get("sslmode") ?? "");
+        if (needsSsl) {
+            // Control SSL via the config object, not the URL. Drop sslmode so pg
+            // does not re-apply verify-full, and drop the now-redundant
+            // uselibpqcompat hint so the effective URL is clean either way.
+            url.searchParams.delete("sslmode");
+            url.searchParams.delete("uselibpqcompat");
+            sanitized = url.toString();
+        }
+    }
+    catch {
+        // Not a parseable URL (unexpected for a real DSN). Leave it untouched and
+        // let pg surface a clear connection error rather than masking it here.
+    }
+    return {
+        connectionString: sanitized,
+        max,
+        connectionTimeoutMillis: resolveConnectionTimeoutMillis(),
+        ...(needsSsl ? { ssl: { rejectUnauthorized: false } } : {}),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

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

package/dist/src/db-retry.d.ts

@@ -0,0 +1,21 @@
+export declare function isTransientDbError(err: any): boolean;
+/** The AGE lazy-label-creation race, in BOTH manifestations (42P07 duplicate_table
+ * and 23505 unique_violation on a pg_catalog index). Re-running the same
+ * idempotent graph statement once the label exists succeeds. Label-agnostic. */
+export declare function isLabelCreationRaceError(err: any): boolean;
+export interface DbRetryHooks {
+    onRetry?: (info: {
+        label: string;
+        attempt: number;
+        error: any;
+    }) => void;
+}
+/** Install process-wide retry observers (used by the eval perf/error report). */
+export declare function setDbRetryHooks(hooks: DbRetryHooks): void;
+export interface DbRetryOpts {
+    tries?: number;
+    /** Which errors are retryable. Default: isTransientDbError (connection class). */
+    isRetryable?: (err: any) => boolean;
+}
+export declare function withDbRetry<T>(label: string, fn: () => Promise<T>, opts?: DbRetryOpts): Promise<T>;
+//# sourceMappingURL=db-retry.d.ts.map

package/dist/src/db-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-retry.d.ts","sourceRoot":"","sources":["../../src/db-retry.ts"],"names":[],"mappings":"AAwDA,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAIpD;AAED;;gFAEgF;AAChF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAS1D;AAED,MAAM,WAAW,YAAY;IACzB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,GAAG,CAAA;KAAE,KAAK,IAAI,CAAC;CAC5E;AAGD,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAkC;AAE5F,MAAM,WAAW,WAAW;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;CACvC;AAED,wBAAsB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,CAe5G"}

package/dist/src/db-retry.js

@@ -0,0 +1,94 @@
+// pilotswarm-horizon-store — retry helpers (HorizonDB preview hardening).
+//
+// Two distinct retryable classes, each with its own classifier so callers opt
+// into exactly the one that is safe for them:
+//
+// 1. TRANSIENT CONNECTION (isTransientDbError, the default):
+//    Azure HorizonDB (preview) intermittently drops pooled TLS connections —
+//    ECONNRESET / ENOTCONN / "Connection terminated" / "terminating
+//    connection", plus the pg connection-class SQLSTATEs (08xxx, 57P0x). These
+//    surface either as a rejected query or at connection acquisition; in both
+//    cases the statement did not partially commit, so re-running (on a FRESH
+//    connection) is safe. Never matches SQL/logic errors — those must surface.
+//    Also covers connection-ESTABLISHMENT failures that are transient under
+//    load: EADDRNOTAVAIL / ECONNABORTED (local socket exhaustion or aborted
+//    connection setup from rapid connection churn) and DNS hiccups (ENOTFOUND /
+//    EAI_AGAIN / getaddrinfo) against the cluster host — the query never ran,
+//    so a fresh-connection retry is safe.
+//
+// 2. AGE LABEL-CREATION RACE (isLabelCreationRaceError):
+//    Apache AGE creates a label's backing table LAZILY on the first
+//    CREATE/MERGE that references it. The label set is owned by the layer above
+//    us (the harvester / app choose node kinds + edge predicates), so we never
+//    enumerate it. When two writers race the first reference to the same label,
+//    the loser's internal label-table creation aborts the whole Cypher statement
+//    — so the MERGE/CREATE persisted nothing. The label now EXISTS, so re-running
+//    the SAME statement succeeds. This is label-agnostic by construction.
+//
+//    The race has TWO observed manifestations (HorizonDB AGE 1.6.0), depending
+//    on WHERE the duplicate is detected:
+//      - 42P07 duplicate_table — `relation "<label>" already exists` (caught at
+//        the relation level), and
+//      - 23505 unique_violation on a SYSTEM-CATALOG index, e.g.
+//        `pg_class_relname_nsp_index` (two concurrent label-table creations race
+//        into pg_class before either registered). NOTE the "already exists"
+//        text is in err.detail, not err.message, so a message regex misses it —
+//        we key off the code + the catalog constraint name instead. We retry
+//        23505 ONLY when the violated constraint is a pg_catalog index, never a
+//        user constraint (the graph has no user unique constraints anyway).
+//
+// The optional process-wide onRetry hook lets the eval harness record retries
+// for its perf/error report.
+const TRANSIENT_DB_ERROR = /ECONNRESET|ENOTCONN|EPIPE|ETIMEDOUT|Connection terminated|terminating connection|server closed the connection|connection to server|read ECONN|EADDRNOTAVAIL|ECONNABORTED|ENOTFOUND|EAI_AGAIN|getaddrinfo/i;
+/** pg connection-class SQLSTATEs: 08xxx connection exceptions, 57P0x
+ * admin-shutdown / crash-recovery. All mean "connection went away" → safe to
+ * re-run on a fresh connection. */
+const TRANSIENT_PG_CODE = new Set(["08006", "08003", "08000", "08001", "08004", "57P01", "57P02", "57P03"]);
+/** System-catalog unique indexes touched when a label-table creation races
+ * itself: pg_class (relname,relnamespace), pg_type (typname,typnamespace),
+ * pg_namespace. A 23505 on one of these in the graph layer = the AGE
+ * label-creation race. */
+const CATALOG_RACE_CONSTRAINT = /pg_(class|type|namespace)_/i;
+export function isTransientDbError(err) {
+    if (err?.code && TRANSIENT_PG_CODE.has(String(err.code)))
+        return true;
+    const s = `${err?.code ?? ""} ${err?.message ?? ""}`;
+    return TRANSIENT_DB_ERROR.test(s);
+}
+/** The AGE lazy-label-creation race, in BOTH manifestations (42P07 duplicate_table
+ * and 23505 unique_violation on a pg_catalog index). Re-running the same
+ * idempotent graph statement once the label exists succeeds. Label-agnostic. */
+export function isLabelCreationRaceError(err) {
+    const code = String(err?.code ?? "");
+    if (code === "42P07")
+        return true; // duplicate_table
+    if (code === "23505") { // unique_violation…
+        const constraint = String(err?.constraint ?? "");
+        const message = String(err?.message ?? "");
+        if (CATALOG_RACE_CONSTRAINT.test(constraint) || CATALOG_RACE_CONSTRAINT.test(message))
+            return true;
+    }
+    return /already exists/i.test(String(err?.message ?? ""));
+}
+let DB_RETRY_HOOKS = {};
+/** Install process-wide retry observers (used by the eval perf/error report). */
+export function setDbRetryHooks(hooks) { DB_RETRY_HOOKS = hooks ?? {}; }
+export async function withDbRetry(label, fn, opts = {}) {
+    const tries = opts.tries ?? 4;
+    const isRetryable = opts.isRetryable ?? isTransientDbError;
+    let lastErr;
+    for (let attempt = 1; attempt <= tries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isRetryable(err) || attempt === tries)
+                throw err;
+            DB_RETRY_HOOKS.onRetry?.({ label, attempt, error: err });
+            await new Promise((r) => setTimeout(r, Math.min(200 * 2 ** (attempt - 1), 2000)));
+        }
+    }
+    throw lastErr;
+}
+//# sourceMappingURL=db-retry.js.map

package/dist/src/db-retry.js.map

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

package/dist/src/embedding-client.d.ts

@@ -0,0 +1,13 @@
+import type { EmbeddingEndpointConfig } from "./config.js";
+export declare class EmbeddingClient {
+    private readonly cfg;
+    constructor(cfg: EmbeddingEndpointConfig);
+    get dim(): number;
+    /** Embed a single string. Returns a vector of length `cfg.dim`. */
+    embed(text: string): Promise<number[]>;
+    /** Embed a batch. Returns one vector per input, in order. */
+    embedBatch(texts: string[]): Promise<number[][]>;
+}
+/** Format a JS number[] as a pgvector literal: "[0.1,0.2,...]". */
+export declare function toVectorLiteral(vec: number[]): string;
+//# sourceMappingURL=embedding-client.d.ts.map

package/dist/src/embedding-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-client.d.ts","sourceRoot":"","sources":["../../src/embedding-client.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,qBAAa,eAAe;IACZ,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,uBAAuB;IAKzD,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,mEAAmE;IAC7D,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAK5C,6DAA6D;IACvD,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CAyCzD;AAED,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAErD"}

package/dist/src/embedding-client.js

@@ -0,0 +1,79 @@
+// pilotswarm-horizon-store — Node-side embedding client.
+//
+// Two roles:
+//   1. QUERY-TIME embedding for semantic/hybrid search (the adapter embeds the
+//      query string here, then passes the vector to SQL as `$1::vector`).
+//   2. A reference implementation of the request/response contract that the
+//   2. A reference implementation of the request/response contract that any
+//      provider's embedding path must speak. The HorizonDB provider mirrors it
+//      in-database (sql/006 df.http); the integration test stub server speaks
+//      this exact shape.
+//
+// It calls an OpenAI/Azure-OpenAI-compatible embeddings endpoint over HTTP using
+// the global fetch (Node ≥ 18).
+export class EmbeddingClient {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+        if (!cfg?.url)
+            throw new Error("EmbeddingClient requires an endpoint url.");
+        if (!cfg.dim || cfg.dim < 1)
+            throw new Error("EmbeddingClient requires a positive dim.");
+    }
+    get dim() {
+        return this.cfg.dim;
+    }
+    /** Embed a single string. Returns a vector of length `cfg.dim`. */
+    async embed(text) {
+        const [v] = await this.embedBatch([text]);
+        return v;
+    }
+    /** Embed a batch. Returns one vector per input, in order. */
+    async embedBatch(texts) {
+        if (texts.length === 0)
+            return [];
+        const inputField = this.cfg.inputField ?? "input";
+        const headers = {
+            "content-type": "application/json",
+            ...(this.cfg.headers ?? {}),
+        };
+        if (this.cfg.apiKey) {
+            const headerName = this.cfg.apiKeyHeader ?? "api-key";
+            headers[headerName] = this.cfg.bearer ? `Bearer ${this.cfg.apiKey}` : this.cfg.apiKey;
+        }
+        const body = JSON.stringify({ [inputField]: texts.length === 1 ? texts[0] : texts, model: this.cfg.model });
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.cfg.timeoutMs ?? 30_000);
+        let res;
+        try {
+            res = await fetch(this.cfg.url, { method: "POST", headers, body, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok) {
+            const detail = await res.text().catch(() => "");
+            throw new Error(`embedding endpoint ${res.status}: ${detail.slice(0, 200)}`);
+        }
+        const json = await res.json();
+        const data = json?.data;
+        if (!Array.isArray(data) || data.length === 0) {
+            throw new Error("embedding endpoint returned no data[]");
+        }
+        const out = data.map((d) => {
+            const emb = d?.embedding;
+            if (!Array.isArray(emb))
+                throw new Error("embedding endpoint item missing embedding[]");
+            if (emb.length !== this.cfg.dim) {
+                throw new Error(`embedding dim mismatch: got ${emb.length}, expected ${this.cfg.dim}`);
+            }
+            return emb;
+        });
+        return out;
+    }
+}
+/** Format a JS number[] as a pgvector literal: "[0.1,0.2,...]". */
+export function toVectorLiteral(vec) {
+    return `[${vec.join(",")}]`;
+}
+//# sourceMappingURL=embedding-client.js.map

package/dist/src/embedding-client.js.map

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

package/dist/src/graph-model.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Normalize a surface name for SURFACE-FORM dedup only (case, whitespace,
+ * punctuation, diacritics). This does NOT solve semantic identity — "Tom Lane"
+ * vs "tgl" is resolved by the harvester via searchGraphNodes + mergeGraphNodes,
+ * which records an alias. Keep this conservative so we never collapse distinct
+ * people.
+ */
+export declare function normalizeName(raw: string): string;
+/** Canonical dedup key: `<normalized-kind>:<normalized-name>`. */
+export declare function nodeKeyOf(kind: string, name: string): string;
+/** Merge alias lists, de-duplicated by surface form, preserving first-seen order. */
+export declare function mergeAliases(existing: string[], incoming: string[]): string[];
+/**
+ * Normalize a free-text predicate into a grouping key. The original predicate
+ * is kept verbatim on the edge; this is only for matching/analytics so the open
+ * vocabulary stays queryable without being frozen.
+ */
+export declare function predicateKey(predicate: string): string;
+/**
+ * Combine an existing edge confidence with a new independent observation.
+ * Monotonic, saturating, order-independent:  c' = 1 - (1-c_old)(1-c_obs).
+ */
+export declare function reinforceConfidence(existing: number, observation: number): number;
+export declare function clamp01(x: number): number;
+export interface ExistingEdge {
+    confidence: number;
+    observations: number;
+    evidence: string[];
+}
+export interface EdgeUpsertDecision {
+    /** create: no edge existed. reinforce: bump observations + noisy-OR.
+     * noop: re-assert carried only already-known evidence — idempotent. */
+    action: "create" | "reinforce" | "noop";
+    confidence: number;
+    observations: number;
+    evidence: string[];
+}
+/**
+ * Evidence is OPTIONAL (the graph stays permissive). Reinforcement counts only
+ * NOVEL observations: an assertion reinforces iff it carries ≥1 evidence
+ * scopeKey not already on the edge, or carries no evidence at all. Re-asserting
+ * with only already-known evidence is an idempotent no-op — a duplicate/replayed
+ * harvest of the same fact cannot inflate observations or confidence.
+ */
+export declare function decideEdgeUpsert(input: {
+    confidence?: number;
+    evidence?: string[];
+}, existing: ExistingEdge | null): EdgeUpsertDecision;
+//# sourceMappingURL=graph-model.d.ts.map

package/dist/src/graph-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-model.d.ts","sourceRoot":"","sources":["../../src/graph-model.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASjD;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI5D;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAU7E;AAWD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOtD;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAIjF;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAKzC;AAID,MAAM,WAAW,YAAY;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IAC/B;2EACuE;IACvE,MAAM,EAAE,QAAQ,GAAG,WAAW,GAAG,MAAM,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC5B,KAAK,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EACnD,QAAQ,EAAE,YAAY,GAAG,IAAI,GAC9B,kBAAkB,CA0BpB"}

package/dist/src/graph-model.js

@@ -0,0 +1,112 @@
+// pilotswarm-horizon-store — open-graph quality core (DB-less, unit-tested).
+//
+// An LLM-built, ontology-free graph degenerates into noise without these pure
+// guards. These functions hold the policy; the typed Cypher layer just applies
+// their output. See docs/proposals/enhancedfactstore/01-functional-spec.md §6.
+// ─── Node canonicalization ───────────────────────────────────────────────────
+/**
+ * Normalize a surface name for SURFACE-FORM dedup only (case, whitespace,
+ * punctuation, diacritics). This does NOT solve semantic identity — "Tom Lane"
+ * vs "tgl" is resolved by the harvester via searchGraphNodes + mergeGraphNodes,
+ * which records an alias. Keep this conservative so we never collapse distinct
+ * people.
+ */
+export function normalizeName(raw) {
+    return (raw ?? "")
+        .normalize("NFKD")
+        .replace(/(\p{Script=Latin})\p{M}+/gu, "$1") // strip Latin diacritics
+        .normalize("NFC")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, " ") // punctuation → space, keep all scripts
+        .trim()
+        .replace(/\s+/g, " ");
+}
+/** Canonical dedup key: `<normalized-kind>:<normalized-name>`. */
+export function nodeKeyOf(kind, name) {
+    const k = normalizeName(kind).replace(/\s+/g, "_");
+    const n = normalizeName(name).replace(/\s+/g, "-");
+    return `${k}:${n}`;
+}
+/** Merge alias lists, de-duplicated by surface form, preserving first-seen order. */
+export function mergeAliases(existing, incoming) {
+    const seen = new Set();
+    const out = [];
+    for (const a of [...(existing ?? []), ...(incoming ?? [])]) {
+        const norm = normalizeName(a);
+        if (!norm || seen.has(norm))
+            continue;
+        seen.add(norm);
+        out.push(a.trim());
+    }
+    return out;
+}
+// ─── Predicate normalization ─────────────────────────────────────────────────
+// Tiny stopword set so "revives argument from" and "revives the argument from"
+// group together. Deliberately small — we group, we do NOT enforce a vocabulary.
+const PREDICATE_STOPWORDS = new Set([
+    "a", "an", "the", "to", "of", "in", "on", "with", "for", "from", "by",
+    "that", "this", "it", "its", "their", "his", "her",
+]);
+/**
+ * Normalize a free-text predicate into a grouping key. The original predicate
+ * is kept verbatim on the edge; this is only for matching/analytics so the open
+ * vocabulary stays queryable without being frozen.
+ */
+export function predicateKey(predicate) {
+    const words = normalizeName(predicate)
+        .split(" ")
+        .filter((w) => w && !PREDICATE_STOPWORDS.has(w));
+    // crude stem: drop a trailing 's' on each token (comments→comment)
+    const stemmed = words.map((w) => (w.length > 3 && w.endsWith("s") ? w.slice(0, -1) : w));
+    return stemmed.join("_");
+}
+// ─── Confidence reinforcement (noisy-OR) ─────────────────────────────────────
+/**
+ * Combine an existing edge confidence with a new independent observation.
+ * Monotonic, saturating, order-independent:  c' = 1 - (1-c_old)(1-c_obs).
+ */
+export function reinforceConfidence(existing, observation) {
+    const a = clamp01(existing);
+    const b = clamp01(observation);
+    return 1 - (1 - a) * (1 - b);
+}
+export function clamp01(x) {
+    if (!Number.isFinite(x))
+        return 0;
+    if (x < 0)
+        return 0;
+    if (x > 1)
+        return 1;
+    return x;
+}
+/**
+ * Evidence is OPTIONAL (the graph stays permissive). Reinforcement counts only
+ * NOVEL observations: an assertion reinforces iff it carries ≥1 evidence
+ * scopeKey not already on the edge, or carries no evidence at all. Re-asserting
+ * with only already-known evidence is an idempotent no-op — a duplicate/replayed
+ * harvest of the same fact cannot inflate observations or confidence.
+ */
+export function decideEdgeUpsert(input, existing) {
+    const obsConfidence = clamp01(input.confidence ?? 1.0);
+    const incoming = [...new Set(input.evidence ?? [])];
+    if (!existing) {
+        return { action: "create", confidence: obsConfidence, observations: 1, evidence: incoming };
+    }
+    const known = new Set(existing.evidence ?? []);
+    const novel = incoming.filter((e) => !known.has(e));
+    if (incoming.length > 0 && novel.length === 0) {
+        return {
+            action: "noop",
+            confidence: existing.confidence,
+            observations: existing.observations,
+            evidence: existing.evidence,
+        };
+    }
+    return {
+        action: "reinforce",
+        confidence: reinforceConfidence(existing.confidence, obsConfidence),
+        observations: existing.observations + 1,
+        evidence: [...(existing.evidence ?? []), ...novel],
+    };
+}
+//# sourceMappingURL=graph-model.js.map

package/dist/src/graph-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-model.js","sourceRoot":"","sources":["../../src/graph-model.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAE/E,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACrC,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC;SACb,SAAS,CAAC,MAAM,CAAC;SACjB,OAAO,CAAC,4BAA4B,EAAE,IAAI,CAAC,CAAC,yBAAyB;SACrE,SAAS,CAAC,KAAK,CAAC;SAChB,WAAW,EAAE;SACb,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAK,wCAAwC;SAC7E,IAAI,EAAE;SACN,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC9B,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,IAAY;IAChD,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnD,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnD,OAAO,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;AACvB,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,QAAkB,EAAE,QAAkB;IAC/D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACtC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED,gFAAgF;AAEhF,+EAA+E;AAC/E,iFAAiF;AACjF,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC;IAChC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI;IACrE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK;CACrD,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC1C,MAAM,KAAK,GAAG,aAAa,CAAC,SAAS,CAAC;SACjC,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,mEAAmE;IACnE,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzF,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,WAAmB;IACrE,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/B,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,CAAS;IAC7B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACpB,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACpB,OAAO,CAAC,CAAC;AACb,CAAC;AAmBD;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC5B,KAAmD,EACnD,QAA6B;IAE7B,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,IAAI,GAAG,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC;IAEpD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACZ,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;IAChG,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,OAAO;YACH,MAAM,EAAE,MAAM;YACd,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,YAAY,EAAE,QAAQ,CAAC,YAAY;YACnC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;SAC9B,CAAC;IACN,CAAC;IAED,OAAO;QACH,MAAM,EAAE,WAAW;QACnB,UAAU,EAAE,mBAAmB,CAAC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;QACnE,YAAY,EAAE,QAAQ,CAAC,YAAY,GAAG,CAAC;QACvC,QAAQ,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC;KACrD,CAAC;AACN,CAAC"}

package/dist/src/graph-queries.d.ts

@@ -0,0 +1,83 @@
+import type { AccessContext, GraphEdgeHit, GraphEdgeInput, GraphEdgeQuery, GraphNodeHit, GraphNodeInput, GraphNodeQuery, GraphNodeRef, GraphEdgeRef, GraphEvidenceRemovalResult, SubGraph } from "./types.js";
+/**
+ * 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 declare function prepareAgeSession(client: any): Promise<void>;
+/** Parse a scalar agtype column value into a JS value. */
+export declare function ag(v: any): any;
+/** Parse an agtype array column into string[]. */
+export declare function agArr(v: any): 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 declare class GraphQueries {
+    private readonly pool;
+    private readonly graphName;
+    private readonly prepared;
+    constructor(pool: any, graphName: string);
+    private withAge;
+    private cypher;
+    searchGraphNodes(q: GraphNodeQuery, access?: AccessContext): Promise<GraphNodeHit[]>;
+    /**
+     * 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.
+     */
+    private linkEvidenceAnchor;
+    /** EVIDENCED_BY scopeKeys per node, ACL-filtered (01 §6.1a), deduped
+     * (duplicate anchors must never surface as duplicate evidence keys). */
+    private evidenceFor;
+    searchGraphEdges(q: GraphEdgeQuery, access?: AccessContext): Promise<GraphEdgeHit[]>;
+    graphNeighbourhood(nodeKey: string, depth: number, _access?: AccessContext, opts?: {
+        namespace?: string;
+    }): Promise<SubGraph>;
+    /**
+     * 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.
+     */
+    graphStats(opts?: {
+        namespace?: string;
+    }): Promise<{
+        nodeCount: number;
+        edgeCount: number;
+    }>;
+    upsertGraphNode(n: GraphNodeInput): Promise<GraphNodeRef>;
+    upsertGraphEdge(e: GraphEdgeInput): Promise<GraphEdgeRef>;
+    mergeGraphNodes(fromKey: string, intoKey: string, reason: string, opts?: {
+        namespace?: string;
+    }): Promise<void>;
+    deleteGraphNode(nodeKey: string, opts?: {
+        namespace?: string;
+    }): Promise<boolean>;
+    deleteGraphEdge(fromKey: string, toKey: string, predicateKey: string, opts?: {
+        namespace?: string;
+    }): Promise<boolean>;
+    removeGraphEvidence(scopeKey: string, opts?: {
+        namespace?: string;
+    }): Promise<GraphEvidenceRemovalResult>;
+    /**
+     * 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).
+     */
+    deleteNamespaceData(namespace: string): Promise<{
+        nodesDeleted: number;
+        edgesDeleted: number;
+    }>;
+}
+//# sourceMappingURL=graph-queries.d.ts.map

package/dist/src/graph-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-queries.d.ts","sourceRoot":"","sources":["../../src/graph-queries.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACR,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAC3D,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,0BAA0B,EAAE,QAAQ,EACjH,MAAM,YAAY,CAAC;AA+EpB;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAQlE;AAED,0DAA0D;AAC1D,wBAAgB,EAAE,CAAC,CAAC,EAAE,GAAG,GAAG,GAAG,CAK9B;AAED,kDAAkD;AAClD,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,EAAE,CAGtC;AAED;;;;;GAKG;AACH,qBAAa,YAAY;IAWT,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAO,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFlE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAErB,IAAI,EAAE,GAAG,EAAmB,SAAS,EAAE,MAAM;YAE5D,OAAO;YAkBP,MAAM;IAiCd,gBAAgB,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAqF1F;;;;;;;;OAQG;YACW,kBAAkB;IAkBhC;4EACwE;YAC1D,WAAW;IAkBnB,gBAAgB,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA2BpF,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,EAAE,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IA4CvI;;;;OAIG;IACG,UAAU,CAAC,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAiBhG,eAAe,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAyCzD,eAAe,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAiEzD,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAuFnH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAYrF,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAe1H,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,0BAA0B,CAAC;IA6EnH;;;;;;;;OAQG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CA+BxG"}