@nicia-ai/typegraph 0.47.0 → 0.49.0

package/dist/{chunk-5UMTUOM5.js → chunk-JPD2CTC3.js}

@@ -1,6 +1,7 @@
-import { createPostgresBackend } from './chunk-M35DF33T.js';
+import { createPostgresBackend } from './chunk-7LZJNLA5.js';
 import { tables, generatePostgresMigrationSQL, generatePostgresDDL } from './chunk-6SWPJEYN.js';
-import { wrapWithManagedClose, closeAfterFailure } from './chunk-SHSSRCFR.js';
+import { wrapWithManagedClose } from './chunk-UGHG7PGX.js';
+import { closeAfterFailure } from './chunk-6LN7FIVU.js';
 import { ConfigurationError } from './chunk-ZLONH2UD.js';
 import { PGlite } from '@electric-sql/pglite';
 import { drizzle } from 'drizzle-orm/pglite';
@@ -43,5 +44,5 @@ async function createLocalPgliteBackend(options = {}) {
 }
 
 export { createLocalPgliteBackend };
-//# sourceMappingURL=chunk-5UMTUOM5.js.map
-//# sourceMappingURL=chunk-5UMTUOM5.js.map
+//# sourceMappingURL=chunk-JPD2CTC3.js.map
+//# sourceMappingURL=chunk-JPD2CTC3.js.map

package/dist/chunk-JPD2CTC3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/backend/postgres/pglite.ts"],"names":["tables"],"mappings":";;;;;;;;AAqIA,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;AAED,EAAA,IAAI;AAGF,IAAA,MAAM,YAAA,GACJ,gBACE,4BAAA,CAA6BA,OAAM,IACnC,mBAAA,CAAoBA,OAAM,CAAA,CAAE,IAAA,CAAK,MAAM,CAAA;AAC3C,IAAA,MAAM,MAAA,CAAO,KAAK,YAAY,CAAA;AAE9B,IAAA,MAAM,EAAA,GAAK,QAAQ,MAAM,CAAA;AACzB,IAAA,MAAM,OAAA,GAAU,sBAAsB,EAAA,EAAI;AAAA,MACxC,MAAA,EAAAA,OAAAA;AAAA,MACA,GAAI,aAAA,GAAgB,EAAC,GAAI,EAAE,QAAQ,KAAA;AAAM,KAC1C,CAAA;AACD,IAAA,MAAM,cAAA,GAAiB,oBAAA,CAAqB,OAAA,EAAS,YAAY;AAC/D,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB,CAAC,CAAA;AAED,IAAA,OAAO,EAAE,OAAA,EAAS,cAAA,EAAgB,EAAA,EAAI,MAAA,EAAO;AAAA,EAC/C,SAAS,KAAA,EAAO;AACd,IAAA,OAAO,iBAAA,CAAkB,QAAQ,KAAK,CAAA;AAAA,EACxC;AACF","file":"chunk-JPD2CTC3.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/adapters/drizzle/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 { wrapWithManagedClose } from \"../derive-backend\";\nexport type { GraphIdentityConfig } from \"../../core/define-graph\";\nimport {\n  generatePostgresDDL,\n  generatePostgresMigrationSQL,\n} from \"../drizzle/ddl\";\nimport { type AnyPgTransaction } from \"../drizzle/execution\";\nexport type { AnyPgDatabase, AnyPgTransaction } from \"../drizzle/execution\";\nimport {\n  createPostgresBackend,\n  type PostgresTables,\n  tables as defaultTables,\n} from \"../drizzle/postgres\";\nimport { type AdapterBackend, closeAfterFailure } from \"../types\";\nexport type {\n  ContributionDiagnostic,\n  ContributionDiagnosticState,\n  ContributionRepairEntry,\n  ContributionRepairResult,\n} 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: AdapterBackend<AnyPgTransaction>;\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  try {\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  } catch (error) {\n    return closeAfterFailure(client, error);\n  }\n}\n"]}

package/dist/{chunk-SE6EGQSD.js → chunk-KF6K7TGH.js}

@@ -1,11 +1,12 @@
-import { getEmbeddingFields, applyNodeInsertSideEffectsBatch, createNodeWriteContext, applyNodeSoftDelete, applyNodeHardDelete, applyNodeUpdate, applyNodeInsertSideEffects, checkUniquenessConstraints, createUniquenessContext } from './chunk-FNOMT74T.js';
-import { encodeTupleKey, runInWriteTransaction, refKey, runHookedWriteOperation, validateNodeProps } from './chunk-NNQ6A3RM.js';
-import { runInsertBatch, nodeInsertDispatch, runInsertBatchReturning, getNodeRowsByIds, generateId, runInsertNoReturn } from './chunk-AVGUJWVX.js';
+import { getEmbeddingFields, validateResolvedNodeUniqueness, createUniquenessContext, applyNodeInsertSideEffectsBatch, createNodeWriteContext, applyNodeSoftDelete, applyNodeHardDelete, applyNodeUpdate, applyNodeInsertSideEffects, checkUniquenessConstraints } from './chunk-I4GAZH5Z.js';
+import { runInWriteTransaction, refKey, runHookedWriteOperation, validateNodeProps } from './chunk-ZFMCDJGB.js';
+import { encodeTupleKey, runInsertBatch, nodeInsertDispatch, runInsertBatchReturning, getNodeRowsByIds, generateId, runInsertNoReturn } from './chunk-S5TERQVW.js';
 import { canonicalEqual } from './chunk-JBQQ7THH.js';
