@nicia-ai/typegraph 0.32.0 → 0.34.0

package/dist/chunk-JJRCLAUN.cjs

@@ -0,0 +1,155 @@
+'use strict';
+
+var chunkJIEJCTDS_cjs = require('./chunk-JIEJCTDS.cjs');
+
+// src/backend/drizzle/row-mappers.ts
+function requireTimestamp(value, field) {
+  if (value === void 0) {
+    throw new chunkJIEJCTDS_cjs.DatabaseOperationError(
+      `Expected non-null ${field} timestamp`,
+      { operation: "select", entity: "row" }
+    );
+  }
+  return value;
+}
+function asString(value, field) {
+  if (typeof value !== "string") {
+    throw new chunkJIEJCTDS_cjs.DatabaseOperationError(
+      `Expected ${field} to be string, got ${typeof value}`,
+      { operation: "select", entity: "row" }
+    );
+  }
+  return value;
+}
+function asNumber(value, field) {
+  if (typeof value !== "number") {
+    throw new chunkJIEJCTDS_cjs.DatabaseOperationError(
+      `Expected ${field} to be number, got ${typeof value}`,
+      { operation: "select", entity: "row" }
+    );
+  }
+  return value;
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function nullToUndefined(value) {
+  return value ?? void 0;
+}
+function formatPostgresTimestamp(value) {
+  if (value === null || value === void 0) return void 0;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string") {
+    if (value.includes("T")) return value;
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime())) return date.toISOString();
+    return value;
+  }
+  return void 0;
+}
+function coerceNumericScore(value) {
+  if (typeof value === "number") return value;
+  const parsed = Number.parseFloat(value);
+  if (Number.isNaN(parsed)) {
+    throw new TypeError(
+      `Backend returned non-numeric fulltext score: ${JSON.stringify(value)}`
+    );
+  }
+  return parsed;
+}
+function normalizeJsonColumn(value) {
+  return typeof value === "string" ? value : JSON.stringify(value ?? {});
+}
+var SQLITE_ROW_MAPPER_CONFIG = {
+  formatTimestamp: (value) => {
+    if (value === null || value === void 0) return;
+    if (typeof value !== "string") {
+      throw new chunkJIEJCTDS_cjs.DatabaseOperationError(
+        `Expected timestamp to be string, got ${typeof value}`,
+        { operation: "select", entity: "row" }
+      );
+    }
+    return value;
+  },
+  normalizeJson: (value) => {
+    if (typeof value !== "string") {
+      throw new chunkJIEJCTDS_cjs.DatabaseOperationError(
+        `Expected JSON column to be string, got ${typeof value}`,
+        { operation: "select", entity: "row" }
+      );
+    }
+    return value;
+  }
+};
+var POSTGRES_ROW_MAPPER_CONFIG = {
+  formatTimestamp: formatPostgresTimestamp,
+  normalizeJson: normalizeJsonColumn
+};
+function createNodeRowMapper(config) {
+  return (row) => ({
+    graph_id: asString(row.graph_id, "graph_id"),
+    kind: asString(row.kind, "kind"),
+    id: asString(row.id, "id"),
+    props: config.normalizeJson(row.props),
+    version: asNumber(row.version, "version"),
+    valid_from: nullToUndefined(config.formatTimestamp(row.valid_from)),
+    valid_to: nullToUndefined(config.formatTimestamp(row.valid_to)),
+    created_at: requireTimestamp(config.formatTimestamp(row.created_at), "created_at"),
+    updated_at: requireTimestamp(config.formatTimestamp(row.updated_at), "updated_at"),
+    deleted_at: nullToUndefined(config.formatTimestamp(row.deleted_at))
+  });
+}
+function createEdgeRowMapper(config) {
+  return (row) => ({
+    graph_id: asString(row.graph_id, "graph_id"),
+    id: asString(row.id, "id"),
+    kind: asString(row.kind, "kind"),
+    from_kind: asString(row.from_kind, "from_kind"),
+    from_id: asString(row.from_id, "from_id"),
+    to_kind: asString(row.to_kind, "to_kind"),
+    to_id: asString(row.to_id, "to_id"),
+    props: config.normalizeJson(row.props),
+    valid_from: nullToUndefined(config.formatTimestamp(row.valid_from)),
+    valid_to: nullToUndefined(config.formatTimestamp(row.valid_to)),
+    created_at: requireTimestamp(config.formatTimestamp(row.created_at), "created_at"),
+    updated_at: requireTimestamp(config.formatTimestamp(row.updated_at), "updated_at"),
+    deleted_at: nullToUndefined(config.formatTimestamp(row.deleted_at))
+  });
+}
+function createUniqueRowMapper(config) {
+  return (row) => ({
+    graph_id: asString(row.graph_id, "graph_id"),
+    node_kind: asString(row.node_kind, "node_kind"),
+    constraint_name: asString(row.constraint_name, "constraint_name"),
+    key: asString(row.key, "key"),
+    node_id: asString(row.node_id, "node_id"),
+    concrete_kind: asString(row.concrete_kind, "concrete_kind"),
+    deleted_at: nullToUndefined(config.formatTimestamp(row.deleted_at))
+  });
+}
+function createSchemaVersionRowMapper(config) {
+  return (row) => {
+    const isActiveValue = row.is_active;
+    const isActive = isActiveValue === true || isActiveValue === 1 || isActiveValue === "1";
+    return {
+      graph_id: asString(row.graph_id, "graph_id"),
+      version: asNumber(row.version, "version"),
+      schema_hash: asString(row.schema_hash, "schema_hash"),
+      schema_doc: config.normalizeJson(row.schema_doc),
+      created_at: requireTimestamp(config.formatTimestamp(row.created_at), "created_at"),
+      is_active: isActive
+    };
+  };
+}
+
+exports.POSTGRES_ROW_MAPPER_CONFIG = POSTGRES_ROW_MAPPER_CONFIG;
+exports.SQLITE_ROW_MAPPER_CONFIG = SQLITE_ROW_MAPPER_CONFIG;
+exports.coerceNumericScore = coerceNumericScore;
+exports.createEdgeRowMapper = createEdgeRowMapper;
+exports.createNodeRowMapper = createNodeRowMapper;
+exports.createSchemaVersionRowMapper = createSchemaVersionRowMapper;
+exports.createUniqueRowMapper = createUniqueRowMapper;
+exports.formatPostgresTimestamp = formatPostgresTimestamp;
+exports.nowIso = nowIso;
+//# sourceMappingURL=chunk-JJRCLAUN.cjs.map
+//# sourceMappingURL=chunk-JJRCLAUN.cjs.map

