@nicia-ai/typegraph 0.36.0 → 0.37.1

package/dist/{chunk-H7YNSMA7.cjs → chunk-HAHNRASW.cjs}

@@ -95,6 +95,23 @@ function resolveEmbeddingFields(schema) {
   }
   return fields;
 }
+function resolveGraphVectorSlots(graph) {
+  const slots = [];
+  for (const registration of Object.values(graph.nodes)) {
+    const node = registration.type;
+    for (const field of resolveEmbeddingFields(node.schema)) {
+      slots.push({
+        graphId: graph.id,
+        nodeKind: node.kind,
+        fieldPath: field.fieldPath,
+        dimensions: field.dimensions,
+        metric: field.metric,
+        indexType: field.indexType
+      });
+    }
+  }
+  return slots;
+}
 function resolveEmbeddingDimensions(schema) {
   const direct = getEmbeddingDimensions(schema);
   if (direct !== void 0) return direct;
@@ -228,6 +245,7 @@ exports.isEmbeddingSchema = isEmbeddingSchema;
 exports.isSearchableSchema = isSearchableSchema;
 exports.resolveDeclaredFulltextLanguage = resolveDeclaredFulltextLanguage;
 exports.resolveEmbeddingFields = resolveEmbeddingFields;
+exports.resolveGraphVectorSlots = resolveGraphVectorSlots;
 exports.searchable = searchable;
-//# sourceMappingURL=chunk-H7YNSMA7.cjs.map
-//# sourceMappingURL=chunk-H7YNSMA7.cjs.map
+//# sourceMappingURL=chunk-HAHNRASW.cjs.map
+//# sourceMappingURL=chunk-HAHNRASW.cjs.map

package/dist/chunk-HAHNRASW.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-HAHNRASW.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\nimport type { VectorSlot } from \"../query/dialect/vector-strategy\";\nimport type { GraphDef } from \"./define-graph\";\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\n/**\n * Enumerates every embedding `(kind, field)` slot a graph declares, as a\n * fully-resolved {@link VectorSlot}. The single source of truth for \"what\n * vector slots does this graph have?\", shared by the privileged boot\n * materializer (`materializeVectorContributions`) and the verified-attach\n * gate (`assertVectorContributionsInitialized`) so the two can never\n * provision and assert different sets. Walks `graph.nodes` and reuses\n * {@link resolveEmbeddingFields} per node schema.\n */\nexport function resolveGraphVectorSlots(\n  graph: GraphDef,\n): readonly VectorSlot[] {\n  const slots: VectorSlot[] = [];\n  for (const registration of Object.values(graph.nodes)) {\n    const node = registration.type;\n    for (const field of resolveEmbeddingFields(node.schema)) {\n      slots.push({\n        graphId: graph.id,\n        nodeKind: node.kind,\n        fieldPath: field.fieldPath,\n        dimensions: field.dimensions,\n        metric: field.metric,\n        indexType: field.indexType,\n      });\n    }\n  }\n  return slots;\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\n// ============================================================\n// Schema-level searchable-field resolution\n// ============================================================\n\n/** One searchable field discovered on a node schema. */\nexport type SearchableFieldInfo = Readonly<{\n  fieldPath: string;\n  metadata: SearchableMetadata;\n}>;\n\n/**\n * Cache keyed by the Zod schema *instance*. Schemas are immutable at\n * runtime and the same `nodeKind.schema` reference is reused across\n * every CRUD call, so this collapses the per-use introspection cost to\n * one walk per schema for the lifetime of the process.\n */\nconst searchableFieldsCache = new WeakMap<\n  z.ZodType,\n  readonly SearchableFieldInfo[]\n>();\n\n/**\n * Extracts searchable field information from a Zod schema.\n *\n * Handles top-level searchable() strings as well as wrapped variants\n * (optional / nullable / default / readonly / pipe).\n */\nexport function getSearchableFields(\n  schema: z.ZodType,\n): readonly SearchableFieldInfo[] {\n  const cached = searchableFieldsCache.get(schema);\n  if (cached) return cached;\n\n  const fields = computeSearchableFields(schema);\n  searchableFieldsCache.set(schema, fields);\n  return fields;\n}\n\nfunction computeSearchableFields(\n  schema: z.ZodType,\n): readonly SearchableFieldInfo[] {\n  if (schema.type !== \"object\") return [];\n\n  const def = schema.def as { shape?: Record<string, z.ZodType> };\n  const shape = def.shape;\n  if (!shape) return [];\n\n  const fields: SearchableFieldInfo[] = [];\n  for (const [fieldPath, fieldSchema] of Object.entries(shape)) {\n    const metadata = getSearchableMetadata(fieldSchema);\n    if (metadata !== undefined) {\n      fields.push({ fieldPath, metadata });\n    }\n  }\n  warnIfConflictingLanguages(fields);\n  return fields;\n}\n\n/**\n * Warns (once per schema, via the WeakMap memo above) when a schema's\n * searchable fields declare different `language` values. The first\n * field's language wins on the stored row; true per-field multilingual\n * indexing is not supported today.\n */\nfunction warnIfConflictingLanguages(\n  fields: readonly SearchableFieldInfo[],\n): void {\n  if (fields.length < 2) return;\n  const languages = new Set(fields.map((field) => field.metadata.language));\n  if (languages.size < 2) return;\n  if (typeof console === \"undefined\" || typeof console.warn !== \"function\") {\n    return;\n  }\n  const fieldSummary = fields\n    .map((field) => `${field.fieldPath}=${field.metadata.language}`)\n    .join(\", \");\n  const winning = fields[0]?.metadata.language ?? DEFAULT_SEARCHABLE_LANGUAGE;\n  console.warn(\n    `[typegraph] searchable() fields declare conflicting languages ` +\n      `(${fieldSummary}). The first field's language (\"${winning}\") is ` +\n      `used for the combined fulltext row.`,\n  );\n}\n\n/**\n * The one language a kind's fulltext rows are written with — the first\n * searchable field's declared language (the winning-language rule the\n * write path applies). `undefined` when the schema has no searchable\n * fields.\n *\n * Search paths use this to parse queries with a CONSTANT regconfig: the\n * per-row `websearch_to_tsquery(\"language\", ...)` form makes the tsquery\n * non-constant, so PostgreSQL's GIN index on `tsv` can never serve the\n * match and every search scans the kind's rows.\n */\nexport function resolveDeclaredFulltextLanguage(\n  schema: z.ZodType,\n): string | undefined {\n  return getSearchableFields(schema)[0]?.metadata.language;\n}\n"]}

