@nicia-ai/typegraph 0.41.0 → 0.42.1

package/dist/{chunk-NMQ6C6TS.cjs → chunk-F7TDKSVB.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 var chunkDI74SMXS_cjs = require('./chunk-DI74SMXS.cjs');
-var chunkSAFZ6JTI_cjs = require('./chunk-SAFZ6JTI.cjs');
+var chunkKTBTSHU6_cjs = require('./chunk-KTBTSHU6.cjs');
 
 // src/core/json-value.ts
 function assertJsonValue(value, rootLabel, ownerKind) {
@@ -47,7 +47,7 @@ function describeNonPlain(value) {
   return "non-plain object";
 }
 function throwInvalid(path, kind, ownerKind) {
-  throw new chunkSAFZ6JTI_cjs.ConfigurationError(
+  throw new chunkKTBTSHU6_cjs.ConfigurationError(
     `${ownerKind} ${path} contains a non-JSON value (${kind}). Annotations must be JSON-serializable.`,
     { path, valueKind: kind },
     {
@@ -57,5 +57,5 @@ function throwInvalid(path, kind, ownerKind) {
 }
 
 exports.assertJsonValue = assertJsonValue;
-//# sourceMappingURL=chunk-NMQ6C6TS.cjs.map
-//# sourceMappingURL=chunk-NMQ6C6TS.cjs.map
+//# sourceMappingURL=chunk-F7TDKSVB.cjs.map
+//# sourceMappingURL=chunk-F7TDKSVB.cjs.map

package/dist/{chunk-NMQ6C6TS.cjs.map → chunk-F7TDKSVB.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/json-value.ts"],"names":["isPlainObject","ConfigurationError"],"mappings":";;;;;;AAyBO,SAAS,eAAA,CACd,KAAA,EACA,SAAA,EACA,SAAA,EACM;AACN,EAAA,IAAA,CAAK,KAAA,EAAO,WAAW,SAAS,CAAA;AAClC;AAEA,SAAS,IAAA,CAAK,KAAA,EAAgB,IAAA,EAAc,SAAA,EAAyB;AACnE,EAAA,IAAI,UAAU,IAAA,EAAM;AACpB,EAAA,MAAM,YAAY,OAAO,KAAA;AACzB,EAAA,IAAI,cAAc,QAAA,EAAU;AAI1B,IAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,KAAK,CAAA,EAAG;AAC3B,MAAA,YAAA,CAAa,IAAA,EAAM,iBAAA,CAAkB,KAAe,CAAA,EAAG,SAAS,CAAA;AAAA,IAClE;AACA,IAAA;AAAA,EACF;AACA,EAAA,IAAI,SAAA,KAAc,QAAA,IAAY,SAAA,KAAc,SAAA,EAAW;AACvD,EAAA,IACE,cAAc,QAAA,IACd,SAAA,KAAc,cACd,SAAA,KAAc,QAAA,IACd,cAAc,WAAA,EACd;AACA,IAAA,YAAA,CAAa,IAAA,EAAM,WAAW,SAAS,CAAA;AAAA,EACzC;AACA,EAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AACxB,IAAA,KAAA,MAAW,CAAC,KAAA,EAAO,OAAO,CAAA,IAAK,KAAA,CAAM,SAAQ,EAAG;AAC9C,MAAA,IAAA,CAAK,SAAS,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,KAAK,KAAK,SAAS,CAAA;AAAA,IAC9C;AACA,IAAA;AAAA,EACF;AACA,EAAA,IAAI,CAACA,+BAAA,CAAc,KAAK,CAAA,EAAG;AACzB,IAAA,YAAA,CAAa,IAAA,EAAM,gBAAA,CAAiB,KAAK,CAAA,EAAG,SAAS,CAAA;AAAA,EACvD;AACA,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,MAAM,KAAK,MAAA,CAAO,OAAA,CAAQ,KAAK,CAAA,EAAG;AACjD,IAAA,IAAA,CAAK,QAAQ,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,GAAG,IAAI,SAAS,CAAA;AAAA,EAC1C;AACF;AAEA,SAAS,kBAAkB,KAAA,EAAuB;AAChD,EAAA,IAAI,MAAA,CAAO,KAAA,CAAM,KAAK,CAAA,EAAG,OAAO,KAAA;AAChC,EAAA,IAAI,KAAA,KAAU,MAAA,CAAO,iBAAA,EAAmB,OAAO,UAAA;AAC/C,EAAA,IAAI,KAAA,KAAU,MAAA,CAAO,iBAAA,EAAmB,OAAO,WAAA;AAC/C,EAAA,OAAO,mBAAA;AACT;AAEA,SAAS,iBAAiB,KAAA,EAAwB;AAChD,EAAA,MAAM,eAAA,GAAmB,OACrB,WAAA,EAAa,IAAA;AACjB,EAAA,IAAI,OAAO,eAAA,KAAoB,QAAA,IAAY,eAAA,CAAgB,SAAS,CAAA,EAAG;AACrE,IAAA,OAAO,GAAG,eAAe,CAAA,SAAA,CAAA;AAAA,EAC3B;AACA,EAAA,OAAO,kBAAA;AACT;AAEA,SAAS,YAAA,CAAa,IAAA,EAAc,IAAA,EAAc,SAAA,EAA0B;AAC1E,EAAA,MAAM,IAAIC,oCAAA;AAAA,IACR,CAAA,EAAG,SAAS,CAAA,CAAA,EAAI,IAAI,+BAA+B,IAAI,CAAA,yCAAA,CAAA;AAAA,IACvD,EAAE,IAAA,EAAM,SAAA,EAAW,IAAA,EAAK;AAAA,IACxB;AAAA,MACE,UAAA,EACE;AAAA;AACJ,GACF;AACF","file":"chunk-NMQ6C6TS.cjs","sourcesContent":["/**\n * Runtime validation for JSON-serializable values.\n *\n * Used at definition-time boundaries (e.g., `defineNode`/`defineEdge` annotations)\n * to reject values that would silently break `JSON.stringify` round-trips or\n * throw at hash time. Catches accidental violations from untyped JS callers\n * and `as any` escape hatches that bypass the `JsonValue` type.\n */\nimport { ConfigurationError } from \"../errors\";\nimport { isPlainObject } from \"../utils/object\";\n\n/**\n * Asserts that `value` is JSON-serializable.\n *\n * Throws `ConfigurationError` with a dotted path identifying the offending\n * field. Rejects `bigint`, `function`, `symbol`, `undefined`, and class\n * instances such as `Date`, `Map`, `Set`, regex literals, and Buffers — all\n * of which either throw or silently coerce under `JSON.stringify`.\n *\n * @param value - The value to validate\n * @param rootLabel - Label for the root of the value (e.g., `\"annotations\"`)\n *   used as the prefix of the error path\n * @param ownerKind - Human-readable owner identifier for the error message\n *   (e.g., `'Node \"Person\"'`)\n */\nexport function assertJsonValue(\n  value: unknown,\n  rootLabel: string,\n  ownerKind: string,\n): void {\n  walk(value, rootLabel, ownerKind);\n}\n\nfunction walk(value: unknown, path: string, ownerKind: string): void {\n  if (value === null) return;\n  const valueType = typeof value;\n  if (valueType === \"number\") {\n    // NaN/Infinity/-Infinity are not JSON values; JSON.stringify silently\n    // coerces them to `null`, which would change the canonical hash input\n    // without the consumer noticing.\n    if (!Number.isFinite(value)) {\n      throwInvalid(path, describeNonFinite(value as number), ownerKind);\n    }\n    return;\n  }\n  if (valueType === \"string\" || valueType === \"boolean\") return;\n  if (\n    valueType === \"bigint\" ||\n    valueType === \"function\" ||\n    valueType === \"symbol\" ||\n    valueType === \"undefined\"\n  ) {\n    throwInvalid(path, valueType, ownerKind);\n  }\n  if (Array.isArray(value)) {\n    for (const [index, element] of value.entries()) {\n      walk(element, `${path}[${index}]`, ownerKind);\n    }\n    return;\n  }\n  if (!isPlainObject(value)) {\n    throwInvalid(path, describeNonPlain(value), ownerKind);\n  }\n  for (const [key, nested] of Object.entries(value)) {\n    walk(nested, `${path}.${key}`, ownerKind);\n  }\n}\n\nfunction describeNonFinite(value: number): string {\n  if (Number.isNaN(value)) return \"NaN\";\n  if (value === Number.POSITIVE_INFINITY) return \"Infinity\";\n  if (value === Number.NEGATIVE_INFINITY) return \"-Infinity\";\n  return \"non-finite number\";\n}\n\nfunction describeNonPlain(value: unknown): string {\n  const constructorName = (value as { constructor?: { name?: unknown } } | null)\n    ?.constructor?.name;\n  if (typeof constructorName === \"string\" && constructorName.length > 0) {\n    return `${constructorName} instance`;\n  }\n  return \"non-plain object\";\n}\n\nfunction throwInvalid(path: string, kind: string, ownerKind: string): never {\n  throw new ConfigurationError(\n    `${ownerKind} ${path} contains a non-JSON value (${kind}). Annotations must be JSON-serializable.`,\n    { path, valueKind: kind },\n    {\n      suggestion:\n        \"Use only strings, numbers, booleans, null, arrays, and plain objects in annotations.\",\n    },\n  );\n}\n"]}
+{"version":3,"sources":["../src/core/json-value.ts"],"names":["isPlainObject","ConfigurationError"],"mappings":";;;;;;AAyBO,SAAS,eAAA,CACd,KAAA,EACA,SAAA,EACA,SAAA,EACM;AACN,EAAA,IAAA,CAAK,KAAA,EAAO,WAAW,SAAS,CAAA;AAClC;AAEA,SAAS,IAAA,CAAK,KAAA,EAAgB,IAAA,EAAc,SAAA,EAAyB;AACnE,EAAA,IAAI,UAAU,IAAA,EAAM;AACpB,EAAA,MAAM,YAAY,OAAO,KAAA;AACzB,EAAA,IAAI,cAAc,QAAA,EAAU;AAI1B,IAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,KAAK,CAAA,EAAG;AAC3B,MAAA,YAAA,CAAa,IAAA,EAAM,iBAAA,CAAkB,KAAe,CAAA,EAAG,SAAS,CAAA;AAAA,IAClE;AACA,IAAA;AAAA,EACF;AACA,EAAA,IAAI,SAAA,KAAc,QAAA,IAAY,SAAA,KAAc,SAAA,EAAW;AACvD,EAAA,IACE,cAAc,QAAA,IACd,SAAA,KAAc,cACd,SAAA,KAAc,QAAA,IACd,cAAc,WAAA,EACd;AACA,IAAA,YAAA,CAAa,IAAA,EAAM,WAAW,SAAS,CAAA;AAAA,EACzC;AACA,EAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AACxB,IAAA,KAAA,MAAW,CAAC,KAAA,EAAO,OAAO,CAAA,IAAK,KAAA,CAAM,SAAQ,EAAG;AAC9C,MAAA,IAAA,CAAK,SAAS,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,KAAK,KAAK,SAAS,CAAA;AAAA,IAC9C;AACA,IAAA;AAAA,EACF;AACA,EAAA,IAAI,CAACA,+BAAA,CAAc,KAAK,CAAA,EAAG;AACzB,IAAA,YAAA,CAAa,IAAA,EAAM,gBAAA,CAAiB,KAAK,CAAA,EAAG,SAAS,CAAA;AAAA,EACvD;AACA,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,MAAM,KAAK,MAAA,CAAO,OAAA,CAAQ,KAAK,CAAA,EAAG;AACjD,IAAA,IAAA,CAAK,QAAQ,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,GAAG,IAAI,SAAS,CAAA;AAAA,EAC1C;AACF;AAEA,SAAS,kBAAkB,KAAA,EAAuB;AAChD,EAAA,IAAI,MAAA,CAAO,KAAA,CAAM,KAAK,CAAA,EAAG,OAAO,KAAA;AAChC,EAAA,IAAI,KAAA,KAAU,MAAA,CAAO,iBAAA,EAAmB,OAAO,UAAA;AAC/C,EAAA,IAAI,KAAA,KAAU,MAAA,CAAO,iBAAA,EAAmB,OAAO,WAAA;AAC/C,EAAA,OAAO,mBAAA;AACT;AAEA,SAAS,iBAAiB,KAAA,EAAwB;AAChD,EAAA,MAAM,eAAA,GAAmB,OACrB,WAAA,EAAa,IAAA;AACjB,EAAA,IAAI,OAAO,eAAA,KAAoB,QAAA,IAAY,eAAA,CAAgB,SAAS,CAAA,EAAG;AACrE,IAAA,OAAO,GAAG,eAAe,CAAA,SAAA,CAAA;AAAA,EAC3B;AACA,EAAA,OAAO,kBAAA;AACT;AAEA,SAAS,YAAA,CAAa,IAAA,EAAc,IAAA,EAAc,SAAA,EAA0B;AAC1E,EAAA,MAAM,IAAIC,oCAAA;AAAA,IACR,CAAA,EAAG,SAAS,CAAA,CAAA,EAAI,IAAI,+BAA+B,IAAI,CAAA,yCAAA,CAAA;AAAA,IACvD,EAAE,IAAA,EAAM,SAAA,EAAW,IAAA,EAAK;AAAA,IACxB;AAAA,MACE,UAAA,EACE;AAAA;AACJ,GACF;AACF","file":"chunk-F7TDKSVB.cjs","sourcesContent":["/**\n * Runtime validation for JSON-serializable values.\n *\n * Used at definition-time boundaries (e.g., `defineNode`/`defineEdge` annotations)\n * to reject values that would silently break `JSON.stringify` round-trips or\n * throw at hash time. Catches accidental violations from untyped JS callers\n * and `as any` escape hatches that bypass the `JsonValue` type.\n */\nimport { ConfigurationError } from \"../errors\";\nimport { isPlainObject } from \"../utils/object\";\n\n/**\n * Asserts that `value` is JSON-serializable.\n *\n * Throws `ConfigurationError` with a dotted path identifying the offending\n * field. Rejects `bigint`, `function`, `symbol`, `undefined`, and class\n * instances such as `Date`, `Map`, `Set`, regex literals, and Buffers — all\n * of which either throw or silently coerce under `JSON.stringify`.\n *\n * @param value - The value to validate\n * @param rootLabel - Label for the root of the value (e.g., `\"annotations\"`)\n *   used as the prefix of the error path\n * @param ownerKind - Human-readable owner identifier for the error message\n *   (e.g., `'Node \"Person\"'`)\n */\nexport function assertJsonValue(\n  value: unknown,\n  rootLabel: string,\n  ownerKind: string,\n): void {\n  walk(value, rootLabel, ownerKind);\n}\n\nfunction walk(value: unknown, path: string, ownerKind: string): void {\n  if (value === null) return;\n  const valueType = typeof value;\n  if (valueType === \"number\") {\n    // NaN/Infinity/-Infinity are not JSON values; JSON.stringify silently\n    // coerces them to `null`, which would change the canonical hash input\n    // without the consumer noticing.\n    if (!Number.isFinite(value)) {\n      throwInvalid(path, describeNonFinite(value as number), ownerKind);\n    }\n    return;\n  }\n  if (valueType === \"string\" || valueType === \"boolean\") return;\n  if (\n    valueType === \"bigint\" ||\n    valueType === \"function\" ||\n    valueType === \"symbol\" ||\n    valueType === \"undefined\"\n  ) {\n    throwInvalid(path, valueType, ownerKind);\n  }\n  if (Array.isArray(value)) {\n    for (const [index, element] of value.entries()) {\n      walk(element, `${path}[${index}]`, ownerKind);\n    }\n    return;\n  }\n  if (!isPlainObject(value)) {\n    throwInvalid(path, describeNonPlain(value), ownerKind);\n  }\n  for (const [key, nested] of Object.entries(value)) {\n    walk(nested, `${path}.${key}`, ownerKind);\n  }\n}\n\nfunction describeNonFinite(value: number): string {\n  if (Number.isNaN(value)) return \"NaN\";\n  if (value === Number.POSITIVE_INFINITY) return \"Infinity\";\n  if (value === Number.NEGATIVE_INFINITY) return \"-Infinity\";\n  return \"non-finite number\";\n}\n\nfunction describeNonPlain(value: unknown): string {\n  const constructorName = (value as { constructor?: { name?: unknown } } | null)\n    ?.constructor?.name;\n  if (typeof constructorName === \"string\" && constructorName.length > 0) {\n    return `${constructorName} instance`;\n  }\n  return \"non-plain object\";\n}\n\nfunction throwInvalid(path: string, kind: string, ownerKind: string): never {\n  throw new ConfigurationError(\n    `${ownerKind} ${path} contains a non-JSON value (${kind}). Annotations must be JSON-serializable.`,\n    { path, valueKind: kind },\n    {\n      suggestion:\n        \"Use only strings, numbers, booleans, null, arrays, and plain objects in annotations.\",\n    },\n  );\n}\n"]}

package/dist/{chunk-HQRZEYYB.cjs → chunk-FFQGI67R.cjs}

@@ -1,8 +1,8 @@
 'use strict';
 
-var chunk5YBDB7UG_cjs = require('./chunk-5YBDB7UG.cjs');
-var chunkHAQVISUF_cjs = require('./chunk-HAQVISUF.cjs');
-var chunkYX3H63VV_cjs = require('./chunk-YX3H63VV.cjs');
+var chunkVGMNGWBR_cjs = require('./chunk-VGMNGWBR.cjs');
+var chunkUTTW2Q3M_cjs = require('./chunk-UTTW2Q3M.cjs');
+var chunkX2XOQZT3_cjs = require('./chunk-X2XOQZT3.cjs');
 
 // src/query/dialect/vector/sqlite-vec-strategy.ts
 var TABLE_PREFIX = "tg_vec";
@@ -47,17 +47,17 @@ function sqliteVecMetricToken(metric) {
   }
 }
 function vecF32Literal(embedding, name) {
-  chunkHAQVISUF_cjs.assertFiniteEmbedding(embedding, name);
-  return chunkYX3H63VV_cjs.sql`vec_f32(${JSON.stringify(embedding)})`;
+  chunkUTTW2Q3M_cjs.assertFiniteEmbedding(embedding, name);
+  return chunkX2XOQZT3_cjs.sql`vec_f32(${JSON.stringify(embedding)})`;
 }
 function distanceExpression(embeddingColumn, queryEmbedding, metric) {
   const query = vecF32Literal(queryEmbedding, "queryEmbedding");
   switch (metric) {
     case "cosine": {
-      return chunkYX3H63VV_cjs.sql`vec_distance_cosine(${embeddingColumn}, ${query})`;
+      return chunkX2XOQZT3_cjs.sql`vec_distance_cosine(${embeddingColumn}, ${query})`;
     }
     case "l2": {
-      return chunkYX3H63VV_cjs.sql`vec_distance_l2(${embeddingColumn}, ${query})`;
+      return chunkX2XOQZT3_cjs.sql`vec_distance_l2(${embeddingColumn}, ${query})`;
     }
     case "inner_product": {
       throw new Error(
@@ -71,7 +71,7 @@ function distanceExpression(embeddingColumn, queryEmbedding, metric) {
   }
 }
 function tableName(graphId, nodeKind, fieldPath) {
-  return chunkHAQVISUF_cjs.vectorPhysicalName(TABLE_PREFIX, graphId, nodeKind, fieldPath);
+  return chunkUTTW2Q3M_cjs.vectorPhysicalName(TABLE_PREFIX, graphId, nodeKind, fieldPath);
 }
 var sqliteVecStrategy = {
   name: "sqlite-vec",
@@ -79,11 +79,11 @@ var sqliteVecStrategy = {
   tableName,
   ownedTables(slot) {
     const table = tableName(slot.graphId, slot.nodeKind, slot.fieldPath);
-    const name = chunkHAQVISUF_cjs.quoteIdentifier(table);
+    const name = chunkUTTW2Q3M_cjs.quoteIdentifier(table);
     const metric = sqliteVecMetricToken(slot.metric);
     return [
       {
-        logicalName: `${chunkHAQVISUF_cjs.VECTOR_CONTRIBUTION_PREFIX}:${slot.nodeKind}.${slot.fieldPath}`,
+        logicalName: `${chunkUTTW2Q3M_cjs.VECTOR_CONTRIBUTION_PREFIX}:${slot.nodeKind}.${slot.fieldPath}`,
         owner: "sqlite-vec",
         tableName: table,
         createDdl: [
@@ -100,52 +100,52 @@ var sqliteVecStrategy = {
     ];
   },
   buildUpsert(slot, params, timestamp) {
-    const table = chunkYX3H63VV_cjs.sql.identifier(
+    const table = chunkX2XOQZT3_cjs.sql.identifier(
       tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
     const value = vecF32Literal(params.embedding, "embedding");
     return [
-      chunkYX3H63VV_cjs.sql`
+      chunkX2XOQZT3_cjs.sql`
         DELETE FROM ${table}
         WHERE "node_id" = ${params.nodeId} AND "graph_id" = ${params.graphId}
       `,
-      chunkYX3H63VV_cjs.sql`
+      chunkX2XOQZT3_cjs.sql`
         INSERT INTO ${table} ("node_id", "graph_id", "created_at", "updated_at", "embedding")
         VALUES (${params.nodeId}, ${params.graphId}, ${timestamp}, ${timestamp}, ${value})
       `
     ];
   },
   buildUpsertBatch(slot, params, timestamp) {
-    const table = chunkYX3H63VV_cjs.sql.identifier(
+    const table = chunkX2XOQZT3_cjs.sql.identifier(
       tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
-    const nodeIds = chunkYX3H63VV_cjs.sql.join(
-      params.rows.map((row) => chunkYX3H63VV_cjs.sql`${row.nodeId}`),
-      chunkYX3H63VV_cjs.sql`, `
+    const nodeIds = chunkX2XOQZT3_cjs.sql.join(
+      params.rows.map((row) => chunkX2XOQZT3_cjs.sql`${row.nodeId}`),
+      chunkX2XOQZT3_cjs.sql`, `
     );
-    const valueRows = chunkYX3H63VV_cjs.sql.join(
+    const valueRows = chunkX2XOQZT3_cjs.sql.join(
       params.rows.map(
-        (row) => chunkYX3H63VV_cjs.sql`(${row.nodeId}, ${params.graphId}, ${timestamp}, ${timestamp}, ${vecF32Literal(row.embedding, "embedding")})`
+        (row) => chunkX2XOQZT3_cjs.sql`(${row.nodeId}, ${params.graphId}, ${timestamp}, ${timestamp}, ${vecF32Literal(row.embedding, "embedding")})`
       ),
-      chunkYX3H63VV_cjs.sql`, `
+      chunkX2XOQZT3_cjs.sql`, `
     );
     return [
-      chunkYX3H63VV_cjs.sql`
+      chunkX2XOQZT3_cjs.sql`
         DELETE FROM ${table}
         WHERE "graph_id" = ${params.graphId} AND "node_id" IN (${nodeIds})
       `,
-      chunkYX3H63VV_cjs.sql`
+      chunkX2XOQZT3_cjs.sql`
         INSERT INTO ${table} ("node_id", "graph_id", "created_at", "updated_at", "embedding")
         VALUES ${valueRows}
       `
     ];
   },
   buildDelete(slot, params) {
-    const table = chunkYX3H63VV_cjs.sql.identifier(
+    const table = chunkX2XOQZT3_cjs.sql.identifier(
       tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
     return [
-      chunkYX3H63VV_cjs.sql`
+      chunkX2XOQZT3_cjs.sql`
         DELETE FROM ${table}
         WHERE "node_id" = ${params.nodeId} AND "graph_id" = ${params.graphId}
       `
@@ -157,63 +157,63 @@ var sqliteVecStrategy = {
   // route the NON-approximate `.similarTo()` branch through this form.
   searchIsExact: true,
   buildSearch(slot, params, candidates) {
-    const table = chunkYX3H63VV_cjs.sql.identifier(
+    const table = chunkX2XOQZT3_cjs.sql.identifier(
       tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
-    const embeddingColumn = chunkYX3H63VV_cjs.sql`${table}."embedding"`;
+    const embeddingColumn = chunkX2XOQZT3_cjs.sql`${table}."embedding"`;
     const distance = distanceExpression(
       embeddingColumn,
       params.queryEmbedding,
       params.metric
     );
-    const score = chunkHAQVISUF_cjs.vectorScoreExpression(distance, params.metric);
+    const score = chunkUTTW2Q3M_cjs.vectorScoreExpression(distance, params.metric);
     if (usesAnnIndex(slot)) {
       const query = vecF32Literal(params.queryEmbedding, "queryEmbedding");
       const knnK = params.limit + (params.offset ?? 0);
       const conditions2 = [
-        chunkYX3H63VV_cjs.sql`${table}."embedding" MATCH ${query}`,
-        chunkYX3H63VV_cjs.sql`k = ${knnK}`,
-        chunkYX3H63VV_cjs.sql`${table}."graph_id" = ${params.graphId}`
+        chunkX2XOQZT3_cjs.sql`${table}."embedding" MATCH ${query}`,
+        chunkX2XOQZT3_cjs.sql`k = ${knnK}`,
+        chunkX2XOQZT3_cjs.sql`${table}."graph_id" = ${params.graphId}`
       ];
       if (params.minScore !== void 0) {
         conditions2.push(
-          chunkHAQVISUF_cjs.vectorMinScoreCondition(distance, params.metric, params.minScore)
+          chunkUTTW2Q3M_cjs.vectorMinScoreCondition(distance, params.metric, params.minScore)
         );
       }
       if (candidates !== void 0) {
-        conditions2.push(chunkYX3H63VV_cjs.sql`${table}."node_id" IN (${candidates})`);
+        conditions2.push(chunkX2XOQZT3_cjs.sql`${table}."node_id" IN (${candidates})`);
       }
-      const knnBody = chunkYX3H63VV_cjs.sql`
+      const knnBody = chunkX2XOQZT3_cjs.sql`
         SELECT ${table}."node_id" AS node_id, ${score} AS score
         FROM ${table}
-        WHERE ${chunkYX3H63VV_cjs.sql.join(conditions2, chunkYX3H63VV_cjs.sql` AND `)}
+        WHERE ${chunkX2XOQZT3_cjs.sql.join(conditions2, chunkX2XOQZT3_cjs.sql` AND `)}
         ORDER BY distance ASC
       `;
       if (params.offset === void 0 || params.offset === 0) {
         return knnBody;
       }
-      return chunkYX3H63VV_cjs.sql`
+      return chunkX2XOQZT3_cjs.sql`
         WITH knn_page AS MATERIALIZED (${knnBody})
         SELECT node_id, score FROM knn_page
         LIMIT ${params.limit} OFFSET ${params.offset}
       `;
     }
     const conditions = [
-      chunkYX3H63VV_cjs.sql`${table}."graph_id" = ${params.graphId}`
+      chunkX2XOQZT3_cjs.sql`${table}."graph_id" = ${params.graphId}`
     ];
     if (candidates !== void 0) {
-      conditions.push(chunkYX3H63VV_cjs.sql`${table}."node_id" IN (${candidates})`);
+      conditions.push(chunkX2XOQZT3_cjs.sql`${table}."node_id" IN (${candidates})`);
     }
     if (params.minScore !== void 0) {
       conditions.push(
-        chunkHAQVISUF_cjs.vectorMinScoreCondition(distance, params.metric, params.minScore)
+        chunkUTTW2Q3M_cjs.vectorMinScoreCondition(distance, params.metric, params.minScore)
       );
     }
-    const pageClause = chunk5YBDB7UG_cjs.vectorPageClause(params.limit, params.offset);
-    return chunkYX3H63VV_cjs.sql`
+    const pageClause = chunkVGMNGWBR_cjs.vectorPageClause(params.limit, params.offset);
+    return chunkX2XOQZT3_cjs.sql`
       SELECT ${table}."node_id" AS node_id, ${score} AS score
       FROM ${table}
-      WHERE ${chunkYX3H63VV_cjs.sql.join(conditions, chunkYX3H63VV_cjs.sql` AND `)}
+      WHERE ${chunkX2XOQZT3_cjs.sql.join(conditions, chunkX2XOQZT3_cjs.sql` AND `)}
       ORDER BY ${distance} ASC
       ${pageClause}
     `;
@@ -230,7 +230,7 @@ var sqliteVecStrategy = {
     return void 0;
   },
   buildDropStorage(slot) {
-    const table = chunkHAQVISUF_cjs.quoteIdentifier(
+    const table = chunkUTTW2Q3M_cjs.quoteIdentifier(
       tableName(slot.graphId, slot.nodeKind, slot.fieldPath)
     );
     return [`DROP TABLE IF EXISTS ${table}`];
@@ -238,5 +238,5 @@ var sqliteVecStrategy = {
 };
 
 exports.sqliteVecStrategy = sqliteVecStrategy;
-//# sourceMappingURL=chunk-HQRZEYYB.cjs.map
-//# sourceMappingURL=chunk-HQRZEYYB.cjs.map
+//# sourceMappingURL=chunk-FFQGI67R.cjs.map
+//# sourceMappingURL=chunk-FFQGI67R.cjs.map

package/dist/{chunk-HQRZEYYB.cjs.map → chunk-FFQGI67R.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/query/dialect/vector/sqlite-vec-strategy.ts"],"names":["assertFiniteEmbedding","sql","vectorPhysicalName","quoteIdentifier","VECTOR_CONTRIBUTION_PREFIX","vectorScoreExpression","conditions","vectorMinScoreCondition","vectorPageClause"],"mappings":"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","file":"chunk-HQRZEYYB.cjs","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"]}
+{"version":3,"sources":["../src/query/dialect/vector/sqlite-vec-strategy.ts"],"names":["assertFiniteEmbedding","sql","vectorPhysicalName","quoteIdentifier","VECTOR_CONTRIBUTION_PREFIX","vectorScoreExpression","conditions","vectorMinScoreCondition","vectorPageClause"],"mappings":"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","file":"chunk-FFQGI67R.cjs","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-YIRLBUNN.js → chunk-FMPZPOUD.js}

@@ -1,4 +1,4 @@
-import { unwrap, validateGraphExtension } from './chunk-SCTZRFW5.js';
+import { unwrap, validateGraphExtension } from './chunk-EQOQOT55.js';
 
 // src/graph-extension/define-graph-extension.ts
 function defineGraphExtension(input) {
@@ -6,5 +6,5 @@ function defineGraphExtension(input) {
 }
 
 export { defineGraphExtension };
-//# sourceMappingURL=chunk-YIRLBUNN.js.map
-//# sourceMappingURL=chunk-YIRLBUNN.js.map
+//# sourceMappingURL=chunk-FMPZPOUD.js.map
+//# sourceMappingURL=chunk-FMPZPOUD.js.map

package/dist/{chunk-YIRLBUNN.js.map → chunk-FMPZPOUD.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/graph-extension/define-graph-extension.ts"],"names":[],"mappings":";;;AAyDO,SAAS,qBAAqB,KAAA,EAAuC;AAC1E,EAAA,OAAO,OAAO,sBAAA,CAAuB,KAAA,EAAO,EAAE,MAAA,EAAQ,IAAA,EAAM,CAAC,CAAA;AAC/D","file":"chunk-YIRLBUNN.js","sourcesContent":["/**\n * Public entry for declaring a graph extension.\n *\n * Pure value: validates the input, deeply freezes the result, and returns\n * a `GraphExtension`. Invalid documents throw\n * `GraphExtensionValidationError` carrying every issue with a\n * JSON-pointer `path` to the offending field.\n */\nimport { unwrap } from \"../utils/result\";\nimport { type GraphExtension } from \"./extension-types\";\nimport { validateGraphExtension } from \"./validation\";\n\n/**\n * Validates and freezes a graph-extension document.\n *\n * Authoring entry point — runs validation in **strict** mode: unknown\n * top-level keys (e.g. `node` instead of `nodes`) and unsupported\n * string formats (e.g. `\"date-time\"` with a hyphen instead of\n * `\"datetime\"`) fail loudly with `UNKNOWN_DOCUMENT_KEY` /\n * `UNSUPPORTED_STRING_FORMAT`. The persistence-load path leaves both\n * checks off so a document committed by a future v1.x writer with\n * additive fields still parses on an older v1 reader. Callers\n * accepting raw JSON from an untyped source (e.g. an LLM proposal)\n * should validate first via `validateGraphExtension` and surface\n * the structured issues, then pass the validated document here.\n *\n * @param input - Document describing additional node kinds, edge\n *   kinds, and ontology relations. Must satisfy the v1 property-type\n *   subset documented in `ExtensionPropertyType`.\n *\n * @returns The same document, deeply frozen and shape-checked.\n *\n * @throws {GraphExtensionValidationError} when the document violates\n *   the v1 property-type subset, references undeclared kinds, contains\n *   ontology cycles, etc. The thrown error's `details.issues` array\n *   carries every failure with a JSON-pointer path.\n * @throws {GraphExtensionVersionUnsupportedError} when the document\n *   declares a future major version this library cannot safely decode.\n *\n * @example\n * ```typescript\n * const extension = defineGraphExtension({\n *   nodes: {\n *     Paper: {\n *       properties: {\n *         doi:   { type: \"string\" },\n *         title: { type: \"string\", searchable: { language: \"english\" } },\n *       },\n *       unique: [{ name: \"paper_doi\", fields: [\"doi\"] }],\n *     },\n *   },\n * });\n *\n * const evolved = await store.evolve(extension);\n * const papers = evolved.getNodeCollectionOrThrow(\"Paper\");\n * ```\n */\nexport function defineGraphExtension(input: GraphExtension): GraphExtension {\n  return unwrap(validateGraphExtension(input, { strict: true }));\n}\n"]}
+{"version":3,"sources":["../src/graph-extension/define-graph-extension.ts"],"names":[],"mappings":";;;AAyDO,SAAS,qBAAqB,KAAA,EAAuC;AAC1E,EAAA,OAAO,OAAO,sBAAA,CAAuB,KAAA,EAAO,EAAE,MAAA,EAAQ,IAAA,EAAM,CAAC,CAAA;AAC/D","file":"chunk-FMPZPOUD.js","sourcesContent":["/**\n * Public entry for declaring a graph extension.\n *\n * Pure value: validates the input, deeply freezes the result, and returns\n * a `GraphExtension`. Invalid documents throw\n * `GraphExtensionValidationError` carrying every issue with a\n * JSON-pointer `path` to the offending field.\n */\nimport { unwrap } from \"../utils/result\";\nimport { type GraphExtension } from \"./extension-types\";\nimport { validateGraphExtension } from \"./validation\";\n\n/**\n * Validates and freezes a graph-extension document.\n *\n * Authoring entry point — runs validation in **strict** mode: unknown\n * top-level keys (e.g. `node` instead of `nodes`) and unsupported\n * string formats (e.g. `\"date-time\"` with a hyphen instead of\n * `\"datetime\"`) fail loudly with `UNKNOWN_DOCUMENT_KEY` /\n * `UNSUPPORTED_STRING_FORMAT`. The persistence-load path leaves both\n * checks off so a document committed by a future v1.x writer with\n * additive fields still parses on an older v1 reader. Callers\n * accepting raw JSON from an untyped source (e.g. an LLM proposal)\n * should validate first via `validateGraphExtension` and surface\n * the structured issues, then pass the validated document here.\n *\n * @param input - Document describing additional node kinds, edge\n *   kinds, and ontology relations. Must satisfy the v1 property-type\n *   subset documented in `ExtensionPropertyType`.\n *\n * @returns The same document, deeply frozen and shape-checked.\n *\n * @throws {GraphExtensionValidationError} when the document violates\n *   the v1 property-type subset, references undeclared kinds, contains\n *   ontology cycles, etc. The thrown error's `details.issues` array\n *   carries every failure with a JSON-pointer path.\n * @throws {GraphExtensionVersionUnsupportedError} when the document\n *   declares a future major version this library cannot safely decode.\n *\n * @example\n * ```typescript\n * const extension = defineGraphExtension({\n *   nodes: {\n *     Paper: {\n *       properties: {\n *         doi:   { type: \"string\" },\n *         title: { type: \"string\", searchable: { language: \"english\" } },\n *       },\n *       unique: [{ name: \"paper_doi\", fields: [\"doi\"] }],\n *     },\n *   },\n * });\n *\n * const evolved = await store.evolve(extension);\n * const papers = evolved.getNodeCollectionOrThrow(\"Paper\");\n * ```\n */\nexport function defineGraphExtension(input: GraphExtension): GraphExtension {\n  return unwrap(validateGraphExtension(input, { strict: true }));\n}\n"]}

package/dist/{chunk-LL5D5T5W.cjs → chunk-FSCJOTHF.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkMNURF4RF_cjs = require('./chunk-MNURF4RF.cjs');
-var chunkSAFZ6JTI_cjs = require('./chunk-SAFZ6JTI.cjs');
+var chunkZBV4LQD2_cjs = require('./chunk-ZBV4LQD2.cjs');
+var chunkKTBTSHU6_cjs = require('./chunk-KTBTSHU6.cjs');
 
 // src/core/temporal.ts
 var RECORDED_INSTANT_VERSION = "r1";
@@ -9,7 +9,7 @@ var RECORDED_REVISION_WIDTH = 16;
 var RECORDED_MAX_REVISION = Number.MAX_SAFE_INTEGER;
 var RECORDED_INSTANT_PATTERN = /^r1:(\d{16}):(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)$/;
 function invalidRecordedInstant(value, path) {
-  return new chunkSAFZ6JTI_cjs.ValidationError(
+  return new chunkKTBTSHU6_cjs.ValidationError(
     `${path} must be a canonical versioned recorded instant.`,
     {
       issues: [
@@ -36,7 +36,7 @@ function parseRecordedInstant(value, path = "RecordedInstant") {
   if (!Number.isSafeInteger(revision) || revision < 1 || revision >= RECORDED_MAX_REVISION) {
     throw invalidRecordedInstant(value, path);
   }
-  chunkMNURF4RF_cjs.validateCanonicalIsoDate(recordedAt, path);
+  chunkZBV4LQD2_cjs.validateCanonicalIsoDate(recordedAt, path);
   return { revision, recordedAt };
 }
 function assertValidRecordedInstant(value, path) {
@@ -44,7 +44,7 @@ function assertValidRecordedInstant(value, path) {
 }
 function createRecordedInstant(revision, recordedAt) {
   if (!Number.isSafeInteger(revision) || revision < 1 || revision >= RECORDED_MAX_REVISION) {
-    throw new chunkSAFZ6JTI_cjs.ValidationError(
+    throw new chunkKTBTSHU6_cjs.ValidationError(
       "createRecordedInstant revision must be a valid recorded revision.",
       {
         issues: [
@@ -80,7 +80,7 @@ function asRecordedInstant(value) {
 }
 function resolveReadCoordinate(mode, asOf, suggestion) {
   if (mode !== "asOf" && asOf !== void 0) {
-    throw new chunkSAFZ6JTI_cjs.ValidationError(
+    throw new chunkKTBTSHU6_cjs.ValidationError(
       `Temporal mode "${mode}" does not take an asOf timestamp.`,
       {
         issues: [
@@ -111,7 +111,7 @@ function withRecordedCoordinate(coordinate, recordedAsOf) {
 }
 function assertValidAsOf(mode, asOf, options) {
   if (mode === "asOf" && asOf === void 0) {
-    throw new chunkSAFZ6JTI_cjs.ValidationError(
+    throw new chunkKTBTSHU6_cjs.ValidationError(
       'Temporal mode "asOf" requires a timestamp',
       {
         issues: [
@@ -124,7 +124,7 @@ function assertValidAsOf(mode, asOf, options) {
     );
   }
   if (asOf !== void 0) {
-    chunkMNURF4RF_cjs.validateCanonicalIsoDate(asOf, "asOf");
+    chunkZBV4LQD2_cjs.validateCanonicalIsoDate(asOf, "asOf");
   }
 }
 function describeCoordinate(coordinate) {
@@ -153,5 +153,5 @@ exports.recordedInstantRevision = recordedInstantRevision;
 exports.recordedInstantWallTime = recordedInstantWallTime;
 exports.resolveReadCoordinate = resolveReadCoordinate;
 exports.withRecordedCoordinate = withRecordedCoordinate;
-//# sourceMappingURL=chunk-LL5D5T5W.cjs.map
-//# sourceMappingURL=chunk-LL5D5T5W.cjs.map
+//# sourceMappingURL=chunk-FSCJOTHF.cjs.map
+//# sourceMappingURL=chunk-FSCJOTHF.cjs.map

package/dist/{chunk-LL5D5T5W.cjs.map → chunk-FSCJOTHF.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/temporal.ts"],"names":["ValidationError","validateCanonicalIsoDate"],"mappings":"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","file":"chunk-LL5D5T5W.cjs","sourcesContent":["/**\n * Shared temporal coordinate + validation.\n */\nimport { ValidationError } from \"../errors\";\nimport { validateCanonicalIsoDate } from \"../utils/date\";\nimport { type TemporalMode } from \"./types\";\n\nconst RECORDED_INSTANT_VERSION = \"r1\";\nconst RECORDED_REVISION_WIDTH = 16;\n/** Open interval ceiling for numeric recorded-revision columns. */\nexport const RECORDED_MAX_REVISION = Number.MAX_SAFE_INTEGER;\nconst RECORDED_INSTANT_PATTERN =\n  /^r1:(\\d{16}):(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z)$/;\n\ndeclare const RECORDED_INSTANT_BRAND: unique symbol;\n\n/**\n * A versioned recorded-time anchor containing a fixed-width logical revision\n * and a canonical UTC physical timestamp:\n * `r1:0000000000000001:YYYY-MM-DDTHH:mm:ss.sssZ`.\n *\n * Logical revisions are strictly monotonic per graph and make every commit\n * addressable even when many commits share one wall-clock millisecond. The\n * timestamp is a non-decreasing physical wall-time high-water mark used by\n * diagonal valid-time reads. Same-millisecond commits repeat it; backward clock\n * corrections hold it at the previous value until wall time catches up. The\n * string is canonical and lexicographically ordered by revision, so it can\n * round-trip through plain string checkpoint columns without a custom\n * serializer.\n */\nexport type RecordedInstant = string & {\n  readonly [RECORDED_INSTANT_BRAND]: \"RecordedInstant\";\n};\n\nexport type RecordedInstantParts = Readonly<{\n  revision: number;\n  recordedAt: string;\n}>;\n\nfunction invalidRecordedInstant(value: string, path: string): ValidationError {\n  return new ValidationError(\n    `${path} must be a canonical versioned recorded instant.`,\n    {\n      issues: [\n        {\n          path,\n          message: `Expected ${RECORDED_INSTANT_VERSION}:<${RECORDED_REVISION_WIDTH}-digit revision>:YYYY-MM-DDTHH:mm:ss.sssZ, got \"${value}\"`,\n        },\n      ],\n    },\n    {\n      suggestion:\n        \"Persist the exact string returned by store.recordedNow(); migrate preview-schema checkpoints with migrateLegacyRecordedTime() and migrateRecordedAnchor().\",\n    },\n  );\n}\n\nexport function parseRecordedInstant(\n  value: string,\n  path = \"RecordedInstant\",\n): RecordedInstantParts {\n  const match = RECORDED_INSTANT_PATTERN.exec(value);\n  if (match === null) throw invalidRecordedInstant(value, path);\n  const revisionText = match[1];\n  const recordedAt = match[2];\n  if (revisionText === undefined || recordedAt === undefined) {\n    throw invalidRecordedInstant(value, path);\n  }\n  const revision = Number(revisionText);\n  if (\n    !Number.isSafeInteger(revision) ||\n    revision < 1 ||\n    revision >= RECORDED_MAX_REVISION\n  ) {\n    throw invalidRecordedInstant(value, path);\n  }\n  validateCanonicalIsoDate(recordedAt, path);\n  return { revision, recordedAt };\n}\n\nexport function assertValidRecordedInstant(value: string, path: string): void {\n  parseRecordedInstant(value, path);\n}\n\nexport function createRecordedInstant(\n  revision: number,\n  recordedAt: string,\n): RecordedInstant {\n  if (\n    !Number.isSafeInteger(revision) ||\n    revision < 1 ||\n    revision >= RECORDED_MAX_REVISION\n  ) {\n    throw new ValidationError(\n      \"createRecordedInstant revision must be a valid recorded revision.\",\n      {\n        issues: [\n          {\n            path: \"createRecordedInstant.revision\",\n            message: `Expected a safe integer from 1 through ${String(RECORDED_MAX_REVISION - 1)}, got ${String(revision)}`,\n          },\n        ],\n      },\n    );\n  }\n  const revisionText = revision\n    .toString()\n    .padStart(RECORDED_REVISION_WIDTH, \"0\");\n  return asRecordedInstant(\n    `${RECORDED_INSTANT_VERSION}:${revisionText}:${recordedAt}`,\n  );\n}\n\n/**\n * Returns the canonical UTC wall-time component of a recorded anchor.\n *\n * The value is non-decreasing per graph, but it is not the commit-order key;\n * use the complete {@link RecordedInstant} when ordering or replaying commits.\n */\nexport function recordedInstantWallTime(instant: RecordedInstant): string {\n  return parseRecordedInstant(instant).recordedAt;\n}\n\n/** Returns the strict per-graph logical revision carried by an anchor. */\nexport function recordedInstantRevision(instant: RecordedInstant): number {\n  return parseRecordedInstant(instant).revision;\n}\n\n/**\n * Compares two recorded anchors by logical revision.\n *\n * Revisions are local to a graph, so only compare anchors produced by the same\n * graph. The physical wall-time component deliberately does not participate.\n */\nexport function compareRecordedInstants(\n  left: RecordedInstant,\n  right: RecordedInstant,\n): -1 | 0 | 1 {\n  const leftRevision = recordedInstantRevision(left);\n  const rightRevision = recordedInstantRevision(right);\n  if (leftRevision < rightRevision) return -1;\n  if (leftRevision > rightRevision) return 1;\n  return 0;\n}\n\n/**\n * Brands a canonical versioned anchor string as a {@link RecordedInstant}.\n *\n * The escape hatch for an instant that round-trips through untyped storage:\n * captured from {@link Store.recordedNow}, persisted as a plain string, read\n * back, and replayed into `asOfRecorded`. Validates the canonical form eagerly —\n * the same check `asOfRecorded` applies — so a malformed value fails here, at the\n * brand site, rather than deeper in a read. Does *not* assert the instant is a\n * real captured commit; it only guarantees the value is well-formed enough to\n * compare correctly against the recorded relations.\n *\n * @throws {ValidationError} when `value` is not a canonical versioned anchor.\n */\nexport function asRecordedInstant(value: string): RecordedInstant {\n  assertValidRecordedInstant(value, \"asRecordedInstant\");\n  return value as RecordedInstant;\n}\n\n/**\n * The single opaque temporal coordinate every pinned read is resolved\n * against. It carries the valid-time axis plus an optional recorded/system-time\n * axis, so every surface can inject one coordinate object instead of threading\n * each temporal dimension separately.\n */\nexport type ReadCoordinate = Readonly<{\n  /**\n   * The valid-time axis: a resolved temporal mode and (only for `\"asOf\"`) the\n   * instant it is pinned to.\n   */\n  valid: Readonly<{\n    mode: TemporalMode;\n    /** Defined only when `mode` is `\"asOf\"`. */\n    asOf?: string;\n  }>;\n  /** The recorded/system-time axis. Defined only for recorded-pinned views. */\n  recorded?: Readonly<{ asOf: RecordedInstant }>;\n}>;\n\n/**\n * Resolves and validates a `(mode, asOf)` pair into a {@link ReadCoordinate}.\n * Rejects an `asOf` paired with any non-`\"asOf\"` mode rather than silently\n * dropping it — pinning an instant is only meaningful in `\"asOf\"` mode, so a\n * `view({ mode: \"current\", asOf })` is a caller mistake, not a coordinate to\n * quietly discard. Then validates via {@link assertValidAsOf}.\n *\n * @param mode - The temporal mode to pin.\n * @param asOf - The supplied timestamp. Required for `\"asOf\"`; rejected for\n *   every other mode.\n * @param suggestion - Caller-specific remediation hint for the\n *   missing/invalid-timestamp case.\n */\nexport function resolveReadCoordinate(\n  mode: TemporalMode,\n  asOf: string | undefined,\n  suggestion?: string,\n): ReadCoordinate {\n  if (mode !== \"asOf\" && asOf !== undefined) {\n    throw new ValidationError(\n      `Temporal mode \"${mode}\" does not take an asOf timestamp.`,\n      {\n        issues: [\n          {\n            path: \"asOf\",\n            message: `asOf is only valid with mode \"asOf\", not \"${mode}\"`,\n          },\n        ],\n      },\n      {\n        suggestion:\n          'Pin an instant with store.asOf(timestamp) or store.view({ mode: \"asOf\", asOf }); drop asOf for other modes.',\n      },\n    );\n  }\n  assertValidAsOf(\n    mode,\n    asOf,\n    suggestion === undefined ? undefined : { suggestion },\n  );\n  return { valid: asOf === undefined ? { mode } : { mode, asOf } };\n}\n\n/**\n * Adds a recorded/system-time pin to an existing valid-time coordinate.\n * Direct `store.asOfRecorded(T)` passes the diagonal valid-time coordinate\n * (`mode: \"asOf\", asOf: T`); `store.asOf(vt).asOfRecorded(rt)` passes the\n * already-resolved valid coordinate and adds the recorded sibling.\n */\nexport function withRecordedCoordinate(\n  coordinate: ReadCoordinate,\n  recordedAsOf: RecordedInstant,\n): ReadCoordinate {\n  assertValidRecordedInstant(recordedAsOf, \"asOfRecorded\");\n  return {\n    ...coordinate,\n    recorded: { asOf: recordedAsOf },\n  };\n}\n\n/**\n * Validates the `asOf` coordinate of a temporal read: `\"asOf\"` mode\n * requires a timestamp, and any supplied timestamp must be a canonical\n * fixed-width UTC ISO-8601 string (`YYYY-MM-DDTHH:mm:ss.sssZ`). The latter\n * is load-bearing — temporal filters compare `asOf` against `valid_from` /\n * `valid_to` as text on SQLite, so a non-canonical value (date-only, an\n * offset, natural language, or variable-width / missing milliseconds like\n * `.1Z`) would sort and compare wrong rather than error. Reached only through\n * {@link resolveReadCoordinate}, which every temporal read entry point routes\n * through (direct reads, queries, subgraphs, algorithms, and StoreView), so\n * they all fail identically.\n *\n * @param mode - The resolved temporal mode.\n * @param asOf - The supplied timestamp (may be `undefined`).\n * @param options.suggestion - A caller-specific remediation hint for the\n *   missing-timestamp case.\n *\n * @throws {ValidationError} when `mode` is `\"asOf\"` and `asOf` is missing, or\n *   when any supplied `asOf` is not a canonical UTC ISO-8601 timestamp. The\n *   canonical check runs for *every* mode that consumes `asOf`, so a\n *   non-canonical value can never reach a text comparison.\n */\nfunction assertValidAsOf(\n  mode: TemporalMode,\n  asOf: string | undefined,\n  options?: Readonly<{ suggestion?: string }>,\n): void {\n  if (mode === \"asOf\" && asOf === undefined) {\n    throw new ValidationError(\n      'Temporal mode \"asOf\" requires a timestamp',\n      {\n        issues: [\n          { path: \"asOf\", message: \"Timestamp is required for asOf mode\" },\n        ],\n      },\n      {\n        suggestion:\n          options?.suggestion ??\n          'Provide an ISO-8601 timestamp for asOf mode, e.g. \"2026-01-01T00:00:00.000Z\".',\n      },\n    );\n  }\n  if (asOf !== undefined) {\n    validateCanonicalIsoDate(asOf, \"asOf\");\n  }\n}\n\n/**\n * A human-readable description of a coordinate for error messages, e.g.\n * `mode \"current\"` or `mode \"asOf\" asOf 2026-01-01T00:00:00.000Z`. Shared by\n * every refusal path (the `StoreView` read-only / current-only / search facades\n * and the sealed-query builder) so they describe a coordinate identically — and\n * a future axis (recorded time) is reflected everywhere from one place.\n */\nexport function describeCoordinate(coordinate: ReadCoordinate): string {\n  const { mode, asOf } = coordinate.valid;\n  const valid =\n    asOf === undefined ? `mode \"${mode}\"` : `mode \"${mode}\" asOf ${asOf}`;\n  return coordinate.recorded === undefined ?\n      valid\n    : `${valid}, recorded asOf ${coordinate.recorded.asOf}`;\n}\n\n/**\n * The structured error-context fields describing a coordinate, shared by the\n * same refusal paths as {@link describeCoordinate}.\n */\nexport function coordinateContext(\n  coordinate: ReadCoordinate,\n): Record<string, unknown> {\n  const { mode, asOf } = coordinate.valid;\n  return {\n    temporalMode: mode,\n    ...(asOf !== undefined && { asOf }),\n    ...(coordinate.recorded === undefined ?\n      {}\n    : { recordedAsOf: coordinate.recorded.asOf }),\n  };\n}\n"]}
+{"version":3,"sources":["../src/core/temporal.ts"],"names":["ValidationError","validateCanonicalIsoDate"],"mappings":"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","file":"chunk-FSCJOTHF.cjs","sourcesContent":["/**\n * Shared temporal coordinate + validation.\n */\nimport { ValidationError } from \"../errors\";\nimport { validateCanonicalIsoDate } from \"../utils/date\";\nimport { type TemporalMode } from \"./types\";\n\nconst RECORDED_INSTANT_VERSION = \"r1\";\nconst RECORDED_REVISION_WIDTH = 16;\n/** Open interval ceiling for numeric recorded-revision columns. */\nexport const RECORDED_MAX_REVISION = Number.MAX_SAFE_INTEGER;\nconst RECORDED_INSTANT_PATTERN =\n  /^r1:(\\d{16}):(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z)$/;\n\ndeclare const RECORDED_INSTANT_BRAND: unique symbol;\n\n/**\n * A versioned recorded-time anchor containing a fixed-width logical revision\n * and a canonical UTC physical timestamp:\n * `r1:0000000000000001:YYYY-MM-DDTHH:mm:ss.sssZ`.\n *\n * Logical revisions are strictly monotonic per graph and make every commit\n * addressable even when many commits share one wall-clock millisecond. The\n * timestamp is a non-decreasing physical wall-time high-water mark used by\n * diagonal valid-time reads. Same-millisecond commits repeat it; backward clock\n * corrections hold it at the previous value until wall time catches up. The\n * string is canonical and lexicographically ordered by revision, so it can\n * round-trip through plain string checkpoint columns without a custom\n * serializer.\n */\nexport type RecordedInstant = string & {\n  readonly [RECORDED_INSTANT_BRAND]: \"RecordedInstant\";\n};\n\nexport type RecordedInstantParts = Readonly<{\n  revision: number;\n  recordedAt: string;\n}>;\n\nfunction invalidRecordedInstant(value: string, path: string): ValidationError {\n  return new ValidationError(\n    `${path} must be a canonical versioned recorded instant.`,\n    {\n      issues: [\n        {\n          path,\n          message: `Expected ${RECORDED_INSTANT_VERSION}:<${RECORDED_REVISION_WIDTH}-digit revision>:YYYY-MM-DDTHH:mm:ss.sssZ, got \"${value}\"`,\n        },\n      ],\n    },\n    {\n      suggestion:\n        \"Persist the exact string returned by store.recordedNow(); migrate preview-schema checkpoints with migrateLegacyRecordedTime() and migrateRecordedAnchor().\",\n    },\n  );\n}\n\nexport function parseRecordedInstant(\n  value: string,\n  path = \"RecordedInstant\",\n): RecordedInstantParts {\n  const match = RECORDED_INSTANT_PATTERN.exec(value);\n  if (match === null) throw invalidRecordedInstant(value, path);\n  const revisionText = match[1];\n  const recordedAt = match[2];\n  if (revisionText === undefined || recordedAt === undefined) {\n    throw invalidRecordedInstant(value, path);\n  }\n  const revision = Number(revisionText);\n  if (\n    !Number.isSafeInteger(revision) ||\n    revision < 1 ||\n    revision >= RECORDED_MAX_REVISION\n  ) {\n    throw invalidRecordedInstant(value, path);\n  }\n  validateCanonicalIsoDate(recordedAt, path);\n  return { revision, recordedAt };\n}\n\nexport function assertValidRecordedInstant(value: string, path: string): void {\n  parseRecordedInstant(value, path);\n}\n\nexport function createRecordedInstant(\n  revision: number,\n  recordedAt: string,\n): RecordedInstant {\n  if (\n    !Number.isSafeInteger(revision) ||\n    revision < 1 ||\n    revision >= RECORDED_MAX_REVISION\n  ) {\n    throw new ValidationError(\n      \"createRecordedInstant revision must be a valid recorded revision.\",\n      {\n        issues: [\n          {\n            path: \"createRecordedInstant.revision\",\n            message: `Expected a safe integer from 1 through ${String(RECORDED_MAX_REVISION - 1)}, got ${String(revision)}`,\n          },\n        ],\n      },\n    );\n  }\n  const revisionText = revision\n    .toString()\n    .padStart(RECORDED_REVISION_WIDTH, \"0\");\n  return asRecordedInstant(\n    `${RECORDED_INSTANT_VERSION}:${revisionText}:${recordedAt}`,\n  );\n}\n\n/**\n * Returns the canonical UTC wall-time component of a recorded anchor.\n *\n * The value is non-decreasing per graph, but it is not the commit-order key;\n * use the complete {@link RecordedInstant} when ordering or replaying commits.\n */\nexport function recordedInstantWallTime(instant: RecordedInstant): string {\n  return parseRecordedInstant(instant).recordedAt;\n}\n\n/** Returns the strict per-graph logical revision carried by an anchor. */\nexport function recordedInstantRevision(instant: RecordedInstant): number {\n  return parseRecordedInstant(instant).revision;\n}\n\n/**\n * Compares two recorded anchors by logical revision.\n *\n * Revisions are local to a graph, so only compare anchors produced by the same\n * graph. The physical wall-time component deliberately does not participate.\n */\nexport function compareRecordedInstants(\n  left: RecordedInstant,\n  right: RecordedInstant,\n): -1 | 0 | 1 {\n  const leftRevision = recordedInstantRevision(left);\n  const rightRevision = recordedInstantRevision(right);\n  if (leftRevision < rightRevision) return -1;\n  if (leftRevision > rightRevision) return 1;\n  return 0;\n}\n\n/**\n * Brands a canonical versioned anchor string as a {@link RecordedInstant}.\n *\n * The escape hatch for an instant that round-trips through untyped storage:\n * captured from {@link Store.recordedNow}, persisted as a plain string, read\n * back, and replayed into `asOfRecorded`. Validates the canonical form eagerly —\n * the same check `asOfRecorded` applies — so a malformed value fails here, at the\n * brand site, rather than deeper in a read. Does *not* assert the instant is a\n * real captured commit; it only guarantees the value is well-formed enough to\n * compare correctly against the recorded relations.\n *\n * @throws {ValidationError} when `value` is not a canonical versioned anchor.\n */\nexport function asRecordedInstant(value: string): RecordedInstant {\n  assertValidRecordedInstant(value, \"asRecordedInstant\");\n  return value as RecordedInstant;\n}\n\n/**\n * The single opaque temporal coordinate every pinned read is resolved\n * against. It carries the valid-time axis plus an optional recorded/system-time\n * axis, so every surface can inject one coordinate object instead of threading\n * each temporal dimension separately.\n */\nexport type ReadCoordinate = Readonly<{\n  /**\n   * The valid-time axis: a resolved temporal mode and (only for `\"asOf\"`) the\n   * instant it is pinned to.\n   */\n  valid: Readonly<{\n    mode: TemporalMode;\n    /** Defined only when `mode` is `\"asOf\"`. */\n    asOf?: string;\n  }>;\n  /** The recorded/system-time axis. Defined only for recorded-pinned views. */\n  recorded?: Readonly<{ asOf: RecordedInstant }>;\n}>;\n\n/**\n * Resolves and validates a `(mode, asOf)` pair into a {@link ReadCoordinate}.\n * Rejects an `asOf` paired with any non-`\"asOf\"` mode rather than silently\n * dropping it — pinning an instant is only meaningful in `\"asOf\"` mode, so a\n * `view({ mode: \"current\", asOf })` is a caller mistake, not a coordinate to\n * quietly discard. Then validates via {@link assertValidAsOf}.\n *\n * @param mode - The temporal mode to pin.\n * @param asOf - The supplied timestamp. Required for `\"asOf\"`; rejected for\n *   every other mode.\n * @param suggestion - Caller-specific remediation hint for the\n *   missing/invalid-timestamp case.\n */\nexport function resolveReadCoordinate(\n  mode: TemporalMode,\n  asOf: string | undefined,\n  suggestion?: string,\n): ReadCoordinate {\n  if (mode !== \"asOf\" && asOf !== undefined) {\n    throw new ValidationError(\n      `Temporal mode \"${mode}\" does not take an asOf timestamp.`,\n      {\n        issues: [\n          {\n            path: \"asOf\",\n            message: `asOf is only valid with mode \"asOf\", not \"${mode}\"`,\n          },\n        ],\n      },\n      {\n        suggestion:\n          'Pin an instant with store.asOf(timestamp) or store.view({ mode: \"asOf\", asOf }); drop asOf for other modes.',\n      },\n    );\n  }\n  assertValidAsOf(\n    mode,\n    asOf,\n    suggestion === undefined ? undefined : { suggestion },\n  );\n  return { valid: asOf === undefined ? { mode } : { mode, asOf } };\n}\n\n/**\n * Adds a recorded/system-time pin to an existing valid-time coordinate.\n * Direct `store.asOfRecorded(T)` passes the diagonal valid-time coordinate\n * (`mode: \"asOf\", asOf: T`); `store.asOf(vt).asOfRecorded(rt)` passes the\n * already-resolved valid coordinate and adds the recorded sibling.\n */\nexport function withRecordedCoordinate(\n  coordinate: ReadCoordinate,\n  recordedAsOf: RecordedInstant,\n): ReadCoordinate {\n  assertValidRecordedInstant(recordedAsOf, \"asOfRecorded\");\n  return {\n    ...coordinate,\n    recorded: { asOf: recordedAsOf },\n  };\n}\n\n/**\n * Validates the `asOf` coordinate of a temporal read: `\"asOf\"` mode\n * requires a timestamp, and any supplied timestamp must be a canonical\n * fixed-width UTC ISO-8601 string (`YYYY-MM-DDTHH:mm:ss.sssZ`). The latter\n * is load-bearing — temporal filters compare `asOf` against `valid_from` /\n * `valid_to` as text on SQLite, so a non-canonical value (date-only, an\n * offset, natural language, or variable-width / missing milliseconds like\n * `.1Z`) would sort and compare wrong rather than error. Reached only through\n * {@link resolveReadCoordinate}, which every temporal read entry point routes\n * through (direct reads, queries, subgraphs, algorithms, and StoreView), so\n * they all fail identically.\n *\n * @param mode - The resolved temporal mode.\n * @param asOf - The supplied timestamp (may be `undefined`).\n * @param options.suggestion - A caller-specific remediation hint for the\n *   missing-timestamp case.\n *\n * @throws {ValidationError} when `mode` is `\"asOf\"` and `asOf` is missing, or\n *   when any supplied `asOf` is not a canonical UTC ISO-8601 timestamp. The\n *   canonical check runs for *every* mode that consumes `asOf`, so a\n *   non-canonical value can never reach a text comparison.\n */\nfunction assertValidAsOf(\n  mode: TemporalMode,\n  asOf: string | undefined,\n  options?: Readonly<{ suggestion?: string }>,\n): void {\n  if (mode === \"asOf\" && asOf === undefined) {\n    throw new ValidationError(\n      'Temporal mode \"asOf\" requires a timestamp',\n      {\n        issues: [\n          { path: \"asOf\", message: \"Timestamp is required for asOf mode\" },\n        ],\n      },\n      {\n        suggestion:\n          options?.suggestion ??\n          'Provide an ISO-8601 timestamp for asOf mode, e.g. \"2026-01-01T00:00:00.000Z\".',\n      },\n    );\n  }\n  if (asOf !== undefined) {\n    validateCanonicalIsoDate(asOf, \"asOf\");\n  }\n}\n\n/**\n * A human-readable description of a coordinate for error messages, e.g.\n * `mode \"current\"` or `mode \"asOf\" asOf 2026-01-01T00:00:00.000Z`. Shared by\n * every refusal path (the `StoreView` read-only / current-only / search facades\n * and the sealed-query builder) so they describe a coordinate identically — and\n * a future axis (recorded time) is reflected everywhere from one place.\n */\nexport function describeCoordinate(coordinate: ReadCoordinate): string {\n  const { mode, asOf } = coordinate.valid;\n  const valid =\n    asOf === undefined ? `mode \"${mode}\"` : `mode \"${mode}\" asOf ${asOf}`;\n  return coordinate.recorded === undefined ?\n      valid\n    : `${valid}, recorded asOf ${coordinate.recorded.asOf}`;\n}\n\n/**\n * The structured error-context fields describing a coordinate, shared by the\n * same refusal paths as {@link describeCoordinate}.\n */\nexport function coordinateContext(\n  coordinate: ReadCoordinate,\n): Record<string, unknown> {\n  const { mode, asOf } = coordinate.valid;\n  return {\n    temporalMode: mode,\n    ...(asOf !== undefined && { asOf }),\n    ...(coordinate.recorded === undefined ?\n      {}\n    : { recordedAsOf: coordinate.recorded.asOf }),\n  };\n}\n"]}