@nicia-ai/typegraph 0.29.0 → 0.31.0

package/README.md

@@ -46,6 +46,45 @@ See the repo README for more.
 
 Examples: [github.com/nicia-ai/typegraph/tree/main/packages/typegraph/examples](https://github.com/nicia-ai/typegraph/tree/main/packages/typegraph/examples)
 
+## Graph Merge
+
+TypeGraph ships semantic graph merge as a dedicated subpath:
+
+```ts
+import { branch, merge } from "@nicia-ai/typegraph/graph-merge";
+```
+
+`branch()` creates isolated working copies over caller-provided backends, stamped
+with the base graph's schema and content version. `merge()` reconciles those
+branches back into a target graph with deterministic entity resolution, conflict
+reporting, edge repointing, optional ontology type reconciliation, and provenance
+reporting.
+
+Use it when several agents, importers, reviewers, or local workers edit graph
+state independently and the application needs one canonical result instead of an
+append-only pile of duplicates. The merge pipeline can:
+
+- resolve duplicate entities by exact unique constraints, blocking keys,
+  fulltext/custom similarity, or vector/hybrid similarity;
+- preserve branch-specific context by repointing edges to canonical nodes;
+- surface property and delete/modify conflicts (for nodes and edges) in a
+  `MergeReport`, three-way merged against base so disjoint edits compose;
+- expose report-only provenance, with optional sidecar persistence you can query.
+
+`merge()` is a snapshot merge (all branches forked from the current base);
+`mergeIncremental()` additively folds a new source into a target that has already
+advanced, re-discovering committed entities instead of duplicating them — the
+primitive for continuous ingestion.
+
+It lives in the core package because the primitive is defined over TypeGraph
+stores, schemas, indexes, backends, and ontology semantics rather than as a
+separate product surface.
+
+Docs: [Graph Merge](https://typegraph.dev/graph-merge)
+
+Examples: [FHIR Graph Merge](https://typegraph.dev/examples/fhir-graph-merge)
+· [Incremental Merge](https://typegraph.dev/examples/incremental-merge)
+
 ## Performance Smoke Check
 
 The perf harness lives in `@nicia-ai/typegraph-benchmarks`; these commands delegate to it.

package/dist/backend/postgres/index.cjs

@@ -1,58 +1,59 @@
 'use strict';
 
-var chunkUP4QAJND_cjs = require('../../chunk-UP4QAJND.cjs');
-require('../../chunk-KGAJ5HFO.cjs');
-var chunkZYQEXGYC_cjs = require('../../chunk-ZYQEXGYC.cjs');
-require('../../chunk-F2Q76CQ4.cjs');
+var chunkFLOI7QOT_cjs = require('../../chunk-FLOI7QOT.cjs');
+require('../../chunk-5CN7B4CZ.cjs');
+require('../../chunk-HTGDWIDE.cjs');
+var chunkCIINW6PS_cjs = require('../../chunk-CIINW6PS.cjs');
+require('../../chunk-54JVNOAQ.cjs');
+require('../../chunk-VMEWZU2N.cjs');
+require('../../chunk-6G35I3VW.cjs');
 require('../../chunk-RP7YITHX.cjs');
-require('../../chunk-C2RWFIYP.cjs');
-require('../../chunk-UPBXUOW7.cjs');
-require('../../chunk-VGU26WIU.cjs');
-require('../../chunk-ZFWNO3GE.cjs');
-require('../../chunk-G6P3OVDY.cjs');
-require('../../chunk-7V335GHG.cjs');
+require('../../chunk-V4IQYOQ4.cjs');
+require('../../chunk-73KASJGO.cjs');
+require('../../chunk-JIEJCTDS.cjs');
+require('../../chunk-FLRCVI2G.cjs');
 
 
 
 Object.defineProperty(exports, "createPostgresBackend", {
   enumerable: true,
-  get: function () { return chunkUP4QAJND_cjs.createPostgresBackend; }
+  get: function () { return chunkFLOI7QOT_cjs.createPostgresBackend; }
 });
 Object.defineProperty(exports, "createPostgresTables", {
   enumerable: true,
-  get: function () { return chunkZYQEXGYC_cjs.createPostgresTables; }
+  get: function () { return chunkCIINW6PS_cjs.createPostgresTables; }
 });
 Object.defineProperty(exports, "edges", {
   enumerable: true,
-  get: function () { return chunkZYQEXGYC_cjs.edges; }
+  get: function () { return chunkCIINW6PS_cjs.edges; }
 });
 Object.defineProperty(exports, "fulltext", {
   enumerable: true,
-  get: function () { return chunkZYQEXGYC_cjs.fulltext; }
+  get: function () { return chunkCIINW6PS_cjs.fulltext; }
 });
 Object.defineProperty(exports, "generatePostgresDDL", {
   enumerable: true,
-  get: function () { return chunkZYQEXGYC_cjs.generatePostgresDDL; }
+  get: function () { return chunkCIINW6PS_cjs.generatePostgresDDL; }
 });
 Object.defineProperty(exports, "generatePostgresMigrationSQL", {
   enumerable: true,
-  get: function () { return chunkZYQEXGYC_cjs.generatePostgresMigrationSQL; }
+  get: function () { return chunkCIINW6PS_cjs.generatePostgresMigrationSQL; }
 });
 Object.defineProperty(exports, "nodes", {
   enumerable: true,
-  get: function () { return chunkZYQEXGYC_cjs.nodes; }
+  get: function () { return chunkCIINW6PS_cjs.nodes; }
 });
 Object.defineProperty(exports, "schemaVersions", {
   enumerable: true,
-  get: function () { return chunkZYQEXGYC_cjs.schemaVersions; }
+  get: function () { return chunkCIINW6PS_cjs.schemaVersions; }
 });
 Object.defineProperty(exports, "tables", {
   enumerable: true,
-  get: function () { return chunkZYQEXGYC_cjs.tables; }
+  get: function () { return chunkCIINW6PS_cjs.tables; }
 });
 Object.defineProperty(exports, "uniques", {
   enumerable: true,
-  get: function () { return chunkZYQEXGYC_cjs.uniques; }
+  get: function () { return chunkCIINW6PS_cjs.uniques; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/backend/postgres/index.d.cts

@@ -1,13 +1,13 @@
-import { F as FulltextStrategy, V as VectorStrategy, B as BackendCapabilities, b as AnyPgDatabase, G as GraphBackend } from '../../types-DXCSyxac.cjs';
-import { P as PostgresTables } from '../../postgres-CQL9UIn2.cjs';
-export { C as CreatePostgresTablesOptions, a as PostgresTableNames, c as createPostgresTables, e as edges, f as fulltext, n as nodes, s as schemaVersions, t as tables, u as uniques } from '../../postgres-CQL9UIn2.cjs';
-export { b as generatePostgresDDL, c as generatePostgresMigrationSQL } from '../../ddl-D3o-RmsV.cjs';
+import { F as FulltextStrategy, V as VectorStrategy, B as BackendCapabilities, b as AnyPgDatabase, G as GraphBackend } from '../../types-C1CYxWrL.cjs';
+import { P as PostgresTables } from '../../postgres-4J2tmauh.cjs';
+export { C as CreatePostgresTablesOptions, a as PostgresTableNames, c as createPostgresTables, e as edges, f as fulltext, n as nodes, s as schemaVersions, t as tables, u as uniques } from '../../postgres-4J2tmauh.cjs';
+export { b as generatePostgresDDL, c as generatePostgresMigrationSQL } from '../../ddl-CPZ7mB7X.cjs';
 import 'zod';
-import '../../extension-types-CwHV-Uk4.cjs';
+import '../../extension-types-D1k0inWU.cjs';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm/sqlite-core';
-import '../../sqlite-Rj3xu4It.cjs';
+import '../../sqlite-Gatk_iw_.cjs';
 
 /**
  * Options for creating a PostgreSQL backend.

package/dist/backend/postgres/index.d.ts

@@ -1,13 +1,13 @@
-import { F as FulltextStrategy, V as VectorStrategy, B as BackendCapabilities, b as AnyPgDatabase, G as GraphBackend } from '../../types-CmAT-Z47.js';
-import { P as PostgresTables } from '../../postgres-CcRLaxz0.js';
-export { C as CreatePostgresTablesOptions, a as PostgresTableNames, c as createPostgresTables, e as edges, f as fulltext, n as nodes, s as schemaVersions, t as tables, u as uniques } from '../../postgres-CcRLaxz0.js';
-export { b as generatePostgresDDL, c as generatePostgresMigrationSQL } from '../../ddl-BwH00BB6.js';
+import { F as FulltextStrategy, V as VectorStrategy, B as BackendCapabilities, b as AnyPgDatabase, G as GraphBackend } from '../../types-BKQljXom.js';
+import { P as PostgresTables } from '../../postgres-BdIb7tS_.js';
+export { C as CreatePostgresTablesOptions, a as PostgresTableNames, c as createPostgresTables, e as edges, f as fulltext, n as nodes, s as schemaVersions, t as tables, u as uniques } from '../../postgres-BdIb7tS_.js';
+export { b as generatePostgresDDL, c as generatePostgresMigrationSQL } from '../../ddl-BJcPrB4L.js';
 import 'zod';
-import '../../extension-types-CwHV-Uk4.js';
+import '../../extension-types-D1k0inWU.js';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm/sqlite-core';
-import '../../sqlite-CZDFUfHS.js';
+import '../../sqlite-aM_PAz-O.js';
 
 /**
  * Options for creating a PostgreSQL backend.

package/dist/backend/postgres/index.js

@@ -1,13 +1,14 @@
-export { createPostgresBackend } from '../../chunk-Y52UNT66.js';
-import '../../chunk-IE2TPFBT.js';
-export { createPostgresTables, edges, fulltext, generatePostgresDDL, generatePostgresMigrationSQL, nodes, schemaVersions, tables, uniques } from '../../chunk-3DTLDGIM.js';
-import '../../chunk-HKN622O4.js';
+export { createPostgresBackend } from '../../chunk-STP7QVUB.js';
+import '../../chunk-ATTXBMAX.js';
+import '../../chunk-3EUKJEQ3.js';
+export { createPostgresTables, edges, fulltext, generatePostgresDDL, generatePostgresMigrationSQL, nodes, schemaVersions, tables, uniques } from '../../chunk-VZX2KSY3.js';
+import '../../chunk-GKFWM3DS.js';
+import '../../chunk-LJLMDDCW.js';
+import '../../chunk-SAJSMR2B.js';
 import '../../chunk-M6OC455F.js';
-import '../../chunk-7KLVFWXR.js';
-import '../../chunk-OGUH56BB.js';
-import '../../chunk-N3VVQDMA.js';
-import '../../chunk-454I6GDF.js';
-import '../../chunk-MB363HT5.js';
-import '../../chunk-NZ5PMBTG.js';
+import '../../chunk-2HZGWCB4.js';
+import '../../chunk-2YMGNYXY.js';
+import '../../chunk-TQOYM4LN.js';
+import '../../chunk-K5P5OZXS.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/backend/postgres/pglite.cjs

@@ -1,16 +1,17 @@
 'use strict';
 
-var chunkUP4QAJND_cjs = require('../../chunk-UP4QAJND.cjs');
-require('../../chunk-KGAJ5HFO.cjs');
-var chunkZYQEXGYC_cjs = require('../../chunk-ZYQEXGYC.cjs');
-var chunkF2Q76CQ4_cjs = require('../../chunk-F2Q76CQ4.cjs');
+var chunkFLOI7QOT_cjs = require('../../chunk-FLOI7QOT.cjs');
+require('../../chunk-5CN7B4CZ.cjs');
+require('../../chunk-HTGDWIDE.cjs');
+var chunkCIINW6PS_cjs = require('../../chunk-CIINW6PS.cjs');
+require('../../chunk-54JVNOAQ.cjs');
+require('../../chunk-VMEWZU2N.cjs');
+var chunk6G35I3VW_cjs = require('../../chunk-6G35I3VW.cjs');
 require('../../chunk-RP7YITHX.cjs');
-require('../../chunk-C2RWFIYP.cjs');
-require('../../chunk-UPBXUOW7.cjs');
-require('../../chunk-VGU26WIU.cjs');
-require('../../chunk-ZFWNO3GE.cjs');
-var chunkG6P3OVDY_cjs = require('../../chunk-G6P3OVDY.cjs');
-require('../../chunk-7V335GHG.cjs');
+require('../../chunk-V4IQYOQ4.cjs');
+require('../../chunk-73KASJGO.cjs');
+var chunkJIEJCTDS_cjs = require('../../chunk-JIEJCTDS.cjs');
+require('../../chunk-FLRCVI2G.cjs');
 var pglite = require('@electric-sql/pglite');
 var pglite$1 = require('drizzle-orm/pglite');
 
@@ -19,7 +20,7 @@ async function loadDefaultPgvectorExtension() {
     const module_ = await import('@electric-sql/pglite-pgvector');
     return module_.vector;
   } catch (error) {
-    throw new chunkG6P3OVDY_cjs.ConfigurationError(
+    throw new chunkJIEJCTDS_cjs.ConfigurationError(
       "createLocalPgliteBackend needs the pgvector extension but `@electric-sql/pglite-pgvector` could not be loaded. Install it (`pnpm add @electric-sql/pglite-pgvector`), pass your own `vector` extension, or set `vector: false` to disable vector support.",
       { backend: "pglite", dependency: "@electric-sql/pglite-pgvector" },
       { cause: error }
@@ -27,21 +28,21 @@ async function loadDefaultPgvectorExtension() {
   }
 }
 async function createLocalPgliteBackend(options = {}) {
-  const tables2 = options.tables ?? chunkZYQEXGYC_cjs.tables;
+  const tables2 = options.tables ?? chunkCIINW6PS_cjs.tables;
   const vectorExtension = options.vector === false ? void 0 : options.vector ?? await loadDefaultPgvectorExtension();
   const vectorEnabled = vectorExtension !== void 0;
   const client = await pglite.PGlite.create({
     ...options.dataDir === void 0 ? {} : { dataDir: options.dataDir },
     ...vectorExtension === void 0 ? {} : { extensions: { vector: vectorExtension } }
   });
-  const migrationSql = vectorEnabled ? chunkZYQEXGYC_cjs.generatePostgresMigrationSQL(tables2) : chunkZYQEXGYC_cjs.generatePostgresDDL(tables2).join("\n\n");
+  const migrationSql = vectorEnabled ? chunkCIINW6PS_cjs.generatePostgresMigrationSQL(tables2) : chunkCIINW6PS_cjs.generatePostgresDDL(tables2).join("\n\n");
   await client.exec(migrationSql);
   const db = pglite$1.drizzle(client);
-  const backend = chunkUP4QAJND_cjs.createPostgresBackend(db, {
+  const backend = chunkFLOI7QOT_cjs.createPostgresBackend(db, {
     tables: tables2,
     ...vectorEnabled ? {} : { vector: false }
   });
-  const managedBackend = chunkF2Q76CQ4_cjs.wrapWithManagedClose(backend, async () => {
+  const managedBackend = chunk6G35I3VW_cjs.wrapWithManagedClose(backend, async () => {
     await client.close();
   });
   return { backend: managedBackend, db, client };

package/dist/backend/postgres/pglite.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/backend/postgres/pglite.ts"],"names":["ConfigurationError","tables","PGlite","generatePostgresMigrationSQL","generatePostgresDDL","drizzle","createPostgresBackend","wrapWithManagedClose"],"mappings":";;;;;;;;;;;;;;;;AA2HA,eAAe,4BAAA,GAAmD;AAChE,EAAA,IAAI;AACF,IAAA,MAAM,OAAA,GAAU,MAAM,OAAO,+BAA+B,CAAA;AAC5D,IAAA,OAAO,OAAA,CAAQ,MAAA;AAAA,EACjB,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,IAAIA,oCAAA;AAAA,MACR,2PAAA;AAAA,MAIA,EAAE,OAAA,EAAS,QAAA,EAAU,UAAA,EAAY,+BAAA,EAAgC;AAAA,MACjE,EAAE,OAAO,KAAA;AAAM,KACjB;AAAA,EACF;AACF;AAoBA,eAAsB,wBAAA,CACpB,OAAA,GAAqC,EAAC,EACH;AACnC,EAAA,MAAMC,OAAAA,GAAS,QAAQ,MAAA,IAAUA,wBAAA;AAMjC,EAAA,MAAM,eAAA,GACJ,QAAQ,MAAA,KAAW,KAAA,GACjB,SACC,OAAA,CAAQ,MAAA,IAAW,MAAM,4BAAA,EAA6B;AAC3D,EAAA,MAAM,gBAAgB,eAAA,KAAoB,MAAA;AAO1C,EAAA,MAAM,MAAA,GAAS,MAAMC,aAAA,CAAO,MAAA,CAAO;AAAA,IACjC,GAAI,QAAQ,OAAA,KAAY,MAAA,GAAY,EAAC,GAAI,EAAE,OAAA,EAAS,OAAA,CAAQ,OAAA,EAAQ;AAAA,IACpE,GAAI,eAAA,KAAoB,MAAA,GACtB,EAAC,GACD,EAAE,UAAA,EAAY,EAAE,MAAA,EAAQ,eAAA,EAAgB;AAAE,GAC7C,CAAA;AAID,EAAA,MAAM,YAAA,GACJ,gBACEC,8CAAA,CAA6BF,OAAM,IACnCG,qCAAA,CAAoBH,OAAM,CAAA,CAAE,IAAA,CAAK,MAAM,CAAA;AAC3C,EAAA,MAAM,MAAA,CAAO,KAAK,YAAY,CAAA;AAE9B,EAAA,MAAM,EAAA,GAAKI,iBAAQ,MAAM,CAAA;AACzB,EAAA,MAAM,OAAA,GAAUC,wCAAsB,EAAA,EAAI;AAAA,IACxC,MAAA,EAAAL,OAAAA;AAAA,IACA,GAAI,aAAA,GAAgB,EAAC,GAAI,EAAE,QAAQ,KAAA;AAAM,GAC1C,CAAA;AACD,EAAA,MAAM,cAAA,GAAiBM,sCAAA,CAAqB,OAAA,EAAS,YAAY;AAC/D,IAAA,MAAM,OAAO,KAAA,EAAM;AAAA,EACrB,CAAC,CAAA;AAED,EAAA,OAAO,EAAE,OAAA,EAAS,cAAA,EAAgB,EAAA,EAAI,MAAA,EAAO;AAC/C","file":"pglite.cjs","sourcesContent":["/**\n * Local PGlite backend — Postgres-in-WASM, running in-process.\n *\n * [PGlite](https://pglite.dev/) is a full Postgres compiled to WebAssembly\n * that runs inside the Node/Bun/Deno/browser process with no server and no\n * native addon. This is the batteries-included Postgres analog of\n * `createLocalSqliteBackend`: it constructs a PGlite instance, loads the\n * pgvector extension, runs the schema DDL, and returns a ready\n * `{ backend, db }` pair whose `close()` disposes the engine.\n *\n * `@electric-sql/pglite` is an optional peer dependency. Vector support\n * additionally needs `@electric-sql/pglite-pgvector` (PGlite ≥ 0.5 ships\n * pgvector as a separate package). Install what you need:\n *\n * ```bash\n * pnpm add @electric-sql/pglite @electric-sql/pglite-pgvector\n * ```\n *\n * @example In-memory database (default, vector enabled)\n * ```typescript\n * import { createLocalPgliteBackend } from \"@nicia-ai/typegraph/postgres/pglite\";\n *\n * const { backend } = await createLocalPgliteBackend();\n * const store = createStore(graph, backend);\n * ```\n *\n * @example Persistent on-disk database\n * ```typescript\n * const { backend, db } = await createLocalPgliteBackend({ dataDir: \"./pgdata\" });\n * ```\n *\n * @example No vector support (skip the pgvector extension)\n * ```typescript\n * const { backend } = await createLocalPgliteBackend({ vector: false });\n * ```\n *\n * PGlite is single-connection and serial: there is no pooling, so concurrent\n * `store.transaction()` calls queue rather than run in parallel.\n */\nimport { type Extension, PGlite } from \"@electric-sql/pglite\";\nimport { drizzle, type PgliteDatabase } from \"drizzle-orm/pglite\";\n\nimport { ConfigurationError } from \"../../errors\";\nimport {\n  generatePostgresDDL,\n  generatePostgresMigrationSQL,\n} from \"../drizzle/ddl\";\nimport {\n  createPostgresBackend,\n  type PostgresTables,\n  tables as defaultTables,\n} from \"../drizzle/postgres\";\nimport { type GraphBackend, wrapWithManagedClose } from \"../types\";\n\n// ============================================================\n// Types\n// ============================================================\n\n/**\n * Options for creating a local PGlite backend.\n */\nexport type LocalPgliteBackendOptions = Readonly<{\n  /**\n   * PGlite data directory. Omit for an in-memory database (the default).\n   * Accepts any PGlite data-dir spec: a filesystem path (`\"./pgdata\"`),\n   * `\"memory://\"`, or a browser/runtime-specific scheme such as\n   * `\"idb://my-db\"`.\n   */\n  dataDir?: string;\n\n  /**\n   * Custom table definitions. Defaults to standard TypeGraph table names.\n   */\n  tables?: PostgresTables;\n\n  /**\n   * Controls the pgvector stack:\n   *\n   * - **omitted (default)** — load pgvector from `@electric-sql/pglite-pgvector`\n   *   and run `CREATE EXTENSION vector`, so embedding fields work out of the\n   *   box. Throws a {@link ConfigurationError} if the package isn't installed.\n   * - **`false`** — skip the extension entirely; the backend advertises no\n   *   vector capability (mirroring a SQLite connection without sqlite-vec).\n   *   Use when a graph carries no embeddings, or to avoid the extension dep.\n   * - **a PGlite `Extension`** — bring your own pgvector build or custom\n   *   extension packaging. Decouples this helper from a specific pgvector\n   *   package version.\n   */\n  vector?: false | Extension;\n}>;\n\n/**\n * Result of creating a local PGlite backend.\n */\nexport type LocalPgliteBackendResult = Readonly<{\n  /**\n   * The GraphBackend instance for use with createStore. Its `close()`\n   * disposes the underlying PGlite engine.\n   */\n  backend: GraphBackend;\n\n  /**\n   * The underlying Drizzle database instance. Useful for direct SQL access.\n   */\n  db: PgliteDatabase;\n\n  /**\n   * The raw PGlite instance, for engine-specific operations such as\n   * `dumpDataDir()` / `clone()` not surfaced through Drizzle.\n   */\n  client: PGlite;\n}>;\n\n// ============================================================\n// Vector extension loading\n// ============================================================\n\n/**\n * Dynamically loads the default pgvector extension from\n * `@electric-sql/pglite-pgvector`. Kept as a runtime import so the package\n * stays an optional peer dependency — callers using `vector: false` or\n * supplying their own extension never need it installed.\n */\nasync function loadDefaultPgvectorExtension(): Promise<Extension> {\n  try {\n    const module_ = await import(\"@electric-sql/pglite-pgvector\");\n    return module_.vector;\n  } catch (error) {\n    throw new ConfigurationError(\n      \"createLocalPgliteBackend needs the pgvector extension but \" +\n        \"`@electric-sql/pglite-pgvector` could not be loaded. Install it \" +\n        \"(`pnpm add @electric-sql/pglite-pgvector`), pass your own `vector` \" +\n        \"extension, or set `vector: false` to disable vector support.\",\n      { backend: \"pglite\", dependency: \"@electric-sql/pglite-pgvector\" },\n      { cause: error },\n    );\n  }\n}\n\n// ============================================================\n// Factory Function\n// ============================================================\n\n/**\n * Creates a TypeGraph backend backed by an in-process PGlite database.\n *\n * Constructs the PGlite engine (loading pgvector unless disabled), executes\n * the schema DDL, and wires the standard Postgres backend. The returned\n * backend owns the engine: call `backend.close()` to dispose it.\n *\n * For production Postgres, or a PGlite instance you construct yourself,\n * use `createPostgresBackend` directly with your own Drizzle database — the\n * execution fast path detects PGlite and routes it correctly.\n *\n * @param options - Configuration options\n * @returns Backend, Drizzle database, and raw PGlite client\n */\nexport async function createLocalPgliteBackend(\n  options: LocalPgliteBackendOptions = {},\n): Promise<LocalPgliteBackendResult> {\n  const tables = options.tables ?? defaultTables;\n\n  // pgvector lives in the WASM instance, so the extension must be passed at\n  // construction — `CREATE EXTENSION vector` alone can't pull it in. An\n  // explicitly supplied extension wins; `false` disables; otherwise load the\n  // default package.\n  const vectorExtension =\n    options.vector === false ?\n      undefined\n    : (options.vector ?? (await loadDefaultPgvectorExtension()));\n  const vectorEnabled = vectorExtension !== undefined;\n\n  // Construct via the single options-object form (passing `dataDir` as a\n  // field), not the positional `create(dataDir, options)` overload: with a\n  // leading `undefined` dataDir, that overload silently drops `extensions`\n  // (\"extension vector is not available\"). The options form loads them for\n  // both the in-memory and on-disk cases.\n  const client = await PGlite.create({\n    ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),\n    ...(vectorExtension === undefined ?\n      {}\n    : { extensions: { vector: vectorExtension } }),\n  });\n\n  // `exec` runs a multi-statement batch (DDL + the pgvector `CREATE\n  // EXTENSION` when enabled) in one round trip.\n  const migrationSql =\n    vectorEnabled ?\n      generatePostgresMigrationSQL(tables)\n    : generatePostgresDDL(tables).join(\"\\n\\n\");\n  await client.exec(migrationSql);\n\n  const db = drizzle(client);\n  const backend = createPostgresBackend(db, {\n    tables,\n    ...(vectorEnabled ? {} : { vector: false }),\n  });\n  const managedBackend = wrapWithManagedClose(backend, async () => {\n    await client.close();\n  });\n\n  return { backend: managedBackend, db, client };\n}\n"]}
+{"version":3,"sources":["../../../src/backend/postgres/pglite.ts"],"names":["ConfigurationError","tables","PGlite","generatePostgresMigrationSQL","generatePostgresDDL","drizzle","createPostgresBackend","wrapWithManagedClose"],"mappings":";;;;;;;;;;;;;;;;;AA2HA,eAAe,4BAAA,GAAmD;AAChE,EAAA,IAAI;AACF,IAAA,MAAM,OAAA,GAAU,MAAM,OAAO,+BAA+B,CAAA;AAC5D,IAAA,OAAO,OAAA,CAAQ,MAAA;AAAA,EACjB,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,IAAIA,oCAAA;AAAA,MACR,2PAAA;AAAA,MAIA,EAAE,OAAA,EAAS,QAAA,EAAU,UAAA,EAAY,+BAAA,EAAgC;AAAA,MACjE,EAAE,OAAO,KAAA;AAAM,KACjB;AAAA,EACF;AACF;AAoBA,eAAsB,wBAAA,CACpB,OAAA,GAAqC,EAAC,EACH;AACnC,EAAA,MAAMC,OAAAA,GAAS,QAAQ,MAAA,IAAUA,wBAAA;AAMjC,EAAA,MAAM,eAAA,GACJ,QAAQ,MAAA,KAAW,KAAA,GACjB,SACC,OAAA,CAAQ,MAAA,IAAW,MAAM,4BAAA,EAA6B;AAC3D,EAAA,MAAM,gBAAgB,eAAA,KAAoB,MAAA;AAO1C,EAAA,MAAM,MAAA,GAAS,MAAMC,aAAA,CAAO,MAAA,CAAO;AAAA,IACjC,GAAI,QAAQ,OAAA,KAAY,MAAA,GAAY,EAAC,GAAI,EAAE,OAAA,EAAS,OAAA,CAAQ,OAAA,EAAQ;AAAA,IACpE,GAAI,eAAA,KAAoB,MAAA,GACtB,EAAC,GACD,EAAE,UAAA,EAAY,EAAE,MAAA,EAAQ,eAAA,EAAgB;AAAE,GAC7C,CAAA;AAID,EAAA,MAAM,YAAA,GACJ,gBACEC,8CAAA,CAA6BF,OAAM,IACnCG,qCAAA,CAAoBH,OAAM,CAAA,CAAE,IAAA,CAAK,MAAM,CAAA;AAC3C,EAAA,MAAM,MAAA,CAAO,KAAK,YAAY,CAAA;AAE9B,EAAA,MAAM,EAAA,GAAKI,iBAAQ,MAAM,CAAA;AACzB,EAAA,MAAM,OAAA,GAAUC,wCAAsB,EAAA,EAAI;AAAA,IACxC,MAAA,EAAAL,OAAAA;AAAA,IACA,GAAI,aAAA,GAAgB,EAAC,GAAI,EAAE,QAAQ,KAAA;AAAM,GAC1C,CAAA;AACD,EAAA,MAAM,cAAA,GAAiBM,sCAAA,CAAqB,OAAA,EAAS,YAAY;AAC/D,IAAA,MAAM,OAAO,KAAA,EAAM;AAAA,EACrB,CAAC,CAAA;AAED,EAAA,OAAO,EAAE,OAAA,EAAS,cAAA,EAAgB,EAAA,EAAI,MAAA,EAAO;AAC/C","file":"pglite.cjs","sourcesContent":["/**\n * Local PGlite backend — Postgres-in-WASM, running in-process.\n *\n * [PGlite](https://pglite.dev/) is a full Postgres compiled to WebAssembly\n * that runs inside the Node/Bun/Deno/browser process with no server and no\n * native addon. This is the batteries-included Postgres analog of\n * `createLocalSqliteBackend`: it constructs a PGlite instance, loads the\n * pgvector extension, runs the schema DDL, and returns a ready\n * `{ backend, db }` pair whose `close()` disposes the engine.\n *\n * `@electric-sql/pglite` is an optional peer dependency. Vector support\n * additionally needs `@electric-sql/pglite-pgvector` (PGlite ≥ 0.5 ships\n * pgvector as a separate package). Install what you need:\n *\n * ```bash\n * pnpm add @electric-sql/pglite @electric-sql/pglite-pgvector\n * ```\n *\n * @example In-memory database (default, vector enabled)\n * ```typescript\n * import { createLocalPgliteBackend } from \"@nicia-ai/typegraph/postgres/pglite\";\n *\n * const { backend } = await createLocalPgliteBackend();\n * const store = createStore(graph, backend);\n * ```\n *\n * @example Persistent on-disk database\n * ```typescript\n * const { backend, db } = await createLocalPgliteBackend({ dataDir: \"./pgdata\" });\n * ```\n *\n * @example No vector support (skip the pgvector extension)\n * ```typescript\n * const { backend } = await createLocalPgliteBackend({ vector: false });\n * ```\n *\n * PGlite is single-connection and serial: there is no pooling, so concurrent\n * `store.transaction()` calls queue rather than run in parallel.\n */\nimport { type Extension, PGlite } from \"@electric-sql/pglite\";\nimport { drizzle, type PgliteDatabase } from \"drizzle-orm/pglite\";\n\nimport { ConfigurationError } from \"../../errors\";\nimport {\n  generatePostgresDDL,\n  generatePostgresMigrationSQL,\n} from \"../drizzle/ddl\";\nimport {\n  createPostgresBackend,\n  type PostgresTables,\n  tables as defaultTables,\n} from \"../drizzle/postgres\";\nimport { type GraphBackend, wrapWithManagedClose } from \"../types\";\n\n// ============================================================\n// Types\n// ============================================================\n\n/**\n * Options for creating a local PGlite backend.\n */\nexport type LocalPgliteBackendOptions = Readonly<{\n  /**\n   * PGlite data directory. Omit for an in-memory database (the default).\n   * Accepts any PGlite data-dir spec: a filesystem path (`\"./pgdata\"`),\n   * `\"memory://\"`, or a browser/runtime-specific scheme such as\n   * `\"idb://my-db\"`.\n   */\n  dataDir?: string;\n\n  /**\n   * Custom table definitions. Defaults to standard TypeGraph table names.\n   */\n  tables?: PostgresTables;\n\n  /**\n   * Controls the pgvector stack:\n   *\n   * - **omitted (default)** — load pgvector from `@electric-sql/pglite-pgvector`\n   *   and run `CREATE EXTENSION vector`, so embedding fields work out of the\n   *   box. Throws a {@link ConfigurationError} if the package isn't installed.\n   * - **`false`** — skip the extension entirely; the backend advertises no\n   *   vector capability (mirroring a SQLite connection without sqlite-vec).\n   *   Use when a graph carries no embeddings, or to avoid the extension dep.\n   * - **a PGlite `Extension`** — bring your own pgvector build or custom\n   *   extension packaging. Decouples this helper from a specific pgvector\n   *   package version.\n   */\n  vector?: false | Extension;\n}>;\n\n/**\n * Result of creating a local PGlite backend.\n */\nexport type LocalPgliteBackendResult = Readonly<{\n  /**\n   * The GraphBackend instance for use with createStore. Its `close()`\n   * disposes the underlying PGlite engine.\n   */\n  backend: GraphBackend;\n\n  /**\n   * The underlying Drizzle database instance. Useful for direct SQL access.\n   */\n  db: PgliteDatabase;\n\n  /**\n   * The raw PGlite instance, for engine-specific operations such as\n   * `dumpDataDir()` / `clone()` not surfaced through Drizzle.\n   */\n  client: PGlite;\n}>;\n\n// ============================================================\n// Vector extension loading\n// ============================================================\n\n/**\n * Dynamically loads the default pgvector extension from\n * `@electric-sql/pglite-pgvector`. Kept as a runtime import so the package\n * stays an optional peer dependency — callers using `vector: false` or\n * supplying their own extension never need it installed.\n */\nasync function loadDefaultPgvectorExtension(): Promise<Extension> {\n  try {\n    const module_ = await import(\"@electric-sql/pglite-pgvector\");\n    return module_.vector;\n  } catch (error) {\n    throw new ConfigurationError(\n      \"createLocalPgliteBackend needs the pgvector extension but \" +\n        \"`@electric-sql/pglite-pgvector` could not be loaded. Install it \" +\n        \"(`pnpm add @electric-sql/pglite-pgvector`), pass your own `vector` \" +\n        \"extension, or set `vector: false` to disable vector support.\",\n      { backend: \"pglite\", dependency: \"@electric-sql/pglite-pgvector\" },\n      { cause: error },\n    );\n  }\n}\n\n// ============================================================\n// Factory Function\n// ============================================================\n\n/**\n * Creates a TypeGraph backend backed by an in-process PGlite database.\n *\n * Constructs the PGlite engine (loading pgvector unless disabled), executes\n * the schema DDL, and wires the standard Postgres backend. The returned\n * backend owns the engine: call `backend.close()` to dispose it.\n *\n * For production Postgres, or a PGlite instance you construct yourself,\n * use `createPostgresBackend` directly with your own Drizzle database — the\n * execution fast path detects PGlite and routes it correctly.\n *\n * @param options - Configuration options\n * @returns Backend, Drizzle database, and raw PGlite client\n */\nexport async function createLocalPgliteBackend(\n  options: LocalPgliteBackendOptions = {},\n): Promise<LocalPgliteBackendResult> {\n  const tables = options.tables ?? defaultTables;\n\n  // pgvector lives in the WASM instance, so the extension must be passed at\n  // construction — `CREATE EXTENSION vector` alone can't pull it in. An\n  // explicitly supplied extension wins; `false` disables; otherwise load the\n  // default package.\n  const vectorExtension =\n    options.vector === false ?\n      undefined\n    : (options.vector ?? (await loadDefaultPgvectorExtension()));\n  const vectorEnabled = vectorExtension !== undefined;\n\n  // Construct via the single options-object form (passing `dataDir` as a\n  // field), not the positional `create(dataDir, options)` overload: with a\n  // leading `undefined` dataDir, that overload silently drops `extensions`\n  // (\"extension vector is not available\"). The options form loads them for\n  // both the in-memory and on-disk cases.\n  const client = await PGlite.create({\n    ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),\n    ...(vectorExtension === undefined ?\n      {}\n    : { extensions: { vector: vectorExtension } }),\n  });\n\n  // `exec` runs a multi-statement batch (DDL + the pgvector `CREATE\n  // EXTENSION` when enabled) in one round trip.\n  const migrationSql =\n    vectorEnabled ?\n      generatePostgresMigrationSQL(tables)\n    : generatePostgresDDL(tables).join(\"\\n\\n\");\n  await client.exec(migrationSql);\n\n  const db = drizzle(client);\n  const backend = createPostgresBackend(db, {\n    tables,\n    ...(vectorEnabled ? {} : { vector: false }),\n  });\n  const managedBackend = wrapWithManagedClose(backend, async () => {\n    await client.close();\n  });\n\n  return { backend: managedBackend, db, client };\n}\n"]}

package/dist/backend/postgres/pglite.d.cts

@@ -1,9 +1,9 @@
 import { Extension, PGlite } from '@electric-sql/pglite';
 import { PgliteDatabase } from 'drizzle-orm/pglite';
-import { G as GraphBackend } from '../../types-DXCSyxac.cjs';
-import { P as PostgresTables } from '../../postgres-CQL9UIn2.cjs';
+import { G as GraphBackend } from '../../types-C1CYxWrL.cjs';
+import { P as PostgresTables } from '../../postgres-4J2tmauh.cjs';
 import 'zod';
-import '../../extension-types-CwHV-Uk4.cjs';
+import '../../extension-types-D1k0inWU.cjs';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm/sqlite-core';

package/dist/backend/postgres/pglite.d.ts

@@ -1,9 +1,9 @@
 import { Extension, PGlite } from '@electric-sql/pglite';
 import { PgliteDatabase } from 'drizzle-orm/pglite';
-import { G as GraphBackend } from '../../types-CmAT-Z47.js';
-import { P as PostgresTables } from '../../postgres-CcRLaxz0.js';
+import { G as GraphBackend } from '../../types-BKQljXom.js';
+import { P as PostgresTables } from '../../postgres-BdIb7tS_.js';
 import 'zod';
-import '../../extension-types-CwHV-Uk4.js';
+import '../../extension-types-D1k0inWU.js';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm/sqlite-core';

package/dist/backend/postgres/pglite.js

@@ -1,14 +1,15 @@
-import { createPostgresBackend } from '../../chunk-Y52UNT66.js';
-import '../../chunk-IE2TPFBT.js';
-import { tables, generatePostgresMigrationSQL, generatePostgresDDL } from '../../chunk-3DTLDGIM.js';
-import { wrapWithManagedClose } from '../../chunk-HKN622O4.js';
+import { createPostgresBackend } from '../../chunk-STP7QVUB.js';
+import '../../chunk-ATTXBMAX.js';
+import '../../chunk-3EUKJEQ3.js';
+import { tables, generatePostgresMigrationSQL, generatePostgresDDL } from '../../chunk-VZX2KSY3.js';
+import '../../chunk-GKFWM3DS.js';
+import '../../chunk-LJLMDDCW.js';
+import { wrapWithManagedClose } from '../../chunk-SAJSMR2B.js';
 import '../../chunk-M6OC455F.js';
-import '../../chunk-7KLVFWXR.js';
-import '../../chunk-OGUH56BB.js';
-import '../../chunk-N3VVQDMA.js';
-import '../../chunk-454I6GDF.js';
-import { ConfigurationError } from '../../chunk-MB363HT5.js';
-import '../../chunk-NZ5PMBTG.js';
+import '../../chunk-2HZGWCB4.js';
+import '../../chunk-2YMGNYXY.js';
+import { ConfigurationError } from '../../chunk-TQOYM4LN.js';
+import '../../chunk-K5P5OZXS.js';
 import { PGlite } from '@electric-sql/pglite';
 import { drizzle } from 'drizzle-orm/pglite';
 

package/dist/backend/postgres/pglite.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/backend/postgres/pglite.ts"],"names":["tables"],"mappings":";;;;;;;;;;;;;;AA2HA,eAAe,4BAAA,GAAmD;AAChE,EAAA,IAAI;AACF,IAAA,MAAM,OAAA,GAAU,MAAM,OAAO,+BAA+B,CAAA;AAC5D,IAAA,OAAO,OAAA,CAAQ,MAAA;AAAA,EACjB,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR,2PAAA;AAAA,MAIA,EAAE,OAAA,EAAS,QAAA,EAAU,UAAA,EAAY,+BAAA,EAAgC;AAAA,MACjE,EAAE,OAAO,KAAA;AAAM,KACjB;AAAA,EACF;AACF;AAoBA,eAAsB,wBAAA,CACpB,OAAA,GAAqC,EAAC,EACH;AACnC,EAAA,MAAMA,OAAAA,GAAS,QAAQ,MAAA,IAAU,MAAA;AAMjC,EAAA,MAAM,eAAA,GACJ,QAAQ,MAAA,KAAW,KAAA,GACjB,SACC,OAAA,CAAQ,MAAA,IAAW,MAAM,4BAAA,EAA6B;AAC3D,EAAA,MAAM,gBAAgB,eAAA,KAAoB,MAAA;AAO1C,EAAA,MAAM,MAAA,GAAS,MAAM,MAAA,CAAO,MAAA,CAAO;AAAA,IACjC,GAAI,QAAQ,OAAA,KAAY,MAAA,GAAY,EAAC,GAAI,EAAE,OAAA,EAAS,OAAA,CAAQ,OAAA,EAAQ;AAAA,IACpE,GAAI,eAAA,KAAoB,MAAA,GACtB,EAAC,GACD,EAAE,UAAA,EAAY,EAAE,MAAA,EAAQ,eAAA,EAAgB;AAAE,GAC7C,CAAA;AAID,EAAA,MAAM,YAAA,GACJ,gBACE,4BAAA,CAA6BA,OAAM,IACnC,mBAAA,CAAoBA,OAAM,CAAA,CAAE,IAAA,CAAK,MAAM,CAAA;AAC3C,EAAA,MAAM,MAAA,CAAO,KAAK,YAAY,CAAA;AAE9B,EAAA,MAAM,EAAA,GAAK,QAAQ,MAAM,CAAA;AACzB,EAAA,MAAM,OAAA,GAAU,sBAAsB,EAAA,EAAI;AAAA,IACxC,MAAA,EAAAA,OAAAA;AAAA,IACA,GAAI,aAAA,GAAgB,EAAC,GAAI,EAAE,QAAQ,KAAA;AAAM,GAC1C,CAAA;AACD,EAAA,MAAM,cAAA,GAAiB,oBAAA,CAAqB,OAAA,EAAS,YAAY;AAC/D,IAAA,MAAM,OAAO,KAAA,EAAM;AAAA,EACrB,CAAC,CAAA;AAED,EAAA,OAAO,EAAE,OAAA,EAAS,cAAA,EAAgB,EAAA,EAAI,MAAA,EAAO;AAC/C","file":"pglite.js","sourcesContent":["/**\n * Local PGlite backend — Postgres-in-WASM, running in-process.\n *\n * [PGlite](https://pglite.dev/) is a full Postgres compiled to WebAssembly\n * that runs inside the Node/Bun/Deno/browser process with no server and no\n * native addon. This is the batteries-included Postgres analog of\n * `createLocalSqliteBackend`: it constructs a PGlite instance, loads the\n * pgvector extension, runs the schema DDL, and returns a ready\n * `{ backend, db }` pair whose `close()` disposes the engine.\n *\n * `@electric-sql/pglite` is an optional peer dependency. Vector support\n * additionally needs `@electric-sql/pglite-pgvector` (PGlite ≥ 0.5 ships\n * pgvector as a separate package). Install what you need:\n *\n * ```bash\n * pnpm add @electric-sql/pglite @electric-sql/pglite-pgvector\n * ```\n *\n * @example In-memory database (default, vector enabled)\n * ```typescript\n * import { createLocalPgliteBackend } from \"@nicia-ai/typegraph/postgres/pglite\";\n *\n * const { backend } = await createLocalPgliteBackend();\n * const store = createStore(graph, backend);\n * ```\n *\n * @example Persistent on-disk database\n * ```typescript\n * const { backend, db } = await createLocalPgliteBackend({ dataDir: \"./pgdata\" });\n * ```\n *\n * @example No vector support (skip the pgvector extension)\n * ```typescript\n * const { backend } = await createLocalPgliteBackend({ vector: false });\n * ```\n *\n * PGlite is single-connection and serial: there is no pooling, so concurrent\n * `store.transaction()` calls queue rather than run in parallel.\n */\nimport { type Extension, PGlite } from \"@electric-sql/pglite\";\nimport { drizzle, type PgliteDatabase } from \"drizzle-orm/pglite\";\n\nimport { ConfigurationError } from \"../../errors\";\nimport {\n  generatePostgresDDL,\n  generatePostgresMigrationSQL,\n} from \"../drizzle/ddl\";\nimport {\n  createPostgresBackend,\n  type PostgresTables,\n  tables as defaultTables,\n} from \"../drizzle/postgres\";\nimport { type GraphBackend, wrapWithManagedClose } from \"../types\";\n\n// ============================================================\n// Types\n// ============================================================\n\n/**\n * Options for creating a local PGlite backend.\n */\nexport type LocalPgliteBackendOptions = Readonly<{\n  /**\n   * PGlite data directory. Omit for an in-memory database (the default).\n   * Accepts any PGlite data-dir spec: a filesystem path (`\"./pgdata\"`),\n   * `\"memory://\"`, or a browser/runtime-specific scheme such as\n   * `\"idb://my-db\"`.\n   */\n  dataDir?: string;\n\n  /**\n   * Custom table definitions. Defaults to standard TypeGraph table names.\n   */\n  tables?: PostgresTables;\n\n  /**\n   * Controls the pgvector stack:\n   *\n   * - **omitted (default)** — load pgvector from `@electric-sql/pglite-pgvector`\n   *   and run `CREATE EXTENSION vector`, so embedding fields work out of the\n   *   box. Throws a {@link ConfigurationError} if the package isn't installed.\n   * - **`false`** — skip the extension entirely; the backend advertises no\n   *   vector capability (mirroring a SQLite connection without sqlite-vec).\n   *   Use when a graph carries no embeddings, or to avoid the extension dep.\n   * - **a PGlite `Extension`** — bring your own pgvector build or custom\n   *   extension packaging. Decouples this helper from a specific pgvector\n   *   package version.\n   */\n  vector?: false | Extension;\n}>;\n\n/**\n * Result of creating a local PGlite backend.\n */\nexport type LocalPgliteBackendResult = Readonly<{\n  /**\n   * The GraphBackend instance for use with createStore. Its `close()`\n   * disposes the underlying PGlite engine.\n   */\n  backend: GraphBackend;\n\n  /**\n   * The underlying Drizzle database instance. Useful for direct SQL access.\n   */\n  db: PgliteDatabase;\n\n  /**\n   * The raw PGlite instance, for engine-specific operations such as\n   * `dumpDataDir()` / `clone()` not surfaced through Drizzle.\n   */\n  client: PGlite;\n}>;\n\n// ============================================================\n// Vector extension loading\n// ============================================================\n\n/**\n * Dynamically loads the default pgvector extension from\n * `@electric-sql/pglite-pgvector`. Kept as a runtime import so the package\n * stays an optional peer dependency — callers using `vector: false` or\n * supplying their own extension never need it installed.\n */\nasync function loadDefaultPgvectorExtension(): Promise<Extension> {\n  try {\n    const module_ = await import(\"@electric-sql/pglite-pgvector\");\n    return module_.vector;\n  } catch (error) {\n    throw new ConfigurationError(\n      \"createLocalPgliteBackend needs the pgvector extension but \" +\n        \"`@electric-sql/pglite-pgvector` could not be loaded. Install it \" +\n        \"(`pnpm add @electric-sql/pglite-pgvector`), pass your own `vector` \" +\n        \"extension, or set `vector: false` to disable vector support.\",\n      { backend: \"pglite\", dependency: \"@electric-sql/pglite-pgvector\" },\n      { cause: error },\n    );\n  }\n}\n\n// ============================================================\n// Factory Function\n// ============================================================\n\n/**\n * Creates a TypeGraph backend backed by an in-process PGlite database.\n *\n * Constructs the PGlite engine (loading pgvector unless disabled), executes\n * the schema DDL, and wires the standard Postgres backend. The returned\n * backend owns the engine: call `backend.close()` to dispose it.\n *\n * For production Postgres, or a PGlite instance you construct yourself,\n * use `createPostgresBackend` directly with your own Drizzle database — the\n * execution fast path detects PGlite and routes it correctly.\n *\n * @param options - Configuration options\n * @returns Backend, Drizzle database, and raw PGlite client\n */\nexport async function createLocalPgliteBackend(\n  options: LocalPgliteBackendOptions = {},\n): Promise<LocalPgliteBackendResult> {\n  const tables = options.tables ?? defaultTables;\n\n  // pgvector lives in the WASM instance, so the extension must be passed at\n  // construction — `CREATE EXTENSION vector` alone can't pull it in. An\n  // explicitly supplied extension wins; `false` disables; otherwise load the\n  // default package.\n  const vectorExtension =\n    options.vector === false ?\n      undefined\n    : (options.vector ?? (await loadDefaultPgvectorExtension()));\n  const vectorEnabled = vectorExtension !== undefined;\n\n  // Construct via the single options-object form (passing `dataDir` as a\n  // field), not the positional `create(dataDir, options)` overload: with a\n  // leading `undefined` dataDir, that overload silently drops `extensions`\n  // (\"extension vector is not available\"). The options form loads them for\n  // both the in-memory and on-disk cases.\n  const client = await PGlite.create({\n    ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),\n    ...(vectorExtension === undefined ?\n      {}\n    : { extensions: { vector: vectorExtension } }),\n  });\n\n  // `exec` runs a multi-statement batch (DDL + the pgvector `CREATE\n  // EXTENSION` when enabled) in one round trip.\n  const migrationSql =\n    vectorEnabled ?\n      generatePostgresMigrationSQL(tables)\n    : generatePostgresDDL(tables).join(\"\\n\\n\");\n  await client.exec(migrationSql);\n\n  const db = drizzle(client);\n  const backend = createPostgresBackend(db, {\n    tables,\n    ...(vectorEnabled ? {} : { vector: false }),\n  });\n  const managedBackend = wrapWithManagedClose(backend, async () => {\n    await client.close();\n  });\n\n  return { backend: managedBackend, db, client };\n}\n"]}
+{"version":3,"sources":["../../../src/backend/postgres/pglite.ts"],"names":["tables"],"mappings":";;;;;;;;;;;;;;;AA2HA,eAAe,4BAAA,GAAmD;AAChE,EAAA,IAAI;AACF,IAAA,MAAM,OAAA,GAAU,MAAM,OAAO,+BAA+B,CAAA;AAC5D,IAAA,OAAO,OAAA,CAAQ,MAAA;AAAA,EACjB,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR,2PAAA;AAAA,MAIA,EAAE,OAAA,EAAS,QAAA,EAAU,UAAA,EAAY,+BAAA,EAAgC;AAAA,MACjE,EAAE,OAAO,KAAA;AAAM,KACjB;AAAA,EACF;AACF;AAoBA,eAAsB,wBAAA,CACpB,OAAA,GAAqC,EAAC,EACH;AACnC,EAAA,MAAMA,OAAAA,GAAS,QAAQ,MAAA,IAAU,MAAA;AAMjC,EAAA,MAAM,eAAA,GACJ,QAAQ,MAAA,KAAW,KAAA,GACjB,SACC,OAAA,CAAQ,MAAA,IAAW,MAAM,4BAAA,EAA6B;AAC3D,EAAA,MAAM,gBAAgB,eAAA,KAAoB,MAAA;AAO1C,EAAA,MAAM,MAAA,GAAS,MAAM,MAAA,CAAO,MAAA,CAAO;AAAA,IACjC,GAAI,QAAQ,OAAA,KAAY,MAAA,GAAY,EAAC,GAAI,EAAE,OAAA,EAAS,OAAA,CAAQ,OAAA,EAAQ;AAAA,IACpE,GAAI,eAAA,KAAoB,MAAA,GACtB,EAAC,GACD,EAAE,UAAA,EAAY,EAAE,MAAA,EAAQ,eAAA,EAAgB;AAAE,GAC7C,CAAA;AAID,EAAA,MAAM,YAAA,GACJ,gBACE,4BAAA,CAA6BA,OAAM,IACnC,mBAAA,CAAoBA,OAAM,CAAA,CAAE,IAAA,CAAK,MAAM,CAAA;AAC3C,EAAA,MAAM,MAAA,CAAO,KAAK,YAAY,CAAA;AAE9B,EAAA,MAAM,EAAA,GAAK,QAAQ,MAAM,CAAA;AACzB,EAAA,MAAM,OAAA,GAAU,sBAAsB,EAAA,EAAI;AAAA,IACxC,MAAA,EAAAA,OAAAA;AAAA,IACA,GAAI,aAAA,GAAgB,EAAC,GAAI,EAAE,QAAQ,KAAA;AAAM,GAC1C,CAAA;AACD,EAAA,MAAM,cAAA,GAAiB,oBAAA,CAAqB,OAAA,EAAS,YAAY;AAC/D,IAAA,MAAM,OAAO,KAAA,EAAM;AAAA,EACrB,CAAC,CAAA;AAED,EAAA,OAAO,EAAE,OAAA,EAAS,cAAA,EAAgB,EAAA,EAAI,MAAA,EAAO;AAC/C","file":"pglite.js","sourcesContent":["/**\n * Local PGlite backend — Postgres-in-WASM, running in-process.\n *\n * [PGlite](https://pglite.dev/) is a full Postgres compiled to WebAssembly\n * that runs inside the Node/Bun/Deno/browser process with no server and no\n * native addon. This is the batteries-included Postgres analog of\n * `createLocalSqliteBackend`: it constructs a PGlite instance, loads the\n * pgvector extension, runs the schema DDL, and returns a ready\n * `{ backend, db }` pair whose `close()` disposes the engine.\n *\n * `@electric-sql/pglite` is an optional peer dependency. Vector support\n * additionally needs `@electric-sql/pglite-pgvector` (PGlite ≥ 0.5 ships\n * pgvector as a separate package). Install what you need:\n *\n * ```bash\n * pnpm add @electric-sql/pglite @electric-sql/pglite-pgvector\n * ```\n *\n * @example In-memory database (default, vector enabled)\n * ```typescript\n * import { createLocalPgliteBackend } from \"@nicia-ai/typegraph/postgres/pglite\";\n *\n * const { backend } = await createLocalPgliteBackend();\n * const store = createStore(graph, backend);\n * ```\n *\n * @example Persistent on-disk database\n * ```typescript\n * const { backend, db } = await createLocalPgliteBackend({ dataDir: \"./pgdata\" });\n * ```\n *\n * @example No vector support (skip the pgvector extension)\n * ```typescript\n * const { backend } = await createLocalPgliteBackend({ vector: false });\n * ```\n *\n * PGlite is single-connection and serial: there is no pooling, so concurrent\n * `store.transaction()` calls queue rather than run in parallel.\n */\nimport { type Extension, PGlite } from \"@electric-sql/pglite\";\nimport { drizzle, type PgliteDatabase } from \"drizzle-orm/pglite\";\n\nimport { ConfigurationError } from \"../../errors\";\nimport {\n  generatePostgresDDL,\n  generatePostgresMigrationSQL,\n} from \"../drizzle/ddl\";\nimport {\n  createPostgresBackend,\n  type PostgresTables,\n  tables as defaultTables,\n} from \"../drizzle/postgres\";\nimport { type GraphBackend, wrapWithManagedClose } from \"../types\";\n\n// ============================================================\n// Types\n// ============================================================\n\n/**\n * Options for creating a local PGlite backend.\n */\nexport type LocalPgliteBackendOptions = Readonly<{\n  /**\n   * PGlite data directory. Omit for an in-memory database (the default).\n   * Accepts any PGlite data-dir spec: a filesystem path (`\"./pgdata\"`),\n   * `\"memory://\"`, or a browser/runtime-specific scheme such as\n   * `\"idb://my-db\"`.\n   */\n  dataDir?: string;\n\n  /**\n   * Custom table definitions. Defaults to standard TypeGraph table names.\n   */\n  tables?: PostgresTables;\n\n  /**\n   * Controls the pgvector stack:\n   *\n   * - **omitted (default)** — load pgvector from `@electric-sql/pglite-pgvector`\n   *   and run `CREATE EXTENSION vector`, so embedding fields work out of the\n   *   box. Throws a {@link ConfigurationError} if the package isn't installed.\n   * - **`false`** — skip the extension entirely; the backend advertises no\n   *   vector capability (mirroring a SQLite connection without sqlite-vec).\n   *   Use when a graph carries no embeddings, or to avoid the extension dep.\n   * - **a PGlite `Extension`** — bring your own pgvector build or custom\n   *   extension packaging. Decouples this helper from a specific pgvector\n   *   package version.\n   */\n  vector?: false | Extension;\n}>;\n\n/**\n * Result of creating a local PGlite backend.\n */\nexport type LocalPgliteBackendResult = Readonly<{\n  /**\n   * The GraphBackend instance for use with createStore. Its `close()`\n   * disposes the underlying PGlite engine.\n   */\n  backend: GraphBackend;\n\n  /**\n   * The underlying Drizzle database instance. Useful for direct SQL access.\n   */\n  db: PgliteDatabase;\n\n  /**\n   * The raw PGlite instance, for engine-specific operations such as\n   * `dumpDataDir()` / `clone()` not surfaced through Drizzle.\n   */\n  client: PGlite;\n}>;\n\n// ============================================================\n// Vector extension loading\n// ============================================================\n\n/**\n * Dynamically loads the default pgvector extension from\n * `@electric-sql/pglite-pgvector`. Kept as a runtime import so the package\n * stays an optional peer dependency — callers using `vector: false` or\n * supplying their own extension never need it installed.\n */\nasync function loadDefaultPgvectorExtension(): Promise<Extension> {\n  try {\n    const module_ = await import(\"@electric-sql/pglite-pgvector\");\n    return module_.vector;\n  } catch (error) {\n    throw new ConfigurationError(\n      \"createLocalPgliteBackend needs the pgvector extension but \" +\n        \"`@electric-sql/pglite-pgvector` could not be loaded. Install it \" +\n        \"(`pnpm add @electric-sql/pglite-pgvector`), pass your own `vector` \" +\n        \"extension, or set `vector: false` to disable vector support.\",\n      { backend: \"pglite\", dependency: \"@electric-sql/pglite-pgvector\" },\n      { cause: error },\n    );\n  }\n}\n\n// ============================================================\n// Factory Function\n// ============================================================\n\n/**\n * Creates a TypeGraph backend backed by an in-process PGlite database.\n *\n * Constructs the PGlite engine (loading pgvector unless disabled), executes\n * the schema DDL, and wires the standard Postgres backend. The returned\n * backend owns the engine: call `backend.close()` to dispose it.\n *\n * For production Postgres, or a PGlite instance you construct yourself,\n * use `createPostgresBackend` directly with your own Drizzle database — the\n * execution fast path detects PGlite and routes it correctly.\n *\n * @param options - Configuration options\n * @returns Backend, Drizzle database, and raw PGlite client\n */\nexport async function createLocalPgliteBackend(\n  options: LocalPgliteBackendOptions = {},\n): Promise<LocalPgliteBackendResult> {\n  const tables = options.tables ?? defaultTables;\n\n  // pgvector lives in the WASM instance, so the extension must be passed at\n  // construction — `CREATE EXTENSION vector` alone can't pull it in. An\n  // explicitly supplied extension wins; `false` disables; otherwise load the\n  // default package.\n  const vectorExtension =\n    options.vector === false ?\n      undefined\n    : (options.vector ?? (await loadDefaultPgvectorExtension()));\n  const vectorEnabled = vectorExtension !== undefined;\n\n  // Construct via the single options-object form (passing `dataDir` as a\n  // field), not the positional `create(dataDir, options)` overload: with a\n  // leading `undefined` dataDir, that overload silently drops `extensions`\n  // (\"extension vector is not available\"). The options form loads them for\n  // both the in-memory and on-disk cases.\n  const client = await PGlite.create({\n    ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),\n    ...(vectorExtension === undefined ?\n      {}\n    : { extensions: { vector: vectorExtension } }),\n  });\n\n  // `exec` runs a multi-statement batch (DDL + the pgvector `CREATE\n  // EXTENSION` when enabled) in one round trip.\n  const migrationSql =\n    vectorEnabled ?\n      generatePostgresMigrationSQL(tables)\n    : generatePostgresDDL(tables).join(\"\\n\\n\");\n  await client.exec(migrationSql);\n\n  const db = drizzle(client);\n  const backend = createPostgresBackend(db, {\n    tables,\n    ...(vectorEnabled ? {} : { vector: false }),\n  });\n  const managedBackend = wrapWithManagedClose(backend, async () => {\n    await client.close();\n  });\n\n  return { backend: managedBackend, db, client };\n}\n"]}

package/dist/backend/sqlite/index.cjs

@@ -1,53 +1,53 @@
 'use strict';
 
-var chunkRU5BBUU2_cjs = require('../../chunk-RU5BBUU2.cjs');
-var chunkZYQEXGYC_cjs = require('../../chunk-ZYQEXGYC.cjs');
-var chunkF2Q76CQ4_cjs = require('../../chunk-F2Q76CQ4.cjs');
+var chunkSFFJ2IKN_cjs = require('../../chunk-SFFJ2IKN.cjs');
+var chunkCIINW6PS_cjs = require('../../chunk-CIINW6PS.cjs');
+var chunk54JVNOAQ_cjs = require('../../chunk-54JVNOAQ.cjs');
+require('../../chunk-VMEWZU2N.cjs');
+require('../../chunk-6G35I3VW.cjs');
 require('../../chunk-RP7YITHX.cjs');
-require('../../chunk-C2RWFIYP.cjs');
-require('../../chunk-UPBXUOW7.cjs');
-require('../../chunk-VGU26WIU.cjs');
-require('../../chunk-ZFWNO3GE.cjs');
-require('../../chunk-G6P3OVDY.cjs');
-require('../../chunk-7V335GHG.cjs');
+require('../../chunk-V4IQYOQ4.cjs');
+require('../../chunk-73KASJGO.cjs');
+require('../../chunk-JIEJCTDS.cjs');
+require('../../chunk-FLRCVI2G.cjs');
 
 
 
 Object.defineProperty(exports, "createSqliteBackend", {
   enumerable: true,
-  get: function () { return chunkRU5BBUU2_cjs.createSqliteBackend; }
+  get: function () { return chunkSFFJ2IKN_cjs.createSqliteBackend; }
 });
 Object.defineProperty(exports, "generateSqliteDDL", {
   enumerable: true,
-  get: function () { return chunkZYQEXGYC_cjs.generateSqliteDDL; }
+  get: function () { return chunkCIINW6PS_cjs.generateSqliteDDL; }
 });
 Object.defineProperty(exports, "generateSqliteMigrationSQL", {
   enumerable: true,
-  get: function () { return chunkZYQEXGYC_cjs.generateSqliteMigrationSQL; }
+  get: function () { return chunkCIINW6PS_cjs.generateSqliteMigrationSQL; }
 });
 Object.defineProperty(exports, "createSqliteTables", {
   enumerable: true,
-  get: function () { return chunkF2Q76CQ4_cjs.createSqliteTables; }
+  get: function () { return chunk54JVNOAQ_cjs.createSqliteTables; }
 });
 Object.defineProperty(exports, "edges", {
   enumerable: true,
-  get: function () { return chunkF2Q76CQ4_cjs.edges; }
+  get: function () { return chunk54JVNOAQ_cjs.edges; }
 });
 Object.defineProperty(exports, "nodes", {
   enumerable: true,
-  get: function () { return chunkF2Q76CQ4_cjs.nodes; }
+  get: function () { return chunk54JVNOAQ_cjs.nodes; }
 });
 Object.defineProperty(exports, "schemaVersions", {
   enumerable: true,
-  get: function () { return chunkF2Q76CQ4_cjs.schemaVersions; }
+  get: function () { return chunk54JVNOAQ_cjs.schemaVersions; }
 });
 Object.defineProperty(exports, "tables", {
   enumerable: true,
-  get: function () { return chunkF2Q76CQ4_cjs.tables; }
+  get: function () { return chunk54JVNOAQ_cjs.tables; }
 });
 Object.defineProperty(exports, "uniques", {
   enumerable: true,
-  get: function () { return chunkF2Q76CQ4_cjs.uniques; }
+  get: function () { return chunk54JVNOAQ_cjs.uniques; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/backend/sqlite/index.d.cts

@@ -1,14 +1,14 @@
-import { S as SqliteExecutionProfileHints, F as FulltextStrategy, V as VectorStrategy, A as AnySqliteDatabase, G as GraphBackend } from '../../types-DXCSyxac.cjs';
-export { a as SqliteTransactionMode } from '../../types-DXCSyxac.cjs';
-import { S as SqliteTables } from '../../sqlite-Rj3xu4It.cjs';
-export { C as CreateSqliteTablesOptions, a as SqliteTableNames, c as createSqliteTables, e as edges, n as nodes, s as schemaVersions, t as tables, u as uniques } from '../../sqlite-Rj3xu4It.cjs';
-export { g as generateSqliteDDL, a as generateSqliteMigrationSQL } from '../../ddl-D3o-RmsV.cjs';
+import { S as SqliteExecutionProfileHints, F as FulltextStrategy, V as VectorStrategy, B as BackendCapabilities, A as AnySqliteDatabase, G as GraphBackend } from '../../types-C1CYxWrL.cjs';
+export { a as SqliteTransactionMode } from '../../types-C1CYxWrL.cjs';
+import { S as SqliteTables } from '../../sqlite-Gatk_iw_.cjs';
+export { C as CreateSqliteTablesOptions, a as SqliteTableNames, c as createSqliteTables, e as edges, n as nodes, s as schemaVersions, t as tables, u as uniques } from '../../sqlite-Gatk_iw_.cjs';
+export { g as generateSqliteDDL, a as generateSqliteMigrationSQL } from '../../ddl-CPZ7mB7X.cjs';
 import 'zod';
-import '../../extension-types-CwHV-Uk4.cjs';
+import '../../extension-types-D1k0inWU.cjs';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm/sqlite-core';
-import '../../postgres-CQL9UIn2.cjs';
+import '../../postgres-4J2tmauh.cjs';
 
 /**
  * Options for creating a SQLite backend.
@@ -43,6 +43,11 @@ type SqliteBackendOptions = Readonly<{
      * connections without a vector extension.
      */
     vector?: VectorStrategy;
+    /**
+     * Override specific backend capabilities. Useful for custom SQLite builds
+     * or tests that need to simulate an engine-level capability gap.
+     */
+    capabilities?: Partial<BackendCapabilities>;
 }>;
 declare function createSqliteBackend(db: AnySqliteDatabase, options?: SqliteBackendOptions): GraphBackend;
 

package/dist/backend/sqlite/index.d.ts

@@ -1,14 +1,14 @@
-import { S as SqliteExecutionProfileHints, F as FulltextStrategy, V as VectorStrategy, A as AnySqliteDatabase, G as GraphBackend } from '../../types-CmAT-Z47.js';
-export { a as SqliteTransactionMode } from '../../types-CmAT-Z47.js';
-import { S as SqliteTables } from '../../sqlite-CZDFUfHS.js';
-export { C as CreateSqliteTablesOptions, a as SqliteTableNames, c as createSqliteTables, e as edges, n as nodes, s as schemaVersions, t as tables, u as uniques } from '../../sqlite-CZDFUfHS.js';
-export { g as generateSqliteDDL, a as generateSqliteMigrationSQL } from '../../ddl-BwH00BB6.js';
+import { S as SqliteExecutionProfileHints, F as FulltextStrategy, V as VectorStrategy, B as BackendCapabilities, A as AnySqliteDatabase, G as GraphBackend } from '../../types-BKQljXom.js';
+export { a as SqliteTransactionMode } from '../../types-BKQljXom.js';
+import { S as SqliteTables } from '../../sqlite-aM_PAz-O.js';
+export { C as CreateSqliteTablesOptions, a as SqliteTableNames, c as createSqliteTables, e as edges, n as nodes, s as schemaVersions, t as tables, u as uniques } from '../../sqlite-aM_PAz-O.js';
+export { g as generateSqliteDDL, a as generateSqliteMigrationSQL } from '../../ddl-BJcPrB4L.js';
 import 'zod';
-import '../../extension-types-CwHV-Uk4.js';
+import '../../extension-types-D1k0inWU.js';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm/sqlite-core';
-import '../../postgres-CcRLaxz0.js';
+import '../../postgres-BdIb7tS_.js';
 
 /**
  * Options for creating a SQLite backend.
@@ -43,6 +43,11 @@ type SqliteBackendOptions = Readonly<{
      * connections without a vector extension.
      */
     vector?: VectorStrategy;
+    /**
+     * Override specific backend capabilities. Useful for custom SQLite builds
+     * or tests that need to simulate an engine-level capability gap.
+     */
+    capabilities?: Partial<BackendCapabilities>;
 }>;
 declare function createSqliteBackend(db: AnySqliteDatabase, options?: SqliteBackendOptions): GraphBackend;
 

package/dist/backend/sqlite/index.js

@@ -1,12 +1,12 @@
-export { createSqliteBackend } from '../../chunk-A4H6QMV4.js';
-export { generateSqliteDDL, generateSqliteMigrationSQL } from '../../chunk-3DTLDGIM.js';
-export { createSqliteTables, edges, nodes, schemaVersions, tables, uniques } from '../../chunk-HKN622O4.js';
+export { createSqliteBackend } from '../../chunk-4A4GUZTQ.js';
+export { generateSqliteDDL, generateSqliteMigrationSQL } from '../../chunk-VZX2KSY3.js';
+export { createSqliteTables, edges, nodes, schemaVersions, tables, uniques } from '../../chunk-GKFWM3DS.js';
+import '../../chunk-LJLMDDCW.js';
+import '../../chunk-SAJSMR2B.js';
 import '../../chunk-M6OC455F.js';
-import '../../chunk-7KLVFWXR.js';
-import '../../chunk-OGUH56BB.js';
-import '../../chunk-N3VVQDMA.js';
-import '../../chunk-454I6GDF.js';
-import '../../chunk-MB363HT5.js';
-import '../../chunk-NZ5PMBTG.js';
+import '../../chunk-2HZGWCB4.js';
+import '../../chunk-2YMGNYXY.js';
+import '../../chunk-TQOYM4LN.js';
+import '../../chunk-K5P5OZXS.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map