package/dist/chunk-JJRCLAUN.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/backend/drizzle/row-mappers.ts"],"names":["DatabaseOperationError"],"mappings":"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","file":"chunk-JJRCLAUN.cjs","sourcesContent":["/**\n * Shared row-mapping utilities for Drizzle backend adapters.\n */\n\nimport { DatabaseOperationError } from \"../../errors\";\nimport type { EdgeRow, NodeRow, SchemaVersionRow, UniqueRow } from \"../types\";\n\nfunction requireTimestamp(value: string | undefined, field: string): string {\n  if (value === undefined) {\n    throw new DatabaseOperationError(\n      `Expected non-null ${field} timestamp`,\n      { operation: \"select\", entity: \"row\" },\n    );\n  }\n  return value;\n}\n\nfunction asString(value: unknown, field: string): string {\n  if (typeof value !== \"string\") {\n    throw new DatabaseOperationError(\n      `Expected ${field} to be string, got ${typeof value}`,\n      { operation: \"select\", entity: \"row\" },\n    );\n  }\n  return value;\n}\n\nfunction asNumber(value: unknown, field: string): number {\n  if (typeof value !== \"number\") {\n    throw new DatabaseOperationError(\n      `Expected ${field} to be number, got ${typeof value}`,\n      { operation: \"select\", entity: \"row\" },\n    );\n  }\n  return value;\n}\n\nexport function nowIso(): string {\n  return new Date().toISOString();\n}\n\nfunction nullToUndefined<T>(value: T | null): T | undefined {\n  return value ?? undefined;\n}\n\n/**\n * Formats a PostgreSQL timestamp value to ISO string.\n * PostgreSQL returns Date objects or timestamp strings that need normalization.\n */\nexport function formatPostgresTimestamp(value: unknown): string | undefined {\n  if (value === null || value === undefined) return undefined;\n  if (value instanceof Date) return value.toISOString();\n  if (typeof value === \"string\") {\n    if (value.includes(\"T\")) return value;\n    const date = new Date(value);\n    if (!Number.isNaN(date.getTime())) return date.toISOString();\n    return value;\n  }\n  return undefined;\n}\n\n/**\n * Coerce a fulltext relevance score to `number` at the backend\n * boundary. Postgres returns `numeric` as a string to preserve\n * precision; a custom `FulltextStrategy` on either dialect could\n * likewise yield a string. Shared so both backends enforce the same\n * `FulltextSearchResult.score: number` contract and reject garbage\n * loudly instead of propagating `NaN`.\n */\nexport function coerceNumericScore(value: number | string): number {\n  if (typeof value === \"number\") return value;\n  const parsed = Number.parseFloat(value);\n  if (Number.isNaN(parsed)) {\n    throw new TypeError(\n      `Backend returned non-numeric fulltext score: ${JSON.stringify(value)}`,\n    );\n  }\n  return parsed;\n}\n\n/**\n * Normalizes a JSON column that may be returned as a parsed object (JSONB) or string.\n */\nfunction normalizeJsonColumn(value: unknown): string {\n  return typeof value === \"string\" ? value : JSON.stringify(value ?? {});\n}\n\n/**\n * Dialect-specific configuration for row mappers.\n *\n * Row mapper factories accept this config to produce dialect-appropriate\n * mappers. The `formatTimestamp` and `normalizeJson` functions handle\n * the differences between how SQLite and PostgreSQL return timestamps\n * and JSON columns.\n */\ntype DialectRowMapperConfig = Readonly<{\n  formatTimestamp: (value: unknown) => string | undefined;\n  normalizeJson: (value: unknown) => string;\n}>;\n\n/**\n * SQLite row mapper config.\n * Timestamps are stored as ISO strings; JSON is stored as TEXT.\n */\nexport const SQLITE_ROW_MAPPER_CONFIG: DialectRowMapperConfig = {\n  formatTimestamp: (value) => {\n    if (value === null || value === undefined) return;\n    if (typeof value !== \"string\") {\n      throw new DatabaseOperationError(\n        `Expected timestamp to be string, got ${typeof value}`,\n        { operation: \"select\", entity: \"row\" },\n      );\n    }\n    return value;\n  },\n  normalizeJson: (value) => {\n    if (typeof value !== \"string\") {\n      throw new DatabaseOperationError(\n        `Expected JSON column to be string, got ${typeof value}`,\n        { operation: \"select\", entity: \"row\" },\n      );\n    }\n    return value;\n  },\n};\n\n/**\n * PostgreSQL row mapper config.\n * Timestamps may be Date objects or PG-format strings; JSONB is parsed objects.\n */\nexport const POSTGRES_ROW_MAPPER_CONFIG: DialectRowMapperConfig = {\n  formatTimestamp: formatPostgresTimestamp,\n  normalizeJson: normalizeJsonColumn,\n};\n\n// Trust boundary: Drizzle raw SQL returns Record<string, unknown> rows.\n// The field access patterns below are intentional unsafe casts at the\n// database driver boundary where we know the column shapes.\n\nexport function createNodeRowMapper(\n  config: DialectRowMapperConfig,\n): (row: Record<string, unknown>) => NodeRow {\n  return (row) => ({\n    graph_id: asString(row.graph_id, \"graph_id\"),\n    kind: asString(row.kind, \"kind\"),\n    id: asString(row.id, \"id\"),\n    props: config.normalizeJson(row.props),\n    version: asNumber(row.version, \"version\"),\n    valid_from: nullToUndefined(config.formatTimestamp(row.valid_from)),\n    valid_to: nullToUndefined(config.formatTimestamp(row.valid_to)),\n    created_at: requireTimestamp(config.formatTimestamp(row.created_at), \"created_at\"),\n    updated_at: requireTimestamp(config.formatTimestamp(row.updated_at), \"updated_at\"),\n    deleted_at: nullToUndefined(config.formatTimestamp(row.deleted_at)),\n  });\n}\n\nexport function createEdgeRowMapper(\n  config: DialectRowMapperConfig,\n): (row: Record<string, unknown>) => EdgeRow {\n  return (row) => ({\n    graph_id: asString(row.graph_id, \"graph_id\"),\n    id: asString(row.id, \"id\"),\n    kind: asString(row.kind, \"kind\"),\n    from_kind: asString(row.from_kind, \"from_kind\"),\n    from_id: asString(row.from_id, \"from_id\"),\n    to_kind: asString(row.to_kind, \"to_kind\"),\n    to_id: asString(row.to_id, \"to_id\"),\n    props: config.normalizeJson(row.props),\n    valid_from: nullToUndefined(config.formatTimestamp(row.valid_from)),\n    valid_to: nullToUndefined(config.formatTimestamp(row.valid_to)),\n    created_at: requireTimestamp(config.formatTimestamp(row.created_at), \"created_at\"),\n    updated_at: requireTimestamp(config.formatTimestamp(row.updated_at), \"updated_at\"),\n    deleted_at: nullToUndefined(config.formatTimestamp(row.deleted_at)),\n  });\n}\n\nexport function createUniqueRowMapper(\n  config: DialectRowMapperConfig,\n): (row: Record<string, unknown>) => UniqueRow {\n  return (row) => ({\n    graph_id: asString(row.graph_id, \"graph_id\"),\n    node_kind: asString(row.node_kind, \"node_kind\"),\n    constraint_name: asString(row.constraint_name, \"constraint_name\"),\n    key: asString(row.key, \"key\"),\n    node_id: asString(row.node_id, \"node_id\"),\n    concrete_kind: asString(row.concrete_kind, \"concrete_kind\"),\n    deleted_at: nullToUndefined(config.formatTimestamp(row.deleted_at)),\n  });\n}\n\nexport function createSchemaVersionRowMapper(\n  config: DialectRowMapperConfig,\n): (row: Record<string, unknown>) => SchemaVersionRow {\n  return (row) => {\n    const isActiveValue = row.is_active;\n    const isActive =\n      isActiveValue === true || isActiveValue === 1 || isActiveValue === \"1\";\n\n    return {\n      graph_id: asString(row.graph_id, \"graph_id\"),\n      version: asNumber(row.version, \"version\"),\n      schema_hash: asString(row.schema_hash, \"schema_hash\"),\n      schema_doc: config.normalizeJson(row.schema_doc),\n      created_at: requireTimestamp(config.formatTimestamp(row.created_at), \"created_at\"),\n      is_active: isActive,\n    };\n  };\n}\n"]}

