pilotswarm-horizon-store 0.2.2

package/dist/src/horizon-migrator.js

@@ -0,0 +1,231 @@
+// pilotswarm-horizon-store — vendored migration runner.
+//
+// VENDORED from packages/sdk/src/pg-migrator.ts (advisory-locked, versioned,
+// one transaction per migration). TODO(graduation): merge back into
+// pg-migrator.ts when this package moves into packages/* — do not let the two
+// copies drift.
+//
+// The loader half is horizon-specific: it reads the numbered migrations/*.sql
+// files that ship with the package and substitutes the deployment tokens
+// ({{SCHEMA}}, {{GRAPH_NAME}}, {{EMBEDDING_DIM}}) before handing them to the
+// runner. All DDL lives in those files — none in TypeScript (04 §6 M1 guard).
+import { readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+/** Seed for the advisory lock — distinct from the SDK CMS/facts seeds. */
+export const HORIZON_FACTS_LOCK_SEED = 0x48_5a_46; // "HZF"
+/**
+ * Migration versions OWNED BY THE GRAPH PROVIDER (HorizonDBGraphStore), not the
+ * facts provider. The facts store filters these out of its run set; the graph
+ * store runs them inline as part of its idempotent bootstrap.
+ *   0003 — AGE extension + create_graph (the graph bootstrap).
+ *   0013 — graph_namespaces registry sidecar (graph-fact-search enhancements).
+ */
+export const GRAPH_OWNED_MIGRATIONS = ["0003", "0013"];
+export const HORIZON_GLOBAL_DDL_LOCK_LABEL = "__horizon_facts_global_ddl__";
+export const DEFAULT_MIGRATION_LOCK_TIMEOUT_MS = 60_000;
+const GLOBAL_DDL_SQL = /\bCREATE\s+EXTENSION\b|\bag_catalog\.create_graph\b/i;
+/** Whether a migration version is graph-owned (run by the graph store, not facts). */
+export function isGraphOwnedMigration(version) {
+    return GRAPH_OWNED_MIGRATIONS.includes(version);
+}
+/** Whether a migration contains database-global DDL that needs global serialization. */
+export function migrationRequiresGlobalDdlLock(migration) {
+    return GLOBAL_DDL_SQL.test(migration.sql);
+}
+/**
+ * Run all pending migrations against the given schema.
+ *
+ * Uses a PostgreSQL advisory lock keyed on `lockSeed` + schema name to
+ * serialize concurrent workers. Each migration runs in its own transaction.
+ * Throws (never "repairs") when the migrations table records a version the
+ * code does not know — a newer deployment owns this schema.
+ */
+export async function runMigrations(pool, schema, migrations, lockSeed) {
+    const lockKey = hashSchemaName(schema, lockSeed);
+    const globalDdlLockKey = hashSchemaName(HORIZON_GLOBAL_DDL_LOCK_LABEL, lockSeed);
+    const client = await pool.connect();
+    let schemaLockHeld = false;
+    try {
+        // Serialize concurrent initializers for the same schema, but keep other
+        // schemas moving. The database-global DDL lock is acquired only inside
+        // the specific migration transactions that need it.
+        await acquireSessionAdvisoryLock(client, lockKey, `horizon schema migration for ${schema}`);
+        schemaLockHeld = true;
+        await client.query(`CREATE SCHEMA IF NOT EXISTS "${schema}"`);
+        const migrationsTable = `"${schema}".schema_migrations`;
+        await client.query(`
+            CREATE TABLE IF NOT EXISTS ${migrationsTable} (
+                version     TEXT PRIMARY KEY,
+                name        TEXT NOT NULL,
+                applied_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+            )
+        `);
+        const { rows: applied } = await client.query(`SELECT version FROM ${migrationsTable} ORDER BY version`);
+        const appliedSet = new Set(applied.map((r) => r.version));
+        const knownSet = new Set(migrations.map((m) => m.version));
+        const unknown = [...appliedSet].filter((v) => !knownSet.has(v));
+        if (unknown.length > 0) {
+            throw new Error(`horizon-facts migrations: schema "${schema}" records versions this build does not know ` +
+                `(${unknown.join(", ")}). A newer deployment owns this schema; refusing to continue.`);
+        }
+        for (const migration of migrations) {
+            if (appliedSet.has(migration.version))
+                continue;
+            for (let attempt = 1; attempt <= 5; attempt++) {
+                try {
+                    await client.query("BEGIN");
+                    if (migrationRequiresGlobalDdlLock(migration)) {
+                        await acquireTransactionAdvisoryLock(client, globalDdlLockKey, `horizon global DDL migration ${migration.version} (${migration.name})`);
+                    }
+                    await client.query(migration.sql);
+                    await client.query(`INSERT INTO ${migrationsTable} (version, name) VALUES ($1, $2)`, [migration.version, migration.name]);
+                    await client.query("COMMIT");
+                    break;
+                }
+                catch (err) {
+                    await client.query("ROLLBACK").catch(() => { });
+                    if (!isRetryableMigrationRace(err) || attempt === 5)
+                        throw err;
+                    await new Promise((resolve) => setTimeout(resolve, 200 * attempt));
+                }
+            }
+        }
+    }
+    finally {
+        if (schemaLockHeld)
+            await client.query("SELECT pg_advisory_unlock($1)", [lockKey]).catch(() => { });
+        client.release();
+    }
+}
+function migrationLockTimeoutMs() {
+    const raw = process.env.HORIZON_MIGRATION_LOCK_TIMEOUT_MS;
+    if (raw == null || raw === "")
+        return DEFAULT_MIGRATION_LOCK_TIMEOUT_MS;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`HORIZON_MIGRATION_LOCK_TIMEOUT_MS must be a non-negative number, got ${JSON.stringify(raw)}`);
+    }
+    return Math.trunc(value);
+}
+async function acquireSessionAdvisoryLock(client, key, label) {
+    await acquireAdvisoryLock(client, key, label, "pg_try_advisory_lock");
+}
+async function acquireTransactionAdvisoryLock(client, key, label) {
+    await acquireAdvisoryLock(client, key, label, "pg_try_advisory_xact_lock");
+}
+async function acquireAdvisoryLock(client, key, label, fnName) {
+    const timeoutMs = migrationLockTimeoutMs();
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const { rows } = await client.query(`SELECT ${fnName}($1) AS locked`, [key]);
+        if (rows[0]?.locked === true)
+            return;
+        if (Date.now() >= deadline) {
+            throw new Error(await advisoryLockTimeoutMessage(client, key, label, timeoutMs));
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+}
+async function advisoryLockTimeoutMessage(client, key, label, timeoutMs) {
+    try {
+        const { classid, objid } = advisoryLockKeyParts(key);
+        const { rows } = await client.query(`SELECT a.pid,
+                    a.state,
+                    a.wait_event_type,
+                    a.wait_event,
+                    now() - a.query_start AS age,
+                    left(a.query, 160) AS query
+               FROM pg_locks l
+               LEFT JOIN pg_stat_activity a ON a.pid = l.pid
+              WHERE l.locktype = 'advisory'
+                AND l.granted
+                AND l.classid::bigint = $1
+                AND l.objid::bigint = $2
+              ORDER BY a.query_start NULLS LAST
+              LIMIT 5`, [String(classid), String(objid)]);
+        const holders = rows.length > 0
+            ? rows.map((row) => `pid=${row.pid} state=${row.state ?? "unknown"} wait=${row.wait_event_type ?? ""}/${row.wait_event ?? ""} query=${JSON.stringify(row.query ?? "")}`).join("; ")
+            : "no granted holder found";
+        return `${label} could not acquire advisory lock ${key} within ${timeoutMs}ms; holders: ${holders}`;
+    }
+    catch (err) {
+        return `${label} could not acquire advisory lock ${key} within ${timeoutMs}ms; holder lookup failed: ${err?.message ?? err}`;
+    }
+}
+export function advisoryLockKeyParts(key) {
+    const unsigned = BigInt.asUintN(64, BigInt(Math.trunc(key)));
+    return {
+        classid: String((unsigned >> 32n) & 0xffffffffn),
+        objid: String(unsigned & 0xffffffffn),
+    };
+}
+// Concurrent first-time creation of the same global object (extension, AGE
+// graph schema, catalog row) surfaces as one of these races. The losing tx
+// rolled back and committed nothing, and the object now exists, so re-running
+// the same idempotent migration statement succeeds.
+function isRetryableMigrationRace(err) {
+    const text = `${err?.code ?? ""} ${err?.message ?? ""} ${err?.detail ?? ""}`;
+    return /tuple concurrently updated|deadlock detected|could not serialize access|already exists/i.test(text);
+}
+/** Stable 32-bit hash of a schema name combined with a per-system seed. */
+export function hashSchemaName(schema, seed) {
+    let hash = seed;
+    for (let i = 0; i < schema.length; i++) {
+        hash = ((hash << 5) - hash + schema.charCodeAt(i)) | 0;
+    }
+    return hash;
+}
+const MIGRATION_FILE = /^(\d{4})_([a-z0-9_]+)\.sql$/;
+/** Resolve the packaged migrations/ directory (works from src/ and dist/src/). */
+export function migrationsDir() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    // src/ → ../migrations ; dist/src/ → ../../migrations
+    for (const rel of ["../migrations", "../../migrations"]) {
+        const dir = path.resolve(here, rel);
+        try {
+            readdirSync(dir);
+            return dir;
+        }
+        catch { /* try next */ }
+    }
+    throw new Error(`horizon-facts: cannot locate migrations/ relative to ${here}`);
+}
+/** Load the numbered migrations, token-substituted for this deployment. */
+export function loadMigrations(tokens) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tokens.schema)) {
+        throw new Error(`unsafe schema name: ${JSON.stringify(tokens.schema)}`);
+    }
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tokens.graphName)) {
+        throw new Error(`unsafe graph name: ${JSON.stringify(tokens.graphName)}`);
+    }
+    const registrySchema = tokens.registrySchema ?? `${tokens.graphName}_registry`;
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(registrySchema)) {
+        throw new Error(`unsafe registry schema name: ${JSON.stringify(registrySchema)}`);
+    }
+    const dim = Math.trunc(tokens.embeddingDim);
+    if (!Number.isFinite(dim) || dim < 1) {
+        throw new Error(`embeddingDim must be a positive integer, got ${tokens.embeddingDim}`);
+    }
+    const dir = migrationsDir();
+    const files = readdirSync(dir).filter((f) => MIGRATION_FILE.test(f)).sort();
+    if (files.length === 0)
+        throw new Error(`horizon-facts: no migrations found in ${dir}`);
+    let last = 0;
+    return files.map((f) => {
+        const m = MIGRATION_FILE.exec(f);
+        const num = Number(m[1]);
+        if (num !== last + 1) {
+            throw new Error(`horizon-facts migrations: non-contiguous numbering at ${f} (expected ${String(last + 1).padStart(4, "0")})`);
+        }
+        last = num;
+        const raw = readFileSync(path.join(dir, f), "utf8");
+        const sql = raw
+            .replaceAll("{{SCHEMA}}", tokens.schema)
+            .replaceAll("{{GRAPH_NAME}}", tokens.graphName)
+            .replaceAll("{{REGISTRY_SCHEMA}}", registrySchema)
+            .replaceAll("{{EMBEDDING_DIM}}", String(dim));
+        return { version: m[1], name: m[2], sql };
+    });
+}
+//# sourceMappingURL=horizon-migrator.js.map

