@nicia-ai/typegraph 0.37.1 → 0.39.0

package/dist/chunk-X4PVHAZ6.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+var chunkSAFZ6JTI_cjs = require('./chunk-SAFZ6JTI.cjs');
+
+// src/errors/validation.ts
+function zodIssuesToValidationIssues(error) {
+  return error.issues.map((issue) => ({
+    path: issue.path.join("."),
+    message: issue.message,
+    code: issue.code
+  }));
+}
+function buildLocationString(context) {
+  if (context.id) {
+    return `${context.kind}/${context.id}`;
+  }
+  return `new ${context.kind}`;
+}
+function validateProps(schema, props, context) {
+  const result = schema.safeParse(props);
+  if (result.success) {
+    return result.data;
+  }
+  const issues = zodIssuesToValidationIssues(result.error);
+  const location = buildLocationString(context);
+  throw new chunkSAFZ6JTI_cjs.ValidationError(
+    `Invalid ${context.entityType} props for ${location}: ${result.error.message}`,
+    {
+      entityType: context.entityType,
+      kind: context.kind,
+      operation: context.operation,
+      ...context.id !== void 0 && { id: context.id },
+      issues
+    },
+    { cause: result.error }
+  );
+}
+function validateNodeProps(schema, props, context) {
+  return validateProps(schema, props, {
+    entityType: "node",
+    ...context
+  });
+}
+function validateEdgeProps(schema, props, context) {
+  return validateProps(schema, props, {
+    entityType: "edge",
+    ...context
+  });
+}
+function wrapZodError(error, context) {
+  const issues = zodIssuesToValidationIssues(error);
+  const location = buildLocationString(context);
+  return new chunkSAFZ6JTI_cjs.ValidationError(
+    `Validation failed for ${context.entityType} ${location}: ${error.message}`,
+    {
+      entityType: context.entityType,
+      kind: context.kind,
+      operation: context.operation,
+      ...context.id !== void 0 && { id: context.id },
+      issues
+    },
+    { cause: error }
+  );
+}
+function createValidationError(message, issues, context) {
+  return new chunkSAFZ6JTI_cjs.ValidationError(message, {
+    ...context?.entityType !== void 0 && {
+      entityType: context.entityType
+    },
+    ...context?.kind !== void 0 && { kind: context.kind },
+    ...context?.operation !== void 0 && { operation: context.operation },
+    ...context?.id !== void 0 && { id: context.id },
+    issues
+  });
+}
+
+exports.createValidationError = createValidationError;
+exports.validateEdgeProps = validateEdgeProps;
+exports.validateNodeProps = validateNodeProps;
+exports.validateProps = validateProps;
+exports.wrapZodError = wrapZodError;
+//# sourceMappingURL=chunk-X4PVHAZ6.cjs.map
+//# sourceMappingURL=chunk-X4PVHAZ6.cjs.map

package/dist/chunk-X4PVHAZ6.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors/validation.ts"],"names":["ValidationError"],"mappings":"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","file":"chunk-X4PVHAZ6.cjs","sourcesContent":["/**\n * Contextual Validation Utilities\n *\n * Provides Zod validation wrappers that include full context about\n * which entity (node/edge) and operation (create/update) failed.\n *\n * @example\n * ```typescript\n * const props = validateNodeProps(schema, input, {\n *   kind: \"Person\",\n *   operation: \"create\",\n * });\n * ```\n */\n\nimport { type ZodError, type ZodType } from \"zod\";\n\nimport type { KindEntity } from \"../core/types\";\nimport { ValidationError, type ValidationIssue } from \"./index\";\n\n// ============================================================\n// Types\n// ============================================================\n\n/**\n * Context for validation operations.\n */\nexport type ValidationContext = Readonly<{\n  /** Type of entity being validated */\n  entityType: KindEntity;\n  /** Kind/type name of the entity */\n  kind: string;\n  /** Operation being performed */\n  operation: \"create\" | \"update\";\n  /** Entity ID (for updates) */\n  id?: string;\n}>;\n\n// ============================================================\n// Validation Functions\n// ============================================================\n\n/**\n * Converts Zod issues to ValidationIssue format.\n */\nfunction zodIssuesToValidationIssues(error: ZodError): ValidationIssue[] {\n  return error.issues.map((issue) => ({\n    path: issue.path.join(\".\"),\n    message: issue.message,\n    code: issue.code,\n  }));\n}\n\n/**\n * Builds a descriptive location string for error messages.\n */\nfunction buildLocationString(context: ValidationContext): string {\n  if (context.id) {\n    return `${context.kind}/${context.id}`;\n  }\n  return `new ${context.kind}`;\n}\n\n/**\n * Validates props with full context for error messages.\n *\n * @param schema - Zod schema to validate against\n * @param props - Properties to validate\n * @param context - Context about the entity and operation\n * @returns Validated and transformed props\n * @throws ValidationError with full context if validation fails\n *\n * @example\n * ```typescript\n * const validatedProps = validateProps(personSchema, input, {\n *   entityType: \"node\",\n *   kind: \"Person\",\n *   operation: \"create\",\n * });\n * ```\n */\nexport function validateProps<T>(\n  schema: ZodType<T>,\n  props: unknown,\n  context: ValidationContext,\n): T {\n  const result = schema.safeParse(props);\n\n  if (result.success) {\n    return result.data;\n  }\n\n  const issues = zodIssuesToValidationIssues(result.error);\n  const location = buildLocationString(context);\n\n  throw new ValidationError(\n    `Invalid ${context.entityType} props for ${location}: ${result.error.message}`,\n    {\n      entityType: context.entityType,\n      kind: context.kind,\n      operation: context.operation,\n      ...(context.id !== undefined && { id: context.id }),\n      issues,\n    },\n    { cause: result.error },\n  );\n}\n\n/**\n * Validates node props with full context.\n *\n * Convenience wrapper around validateProps for node operations.\n *\n * @example\n * ```typescript\n * const props = validateNodeProps(schema, input, {\n *   kind: \"Person\",\n *   operation: \"create\",\n * });\n * ```\n */\nexport function validateNodeProps<T>(\n  schema: ZodType<T>,\n  props: unknown,\n  context: Readonly<{\n    kind: string;\n    operation: \"create\" | \"update\";\n    id?: string;\n  }>,\n): T {\n  return validateProps(schema, props, {\n    entityType: \"node\",\n    ...context,\n  });\n}\n\n/**\n * Validates edge props with full context.\n *\n * Convenience wrapper around validateProps for edge operations.\n *\n * @example\n * ```typescript\n * const props = validateEdgeProps(schema, input, {\n *   kind: \"worksAt\",\n *   operation: \"create\",\n * });\n * ```\n */\nexport function validateEdgeProps<T>(\n  schema: ZodType<T>,\n  props: unknown,\n  context: Readonly<{\n    kind: string;\n    operation: \"create\" | \"update\";\n    id?: string;\n  }>,\n): T {\n  return validateProps(schema, props, {\n    entityType: \"edge\",\n    ...context,\n  });\n}\n\n/**\n * Wraps a Zod error with TypeGraph context.\n *\n * Use this when you've already caught a ZodError and want to\n * convert it to a ValidationError with context.\n *\n * @example\n * ```typescript\n * try {\n *   schema.parse(input);\n * } catch (error) {\n *   if (error instanceof ZodError) {\n *     throw wrapZodError(error, {\n *       entityType: \"node\",\n *       kind: \"Person\",\n *       operation: \"create\",\n *     });\n *   }\n *   throw error;\n * }\n * ```\n */\nexport function wrapZodError(\n  error: ZodError,\n  context: ValidationContext,\n): ValidationError {\n  const issues = zodIssuesToValidationIssues(error);\n  const location = buildLocationString(context);\n\n  return new ValidationError(\n    `Validation failed for ${context.entityType} ${location}: ${error.message}`,\n    {\n      entityType: context.entityType,\n      kind: context.kind,\n      operation: context.operation,\n      ...(context.id !== undefined && { id: context.id }),\n      issues,\n    },\n    { cause: error },\n  );\n}\n\n/**\n * Creates a simple ValidationError without Zod context.\n *\n * Use this for custom validation rules that aren't part of a Zod schema.\n *\n * @example\n * ```typescript\n * if (startDate > endDate) {\n *   throw createValidationError(\n *     \"Start date must be before end date\",\n *     [{ path: \"startDate\", message: \"Must be before endDate\" }],\n *     { entityType: \"edge\", kind: \"employment\", operation: \"create\" }\n *   );\n * }\n * ```\n */\nexport function createValidationError(\n  message: string,\n  issues: ValidationIssue[],\n  context?: Partial<ValidationContext>,\n): ValidationError {\n  return new ValidationError(message, {\n    ...(context?.entityType !== undefined && {\n      entityType: context.entityType,\n    }),\n    ...(context?.kind !== undefined && { kind: context.kind }),\n    ...(context?.operation !== undefined && { operation: context.operation }),\n    ...(context?.id !== undefined && { id: context.id }),\n    issues,\n  });\n}\n"]}