package/dist/{chunk-ZFWNO3GE.cjs → chunk-JQGIPGVL.cjs}

@@ -116,13 +116,77 @@ function unwrapToEmbedding(schema) {
   }
   return void 0;
 }
+var SEARCHABLE_FIELD_KEY = "_searchableField";
+var DEFAULT_SEARCHABLE_LANGUAGE = "english";
+var SEARCHABLE_WRAPPER_TYPES = /* @__PURE__ */ new Set([
+  "optional",
+  "nullable",
+  "default",
+  "prefault",
+  "catch",
+  "readonly",
+  "nonoptional",
+  "success"
+]);
+function readSearchableMetadata(value) {
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  const language = value.language;
+  return typeof language === "string" ? { language } : void 0;
+}
+function getSearchableMetadataFromSchemaMeta(schema) {
+  const meta = schema.meta();
+  return readSearchableMetadata(meta?.[SEARCHABLE_FIELD_KEY]);
+}
+function searchable(options = {}) {
+  const language = options.language ?? DEFAULT_SEARCHABLE_LANGUAGE;
+  if (language.length === 0) {
+    throw new Error("searchable() language must be a non-empty string");
+  }
+  const metadata = { language };
+  const schema = zod.z.string().meta({
+    [SEARCHABLE_FIELD_KEY]: metadata
+  });
+  return Object.assign(schema, {
+    [SEARCHABLE_FIELD_KEY]: metadata
+  });
+}
+function isSearchableSchema(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (!(SEARCHABLE_FIELD_KEY in value)) return false;
+  return readSearchableMetadata(
+    value[SEARCHABLE_FIELD_KEY]
+  ) !== void 0;
+}
+function getSearchableMetadata(schema) {
+  if (isSearchableSchema(schema)) {
+    return schema[SEARCHABLE_FIELD_KEY];
+  }
+  const directMetadata = getSearchableMetadataFromSchemaMeta(schema);
+  if (directMetadata !== void 0) {
+    return directMetadata;
+  }
+  const def = schema.def;
+  if (SEARCHABLE_WRAPPER_TYPES.has(schema.type) && def.innerType !== void 0) {
+    return getSearchableMetadata(def.innerType);
+  }
+  if (schema.type === "pipe") {
+    return (def.in === void 0 ? void 0 : getSearchableMetadata(def.in)) ?? (def.out === void 0 ? void 0 : getSearchableMetadata(def.out));
+  }
+  return void 0;
+}
 
 exports.DEFAULT_EMBEDDING_INDEX_TYPE = DEFAULT_EMBEDDING_INDEX_TYPE;
 exports.DEFAULT_EMBEDDING_METRIC = DEFAULT_EMBEDDING_METRIC;
+exports.DEFAULT_SEARCHABLE_LANGUAGE = DEFAULT_SEARCHABLE_LANGUAGE;
 exports.embedding = embedding;
 exports.getEmbeddingDimensions = getEmbeddingDimensions;
 exports.getEmbeddingIndex = getEmbeddingIndex;
+exports.getSearchableMetadata = getSearchableMetadata;
 exports.isEmbeddingSchema = isEmbeddingSchema;
+exports.isSearchableSchema = isSearchableSchema;
 exports.resolveEmbeddingFields = resolveEmbeddingFields;