package/dist/src/horizon-migrator.js.map

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

package/dist/src/horizon-store.d.ts

@@ -0,0 +1,116 @@
+import type { AccessContext, CrawledFactStamp, DeletedFactResult, DeletedFactsResult, DeleteFactInput, EmbedderStatus, EmbeddingEndpointConfig, EnhancedFactStore, FactRecord, FactsStatsRow, FactsTombstoneStats, ForcePurgeFactsInput, ReadFactsQuery, SearchOpts, SearchResult, SimilarOpts, StoreFactInput, StoredFactResult } from "./types.js";
+import type { HorizonFactsConfig } from "./config.js";
+/** df-allow-list normalization: the Azure AI Foundry unified host is blocked
+ * for df.http; the classic AOAI host points at the same deployment. */
+export declare function toAllowlistedAzureHost(url: string): {
+    url: string;
+    rewritten: boolean;
+};
+export declare class HorizonDBFactStore implements EnhancedFactStore {
+    private readonly cfg;
+    private pool;
+    private initialized;
+    /** Snapshot of the configured endpoint (mirrors the durable vars). */
+    private embedConfig?;
+    private queryEmbedder?;
+    /** Capability descriptor (enhancedfactstore 07 §1.4) — HorizonDB always
+     * backs multi-signal search (lexical works with no endpoint). `embedder`
+     * reflects whether an embedding endpoint was provisioned at construction:
+     * the durable in-DB embed loop only runs (and semantic/hybrid return
+     * semantic hits) when one is configured. A store created without
+     * `embedding` reports `embedder:false` so the runtime can gate the embedder
+     * lifecycle on real configuration rather than a hardcoded `true`. */
+    readonly capabilities: {
+        search: boolean;
+        embedder: boolean;
+    };
+    private constructor();
+    static create(config?: Partial<HorizonFactsConfig>): Promise<HorizonDBFactStore>;
+    private get schema();
+    private get s();
+    /**
+     * Fail-fast (01 §5.5): verify every required extension is available —
+     * itemized error otherwise — then apply the numbered migrations, then
+     * verify df.http usability. When the config carries an embedding endpoint,
+     * configure the embedder from it.
+     */
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    storeFact(input: StoreFactInput): Promise<StoredFactResult>;
+    storeFact(input: StoreFactInput[]): Promise<{
+        stored: number;
+        facts: StoredFactResult[];
+    }>;
+    readFacts(query: ReadFactsQuery, access?: AccessContext): Promise<{
+        count: number;
+        facts: FactRecord[];
+    }>;
+    deleteFact(input: DeleteFactInput & {
+        pattern: true;
+    }): Promise<DeletedFactsResult>;
+    deleteFact(input: DeleteFactInput & {
+        pattern?: false | undefined;
+    }): Promise<DeletedFactResult>;
+    deleteFact(input: DeleteFactInput): Promise<DeletedFactResult | DeletedFactsResult>;
+    deleteSessionFactsForSession(sessionId: string): Promise<number>;
+    private stats;
+    getSessionFactsStats(sessionId: string): Promise<FactsStatsRow[]>;
+    getFactsStatsForSessions(sessionIds: string[]): Promise<FactsStatsRow[]>;
+    getSharedFactsStats(): Promise<FactsStatsRow[]>;
+    searchFacts(query: string, opts?: SearchOpts, access?: AccessContext): Promise<SearchResult>;
+    private aclParams;
+    private lexicalCandidates;
+    private semanticCandidates;
+    similarFacts(scopeKey: string, opts?: SimilarOpts, access?: AccessContext): Promise<SearchResult>;
+    readUncrawledFacts(opts?: {
+        namespace?: string;
+        limit?: number;
+        embeddedOnly?: boolean;
+    }): Promise<{
+        count: number;
+        facts: FactRecord[];
+    }>;
+    markFactsCrawled(stamps: CrawledFactStamp[]): Promise<{
+        marked: number;
+        skipped: number;
+    }>;
+    purgeExpiredFacts(ttlSeconds: number, limit?: number): Promise<number>;
+    getFactsTombstoneStats(ttlSeconds?: number): Promise<FactsTombstoneStats>;
+    forcePurgeFacts(input: ForcePurgeFactsInput): Promise<number>;
+    private varName;
+    private embedderLabel;
+    private get legacyEmbedderLabel();
+    private get embedderLabels();
+    private cancelRunningLabel;
+    /**
+     * Serialize embedder start/restart across processes. Two providers
+     * initializing the same schema concurrently must not both df.start (the
+     * design is ONE loop per schema, label hz-embed-cron:<schema>). Reuses the
+     * migrator's advisory-lock pattern: hold a session-level lock on a single
+     * checked-out client for the whole critical section, then release it.
+     */
+    private withEmbedderLock;
+    configureEmbedder(endpoint: EmbeddingEndpointConfig, opts?: {
+        restartIfRunning?: boolean;
+    }): Promise<EmbedderStatus>;
+    startEmbedder(opts?: {
+        intervalSeconds?: number;
+        batch?: number;
+    }): Promise<EmbedderStatus>;
+    private startLoops;
+    stopEmbedder(reason?: string): Promise<EmbedderStatus>;
+    embedderStatus(exec?: any): Promise<EmbedderStatus>;
+    private getvar;
+    /** Query-time embedding client, resolved from the configured endpoint
+     * (memory snapshot → durable vars). Throws when semantic search is
+     * attempted with no endpoint configured (02 §6). */
+    /**
+     * Whether an embedding endpoint is available to this store — either the
+     * in-memory snapshot or the durable config vars written by configureEmbedder
+     * (possibly by another process). Non-throwing; used by searchFacts to decide
+     * whether HYBRID can include the semantic signal or must degrade to lexical.
+     */
+    private hasEmbedder;
+    private requireQueryEmbedder;
+}
+//# sourceMappingURL=horizon-store.d.ts.map

package/dist/src/horizon-store.d.ts.map

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