package/dist/{chunk-UYQMBBWJ.js → chunk-X6CNEA32.js}

@@ -1,8 +1,8 @@
-import { vectorPageClause } from './chunk-DFVLCOP6.js';
-import { quoteIdentifier, vectorScoreExpression, vectorMinScoreCondition, VECTOR_CONTRIBUTION_PREFIX, vectorPhysicalName, assertFiniteEmbedding } from './chunk-EXU3RASM.js';
-import { quotedTableName } from './chunk-OHMP6N2J.js';
-import { sql } from 'drizzle-orm';
+import { vectorPageClause } from './chunk-EZH7FNUS.js';
+import { vectorPhysicalName, quoteIdentifier, vectorScoreExpression, vectorMinScoreCondition, VECTOR_CONTRIBUTION_PREFIX, assertFiniteEmbedding } from './chunk-Y7M44XEK.js';
+import { sql } from './chunk-6XDBRDZE.js';
 
+// src/query/dialect/vector/sqlite-vec-strategy.ts
 var TABLE_PREFIX = "tg_vec";
 var SQLITE_VEC_MAX_DIMENSIONS = 8e3;
 var SQLITE_VEC_CAPABILITIES = {
@@ -68,14 +68,15 @@ function distanceExpression(embeddingColumn, queryEmbedding, metric) {
     }
   }
 }