package/dist/{chunk-J3LEGNQB.cjs → chunk-IP3CGGPA.cjs}

@@ -1,8 +1,8 @@
 'use strict';
 
-var chunk4BCU6VFZ_cjs = require('./chunk-4BCU6VFZ.cjs');
+var chunkDEFQM7JU_cjs = require('./chunk-DEFQM7JU.cjs');
 var chunkDI74SMXS_cjs = require('./chunk-DI74SMXS.cjs');
-var chunkDIK74MXX_cjs = require('./chunk-DIK74MXX.cjs');
+var chunkBVRDGYXQ_cjs = require('./chunk-BVRDGYXQ.cjs');
 var chunkTDXIBCGY_cjs = require('./chunk-TDXIBCGY.cjs');
 
 // src/ontology/closures.ts
@@ -85,7 +85,7 @@ var GRAPH_EXTENSION_ISSUE_CODES = [
   "EMPTY_INDEX_FIELDS",
   "UNKNOWN_PROPERTY_KEY"
 ];
-var GraphExtensionError = class extends chunkDIK74MXX_cjs.TypeGraphError {
+var GraphExtensionError = class extends chunkBVRDGYXQ_cjs.TypeGraphError {
   constructor(spec) {
     super(spec.message, spec.code, {
       details: spec.details,
@@ -320,7 +320,7 @@ function describeNonPlain(value) {
   return "non-plain object";
 }
 function throwInvalid(path, kind, ownerKind) {
-  throw new chunkDIK74MXX_cjs.ConfigurationError(
+  throw new chunkBVRDGYXQ_cjs.ConfigurationError(
     `${ownerKind} ${path} contains a non-JSON value (${kind}). Annotations must be JSON-serializable.`,
     { path, valueKind: kind },
     {
@@ -1163,7 +1163,7 @@ function validatePropertiesMap(raw, path, ownerType, ownerName, issues, strict)
     });
     return void 0;
   }
-  const reserved = ownerType === "node" ? chunk4BCU6VFZ_cjs.RESERVED_NODE_KEYS : chunk4BCU6VFZ_cjs.RESERVED_EDGE_KEYS;
+  const reserved = ownerType === "node" ? chunkDEFQM7JU_cjs.RESERVED_NODE_KEYS : chunkDEFQM7JU_cjs.RESERVED_EDGE_KEYS;
   const result = {};
   for (const [propertyName, propertyValue] of Object.entries(raw)) {
     const propertyPath = `${path}/${chunkTDXIBCGY_cjs.encodeJsonPointerSegment(propertyName)}`;
@@ -1836,7 +1836,7 @@ function validateAnnotations(raw, path, ownerLabel, issues) {
   try {
     assertJsonValue(raw, "annotations", ownerLabel);
   } catch (error) {
-    if (error instanceof chunkDIK74MXX_cjs.ConfigurationError) {
+    if (error instanceof chunkBVRDGYXQ_cjs.ConfigurationError) {
       const detailPath = error.details.path;
       const annotationPath = typeof detailPath === "string" ? `${path}/${detailPath.replace(/^annotations\.?/, "").replaceAll(".", "/")}` : path;
       issues.push({
@@ -1959,5 +1959,5 @@ exports.isReachable = isReachable;
 exports.ok = ok;
 exports.unwrap = unwrap;
 exports.validateGraphExtension = validateGraphExtension;
-//# sourceMappingURL=chunk-J3LEGNQB.cjs.map
-//# sourceMappingURL=chunk-J3LEGNQB.cjs.map
+//# sourceMappingURL=chunk-IP3CGGPA.cjs.map
+//# sourceMappingURL=chunk-IP3CGGPA.cjs.map