-//# sourceMappingURL=chunk-ZFWNO3GE.cjs.map
-//# sourceMappingURL=chunk-ZFWNO3GE.cjs.map
+exports.searchable = searchable;
+//# sourceMappingURL=chunk-JQGIPGVL.cjs.map
+//# sourceMappingURL=chunk-JQGIPGVL.cjs.map

package/dist/chunk-JQGIPGVL.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/embedding.ts","../src/core/searchable.ts"],"names":["z"],"mappings":"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","file":"chunk-JQGIPGVL.cjs","sourcesContent":["/**\n * Embedding type for vector search.\n *\n * Creates a Zod-compatible schema for vector embeddings with\n * dimension validation and metadata for query compilation.\n */\nimport { z } from \"zod\";\n\n// ============================================================\n// Embedding Brand Symbol\n// ============================================================\n\n/**\n * Symbol used to brand embedding values at the type level.\n * This allows TypeScript to distinguish embedding arrays from regular\n * number arrays in the query builder type system.\n */\ndeclare const EMBEDDING_BRAND: unique symbol;\n\n/**\n * Branded embedding type for type-level distinction.\n * At runtime this is just `readonly number[]`, but TypeScript can\n * distinguish it from regular arrays for query builder typing.\n */\nexport type EmbeddingValue = readonly number[] & {\n  readonly [EMBEDDING_BRAND]: true;\n};\n\n// ============================================================\n// Embedding Metadata Symbol\n// ============================================================\n\n/**\n * Symbol key for storing embedding dimensions on the schema.\n * This allows the schema introspector to detect embedding types\n * and extract dimension information.\n */\nexport const EMBEDDING_DIMENSIONS_KEY = \"_embeddingDimensions\" as const;\n\n/**\n * Symbol key for storing the embedding's preferred index configuration\n * on the schema. The schema introspector reads this when auto-deriving\n * `VectorIndexDeclaration` entries at `defineGraph()` time.\n */\nexport const EMBEDDING_INDEX_KEY = \"_embeddingIndex\" as const;\n\n/**\n * Distance metric used for vector similarity. Pinned at the embedding\n * brand because changing the metric usually means generating different\n * model output (e.g. cosine-normalized vs. raw inner-product), and the\n * stored index needs the same metric to score correctly.\n *\n * - `cosine`: cosine similarity. The default — works for most\n *   sentence-transformer / OpenAI-style embeddings that are already\n *   length-normalized.\n * - `l2`: Euclidean distance. Use when your model outputs vectors\n *   trained for L2 (e.g. some image embedding models).\n * - `inner_product`: dot-product distance. Use when your model outputs\n *   pre-normalized vectors AND you want to skip the cosine\n *   normalization step at query time.\n */\nexport type EmbeddingMetric = \"cosine\" | \"l2\" | \"inner_product\";\n\n/**\n * Vector index implementation. `hnsw` is the default and what pgvector\n * recommends for most workloads. `ivfflat` is the alternative for\n * larger datasets where memory is the bottleneck. `none` disables\n * automatic index creation for this embedding (the operator can still\n * call `backend.createVectorIndex` manually).\n */\nexport type EmbeddingIndexType = \"hnsw\" | \"ivfflat\" | \"none\";\n\n/**\n * Per-embedding configuration for the auto-derived\n * `VectorIndexDeclaration`. All fields are optional with sensible\n * defaults (`cosine` / `hnsw` / pgvector defaults: `m=16`,\n * `ef_construction=64`). Override only when your model or dataset has\n * a known reason to.\n */\nexport type EmbeddingIndexOptions = Readonly<{\n  /** Distance metric. Default `\"cosine\"`. */\n  metric?: EmbeddingMetric;\n  /** Vector index implementation. Default `\"hnsw\"`. */\n  indexType?: EmbeddingIndexType;\n  /** HNSW `m` parameter — max connections per layer. Default `16`. */\n  m?: number;\n  /** HNSW `ef_construction` parameter — build-time search depth. Default `64`. */\n  efConstruction?: number;\n  /** IVFFlat `lists` parameter — number of inverted-list partitions. */\n  lists?: number;\n}>;\n\n/**\n * Resolved embedding index configuration with all defaults applied.\n * What gets attached to the brand and read by the auto-derivation pass.\n */\nexport type ResolvedEmbeddingIndex = Readonly<{\n  metric: EmbeddingMetric;\n  indexType: EmbeddingIndexType;\n  m: number;\n  efConstruction: number;\n  lists: number | undefined;\n}>;\n\nconst DEFAULT_HNSW_M = 16;\nconst DEFAULT_HNSW_EF_CONSTRUCTION = 64;\n\n// ============================================================\n// Embedding Schema Type\n// ============================================================\n\n/**\n * A Zod schema for vector embeddings with attached dimension metadata.\n * Uses the branded EmbeddingValue type for type-level distinction.\n */\nexport type EmbeddingSchema<D extends number = number> =\n  z.ZodType<EmbeddingValue> &\n    Readonly<{\n      [EMBEDDING_DIMENSIONS_KEY]: D;\n      [EMBEDDING_INDEX_KEY]: ResolvedEmbeddingIndex;\n    }>;\n\n// ============================================================\n// Embedding Factory\n// ============================================================\n\n/**\n * Creates a Zod schema for vector embeddings.\n *\n * The dimension is validated at runtime and attached as metadata\n * for the schema introspector and query compiler.\n *\n * @param dimensions - The number of dimensions (e.g., 384, 512, 768, 1536, 3072)\n * @returns A Zod schema that validates embedding arrays\n *\n * @example\n * ```typescript\n * // OpenAI ada-002 embeddings\n * const Document = defineNode(\"Document\", {\n *   schema: z.object({\n *     title: z.string(),\n *     embedding: embedding(1536),\n *   }),\n * });\n *\n * // Sentence transformers\n * const Sentence = defineNode(\"Sentence\", {\n *   schema: z.object({\n *     text: z.string(),\n *     embedding: embedding(384), // all-MiniLM-L6-v2\n *   }),\n * });\n *\n * // Optional embeddings are supported\n * const Article = defineNode(\"Article\", {\n *   schema: z.object({\n *     content: z.string(),\n *     embedding: embedding(1536).optional(),\n *   }),\n * });\n * ```\n */\nexport function embedding<D extends number>(\n  dimensions: D,\n  options: EmbeddingIndexOptions = {},\n): EmbeddingSchema<D> {\n  if (!Number.isInteger(dimensions) || dimensions <= 0) {\n    throw new Error(\n      `Embedding dimensions must be a positive integer, got: ${dimensions}`,\n    );\n  }\n\n  const indexConfig = resolveEmbeddingIndex(options);\n\n  // Use EmbeddingValue as the output type for proper type branding.\n  // At runtime, validation accepts any number array with correct dimensions.\n  const schema = z.custom<EmbeddingValue>(\n    (value): value is EmbeddingValue => {\n      if (!Array.isArray(value)) {\n        return false;\n      }\n      if (value.length !== dimensions) {\n        return false;\n      }\n      return value.every((n) => typeof n === \"number\" && Number.isFinite(n));\n    },\n    {\n      message: `Expected an array of ${dimensions} finite numbers`,\n    },\n  );\n\n  return Object.assign(schema, {\n    [EMBEDDING_DIMENSIONS_KEY]: dimensions,\n    [EMBEDDING_INDEX_KEY]: indexConfig,\n  });\n}\n\nfunction resolveEmbeddingIndex(\n  options: EmbeddingIndexOptions,\n): ResolvedEmbeddingIndex {\n  const indexType = options.indexType ?? DEFAULT_EMBEDDING_INDEX_TYPE;\n  const m = options.m ?? DEFAULT_HNSW_M;\n  const efConstruction = options.efConstruction ?? DEFAULT_HNSW_EF_CONSTRUCTION;\n\n  if (m <= 0 || !Number.isInteger(m)) {\n    throw new Error(\n      `embedding() index option 'm' must be a positive integer, got: ${m}`,\n    );\n  }\n  if (efConstruction <= 0 || !Number.isInteger(efConstruction)) {\n    throw new Error(\n      `embedding() index option 'efConstruction' must be a positive integer, got: ${efConstruction}`,\n    );\n  }\n  if (\n    options.lists !== undefined &&\n    (options.lists <= 0 || !Number.isInteger(options.lists))\n  ) {\n    throw new Error(\n      `embedding() index option 'lists' must be a positive integer, got: ${options.lists}`,\n    );\n  }\n\n  return Object.freeze({\n    metric: options.metric ?? DEFAULT_EMBEDDING_METRIC,\n    indexType,\n    m,\n    efConstruction,\n    lists: options.lists,\n  });\n}\n\n// ============================================================\n// Type Guards\n// ============================================================\n\n/**\n * Checks if a value is an embedding schema.\n */\nexport function isEmbeddingSchema(value: unknown): value is EmbeddingSchema {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    EMBEDDING_DIMENSIONS_KEY in value &&\n    typeof (value as Record<string, unknown>)[EMBEDDING_DIMENSIONS_KEY] ===\n      \"number\"\n  );\n}\n\n/**\n * Gets the dimensions from an embedding schema.\n * Returns undefined if the schema is not an embedding schema.\n */\nexport function getEmbeddingDimensions(schema: z.ZodType): number | undefined {\n  if (isEmbeddingSchema(schema)) {\n    return schema[EMBEDDING_DIMENSIONS_KEY];\n  }\n  return undefined;\n}\n\n/**\n * Gets the resolved index configuration from an embedding schema.\n * Returns undefined if the schema is not an embedding schema. Used by\n * the auto-derivation pass at `defineGraph()` time to build vector\n * `IndexDeclaration` entries.\n */\nexport function getEmbeddingIndex(\n  schema: z.ZodType,\n): ResolvedEmbeddingIndex | undefined {\n  if (!isEmbeddingSchema(schema)) return undefined;\n  const candidate = (schema as unknown as Record<string, unknown>)[\n    EMBEDDING_INDEX_KEY\n  ];\n  if (candidate === undefined) return undefined;\n  return candidate as ResolvedEmbeddingIndex;\n}\n\n// ============================================================\n// Embedding Field Resolution\n// ============================================================\n\n/**\n * One resolved embedding field on a node schema — its dot-path plus the\n * fixed `dimensions` and the resolved index `(metric, indexType)`.\n * Sourced from the field's `embedding()` brand, unwrapping `.optional()`\n * / `.nullable()` / `.default()` / `.readonly()` wrappers. The single\n * source of truth shared by embedding sync (write path), the query\n * compiler's `field.similarTo(...)` slot resolution, and search.\n */\nexport type ResolvedEmbeddingField = Readonly<{\n  fieldPath: string;\n  dimensions: number;\n  metric: EmbeddingMetric;\n  indexType: EmbeddingIndexType;\n}>;\n\n/**\n * The single source of truth for an embedding field's default metric / index\n * type when unspecified — used by `embedding()` declaration resolution, the\n * field-fallback below, and the legacy-migration slot defaults\n * (`migrate-vectors.ts`) so the three never drift.\n */\nexport const DEFAULT_EMBEDDING_METRIC: EmbeddingMetric = \"cosine\";\nexport const DEFAULT_EMBEDDING_INDEX_TYPE: EmbeddingIndexType = \"hnsw\";\n\n/**\n * Extracts every top-level embedding field from a node's object schema.\n * Returns `[]` for non-object schemas or schemas with no embedding\n * fields. Embeddings nested inside object properties are out of scope by\n * design (storage keys at the top-level `(kind, fieldPath)` grain).\n */\nexport function resolveEmbeddingFields(\n  schema: z.ZodType,\n): readonly ResolvedEmbeddingField[] {\n  if (schema.type !== \"object\") return [];\n  const shape = (schema.def as { shape?: Record<string, z.ZodType> }).shape;\n  if (!shape) return [];\n\n  const fields: ResolvedEmbeddingField[] = [];\n  for (const [fieldPath, fieldSchema] of Object.entries(shape)) {\n    const dimensions = resolveEmbeddingDimensions(fieldSchema);\n    if (dimensions === undefined) continue;\n    const index = resolveEmbeddingIndexConfig(fieldSchema);\n    fields.push({\n      fieldPath,\n      dimensions,\n      metric: index?.metric ?? DEFAULT_EMBEDDING_METRIC,\n      indexType: index?.indexType ?? DEFAULT_EMBEDDING_INDEX_TYPE,\n    });\n  }\n  return fields;\n}\n\nfunction resolveEmbeddingDimensions(schema: z.ZodType): number | undefined {\n  const direct = getEmbeddingDimensions(schema);\n  if (direct !== undefined) return direct;\n  const unwrapped = unwrapToEmbedding(schema);\n  return unwrapped === undefined ? undefined : (\n      getEmbeddingDimensions(unwrapped)\n    );\n}\n\nfunction resolveEmbeddingIndexConfig(\n  schema: z.ZodType,\n): ResolvedEmbeddingIndex | undefined {\n  const direct = getEmbeddingIndex(schema);\n  if (direct !== undefined) return direct;\n  const unwrapped = unwrapToEmbedding(schema);\n  return unwrapped === undefined ? undefined : getEmbeddingIndex(unwrapped);\n}\n\n/**\n * Unwraps optional / nullable / default / readonly wrappers to find the\n * inner embedding schema, recursing through chained wrappers. Returns\n * `undefined` when no embedding schema is reachable.\n */\nfunction unwrapToEmbedding(schema: z.ZodType): z.ZodType | undefined {\n  const type = schema.type;\n  const innerType = (schema.def as { innerType?: z.ZodType }).innerType;\n  if (\n    (type === \"optional\" ||\n      type === \"nullable\" ||\n      type === \"default\" ||\n      type === \"readonly\") &&\n    innerType\n  ) {\n    if (isEmbeddingSchema(innerType)) return innerType;\n    return unwrapToEmbedding(innerType);\n  }\n  return undefined;\n}\n","/**\n * Searchable string type for fulltext search.\n *\n * `searchable()` attaches `SearchableMetadata` to a plain Zod string so\n * the schema introspector and fulltext-sync layer can keep the fulltext\n * index in sync with node data.\n *\n * The metadata is preserved by Zod's `.meta()` across refinements\n * (`.min(1)`, `.trim()`, `.regex(...)`) and wrapper types (`.optional()`,\n * `.nullable()`, `.default(...)`, pipes) — `getSearchableMetadata()` walks\n * these variants so runtime indexing works whether or not a user chains\n * additional modifiers.\n *\n * `$fulltext` is exposed on every `NodeAccessor` at the type level; a\n * runtime guard throws a clear error if you call `.matches()` on an\n * alias whose node kind has no `searchable()` fields. This is simpler\n * and more predictable than a type-level brand that silently disappears\n * behind `.min(1)`.\n *\n * @example\n * ```typescript\n * const Document = defineNode(\"Document\", {\n *   schema: z.object({\n *     title: searchable({ language: \"english\" }),\n *     body: searchable().min(1),\n *     authorId: z.string(),\n *   }),\n * });\n * ```\n */\nimport { z } from \"zod\";\n\nexport const SEARCHABLE_FIELD_KEY = \"_searchableField\" as const;\n\nexport const DEFAULT_SEARCHABLE_LANGUAGE = \"english\" as const;\n\nconst SEARCHABLE_WRAPPER_TYPES = new Set([\n  \"optional\",\n  \"nullable\",\n  \"default\",\n  \"prefault\",\n  \"catch\",\n  \"readonly\",\n  \"nonoptional\",\n  \"success\",\n]);\n\n/**\n * Searchable field metadata attached to a Zod schema.\n */\nexport type SearchableMetadata = Readonly<{\n  /**\n   * Language for stemming / tokenization.\n   * Postgres: passed to `to_tsvector(regconfig, ...)`.\n   * SQLite FTS5: tokenizer is fixed at table-create time, so the\n   * language is recorded but not applied per-row.\n   */\n  language: string;\n}>;\n\n/**\n * Branded Zod string schema. The `SEARCHABLE_FIELD_KEY` marker is\n * attached both as a direct property (fast runtime check) and via Zod's\n * `.meta()` (so it survives `.min()`, `.trim()`, etc.).\n */\nexport type SearchableSchema = z.ZodString &\n  Readonly<{\n    [SEARCHABLE_FIELD_KEY]: SearchableMetadata;\n  }>;\n\nexport type SearchableOptions = Readonly<{\n  language?: string;\n}>;\n\ntype SearchableMetaRecord = Readonly<\n  Partial<Record<typeof SEARCHABLE_FIELD_KEY, unknown>>\n>;\n\ntype SearchableSchemaDef = Readonly<{\n  innerType?: z.ZodType;\n  in?: z.ZodType;\n  out?: z.ZodType;\n}>;\n\nfunction readSearchableMetadata(\n  value: unknown,\n): SearchableMetadata | undefined {\n  if (typeof value !== \"object\" || value === null) {\n    return undefined;\n  }\n\n  const language = (value as Partial<SearchableMetadata>).language;\n  return typeof language === \"string\" ? { language } : undefined;\n}\n\nfunction getSearchableMetadataFromSchemaMeta(\n  schema: z.ZodType,\n): SearchableMetadata | undefined {\n  const meta = schema.meta() as SearchableMetaRecord | undefined;\n  return readSearchableMetadata(meta?.[SEARCHABLE_FIELD_KEY]);\n}\n\n/**\n * Creates a Zod string schema tagged as fulltext-searchable.\n *\n * The returned schema passes runtime validation unchanged — the tag only\n * affects how TypeGraph treats the field for indexing and search. Pair\n * with `.optional()` / `.nullable()` / `.min()` / `.trim()` exactly like\n * any other Zod string; `getSearchableMetadata()` finds the metadata\n * through all of them.\n */\nexport function searchable(options: SearchableOptions = {}): SearchableSchema {\n  const language = options.language ?? DEFAULT_SEARCHABLE_LANGUAGE;\n\n  if (language.length === 0) {\n    throw new Error(\"searchable() language must be a non-empty string\");\n  }\n\n  const metadata: SearchableMetadata = { language };\n  const schema = z.string().meta({\n    [SEARCHABLE_FIELD_KEY]: metadata,\n  });\n\n  return Object.assign(schema, {\n    [SEARCHABLE_FIELD_KEY]: metadata,\n  });\n}\n\nexport function isSearchableSchema(value: unknown): value is SearchableSchema {\n  if (typeof value !== \"object\" || value === null) return false;\n  if (!(SEARCHABLE_FIELD_KEY in value)) return false;\n  return (\n    readSearchableMetadata(\n      (value as Record<string, unknown>)[SEARCHABLE_FIELD_KEY],\n    ) !== undefined\n  );\n}\n\nexport function getSearchableMetadata(\n  schema: z.ZodType,\n): SearchableMetadata | undefined {\n  if (isSearchableSchema(schema)) {\n    return schema[SEARCHABLE_FIELD_KEY];\n  }\n\n  const directMetadata = getSearchableMetadataFromSchemaMeta(schema);\n  if (directMetadata !== undefined) {\n    return directMetadata;\n  }\n\n  const def = schema.def as SearchableSchemaDef;\n  if (\n    SEARCHABLE_WRAPPER_TYPES.has(schema.type) &&\n    def.innerType !== undefined\n  ) {\n    return getSearchableMetadata(def.innerType);\n  }\n\n  if (schema.type === \"pipe\") {\n    return (\n      (def.in === undefined ? undefined : getSearchableMetadata(def.in)) ??\n      (def.out === undefined ? undefined : getSearchableMetadata(def.out))\n    );\n  }\n\n  return undefined;\n}\n"]}

