@nicia-ai/typegraph 0.37.1 → 0.38.0

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/meta-edge.ts","../src/core/external-ref.ts","../src/backend/migrate-vectors.ts"],"names":["META_EDGE_BRAND","z","DEFAULT_EMBEDDING_METRIC","DEFAULT_EMBEDDING_INDEX_TYPE","LEGACY_EMBEDDINGS_TABLE_NAME","isMissingTableError","embedding","EmbeddingDimensionChangedError","quotedTableName","sql","asCompiledRowsSql"],"mappings":"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","file":"index.cjs","sourcesContent":["import {\n  type InferenceType,\n  META_EDGE_BRAND,\n  type MetaEdge,\n  type MetaEdgeProperties,\n} from \"../ontology/types\";\n\n// ============================================================\n// Meta-Edge Factory Options\n// ============================================================\n\n/**\n * Options for creating a meta-edge.\n */\nexport type MetaEdgeOptions = Readonly<{\n  /** Whether the relationship is transitive (A→B, B→C implies A→C) */\n  transitive?: boolean;\n  /** Whether the relationship is symmetric (A→B implies B→A) */\n  symmetric?: boolean;\n  /** Whether the relationship is reflexive (A→A is always true) */\n  reflexive?: boolean;\n  /** Name of the inverse meta-edge */\n  inverse?: string;\n  /** How this meta-edge affects queries and validation */\n  inference?: InferenceType;\n  /** Optional description */\n  description?: string;\n}>;\n\n// ============================================================\n// Meta-Edge Factory\n// ============================================================\n\n/**\n * Creates a custom meta-edge definition.\n *\n * @example\n * ```typescript\n * // Custom meta-edge for regulatory relationships\n * const regulatedBy = metaEdge(\"regulatedBy\", {\n *   description: \"Type X is regulated by authority type Y\",\n *   transitive: false,\n *   symmetric: false,\n * });\n * ```\n */\nexport function metaEdge<K extends string>(\n  name: K,\n  options: MetaEdgeOptions = {},\n): MetaEdge<K> {\n  const properties: MetaEdgeProperties = {\n    transitive: options.transitive ?? false,\n    symmetric: options.symmetric ?? false,\n    reflexive: options.reflexive ?? false,\n    inverse: options.inverse,\n    inference: options.inference ?? \"none\",\n    description: options.description,\n  };\n\n  return Object.freeze({\n    [META_EDGE_BRAND]: true as const,\n    name,\n    properties,\n  });\n}\n","/**\n * External reference type for hybrid overlay patterns.\n *\n * Creates a Zod-compatible schema for referencing entities in external\n * data sources (e.g., existing application tables) from TypeGraph nodes.\n */\nimport { z } from \"zod\";\n\n// ============================================================\n// External Reference Metadata Symbol\n// ============================================================\n\n/**\n * Symbol key for storing external table name on the schema.\n * This allows the schema introspector to detect external reference types\n * and extract source information.\n */\nexport const EXTERNAL_REF_TABLE_KEY = \"_externalRefTable\" as const;\n\n// ============================================================\n// External Reference Value Type\n// ============================================================\n\n/**\n * The shape of an external reference value.\n * Contains the source table identifier and the ID of the referenced record.\n */\nexport type ExternalRefValue<T extends string = string> = Readonly<{\n  table: T;\n  id: string;\n}>;\n\n// ============================================================\n// External Reference Schema Type\n// ============================================================\n\n/**\n * A Zod schema for external references with attached table metadata.\n */\nexport type ExternalRefSchema<T extends string = string> = z.ZodType<\n  ExternalRefValue<T>\n> &\n  Readonly<{\n    [EXTERNAL_REF_TABLE_KEY]: T;\n  }>;\n\n// ============================================================\n// External Reference Factory\n// ============================================================\n\n/**\n * Creates a Zod schema for referencing external data sources.\n *\n * Use this when building a hybrid overlay where TypeGraph stores\n * graph relationships and metadata while your existing tables\n * remain the source of truth for entity data.\n *\n * @param table - The identifier for the external table/source (e.g., \"users\", \"documents\")\n * @returns A Zod schema that validates external reference objects\n *\n * @example\n * ```typescript\n * import { defineNode, externalRef, embedding } from \"@nicia-ai/typegraph\";\n *\n * // Reference documents from your existing application database\n * const Document = defineNode(\"Document\", {\n *   schema: z.object({\n *     source: externalRef(\"documents\"),\n *     embedding: embedding(1536).optional(),\n *     extractedTopics: z.array(z.string()).optional(),\n *   }),\n * });\n *\n * // Create a node referencing an external document\n * await store.nodes.Document.create({\n *   source: { table: \"documents\", id: \"doc_abc123\" },\n *   embedding: await generateEmbedding(docContent),\n * });\n *\n * // Query and hydrate with external data\n * const results = await store\n *   .query()\n *   .from(\"Document\", \"d\")\n *   .whereNode(\"d\", (d) => d.embedding.similarTo(query, 10))\n *   .select((ctx) => ctx.d.source)\n *   .execute();\n *\n * // Fetch full data from your app database\n * const externalIds = results.map((r) => r.id);\n * const fullDocs = await appDb.query.documents.findMany({\n *   where: inArray(documents.id, externalIds),\n * });\n * ```\n */\nexport function externalRef<T extends string>(table: T): ExternalRefSchema<T> {\n  if (typeof table !== \"string\" || table.length === 0) {\n    throw new Error(\n      `External reference table must be a non-empty string, got: ${typeof table === \"string\" ? `\"${table}\"` : typeof table}`,\n    );\n  }\n\n  const schema = z.object({\n    table: z.literal(table),\n    id: z.string().min(1, \"External reference ID must be non-empty\"),\n  });\n\n  // Attach table metadata for introspection\n  return Object.assign(schema, {\n    [EXTERNAL_REF_TABLE_KEY]: table,\n  });\n}\n\n// ============================================================\n// Type Guards\n// ============================================================\n\n/**\n * Checks if a value is an external reference schema.\n */\nexport function isExternalRefSchema(\n  value: unknown,\n): value is ExternalRefSchema {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    EXTERNAL_REF_TABLE_KEY in value &&\n    typeof (value as Record<string, unknown>)[EXTERNAL_REF_TABLE_KEY] ===\n      \"string\"\n  );\n}\n\n/**\n * Gets the table name from an external reference schema.\n * Returns undefined if the schema is not an external reference schema.\n */\nexport function getExternalRefTable(schema: z.ZodType): string | undefined {\n  if (isExternalRefSchema(schema)) {\n    return schema[EXTERNAL_REF_TABLE_KEY];\n  }\n  return undefined;\n}\n\n// ============================================================\n// Helper for creating reference values\n// ============================================================\n\n/**\n * Helper function to create a typed external reference value.\n * Useful when you want to avoid repeating the table name.\n *\n * @example\n * ```typescript\n * const docRef = createExternalRef(\"documents\");\n *\n * await store.nodes.Document.create({\n *   source: docRef(\"doc_123\"),\n *   embedding: [...],\n * });\n * ```\n */\nexport function createExternalRef<T extends string>(\n  table: T,\n): (id: string) => ExternalRefValue<T> {\n  return (id: string) => ({ table, id });\n}\n","/**\n * One-time offline migration: legacy shared embeddings table → per-field\n * strategy storage.\n *\n * ## What this is for\n *\n * The cross-backend vector cutover (#157) dropped the single shared\n * `typegraph_node_embeddings` table. Each\n * `VectorStrategy` now OWNS one typed, fixed-dimension structure per\n * `(nodeKind, fieldPath)` — the only layout that can be ANN-indexed on\n * libSQL and sqlite-vec, not just pgvector.\n *\n * Deployments that wrote embeddings under the old shared table before\n * upgrading still hold those rows. This utility drains them into the new\n * per-field storage **once**, during the upgrade, so existing embedded\n * data survives the cutover without re-embedding from source.\n *\n * It is an explicitly-run, offline step — not wired into `materializeIndexes`\n * or any boot path. Run it once after deploying the new version and before\n * (or alongside) the first `materializeIndexes()`, then drop the legacy\n * table at your leisure.\n *\n * ## How it works\n *\n * - Skips cleanly (returns a zero summary) when the legacy table is absent —\n *   a fresh install, or a re-run after the table was dropped.\n * - Reads rows in keyset-paginated batches (never the whole table at once),\n *   decoding the engine-native embedding column to a numeric array at the SQL\n *   level: sqlite-vec stored a `vec_f32` blob (`vec_to_json` decodes it);\n *   pgvector stored a native `vector` (`::text` yields a `[…]` literal).\n * - Re-inserts each row through `backend.upsertEmbedding`, which routes the\n *   active strategy's `buildUpsert` and idempotently provisions the per-field\n *   storage (the same `(nodeKind, fieldPath)` slot a fresh store write uses).\n *   The migration stays graph-agnostic and execution-correct on both the\n *   sync (better-sqlite3) and async (libsql / Postgres) backends — it does\n *   not re-implement the backend's statement-execution glue.\n *\n * Idempotent and resumable: a partial run followed by a full run converges\n * to the same per-field tables, because every write is an upsert keyed by\n * `(graph_id, node_id)` in the strategy's owned storage.\n */\nimport { type SQL, sql } from \"drizzle-orm\";\n\nimport {\n  DEFAULT_EMBEDDING_INDEX_TYPE,\n  DEFAULT_EMBEDDING_METRIC,\n  type EmbeddingIndexType,\n  type EmbeddingMetric,\n} from \"../core/embedding\";\nimport { EmbeddingDimensionChangedError } from \"../errors\";\nimport { asCompiledRowsSql } from \"../query/sql-intent\";\nimport { isMissingTableError } from \"../utils/sql-errors\";\nimport { quotedTableName } from \"./drizzle/operations/shared\";\nimport { LEGACY_EMBEDDINGS_TABLE_NAME } from \"./drizzle/schema/sqlite\";\nimport { type GraphBackend } from \"./types\";\n\n/**\n * Default rows read per round-trip. Large enough to amortize round-trip\n * latency, small enough to bound peak memory regardless of table size.\n */\nconst DEFAULT_BATCH_SIZE = 500;\n\n/**\n * Metric / index type applied to a migrated field when no\n * {@link MigrateLegacyEmbeddingsOptions.resolveSlotConfig} is supplied (or\n * it returns `undefined`). Matches the defaults `embedding()` and\n * `resolveEmbeddingFields` apply, so a migrated field lands in storage shaped\n * identically to one written fresh through the store. Migrated data is only\n * ever brute-forceable until `materializeIndexes()` builds the ANN index, so\n * the index-type default governs only which ANN structure the per-field\n * storage DDL provisions, not the migration's correctness.\n */\nconst DEFAULT_SLOT_METRIC: EmbeddingMetric = DEFAULT_EMBEDDING_METRIC;\nconst DEFAULT_SLOT_INDEX_TYPE: EmbeddingIndexType =\n  DEFAULT_EMBEDDING_INDEX_TYPE;\n\n/**\n * The resolved storage config for one `(nodeKind, fieldPath)` slot that the\n * legacy table did not record. The legacy shared table stored only the\n * vector and its dimension count — not the metric or index type — so a\n * caller that wants migrated fields to match a specific graph's `embedding()`\n * declarations supplies this resolver.\n */\nexport type LegacyEmbeddingSlotConfig = Readonly<{\n  metric: EmbeddingMetric;\n  indexType: EmbeddingIndexType;\n}>;\n\n/**\n * Options for {@link migrateLegacyEmbeddings}.\n */\nexport type MigrateLegacyEmbeddingsOptions = Readonly<{\n  /**\n   * The backend to migrate, wired with the destination `VectorStrategy`\n   * (i.e. the post-cutover backend). Its `vectorStrategy` owns the per-field\n   * storage rows are written into and its `upsertEmbedding` performs the\n   * writes.\n   */\n  backend: GraphBackend;\n\n  /**\n   * Restrict the migration to a single graph. When omitted, every graph's\n   * rows in the legacy table are migrated (the table is graph-scoped by its\n   * `graph_id` column).\n   */\n  graphId?: string;\n\n  /**\n   * Resolves the metric / index type for a `(nodeKind, fieldPath)` slot the\n   * legacy table didn't persist. Return `undefined` to fall back to the\n   * cosine / hnsw defaults. Supply this (typically reading the graph's\n   * `embedding()` declarations) when migrated fields must match a specific\n   * metric — e.g. an `l2` field, which scores incorrectly under the cosine\n   * default.\n   */\n  resolveSlotConfig?: (\n    nodeKind: string,\n    fieldPath: string,\n  ) => LegacyEmbeddingSlotConfig | undefined;\n\n  /** Rows read per round-trip. Defaults to {@link DEFAULT_BATCH_SIZE}. */\n  batchSize?: number;\n\n  /**\n   * Physical name of the legacy table to drain. Defaults to\n   * {@link LEGACY_EMBEDDINGS_TABLE_NAME}. Override only for a non-default\n   * deployment that renamed the embeddings table.\n   */\n  legacyTableName?: string;\n}>;\n\n/**\n * Summary of a {@link migrateLegacyEmbeddings} run.\n */\nexport type MigrateLegacyEmbeddingsResult = Readonly<{\n  /** Total embedding rows re-inserted into per-field storage. */\n  migrated: number;\n  /**\n   * Per-`(nodeKind, fieldPath)` counts, keyed `\"<nodeKind>.<fieldPath>\"`\n   * (the strategy's logical-slot key form). Empty when the legacy table was\n   * absent or held no rows for the requested scope.\n   */\n  perField: Readonly<Record<string, number>>;\n  /**\n   * Rows skipped because their vector length didn't match the per-field\n   * table's fixed dimension. The legacy shared column allowed mixed\n   * dimensions for one `(nodeKind, fieldPath)` (e.g. an unmigrated model\n   * change); the first migrated row fixes the typed table's dimension and\n   * any differently-sized rows for that slot are skipped rather than aborting\n   * the whole migration. Keyed `\"<nodeKind>.<fieldPath>\"`. Non-empty here\n   * means those fields need a deliberate re-embed at a single dimension.\n   */\n  skippedDimensionMismatch: Readonly<Record<string, number>>;\n  /**\n   * Rows skipped because their legacy embedding could not be decoded into a\n   * finite-number array — a corrupt value (e.g. a pgvector `vector` column\n   * permits `NaN`/`Infinity`, which is not valid JSON). Keyed\n   * `\"<nodeKind>.<fieldPath>\"`. Skipping + reporting keeps one bad row from\n   * aborting the whole migration; non-empty here means those rows need manual\n   * repair.\n   */\n  skippedDecodeError: Readonly<Record<string, number>>;\n  /**\n   * Whether the legacy table existed. `false` means the run was a clean\n   * no-op (fresh install, or already-dropped table on a re-run).\n   */\n  legacyTablePresent: boolean;\n}>;\n\n/**\n * A single legacy embedding row, with the engine-native vector already\n * decoded to a JSON array string by the dialect-specific SELECT. The\n * legacy `dimensions` column is intentionally not read: the decoded array's\n * length is the authoritative fixed dimension for the destination slot, and\n * relying on it sidesteps the per-driver string/number coercion the legacy\n * integer column would otherwise need.\n */\ntype LegacyEmbeddingRow = Readonly<{\n  graph_id: string;\n  node_kind: string;\n  node_id: string;\n  field_path: string;\n  /** JSON array text, e.g. `\"[0.1,0.2,0.3]\"` — decoded per dialect. */\n  embedding_json: string;\n}>;\n\n/**\n * Re-inserts every embedding from the legacy shared\n * `typegraph_node_embeddings` table into the active\n * `backend.vectorStrategy`'s per-`(nodeKind, fieldPath)` storage.\n *\n * One-time, explicitly-run upgrade step for the shared-table → per-field\n * cutover (#157). Idempotent, batched, and a clean no-op when the legacy\n * table is absent. See the module doc comment for the full contract.\n *\n * @throws Error when the backend exposes no `vectorStrategy` /\n *         `upsertEmbedding` (nothing to migrate *into*) — a configuration\n *         error the caller must fix by wiring the destination strategy\n *         before migrating.\n */\nexport async function migrateLegacyEmbeddings(\n  options: MigrateLegacyEmbeddingsOptions,\n): Promise<MigrateLegacyEmbeddingsResult> {\n  const {\n    backend,\n    graphId,\n    resolveSlotConfig,\n    batchSize = DEFAULT_BATCH_SIZE,\n    legacyTableName = LEGACY_EMBEDDINGS_TABLE_NAME,\n  } = options;\n\n  if (\n    backend.vectorStrategy === undefined ||\n    backend.upsertEmbedding === undefined\n  ) {\n    throw new Error(\n      \"migrateLegacyEmbeddings requires a backend wired with a vectorStrategy \" +\n        \"(the destination per-field storage). Pass the post-cutover backend.\",\n    );\n  }\n  if (!Number.isInteger(batchSize) || batchSize <= 0) {\n    throw new RangeError(\n      `batchSize must be a positive integer, got: ${batchSize}`,\n    );\n  }\n  const upsertEmbedding = backend.upsertEmbedding;\n  const ensureVectorSlotContribution = backend.ensureVectorSlotContribution;\n\n  const perField: Record<string, number> = {};\n  const skippedDimensionMismatch: Record<string, number> = {};\n  const skippedDecodeError: Record<string, number> = {};\n  // (kind, field) slots whose per-field table + durable marker this run has\n  // already provisioned, mapped to the dimension the table was fixed at.\n  // `upsertEmbedding` asserts the marker (#135) and no longer self-creates\n  // the table, so this offline migration (privileged) provisions each slot\n  // once — at the first row's dimension, which fixes the typed table just as\n  // the original lazy write did. Differently-sized later rows for the same\n  // slot are detected against this map and skipped BEFORE the upsert: the\n  // marker assert would otherwise read the differently-dimensioned slot as\n  // stale and abort the whole migration, and the ensure is deliberately not\n  // re-run per row (that would trip the marker drift-guard).\n  const ensuredSlots = new Map<string, number>();\n  let migrated = 0;\n\n  let cursor: LegacyRowCursor | undefined;\n  for (;;) {\n    let batch: readonly LegacyEmbeddingRow[];\n    try {\n      batch = await readLegacyBatch(backend, {\n        legacyTableName,\n        graphId,\n        batchSize,\n        after: cursor,\n      });\n    } catch (error) {\n      // A missing legacy table is the expected \"nothing to migrate\" path on\n      // the first read — surface it as a clean no-op, not a failure.\n      if (cursor === undefined && isMissingTableError(error)) {\n        return {\n          migrated: 0,\n          perField: {},\n          skippedDimensionMismatch: {},\n          skippedDecodeError: {},\n          legacyTablePresent: false,\n        };\n      }\n      throw error;\n    }\n\n    if (batch.length === 0) break;\n\n    for (const row of batch) {\n      const slotKey = `${row.node_kind}.${row.field_path}`;\n\n      let embedding: readonly number[];\n      try {\n        embedding = decodeEmbeddingJson(row);\n      } catch {\n        // A corrupt legacy value (e.g. a pgvector `vector` column permits\n        // NaN/Infinity, which is not valid JSON) is skipped + reported rather\n        // than aborting the whole migration on one bad row.\n        skippedDecodeError[slotKey] = (skippedDecodeError[slotKey] ?? 0) + 1;\n        continue;\n      }\n      const config = resolveSlotConfig?.(row.node_kind, row.field_path);\n      // The decoded length is the authoritative fixed dimension — the\n      // strategy provisions its column type (e.g. `F32_BLOB(N)`) from it.\n      const slot = {\n        graphId: row.graph_id,\n        nodeKind: row.node_kind,\n        fieldPath: row.field_path,\n        dimensions: embedding.length,\n        metric: config?.metric ?? DEFAULT_SLOT_METRIC,\n        indexType: config?.indexType ?? DEFAULT_SLOT_INDEX_TYPE,\n      };\n\n      // Provision the per-field table + durable marker before the first\n      // write into this slot. Once per (graph, kind, field): the first row's\n      // dimension fixes the table. Keyed by graph id too — the legacy table\n      // is graph-scoped, so the same `kind.field` can recur across graphs.\n      const ensuredKey = JSON.stringify([\n        row.graph_id,\n        row.node_kind,\n        row.field_path,\n      ]);\n      if (\n        ensureVectorSlotContribution !== undefined &&\n        !ensuredSlots.has(ensuredKey)\n      ) {\n        await ensureVectorSlotContribution(slot);\n        ensuredSlots.set(ensuredKey, slot.dimensions);\n      }\n\n      // The legacy shared column allowed mixed dimensions for one\n      // (nodeKind, fieldPath); the per-field table is fixed at the first\n      // migrated row's dimension. Skip a differently-sized row up front —\n      // its slot would fail the marker assert as stale (different\n      // signature), aborting the migration instead of skipping the row.\n      const provisionedDimensions = ensuredSlots.get(ensuredKey);\n      if (\n        provisionedDimensions !== undefined &&\n        provisionedDimensions !== embedding.length\n      ) {\n        skippedDimensionMismatch[slotKey] =\n          (skippedDimensionMismatch[slotKey] ?? 0) + 1;\n        continue;\n      }\n\n      try {\n        await upsertEmbedding({ ...slot, nodeId: row.node_id, embedding });\n      } catch (error) {\n        // The legacy shared column allowed mixed dimensions for one\n        // (nodeKind, fieldPath); the per-field table is fixed at the first\n        // migrated row's dimension, so a differently-sized row is skipped and\n        // reported rather than aborting the whole migration.\n        if (error instanceof EmbeddingDimensionChangedError) {\n          skippedDimensionMismatch[slotKey] =\n            (skippedDimensionMismatch[slotKey] ?? 0) + 1;\n          continue;\n        }\n        throw error;\n      }\n\n      migrated += 1;\n      perField[slotKey] = (perField[slotKey] ?? 0) + 1;\n    }\n\n    if (batch.length < batchSize) break;\n    const last = batch.at(-1)!;\n    cursor = {\n      graphId: last.graph_id,\n      nodeKind: last.node_kind,\n      nodeId: last.node_id,\n      fieldPath: last.field_path,\n    };\n  }\n\n  return {\n    migrated,\n    perField,\n    skippedDimensionMismatch,\n    skippedDecodeError,\n    legacyTablePresent: true,\n  };\n}\n\n/**\n * Composite keyset cursor over the legacy table's primary key\n * `(graph_id, node_kind, node_id, field_path)`. Stable under concurrent\n * writes and immune to OFFSET drift, so a batched walk reads every row once.\n */\ntype LegacyRowCursor = Readonly<{\n  graphId: string;\n  nodeKind: string;\n  nodeId: string;\n  fieldPath: string;\n}>;\n\ntype ReadLegacyBatchParams = Readonly<{\n  legacyTableName: string;\n  graphId: string | undefined;\n  batchSize: number;\n  after: LegacyRowCursor | undefined;\n}>;\n\n/**\n * Reads one keyset-paginated batch of legacy rows, ordered by the primary\n * key, with the engine-native embedding column decoded to a JSON array\n * string by the dialect.\n */\nasync function readLegacyBatch(\n  backend: GraphBackend,\n  params: ReadLegacyBatchParams,\n): Promise<readonly LegacyEmbeddingRow[]> {\n  const table = quotedTableName(params.legacyTableName);\n  const embeddingJson = legacyEmbeddingDecodeExpression(backend);\n\n  const conditions: SQL[] = [];\n  if (params.graphId !== undefined) {\n    conditions.push(sql`\"graph_id\" = ${params.graphId}`);\n  }\n  if (params.after !== undefined) {\n    conditions.push(keysetAfterCondition(params.after));\n  }\n\n  const whereClause =\n    conditions.length === 0 ?\n      sql``\n    : sql` WHERE ${sql.join(conditions, sql` AND `)}`;\n\n  const query = sql`\n    SELECT\n      \"graph_id\" AS graph_id,\n      \"node_kind\" AS node_kind,\n      \"node_id\" AS node_id,\n      \"field_path\" AS field_path,\n      ${embeddingJson} AS embedding_json\n    FROM ${table}${whereClause}\n    ORDER BY \"graph_id\" ASC, \"node_kind\" ASC, \"node_id\" ASC, \"field_path\" ASC\n    LIMIT ${params.batchSize}\n  `;\n\n  return backend.execute<LegacyEmbeddingRow>(asCompiledRowsSql(query));\n}\n\n/**\n * The strict `>` comparison over the composite primary key, expressed as\n * the standard lexicographic OR-chain so it works on every dialect (SQLite\n * supports row-value comparison, but Postgres + SQLite both accept this\n * portable form).\n */\nfunction keysetAfterCondition(after: LegacyRowCursor): SQL {\n  return sql`\n    (\n        \"graph_id\" > ${after.graphId}\n        OR (\"graph_id\" = ${after.graphId} AND \"node_kind\" > ${after.nodeKind})\n        OR (\"graph_id\" = ${after.graphId} AND \"node_kind\" = ${after.nodeKind} AND \"node_id\" > ${after.nodeId})\n        OR (\n          \"graph_id\" = ${after.graphId}\n          AND \"node_kind\" = ${after.nodeKind}\n          AND \"node_id\" = ${after.nodeId}\n          AND \"field_path\" > ${after.fieldPath}\n        )\n      )\n  `;\n}\n\n/**\n * The SQL expression that decodes the legacy engine-native embedding column\n * into a JSON array string `embedding_json`. The single dialect branch in\n * this whole module: the legacy storage formats are genuinely engine-\n * specific, and there is no longer a strategy abstraction over the *legacy*\n * table to delegate to.\n */\nfunction legacyEmbeddingDecodeExpression(backend: GraphBackend): SQL {\n  switch (backend.dialect) {\n    case \"sqlite\": {\n      // Legacy SQLite embeddings were written via `vec_f32('[…]')`\n      // (sqlite-vec binary). `vec_to_json` is its inverse, yielding the\n      // JSON array text. Requires sqlite-vec on the connection — which the\n      // legacy write path also required, so any deployment with legacy rows\n      // has it loaded.\n      return sql`vec_to_json(\"embedding\")`;\n    }\n    case \"postgres\": {\n      // pgvector's native `vector` casts to its `[…]` text literal, which is\n      // valid JSON for `JSON.parse`.\n      return sql`\"embedding\"::text`;\n    }\n    default: {\n      const _exhaustive: never = backend.dialect;\n      throw new Error(\n        `migrateLegacyEmbeddings does not support dialect: ${String(_exhaustive)}`,\n      );\n    }\n  }\n}\n\n/**\n * Parses a decoded `embedding_json` array, asserting it is a non-empty array\n * of finite numbers. A bad decode (wrong type, NaN) names the offending row\n * loudly instead of writing a corrupt vector into per-field storage.\n */\nfunction decodeEmbeddingJson(row: LegacyEmbeddingRow): readonly number[] {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(row.embedding_json) as unknown;\n  } catch (error) {\n    throw new Error(\n      `Failed to decode legacy embedding for ${row.node_kind}.${row.field_path} ` +\n        `(graph ${row.graph_id}, node ${row.node_id}): not valid JSON.`,\n      { cause: error },\n    );\n  }\n  if (!Array.isArray(parsed) || parsed.length === 0) {\n    throw new Error(\n      `Legacy embedding for ${row.node_kind}.${row.field_path} ` +\n        `(graph ${row.graph_id}, node ${row.node_id}) decoded to a non-array ` +\n        `or empty value.`,\n    );\n  }\n  for (const [index, value] of parsed.entries()) {\n    if (typeof value !== \"number\" || !Number.isFinite(value)) {\n      throw new TypeError(\n        `Legacy embedding for ${row.node_kind}.${row.field_path} ` +\n          `(graph ${row.graph_id}, node ${row.node_id}) has a non-finite ` +\n          `value at index ${index}: ${String(value)}.`,\n      );\n    }\n  }\n  return parsed as readonly number[];\n}\n"]}
+{"version":3,"sources":["../src/backend/migrate-vectors.ts"],"names":["DEFAULT_EMBEDDING_METRIC","DEFAULT_EMBEDDING_INDEX_TYPE","LEGACY_EMBEDDINGS_TABLE_NAME","isMissingTableError","embedding","EmbeddingDimensionChangedError","requireDefined","sql","asCompiledRowsSql"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,IAAM,kBAAA,GAAqB,GAAA;AAY3B,IAAM,mBAAA,GAAuCA,0CAAA;AAC7C,IAAM,uBAAA,GACJC,8CAAA;AA8HF,eAAsB,wBACpB,OAAA,EACwC;AACxC,EAAA,MAAM;AAAA,IACJ,OAAA;AAAA,IACA,OAAA;AAAA,IACA,iBAAA;AAAA,IACA,SAAA,GAAY,kBAAA;AAAA,IACZ,eAAA,GAAkBC;AAAA,GACpB,GAAI,OAAA;AAEJ,EAAA,IACE,OAAA,CAAQ,cAAA,KAAmB,MAAA,IAC3B,OAAA,CAAQ,oBAAoB,MAAA,EAC5B;AACA,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KAEF;AAAA,EACF;AACA,EAAA,IAAI,CAAC,MAAA,CAAO,SAAA,CAAU,SAAS,CAAA,IAAK,aAAa,CAAA,EAAG;AAClD,IAAA,MAAM,IAAI,UAAA;AAAA,MACR,8CAA8C,SAAS,CAAA;AAAA,KACzD;AAAA,EACF;AACA,EAAA,MAAM,kBAAkB,OAAA,CAAQ,eAAA;AAChC,EAAA,MAAM,+BAA+B,OAAA,CAAQ,4BAAA;AAE7C,EAAA,MAAM,WAAmC,EAAC;AAC1C,EAAA,MAAM,2BAAmD,EAAC;AAC1D,EAAA,MAAM,qBAA6C,EAAC;AAWpD,EAAA,MAAM,YAAA,uBAAmB,GAAA,EAAoB;AAC7C,EAAA,IAAI,QAAA,GAAW,CAAA;AAEf,EAAA,IAAI,MAAA;AACJ,EAAA,WAAS;AACP,IAAA,IAAI,KAAA;AACJ,IAAA,IAAI;AACF,MAAA,KAAA,GAAQ,MAAM,gBAAgB,OAAA,EAAS;AAAA,QACrC,eAAA;AAAA,QACA,OAAA;AAAA,QACA,SAAA;AAAA,QACA,KAAA,EAAO;AAAA,OACR,CAAA;AAAA,IACH,SAAS,KAAA,EAAO;AAGd,MAAA,IAAI,MAAA,KAAW,MAAA,IAAaC,qCAAA,CAAoB,KAAK,CAAA,EAAG;AACtD,QAAA,OAAO;AAAA,UACL,QAAA,EAAU,CAAA;AAAA,UACV,UAAU,EAAC;AAAA,UACX,0BAA0B,EAAC;AAAA,UAC3B,oBAAoB,EAAC;AAAA,UACrB,kBAAA,EAAoB;AAAA,SACtB;AAAA,MACF;AACA,MAAA,MAAM,KAAA;AAAA,IACR;AAEA,IAAA,IAAI,KAAA,CAAM,WAAW,CAAA,EAAG;AAExB,IAAA,KAAA,MAAW,OAAO,KAAA,EAAO;AACvB,MAAA,MAAM,UAAU,CAAA,EAAG,GAAA,CAAI,SAAS,CAAA,CAAA,EAAI,IAAI,UAAU,CAAA,CAAA;AAElD,MAAA,IAAIC,UAAAA;AACJ,MAAA,IAAI;AACF,QAAAA,UAAAA,GAAY,oBAAoB,GAAG,CAAA;AAAA,MACrC,CAAA,CAAA,MAAQ;AAIN,QAAA,kBAAA,CAAmB,OAAO,CAAA,GAAA,CAAK,kBAAA,CAAmB,OAAO,KAAK,CAAA,IAAK,CAAA;AACnE,QAAA;AAAA,MACF;AACA,MAAA,MAAM,MAAA,GAAS,iBAAA,GAAoB,GAAA,CAAI,SAAA,EAAW,IAAI,UAAU,CAAA;AAGhE,MAAA,MAAM,IAAA,GAAO;AAAA,QACX,SAAS,GAAA,CAAI,QAAA;AAAA,QACb,UAAU,GAAA,CAAI,SAAA;AAAA,QACd,WAAW,GAAA,CAAI,UAAA;AAAA,QACf,YAAYA,UAAAA,CAAU,MAAA;AAAA,QACtB,MAAA,EAAQ,QAAQ,MAAA,IAAU,mBAAA;AAAA,QAC1B,SAAA,EAAW,QAAQ,SAAA,IAAa;AAAA,OAClC;AAMA,MAAA,MAAM,UAAA,GAAa,KAAK,SAAA,CAAU;AAAA,QAChC,GAAA,CAAI,QAAA;AAAA,QACJ,GAAA,CAAI,SAAA;AAAA,QACJ,GAAA,CAAI;AAAA,OACL,CAAA;AACD,MAAA,IACE,iCAAiC,MAAA,IACjC,CAAC,YAAA,CAAa,GAAA,CAAI,UAAU,CAAA,EAC5B;AACA,QAAA,MAAM,6BAA6B,IAAI,CAAA;AACvC,QAAA,YAAA,CAAa,GAAA,CAAI,UAAA,EAAY,IAAA,CAAK,UAAU,CAAA;AAAA,MAC9C;AAOA,MAAA,MAAM,qBAAA,GAAwB,YAAA,CAAa,GAAA,CAAI,UAAU,CAAA;AACzD,MAAA,IACE,qBAAA,KAA0B,MAAA,IAC1B,qBAAA,KAA0BA,UAAAA,CAAU,MAAA,EACpC;AACA,QAAA,wBAAA,CAAyB,OAAO,CAAA,GAAA,CAC7B,wBAAA,CAAyB,OAAO,KAAK,CAAA,IAAK,CAAA;AAC7C,QAAA;AAAA,MACF;AAEA,MAAA,IAAI;AACF,QAAA,MAAM,eAAA,CAAgB,EAAE,GAAG,IAAA,EAAM,QAAQ,GAAA,CAAI,OAAA,EAAS,SAAA,EAAAA,UAAAA,EAAW,CAAA;AAAA,MACnE,SAAS,KAAA,EAAO;AAKd,QAAA,IAAI,iBAAiBC,gDAAA,EAAgC;AACnD,UAAA,wBAAA,CAAyB,OAAO,CAAA,GAAA,CAC7B,wBAAA,CAAyB,OAAO,KAAK,CAAA,IAAK,CAAA;AAC7C,UAAA;AAAA,QACF;AACA,QAAA,MAAM,KAAA;AAAA,MACR;AAEA,MAAA,QAAA,IAAY,CAAA;AACZ,MAAA,QAAA,CAAS,OAAO,CAAA,GAAA,CAAK,QAAA,CAAS,OAAO,KAAK,CAAA,IAAK,CAAA;AAAA,IACjD;AAEA,IAAA,IAAI,KAAA,CAAM,SAAS,SAAA,EAAW;AAC9B,IAAA,MAAM,IAAA,GAAOC,gCAAA,CAAe,KAAA,CAAM,EAAA,CAAG,EAAE,CAAC,CAAA;AACxC,IAAA,MAAA,GAAS;AAAA,MACP,SAAS,IAAA,CAAK,QAAA;AAAA,MACd,UAAU,IAAA,CAAK,SAAA;AAAA,MACf,QAAQ,IAAA,CAAK,OAAA;AAAA,MACb,WAAW,IAAA,CAAK;AAAA,KAClB;AAAA,EACF;AAEA,EAAA,OAAO;AAAA,IACL,QAAA;AAAA,IACA,QAAA;AAAA,IACA,wBAAA;AAAA,IACA,kBAAA;AAAA,IACA,kBAAA,EAAoB;AAAA,GACtB;AACF;AA0BA,eAAe,eAAA,CACb,SACA,MAAA,EACwC;AACxC,EAAA,MAAM,KAAA,GAAQC,qBAAA,CAAI,UAAA,CAAW,MAAA,CAAO,eAAe,CAAA;AACnD,EAAA,MAAM,aAAA,GAAgB,gCAAgC,OAAO,CAAA;AAE7D,EAAA,MAAM,aAA4B,EAAC;AACnC,EAAA,IAAI,MAAA,CAAO,YAAY,MAAA,EAAW;AAChC,IAAA,UAAA,CAAW,IAAA,CAAKA,qBAAA,CAAA,aAAA,EAAmB,MAAA,CAAO,OAAO,CAAA,CAAE,CAAA;AAAA,EACrD;AACA,EAAA,IAAI,MAAA,CAAO,UAAU,MAAA,EAAW;AAC9B,IAAA,UAAA,CAAW,IAAA,CAAK,oBAAA,CAAqB,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,EACpD;AAEA,EAAA,MAAM,WAAA,GACJ,UAAA,CAAW,MAAA,KAAW,CAAA,GACpBA,qBAAA,CAAA,CAAA,GACAA,+BAAaA,qBAAA,CAAI,IAAA,CAAK,UAAA,EAAYA,qBAAA,CAAA,KAAA,CAAU,CAAC,CAAA,CAAA;AAEjD,EAAA,MAAM,KAAA,GAAQA,qBAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAAA,EAMR,aAAa,CAAA;AAAA,SAAA,EACV,KAAK,GAAG,WAAW;AAAA;AAAA,UAAA,EAElB,OAAO,SAAS;AAAA,EAAA,CAAA;AAG1B,EAAA,OAAO,OAAA,CAAQ,OAAA,CAA4BC,mCAAA,CAAkB,KAAK,CAAC,CAAA;AACrE;AAQA,SAAS,qBAAqB,KAAA,EAAqC;AACjE,EAAA,OAAOD,qBAAA;AAAA;AAAA,qBAAA,EAEc,MAAM,OAAO;AAAA,yBAAA,EACT,KAAA,CAAM,OAAO,CAAA,mBAAA,EAAsB,KAAA,CAAM,QAAQ,CAAA;AAAA,yBAAA,EACjD,MAAM,OAAO,CAAA,mBAAA,EAAsB,MAAM,QAAQ,CAAA,iBAAA,EAAoB,MAAM,MAAM,CAAA;AAAA;AAAA,uBAAA,EAEnF,MAAM,OAAO;AAAA,4BAAA,EACR,MAAM,QAAQ;AAAA,0BAAA,EAChB,MAAM,MAAM;AAAA,6BAAA,EACT,MAAM,SAAS;AAAA;AAAA;AAAA,EAAA,CAAA;AAI9C;AASA,SAAS,gCAAgC,OAAA,EAAoC;AAC3E,EAAA,QAAQ,QAAQ,OAAA;AAAS,IACvB,KAAK,QAAA,EAAU;AAMb,MAAA,OAAOA,qBAAA,CAAA,wBAAA,CAAA;AAAA,IACT;AAAA,IACA,KAAK,UAAA,EAAY;AAGf,MAAA,OAAOA,qBAAA,CAAA,iBAAA,CAAA;AAAA,IACT;AAAA,IACA,SAAS;AACP,MAAA,MAAM,cAAqB,OAAA,CAAQ,OAAA;AACnC,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,kDAAA,EAAqD,MAAA,CAAO,WAAW,CAAC,CAAA;AAAA,OAC1E;AAAA,IACF;AAAA;AAEJ;AAOA,SAAS,oBAAoB,GAAA,EAA4C;AACvE,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI;AACF,IAAA,MAAA,GAAS,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,cAAc,CAAA;AAAA,EACxC,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,sCAAA,EAAyC,GAAA,CAAI,SAAS,CAAA,CAAA,EAAI,GAAA,CAAI,UAAU,CAAA,QAAA,EAC5D,GAAA,CAAI,QAAQ,CAAA,OAAA,EAAU,GAAA,CAAI,OAAO,CAAA,kBAAA,CAAA;AAAA,MAC7C,EAAE,OAAO,KAAA;AAAM,KACjB;AAAA,EACF;AACA,EAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,MAAM,CAAA,IAAK,MAAA,CAAO,WAAW,CAAA,EAAG;AACjD,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,qBAAA,EAAwB,GAAA,CAAI,SAAS,CAAA,CAAA,EAAI,GAAA,CAAI,UAAU,CAAA,QAAA,EAC3C,GAAA,CAAI,QAAQ,CAAA,OAAA,EAAU,GAAA,CAAI,OAAO,CAAA,wCAAA;AAAA,KAE/C;AAAA,EACF;AACA,EAAA,KAAA,MAAW,CAAC,KAAA,EAAO,KAAK,CAAA,IAAK,MAAA,CAAO,SAAQ,EAAG;AAC7C,IAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,CAAC,MAAA,CAAO,QAAA,CAAS,KAAK,CAAA,EAAG;AACxD,MAAA,MAAM,IAAI,SAAA;AAAA,QACR,wBAAwB,GAAA,CAAI,SAAS,CAAA,CAAA,EAAI,GAAA,CAAI,UAAU,CAAA,QAAA,EAC3C,GAAA,CAAI,QAAQ,CAAA,OAAA,EAAU,IAAI,OAAO,CAAA,kCAAA,EACzB,KAAK,CAAA,EAAA,EAAK,MAAA,CAAO,KAAK,CAAC,CAAA,CAAA;AAAA,OAC7C;AAAA,IACF;AAAA,EACF;AACA,EAAA,OAAO,MAAA;AACT","file":"index.cjs","sourcesContent":["/**\n * One-time offline migration: legacy shared embeddings table → per-field\n * strategy storage.\n *\n * ## What this is for\n *\n * The cross-backend vector cutover (#157) dropped the single shared\n * `typegraph_node_embeddings` table. Each\n * `VectorStrategy` now OWNS one typed, fixed-dimension structure per\n * `(nodeKind, fieldPath)` — the only layout that can be ANN-indexed on\n * libSQL and sqlite-vec, not just pgvector.\n *\n * Deployments that wrote embeddings under the old shared table before\n * upgrading still hold those rows. This utility drains them into the new\n * per-field storage **once**, during the upgrade, so existing embedded\n * data survives the cutover without re-embedding from source.\n *\n * It is an explicitly-run, offline step — not wired into `materializeIndexes`\n * or any boot path. Run it once after deploying the new version and before\n * (or alongside) the first `materializeIndexes()`, then drop the legacy\n * table at your leisure.\n *\n * ## How it works\n *\n * - Skips cleanly (returns a zero summary) when the legacy table is absent —\n *   a fresh install, or a re-run after the table was dropped.\n * - Reads rows in keyset-paginated batches (never the whole table at once),\n *   decoding the engine-native embedding column to a numeric array at the SQL\n *   level: sqlite-vec stored a `vec_f32` blob (`vec_to_json` decodes it);\n *   pgvector stored a native `vector` (`::text` yields a `[…]` literal).\n * - Re-inserts each row through `backend.upsertEmbedding`, which routes the\n *   active strategy's `buildUpsert` and idempotently provisions the per-field\n *   storage (the same `(nodeKind, fieldPath)` slot a fresh store write uses).\n *   The migration stays graph-agnostic and execution-correct on both the\n *   sync (better-sqlite3) and async (libsql / Postgres) backends — it does\n *   not re-implement the backend's statement-execution glue.\n *\n * Idempotent and resumable: a partial run followed by a full run converges\n * to the same per-field tables, because every write is an upsert keyed by\n * `(graph_id, node_id)` in the strategy's owned storage.\n */\nimport {\n  DEFAULT_EMBEDDING_INDEX_TYPE,\n  DEFAULT_EMBEDDING_METRIC,\n  type EmbeddingIndexType,\n  type EmbeddingMetric,\n} from \"../core/embedding\";\nimport { EmbeddingDimensionChangedError } from \"../errors\";\nimport { sql, type SqlFragment } from \"../query/sql-fragment\";\nimport { asCompiledRowsSql } from \"../query/sql-intent\";\nimport { requireDefined } from \"../utils/presence\";\nimport { isMissingTableError } from \"../utils/sql-errors\";\nimport { LEGACY_EMBEDDINGS_TABLE_NAME } from \"./drizzle/schema/sqlite\";\nimport { type GraphBackend } from \"./types\";\n\n/**\n * Default rows read per round-trip. Large enough to amortize round-trip\n * latency, small enough to bound peak memory regardless of table size.\n */\nconst DEFAULT_BATCH_SIZE = 500;\n\n/**\n * Metric / index type applied to a migrated field when no\n * {@link MigrateLegacyEmbeddingsOptions.resolveSlotConfig} is supplied (or\n * it returns `undefined`). Matches the defaults `embedding()` and\n * `resolveEmbeddingFields` apply, so a migrated field lands in storage shaped\n * identically to one written fresh through the store. Migrated data is only\n * ever brute-forceable until `materializeIndexes()` builds the ANN index, so\n * the index-type default governs only which ANN structure the per-field\n * storage DDL provisions, not the migration's correctness.\n */\nconst DEFAULT_SLOT_METRIC: EmbeddingMetric = DEFAULT_EMBEDDING_METRIC;\nconst DEFAULT_SLOT_INDEX_TYPE: EmbeddingIndexType =\n  DEFAULT_EMBEDDING_INDEX_TYPE;\n\n/**\n * The resolved storage config for one `(nodeKind, fieldPath)` slot that the\n * legacy table did not record. The legacy shared table stored only the\n * vector and its dimension count — not the metric or index type — so a\n * caller that wants migrated fields to match a specific graph's `embedding()`\n * declarations supplies this resolver.\n */\nexport type LegacyEmbeddingSlotConfig = Readonly<{\n  metric: EmbeddingMetric;\n  indexType: EmbeddingIndexType;\n}>;\n\n/**\n * Options for {@link migrateLegacyEmbeddings}.\n */\nexport type MigrateLegacyEmbeddingsOptions = Readonly<{\n  /**\n   * The backend to migrate, wired with the destination `VectorStrategy`\n   * (i.e. the post-cutover backend). Its `vectorStrategy` owns the per-field\n   * storage rows are written into and its `upsertEmbedding` performs the\n   * writes.\n   */\n  backend: GraphBackend;\n\n  /**\n   * Restrict the migration to a single graph. When omitted, every graph's\n   * rows in the legacy table are migrated (the table is graph-scoped by its\n   * `graph_id` column).\n   */\n  graphId?: string;\n\n  /**\n   * Resolves the metric / index type for a `(nodeKind, fieldPath)` slot the\n   * legacy table didn't persist. Return `undefined` to fall back to the\n   * cosine / hnsw defaults. Supply this (typically reading the graph's\n   * `embedding()` declarations) when migrated fields must match a specific\n   * metric — e.g. an `l2` field, which scores incorrectly under the cosine\n   * default.\n   */\n  resolveSlotConfig?: (\n    nodeKind: string,\n    fieldPath: string,\n  ) => LegacyEmbeddingSlotConfig | undefined;\n\n  /** Rows read per round-trip. Defaults to {@link DEFAULT_BATCH_SIZE}. */\n  batchSize?: number;\n\n  /**\n   * Physical name of the legacy table to drain. Defaults to\n   * {@link LEGACY_EMBEDDINGS_TABLE_NAME}. Override only for a non-default\n   * deployment that renamed the embeddings table.\n   */\n  legacyTableName?: string;\n}>;\n\n/**\n * Summary of a {@link migrateLegacyEmbeddings} run.\n */\nexport type MigrateLegacyEmbeddingsResult = Readonly<{\n  /** Total embedding rows re-inserted into per-field storage. */\n  migrated: number;\n  /**\n   * Per-`(nodeKind, fieldPath)` counts, keyed `\"<nodeKind>.<fieldPath>\"`\n   * (the strategy's logical-slot key form). Empty when the legacy table was\n   * absent or held no rows for the requested scope.\n   */\n  perField: Readonly<Record<string, number>>;\n  /**\n   * Rows skipped because their vector length didn't match the per-field\n   * table's fixed dimension. The legacy shared column allowed mixed\n   * dimensions for one `(nodeKind, fieldPath)` (e.g. an unmigrated model\n   * change); the first migrated row fixes the typed table's dimension and\n   * any differently-sized rows for that slot are skipped rather than aborting\n   * the whole migration. Keyed `\"<nodeKind>.<fieldPath>\"`. Non-empty here\n   * means those fields need a deliberate re-embed at a single dimension.\n   */\n  skippedDimensionMismatch: Readonly<Record<string, number>>;\n  /**\n   * Rows skipped because their legacy embedding could not be decoded into a\n   * finite-number array — a corrupt value (e.g. a pgvector `vector` column\n   * permits `NaN`/`Infinity`, which is not valid JSON). Keyed\n   * `\"<nodeKind>.<fieldPath>\"`. Skipping + reporting keeps one bad row from\n   * aborting the whole migration; non-empty here means those rows need manual\n   * repair.\n   */\n  skippedDecodeError: Readonly<Record<string, number>>;\n  /**\n   * Whether the legacy table existed. `false` means the run was a clean\n   * no-op (fresh install, or already-dropped table on a re-run).\n   */\n  legacyTablePresent: boolean;\n}>;\n\n/**\n * A single legacy embedding row, with the engine-native vector already\n * decoded to a JSON array string by the dialect-specific SELECT. The\n * legacy `dimensions` column is intentionally not read: the decoded array's\n * length is the authoritative fixed dimension for the destination slot, and\n * relying on it sidesteps the per-driver string/number coercion the legacy\n * integer column would otherwise need.\n */\ntype LegacyEmbeddingRow = Readonly<{\n  graph_id: string;\n  node_kind: string;\n  node_id: string;\n  field_path: string;\n  /** JSON array text, e.g. `\"[0.1,0.2,0.3]\"` — decoded per dialect. */\n  embedding_json: string;\n}>;\n\n/**\n * Re-inserts every embedding from the legacy shared\n * `typegraph_node_embeddings` table into the active\n * `backend.vectorStrategy`'s per-`(nodeKind, fieldPath)` storage.\n *\n * One-time, explicitly-run upgrade step for the shared-table → per-field\n * cutover (#157). Idempotent, batched, and a clean no-op when the legacy\n * table is absent. See the module doc comment for the full contract.\n *\n * @throws Error when the backend exposes no `vectorStrategy` /\n *         `upsertEmbedding` (nothing to migrate *into*) — a configuration\n *         error the caller must fix by wiring the destination strategy\n *         before migrating.\n */\nexport async function migrateLegacyEmbeddings(\n  options: MigrateLegacyEmbeddingsOptions,\n): Promise<MigrateLegacyEmbeddingsResult> {\n  const {\n    backend,\n    graphId,\n    resolveSlotConfig,\n    batchSize = DEFAULT_BATCH_SIZE,\n    legacyTableName = LEGACY_EMBEDDINGS_TABLE_NAME,\n  } = options;\n\n  if (\n    backend.vectorStrategy === undefined ||\n    backend.upsertEmbedding === undefined\n  ) {\n    throw new Error(\n      \"migrateLegacyEmbeddings requires a backend wired with a vectorStrategy \" +\n        \"(the destination per-field storage). Pass the post-cutover backend.\",\n    );\n  }\n  if (!Number.isInteger(batchSize) || batchSize <= 0) {\n    throw new RangeError(\n      `batchSize must be a positive integer, got: ${batchSize}`,\n    );\n  }\n  const upsertEmbedding = backend.upsertEmbedding;\n  const ensureVectorSlotContribution = backend.ensureVectorSlotContribution;\n\n  const perField: Record<string, number> = {};\n  const skippedDimensionMismatch: Record<string, number> = {};\n  const skippedDecodeError: Record<string, number> = {};\n  // (kind, field) slots whose per-field table + durable marker this run has\n  // already provisioned, mapped to the dimension the table was fixed at.\n  // `upsertEmbedding` asserts the marker (#135) and no longer self-creates\n  // the table, so this offline migration (privileged) provisions each slot\n  // once — at the first row's dimension, which fixes the typed table just as\n  // the original lazy write did. Differently-sized later rows for the same\n  // slot are detected against this map and skipped BEFORE the upsert: the\n  // marker assert would otherwise read the differently-dimensioned slot as\n  // stale and abort the whole migration, and the ensure is deliberately not\n  // re-run per row (that would trip the marker drift-guard).\n  const ensuredSlots = new Map<string, number>();\n  let migrated = 0;\n\n  let cursor: LegacyRowCursor | undefined;\n  for (;;) {\n    let batch: readonly LegacyEmbeddingRow[];\n    try {\n      batch = await readLegacyBatch(backend, {\n        legacyTableName,\n        graphId,\n        batchSize,\n        after: cursor,\n      });\n    } catch (error) {\n      // A missing legacy table is the expected \"nothing to migrate\" path on\n      // the first read — surface it as a clean no-op, not a failure.\n      if (cursor === undefined && isMissingTableError(error)) {\n        return {\n          migrated: 0,\n          perField: {},\n          skippedDimensionMismatch: {},\n          skippedDecodeError: {},\n          legacyTablePresent: false,\n        };\n      }\n      throw error;\n    }\n\n    if (batch.length === 0) break;\n\n    for (const row of batch) {\n      const slotKey = `${row.node_kind}.${row.field_path}`;\n\n      let embedding: readonly number[];\n      try {\n        embedding = decodeEmbeddingJson(row);\n      } catch {\n        // A corrupt legacy value (e.g. a pgvector `vector` column permits\n        // NaN/Infinity, which is not valid JSON) is skipped + reported rather\n        // than aborting the whole migration on one bad row.\n        skippedDecodeError[slotKey] = (skippedDecodeError[slotKey] ?? 0) + 1;\n        continue;\n      }\n      const config = resolveSlotConfig?.(row.node_kind, row.field_path);\n      // The decoded length is the authoritative fixed dimension — the\n      // strategy provisions its column type (e.g. `F32_BLOB(N)`) from it.\n      const slot = {\n        graphId: row.graph_id,\n        nodeKind: row.node_kind,\n        fieldPath: row.field_path,\n        dimensions: embedding.length,\n        metric: config?.metric ?? DEFAULT_SLOT_METRIC,\n        indexType: config?.indexType ?? DEFAULT_SLOT_INDEX_TYPE,\n      };\n\n      // Provision the per-field table + durable marker before the first\n      // write into this slot. Once per (graph, kind, field): the first row's\n      // dimension fixes the table. Keyed by graph id too — the legacy table\n      // is graph-scoped, so the same `kind.field` can recur across graphs.\n      const ensuredKey = JSON.stringify([\n        row.graph_id,\n        row.node_kind,\n        row.field_path,\n      ]);\n      if (\n        ensureVectorSlotContribution !== undefined &&\n        !ensuredSlots.has(ensuredKey)\n      ) {\n        await ensureVectorSlotContribution(slot);\n        ensuredSlots.set(ensuredKey, slot.dimensions);\n      }\n\n      // The legacy shared column allowed mixed dimensions for one\n      // (nodeKind, fieldPath); the per-field table is fixed at the first\n      // migrated row's dimension. Skip a differently-sized row up front —\n      // its slot would fail the marker assert as stale (different\n      // signature), aborting the migration instead of skipping the row.\n      const provisionedDimensions = ensuredSlots.get(ensuredKey);\n      if (\n        provisionedDimensions !== undefined &&\n        provisionedDimensions !== embedding.length\n      ) {\n        skippedDimensionMismatch[slotKey] =\n          (skippedDimensionMismatch[slotKey] ?? 0) + 1;\n        continue;\n      }\n\n      try {\n        await upsertEmbedding({ ...slot, nodeId: row.node_id, embedding });\n      } catch (error) {\n        // The legacy shared column allowed mixed dimensions for one\n        // (nodeKind, fieldPath); the per-field table is fixed at the first\n        // migrated row's dimension, so a differently-sized row is skipped and\n        // reported rather than aborting the whole migration.\n        if (error instanceof EmbeddingDimensionChangedError) {\n          skippedDimensionMismatch[slotKey] =\n            (skippedDimensionMismatch[slotKey] ?? 0) + 1;\n          continue;\n        }\n        throw error;\n      }\n\n      migrated += 1;\n      perField[slotKey] = (perField[slotKey] ?? 0) + 1;\n    }\n\n    if (batch.length < batchSize) break;\n    const last = requireDefined(batch.at(-1));\n    cursor = {\n      graphId: last.graph_id,\n      nodeKind: last.node_kind,\n      nodeId: last.node_id,\n      fieldPath: last.field_path,\n    };\n  }\n\n  return {\n    migrated,\n    perField,\n    skippedDimensionMismatch,\n    skippedDecodeError,\n    legacyTablePresent: true,\n  };\n}\n\n/**\n * Composite keyset cursor over the legacy table's primary key\n * `(graph_id, node_kind, node_id, field_path)`. Stable under concurrent\n * writes and immune to OFFSET drift, so a batched walk reads every row once.\n */\ntype LegacyRowCursor = Readonly<{\n  graphId: string;\n  nodeKind: string;\n  nodeId: string;\n  fieldPath: string;\n}>;\n\ntype ReadLegacyBatchParams = Readonly<{\n  legacyTableName: string;\n  graphId: string | undefined;\n  batchSize: number;\n  after: LegacyRowCursor | undefined;\n}>;\n\n/**\n * Reads one keyset-paginated batch of legacy rows, ordered by the primary\n * key, with the engine-native embedding column decoded to a JSON array\n * string by the dialect.\n */\nasync function readLegacyBatch(\n  backend: GraphBackend,\n  params: ReadLegacyBatchParams,\n): Promise<readonly LegacyEmbeddingRow[]> {\n  const table = sql.identifier(params.legacyTableName);\n  const embeddingJson = legacyEmbeddingDecodeExpression(backend);\n\n  const conditions: SqlFragment[] = [];\n  if (params.graphId !== undefined) {\n    conditions.push(sql`\"graph_id\" = ${params.graphId}`);\n  }\n  if (params.after !== undefined) {\n    conditions.push(keysetAfterCondition(params.after));\n  }\n\n  const whereClause =\n    conditions.length === 0 ?\n      sql``\n    : sql` WHERE ${sql.join(conditions, sql` AND `)}`;\n\n  const query = sql`\n    SELECT\n      \"graph_id\" AS graph_id,\n      \"node_kind\" AS node_kind,\n      \"node_id\" AS node_id,\n      \"field_path\" AS field_path,\n      ${embeddingJson} AS embedding_json\n    FROM ${table}${whereClause}\n    ORDER BY \"graph_id\" ASC, \"node_kind\" ASC, \"node_id\" ASC, \"field_path\" ASC\n    LIMIT ${params.batchSize}\n  `;\n\n  return backend.execute<LegacyEmbeddingRow>(asCompiledRowsSql(query));\n}\n\n/**\n * The strict `>` comparison over the composite primary key, expressed as\n * the standard lexicographic OR-chain so it works on every dialect (SQLite\n * supports row-value comparison, but Postgres + SQLite both accept this\n * portable form).\n */\nfunction keysetAfterCondition(after: LegacyRowCursor): SqlFragment {\n  return sql`\n    (\n        \"graph_id\" > ${after.graphId}\n        OR (\"graph_id\" = ${after.graphId} AND \"node_kind\" > ${after.nodeKind})\n        OR (\"graph_id\" = ${after.graphId} AND \"node_kind\" = ${after.nodeKind} AND \"node_id\" > ${after.nodeId})\n        OR (\n          \"graph_id\" = ${after.graphId}\n          AND \"node_kind\" = ${after.nodeKind}\n          AND \"node_id\" = ${after.nodeId}\n          AND \"field_path\" > ${after.fieldPath}\n        )\n      )\n  `;\n}\n\n/**\n * The SQL expression that decodes the legacy engine-native embedding column\n * into a JSON array string `embedding_json`. The single dialect branch in\n * this whole module: the legacy storage formats are genuinely engine-\n * specific, and there is no longer a strategy abstraction over the *legacy*\n * table to delegate to.\n */\nfunction legacyEmbeddingDecodeExpression(backend: GraphBackend): SqlFragment {\n  switch (backend.dialect) {\n    case \"sqlite\": {\n      // Legacy SQLite embeddings were written via `vec_f32('[…]')`\n      // (sqlite-vec binary). `vec_to_json` is its inverse, yielding the\n      // JSON array text. Requires sqlite-vec on the connection — which the\n      // legacy write path also required, so any deployment with legacy rows\n      // has it loaded.\n      return sql`vec_to_json(\"embedding\")`;\n    }\n    case \"postgres\": {\n      // pgvector's native `vector` casts to its `[…]` text literal, which is\n      // valid JSON for `JSON.parse`.\n      return sql`\"embedding\"::text`;\n    }\n    default: {\n      const _exhaustive: never = backend.dialect;\n      throw new Error(\n        `migrateLegacyEmbeddings does not support dialect: ${String(_exhaustive)}`,\n      );\n    }\n  }\n}\n\n/**\n * Parses a decoded `embedding_json` array, asserting it is a non-empty array\n * of finite numbers. A bad decode (wrong type, NaN) names the offending row\n * loudly instead of writing a corrupt vector into per-field storage.\n */\nfunction decodeEmbeddingJson(row: LegacyEmbeddingRow): readonly number[] {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(row.embedding_json) as unknown;\n  } catch (error) {\n    throw new Error(\n      `Failed to decode legacy embedding for ${row.node_kind}.${row.field_path} ` +\n        `(graph ${row.graph_id}, node ${row.node_id}): not valid JSON.`,\n      { cause: error },\n    );\n  }\n  if (!Array.isArray(parsed) || parsed.length === 0) {\n    throw new Error(\n      `Legacy embedding for ${row.node_kind}.${row.field_path} ` +\n        `(graph ${row.graph_id}, node ${row.node_id}) decoded to a non-array ` +\n        `or empty value.`,\n    );\n  }\n  for (const [index, value] of parsed.entries()) {\n    if (typeof value !== \"number\" || !Number.isFinite(value)) {\n      throw new TypeError(\n        `Legacy embedding for ${row.node_kind}.${row.field_path} ` +\n          `(graph ${row.graph_id}, node ${row.node_id}) has a non-finite ` +\n          `value at index ${index}: ${String(value)}.`,\n      );\n    }\n  }\n  return parsed as readonly number[];\n}\n"]}