+import { deriveBackend } from './chunk-UGHG7PGX.js';
 import { createSqlSchema, DEFAULT_SQL_SCHEMA } from './chunk-NVY5CJFP.js';
-import { rowPropsToObject, createBackendOverlay, isLiveNodeRow } from './chunk-SHSSRCFR.js';
+import { rowPropsToObject, isLiveNodeRow } from './chunk-6LN7FIVU.js';
 import { checkCardinality, checkUniqueEdge, checkWherePredicate, computeUniqueKey, getKindsForUniquenessCheck, checkDisjointness } from './chunk-GLHXM7C4.js';
-import { validateOptionalCanonicalIsoDate, assertOrderedValidityWindow, nowIso, preservesImmutableLowerBound, assertWritableValidityWindow } from './chunk-NG2RB5WL.js';
+import { validateOptionalCanonicalIsoDate, nowIso, resolveStampedValidityLowerBound, assertOrderedValidityWindow, preservesImmutableLowerBound, assertWritableValidityWindow } from './chunk-5K2BKEBD.js';
 import { getDialect, compileNodeIndexFieldKeys, compileIndexWhere } from './chunk-ZDKTPBGV.js';
 import { sql, asCompiledRowsSql } from './chunk-3DMMGT6S.js';
 import { getSearchableFields } from './chunk-PC2UBAUB.js';
@@ -446,7 +447,7 @@ function createNodeBatchValidationBackend(graphId, registry, backend) {
     if (uniqueCache.has(cacheKey)) return;
     uniqueCache.set(cacheKey, row);
   }