package/dist/{chunk-2BVHPOIG.js → chunk-K2TGS3EN.js}

@@ -1,10 +1,12 @@
-import { NODE_TYPE_BRAND, EDGE_TYPE_BRAND, nowIso, getNodeKinds, getEdgeKinds, autoDeriveVectorIndexes, mergeVectorIndexes } from './chunk-W4ZX2GCP.js';
-import { defineNodeIndex, defineEdgeIndex } from './chunk-IJORSAC3.js';
-import { searchable } from './chunk-MXE2U3EX.js';
-import { embedding } from './chunk-454I6GDF.js';
-import { ALL_META_EDGE_NAMES, META_EDGE_IMPLIES, META_EDGE_INVERSE_OF, META_EDGE_PART_OF, META_EDGE_HAS_PART, META_EDGE_DISJOINT_WITH, META_EDGE_DIFFERENT_FROM, META_EDGE_SAME_AS, META_EDGE_EQUIVALENT_TO, META_EDGE_RELATED_TO, META_EDGE_BROADER, META_EDGE_NARROWER, META_EDGE_SUB_CLASS_OF, assertJsonValue, isReachable, computeTransitiveClosure, invertClosure, LEGACY_GRAPH_EXTENSION_VERSION, unwrap, validateGraphExtension, compactUndefined, KindCollisionError, GraphExtensionUnresolvedEndpointError, freezeDeep, assertSchemaKeysAreFree, RESERVED_NODE_KEYS, RESERVED_EDGE_KEYS } from './chunk-YCV72E6L.js';
-import { canonicalEqual, sortedReplacer, isMissingTableError } from './chunk-M6OC455F.js';
-import { sha256Hex } from './chunk-2YMGNYXY.js';
+import { canonicalEqual, sortedReplacer } from './chunk-UR7W5YQK.js';
+import { NODE_TYPE_BRAND, EDGE_TYPE_BRAND, getNodeKinds, getEdgeKinds, autoDeriveVectorIndexes, mergeVectorIndexes } from './chunk-CHXTTSC6.js';
+import { defineNodeIndex, defineEdgeIndex } from './chunk-4DIBPQNJ.js';
+import { sha256Hex } from './chunk-K34OPSJK.js';
+import { ALL_META_EDGE_NAMES, META_EDGE_IMPLIES, META_EDGE_INVERSE_OF, META_EDGE_PART_OF, META_EDGE_HAS_PART, META_EDGE_DISJOINT_WITH, META_EDGE_DIFFERENT_FROM, META_EDGE_SAME_AS, META_EDGE_EQUIVALENT_TO, META_EDGE_RELATED_TO, META_EDGE_BROADER, META_EDGE_NARROWER, META_EDGE_SUB_CLASS_OF, assertJsonValue, isReachable, computeTransitiveClosure, invertClosure, LEGACY_GRAPH_EXTENSION_VERSION, unwrap, validateGraphExtension, KindCollisionError, GraphExtensionUnresolvedEndpointError, assertSchemaKeysAreFree, RESERVED_NODE_KEYS, RESERVED_EDGE_KEYS } from './chunk-ZURTTSCM.js';
+import { nowIso } from './chunk-XXVEULWX.js';
+import { isMissingTableError } from './chunk-2MRAX3UE.js';
+import { embedding, searchable } from './chunk-Z5XBMDXU.js';
+import { compactUndefined, freezeDeep } from './chunk-ITE4IXAK.js';
 import { ConfigurationError, KindNotFoundError, DatabaseOperationError, MigrationError, ValidationError } from './chunk-TQOYM4LN.js';
 import { z } from 'zod';
 