+function tableName(graphId, nodeKind, fieldPath) {
+  return vectorPhysicalName(TABLE_PREFIX, graphId, nodeKind, fieldPath);
+}
 var sqliteVecStrategy = {
   name: "sqlite-vec",
   capabilities: SQLITE_VEC_CAPABILITIES,
-  tableName(graphId, nodeKind, fieldPath) {
-    return vectorPhysicalName(TABLE_PREFIX, graphId, nodeKind, fieldPath);
-  },
+  tableName,
   ownedTables(slot) {
-    const table = this.tableName(slot.graphId, slot.nodeKind, slot.fieldPath);
+    const table = tableName(slot.graphId, slot.nodeKind, slot.fieldPath);
     const name = quoteIdentifier(table);
     const metric = sqliteVecMetricToken(slot.metric);
     return [
@@ -97,8 +98,8 @@ var sqliteVecStrategy = {
     ];
   },
   buildUpsert(slot, params, timestamp) {
-    const table = quotedTableName(
-      this.tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
+    const table = sql.identifier(
+      tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
     const value = vecF32Literal(params.embedding, "embedding");
     return [
@@ -113,8 +114,8 @@ var sqliteVecStrategy = {
     ];
   },
   buildUpsertBatch(slot, params, timestamp) {
-    const table = quotedTableName(
-      this.tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
+    const table = sql.identifier(
+      tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
     const nodeIds = sql.join(
       params.rows.map((row) => sql`${row.nodeId}`),
@@ -138,8 +139,8 @@ var sqliteVecStrategy = {
     ];
   },
   buildDelete(slot, params) {
-    const table = quotedTableName(
-      this.tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
+    const table = sql.identifier(
+      tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
     return [
       sql`
@@ -154,8 +155,8 @@ var sqliteVecStrategy = {
   // route the NON-approximate `.similarTo()` branch through this form.
   searchIsExact: true,
   buildSearch(slot, params, candidates) {
-    const table = quotedTableName(
-      this.tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
+    const table = sql.identifier(
+      tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
     const embeddingColumn = sql`${table}."embedding"`;
     const distance = distanceExpression(
@@ -195,7 +196,9 @@ var sqliteVecStrategy = {
         LIMIT ${params.limit} OFFSET ${params.offset}
       `;
     }
-    const conditions = [sql`${table}."graph_id" = ${params.graphId}`];
+    const conditions = [
+      sql`${table}."graph_id" = ${params.graphId}`
+    ];
     if (candidates !== void 0) {
       conditions.push(sql`${table}."node_id" IN (${candidates})`);
     }
@@ -226,12 +229,12 @@ var sqliteVecStrategy = {
   },
   buildDropStorage(slot) {
     const table = quoteIdentifier(
-      this.tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
+      tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
     return [`DROP TABLE IF EXISTS ${table}`];
   }
 };
 
 export { sqliteVecStrategy };
-//# sourceMappingURL=chunk-UYQMBBWJ.js.map
-//# sourceMappingURL=chunk-UYQMBBWJ.js.map
+//# sourceMappingURL=chunk-X6CNEA32.js.map
+//# sourceMappingURL=chunk-X6CNEA32.js.map

package/dist/chunk-X6CNEA32.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/query/dialect/vector/sqlite-vec-strategy.ts"],"names":["conditions"],"mappings":"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","file":"chunk-X6CNEA32.js","sourcesContent":["/**\n * sqlite-vec strategy — real `vec0` KNN for local SQLite.\n *\n * This upgrades `createLocalSqliteBackend` (better-sqlite3 + the sqlite-vec\n * extension) from the legacy brute-force-on-a-shared-table model to genuine\n * approximate-nearest-neighbor search on per-`(nodeKind, fieldPath)` storage.\n *\n * ## Storage choice: a `vec0` virtual table per field\n *\n * Each slot is backed by its own `vec0` virtual table:\n *\n * ```sql\n * CREATE VIRTUAL TABLE tg_vec_<kind>_<field> USING vec0(\n *   node_id TEXT PRIMARY KEY,\n *   graph_id TEXT PARTITION KEY,\n *   +created_at TEXT,\n *   +updated_at TEXT,\n *   embedding float[<N>] distance_metric=<cosine|l2>\n * );\n * ```\n *\n * Verified against the installed `sqlite-vec` `v0.1.9`:\n *\n * - **vec0 over a plain `vec_f32` BLOB column.** The shipped option (a) — a\n *   `vec0` virtual table — is chosen over option (b) — a regular table whose\n *   `vec_f32` BLOB column is brute-forced — because vec0 is the *only* form\n *   that gives local SQLite a real ANN index (today's code only ever\n *   brute-forces). vec0 indexes inline (the virtual table *is* the index), so\n *   there is no separate `CREATE INDEX` step.\n * - **KNN with partition-correct filtering.** `WHERE embedding MATCH vec_f32(q)\n *   AND k = ? AND graph_id = ?` returns the nearest `k`, ordered by `distance`,\n *   scoped to one graph — a near vector in another `graph_id` partition does\n *   not leak. This is strictly better than libSQL's table-global `vector_top_k`\n *   (which over-fetches for multi-graph correctness): vec0's `PARTITION KEY`\n *   makes the per-graph KNN exact.\n * - **One table serves both read paths.** The same `embedding` column answers\n *   the compiler's brute-force `distanceExpression` (`vec_distance_cosine` /\n *   `vec_distance_l2` over the column, `ORDER BY … LIMIT`, no `MATCH`), so the\n *   `.where(field.similarTo(...))` CTE path needs no second structure.\n * - **`k` and `LIMIT` are mutually exclusive** in a vec0 `MATCH` query, so the\n *   ANN path uses `k = <limit>` with no `LIMIT`, and the brute-force path uses\n *   `LIMIT <limit>` with no `MATCH`.\n * - **No `ON CONFLICT` / `INSERT OR REPLACE`** on a vec0 primary key, so upsert\n *   is `DELETE` + `INSERT` (atomic under the caller's outer transaction),\n *   mirroring the FTS5 strategy.\n *\n * Metric support is `cosine` + `l2` (no `inner_product` — sqlite-vec has no\n * `vec_distance_ip`), advertised as data on `capabilities`. The table's\n * `distance_metric` is fixed at creation from the slot's metric, alongside its\n * fixed dimension `N`.\n *\n * The libSQL and pgvector siblings implement the same `VectorStrategy`\n * contract for their engines.\n */\nimport { type StrategyTableContribution } from \"../../../backend/table-contribution\";\nimport {\n  type DeleteEmbeddingParams,\n  type UpsertEmbeddingBatchParams,\n  type UpsertEmbeddingParams,\n  type VectorCapabilities,\n  type VectorMetric,\n  type VectorSearchParams,\n} from \"../../../backend/types\";\nimport { sql, type SqlFragment } from \"../../sql-fragment\";\nimport {\n  assertFiniteEmbedding,\n  quoteIdentifier,\n  VECTOR_CONTRIBUTION_PREFIX,\n  vectorMinScoreCondition,\n  vectorPhysicalName,\n  vectorScoreExpression,\n  type VectorSlot,\n  type VectorStrategy,\n} from \"../vector-strategy\";\nimport { vectorPageClause } from \"./pagination\";\n\n/** Physical-name prefix for the per-field `vec0` virtual table. */\nconst TABLE_PREFIX = \"tg_vec\";\n\n/**\n * sqlite-vec stores each dimension as a 32-bit float; `float[N]` accepts\n * large `N`, but we advertise the same conservative ceiling the legacy\n * SQLite path used so capability discovery is stable across the swap.\n */\nconst SQLITE_VEC_MAX_DIMENSIONS = 8000;\n\nconst SQLITE_VEC_CAPABILITIES: VectorCapabilities = {\n  supported: true,\n  metrics: [\"cosine\", \"l2\"],\n  // vec0 always indexes inline, so the portable ANN intent (\"hnsw\", the\n  // `embedding()` default) is honored by real KNN; \"none\" stays brute-force.\n  // Both map to the same vec0 table — only `buildSearch` differs.\n  indexTypes: [\"hnsw\", \"none\"],\n  maxDimensions: SQLITE_VEC_MAX_DIMENSIONS,\n  // vec0's KNN accepts primary-key `IN (SELECT …)` pushdown (verified on\n  // sqlite-vec v0.1.9), so the candidate filter constrains the KNN itself and\n  // a filtered search returns `k` live rows — no over-fetch, no scan bound, no\n  // under-fill. The only bundled engine that can promise a full page.\n  filteredApproximateSearch: {\n    mode: \"filter-pushdown\",\n    guaranteesFullPage: true,\n  },\n};\n\n/** Whether a slot's declared index type maps to vec0's `MATCH … k =` KNN. */\nfunction usesAnnIndex(slot: VectorSlot): boolean {\n  return slot.indexType === \"hnsw\";\n}\n\n/** vec0 `distance_metric` token accepted in the virtual-table definition. */\nfunction sqliteVecMetricToken(metric: VectorMetric): string {\n  switch (metric) {\n    case \"cosine\": {\n      return \"cosine\";\n    }\n    case \"l2\": {\n      return \"l2\";\n    }\n    case \"inner_product\": {\n      throw new Error(\n        \"sqlite-vec does not support inner_product. Use 'cosine' or 'l2'.\",\n      );\n    }\n    default: {\n      const _exhaustive: never = metric;\n      throw new Error(`Unsupported vector metric: ${String(_exhaustive)}`);\n    }\n  }\n}\n\n/**\n * Formats an embedding as the bound JSON argument to `vec_f32(...)`. The\n * value rides as a parameter (not interpolated) — `vec_f32` parses the JSON\n * array into the packed float blob. Finiteness is validated first so a\n * NaN/Infinity names its index before JSON.stringify masks it as `null`.\n */\nfunction vecF32Literal(\n  embedding: readonly number[],\n  name: string,\n): SqlFragment {\n  assertFiniteEmbedding(embedding, name);\n  return sql`vec_f32(${JSON.stringify(embedding)})`;\n}\n\nfunction distanceExpression(\n  embeddingColumn: SqlFragment,\n  queryEmbedding: readonly number[],\n  metric: VectorMetric,\n): SqlFragment {\n  const query = vecF32Literal(queryEmbedding, \"queryEmbedding\");\n  switch (metric) {\n    case \"cosine\": {\n      return sql`vec_distance_cosine(${embeddingColumn}, ${query})`;\n    }\n    case \"l2\": {\n      return sql`vec_distance_l2(${embeddingColumn}, ${query})`;\n    }\n    case \"inner_product\": {\n      throw new Error(\n        \"sqlite-vec does not support inner_product. Use 'cosine' or 'l2'.\",\n      );\n    }\n    default: {\n      const _exhaustive: never = metric;\n      throw new Error(`Unsupported vector metric: ${String(_exhaustive)}`);\n    }\n  }\n}\n\nfunction tableName(\n  graphId: string,\n  nodeKind: string,\n  fieldPath: string,\n): string {\n  return vectorPhysicalName(TABLE_PREFIX, graphId, nodeKind, fieldPath);\n}\n\nexport const sqliteVecStrategy: VectorStrategy = {\n  name: \"sqlite-vec\",\n  capabilities: SQLITE_VEC_CAPABILITIES,\n\n  tableName,\n\n  ownedTables(slot): readonly StrategyTableContribution[] {\n    const table = tableName(slot.graphId, slot.nodeKind, slot.fieldPath);\n    const name = quoteIdentifier(table);\n    const metric = sqliteVecMetricToken(slot.metric);\n\n    // vec0 virtual tables cannot be modeled as a Drizzle table, so this is a\n    // raw-ddl contribution — emitted verbatim and invisible to drizzle-kit.\n    // `graph_id` is a PARTITION KEY so per-graph KNN is exact; `created_at` /\n    // `updated_at` are auxiliary (`+`) columns (stored, not filtered on). The\n    // virtual table *is* the index — no separate CREATE INDEX is emitted.\n    return [\n      {\n        logicalName: `${VECTOR_CONTRIBUTION_PREFIX}:${slot.nodeKind}.${slot.fieldPath}`,\n        owner: \"sqlite-vec\",\n        tableName: table,\n        createDdl: [\n          `CREATE VIRTUAL TABLE IF NOT EXISTS ${name} USING vec0(\n  node_id TEXT PRIMARY KEY,\n  graph_id TEXT PARTITION KEY,\n  +created_at TEXT,\n  +updated_at TEXT,\n  embedding float[${slot.dimensions}] distance_metric=${metric}\n);`,\n        ],\n        runtimeEnsure: true,\n      },\n    ];\n  },\n\n  buildUpsert(\n    slot,\n    params: UpsertEmbeddingParams,\n    timestamp,\n  ): readonly SqlFragment[] {\n    const table = sql.identifier(\n      tableName(slot.graphId, slot.nodeKind, slot.fieldPath),\n    );\n    const value = vecF32Literal(params.embedding, \"embedding\");\n    // vec0 rejects ON CONFLICT / INSERT OR REPLACE on its primary key —\n    // emulate upsert with DELETE + INSERT, atomic under the caller's\n    // outer transaction (mirrors the FTS5 fulltext strategy).\n    return [\n      sql`\n        DELETE FROM ${table}\n        WHERE \"node_id\" = ${params.nodeId} AND \"graph_id\" = ${params.graphId}\n      `,\n      sql`\n        INSERT INTO ${table} (\"node_id\", \"graph_id\", \"created_at\", \"updated_at\", \"embedding\")\n        VALUES (${params.nodeId}, ${params.graphId}, ${timestamp}, ${timestamp}, ${value})\n      `,\n    ];\n  },\n\n  buildUpsertBatch(\n    slot,\n    params: UpsertEmbeddingBatchParams,\n    timestamp,\n  ): readonly SqlFragment[] {\n    const table = sql.identifier(\n      tableName(slot.graphId, slot.nodeKind, slot.fieldPath),\n    );\n    // Same DELETE + INSERT upsert emulation as buildUpsert, in multi-row\n    // form: one IN-list delete, one multi-row insert.\n    const nodeIds = sql.join(\n      params.rows.map((row) => sql`${row.nodeId}`),\n      sql`, `,\n    );\n    const valueRows = sql.join(\n      params.rows.map(\n        (row) =>\n          sql`(${row.nodeId}, ${params.graphId}, ${timestamp}, ${timestamp}, ${vecF32Literal(row.embedding, \"embedding\")})`,\n      ),\n      sql`, `,\n    );\n    return [\n      sql`\n        DELETE FROM ${table}\n        WHERE \"graph_id\" = ${params.graphId} AND \"node_id\" IN (${nodeIds})\n      `,\n      sql`\n        INSERT INTO ${table} (\"node_id\", \"graph_id\", \"created_at\", \"updated_at\", \"embedding\")\n        VALUES ${valueRows}\n      `,\n    ];\n  },\n\n  buildDelete(slot, params: DeleteEmbeddingParams): readonly SqlFragment[] {\n    const table = sql.identifier(\n      tableName(slot.graphId, slot.nodeKind, slot.fieldPath),\n    );\n    return [\n      sql`\n        DELETE FROM ${table}\n        WHERE \"node_id\" = ${params.nodeId} AND \"graph_id\" = ${params.graphId}\n      `,\n    ];\n  },\n\n  // vec0's KNN is brute force in C — exact by construction (the\n  // \"index\" is a partitioned scan, not a graph) — and the non-indexed\n  // fallback below is a plain SQL scan. The compiler may therefore\n  // route the NON-approximate `.similarTo()` branch through this form.\n  searchIsExact: true,\n\n  buildSearch(\n    slot,\n    params: VectorSearchParams,\n    candidates?: SqlFragment,\n  ): SqlFragment {\n    const table = sql.identifier(\n      tableName(slot.graphId, slot.nodeKind, slot.fieldPath),\n    );\n    const embeddingColumn = sql`${table}.\"embedding\"`;\n    const distance = distanceExpression(\n      embeddingColumn,\n      params.queryEmbedding,\n      params.metric,\n    );\n    const score = vectorScoreExpression(distance, params.metric);\n\n    if (usesAnnIndex(slot)) {\n      // vec0 KNN. `k` and `LIMIT` are mutually exclusive in a MATCH query, so\n      // bound `k = limit` and omit LIMIT. `graph_id` filters by the partition\n      // key (exact, no recall loss). Order by vec0's own `distance` column —\n      // the recomputed `distance` expression is reused only for score/minScore\n      // so the math matches the brute-force path and the shared helpers.\n      const query = vecF32Literal(params.queryEmbedding, \"queryEmbedding\");\n      // `k` covers the requested page: vec0 has no OFFSET inside a MATCH\n      // query, so fetch `limit + offset` neighbors and page in a wrapper.\n      const knnK = params.limit + (params.offset ?? 0);\n      const conditions: SqlFragment[] = [\n        sql`${table}.\"embedding\" MATCH ${query}`,\n        sql`k = ${knnK}`,\n        sql`${table}.\"graph_id\" = ${params.graphId}`,\n      ];\n      if (params.minScore !== undefined) {\n        conditions.push(\n          vectorMinScoreCondition(distance, params.metric, params.minScore),\n        );\n      }\n      // vec0 KNN accepts primary-key `IN (SELECT ...)` pushdown (verified on\n      // sqlite-vec v0.1.9): the filter constrains the KNN candidate set\n      // itself, so `k` live results come back — exact, no over-fetch.\n      if (candidates !== undefined) {\n        conditions.push(sql`${table}.\"node_id\" IN (${candidates})`);\n      }\n      const knnBody = sql`\n        SELECT ${table}.\"node_id\" AS node_id, ${score} AS score\n        FROM ${table}\n        WHERE ${sql.join(conditions, sql` AND `)}\n        ORDER BY distance ASC\n      `;\n      if (params.offset === undefined || params.offset === 0) {\n        return knnBody;\n      }\n      // MATERIALIZED fences the page wrapper: SQLite would otherwise\n      // flatten the subquery and push the outer LIMIT into the vec0 MATCH\n      // query, which rejects `k = ?` and LIMIT together.\n      return sql`\n        WITH knn_page AS MATERIALIZED (${knnBody})\n        SELECT node_id, score FROM knn_page\n        LIMIT ${params.limit} OFFSET ${params.offset}\n      `;\n    }\n\n    // Brute-force scan: no MATCH, so LIMIT is allowed (and required).\n    const conditions: SqlFragment[] = [\n      sql`${table}.\"graph_id\" = ${params.graphId}`,\n    ];\n    if (candidates !== undefined) {\n      conditions.push(sql`${table}.\"node_id\" IN (${candidates})`);\n    }\n    if (params.minScore !== undefined) {\n      conditions.push(\n        vectorMinScoreCondition(distance, params.metric, params.minScore),\n      );\n    }\n    const pageClause = vectorPageClause(params.limit, params.offset);\n    return sql`\n      SELECT ${table}.\"node_id\" AS node_id, ${score} AS score\n      FROM ${table}\n      WHERE ${sql.join(conditions, sql` AND `)}\n      ORDER BY ${distance} ASC\n      ${pageClause}\n    `;\n  },\n\n  distanceExpression(embeddingColumn, queryEmbedding, metric) {\n    return distanceExpression(embeddingColumn, queryEmbedding, metric);\n  },\n\n  // vec0 indexes inline (the virtual table is the index), so there is no\n  // standalone ANN index to create or drop — both return undefined.\n  buildCreateIndex(): SqlFragment | undefined {\n    return undefined;\n  },\n\n  buildDropIndex(): SqlFragment | undefined {\n    return undefined;\n  },\n\n  buildDropStorage(slot): readonly string[] {\n    const table = quoteIdentifier(\n      tableName(slot.graphId, slot.nodeKind, slot.fieldPath),\n    );\n    // Dropping the vec0 virtual table removes its backing shadow tables too.\n    return [`DROP TABLE IF EXISTS ${table}`];\n  },\n};\n"]}

package/dist/chunk-X6RDQ5NB.cjs

@@ -0,0 +1,335 @@
+'use strict';
+
+var chunkSAFZ6JTI_cjs = require('./chunk-SAFZ6JTI.cjs');
+
+// src/utils/global-symbol.ts
+function typeGraphGlobalSymbol(name) {
+  return /* @__PURE__ */ Symbol.for(`@nicia-ai/typegraph/${name}`);
+}
+
+// src/query/dialect/profile.ts
+var SQL_DIALECT_PROFILES = {
+  postgres: {
+    bindValue: (value) => value,
+    booleanLiteralString: (value) => value ? "TRUE" : "FALSE",
+    placeholder: (index) => `$${index}`
+  },
+  sqlite: {
+    bindValue: (value) => typeof value === "boolean" ? value ? 1 : 0 : value,
+    booleanLiteralString: (value) => value ? "1" : "0",
+    placeholder: () => "?"
+  }
+};
+var SQL_STRING_LITERAL_RENDERERS = {
+  postgres: (value) => {
+    if (value.includes("\\")) {
+      return `E'${value.replaceAll("\\", "\\\\").replaceAll("'", "''")}'`;
+    }
+    return `'${value.replaceAll("'", "''")}'`;
+  },
+  sqlite: (value) => `'${value.replaceAll("'", "''")}'`
+};
+function getSqlDialectProfile(dialect) {
+  return SQL_DIALECT_PROFILES[dialect];
+}
+function bindSqlValue(value, dialect) {
+  if (value instanceof Date) return value.toISOString();
+  return getSqlDialectProfile(dialect).bindValue(value);
+}
+function inlineSqlStringLiteral(value, dialect) {
+  return SQL_STRING_LITERAL_RENDERERS[dialect](value);
+}
+
+// src/query/sql-intent.ts
+function asCompiledRowsSql(query) {
+  return query;
+}
+function asCompiledSelectSql(query) {
+  return asCompiledRowsSql(query);
+}
+function asCompiledStatementSql(query) {
+  return query;
+}
+function asCompiledTemporaryStatementSql(query) {
+  return query;
+}
+var SQL_INTENT_REGISTRY = typeGraphGlobalSymbol(
+  "sql-intent-registry"
+);
+var globalWithSqlIntentRegistry = globalThis;
+var sqlIntentRegistry = globalWithSqlIntentRegistry[SQL_INTENT_REGISTRY] ?? (() => {
+  const registry = {
+    annIndexScanQueries: /* @__PURE__ */ new WeakMap(),
+    forceCustomPlanQueries: /* @__PURE__ */ new WeakSet()
+  };
+  Object.defineProperty(globalWithSqlIntentRegistry, SQL_INTENT_REGISTRY, {
+    configurable: false,
+    enumerable: false,
+    value: registry,
+    writable: false
+  });
+  return registry;
+})();
+function markForceCustomPlan(query) {
+  sqlIntentRegistry.forceCustomPlanQueries.add(query);
+}
+function shouldForceCustomPlan(query) {
+  return sqlIntentRegistry.forceCustomPlanQueries.has(query);
+}
+function markAnnIndexScan(query, indexTypes) {
+  sqlIntentRegistry.annIndexScanQueries.set(query, indexTypes);
+}
+function annIndexScanTypes(query) {
+  return sqlIntentRegistry.annIndexScanQueries.get(query);
+}
+function copySqlIntents(target, sources) {
+  if (sources.some((source) => shouldForceCustomPlan(source))) {
+    markForceCustomPlan(target);
+  }
+  const indexTypes = /* @__PURE__ */ new Set();
+  for (const source of sources) {
+    for (const indexType of annIndexScanTypes(source) ?? []) {
+      indexTypes.add(indexType);
+    }
+  }
+  if (indexTypes.size > 0) markAnnIndexScan(target, [...indexTypes]);
+}
+function isRawExecutable(query) {
+  return !shouldForceCustomPlan(query) && annIndexScanTypes(query) === void 0;
+}
+
+// src/query/sql-fragment.ts
+var SQL_FRAGMENT_BRAND = typeGraphGlobalSymbol("sql-fragment");
+var SQL_PLACEHOLDER_BRAND = typeGraphGlobalSymbol("sql-placeholder");
+var Placeholder = class {
+  [SQL_PLACEHOLDER_BRAND] = true;
+  name;
+  constructor(name) {
+    this.name = name;
+    Object.freeze(this);
+  }
+};
+var SqlFragmentValue = class {
+  [SQL_FRAGMENT_BRAND] = true;
+  chunks;
+  constructor(chunks) {
+    this.chunks = Object.freeze([...chunks]);
+    Object.freeze(this);
+  }
+  append(fragment) {
+    return createFragment(
+      [...this.chunks, ...getChunks(fragment)],
+      [this, fragment]
+    );
+  }
+};
+function createFragment(chunks, intentSources = []) {
+  const fragment = new SqlFragmentValue(chunks);
+  copySqlIntents(fragment, intentSources);
+  return fragment;
+}
+function getChunks(fragment) {
+  if (!isSqlFragment(fragment)) {
+    throw new chunkSAFZ6JTI_cjs.ConfigurationError(
+      "Expected a SQL fragment created by TypeGraph's sql helper"
+    );
+  }
+  return fragment.chunks;
+}
+function isSqlFragment(value) {
+  return typeof value === "object" && value !== null && SQL_FRAGMENT_BRAND in value && value[SQL_FRAGMENT_BRAND] === true && "chunks" in value && Array.isArray(value.chunks) && "append" in value && typeof value.append === "function";
+}
+function isSqlPlaceholder(value) {
+  return typeof value === "object" && value !== null && SQL_PLACEHOLDER_BRAND in value && value[SQL_PLACEHOLDER_BRAND] === true && "name" in value && typeof value.name === "string";
+}
+function throwUnsupportedSqlChunk(chunk) {
+  throw new chunkSAFZ6JTI_cjs.ConfigurationError("Unsupported SQL fragment chunk", { chunk });
+}
+function textNode(value) {
+  return Object.freeze({ kind: "text", value });
+}
+function parameterNode(value) {
+  return Object.freeze({ kind: "parameter", value });
+}
+function identifierNode(value) {
+  return Object.freeze({ kind: "identifier", value });
+}
+function placeholderNode(value) {
+  return Object.freeze({ kind: "placeholder", value });
+}
+function templateSql(strings, ...values) {
+  const chunks = [];
+  const intentSources = [];
+  for (const [index, text] of strings.entries()) {
+    if (text.length > 0) chunks.push(textNode(text));
+    if (index >= values.length) continue;
+    const value = values[index];
+    if (isSqlFragment(value)) {
+      chunks.push(...getChunks(value));
+      intentSources.push(value);
+    } else if (isSqlPlaceholder(value)) {
+      chunks.push(placeholderNode(value));
+    } else {
+      chunks.push(parameterNode(value));
+    }
+  }
+  return createFragment(chunks, intentSources);
+}
+function rawSql(value) {
+  return createFragment(value.length === 0 ? [] : [textNode(value)]);
+}
+function identifierSql(value) {
+  return createFragment([identifierNode(value)]);
+}
+function joinSql(fragments, separator = EMPTY_SQL) {
+  const chunks = [];
+  const intentSources = [separator];
+  for (const [index, fragment] of fragments.entries()) {
+    if (index > 0) chunks.push(...getChunks(separator));
+    chunks.push(...getChunks(fragment));
+    intentSources.push(fragment);
+  }
+  return createFragment(chunks, intentSources);
+}
+function placeholderSql(name) {
+  return createFragment([placeholderNode(new Placeholder(name))]);
+}
+var EMPTY_SQL = createFragment([]);
+var sql = Object.assign(templateSql, {
+  empty: function empty() {
+    return EMPTY_SQL;
+  },
+  identifier: identifierSql,
+  join: joinSql,
+  placeholder: placeholderSql,
+  raw: rawSql
+});
+function quotedIdentifier(identifier) {
+  return `"${identifier.replaceAll('"', '""')}"`;
+}
+function resolvedPlaceholder(placeholder, bindings, dialect) {
+  if (bindings === void 0) return placeholder;
+  if (!Object.hasOwn(bindings, placeholder.name)) {
+    throw new chunkSAFZ6JTI_cjs.ConfigurationError(
+      `Missing binding for parameter "${placeholder.name}"`,
+      { parameterName: placeholder.name }
+    );
+  }
+  return bindSqlValue(bindings[placeholder.name], dialect);
+}
+function renderSql(fragment, dialect, bindings) {
+  const parts = [];
+  const params = [];
+  const profile = getSqlDialectProfile(dialect);
+  for (const node of getChunks(fragment)) {
+    switch (node.kind) {
+      case "text": {
+        parts.push(node.value);
+        break;
+      }
+      case "identifier": {
+        parts.push(quotedIdentifier(node.value));
+        break;
+      }
+      case "parameter": {
+        params.push(bindSqlValue(node.value, dialect));
+        parts.push(profile.placeholder(params.length));
+        break;
+      }
+      case "placeholder": {
+        params.push(resolvedPlaceholder(node.value, bindings, dialect));
+        parts.push(profile.placeholder(params.length));
+        break;
+      }
+      default: {
+        throwUnsupportedSqlChunk(node);
+      }
+    }
+  }
+  return Object.freeze({
+    sql: parts.join(""),
+    params: Object.freeze(params)
+  });
+}
+function renderSqlite(fragment, bindings) {
+  return renderSql(fragment, "sqlite", bindings);
+}
+function renderPostgres(fragment, bindings) {
+  return renderSql(fragment, "postgres", bindings);
+}
+function inlineLiteral(value, dialect) {
+  if (value === void 0 || value === null) return "NULL";
+  if (typeof value === "string") return inlineSqlStringLiteral(value, dialect);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new chunkSAFZ6JTI_cjs.ConfigurationError("Cannot inline a non-finite SQL number", {
+        value
+      });
+    }
+    return String(value);
+  }
+  if (typeof value === "bigint") return String(value);
+  if (typeof value === "boolean") {
+    return getSqlDialectProfile(dialect).booleanLiteralString(value);
+  }
+  if (value instanceof Date) {
+    return inlineSqlStringLiteral(value.toISOString(), dialect);
+  }
+  throw new chunkSAFZ6JTI_cjs.ConfigurationError("Cannot inline this SQL parameter value", {
+    value
+  });
+}
+function renderSqlInline(fragment, dialect) {
+  const parts = [];
+  for (const node of getChunks(fragment)) {
+    switch (node.kind) {
+      case "text": {
+        parts.push(node.value);
+        break;
+      }
+      case "identifier": {
+        parts.push(quotedIdentifier(node.value));
+        break;
+      }
+      case "parameter": {
+        parts.push(inlineLiteral(node.value, dialect));
+        break;
+      }
+      case "placeholder": {
+        throw new chunkSAFZ6JTI_cjs.ConfigurationError(
+          `Cannot inline unresolved SQL placeholder "${node.value.name}"`,
+          { parameterName: node.value.name }
+        );
+      }
+      default: {
+        throwUnsupportedSqlChunk(node);
+      }
+    }
+  }
+  return parts.join("");
+}
+
+exports.Placeholder = Placeholder;
+exports.annIndexScanTypes = annIndexScanTypes;
+exports.asCompiledRowsSql = asCompiledRowsSql;
+exports.asCompiledSelectSql = asCompiledSelectSql;
+exports.asCompiledStatementSql = asCompiledStatementSql;
+exports.asCompiledTemporaryStatementSql = asCompiledTemporaryStatementSql;
+exports.bindSqlValue = bindSqlValue;
+exports.getSqlDialectProfile = getSqlDialectProfile;
+exports.inlineSqlStringLiteral = inlineSqlStringLiteral;
+exports.isRawExecutable = isRawExecutable;
+exports.isSqlFragment = isSqlFragment;
+exports.isSqlPlaceholder = isSqlPlaceholder;
+exports.markAnnIndexScan = markAnnIndexScan;
+exports.markForceCustomPlan = markForceCustomPlan;
+exports.renderPostgres = renderPostgres;
+exports.renderSql = renderSql;
+exports.renderSqlInline = renderSqlInline;
+exports.renderSqlite = renderSqlite;
+exports.shouldForceCustomPlan = shouldForceCustomPlan;
+exports.sql = sql;
+exports.throwUnsupportedSqlChunk = throwUnsupportedSqlChunk;
+exports.typeGraphGlobalSymbol = typeGraphGlobalSymbol;
+//# sourceMappingURL=chunk-X6RDQ5NB.cjs.map
+//# sourceMappingURL=chunk-X6RDQ5NB.cjs.map

package/dist/chunk-X6RDQ5NB.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/global-symbol.ts","../src/query/dialect/profile.ts","../src/query/sql-intent.ts","../src/query/sql-fragment.ts"],"names":["ConfigurationError"],"mappings":"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","file":"chunk-X6RDQ5NB.cjs","sourcesContent":["type TypeGraphGlobalSymbolName =\n  | \"sql-fragment\"\n  | \"sql-placeholder\"\n  | \"sql-intent-registry\"\n  | \"internal-temporary-writes-v1\"\n  | \"external-recorded-read-source-v1\"\n  | \"sql-schema-v1\"\n  | \"store-runtime-v1\"\n  | \"typegraph-recorded-read-source-v1\"\n  | \"transaction-runtime-v1\";\n\n/** Returns a process-wide symbol shared across ESM/CJS package instances. */\nexport function typeGraphGlobalSymbol<TSymbol extends symbol>(\n  name: TypeGraphGlobalSymbolName,\n): TSymbol {\n  return Symbol.for(`@nicia-ai/typegraph/${name}`) as TSymbol;\n}\n","import { type SqlDialect } from \"./types\";\n\nexport type SqlDialectProfile = Readonly<{\n  bindValue: (value: unknown) => unknown;\n  booleanLiteralString: (value: boolean) => string;\n  placeholder: (index: number) => string;\n}>;\n\nconst SQL_DIALECT_PROFILES = {\n  postgres: {\n    bindValue: (value: unknown) => value,\n    booleanLiteralString: (value: boolean) => (value ? \"TRUE\" : \"FALSE\"),\n    placeholder: (index: number) => `$${index}`,\n  },\n  sqlite: {\n    bindValue: (value: unknown) =>\n      typeof value === \"boolean\" ?\n        value ? 1\n        : 0\n      : value,\n    booleanLiteralString: (value: boolean) => (value ? \"1\" : \"0\"),\n    placeholder: () => \"?\",\n  },\n} satisfies Record<SqlDialect, SqlDialectProfile>;\n\nconst SQL_STRING_LITERAL_RENDERERS = {\n  postgres: (value: string) => {\n    if (value.includes(\"\\\\\")) {\n      return `E'${value.replaceAll(\"\\\\\", \"\\\\\\\\\").replaceAll(\"'\", \"''\")}'`;\n    }\n    return `'${value.replaceAll(\"'\", \"''\")}'`;\n  },\n  sqlite: (value: string) => `'${value.replaceAll(\"'\", \"''\")}'`,\n} satisfies Record<SqlDialect, (value: string) => string>;\n\n/** Returns the primitive rendering and binding rules for a SQL dialect. */\nexport function getSqlDialectProfile(dialect: SqlDialect): SqlDialectProfile {\n  return SQL_DIALECT_PROFILES[dialect];\n}\n\n/** Maps a JavaScript value to the representation expected by a SQL driver. */\nexport function bindSqlValue(value: unknown, dialect: SqlDialect): unknown {\n  if (value instanceof Date) return value.toISOString();\n  return getSqlDialectProfile(dialect).bindValue(value);\n}\n\n/** Renders one SQL string literal using the dialect's escaping rules. */\nexport function inlineSqlStringLiteral(\n  value: string,\n  dialect: SqlDialect,\n): string {\n  return SQL_STRING_LITERAL_RENDERERS[dialect](value);\n}\n","import { typeGraphGlobalSymbol } from \"../utils/global-symbol\";\nimport { type SqlFragment } from \"./sql-fragment\";\n\ndeclare const SqlIntentBrand: unique symbol;\n\nexport type SqlIntent = \"rows\" | \"statement\" | \"temporary-statement\";\n\nexport type IntentSql<I extends SqlIntent> = SqlFragment &\n  Readonly<{ [SqlIntentBrand]: I }>;\n\nexport type CompiledRowsSql = IntentSql<\"rows\">;\nexport type CompiledSelectSql = CompiledRowsSql;\nexport type CompiledStatementSql = IntentSql<\"statement\">;\nexport type CompiledTemporaryStatementSql = IntentSql<\"temporary-statement\">;\n\nexport function asCompiledRowsSql(query: SqlFragment): CompiledRowsSql {\n  return query as CompiledRowsSql;\n}\n\nexport function asCompiledSelectSql(query: SqlFragment): CompiledSelectSql {\n  return asCompiledRowsSql(query);\n}\n\nexport function asCompiledStatementSql(\n  query: SqlFragment,\n): CompiledStatementSql {\n  return query as CompiledStatementSql;\n}\n\n/**\n * Marks an internal statement that may write only connection-local temporary\n * state. This is intentionally separate from the public raw-statement intent:\n * history-enabled stores block arbitrary raw writes but iterative graph\n * operations still need to manage ephemeral working tables.\n */\nexport function asCompiledTemporaryStatementSql(\n  query: SqlFragment,\n): CompiledTemporaryStatementSql {\n  return query as CompiledTemporaryStatementSql;\n}\n\n/**\n * Statements whose good plan depends on the bound parameter values —\n * e.g. an id-array membership filter where the array cardinality varies\n * per call. PostgreSQL's prepared-statement machinery switches to a\n * generic (parameter-blind) plan after five executions, which for these\n * statements is catastrophically wrong (measured 21ms -> 310ms on the\n * subgraph edge fetch). Marked statements are executed unnamed so every\n * call is planned against the actual parameters; the re-parse cost is\n * ~1ms, the generic-plan cliff it avoids is 10-300ms.\n */\ntype SqlIntentRegistry = Readonly<{\n  annIndexScanQueries: WeakMap<SqlFragment, readonly string[]>;\n  forceCustomPlanQueries: WeakSet<SqlFragment>;\n}>;\n\nconst SQL_INTENT_REGISTRY: unique symbol = typeGraphGlobalSymbol(\n  \"sql-intent-registry\",\n);\nconst globalWithSqlIntentRegistry = globalThis as typeof globalThis &\n  Readonly<{\n    [SQL_INTENT_REGISTRY]?: SqlIntentRegistry;\n  }>;\nconst sqlIntentRegistry =\n  globalWithSqlIntentRegistry[SQL_INTENT_REGISTRY] ??\n  (() => {\n    const registry: SqlIntentRegistry = {\n      annIndexScanQueries: new WeakMap(),\n      forceCustomPlanQueries: new WeakSet(),\n    };\n    Object.defineProperty(globalWithSqlIntentRegistry, SQL_INTENT_REGISTRY, {\n      configurable: false,\n      enumerable: false,\n      value: registry,\n      writable: false,\n    });\n    return registry;\n  })();\n\nexport function markForceCustomPlan(query: SqlFragment): void {\n  sqlIntentRegistry.forceCustomPlanQueries.add(query);\n}\n\nexport function shouldForceCustomPlan(query: SqlFragment): boolean {\n  return sqlIntentRegistry.forceCustomPlanQueries.has(query);\n}\n\n/**\n * Statements whose plan includes an engine ANN index scan (the inline\n * `.similarTo(..., { approximate: true })` branch). The PostgreSQL\n * backend wraps their execution with the same pgvector GUC overrides\n * the search facade applies (`hnsw.iterative_scan = strict_order` /\n * `ivfflat.iterative_scan = relaxed_order` on pgvector >= 0.8), so a\n * filtered approximate query keeps scanning past the default ef_search\n * frontier instead of starving. Carries the slot index types so the\n * backend knows which GUCs apply. Backends without GUC semantics\n * ignore the brand.\n */\nexport function markAnnIndexScan(\n  query: SqlFragment,\n  indexTypes: readonly string[],\n): void {\n  sqlIntentRegistry.annIndexScanQueries.set(query, indexTypes);\n}\n\nexport function annIndexScanTypes(\n  query: SqlFragment,\n): readonly string[] | undefined {\n  return sqlIntentRegistry.annIndexScanQueries.get(query);\n}\n\n/** @internal Copies execution semantics when immutable fragments are composed. */\nexport function copySqlIntents(\n  target: SqlFragment,\n  sources: readonly SqlFragment[],\n): void {\n  if (sources.some((source) => shouldForceCustomPlan(source))) {\n    markForceCustomPlan(target);\n  }\n\n  const indexTypes = new Set<string>();\n  for (const source of sources) {\n    for (const indexType of annIndexScanTypes(source) ?? []) {\n      indexTypes.add(indexType);\n    }\n  }\n  if (indexTypes.size > 0) markAnnIndexScan(target, [...indexTypes]);\n}\n\n/**\n * Whether a compiled statement can be run as raw text (`executeRaw`) without\n * losing execution semantics. Both brands above ride on the SQL *object* and\n * are honored only by `backend.execute`: the force-custom-plan flag makes\n * PostgreSQL re-plan against the actual parameters (opposed to reusing a\n * cached statement), and the ANN-scan brand drives the pgvector iterative-scan\n * GUC wrapper. A statement carrying either must not be flattened to text and\n * cached — callers fall back to `backend.execute`. Keeping this predicate\n * beside the brands means a future brand updates one place, not every caller.\n */\nexport function isRawExecutable(query: SqlFragment): boolean {\n  return (\n    !shouldForceCustomPlan(query) && annIndexScanTypes(query) === undefined\n  );\n}\n","import { ConfigurationError } from \"../errors\";\nimport { typeGraphGlobalSymbol } from \"../utils/global-symbol\";\nimport {\n  bindSqlValue,\n  getSqlDialectProfile,\n  inlineSqlStringLiteral,\n} from \"./dialect/profile\";\nimport { type SqlDialect } from \"./dialect/types\";\nimport { copySqlIntents } from \"./sql-intent\";\n\n/** Nominal identity shared by every package entrypoint. */\nconst SQL_FRAGMENT_BRAND: unique symbol = typeGraphGlobalSymbol(\"sql-fragment\");\nconst SQL_PLACEHOLDER_BRAND: unique symbol =\n  typeGraphGlobalSymbol(\"sql-placeholder\");\n\nexport type SqlTextChunk = Readonly<{\n  kind: \"text\";\n  value: string;\n}>;\n\nexport type SqlParameterChunk = Readonly<{\n  kind: \"parameter\";\n  value: unknown;\n}>;\n\nexport type SqlIdentifierChunk = Readonly<{\n  kind: \"identifier\";\n  value: string;\n}>;\n\nexport type SqlPlaceholderChunk = Readonly<{\n  kind: \"placeholder\";\n  value: Placeholder;\n}>;\n\n/** One immutable unit in a database-independent SQL fragment. */\nexport type SqlChunk =\n  SqlTextChunk | SqlParameterChunk | SqlIdentifierChunk | SqlPlaceholderChunk;\n\n/**\n * An immutable, database-independent SQL expression.\n *\n * Fragments contain syntax and bound values as separate nodes. A database\n * adapter renders the same fragment with its native placeholder convention at\n * the final execution boundary.\n */\nexport type SqlFragment = Readonly<{\n  [SQL_FRAGMENT_BRAND]: true;\n  append: (fragment: SqlFragment) => SqlFragment;\n  chunks: readonly SqlChunk[];\n}>;\n\n/** A named value resolved when a prepared statement is executed. */\nexport class Placeholder {\n  readonly [SQL_PLACEHOLDER_BRAND] = true as const;\n  readonly name: string;\n\n  constructor(name: string) {\n    this.name = name;\n    Object.freeze(this);\n  }\n}\n\nclass SqlFragmentValue implements SqlFragment {\n  readonly [SQL_FRAGMENT_BRAND] = true as const;\n\n  readonly chunks: readonly SqlChunk[];\n\n  constructor(chunks: readonly SqlChunk[]) {\n    this.chunks = Object.freeze([...chunks]);\n    Object.freeze(this);\n  }\n\n  append(fragment: SqlFragment): SqlFragment {\n    return createFragment(\n      [...this.chunks, ...getChunks(fragment)],\n      [this, fragment],\n    );\n  }\n}\n\nfunction createFragment(\n  chunks: readonly SqlChunk[],\n  intentSources: readonly SqlFragment[] = [],\n): SqlFragment {\n  const fragment = new SqlFragmentValue(chunks);\n  copySqlIntents(fragment, intentSources);\n  return fragment;\n}\n\nfunction getChunks(fragment: SqlFragment): readonly SqlChunk[] {\n  if (!isSqlFragment(fragment)) {\n    throw new ConfigurationError(\n      \"Expected a SQL fragment created by TypeGraph's sql helper\",\n    );\n  }\n  return fragment.chunks;\n}\n\n/** Returns whether a value is a TypeGraph-owned SQL fragment. */\nexport function isSqlFragment(value: unknown): value is SqlFragment {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    SQL_FRAGMENT_BRAND in value &&\n    value[SQL_FRAGMENT_BRAND] === true &&\n    \"chunks\" in value &&\n    Array.isArray(value.chunks) &&\n    \"append\" in value &&\n    typeof value.append === \"function\"\n  );\n}\n\n/** Returns whether a value is a TypeGraph named SQL placeholder. */\nexport function isSqlPlaceholder(value: unknown): value is Placeholder {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    SQL_PLACEHOLDER_BRAND in value &&\n    value[SQL_PLACEHOLDER_BRAND] === true &&\n    \"name\" in value &&\n    typeof value.name === \"string\"\n  );\n}\n\n/** @internal Enforces exhaustive handling at every fragment boundary. */\nexport function throwUnsupportedSqlChunk(chunk: never): never {\n  throw new ConfigurationError(\"Unsupported SQL fragment chunk\", { chunk });\n}\n\nfunction textNode(value: string): SqlTextChunk {\n  return Object.freeze({ kind: \"text\", value });\n}\n\nfunction parameterNode(value: unknown): SqlParameterChunk {\n  return Object.freeze({ kind: \"parameter\", value });\n}\n\nfunction identifierNode(value: string): SqlIdentifierChunk {\n  return Object.freeze({ kind: \"identifier\", value });\n}\n\nfunction placeholderNode(value: Placeholder): SqlPlaceholderChunk {\n  return Object.freeze({ kind: \"placeholder\", value });\n}\n\nfunction templateSql(\n  strings: TemplateStringsArray,\n  ...values: readonly unknown[]\n): SqlFragment {\n  const chunks: SqlChunk[] = [];\n  const intentSources: SqlFragment[] = [];\n\n  for (const [index, text] of strings.entries()) {\n    if (text.length > 0) chunks.push(textNode(text));\n\n    if (index >= values.length) continue;\n    const value = values[index];\n    if (isSqlFragment(value)) {\n      chunks.push(...getChunks(value));\n      intentSources.push(value);\n    } else if (isSqlPlaceholder(value)) {\n      chunks.push(placeholderNode(value));\n    } else {\n      chunks.push(parameterNode(value));\n    }\n  }\n\n  return createFragment(chunks, intentSources);\n}\n\nfunction rawSql(value: string): SqlFragment {\n  return createFragment(value.length === 0 ? [] : [textNode(value)]);\n}\n\nfunction identifierSql(value: string): SqlFragment {\n  return createFragment([identifierNode(value)]);\n}\n\nfunction joinSql(\n  fragments: readonly SqlFragment[],\n  separator: SqlFragment = EMPTY_SQL,\n): SqlFragment {\n  const chunks: SqlChunk[] = [];\n  const intentSources: SqlFragment[] = [separator];\n\n  for (const [index, fragment] of fragments.entries()) {\n    if (index > 0) chunks.push(...getChunks(separator));\n    chunks.push(...getChunks(fragment));\n    intentSources.push(fragment);\n  }\n\n  return createFragment(chunks, intentSources);\n}\n\nfunction placeholderSql(name: string): SqlFragment {\n  return createFragment([placeholderNode(new Placeholder(name))]);\n}\n\nconst EMPTY_SQL = createFragment([]);\n\n/** TypeGraph's database-independent SQL template and composition helpers. */\nexport type SqlTag = Readonly<{\n  empty: () => SqlFragment;\n  identifier: (value: string) => SqlFragment;\n  join: (\n    fragments: readonly SqlFragment[],\n    separator?: SqlFragment,\n  ) => SqlFragment;\n  placeholder: (name: string) => SqlFragment;\n  raw: (value: string) => SqlFragment;\n}> &\n  ((\n    strings: TemplateStringsArray,\n    ...values: readonly unknown[]\n  ) => SqlFragment);\n\n/** TypeGraph's database-independent SQL template and composition helpers. */\nexport const sql: SqlTag = Object.assign(templateSql, {\n  empty: function empty(): SqlFragment {\n    return EMPTY_SQL;\n  },\n  identifier: identifierSql,\n  join: joinSql,\n  placeholder: placeholderSql,\n  raw: rawSql,\n});\n\n/** A rendered statement and its ordered bound parameters. */\nexport type RenderedSql = Readonly<{\n  sql: string;\n  params: readonly unknown[];\n}>;\n\nfunction quotedIdentifier(identifier: string): string {\n  return `\"${identifier.replaceAll('\"', '\"\"')}\"`;\n}\n\nfunction resolvedPlaceholder(\n  placeholder: Placeholder,\n  bindings: Readonly<Record<string, unknown>> | undefined,\n  dialect: SqlDialect,\n): unknown {\n  if (bindings === undefined) return placeholder;\n\n  if (!Object.hasOwn(bindings, placeholder.name)) {\n    throw new ConfigurationError(\n      `Missing binding for parameter \"${placeholder.name}\"`,\n      { parameterName: placeholder.name },\n    );\n  }\n  return bindSqlValue(bindings[placeholder.name], dialect);\n}\n\n/**\n * Renders a fragment for a database adapter.\n *\n * Named placeholders remain in `params` when `bindings` is omitted, allowing\n * a prepared template to resolve them later. Passing `bindings` resolves every\n * placeholder eagerly.\n */\nexport function renderSql(\n  fragment: SqlFragment,\n  dialect: SqlDialect,\n  bindings?: Readonly<Record<string, unknown>>,\n): RenderedSql {\n  const parts: string[] = [];\n  const params: unknown[] = [];\n  const profile = getSqlDialectProfile(dialect);\n\n  for (const node of getChunks(fragment)) {\n    switch (node.kind) {\n      case \"text\": {\n        parts.push(node.value);\n        break;\n      }\n      case \"identifier\": {\n        parts.push(quotedIdentifier(node.value));\n        break;\n      }\n      case \"parameter\": {\n        params.push(bindSqlValue(node.value, dialect));\n        parts.push(profile.placeholder(params.length));\n        break;\n      }\n      case \"placeholder\": {\n        params.push(resolvedPlaceholder(node.value, bindings, dialect));\n        parts.push(profile.placeholder(params.length));\n        break;\n      }\n      default: {\n        throwUnsupportedSqlChunk(node);\n      }\n    }\n  }\n\n  return Object.freeze({\n    sql: parts.join(\"\"),\n    params: Object.freeze(params),\n  });\n}\n\n/** Renders a fragment using SQLite's `?` placeholders. */\nexport function renderSqlite(\n  fragment: SqlFragment,\n  bindings?: Readonly<Record<string, unknown>>,\n): RenderedSql {\n  return renderSql(fragment, \"sqlite\", bindings);\n}\n\n/** Renders a fragment using PostgreSQL's numbered placeholders. */\nexport function renderPostgres(\n  fragment: SqlFragment,\n  bindings?: Readonly<Record<string, unknown>>,\n): RenderedSql {\n  return renderSql(fragment, \"postgres\", bindings);\n}\n\nfunction inlineLiteral(value: unknown, dialect: SqlDialect): string {\n  if (value === undefined || value === null) return \"NULL\";\n  if (typeof value === \"string\") return inlineSqlStringLiteral(value, dialect);\n  if (typeof value === \"number\") {\n    if (!Number.isFinite(value)) {\n      throw new ConfigurationError(\"Cannot inline a non-finite SQL number\", {\n        value,\n      });\n    }\n    return String(value);\n  }\n  if (typeof value === \"bigint\") return String(value);\n  if (typeof value === \"boolean\") {\n    return getSqlDialectProfile(dialect).booleanLiteralString(value);\n  }\n  if (value instanceof Date) {\n    return inlineSqlStringLiteral(value.toISOString(), dialect);\n  }\n\n  throw new ConfigurationError(\"Cannot inline this SQL parameter value\", {\n    value,\n  });\n}\n\n/**\n * Renders a fragment with safe scalar literals instead of bound parameters.\n *\n * This is intentionally limited to DDL paths whose drivers cannot bind values.\n * Application queries should always use {@link renderSql}.\n */\nexport function renderSqlInline(\n  fragment: SqlFragment,\n  dialect: SqlDialect,\n): string {\n  const parts: string[] = [];\n\n  for (const node of getChunks(fragment)) {\n    switch (node.kind) {\n      case \"text\": {\n        parts.push(node.value);\n        break;\n      }\n      case \"identifier\": {\n        parts.push(quotedIdentifier(node.value));\n        break;\n      }\n      case \"parameter\": {\n        parts.push(inlineLiteral(node.value, dialect));\n        break;\n      }\n      case \"placeholder\": {\n        throw new ConfigurationError(\n          `Cannot inline unresolved SQL placeholder \"${node.value.name}\"`,\n          { parameterName: node.value.name },\n        );\n      }\n      default: {\n        throwUnsupportedSqlChunk(node);\n      }\n    }\n  }\n\n  return parts.join(\"\");\n}\n"]}