-  const validationBackend = createBackendOverlay(backend, {
+  const validationBackend = deriveBackend(backend, {
     getNode: getNodeCached,
     checkUnique: checkUniqueCached
   });
@@ -609,6 +610,7 @@ async function performNodeUpdate(ctx, input, backend, lock, options) {
     "validFrom"
   );
   const validFrom = preservesLiveLowerBound ? void 0 : statedValidFrom;
+  const resurrectionBound = resurrectionInstant === void 0 ? void 0 : resolveStampedValidityLowerBound(validFrom, validTo, resurrectionInstant);
   const windowVerdict = assertWritableValidityWindow(
     `${kind} "${id}"`,
     validFrom,
@@ -617,20 +619,18 @@ async function performNodeUpdate(ctx, input, backend, lock, options) {
       appliesStatedValidFrom: false,
       effectiveBoundIsStored: true
     } : {
-      effectiveValidFrom: resurrectionInstant,
+      effectiveValidFrom: resurrectionBound,
       appliesStatedValidFrom: true,
-      // The instant this write is about to stamp, not a bound the row holds.
+      // The bound this write is about to stamp, not one the row holds.
       effectiveBoundIsStored: false
     },
     validTo
   );
   const writeContext = createNodeWriteContext(ctx.graphId, ctx.registry, lock);
-  const effectiveValidFrom = validFrom ?? resurrectionInstant;
   const shared = {
     schema: nodeKind.schema,
     validatedProps,
     uniqueConstraints: registration.unique ?? [],
-    ...effectiveValidFrom !== void 0 && { validFrom: effectiveValidFrom },
     ...validTo !== void 0 && { validTo },
     ...input.clearValidTo === true && { clearValidTo: true },
     // The bound the verdict above READ, carried into the UPDATE's own `WHERE`
@@ -646,9 +646,10 @@ async function performNodeUpdate(ctx, input, backend, lock, options) {
     ...windowVerdict.storedLowerBoundFence
   };
   if (options?.clearDeleted) {
+    const resurrectionLowerBound = resurrectionInstant === void 0 ? validFrom !== void 0 && { validFrom } : { validFrom: resurrectionBound ?? null };
     const row2 = await applyNodeUpdate(
       writeContext,
-      { ...shared, existing, clearDeleted: true },
+      { ...shared, existing, clearDeleted: true, ...resurrectionLowerBound },
       backend
     );
     return rowToNode(row2);
@@ -656,7 +657,11 @@ async function performNodeUpdate(ctx, input, backend, lock, options) {
   if (!isLiveNodeRow(existing)) throw new NodeNotFoundError(kind, id);
   const row = await applyNodeUpdate(
     writeContext,
-    { ...shared, existing },
+    // An in-place update must not rewrite the stored bound, so it keeps the
+    // conditional spread: `buildUpdateNode` ignores `validFrom` off the
+    // resurrection leg, and stating one here would claim a rewrite that no
+    // statement performs.
+    { ...shared, existing, ...validFrom !== void 0 && { validFrom } },
     backend
   );
   return rowToNode(row);
@@ -819,6 +824,12 @@ async function resurrectPreparedNode(ctx, target, lock, prepared) {
   if (current.deleted_at === void 0) {
     throw createAlreadyExistsError("node", prepared.kind, prepared.id);
   }
+  const resurrectionInstant = nowIso();
+  const resurrectionBound = resolveStampedValidityLowerBound(
+    prepared.insertParams.validFrom,
+    prepared.insertParams.validTo,
+    resurrectionInstant
+  );
   try {
     return await applyNodeUpdate(
       createNodeWriteContext(ctx.graphId, ctx.registry, lock),
@@ -828,7 +839,10 @@ async function resurrectPreparedNode(ctx, target, lock, prepared) {
         schema: prepared.nodeKind.schema,
         validatedProps: prepared.validatedProps,
         uniqueConstraints: prepared.uniqueConstraints,
-        ...prepared.insertParams.validFrom === void 0 ? {} : { validFrom: prepared.insertParams.validFrom },
+        // The decision itself, never an absence — see the same spelling on
+        // `performNodeUpdate`'s resurrection leg.
+        // eslint-disable-next-line unicorn/no-null -- `validFrom: null` means "store NULL"; omitting the key means "decide for me", and this path has already decided. See UpdateNodeParams.validFrom.
+        validFrom: resurrectionBound ?? null,
         ...prepared.insertParams.validTo === void 0 ? {} : { validTo: prepared.insertParams.validTo }
       },
       target
@@ -1263,57 +1277,15 @@ async function executeNodeUpdateWhere(ctx, kind, inputPatch, candidateIds, candi
           };
         });
         if (uniqueConstraints.length > 0) {
-          const affectedIds = new Set(result.rows.map((row) => row.id));
-          for (const constraint of uniqueConstraints) {
-            const keyToId = /* @__PURE__ */ new Map();
-            for (const item of sidecarItems) {
-              if (!checkWherePredicate(constraint, item.props)) continue;
-              const key = computeUniqueKey(
-                item.props,
-                constraint.fields,
-                constraint.collation
-              );
-              const priorId = keyToId.get(key);
-              if (priorId !== void 0 && priorId !== item.id) {
-                throw new UniquenessError({
-                  constraintName: constraint.name,
-                  kind,
-                  existingId: priorId,
-                  newId: item.id,
-                  fields: constraint.fields
-                });
-              }
-              keyToId.set(key, item.id);
-            }
-            const keys = [...keyToId.keys()];
-            if (keys.length === 0) continue;
-            for (const kindToCheck of getKindsForUniquenessCheck(
-              kind,
-              constraint.scope,
-              ctx.registry
-            )) {
-              const existingRows = await requireDefined(
-                target.checkUniqueBatch
-              )({
-                graphId: ctx.graphId,
-                nodeKind: kindToCheck,
-                constraintName: constraint.name,
-                keys
-              });
-              for (const existing of existingRows) {
-                if (existing.concrete_kind === kind && affectedIds.has(existing.node_id)) {
-                  continue;
-                }
-                throw new UniquenessError({
-                  constraintName: constraint.name,
-                  kind: kindToCheck,
-                  existingId: existing.node_id,
-                  newId: requireDefined(keyToId.get(existing.key)),
-                  fields: constraint.fields
-                });
-              }
-            }
-          }
+          await validateResolvedNodeUniqueness(
+            createUniquenessContext(ctx.graphId, ctx.registry, target),
+            sidecarItems.map((item) => ({
+              kind: item.kind,
+              id: item.id,
+              props: item.props,
+              constraints: item.uniqueConstraints
+            }))
+          );
           await requireDefined(hardDeleteUniquesByNodeIds)({
             graphId: ctx.graphId,
             concreteKind: kind,
@@ -2014,5 +1986,5 @@ async function executeNodeBulkGetOrCreateByConstraint(ctx, kind, constraintName,
 }
 
 export { assertClearValidToSupported, assertValidityEndMutation, checkCardinalityConstraint, createNodeBatchValidationBackend, edgeWriteNeedsConstraintFence, executeNodeBulkFindByConstraint, executeNodeBulkFindByIndex, executeNodeBulkGetOrCreateByConstraint, executeNodeCreate, executeNodeCreateBatch, executeNodeCreateNoReturnBatch, executeNodeDelete, executeNodeDeleteBatch, executeNodeFindByConstraint, executeNodeGetOrCreateByConstraint, executeNodeHardDelete, executeNodeUpdate, executeNodeUpdateWhere, executeNodeUpsertUpdate, nodeUpsertDirtyCheck, primeBatchValidationCaches, rowToEdge, rowToEdgeMeta, rowToNode, rowToNodeMeta, validityEndAfterMutation, withAlreadyExistsTranslation };
-//# sourceMappingURL=chunk-SE6EGQSD.js.map
-//# sourceMappingURL=chunk-SE6EGQSD.js.map
+//# sourceMappingURL=chunk-KF6K7TGH.js.map
+//# sourceMappingURL=chunk-KF6K7TGH.js.map