@@ -345,24 +347,10 @@ function diffNodes(before, after) {
 function diffNodeDef(name, before, after) {
   const changes = [];
   if (!canonicalEqual(before.properties, after.properties)) {
-    const beforeProps = before.properties.properties ?? {};
-    const afterProps = after.properties.properties ?? {};
-    const beforeRequired = new Set(before.properties.required);
-    const afterRequired = new Set(after.properties.required);
-    const addedProps = Object.keys(afterProps).filter(
-      (p) => !(p in beforeProps)
-    );
-    const removedProps = Object.keys(beforeProps).filter(
-      (p) => !(p in afterProps)
-    );
-    const newRequired = [...afterRequired].filter(
-      (p) => !beforeRequired.has(p)
-    );
-    const { severity, details } = computePropertyChangeSeverity(
+    const { severity, details } = classifyPropertyChanges(
       name,
-      removedProps,
-      addedProps,
-      newRequired
+      before.properties,
+      after.properties
     );
     changes.push({
       type: "modified",
@@ -405,29 +393,103 @@ function diffNodeDef(name, before, after) {
   }
   return changes;
 }
-function computePropertyChangeSeverity(name, removedProps, addedProps, newRequired) {
-  if (removedProps.length > 0) {
+function propertyTypeSignature(schema) {
+  if (schema.type !== void 0) return JSON.stringify(schema.type);
+  if (schema.const !== void 0) return "const";
+  if (schema.enum !== void 0) return "enum";
+  if (schema.anyOf !== void 0) return "anyOf";
+  if (schema.oneOf !== void 0) return "oneOf";
+  if (schema.allOf !== void 0) return "allOf";
+  return "unknown";
+}
+var NON_CONSTRAINING_KEYWORDS = /* @__PURE__ */ new Set([
+  "description",
+  "title",
+  "default",
+  "$schema"
+]);
+function stripSchemaMetadata(schema) {
+  const stripped = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (!NON_CONSTRAINING_KEYWORDS.has(key)) stripped[key] = value;
+  }
+  return stripped;
+}
+function isObjectSchema(schema) {
+  return schema.type === "object" || schema.properties !== void 0;
+}
+function isBreakingPropertyChange(before, after) {
+  if (canonicalEqual(stripSchemaMetadata(before), stripSchemaMetadata(after))) {
+    return false;
+  }
+  if (propertyTypeSignature(before) !== propertyTypeSignature(after)) {
+    return true;
+  }
+  if (isObjectSchema(before) && isObjectSchema(after)) {
+    return isBreakingObjectSchemaChange(before, after);
+  }
+  return true;
+}
+function isBreakingObjectSchemaChange(before, after) {
+  const beforeProps = before.properties ?? {};
+  const afterProps = after.properties ?? {};
+  const beforeRequired = new Set(before.required);
+  const afterRequired = new Set(after.required);
+  for (const key of Object.keys(beforeProps)) {
+    if (!(key in afterProps)) return true;
+  }
+  for (const key of afterRequired) {
+    if (!beforeRequired.has(key)) return true;
+  }
+  for (const [key, beforeChild] of Object.entries(beforeProps)) {
+    const afterChild = afterProps[key];
+    if (afterChild === void 0) continue;
+    if (isBreakingPropertyChange(beforeChild, afterChild)) return true;
+  }
+  return false;
+}
+function classifyPropertyChanges(kind, before, after) {
+  const beforeProps = before.properties ?? {};
+  const afterProps = after.properties ?? {};
+  const beforeRequired = new Set(before.required);
+  const afterRequired = new Set(after.required);
+  const removed = Object.keys(beforeProps).filter((p) => !(p in afterProps));
+  const added = Object.keys(afterProps).filter((p) => !(p in beforeProps));
+  const newRequired = [...afterRequired].filter((p) => !beforeRequired.has(p));
+  const breakingProps = [];
+  for (const [property, beforeProperty] of Object.entries(beforeProps)) {
+    const afterProperty = afterProps[property];
+    if (afterProperty === void 0) continue;
+    if (canonicalEqual(beforeProperty, afterProperty)) continue;
+    if (isBreakingPropertyChange(beforeProperty, afterProperty)) {
+      breakingProps.push(property);
+    }
+  }
+  if (removed.length > 0) {
+    return {
+      severity: "breaking",
+      details: `Properties removed from "${kind}": ${removed.join(", ")}`
+    };
+  }
+  if (breakingProps.length > 0) {
     return {
       severity: "breaking",
-      details: `Properties removed from "${name}": ${removedProps.join(", ")}`
+      details: `Property schemas changed incompatibly in "${kind}": ${breakingProps.join(", ")}`
     };
   }
   if (newRequired.length > 0) {
     return {
       severity: "breaking",
-      details: `New required properties in "${name}": ${newRequired.join(", ")}`
+      details: `New required properties in "${kind}": ${newRequired.join(", ")}`
     };
   }
-  if (addedProps.length > 0) {
+  if (added.length > 0) {
     return {
       severity: "safe",
-      details: `Properties added to "${name}": ${addedProps.join(", ")}`
+      details: `Properties added to "${kind}": ${added.join(", ")}`
     };
   }
-  return {
-    severity: "safe",
-    details: `Properties changed in "${name}"`
-  };
+  return { severity: "safe", details: `Properties changed in "${kind}"` };
 }
 function diffEdges(before, after) {
   const changes = [];
@@ -498,11 +560,16 @@ function diffEdgeDef(name, before, after) {
     });
   }
   if (!canonicalEqual(before.properties, after.properties)) {
+    const { severity, details } = classifyPropertyChanges(
+      name,
+      before.properties,
+      after.properties
+    );
     changes.push({
       type: "modified",
       kind: name,
-      severity: "safe",
-      details: `Properties changed for "${name}"`,
+      severity,
+      details,
       before,
       after
     });
@@ -2666,5 +2733,5 @@ function createValidationError(message, issues, context) {
 }
 
 export { KindRegistry, META_EDGE_BRAND, applyDeprecatedKinds, assertSchemaCurrent, broader, buildGraphExtensionOntologyKeySet, commitNewSchemaVersion, compileTimeOntologyKey, computeClosuresFromOntology, computeSchemaDiff, computeSchemaHash, core, createEmptyClosures, createValidationError, defineEdge, defineNode, deserializeWherePredicate, differentFrom, disjointWith, ensureSchema, equivalentTo, extensionKindNames, getActiveSchema, getMigrationActions, getSchemaChanges, getTypeName, hasPart, implies, initializeSchema, inverseOf, isBackwardsCompatible, isMetaEdge, isSchemaInitialized, loadActiveSchemaWithBootstrap, loadAndMergeGraphExtensionDocument, loadAndVerifyGraph, mergeGraphExtension, migrateSchema, narrower, parseSerializedSchema, partOf, relatedTo, rollbackSchema, sameAs, serializeSchema, serializeSchemaProperties, subClassOf, validateEdgeProps, validateNodeProps, validateProps, wrapZodError };
-//# sourceMappingURL=chunk-2BVHPOIG.js.map
-//# sourceMappingURL=chunk-2BVHPOIG.js.map
+//# sourceMappingURL=chunk-K2TGS3EN.js.map
+//# sourceMappingURL=chunk-K2TGS3EN.js.map