package/dist/index.d.cts

@@ -1,244 +1,70 @@
-import { z } from 'zod';
-import { f as KindAnnotations, N as NodeType, g as EdgeType } from './extension-types-BM2ACfYO.cjs';
-export { A as AnyEdgeType, C as CURRENT_GRAPH_EXTENSION_VERSION, m as Cardinality, n as Collation, D as DeleteBehavior, e as EdgeId, o as EdgeProps, E as EdgeRegistration, p as EdgeTypeWithEndpoints, q as EndpointExistence, c as GraphDefaults, G as GraphExtension, h as GraphExtensionVersion, J as JsonValue, L as LEGACY_GRAPH_EXTENSION_VERSION, d as NodeId, r as NodeProps, b as NodeRegistration, T as TemporalMode, U as UniqueConstraint, s as UniquenessScope, t as asEdgeId, u as asNodeId, v as isEdgeType, w as isEdgeTypeWithEndpoints, x as isNodeType } from './extension-types-BM2ACfYO.cjs';
-import { K as InferenceType, M as MetaEdge, V as VectorStrategy, G as GraphBackend, O as OntologyRelation, L as AggregateExpr, P as FieldRef, T as ComparisonOp, U as AggregateComparisonPredicate, W as TraversalDirection } from './fulltext-strategy-C27vXaeB.cjs';
-export { X as AdoptedTransaction, B as BackendCapabilities, Y as BackendIdentity, Z as BackendLifecycle, _ as BackendMaintenance, $ as BackendTransactions, a0 as CommitSchemaVersionExpected, a1 as CommitSchemaVersionParams, a2 as CompiledRowsSql, a3 as CompiledSelectSql, a4 as CompiledStatementSql, a5 as ContributionMaterializationBackend, a6 as DEFAULT_SQL_SCHEMA, a7 as DeleteFulltextBatchParams, a8 as EdgeEntityReadBackend, a9 as EdgeEntityWriteBackend, d as EdgeIndexConfig, E as EdgeIndexDeclaration, e as EdgeIndexDirection, f as EdgeIndexWhereBuilder, aa as ExternalRecordedReadSource, ab as FilteredApproximateSearch, ac as FilteredApproximateSearchMode, ad as FulltextBatchRow, ae as FulltextCapabilities, af as FulltextOperationBackend, ag as FulltextQueryMode, ah as FulltextSearchParams, ai as FulltextSearchResult, F as FulltextStrategy, aj as GraphAnalyticsCapabilities, ak as GraphEntityReadBackend, al as GraphEntityWriteBackend, am as GraphLifecycleBackend, an as HybridFusionOptions, I as IndexDeclaration, ao as IndexMaterializationBackend, g as IndexOrigin, h as IndexScope, i as IndexWhereExpression, j as IndexWhereFieldBuilder, k as IndexWhereInput, ap as IntentSql, J as JsonPointer, aq as JsonPointerFor, ar as JsonPointerInput, as as JsonPointerSegment, at as JsonPointerSegments, au as JsonPointerSegmentsFor, av as MAX_JSON_POINTER_DEPTH, aw as MetaEdgeProperties, ax as NodeEntityReadBackend, ay as NodeEntityWriteBackend, l as NodeIndexConfig, N as NodeIndexDeclaration, m as NodeIndexWhereBuilder, az as OrderSpec, aA as ParameterRef, aB as QueryExecutionBackend, aC as RawQueryExecutionBackend, aD as RawStatementExecutionBackend, aE as RecordedRelationOptions, aF as RemovalMaterializationBackend, aG as ResolveJsonPointer, aH as ResolveJsonPointerSegments, aI as ResolvedSqlTableNames, aJ as RowProps, aK as SchemaCommitBackend, aL as SchemaReadBackend, H as SchemaVersionRow, aM as SetActiveVersionParams, aN as SortDirection, c as SqlDialect, aO as SqlIntent, aP as SqlSchema, aQ as SqlTableNames, aR as StrategyTableContribution, aS as TableContribution, aT as TransactionBackend, aU as TraversalExpansion, aV as TrustedImportSession, aW as UniqueConstraintBackend, aX as UpsertFulltextBatchParams, aY as VectorCapabilities, aZ as VectorOperationBackend, a_ as VectorSlot, a$ as asCompiledRowsSql, b0 as asCompiledSelectSql, b1 as asCompiledStatementSql, b2 as buildVectorCapabilities, b3 as createSqlSchema, b4 as fts5Strategy, b5 as isMetaEdge, b6 as joinJsonPointers, b7 as jsonPointer, b8 as normalizeJsonPointer, b9 as parseJsonPointer, ba as recordedRelation, bb as rowPropsToJsonText, bc as rowPropsToObject, bd as tsvectorStrategy } from './fulltext-strategy-C27vXaeB.cjs';
-import { E as EmbeddingMetric, a as EmbeddingIndexType, A as AliasMap, b as EdgeAliasMap, R as RecursiveAliasMap, Q as QueryCoordinateState, c as QueryBuilder, d as EmptyRecursiveAliasMap, T as TraversalBuilder } from './store-view-X96Rd00T.cjs';
-export { e as AggregateResult, f as AlgorithmCyclePolicy, g as AnyEdge, h as AnyNode, B as BaseTraversalOptions, i as BatchResults, j as BatchableQuery, C as ConstraintNames, k as CreateEdgeInput, l as CreateNodeInput, D as DEFAULT_SEARCHABLE_LANGUAGE, m as DegreeOptions, n as DynamicEdgeAccessor, o as DynamicEdgeCollection, p as DynamicEdgeType, q as DynamicFieldBuilder, r as DynamicNodeAccessor, s as DynamicNodeCollection, t as DynamicNodeType, u as DynamicSelectableEdge, v as DynamicSelectableNode, w as Edge, x as EdgeAccessor, y as EdgeBatchReads, z as EdgeCollection, F as EdgeFindByEndpointsOptions, G as EdgeGetOrCreateByEndpointsOptions, I as EdgeGetOrCreateByEndpointsResult, J as EdgeIntrospection, K as EdgeTemporalReads, L as EdgeWrites, M as EmbeddingSchema, O as EmbeddingValue, P as EmptyAliasMap, V as EmptyEdgeAliasMap, W as ExecutableAggregateQuery, X as ExecutableQuery, Y as FieldAccessor, Z as FulltextSearchHit, _ as FulltextSearchOptions, $ as GetOrCreateAction, a0 as GraphAlgorithms, a1 as GraphEdgeCollections, a2 as GraphNodeCollections, a3 as HistorySafeBackend, a4 as HistorySafeTransactionBackend, H as HistoryStore, a5 as HistoryStoreOptions, a6 as HistoryTransactionContext, a7 as HistoryWithTransactionUnavailable, a8 as HookContext, a9 as HybridFulltextOptions, aa as HybridSearchHit, ab as HybridSearchOptions, ac as HybridVectorOptions, ad as IfExistsMode, ae as InitialQueryBuilder, af as KindIntrospection, ag as LiveStoreOptions, ah as MaterializeRemovalsEntry, ai as MaterializeRemovalsOptions, aj as MaterializeRemovalsResult, ak as MeasurableHistoryTransactionContext, al as MeasurableTransactionContext, am as NeighborsOptions, an as NoRecordedCoordinate, N as Node, ao as NodeAccessor, ap as NodeAlias, aq as NodeBulkFindByIndexOptions, ar as NodeCollection, as as NodeCurrentReads, at as NodeGetOrCreateByConstraintOptions, au as NodeGetOrCreateByConstraintResult, av as NodeIdentifier, aw as NodeRef, ax as NodeTemporalReads, ay as NodeWrites, az as OntologyIntrospection, aA as OperationHookContext, aB as PaginateOptions, aC as PaginatedResult, aD as PathNode, aE as Predicate, aF as PreparedQuery, aG as PropsAccessor, aH as QueryHookContext, aI as QueryOptions, aJ as ReachableNode, aK as ReachableOptions, aL as RebuildFulltextOptions, aM as RebuildFulltextResult, aN as ReclaimedVectorFieldEntry, aO as RecordedInstant, aP as RecordedReadStore, aQ as RecordedStoreView, aR as RecordedStoreViewEdgeCollection, aS as RecordedStoreViewEdgeCollections, aT as RecordedStoreViewNodeCollection, aU as RecordedStoreViewNodeCollections, aV as RecursiveTraversalOptions, aW as ReembedFunction, aX as ReembedVectorFieldOptions, aY as ReembedVectorFieldResult, aZ as SchemaIntrospection, a_ as ScopedMeasure, a$ as SearchScopeOptions, b0 as SearchableMetadata, b1 as SearchableOptions, b2 as SearchableSchema, b3 as SelectContext, b4 as SelectableEdge, b5 as SelectableNode, b6 as ShortestPathOptions, b7 as ShortestPathResult, b8 as SqlAvailability, S as Store, b9 as StoreHooks, ba as StoreOptions, bb as StoreProjection, bc as StoreRef, bd as StoreSearch, be as StoreView, bf as StoreViewCanReachOptions, bg as StoreViewCoordinate, bh as StoreViewDegreeOptions, bi as StoreViewEdgeCollection, bj as StoreViewEdgeCollections, bk as StoreViewGraphAlgorithms, bl as StoreViewNeighborsOptions, bm as StoreViewNodeCollection, bn as StoreViewNodeCollections, bo as StoreViewReachableOptions, bp as StoreViewShortestPathOptions, bq as StoreViewSubgraphOptions, br as StoreViewWeaklyConnectedComponentsOptions, bs as StoreViewWeightedShortestPathOptions, bt as StreamOptions, bu as SubgraphEdgeResult, bv as SubgraphNodeResult, bw as SubgraphOptions, bx as SubgraphResult, by as SubsetEdge, bz as SubsetNode, bA as TemporalAlgorithmOptions, bB as TransactionContext, bC as TransactionOutcome, bD as TransactionReceipt, bE as TraversalDirection, bF as TypedEdgeCollection, bG as TypedRecordedStoreViewEdgeCollection, bH as TypedStoreViewEdgeCollection, bI as UnionableQuery, U as UniqueIntrospection, bJ as UpdateEdgeInput, bK as UpdateNodeInput, bL as VectorSearchHit, bM as VectorSearchOptions, bN as WeaklyConnectedComponentMembership, bO as WeaklyConnectedComponentsOptions, bP as WeightedShortestPathOptions, bQ as WeightedShortestPathResult, bR as asRecordedInstant, bS as createQueryBuilder, bT as createStore, bU as createStoreWithSchema, bV as createVerifiedStore, bW as defineSubgraphProject, bX as embedding, bY as exists, bZ as fieldRef, b_ as getEmbeddingDimensions, b$ as getSearchableMetadata, c0 as inSubquery, c1 as isEmbeddingSchema, c2 as isParameterRef, c3 as isSearchableSchema, c4 as notExists, c5 as notInSubquery, c6 as param, c7 as resolveGraphVectorSlots, c8 as searchable } from './store-view-X96Rd00T.cjs';
-import { G as GraphDef } from './manager-nU1vTJLy.cjs';
-export { A as AllEdgeTypes, v as AllNodeTypes, w as EdgeKinds, x as GetEdgeType, u as GetNodeType, t as NodeKinds, c as SchemaManagerOptions, d as SchemaValidationResult, y as defineGraph, z as getEdgeKinds, B as getNodeKinds, F as isGraphDef } from './manager-nU1vTJLy.cjs';
-export { B as BackendDisposedError, C as CardinalityError, b as CardinalityErrorDetails, c as CompilerInvariantError, d as ConfigurationError, D as DatabaseOperationError, e as DatabaseOperationErrorDetails, f as DisjointError, g as DisjointErrorDetails, E as EagerMaterializationError, h as EagerMaterializationErrorDetails, i as EdgeNotFoundError, j as EdgeNotFoundErrorDetails, k as EmbeddingDimensionChangedError, l as EmbeddingDimensionChangedErrorDetails, m as EndpointError, n as EndpointErrorDetails, o as EndpointNotFoundError, p as EndpointNotFoundErrorDetails, q as ErrorCategory, G as GraphAlgorithmConvergenceError, I as InvalidEdgeWeightError, r as InvalidEdgeWeightErrorDetails, s as InvalidEdgeWeightReason, K as KindNotFoundError, t as KindNotFoundErrorDetails, M as MigrationError, u as MigrationErrorDetails, N as NodeConstraintNotFoundError, v as NodeConstraintNotFoundErrorDetails, w as NodeIndexNotFoundError, x as NodeIndexNotFoundErrorDetails, y as NodeNotFoundError, z as NodeNotFoundErrorDetails, R as RECORDED_CAPTURE_GUARD_CODES, A as RecordedCaptureGuardCode, F as RecordedCaptureGuardError, H as RestrictedDeleteError, J as RestrictedDeleteErrorDetails, S as SchemaContentConflictError, L as SchemaContentConflictErrorDetails, O as SchemaMismatchError, P as SchemaMismatchErrorDetails, Q as StaleVersionError, U as StaleVersionErrorDetails, W as StoreNotInitializedError, X as StoreNotInitializedErrorDetails, Y as StoreNotInitializedReason, Z as TransactionClosedError, _ as TrustedImportError, $ as TrustedImportErrorReason, T as TypeGraphError, a0 as TypeGraphErrorOptions, a1 as UniquenessError, a2 as UniquenessErrorDetails, a3 as UnsupportedBackendCapabilityError, a4 as UnsupportedPredicateError, a as ValidationError, a5 as ValidationErrorDetails, V as ValidationIssue, a6 as VersionConflictError, a7 as VersionConflictErrorDetails, a8 as getErrorSuggestion, a9 as isConstraintError, aa as isRecordedCaptureGuardError, ab as isSystemError, ac as isTypeGraphError, ad as isUserRecoverable } from './index-BPM59vsg.cjs';
-export { a as MaterializeIndexesEntry, b as MaterializeIndexesOptions, M as MaterializeIndexesResult, c as MaterializeSystemIndexesOptions } from './materialize-indexes-CuR3gAZb.cjs';
-export { S as SYSTEM_INDEX_DECLARATIONS, a as SystemIndexDeclaration, b as SystemIndexTable, c as andWhere, d as defineEdgeIndex, e as defineNodeIndex, n as notWhere, o as orWhere } from './where-K3uBP33l.cjs';
+export { DefineEdgeOptions, DefineNodeOptions, ExternalRefSchema, ExternalRefValue, MetaEdgeOptions, createExternalRef, defineEdge, defineNode, externalRef, getExternalRefTable, isExternalRefSchema, metaEdge } from './core/index.cjs';
+import { E as EmbeddingMetric, a as EmbeddingIndexType } from './temporal-BC_NQV5Y.cjs';
+export { D as DEFAULT_SEARCHABLE_LANGUAGE, b as EmbeddingSchema, c as EmbeddingValue, R as RecordedInstant, S as SearchableMetadata, d as SearchableOptions, e as SearchableSchema, f as asRecordedInstant, g as embedding, h as getEmbeddingDimensions, i as getSearchableMetadata, j as isEmbeddingSchema, k as isSearchableSchema, r as resolveGraphVectorSlots, s as searchable } from './temporal-BC_NQV5Y.cjs';
+import { G as GraphDef } from './define-graph-CzEvA_8F.cjs';
+export { A as AllEdgeTypes, a as AllNodeTypes, E as EdgeKinds, b as GetEdgeType, c as GetNodeType, N as NodeKinds, d as defineGraph, g as getEdgeKinds, e as getNodeKinds, i as isGraphDef } from './define-graph-CzEvA_8F.cjs';
+import { a as NodeType, d as EdgeType } from './extension-types-BLEVH4SG.cjs';
+export { A as AnyEdgeType, C as CURRENT_GRAPH_EXTENSION_VERSION, e as Cardinality, f as Collation, D as DeleteBehavior, g as EdgeId, h as EdgeProps, E as EdgeRegistration, i as EdgeTypeWithEndpoints, j as EndpointExistence, b as GraphDefaults, G as GraphExtension, k as GraphExtensionVersion, J as JsonValue, l as KindAnnotations, L as LEGACY_GRAPH_EXTENSION_VERSION, m as NodeId, n as NodeProps, N as NodeRegistration, T as TemporalMode, U as UniqueConstraint, o as UniquenessScope, p as asEdgeId, q as asNodeId, r as isEdgeType, s as isEdgeTypeWithEndpoints, t as isNodeType } from './extension-types-BLEVH4SG.cjs';
+import { V as VectorStrategy, G as GraphBackend, O as OntologyRelation, D as InferenceType, H as AggregateExpr, K as FieldRef, L as ComparisonOp, M as AggregateComparisonPredicate, T as TraversalDirection } from './index-CrFL_ENI.cjs';
+export { A as AdapterBackend, P as AdapterBackendTransactions, B as BackendCapabilities, U as BackendIdentity, W as BackendLifecycle, X as BackendMaintenance, Y as BackendTransactions, Z as CommitSchemaVersionExpected, _ as CommitSchemaVersionParams, $ as CompiledRowsSql, a0 as CompiledSelectSql, a1 as CompiledStatementSql, a2 as ContributionMaterializationBackend, a3 as DEFAULT_SQL_SCHEMA, a4 as DeleteFulltextBatchParams, a5 as EdgeEntityReadBackend, a6 as EdgeEntityWriteBackend, a as EdgeIndexConfig, E as EdgeIndexDeclaration, b as EdgeIndexDirection, c as EdgeIndexWhereBuilder, a7 as ExternalRecordedReadSource, a8 as FilteredApproximateSearch, a9 as FilteredApproximateSearchMode, aa as FulltextBatchRow, ab as FulltextCapabilities, ac as FulltextOperationBackend, ad as FulltextQueryMode, ae as FulltextSearchParams, af as FulltextSearchResult, F as FulltextStrategy, ag as GraphAnalyticsCapabilities, ah as GraphEntityReadBackend, ai as GraphEntityWriteBackend, aj as GraphLifecycleBackend, ak as HybridFusionOptions, I as IndexDeclaration, al as IndexMaterializationBackend, d as IndexOrigin, e as IndexScope, f as IndexWhereExpression, g as IndexWhereFieldBuilder, h as IndexWhereInput, am as IntentSql, J as JsonPointer, an as JsonPointerFor, ao as JsonPointerInput, ap as JsonPointerSegment, aq as JsonPointerSegments, ar as JsonPointerSegmentsFor, as as MAX_JSON_POINTER_DEPTH, at as MetaEdge, au as MetaEdgeProperties, av as NodeEntityReadBackend, aw as NodeEntityWriteBackend, i as NodeIndexConfig, N as NodeIndexDeclaration, j as NodeIndexWhereBuilder, ax as OrderSpec, ay as ParameterRef, az as Placeholder, aA as QueryExecutionBackend, aB as RawQueryExecutionBackend, aC as RawStatementExecutionBackend, aD as RecordedRelationOptions, aE as RemovalMaterializationBackend, aF as RenderedSql, aG as ResolveJsonPointer, aH as ResolveJsonPointerSegments, aI as ResolvedSqlTableNames, aJ as RowProps, aK as SchemaCommitBackend, aL as SchemaReadBackend, C as SchemaVersionRow, aM as SetActiveVersionParams, aN as SortDirection, aO as SqlChunk, S as SqlDialect, aP as SqlFragment, aQ as SqlIdentifierChunk, aR as SqlIntent, aS as SqlParameterChunk, aT as SqlPlaceholderChunk, aU as SqlSchema, aV as SqlTableNames, aW as SqlTag, aX as SqlTextChunk, aY as StrategyTableContribution, aZ as TableContribution, a_ as TransactionBackend, a$ as TransactionOptions, b0 as TransactionReadBackend, b1 as TraversalExpansion, b2 as TrustedImportSession, b3 as UniqueConstraintBackend, b4 as UpsertFulltextBatchParams, b5 as VectorCapabilities, b6 as VectorOperationBackend, p as VectorSlot, b7 as buildVectorCapabilities, b8 as createSqlSchema, b9 as fts5Strategy, ba as isMetaEdge, bb as isSqlFragment, bc as joinJsonPointers, bd as jsonPointer, be as normalizeJsonPointer, bf as parseJsonPointer, bg as recordedRelation, bh as renderPostgres, bi as renderSql, bj as renderSqlInline, bk as renderSqlite, bl as rowPropsToJsonText, bm as rowPropsToObject, bn as sql, bo as tsvectorStrategy } from './index-CrFL_ENI.cjs';
+export { B as BackendDisposedError, C as CardinalityError, b as CardinalityErrorDetails, c as CompilerInvariantError, d as ConfigurationError, D as DatabaseOperationError, e as DatabaseOperationErrorDetails, f as DisjointError, g as DisjointErrorDetails, E as EagerMaterializationError, h as EagerMaterializationErrorDetails, i as EdgeNotFoundError, j as EdgeNotFoundErrorDetails, k as EmbeddingDimensionChangedError, l as EmbeddingDimensionChangedErrorDetails, m as EndpointError, n as EndpointErrorDetails, o as EndpointNotFoundError, p as EndpointNotFoundErrorDetails, q as ErrorCategory, G as GraphAlgorithmConvergenceError, I as InvalidEdgeWeightError, r as InvalidEdgeWeightErrorDetails, s as InvalidEdgeWeightReason, K as KindNotFoundError, t as KindNotFoundErrorDetails, M as MigrationError, u as MigrationErrorDetails, N as NodeConstraintNotFoundError, v as NodeConstraintNotFoundErrorDetails, w as NodeIndexNotFoundError, x as NodeIndexNotFoundErrorDetails, y as NodeNotFoundError, z as NodeNotFoundErrorDetails, R as RECORDED_CAPTURE_GUARD_CODES, A as RecordedCaptureGuardCode, F as RecordedCaptureGuardError, H as RestrictedDeleteError, J as RestrictedDeleteErrorDetails, S as SchemaContentConflictError, L as SchemaContentConflictErrorDetails, O as SchemaMismatchError, P as SchemaMismatchErrorDetails, Q as StaleVersionError, T as StaleVersionErrorDetails, U as StoreNotInitializedError, W as StoreNotInitializedErrorDetails, X as StoreNotInitializedReason, Y as TransactionClosedError, Z as TrustedImportError, _ as TrustedImportErrorReason, $ as TypeGraphError, a0 as TypeGraphErrorOptions, a1 as UniquenessError, a2 as UniquenessErrorDetails, a3 as UnsupportedBackendCapabilityError, a4 as UnsupportedPredicateError, a as ValidationError, a5 as ValidationErrorDetails, V as ValidationIssue, a6 as VersionConflictError, a7 as VersionConflictErrorDetails, a8 as getErrorSuggestion, a9 as isConstraintError, aa as isRecordedCaptureGuardError, ab as isSystemError, ac as isTypeGraphError, ad as isUserRecoverable } from './index-BihFPsPu.cjs';
+import { A as AliasMap, E as EdgeAliasMap, d as RecursiveAliasMap, Q as QueryCoordinateState, e as QueryBuilder, f as EmptyRecursiveAliasMap, T as TraversalBuilder } from './store-view-BoHqdHjB.cjs';
+export { g as AdapterHistoryStore, h as AdapterHistoryTransactionContext, i as AdapterRecordedReadStore, j as AdapterStore, k as AdapterTransactionContext, l as AggregateResult, m as AlgorithmCyclePolicy, n as AnyEdge, o as AnyNode, B as BaseStoreOptions, p as BaseTraversalOptions, q as BatchResults, r as BatchableQuery, C as ConstraintNames, s as CreateEdgeInput, t as CreateNodeInput, D as DegreeOptions, u as DynamicEdgeAccessor, v as DynamicEdgeCollection, w as DynamicEdgeType, x as DynamicFieldBuilder, y as DynamicNodeAccessor, z as DynamicNodeCollection, F as DynamicNodeType, G as DynamicSelectableEdge, I as DynamicSelectableNode, J as Edge, K as EdgeAccessor, M as EdgeBatchReads, N as EdgeCollection, O as EdgeFindByEndpointsOptions, P as EdgeGetOrCreateByEndpointsOptions, V as EdgeGetOrCreateByEndpointsResult, W as EdgeIntrospection, X as EdgeTemporalReads, Y as EdgeWrites, Z as EmptyAliasMap, _ as EmptyEdgeAliasMap, $ as ExecutableAggregateQuery, a0 as ExecutableQuery, a1 as FieldAccessor, a2 as FulltextSearchHit, a3 as FulltextSearchOptions, a4 as GetOrCreateAction, a5 as GraphAlgorithms, a6 as GraphEdgeCollections, a7 as GraphNodeCollections, b as HistoryStore, a8 as HistoryStoreBackend, H as HistoryStoreOptions, a9 as HookContext, aa as HybridFulltextOptions, ab as HybridSearchHit, ac as HybridSearchOptions, ad as HybridVectorOptions, ae as IfExistsMode, af as InitialQueryBuilder, ag as KindIntrospection, ah as LabelPropagationMembership, ai as LabelPropagationOptions, L as LiveStoreOptions, aj as MaterializeRemovalsEntry, ak as MaterializeRemovalsOptions, al as MaterializeRemovalsResult, am as MeasurableAdapterHistoryTransactionContext, an as MeasurableAdapterTransactionContext, ao as MeasurableTransactionContext, ap as NeighborsOptions, aq as NoRecordedCoordinate, ar as Node, as as NodeAccessor, at as NodeAlias, au as NodeBulkFindByIndexOptions, av as NodeCollection, aw as NodeCurrentReads, ax as NodeGetOrCreateByConstraintOptions, ay as NodeGetOrCreateByConstraintResult, az as NodeIdentifier, aA as NodeRef, aB as NodeTemporalReads, aC as NodeWrites, aD as OntologyIntrospection, aE as OperationHookContext, aF as PageRankOptions, aG as PageRankScore, aH as PaginateOptions, aI as PaginatedResult, aJ as PathNode, aK as PersonalizedPageRankOptions, aL as PersonalizedPageRankSeed, aM as Predicate, aN as PreparedQuery, aO as PropsAccessor, aP as QueryHookContext, aQ as QueryOptions, aR as ReachableNode, aS as ReachableOptions, aT as RebuildFulltextOptions, aU as RebuildFulltextResult, aV as ReclaimedVectorFieldEntry, c as RecordedReadStore, R as RecordedReadStoreOptions, aW as RecordedStoreView, aX as RecordedStoreViewEdgeCollection, aY as RecordedStoreViewEdgeCollections, aZ as RecordedStoreViewNodeCollection, a_ as RecordedStoreViewNodeCollections, a$ as RecursiveTraversalOptions, b0 as ReembedFunction, b1 as ReembedVectorFieldOptions, b2 as ReembedVectorFieldResult, b3 as SchemaIntrospection, b4 as ScopedMeasure, b5 as SearchScopeOptions, b6 as SelectContext, b7 as SelectableEdge, b8 as SelectableNode, b9 as ShortestPathOptions, ba as ShortestPathResult, bb as SqlAvailability, a as Store, bc as StoreHooks, S as StoreOptions, bd as StoreProjection, be as StoreRef, bf as StoreSearch, bg as StoreView, bh as StoreViewCanReachOptions, bi as StoreViewCoordinate, bj as StoreViewDegreeOptions, bk as StoreViewEdgeCollection, bl as StoreViewEdgeCollections, bm as StoreViewGraphAlgorithms, bn as StoreViewLabelPropagationOptions, bo as StoreViewNeighborsOptions, bp as StoreViewNodeCollection, bq as StoreViewNodeCollections, br as StoreViewPageRankOptions, bs as StoreViewPersonalizedPageRankOptions, bt as StoreViewReachableOptions, bu as StoreViewShortestPathOptions, bv as StoreViewSubgraphOptions, bw as StoreViewWeaklyConnectedComponentsOptions, bx as StoreViewWeightedShortestPathOptions, by as StreamOptions, bz as SubgraphEdgeResult, bA as SubgraphNodeResult, bB as SubgraphOptions, bC as SubgraphResult, bD as SubsetEdge, bE as SubsetNode, bF as TemporalAlgorithmOptions, bG as TransactionContext, bH as TransactionOutcome, bI as TransactionReceipt, bJ as TraversalDirection, bK as TypedEdgeCollection, bL as TypedRecordedStoreViewEdgeCollection, bM as TypedStoreViewEdgeCollection, U as UnboundLiveStoreOptions, bN as UnionableQuery, bO as UniqueIntrospection, bP as UpdateEdgeInput, bQ as UpdateNodeInput, bR as VectorSearchHit, bS as VectorSearchOptions, bT as WeaklyConnectedComponentMembership, bU as WeaklyConnectedComponentsOptions, bV as WeightedShortestPathOptions, bW as WeightedShortestPathResult, bX as createAdapterStore, bY as createAdapterStoreWithSchema, bZ as createQueryBuilder, b_ as createStore, b$ as createStoreWithSchema, c0 as createVerifiedAdapterStore, c1 as createVerifiedStore, c2 as defineSubgraphProject, c3 as exists, c4 as fieldRef, c5 as inSubquery, c6 as isParameterRef, c7 as notExists, c8 as notInSubquery, c9 as param } from './store-view-BoHqdHjB.cjs';
+export { a as MaterializeIndexesEntry, b as MaterializeIndexesOptions, M as MaterializeIndexesResult, c as MaterializeSystemIndexesOptions } from './materialize-indexes-ExQ6OrAh.cjs';
+export { S as SYSTEM_INDEX_DECLARATIONS, a as SystemIndexDeclaration, b as SystemIndexTable, c as andWhere, d as defineEdgeIndex, e as defineNodeIndex, n as notWhere, o as orWhere } from './where-C92TXCzT.cjs';
 export { GraphExtensionError, GraphExtensionIssue, GraphExtensionIssueCode, GraphExtensionUnresolvedEndpointError, GraphExtensionValidationError, GraphExtensionVersionUnsupportedError, IncompatibleChange, IncompatibleChangeError, KindCollisionError, KindHasReferentsError, KindReferent, RemoveCompileTimeKindError, defineGraphExtension, validateGraphExtension } from './graph-extension/index.cjs';
