@nicia-ai/typegraph 0.50.0 → 0.51.0

package/dist/chunk-RVUL2HXY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constraints/index.ts","../src/utils/tuple-key.ts","../src/store/claims/axis.ts"],"names":[],"mappings":"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","file":"chunk-RVUL2HXY.js","sourcesContent":["/**\n * Constraint validation module.\n *\n * Provides validation functions for enforcing graph constraints:\n * - Uniqueness constraints on node properties\n * - Cardinality constraints on edges\n * - Endpoint type constraints on edges\n * - Disjointness constraints between node kinds\n */\n\n/**\n * Separator used between field values in composite unique keys.\n * Uses ASCII Record Separator (0x1E) — valid UTF-8 and safe for PostgreSQL\n * TEXT columns (unlike \\0 which PostgreSQL rejects).\n */\nconst UNIQUE_KEY_SEPARATOR = \"\\u001E\";\n\n/** Marker for undefined/null field values in unique keys. */\nconst UNIQUE_KEY_NULL_MARKER = \"\\u001F\"; // ASCII Unit Separator\nimport {\n  type Cardinality,\n  type Collation,\n  type EdgeRegistration,\n  type NullCheckOp,\n  type UniqueConstraint,\n  type UniquenessScope,\n} from \"../core/types\";\nimport {\n  CardinalityError,\n  ConfigurationError,\n  DisjointError,\n  EndpointError,\n  UniquenessError,\n} from \"../errors\";\nimport { type KindRegistry } from \"../registry/kind-registry\";\nimport { hasOwnKey, readOwnProperty } from \"../utils/object\";\nimport { isPresent } from \"../utils/presence\";\n\n// ============================================================\n// Uniqueness Validation\n// ============================================================\n\n/**\n * Computes the unique key for a node's uniqueness constraint.\n *\n * The key is built by concatenating the specified field values,\n * optionally normalized for case-insensitive comparison.\n *\n * Field values are read by declared OWN key ({@link readOwnProperty}): a\n * constraint may name a field that a props bag does not carry (an absent\n * optional field), and a plain `props[field]` read would answer such a field\n * with the inherited `Object.prototype` member when the field is named after\n * one. A constraint over a field named `toString` then keyed on the inherited\n * function — `\"\"` under `binary` (the function stringified and dropped by\n * `JSON.stringify`) and a `TypeError` under `caseInsensitive` — instead of the\n * null marker every other absent value gets.\n */\nexport function computeUniqueKey(\n  props: Record<string, unknown>,\n  fields: readonly string[],\n  collation: Collation,\n): string {\n  const values = fields.map((field) => {\n    const value = readOwnProperty(props, field);\n    if (value === undefined || value === null) {\n      return UNIQUE_KEY_NULL_MARKER;\n    }\n    // Convert to string, handling primitives safely\n    const stringValue =\n      typeof value === \"string\" ? value\n      : typeof value === \"number\" || typeof value === \"boolean\" ?\n        value.toString()\n      : JSON.stringify(value);\n    return collation === \"caseInsensitive\" ?\n        stringValue.toLowerCase()\n      : stringValue;\n  });\n  return values.join(UNIQUE_KEY_SEPARATOR);\n}\n\n/**\n * Checks if a uniqueness constraint's where predicate passes.\n *\n * A `where` callback that does not return a predicate is REFUSED here, not\n * treated as \"the constraint always applies\". The same malformed clause is a\n * hard `ConfigurationError` at definition time ({@link assertWhereFieldDeclared})\n * and at persistence time (`serializeWherePredicate`); a third reading that\n * silently widened a partial constraint to a total one would let the three\n * sites disagree about the same clause — the divergence\n * {@link captureWherePredicate} exists to prevent.\n *\n * The arm SHOULD be unreachable: `defineGraph` refuses a non-predicate callback\n * before any write can evaluate it, `validateGraphExtension` refuses the\n * document form, and a constraint reconstructed from a persisted schema carries\n * a callback this module built itself. It is reachable only by handing the\n * store a constraint object that never passed a definition gate — for which\n * failing loudly is the correct answer, since the alternative is enforcing\n * uniqueness over rows the author meant to exclude.\n */\nexport function checkWherePredicate(\n  constraint: UniqueConstraint,\n  props: Record<string, unknown>,\n): boolean {\n  if (!constraint.where) {\n    return true; // No where clause, always applies\n  }\n\n  const predicate = captureWherePredicate(constraint.where);\n  if (predicate === undefined) {\n    throw new ConfigurationError(\n      `Unique constraint \"${constraint.name}\" has a \\`where\\` callback that does not return a predicate.`,\n      { constraintName: constraint.name, fields: [...constraint.fields] },\n      {\n        suggestion: `Return a field predicate, e.g. \\`where: (fields) => fields.${constraint.fields[0] ?? \"someField\"}.isNotNull()\\`. A constraint built outside \\`defineGraph\\` bypasses the definition-time check that normally reports this.`,\n      },\n    );\n  }\n\n  return evaluatePredicate(predicate, props);\n}\n\ntype UniquePredicate = Readonly<{\n  __type: \"unique_predicate\";\n  field: string;\n  op: NullCheckOp;\n}>;\n\n/**\n * The `where` callback as every caller of {@link captureWherePredicate} sees it:\n * a per-field builder in, whatever the author returned out.\n *\n * Deliberately looser than `UniqueConstraint[\"where\"]`, whose builder type is\n * generic in the kind's schema — the capture is the same operation whether the\n * callback came from a typed `defineGraph` registration, a compiled\n * graph-extension document, or an untyped JavaScript caller.\n */\ntype UniqueWhereCallback = (\n  builder: Readonly<\n    Record<\n      string,\n      Readonly<{\n        isNull: () => UniquePredicate;\n        isNotNull: () => UniquePredicate;\n      }>\n    >\n  >,\n) => unknown;\n\n/**\n * Runs a `where` callback against the shared builder and returns the predicate\n * it named, or `undefined` when the callback returned something that is not a\n * predicate.\n *\n * The single owner of \"what does this `where` clause say\": constraint\n * EVALUATION ({@link checkWherePredicate}), definition-time VALIDATION\n * ({@link assertWhereFieldDeclared}), and persistence-time CAPTURE\n * (`serializeWherePredicate` in src/schema/serializer.ts) all read the clause\n * through this one function, so a persisted `where`, a validated `where`, and\n * an evaluated `where` cannot disagree about which field the author named.\n */\nexport function captureWherePredicate(\n  where: UniqueWhereCallback,\n): UniquePredicate | undefined {\n  const predicate = where(buildPredicateContext());\n  if (\n    typeof predicate !== \"object\" ||\n    predicate === null ||\n    !(\"__type\" in predicate)\n  ) {\n    return undefined;\n  }\n\n  const candidate = predicate as {\n    __type: unknown;\n    field: unknown;\n    op: unknown;\n  };\n  if (\n    candidate.__type !== \"unique_predicate\" ||\n    typeof candidate.field !== \"string\" ||\n    (candidate.op !== \"isNull\" && candidate.op !== \"isNotNull\")\n  ) {\n    return undefined;\n  }\n\n  return {\n    __type: \"unique_predicate\",\n    field: candidate.field,\n    op: candidate.op,\n  };\n}\n\n/**\n * Refuses a uniqueness constraint whose `where` clause names a field the kind\n * does not declare.\n *\n * The runtime half of the builder's guard. {@link buildPredicateContext} is\n * total by design — it must answer for a DECLARED-but-absent field, which is\n * the whole point of a partial constraint — so a typo'd name cannot be caught\n * there, and the type system catches it only for typed callers\n * (`UniqueConstraintPredicateBuilder` declares exactly the schema's fields and\n * has no index signature). An untyped caller naming an undeclared field\n * otherwise gets a predicate that quietly never applies.\n *\n * Called once per constraint at graph-definition time — the single point every\n * constraint passes through before any write can evaluate it — rather than at\n * each of the write paths' `checkWherePredicate` call sites, so the refusal\n * covers every path uniformly and costs nothing per write. Mirrors\n * `validateGraphExtension`'s `UNKNOWN_UNIQUE_WHERE_FIELD` refusal, which\n * already holds the same invariant for kinds declared as JSON documents.\n */\nexport function assertWhereFieldDeclared(\n  kind: string,\n  constraint: UniqueConstraint,\n  shape: Readonly<Record<string, unknown>>,\n): void {\n  if (!constraint.where) return;\n\n  const predicate = captureWherePredicate(constraint.where);\n  if (predicate === undefined) {\n    throw new ConfigurationError(\n      `Unique constraint \"${constraint.name}\" on node kind \"${kind}\" has a \\`where\\` callback that does not return a predicate.`,\n      { kind, constraintName: constraint.name },\n      {\n        suggestion: `Return a field predicate, e.g. \\`where: (fields) => fields.${Object.keys(shape)[0] ?? \"someField\"}.isNotNull()\\`.`,\n      },\n    );\n  }\n\n  if (!hasOwnKey(shape, predicate.field)) {\n    throw new ConfigurationError(\n      `Unique constraint \"${constraint.name}\" on node kind \"${kind}\" has a \\`where\\` clause on field \"${predicate.field}\", which is not declared in the kind's schema.`,\n      {\n        kind,\n        constraintName: constraint.name,\n        field: predicate.field,\n        declaredFields: Object.keys(shape),\n      },\n      {\n        suggestion: `Name a declared field (${Object.keys(shape).join(\", \")}) or add \"${predicate.field}\" to the schema.`,\n      },\n    );\n  }\n}\n\ntype PredicateContext = Readonly<\n  Record<\n    string,\n    Readonly<{\n      isNull: () => UniquePredicate;\n      isNotNull: () => UniquePredicate;\n    }>\n  >\n>;\n\n/**\n * Builds the context a constraint's `where` callback names fields on.\n *\n * EVERY field name gets a member, because the builder type declares every\n * schema field as required (`-?` in `UniqueConstraintPredicateBuilder`) —\n * precisely so a partial constraint can ask whether an OPTIONAL field is\n * present. Populating the context from the props bag's own keys instead left a\n * declared-but-absent field with no member, and the callback's access then hit\n * whatever the context's prototype offered: `Object.prototype.toString` for a\n * field named `toString` (so naming it threw \"isNull is not a function\"), and\n * `undefined` for an ordinary field (so the everyday partial constraint over\n * `externalId` threw — \"Cannot read properties of undefined\", or \"Expected a\n * defined value\" through `requireDefined` — for every node written without it).\n *\n * Answering every name is safe because a name comes from the predicate author\n * (the code), never from data, and the field's VALUE is still read from the\n * props bag by own key when the predicate is evaluated — so an absent field\n * evaluates as null, which is what a partial constraint means by absent. Every\n * reader of a `where` clause goes through {@link captureWherePredicate}, which\n * builds this one context, so a persisted `where`, a validated `where`, and an\n * evaluated `where` cannot see different builders.\n *\n * The guard against a TYPO'D field name is NOT this Proxy — it must stay total\n * or a declared-but-absent field loses its member. It is\n * {@link assertWhereFieldDeclared}, which every constraint passes at\n * graph-definition time: an undeclared name is refused there with a typed\n * `ConfigurationError`, so no `where` clause naming one ever reaches\n * evaluation, from a typed or an untyped caller.\n */\nfunction buildPredicateContext(): PredicateContext {\n  return new Proxy<PredicateContext>(\n    {},\n    {\n      get(_target, property) {\n        if (typeof property === \"symbol\") return;\n        return {\n          isNull: () => ({\n            __type: \"unique_predicate\" as const,\n            field: property,\n            op: \"isNull\" as const,\n          }),\n          isNotNull: () => ({\n            __type: \"unique_predicate\" as const,\n            field: property,\n            op: \"isNotNull\" as const,\n          }),\n        };\n      },\n    },\n  );\n}\n\n/**\n * Evaluates a uniqueness predicate.\n *\n * Takes a CAPTURED predicate, not an `unknown`: the \"is this really a\n * predicate?\" question belongs to {@link captureWherePredicate}, which is its\n * single owner. The defensive `return true` arms this function used to carry\n * were a second, quieter answer to that question — and they answered it the\n * opposite way, widening a partial constraint into a total one where the owner\n * refuses.\n */\nfunction evaluatePredicate(\n  pred: UniquePredicate,\n  props: Record<string, unknown>,\n): boolean {\n  // Own-key read: `pred.field` is a schema field name, and a props bag that\n  // does not carry it must read as absent rather than as the inherited\n  // `Object.prototype` member a field named after one would otherwise find\n  // (which reads as present, inverting both `isNull` and `isNotNull`).\n  const value = readOwnProperty(props, pred.field);\n  if (pred.op === \"isNull\") {\n    return value === null || value === undefined;\n  }\n  return isPresent(value);\n}\n\n/**\n * Gets all kinds that should be checked for a uniqueness constraint.\n *\n * For \"kindWithSubClasses\" scope, includes the entire subclass hierarchy:\n * - The kind itself\n * - All ancestors (parent classes)\n * - All descendants of those ancestors (sibling classes)\n *\n * For \"kind\" scope, only the specific kind.\n */\nexport function getKindsForUniquenessCheck(\n  baseKind: string,\n  scope: UniquenessScope,\n  registry: KindRegistry,\n): readonly string[] {\n  if (scope === \"kind\") {\n    return [baseKind];\n  }\n\n  // Get the entire connected subclass hierarchy by finding the root ancestor\n  const root = findRootAncestor(baseKind, registry);\n\n  // Return the root and all its descendants (which includes baseKind and siblings)\n  return registry.expandSubClasses(root);\n}\n\n/**\n * THE definition of \"which kinds a `kindWithSubClasses` scope covers\": the\n * registry's precomputed connected component of the UNDIRECTED `subClassOf`\n * graph containing `kind`, in code-point order.\n *\n * Kind-independent by construction — every member of a component computes the\n * same set — which is what makes a claim axis folded from it deterministic: two\n * writers of two different kinds in one hierarchy reserve the SAME row, so the\n * uniques primary key fences them against each other.\n *\n * {@link getKindsForUniquenessCheck} is deliberately NOT folded into this: it\n * walks one root's descendants, so on a multi-root hierarchy (`Employee`\n * subclassing both `Alpha` and `Zeta`) it answers differently depending on which\n * member asks, and a fold of a kind-dependent set cannot be a canonical axis.\n * This is the documented intent of that function, so the component is a superset\n * of the set it walks: the fence is never weaker than the probe, and is stronger\n * in exactly the multi-root case where the probe is inconsistent.\n */\nexport function subClassComponent(\n  kind: string,\n  registry: KindRegistry,\n): readonly string[] {\n  return registry.getSubClassComponent(kind);\n}\n\n/**\n * Finds the topmost ancestor of a kind, or the kind itself if it has no ancestors.\n */\nfunction findRootAncestor(kind: string, registry: KindRegistry): string {\n  const ancestors = registry.getAncestors(kind);\n\n  if (ancestors.size === 0) {\n    return kind;\n  }\n\n  // Find an ancestor with no ancestors (the root)\n  for (const ancestor of ancestors) {\n    if (registry.getAncestors(ancestor).size === 0) {\n      return ancestor;\n    }\n  }\n\n  // If all ancestors have ancestors, recurse up\n  const firstAncestor = [...ancestors][0];\n  return firstAncestor ? findRootAncestor(firstAncestor, registry) : kind;\n}\n\n/**\n * Creates a uniqueness error.\n */\nexport function createUniquenessError(\n  constraintName: string,\n  kind: string,\n  existingId: string,\n  newId: string,\n  fields: readonly string[],\n): UniquenessError {\n  return new UniquenessError({\n    constraintName,\n    kind,\n    existingId,\n    newId,\n    fields: [...fields],\n  });\n}\n\n// ============================================================\n// Cardinality Validation\n// ============================================================\n\n/**\n * Checks if adding an edge would violate cardinality constraints.\n *\n * @param edgeKind - The edge kind being added\n * @param fromKind - The source node kind\n * @param fromId - The source node ID\n * @param cardinality - The cardinality constraint\n * @param existingEdgeCount - Number of existing edges of this kind from this source\n * @param hasActiveEdge - Whether there's an active (valid_to IS NULL) edge\n * @returns Error if violation, undefined if valid\n */\nexport function checkCardinality(\n  edgeKind: string,\n  fromKind: string,\n  fromId: string,\n  cardinality: Cardinality,\n  existingEdgeCount: number,\n  hasActiveEdge: boolean,\n): CardinalityError | undefined {\n  switch (cardinality) {\n    case \"many\": {\n      // No constraint\n      return undefined;\n    }\n    case \"one\": {\n      // At most one edge of this kind from any source node\n      if (existingEdgeCount > 0) {\n        return new CardinalityError({\n          edgeKind,\n          fromKind,\n          fromId,\n          cardinality: \"one\",\n          existingCount: existingEdgeCount,\n        });\n      }\n      return undefined;\n    }\n    case \"unique\": {\n      // unique is checked separately per (source, target) pair\n      return undefined;\n    }\n    case \"oneActive\": {\n      // At most one edge with valid_to IS NULL from any source\n      if (hasActiveEdge) {\n        return new CardinalityError({\n          edgeKind,\n          fromKind,\n          fromId,\n          cardinality: \"oneActive\",\n          existingCount: 1,\n        });\n      }\n      return undefined;\n    }\n  }\n}\n\n/**\n * Checks unique edge constraint (at most one edge between any source-target pair).\n */\nexport function checkUniqueEdge(\n  edgeKind: string,\n  fromKind: string,\n  fromId: string,\n  _toKind: string,\n  _toId: string,\n  existingCount: number,\n): CardinalityError | undefined {\n  if (existingCount > 0) {\n    return new CardinalityError({\n      edgeKind,\n      fromKind,\n      fromId,\n      cardinality: \"unique\",\n      existingCount,\n    });\n  }\n  return undefined;\n}\n\n// ============================================================\n// Endpoint Validation\n// ============================================================\n\n/**\n * Validates that an edge's endpoints are valid node kinds.\n */\nexport function validateEdgeEndpoints(\n  edgeKind: string,\n  fromKind: string,\n  toKind: string,\n  registration: EdgeRegistration,\n  registry: KindRegistry,\n): EndpointError | undefined {\n  // Check from kinds\n  const validFromKinds = registration.from.map((node) => node.kind);\n  if (!registry.isAssignableToAny(fromKind, validFromKinds)) {\n    return new EndpointError({\n      edgeKind,\n      endpoint: \"from\",\n      actualKind: fromKind,\n      expectedKinds: validFromKinds,\n    });\n  }\n\n  // Check to kinds\n  const validToKinds = registration.to.map((node) => node.kind);\n  if (!registry.isAssignableToAny(toKind, validToKinds)) {\n    return new EndpointError({\n      edgeKind,\n      endpoint: \"to\",\n      actualKind: toKind,\n      expectedKinds: validToKinds,\n    });\n  }\n\n  return undefined;\n}\n\n// ============================================================\n// Disjointness Validation\n// ============================================================\n\n/**\n * Checks if creating a node would violate disjointness constraints.\n *\n * @param nodeId - The node ID being created\n * @param nodeKind - The kind of the new node\n * @param existingKinds - Kinds of existing nodes with the same ID\n * @param registry - The kind registry for disjointness checks\n * @returns Error if disjoint violation, undefined if valid\n */\nexport function checkDisjointness(\n  nodeId: string,\n  nodeKind: string,\n  existingKinds: readonly string[],\n  registry: KindRegistry,\n): DisjointError | undefined {\n  for (const existingKind of existingKinds) {\n    if (registry.areDisjoint(nodeKind, existingKind)) {\n      return new DisjointError({\n        nodeId,\n        attemptedKind: nodeKind,\n        conflictingKind: existingKind,\n      });\n    }\n  }\n  return undefined;\n}\n\n/**\n * Gets all disjoint kinds for a given kind.\n */\nexport function getDisjointKinds(\n  kind: string,\n  registry: KindRegistry,\n): readonly string[] {\n  return registry.getDisjointKinds(kind);\n}\n","/**\n * Encodes an ordered tuple of strings as an injective map key.\n *\n * Delimiter joins are unsafe because every delimiter is also a legal value\n * character. JSON's string-array grammar preserves both field boundaries and\n * string contents, so distinct tuples cannot collapse onto the same key.\n */\nexport function encodeTupleKey(values: readonly string[]): string {\n  return JSON.stringify(values);\n}\n","/**\n * Claim axis vocabulary.\n *\n * A declared constraint is a CLAIM on an AXIS: the value bound to a claim row's\n * `node_kind` column, which is what the relation's primary key fences on. The\n * axis is not always a kind — it is whatever set of kinds the constraint spans —\n * and deciding it is this module's only job, so no write path spells its own.\n *\n * The other half of a claim row is its OWNER, `(concrete_kind, node_id)`. Ids\n * are unique only per kind, so an id alone cannot answer \"is this row mine?\":\n * `Employee \"X\"` and `Contractor \"X\"` are two rows under the nodes primary key\n * and would read as one owner. The predicate lives here once, in the two\n * renderings the code needs (TypeScript and SQL), so a claim's accept/refuse\n * verdict cannot differ between the layer that probes it and the layer that\n * writes it.\n *\n * The SQL rendering below is generic over the caller's SQL representation and\n * keyed on physical column NAMES rather than a Drizzle `Column` object, so a\n * backend with no column objects at all can call this one owner without an\n * adapter-specific intermediate representation or a re-spelled predicate.\n */\nimport { subClassComponent } from \"../../constraints\";\nimport { type UniquenessScope } from \"../../core/types\";\nimport { ConfigurationError } from \"../../errors\";\nimport { type KindRegistry } from \"../../registry/kind-registry\";\nimport { compareStrings } from \"../../utils/compare\";\nimport { encodeTupleKey } from \"../../utils/tuple-key\";\n\n/**\n * The one code point an axis component may not contain, written as an escape\n * so it can never be mistaken for whitespace in a diff.\n *\n * Axes that are not kinds are built by joining with it — the disjointness pair\n * axis below is the first — so a kind or constraint name containing it could\n * spell a reserved axis and take a claim row the fence assigns to something\n * else. {@link assertClaimAxisSafe} is what makes that unspellable, at\n * graph-definition time.\n */\nconst AXIS_SEPARATOR = \"\\u001E\";\n\n/** The prefix marking an axis as a disjoint PAIR rather than as a kind. */\nconst DISJOINT_AXIS_PREFIX = `${AXIS_SEPARATOR}disjoint${AXIS_SEPARATOR}`;\n\n/**\n * The `constraint_name` every disjointness claim is written under.\n *\n * Reserved rather than derived: it is what tells the claim seam that a refusal\n * on this row is a `DisjointError` and not a `UniquenessError`, and what tells\n * a reader of the relation that this row's `node_kind` is a pair label rather\n * than a kind. {@link assertClaimAxisSafe} is what guarantees no declared\n * constraint can carry the same name.\n */\nexport const DISJOINT_CONSTRAINT_NAME = `${AXIS_SEPARATOR}disjointWith`;\n\n/**\n * THE axis a disjointness claim is written at: the registry's own canonical\n * pair label, prefixed so it cannot collide with a kind.\n *\n * A fold of `KindRegistry.disjointPairLabel` rather than a second\n * normalization of the same pair — the two kinds of one disjoint pair must\n * compute ONE string, or their claims sit on two rows that can never collide\n * and the fence refuses nothing.\n *\n * Pairwise, and deliberately not per component: the registry's disjoint pairs\n * are literal unordered pairs and disjointness is not transitive here, so an\n * axis keyed on a connected component would refuse an `A`/`C` pair under\n * `A⊥B, B⊥C` that the graph never declared disjoint.\n */\nexport function disjointnessClaimAxis(\n  kind: string,\n  otherKind: string,\n  registry: KindRegistry,\n): string {\n  return `${DISJOINT_AXIS_PREFIX}${registry.disjointPairLabel(kind, otherKind)}`;\n}\n\n/**\n * Refuses a kind name or constraint name that could spell a reserved claim\n * axis or the reserved disjointness constraint name.\n *\n * Runs at graph-definition time, the one gate every kind and every declared\n * constraint passes before a claim can be written for it — so the reserved\n * vocabulary is unspellable by construction rather than re-checked at each\n * write, and the claim seam can read \"this refusal is a disjointness refusal\"\n * off the reserved constraint name without a caller being able to forge it. A\n * new refusal, on an input no real schema carries.\n *\n * `subject` names the ROLE (`Node kind`, `Unique constraint`); the name itself\n * is quoted through `JSON.stringify` so the offending code point reads as an\n * escape instead of as an invisible character.\n */\nexport function assertClaimAxisSafe(name: string, subject: string): void {\n  if (!name.includes(AXIS_SEPARATOR)) return;\n  throw new ConfigurationError(\n    `${subject} name ${JSON.stringify(name)} contains U+001E, which TypeGraph reserves for claim axes.`,\n    { name },\n    {\n      suggestion: `Rename it without the U+001E (record separator) character.`,\n    },\n  );\n}\n\n/**\n * WHERE a uniqueness claim for this kind and scope is written, and whether that\n * target spans kinds beyond the writer's own.\n *\n * Both facts come out of one computation on purpose. The axis is the code-point\n * minimum of the set the scope covers, and \"does this site also need the\n * per-graph write lock?\" is that same set having more than one member — so a\n * caller cannot pick up one without the other, and the lock trigger cannot\n * drift away from the claim target. Asking the covered SET rather than the\n * scope token is what keeps a `kindWithSubClasses` constraint on a kind with no\n * hierarchy classified like the `kind` scope it is equivalent to.\n */\nexport type UniquenessClaimTarget = Readonly<{\n  axis: string;\n  crossKind: boolean;\n}>;\n\n/** The kinds one uniqueness claim axis spans, in canonical order. */\nfunction uniquenessClaimKinds(\n  kind: string,\n  scope: UniquenessScope,\n  registry: KindRegistry,\n): readonly string[] {\n  return scope === \"kind\" ? [kind] : subClassComponent(kind, registry);\n}\n\n/** THE decision above — the one owner of both readings. */\nexport function uniquenessClaimTarget(\n  kind: string,\n  scope: UniquenessScope,\n  registry: KindRegistry,\n): UniquenessClaimTarget {\n  const kinds = uniquenessClaimKinds(kind, scope, registry);\n  return { axis: kinds[0] ?? kind, crossKind: kinds.length > 1 };\n}\n\n/**\n * THE axis a uniqueness claim is written at: the kind itself for\n * `scope: \"kind\"`, and the code-point minimum of the subclass component for\n * `scope: \"kindWithSubClasses\"`.\n *\n * The minimum is a fold of a kind-independent set, so every kind in one\n * hierarchy folds to the same axis and their claims collide on the uniques\n * primary key — which is the whole fence. Reserving under each writer's own\n * kind (what this replaces) put sibling kinds in rows that can never collide.\n */\nexport function uniquenessClaimAxis(\n  kind: string,\n  scope: UniquenessScope,\n  registry: KindRegistry,\n): string {\n  return uniquenessClaimTarget(kind, scope, registry).axis;\n}\n\n/**\n * THE order a uniqueness probe reads claim rows in: the axis first, then every\n * remaining kind the scope covers, in code-point order.\n *\n * Two things make this list wider than the axis alone and narrower than\n * arbitrary:\n *\n * - The axis is where this version writes, so it is read first.\n * - Rows written before the axis move sit under their own concrete kind, so the\n *   probe visits the full undirected component, including every root of a\n *   multi-root hierarchy. That is what makes the axis move need no data\n *   migration.\n *\n * The remainder is sorted rather than left in registry-iteration order so two\n * processes reading the same scope read it in the same order.\n */\nexport function uniquenessProbeKinds(\n  kind: string,\n  scope: UniquenessScope,\n  registry: KindRegistry,\n): readonly string[] {\n  const axis = uniquenessClaimAxis(kind, scope, registry);\n  const coveredKinds = uniquenessClaimKinds(kind, scope, registry);\n  const rest = coveredKinds\n    .filter((candidate) => candidate !== axis)\n    .toSorted((left, right) => compareStrings(left, right));\n  return [axis, ...rest];\n}\n\n/**\n * THE axis an edge cardinality claim is written at: the declared cardinality\n * and the edge kind, which together name the population the constraint counts.\n *\n * `one` and `oneActive` on one kind are DIFFERENT axes on purpose — they count\n * different populations (every live edge from a source vs every active one) —\n * so a kind whose declaration changed cannot inherit rows the old declaration\n * wrote. The cardinality tokens contain no `:`, so the pair is injective over\n * arbitrary edge kind names.\n */\nexport function edgeCardinalityAxis(\n  cardinality: string,\n  edgeKind: string,\n): string {\n  return `${cardinality}:${edgeKind}`;\n}\n\n/** The relation a claim row lives in. */\ntype ClaimRelation = \"uniques\" | \"edgeClaims\";\n\n/** A claim row named in full — the row a statement is about to lock. */\nexport type ClaimTarget = Readonly<{\n  relation: ClaimRelation;\n  graphId: string;\n  axis: string;\n  /**\n   * `uniques.constraint_name`. The edge claim relation keys on\n   * `(graph_id, axis, key)` and has no such column, so its targets omit it and\n   * sort as the empty string. Absent means \"this relation does not key on a\n   * constraint name\", never \"not known yet\".\n   */\n  constraintName?: string;\n  key: string;\n}>;\n\n/**\n * THE canonical order claims are acquired in: code-point compare on\n * `(relation, graphId, axis, constraintName, key)`.\n *\n * Two writers that take the same two claim rows in opposite orders deadlock,\n * and PostgreSQL resolves that by aborting one with `40P01` — which would turn\n * an import's per-row recovery into a whole-batch abort. Sorting every claim\n * statement's entries by one comparator removes the commonest cycle, exactly as\n * multi-graph lock acquisition already does (see `recorded-capture.ts`, whose\n * comment states the same rule: every process must acquire in the same order).\n *\n * The order it establishes is per claim SET and per statement, not per\n * transaction: rows and batches inside one import claim in input order, so two\n * concurrent lock-free imports into one graph can still deadlock. That residual\n * is declared out of contract rather than fenced here.\n */\nexport function compareClaimTargets(\n  left: ClaimTarget,\n  right: ClaimTarget,\n): number {\n  return (\n    compareStrings(left.relation, right.relation) ||\n    compareStrings(left.graphId, right.graphId) ||\n    compareStrings(left.axis, right.axis) ||\n    compareStrings(left.constraintName ?? \"\", right.constraintName ?? \"\") ||\n    compareStrings(left.key, right.key)\n  );\n}\n\n/**\n * WHO holds a claim. A node, not an id: ids are unique only per kind, so\n * `(concrete_kind, node_id)` is the smallest thing that identifies a claimant.\n */\nexport type ClaimOwner = Readonly<{ concreteKind: string; nodeId: string }>;\n\n/**\n * THE ownership predicate. Every reader of \"is this claim row mine?\" calls it —\n * the probe, the single-row upsert's verdict, the batch upsert's verdict, and\n * the batch-validation cache's pending answer.\n *\n * Comparing ids alone accepts a claim held by a namesake under another kind,\n * which is precisely the collision `disjointWith` forbids and precisely the one\n * a shared uniqueness scope exists to catch.\n */\nexport function isSameClaimOwner(left: ClaimOwner, right: ClaimOwner): boolean {\n  return (\n    left.nodeId === right.nodeId && left.concreteKind === right.concreteKind\n  );\n}\n\n/**\n * THE Set/Map key rendering of {@link isSameClaimOwner}, for a path that decides\n * ownership against MANY owners at once rather than pairwise.\n *\n * `encodeTupleKey`, not a delimiter join: kind names are constrained but node\n * ids are arbitrary caller data, and a delimiter a value may contain would make\n * two different owners collapse onto one key — which, where this is used, would\n * silently whitelist a foreign owner. Third rendering of one predicate, in the\n * module that owns it and beside {@link claimOwnerMatchesSql}: keys are equal\n * exactly when `isSameClaimOwner` holds and exactly when the SQL matches.\n */\nexport function claimOwnerKey(owner: ClaimOwner): string {\n  return encodeTupleKey([owner.concreteKind, owner.nodeId]);\n}\n\n/**\n * The owner columns of the uniques relation, by PHYSICAL COLUMN NAME.\n *\n * Names, not column objects: every renderer only ever reads `column.name`\n * (the batch builder's is already typed `(column: Readonly<{name: string}>)`),\n * and taking the name is what lets a backend that has no column objects at all\n * call the one owner of this predicate instead of re-spelling it.\n */\nexport type ClaimOwnerColumnNames = Readonly<{\n  nodeId: string;\n  concreteKind: string;\n}>;\n\n/**\n * THE SQL rendering of {@link isSameClaimOwner}, for the three upsert builders.\n *\n * `existing` qualifies a column of the conflicting row the way the dialect\n * requires (PostgreSQL needs the table name, SQLite takes the bare quoted\n * column); `proposed` renders the value being claimed — a bound parameter for\n * the single-row builders, an `excluded.` reference for the batch one. Two\n * renderings, one definition: the arms every builder decides ownership with\n * are this fragment, so a builder cannot quietly compare fewer columns than\n * the TypeScript predicate does. The dialect switch between the qualified and\n * bare forms is the batch builder's own; this function only composes whatever\n * renderer it is handed. The generic tag keeps that composition portable while\n * allowing an adapter to build its native SQL value directly.\n */\nexport function claimOwnerMatchesSql<TExpression>(\n  tag: (\n    strings: TemplateStringsArray,\n    ...expressions: readonly TExpression[]\n  ) => TExpression,\n  existing: (columnName: string) => TExpression,\n  proposed: (columnName: string) => TExpression,\n  columns: ClaimOwnerColumnNames,\n): TExpression {\n  return tag`${existing(columns.nodeId)} = ${proposed(columns.nodeId)} AND ${existing(columns.concreteKind)} = ${proposed(columns.concreteKind)}`;\n}\n"]}