-import 'drizzle-orm';
-import 'drizzle-orm/pg-core';
-import 'drizzle-orm/sqlite-core';
+export { S as SchemaManagerOptions, d as SchemaValidationResult } from './manager-nCEJiYBb.cjs';
+import 'zod';
 import './result-DWo6mUVz.cjs';
 
-/**
- * Options for defining a node type.
- */
-type DefineNodeOptions<S extends z.ZodObject<z.ZodRawShape>> = Readonly<{
-    /** Zod schema for node properties */
-    schema: S;
-    /** Optional description for documentation */
-    description?: string;
-    /**
-     * Consumer-owned structured annotations for the kind.
-     *
-     * Stored in the canonical schema and **participates in schema hashing** —
-     * any change bumps the schema version and shows up as a `safe`-severity
-     * diff in `getSchemaChanges`. See `KindAnnotations` for the contract.
-     */
-    annotations?: KindAnnotations;
-}>;
-/**
- * Creates a node type definition.
- *
- * @example
- * ```typescript
- * const Person = defineNode("Person", {
- *   schema: z.object({
- *     fullName: z.string().min(1),
- *     email: z.string().email().optional(),
- *   }),
- *   description: "A person in the system",
- * });
- * ```
- */
-declare function defineNode<K extends string, S extends z.ZodObject<z.ZodRawShape>>(name: K, options: DefineNodeOptions<S>): NodeType<K, S>;
-
-/**
- * Options for defining an edge type.
- */
-type DefineEdgeOptions<S extends z.ZodObject<z.ZodRawShape>, From extends readonly NodeType[] | undefined = undefined, To extends readonly NodeType[] | undefined = undefined> = Readonly<{
-    /** Zod schema for edge properties (defaults to empty object) */
-    schema?: S;
-    /** Optional description for documentation */
-    description?: string;
-    /**
-     * Consumer-owned structured annotations for the kind.
-     *
-     * Stored in the canonical schema and **participates in schema hashing** —
-     * any change bumps the schema version and shows up as a `safe`-severity
-     * diff in `getSchemaChanges`. See `KindAnnotations` for the contract.
-     */
-    annotations?: KindAnnotations;
-    /** Node types that can be the source of this edge (domain constraint) */
-    from?: From;
-    /** Node types that can be the target of this edge (range constraint) */
-    to?: To;
-}>;
-declare const EMPTY_SCHEMA: z.ZodObject<{}, z.core.$strip>;
-type EmptySchema = typeof EMPTY_SCHEMA;
-/**
- * Creates an edge type definition.
- *
- * @example
- * ```typescript
- * // Edge with no properties
- * const hasEpisode = defineEdge("hasEpisode");
- *
- * // Edge with properties
- * const employedAt = defineEdge("employedAt", {
- *   schema: z.object({
- *     isPrimary: z.boolean().default(true),
- *     startedAt: z.date(),
- *   }),
- *   description: "Employment relationship",
- * });
- *
- * // Edge with domain/range constraints (can be used directly in defineGraph)
- * const worksAt = defineEdge("worksAt", {
- *   schema: z.object({ role: z.string() }),
- *   from: [Person],
- *   to: [Company],
- * });
- * ```
- */
-declare function defineEdge<K extends string>(name: K): EdgeType<K, EmptySchema>;
-declare function defineEdge<K extends string, S extends z.ZodObject<z.ZodRawShape>, From extends readonly NodeType[], To extends readonly NodeType[]>(name: K, options: DefineEdgeOptions<S, From, To> & {
-    from: From;
-    to: To;
-}): EdgeType<K, S, From, To>;
-declare function defineEdge<K extends string, S extends z.ZodObject<z.ZodRawShape>>(name: K, options: DefineEdgeOptions<S>): EdgeType<K, S>;
-
-/**
- * Options for creating a meta-edge.
- */
-type MetaEdgeOptions = Readonly<{
-    /** Whether the relationship is transitive (A→B, B→C implies A→C) */
-    transitive?: boolean;
-    /** Whether the relationship is symmetric (A→B implies B→A) */
-    symmetric?: boolean;
-    /** Whether the relationship is reflexive (A→A is always true) */
-    reflexive?: boolean;
-    /** Name of the inverse meta-edge */
-    inverse?: string;
-    /** How this meta-edge affects queries and validation */
-    inference?: InferenceType;
-    /** Optional description */
-    description?: string;
-}>;
-/**
- * Creates a custom meta-edge definition.
- *
- * @example
- * ```typescript
- * // Custom meta-edge for regulatory relationships
- * const regulatedBy = metaEdge("regulatedBy", {
- *   description: "Type X is regulated by authority type Y",
- *   transitive: false,
- *   symmetric: false,
- * });
- * ```
- */
-declare function metaEdge<K extends string>(name: K, options?: MetaEdgeOptions): MetaEdge<K>;
-
-/**
- * External reference type for hybrid overlay patterns.
- *
- * Creates a Zod-compatible schema for referencing entities in external
- * data sources (e.g., existing application tables) from TypeGraph nodes.
- */
-
-/**
- * Symbol key for storing external table name on the schema.
- * This allows the schema introspector to detect external reference types
- * and extract source information.
- */
-declare const EXTERNAL_REF_TABLE_KEY: "_externalRefTable";
-/**
- * The shape of an external reference value.
- * Contains the source table identifier and the ID of the referenced record.
- */
-type ExternalRefValue<T extends string = string> = Readonly<{
-    table: T;
-    id: string;
-}>;
-/**
- * A Zod schema for external references with attached table metadata.
- */
-type ExternalRefSchema<T extends string = string> = z.ZodType<ExternalRefValue<T>> & Readonly<{
-    [EXTERNAL_REF_TABLE_KEY]: T;
-}>;
-/**
- * Creates a Zod schema for referencing external data sources.
- *
- * Use this when building a hybrid overlay where TypeGraph stores
- * graph relationships and metadata while your existing tables
- * remain the source of truth for entity data.
- *
- * @param table - The identifier for the external table/source (e.g., "users", "documents")
- * @returns A Zod schema that validates external reference objects
- *
- * @example
- * ```typescript
- * import { defineNode, externalRef, embedding } from "@nicia-ai/typegraph";
- *
- * // Reference documents from your existing application database
- * const Document = defineNode("Document", {
- *   schema: z.object({
- *     source: externalRef("documents"),
- *     embedding: embedding(1536).optional(),
- *     extractedTopics: z.array(z.string()).optional(),
- *   }),
- * });
- *
- * // Create a node referencing an external document
- * await store.nodes.Document.create({
- *   source: { table: "documents", id: "doc_abc123" },
- *   embedding: await generateEmbedding(docContent),
- * });
- *
- * // Query and hydrate with external data
- * const results = await store
- *   .query()
- *   .from("Document", "d")
- *   .whereNode("d", (d) => d.embedding.similarTo(query, 10))
- *   .select((ctx) => ctx.d.source)
- *   .execute();
- *
- * // Fetch full data from your app database
- * const externalIds = results.map((r) => r.id);
- * const fullDocs = await appDb.query.documents.findMany({
- *   where: inArray(documents.id, externalIds),
- * });
- * ```
- */
-declare function externalRef<T extends string>(table: T): ExternalRefSchema<T>;
-/**
- * Checks if a value is an external reference schema.
- */
-declare function isExternalRefSchema(value: unknown): value is ExternalRefSchema;
-/**
- * Gets the table name from an external reference schema.
- * Returns undefined if the schema is not an external reference schema.
- */
-declare function getExternalRefTable(schema: z.ZodType): string | undefined;
-/**
- * Helper function to create a typed external reference value.
- * Useful when you want to avoid repeating the table name.
- *
- * @example
- * ```typescript
- * const docRef = createExternalRef("documents");
- *
- * await store.nodes.Document.create({
- *   source: docRef("doc_123"),
- *   embedding: [...],
- * });
- * ```
- */
-declare function createExternalRef<T extends string>(table: T): (id: string) => ExternalRefValue<T>;
-
 declare const libsqlVectorStrategy: VectorStrategy;
 
 declare const pgvectorStrategy: VectorStrategy;
 
 declare const sqliteVecStrategy: VectorStrategy;
 
+/**
+ * One-time offline migration: legacy shared embeddings table → per-field
+ * strategy storage.
+ *
+ * ## What this is for
+ *
+ * The cross-backend vector cutover (#157) dropped the single shared
+ * `typegraph_node_embeddings` table. Each
+ * `VectorStrategy` now OWNS one typed, fixed-dimension structure per
+ * `(nodeKind, fieldPath)` — the only layout that can be ANN-indexed on
+ * libSQL and sqlite-vec, not just pgvector.
+ *
+ * Deployments that wrote embeddings under the old shared table before
+ * upgrading still hold those rows. This utility drains them into the new
+ * per-field storage **once**, during the upgrade, so existing embedded
+ * data survives the cutover without re-embedding from source.
+ *
+ * It is an explicitly-run, offline step — not wired into `materializeIndexes`
+ * or any boot path. Run it once after deploying the new version and before
+ * (or alongside) the first `materializeIndexes()`, then drop the legacy
+ * table at your leisure.
+ *
+ * ## How it works
+ *
+ * - Skips cleanly (returns a zero summary) when the legacy table is absent —
+ *   a fresh install, or a re-run after the table was dropped.
+ * - Reads rows in keyset-paginated batches (never the whole table at once),
+ *   decoding the engine-native embedding column to a numeric array at the SQL
+ *   level: sqlite-vec stored a `vec_f32` blob (`vec_to_json` decodes it);
+ *   pgvector stored a native `vector` (`::text` yields a `[…]` literal).
+ * - Re-inserts each row through `backend.upsertEmbedding`, which routes the
+ *   active strategy's `buildUpsert` and idempotently provisions the per-field
+ *   storage (the same `(nodeKind, fieldPath)` slot a fresh store write uses).
+ *   The migration stays graph-agnostic and execution-correct on both the
+ *   sync (better-sqlite3) and async (libsql / Postgres) backends — it does
+ *   not re-implement the backend's statement-execution glue.
+ *
+ * Idempotent and resumable: a partial run followed by a full run converges
+ * to the same per-field tables, because every write is an upsert keyed by
+ * `(graph_id, node_id)` in the strategy's owned storage.
+ */
+
 /**
  * The resolved storage config for one `(nodeKind, fieldPath)` slot that the
  * legacy table did not record. The legacy shared table stored only the
@@ -577,13 +403,6 @@ declare function invertClosure(closure: ReadonlyMap<string, ReadonlySet<string>>
  */
 declare function isReachable(closure: ReadonlyMap<string, ReadonlySet<string>>, source: string, target: string): boolean;
 