package/dist/{chunk-WK23PGTP.cjs → chunk-S5GU4LUN.cjs}

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunkTYGGUWMS_cjs = require('./chunk-TYGGUWMS.cjs');
-var chunkTP4NJTI3_cjs = require('./chunk-TP4NJTI3.cjs');
-var chunkZBFZGLZE_cjs = require('./chunk-ZBFZGLZE.cjs');
-var chunkGHZPZNFC_cjs = require('./chunk-GHZPZNFC.cjs');
+var chunkB3MN7EJR_cjs = require('./chunk-B3MN7EJR.cjs');
+var chunk5WWEYV4H_cjs = require('./chunk-5WWEYV4H.cjs');
+var chunkNLX5OWK7_cjs = require('./chunk-NLX5OWK7.cjs');
+var chunkNUQ2YFFH_cjs = require('./chunk-NUQ2YFFH.cjs');
 var chunkX4GDXBOP_cjs = require('./chunk-X4GDXBOP.cjs');
 var pglite = require('@electric-sql/pglite');
 var pglite$1 = require('drizzle-orm/pglite');
@@ -21,7 +21,7 @@ async function loadDefaultPgvectorExtension() {
   }
 }
 async function createLocalPgliteBackend(options = {}) {
-  const tables2 = options.tables ?? chunkTP4NJTI3_cjs.tables;
+  const tables2 = options.tables ?? chunk5WWEYV4H_cjs.tables;
   const vectorExtension = options.vector === false ? void 0 : options.vector ?? await loadDefaultPgvectorExtension();
   const vectorEnabled = vectorExtension !== void 0;
   const client = await pglite.PGlite.create({
@@ -29,22 +29,22 @@ async function createLocalPgliteBackend(options = {}) {
     ...vectorExtension === void 0 ? {} : { extensions: { vector: vectorExtension } }
   });
   try {
-    const migrationSql = vectorEnabled ? chunkTP4NJTI3_cjs.generatePostgresMigrationSQL(tables2) : chunkTP4NJTI3_cjs.generatePostgresDDL(tables2).join("\n\n");
+    const migrationSql = vectorEnabled ? chunk5WWEYV4H_cjs.generatePostgresMigrationSQL(tables2) : chunk5WWEYV4H_cjs.generatePostgresDDL(tables2).join("\n\n");
     await client.exec(migrationSql);
     const db = pglite$1.drizzle(client);
-    const backend = chunkTYGGUWMS_cjs.createPostgresBackend(db, {
+    const backend = chunkB3MN7EJR_cjs.createPostgresBackend(db, {
       tables: tables2,
       ...vectorEnabled ? {} : { vector: false }
     });
-    const managedBackend = chunkZBFZGLZE_cjs.wrapWithManagedClose(backend, async () => {
+    const managedBackend = chunkNLX5OWK7_cjs.wrapWithManagedClose(backend, async () => {
       await client.close();
     });
     return { backend: managedBackend, db, client };
   } catch (error) {
-    return chunkGHZPZNFC_cjs.closeAfterFailure(client, error);
+    return chunkNUQ2YFFH_cjs.closeAfterFailure(client, error);
   }
 }
 
 exports.createLocalPgliteBackend = createLocalPgliteBackend;
-//# sourceMappingURL=chunk-WK23PGTP.cjs.map
-//# sourceMappingURL=chunk-WK23PGTP.cjs.map
+//# sourceMappingURL=chunk-S5GU4LUN.cjs.map
+//# sourceMappingURL=chunk-S5GU4LUN.cjs.map

package/dist/{chunk-WK23PGTP.cjs.map → chunk-S5GU4LUN.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/backend/postgres/pglite.ts"],"names":["ConfigurationError","tables","PGlite","generatePostgresMigrationSQL","generatePostgresDDL","drizzle","createPostgresBackend","wrapWithManagedClose","closeAfterFailure"],"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,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;AAED,EAAA,IAAI;AAGF,IAAA,MAAM,YAAA,GACJ,gBACEC,8CAAA,CAA6BF,OAAM,IACnCG,qCAAA,CAAoBH,OAAM,CAAA,CAAE,IAAA,CAAK,MAAM,CAAA;AAC3C,IAAA,MAAM,MAAA,CAAO,KAAK,YAAY,CAAA;AAE9B,IAAA,MAAM,EAAA,GAAKI,iBAAQ,MAAM,CAAA;AACzB,IAAA,MAAM,OAAA,GAAUC,wCAAsB,EAAA,EAAI;AAAA,MACxC,MAAA,EAAAL,OAAAA;AAAA,MACA,GAAI,aAAA,GAAgB,EAAC,GAAI,EAAE,QAAQ,KAAA;AAAM,KAC1C,CAAA;AACD,IAAA,MAAM,cAAA,GAAiBM,sCAAA,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,OAAOC,mCAAA,CAAkB,QAAQ,KAAK,CAAA;AAAA,EACxC;AACF","file":"chunk-WK23PGTP.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/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"]}
+{"version":3,"sources":["../src/backend/postgres/pglite.ts"],"names":["ConfigurationError","tables","PGlite","generatePostgresMigrationSQL","generatePostgresDDL","drizzle","createPostgresBackend","wrapWithManagedClose","closeAfterFailure"],"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,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;AAED,EAAA,IAAI;AAGF,IAAA,MAAM,YAAA,GACJ,gBACEC,8CAAA,CAA6BF,OAAM,IACnCG,qCAAA,CAAoBH,OAAM,CAAA,CAAE,IAAA,CAAK,MAAM,CAAA;AAC3C,IAAA,MAAM,MAAA,CAAO,KAAK,YAAY,CAAA;AAE9B,IAAA,MAAM,EAAA,GAAKI,iBAAQ,MAAM,CAAA;AACzB,IAAA,MAAM,OAAA,GAAUC,wCAAsB,EAAA,EAAI;AAAA,MACxC,MAAA,EAAAL,OAAAA;AAAA,MACA,GAAI,aAAA,GAAgB,EAAC,GAAI,EAAE,QAAQ,KAAA;AAAM,KAC1C,CAAA;AACD,IAAA,MAAM,cAAA,GAAiBM,sCAAA,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,OAAOC,mCAAA,CAAkB,QAAQ,KAAK,CAAA;AAAA,EACxC;AACF","file":"chunk-S5GU4LUN.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/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-S33YQEL7.js → chunk-SDPWO2Z5.js}

@@ -1,7 +1,7 @@
-import { createPostgresBackend } from './chunk-JG5XIJDY.js';
-import { tables, generatePostgresMigrationSQL, generatePostgresDDL } from './chunk-6LEOAIIB.js';
-import { wrapWithManagedClose } from './chunk-IRPYOHRC.js';
-import { closeAfterFailure } from './chunk-PALYTHGM.js';
+import { createPostgresBackend } from './chunk-K67P5DLL.js';
+import { tables, generatePostgresMigrationSQL, generatePostgresDDL } from './chunk-UKOVGCRN.js';
+import { wrapWithManagedClose } from './chunk-QG5VEOKX.js';
+import { closeAfterFailure } from './chunk-LKZDQ2B4.js';
 import { ConfigurationError } from './chunk-YDEJQWOL.js';
 import { PGlite } from '@electric-sql/pglite';
 import { drizzle } from 'drizzle-orm/pglite';
@@ -44,5 +44,5 @@ async function createLocalPgliteBackend(options = {}) {
 }
 
 export { createLocalPgliteBackend };
-//# sourceMappingURL=chunk-S33YQEL7.js.map
-//# sourceMappingURL=chunk-S33YQEL7.js.map
+//# sourceMappingURL=chunk-SDPWO2Z5.js.map
+//# sourceMappingURL=chunk-SDPWO2Z5.js.map

package/dist/{chunk-S33YQEL7.js.map → chunk-SDPWO2Z5.js.map}

@@ -1 +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-S33YQEL7.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"]}
+{"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-SDPWO2Z5.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-6S3PTHL4.js → chunk-SLGGT2XD.js}

@@ -1,4 +1,4 @@
-import { sql } from './chunk-46UGOVRW.js';
+import { sql } from './chunk-7QFRK6PU.js';
 
 // src/query/dialect/vector/pagination.ts
 function vectorPageClause(limit, offset) {
@@ -6,5 +6,5 @@ function vectorPageClause(limit, offset) {
 }
 
 export { vectorPageClause };
-//# sourceMappingURL=chunk-6S3PTHL4.js.map
-//# sourceMappingURL=chunk-6S3PTHL4.js.map
+//# sourceMappingURL=chunk-SLGGT2XD.js.map
+//# sourceMappingURL=chunk-SLGGT2XD.js.map

package/dist/{chunk-6S3PTHL4.js.map → chunk-SLGGT2XD.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/query/dialect/vector/pagination.ts"],"names":[],"mappings":";;;AAcO,SAAS,gBAAA,CAAiB,OAAe,MAAA,EAA8B;AAC5E,EAAA,OAAO,MAAA,KAAW,MAAA,IAAa,MAAA,KAAW,CAAA,GACtC,GAAA,CAAA,MAAA,EAAY,KAAK,CAAA,CAAA,GACjB,GAAA,CAAA,MAAA,EAAY,KAAK,CAAA,QAAA,EAAW,MAAM,CAAA,CAAA;AACxC","file":"chunk-6S3PTHL4.js","sourcesContent":["/**\n * Shared vector-search pagination clause.\n *\n * Every vector strategy pages its ordered relevance scan the same way: emit a\n * bare `LIMIT` for the first page (`offset` unset or `0`), and `LIMIT … OFFSET`\n * only when a non-zero offset must discard the leading rows. The three engines'\n * `buildSearch` methods each repeated this ternary verbatim; it lives here once\n * so the emitted clause can never drift between dialects.\n *\n * `limit` and `offset` ride as bound parameters (never interpolated), so the\n * clause — string and bound values alike — is identical across engines.\n */\nimport { sql, type SqlFragment } from \"../../sql-fragment\";\n\nexport function vectorPageClause(limit: number, offset?: number): SqlFragment {\n  return offset === undefined || offset === 0 ?\n      sql`LIMIT ${limit}`\n    : sql`LIMIT ${limit} OFFSET ${offset}`;\n}\n"]}
+{"version":3,"sources":["../src/query/dialect/vector/pagination.ts"],"names":[],"mappings":";;;AAcO,SAAS,gBAAA,CAAiB,OAAe,MAAA,EAA8B;AAC5E,EAAA,OAAO,MAAA,KAAW,MAAA,IAAa,MAAA,KAAW,CAAA,GACtC,GAAA,CAAA,MAAA,EAAY,KAAK,CAAA,CAAA,GACjB,GAAA,CAAA,MAAA,EAAY,KAAK,CAAA,QAAA,EAAW,MAAM,CAAA,CAAA;AACxC","file":"chunk-SLGGT2XD.js","sourcesContent":["/**\n * Shared vector-search pagination clause.\n *\n * Every vector strategy pages its ordered relevance scan the same way: emit a\n * bare `LIMIT` for the first page (`offset` unset or `0`), and `LIMIT … OFFSET`\n * only when a non-zero offset must discard the leading rows. The three engines'\n * `buildSearch` methods each repeated this ternary verbatim; it lives here once\n * so the emitted clause can never drift between dialects.\n *\n * `limit` and `offset` ride as bound parameters (never interpolated), so the\n * clause — string and bound values alike — is identical across engines.\n */\nimport { sql, type SqlFragment } from \"../../sql-fragment\";\n\nexport function vectorPageClause(limit: number, offset?: number): SqlFragment {\n  return offset === undefined || offset === 0 ?\n      sql`LIMIT ${limit}`\n    : sql`LIMIT ${limit} OFFSET ${offset}`;\n}\n"]}

package/dist/{chunk-HSEZ7X6Y.cjs → chunk-TIJUA4I6.cjs}

@@ -1,8 +1,8 @@
 'use strict';
 
-var chunkKWNWG4RC_cjs = require('./chunk-KWNWG4RC.cjs');
-var chunkTEC24ZDA_cjs = require('./chunk-TEC24ZDA.cjs');
-var chunkOJHD3LXJ_cjs = require('./chunk-OJHD3LXJ.cjs');
+var chunkUYKDYE5D_cjs = require('./chunk-UYKDYE5D.cjs');
+var chunkH2VWDQWC_cjs = require('./chunk-H2VWDQWC.cjs');
+var chunkH5IJSROF_cjs = require('./chunk-H5IJSROF.cjs');
 
 // src/query/dialect/vector/pgvector-strategy.ts
 var TABLE_PREFIX = "tg_vec";
@@ -74,20 +74,20 @@ function operatorClass(metric) {
   }
 }
 function vectorLiteral(embedding, name) {
-  chunkTEC24ZDA_cjs.assertFiniteEmbedding(embedding, name);
-  return chunkOJHD3LXJ_cjs.sql`${`[${embedding.join(",")}]`}::vector`;
+  chunkH2VWDQWC_cjs.assertFiniteEmbedding(embedding, name);
+  return chunkH5IJSROF_cjs.sql`${`[${embedding.join(",")}]`}::vector`;
 }
 function distanceExpression(embeddingColumn, queryEmbedding, metric) {
   const query = vectorLiteral(queryEmbedding, "queryEmbedding");
   switch (metric) {
     case "cosine": {
-      return chunkOJHD3LXJ_cjs.sql`(${embeddingColumn} <=> ${query})`;
+      return chunkH5IJSROF_cjs.sql`(${embeddingColumn} <=> ${query})`;
     }
     case "l2": {
-      return chunkOJHD3LXJ_cjs.sql`(${embeddingColumn} <-> ${query})`;
+      return chunkH5IJSROF_cjs.sql`(${embeddingColumn} <-> ${query})`;
     }
     case "inner_product": {
-      return chunkOJHD3LXJ_cjs.sql`(${embeddingColumn} <#> ${query})`;
+      return chunkH5IJSROF_cjs.sql`(${embeddingColumn} <#> ${query})`;
     }
     default: {
       const _exhaustive = metric;
@@ -96,7 +96,7 @@ function distanceExpression(embeddingColumn, queryEmbedding, metric) {
   }
 }
 function tableName(graphId, nodeKind, fieldPath) {
-  return chunkTEC24ZDA_cjs.vectorPhysicalName(TABLE_PREFIX, graphId, nodeKind, fieldPath);
+  return chunkH2VWDQWC_cjs.vectorPhysicalName(TABLE_PREFIX, graphId, nodeKind, fieldPath);
 }
 var pgvectorStrategy = {
   name: "pgvector",
@@ -104,7 +104,7 @@ var pgvectorStrategy = {
   tableName,
   ownedTables(slot) {
     const table = tableName(slot.graphId, slot.nodeKind, slot.fieldPath);
-    const name = chunkTEC24ZDA_cjs.quoteIdentifier(table);
+    const name = chunkH2VWDQWC_cjs.quoteIdentifier(table);
     const createDdl = [
       `CREATE TABLE IF NOT EXISTS ${name} (
   "graph_id" TEXT NOT NULL,
@@ -117,7 +117,7 @@ var pgvectorStrategy = {
     ];
     return [
       {
-        logicalName: `${chunkTEC24ZDA_cjs.VECTOR_CONTRIBUTION_PREFIX}:${slot.nodeKind}.${slot.fieldPath}`,
+        logicalName: `${chunkH2VWDQWC_cjs.VECTOR_CONTRIBUTION_PREFIX}:${slot.nodeKind}.${slot.fieldPath}`,
         owner: "pgvector",
         tableName: table,
         createDdl,
@@ -126,12 +126,12 @@ var pgvectorStrategy = {
     ];
   },
   buildUpsert(slot, params, timestamp) {
-    const table = chunkOJHD3LXJ_cjs.sql.identifier(
+    const table = chunkH5IJSROF_cjs.sql.identifier(
       tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
     const value = vectorLiteral(params.embedding, "embedding");
     return [
-      chunkOJHD3LXJ_cjs.sql`
+      chunkH5IJSROF_cjs.sql`
         INSERT INTO ${table} ("graph_id", "node_id", "embedding", "created_at", "updated_at")
         VALUES (${params.graphId}, ${params.nodeId}, ${value}, ${timestamp}, ${timestamp})
         ON CONFLICT ("graph_id", "node_id")
@@ -140,17 +140,17 @@ var pgvectorStrategy = {
     ];
   },
   buildUpsertBatch(slot, params, timestamp) {
-    const table = chunkOJHD3LXJ_cjs.sql.identifier(
+    const table = chunkH5IJSROF_cjs.sql.identifier(
       tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
-    const valueRows = chunkOJHD3LXJ_cjs.sql.join(
+    const valueRows = chunkH5IJSROF_cjs.sql.join(
       params.rows.map(
-        (row) => chunkOJHD3LXJ_cjs.sql`(${params.graphId}, ${row.nodeId}, ${vectorLiteral(row.embedding, "embedding")}, ${timestamp}, ${timestamp})`
+        (row) => chunkH5IJSROF_cjs.sql`(${params.graphId}, ${row.nodeId}, ${vectorLiteral(row.embedding, "embedding")}, ${timestamp}, ${timestamp})`
       ),
-      chunkOJHD3LXJ_cjs.sql`, `
+      chunkH5IJSROF_cjs.sql`, `
     );
     return [
-      chunkOJHD3LXJ_cjs.sql`
+      chunkH5IJSROF_cjs.sql`
         INSERT INTO ${table} ("graph_id", "node_id", "embedding", "created_at", "updated_at")
         VALUES ${valueRows}
         ON CONFLICT ("graph_id", "node_id")
@@ -159,11 +159,11 @@ var pgvectorStrategy = {
     ];
   },
   buildDelete(slot, params) {
-    const table = chunkOJHD3LXJ_cjs.sql.identifier(
+    const table = chunkH5IJSROF_cjs.sql.identifier(
       tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
     return [
-      chunkOJHD3LXJ_cjs.sql`
+      chunkH5IJSROF_cjs.sql`
         DELETE FROM ${table}
         WHERE "graph_id" = ${params.graphId} AND "node_id" = ${params.nodeId}
       `
@@ -171,60 +171,60 @@ var pgvectorStrategy = {
   },
   buildDeleteBatch(slot, params) {
     if (params.nodeIds.length === 0) return [];
-    const table = chunkOJHD3LXJ_cjs.sql.identifier(
+    const table = chunkH5IJSROF_cjs.sql.identifier(
       tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
     return [
-      chunkOJHD3LXJ_cjs.sql`DELETE FROM ${table} WHERE "graph_id" = ${params.graphId} AND "node_id" IN (${chunkOJHD3LXJ_cjs.sql.join(
-        params.nodeIds.map((nodeId) => chunkOJHD3LXJ_cjs.sql`${nodeId}`),
-        chunkOJHD3LXJ_cjs.sql`, `
+      chunkH5IJSROF_cjs.sql`DELETE FROM ${table} WHERE "graph_id" = ${params.graphId} AND "node_id" IN (${chunkH5IJSROF_cjs.sql.join(
+        params.nodeIds.map((nodeId) => chunkH5IJSROF_cjs.sql`${nodeId}`),
+        chunkH5IJSROF_cjs.sql`, `
       )})`
     ];
   },
   buildSearch(slot, params, candidates) {
-    const table = chunkOJHD3LXJ_cjs.sql.identifier(
+    const table = chunkH5IJSROF_cjs.sql.identifier(
       tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
-    const embeddingColumn = chunkOJHD3LXJ_cjs.sql`${table}."embedding"`;
+    const embeddingColumn = chunkH5IJSROF_cjs.sql`${table}."embedding"`;
     const distance = distanceExpression(
       embeddingColumn,
       params.queryEmbedding,
       params.metric
     );
-    const score = chunkTEC24ZDA_cjs.vectorScoreExpression(distance, params.metric);
+    const score = chunkH2VWDQWC_cjs.vectorScoreExpression(distance, params.metric);
     const conditions = [
-      chunkOJHD3LXJ_cjs.sql`${table}."graph_id" = ${params.graphId}`
+      chunkH5IJSROF_cjs.sql`${table}."graph_id" = ${params.graphId}`
     ];
     if (params.minScore !== void 0) {
       conditions.push(
-        chunkTEC24ZDA_cjs.vectorMinScoreCondition(distance, params.metric, params.minScore)
+        chunkH2VWDQWC_cjs.vectorMinScoreCondition(distance, params.metric, params.minScore)
       );
     }
     if (candidates !== void 0) {
-      conditions.push(chunkOJHD3LXJ_cjs.sql`${table}."node_id" IN (${candidates})`);
+      conditions.push(chunkH5IJSROF_cjs.sql`${table}."node_id" IN (${candidates})`);
     }
     const pageOffset = params.offset ?? 0;
-    const pageClause = chunkKWNWG4RC_cjs.vectorPageClause(params.limit, params.offset);
+    const pageClause = chunkUYKDYE5D_cjs.vectorPageClause(params.limit, params.offset);
     if (slot.indexType === "ivfflat") {
-      const direction = params.metric === "cosine" ? chunkOJHD3LXJ_cjs.sql.raw("DESC") : chunkOJHD3LXJ_cjs.sql.raw("ASC");
-      const relaxedBody = chunkOJHD3LXJ_cjs.sql`
+      const direction = params.metric === "cosine" ? chunkH5IJSROF_cjs.sql.raw("DESC") : chunkH5IJSROF_cjs.sql.raw("ASC");
+      const relaxedBody = chunkH5IJSROF_cjs.sql`
         SELECT ${table}."node_id" AS node_id, ${score} AS score
         FROM ${table}
-        WHERE ${chunkOJHD3LXJ_cjs.sql.join(conditions, chunkOJHD3LXJ_cjs.sql` AND `)}
+        WHERE ${chunkH5IJSROF_cjs.sql.join(conditions, chunkH5IJSROF_cjs.sql` AND `)}
         ORDER BY ${distance} ASC
         LIMIT ${params.limit + pageOffset}
       `;
-      return chunkOJHD3LXJ_cjs.sql`
+      return chunkH5IJSROF_cjs.sql`
         WITH tg_vec_relaxed AS MATERIALIZED (${relaxedBody})
         SELECT node_id, score FROM tg_vec_relaxed
         ORDER BY score ${direction}, node_id ASC
         ${pageClause}
       `;
     }
-    return chunkOJHD3LXJ_cjs.sql`
+    return chunkH5IJSROF_cjs.sql`
       SELECT ${table}."node_id" AS node_id, ${score} AS score
       FROM ${table}
-      WHERE ${chunkOJHD3LXJ_cjs.sql.join(conditions, chunkOJHD3LXJ_cjs.sql` AND `)}
+      WHERE ${chunkH5IJSROF_cjs.sql.join(conditions, chunkH5IJSROF_cjs.sql` AND `)}
       ORDER BY ${distance} ASC
       ${pageClause}
     `;
@@ -234,7 +234,7 @@ var pgvectorStrategy = {
   },
   buildCreateIndex(slot, options) {
     if (!usesAnnIndex(slot)) return void 0;
-    return chunkOJHD3LXJ_cjs.sql.raw(
+    return chunkH5IJSROF_cjs.sql.raw(
       pgvectorIndexDdl(
         tableName(slot.graphId, slot.nodeKind, slot.fieldPath),
         slot,
@@ -245,17 +245,17 @@ var pgvectorStrategy = {
   buildDropIndex(slot) {
     if (!usesAnnIndex(slot)) return void 0;
     const indexName = pgvectorIndexName(slot);
-    return chunkOJHD3LXJ_cjs.sql.raw(`DROP INDEX IF EXISTS ${chunkTEC24ZDA_cjs.quoteIdentifier(indexName)}`);
+    return chunkH5IJSROF_cjs.sql.raw(`DROP INDEX IF EXISTS ${chunkH2VWDQWC_cjs.quoteIdentifier(indexName)}`);
   },
   buildDropStorage(slot) {
-    const table = chunkTEC24ZDA_cjs.quoteIdentifier(
+    const table = chunkH2VWDQWC_cjs.quoteIdentifier(
       tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
     return [`DROP TABLE IF EXISTS ${table} CASCADE`];
   }
 };
 function pgvectorIndexName(slot) {
-  return chunkTEC24ZDA_cjs.vectorPhysicalName(
+  return chunkH2VWDQWC_cjs.vectorPhysicalName(
     INDEX_PREFIX,
     slot.graphId,
     slot.nodeKind,
@@ -263,8 +263,8 @@ function pgvectorIndexName(slot) {
   );
 }
 function pgvectorIndexDdl(table, slot, concurrent) {
-  const indexName = chunkTEC24ZDA_cjs.quoteIdentifier(pgvectorIndexName(slot));
-  const quotedTable = chunkTEC24ZDA_cjs.quoteIdentifier(table);
+  const indexName = chunkH2VWDQWC_cjs.quoteIdentifier(pgvectorIndexName(slot));
+  const quotedTable = chunkH2VWDQWC_cjs.quoteIdentifier(table);
   const opClass = operatorClass(slot.metric);
   const m = slot.indexParams?.m ?? DEFAULT_HNSW_M;
   const efConstruction = slot.indexParams?.efConstruction ?? DEFAULT_HNSW_EF_CONSTRUCTION;
@@ -291,5 +291,5 @@ function pgvectorIndexDdl(table, slot, concurrent) {
 
 exports.assertPgvectorEfSearch = assertPgvectorEfSearch;
 exports.pgvectorStrategy = pgvectorStrategy;
-//# sourceMappingURL=chunk-HSEZ7X6Y.cjs.map
-//# sourceMappingURL=chunk-HSEZ7X6Y.cjs.map
+//# sourceMappingURL=chunk-TIJUA4I6.cjs.map
+//# sourceMappingURL=chunk-TIJUA4I6.cjs.map