-/**
- * Recursive CTE Compilation
- *
- * Compiles variable-length path traversals using WITH RECURSIVE.
- * Handles cycle detection and depth limiting using dialect-specific operations.
- */
-
 /**
  * Maximum depth for recursive CTE queries when maxDepth is unlimited (-1).
  *
@@ -888,4 +707,4 @@ type IdConfig = Readonly<{
     edgeIdGenerator: IdGenerator;
 }>;
 
-export { AliasMap, type DefineEdgeOptions, type DefineNodeOptions, EdgeType, EmptyRecursiveAliasMap, type ExternalRefSchema, type ExternalRefValue, FieldRef, type FlexibleQueryFragment, GraphBackend, GraphDef, type IdConfig, type IdGenerator, InferenceType, KindAnnotations, type LegacyEmbeddingSlotConfig, MAX_EXPLICIT_RECURSIVE_DEPTH, MAX_RECURSIVE_DEPTH, MetaEdge, type MetaEdgeOptions, type MigrateLegacyEmbeddingsOptions, type MigrateLegacyEmbeddingsResult, NodeType, OntologyRelation, QueryBuilder, QueryCoordinateState, type QueryFragment, type TraversalFragment, VectorStrategy, avg, broader, composeFragments, computeTransitiveClosure, core, count, countDistinct, countDistinctEdges, countEdges, createExternalRef, createFragment, defineEdge, defineNode, differentFrom, disjointWith, equivalentTo, externalRef, field, generateId, getExternalRefTable, hasPart, having, havingEq, havingGt, havingGte, havingLt, havingLte, implies, inverseOf, invertClosure, isExternalRefSchema, isReachable, libsqlVectorStrategy, limitFragment, max, metaEdge, migrateLegacyEmbeddings, min, narrower, offsetFragment, orderByFragment, partOf, pgvectorStrategy, relatedTo, sameAs, sqliteVecStrategy, subClassOf, sum };
+export { AliasMap, EdgeType, EmptyRecursiveAliasMap, FieldRef, type FlexibleQueryFragment, GraphBackend, GraphDef, type IdConfig, type IdGenerator, InferenceType, type LegacyEmbeddingSlotConfig, MAX_EXPLICIT_RECURSIVE_DEPTH, MAX_RECURSIVE_DEPTH, type MigrateLegacyEmbeddingsOptions, type MigrateLegacyEmbeddingsResult, NodeType, OntologyRelation, QueryBuilder, QueryCoordinateState, type QueryFragment, type TraversalFragment, VectorStrategy, avg, broader, composeFragments, computeTransitiveClosure, core, count, countDistinct, countDistinctEdges, countEdges, createFragment, differentFrom, disjointWith, equivalentTo, field, generateId, hasPart, having, havingEq, havingGt, havingGte, havingLt, havingLte, implies, inverseOf, invertClosure, isReachable, libsqlVectorStrategy, limitFragment, max, migrateLegacyEmbeddings, min, narrower, offsetFragment, orderByFragment, partOf, pgvectorStrategy, relatedTo, sameAs, sqliteVecStrategy, subClassOf, sum };