@nicia-ai/typegraph 0.46.0 → 0.46.2

package/dist/{chunk-JXA2ZP2Q.js.map → chunk-36LIJXWC.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/node.ts","../src/core/edge.ts","../src/ontology/types.ts"],"names":["validateSchemaKeys"],"mappings":";;;;;AAmCA,SAAS,kBAAA,CACP,QACA,IAAA,EACM;AACN,EAAA,uBAAA,CAAwB,MAAA,EAAQ,IAAA,EAAM,MAAA,EAAQ,kBAAkB,CAAA;AAClE;AAgBO,SAAS,UAAA,CAGd,MAAS,OAAA,EAA+C;AACxD,EAAA,kBAAA,CAAmB,OAAA,CAAQ,QAAQ,IAAI,CAAA;AACvC,EAAA,IAAI,OAAA,CAAQ,gBAAgB,MAAA,EAAW;AACrC,IAAA,eAAA,CAAgB,OAAA,CAAQ,WAAA,EAAa,aAAA,EAAe,CAAA,MAAA,EAAS,IAAI,CAAA,CAAA,CAAG,CAAA;AAAA,EACtE;AAEA,EAAA,OAAO,OAAO,MAAA,CAAO;AAAA,IACnB,CAAC,eAAe,GAAG,IAAA;AAAA,IACnB,IAAA,EAAM,IAAA;AAAA,IACN,QAAQ,OAAA,CAAQ,MAAA;AAAA,IAChB,aAAa,OAAA,CAAQ,WAAA;AAAA,IACrB,aAAa,OAAA,CAAQ;AAAA,GACtB,CAAA;AACH;ACxBA,IAAM,YAAA,GAAe,CAAA,CAAE,MAAA,CAAO,EAAE,CAAA;AAOhC,SAASA,mBAAAA,CACP,QACA,IAAA,EACM;AACN,EAAA,uBAAA,CAAwB,MAAA,EAAQ,IAAA,EAAM,MAAA,EAAQ,kBAAkB,CAAA;AAClE;AAgDO,SAAS,UAAA,CAMd,MACA,OAAA,EACqD;AACrD,EAAA,MAAM,MAAA,GAAS,SAAS,MAAA,IAAU,YAAA;AAClC,EAAAA,mBAAAA,CAAmB,QAAQ,IAAI,CAAA;AAC/B,EAAA,IAAI,OAAA,EAAS,gBAAgB,MAAA,EAAW;AACtC,IAAA,eAAA,CAAgB,OAAA,CAAQ,WAAA,EAAa,aAAA,EAAe,CAAA,MAAA,EAAS,IAAI,CAAA,CAAA,CAAG,CAAA;AAAA,EACtE;AAEA,EAAA,OAAO,OAAO,MAAA,CAAO;AAAA,IACnB,CAAC,eAAe,GAAG,IAAA;AAAA,IACnB,IAAA,EAAM,IAAA;AAAA,IACN,MAAA;AAAA,IACA,aAAa,OAAA,EAAS,WAAA;AAAA,IACtB,aAAa,OAAA,EAAS,WAAA;AAAA,IACtB,MAAM,OAAA,EAAS,IAAA;AAAA,IACf,IAAI,OAAA,EAAS;AAAA,GACd,CAAA;AACH;;;AC7HO,IAAM,eAAA,GAAkB;AA+ExB,SAAS,WAAW,KAAA,EAAmC;AAC5D,EAAA,OACE,OAAO,UAAU,QAAA,IACjB,KAAA,KAAU,QACV,eAAA,IAAmB,KAAA,IAClB,KAAA,CAAkC,eAAe,CAAA,KAAM,IAAA;AAE5D;AAKO,SAAS,YAAY,SAAA,EAAiD;AAC3E,EAAA,IAAI,OAAO,cAAc,QAAA,EAAU;AACjC,IAAA,OAAO,SAAA;AAAA,EACT;AACA,EAAA,OAAO,SAAA,CAAU,IAAA;AACnB","file":"chunk-JXA2ZP2Q.js","sourcesContent":["import { type z } from \"zod\";\n\nimport {\n  assertSchemaKeysAreFree,\n  RESERVED_NODE_KEYS,\n} from \"../store/reserved-keys\";\nimport { assertJsonValue } from \"./json-value\";\nimport { type KindAnnotations, NODE_TYPE_BRAND, type NodeType } from \"./types\";\n\n// ============================================================\n// Node Factory Options\n// ============================================================\n\n/**\n * Options for defining a node type.\n */\nexport type DefineNodeOptions<S extends z.ZodObject<z.ZodRawShape>> = Readonly<{\n  /** Zod schema for node properties */\n  schema: S;\n  /** Optional description for documentation */\n  description?: string;\n  /**\n   * Consumer-owned structured annotations for the kind.\n   *\n   * Stored in the canonical schema and **participates in schema hashing** —\n   * any change bumps the schema version and shows up as a `safe`-severity\n   * diff in `getSchemaChanges`. See `KindAnnotations` for the contract.\n   */\n  annotations?: KindAnnotations;\n}>;\n\n// ============================================================\n// Node Factory\n// ============================================================\n\nfunction validateSchemaKeys(\n  schema: z.ZodObject<z.ZodRawShape>,\n  name: string,\n): void {\n  assertSchemaKeysAreFree(\"Node\", name, schema, RESERVED_NODE_KEYS);\n}\n\n/**\n * Creates a node type definition.\n *\n * @example\n * ```typescript\n * const Person = defineNode(\"Person\", {\n *   schema: z.object({\n *     fullName: z.string().min(1),\n *     email: z.string().email().optional(),\n *   }),\n *   description: \"A person in the system\",\n * });\n * ```\n */\nexport function defineNode<\n  K extends string,\n  S extends z.ZodObject<z.ZodRawShape>,\n>(name: K, options: DefineNodeOptions<S>): NodeType<K, S> {\n  validateSchemaKeys(options.schema, name);\n  if (options.annotations !== undefined) {\n    assertJsonValue(options.annotations, \"annotations\", `Node \"${name}\"`);\n  }\n\n  return Object.freeze({\n    [NODE_TYPE_BRAND]: true as const,\n    kind: name,\n    schema: options.schema,\n    description: options.description,\n    annotations: options.annotations,\n  });\n}\n","import { z } from \"zod\";\n\nimport {\n  assertSchemaKeysAreFree,\n  RESERVED_EDGE_KEYS,\n} from \"../store/reserved-keys\";\nimport { assertJsonValue } from \"./json-value\";\nimport {\n  EDGE_TYPE_BRAND,\n  type EdgeType,\n  type KindAnnotations,\n  type NodeType,\n} from \"./types\";\n\n// ============================================================\n// Edge Factory Options\n// ============================================================\n\n/**\n * Options for defining an edge type.\n */\nexport type DefineEdgeOptions<\n  S extends z.ZodObject<z.ZodRawShape>,\n  From extends readonly NodeType[] | undefined = undefined,\n  To extends readonly NodeType[] | undefined = undefined,\n> = Readonly<{\n  /** Zod schema for edge properties (defaults to empty object) */\n  schema?: S;\n  /** Optional description for documentation */\n  description?: string;\n  /**\n   * Consumer-owned structured annotations for the kind.\n   *\n   * Stored in the canonical schema and **participates in schema hashing** —\n   * any change bumps the schema version and shows up as a `safe`-severity\n   * diff in `getSchemaChanges`. See `KindAnnotations` for the contract.\n   */\n  annotations?: KindAnnotations;\n  /** Node types that can be the source of this edge (domain constraint) */\n  from?: From;\n  /** Node types that can be the target of this edge (range constraint) */\n  to?: To;\n}>;\n\n// ============================================================\n// Empty Schema\n// ============================================================\n\nconst EMPTY_SCHEMA = z.object({});\ntype EmptySchema = typeof EMPTY_SCHEMA;\n\n// ============================================================\n// Edge Factory\n// ============================================================\n\nfunction validateSchemaKeys(\n  schema: z.ZodObject<z.ZodRawShape>,\n  name: string,\n): void {\n  assertSchemaKeysAreFree(\"Edge\", name, schema, RESERVED_EDGE_KEYS);\n}\n\n/**\n * Creates an edge type definition.\n *\n * @example\n * ```typescript\n * // Edge with no properties\n * const hasEpisode = defineEdge(\"hasEpisode\");\n *\n * // Edge with properties\n * const employedAt = defineEdge(\"employedAt\", {\n *   schema: z.object({\n *     isPrimary: z.boolean().default(true),\n *     startedAt: z.date(),\n *   }),\n *   description: \"Employment relationship\",\n * });\n *\n * // Edge with domain/range constraints (can be used directly in defineGraph)\n * const worksAt = defineEdge(\"worksAt\", {\n *   schema: z.object({ role: z.string() }),\n *   from: [Person],\n *   to: [Company],\n * });\n * ```\n */\n// Overload: no options - returns edge without domain/range\nexport function defineEdge<K extends string>(name: K): EdgeType<K, EmptySchema>;\n\n// Overload: options with both from and to - returns edge with domain/range\nexport function defineEdge<\n  K extends string,\n  S extends z.ZodObject<z.ZodRawShape>,\n  From extends readonly NodeType[],\n  To extends readonly NodeType[],\n>(\n  name: K,\n  options: DefineEdgeOptions<S, From, To> & { from: From; to: To },\n): EdgeType<K, S, From, To>;\n\n// Overload: options without from/to - returns edge without domain/range\nexport function defineEdge<\n  K extends string,\n  S extends z.ZodObject<z.ZodRawShape>,\n>(name: K, options: DefineEdgeOptions<S>): EdgeType<K, S>;\n\n// Implementation\nexport function defineEdge<\n  K extends string,\n  S extends z.ZodObject<z.ZodRawShape>,\n  From extends readonly NodeType[] | undefined,\n  To extends readonly NodeType[] | undefined,\n>(\n  name: K,\n  options?: DefineEdgeOptions<S, From, To>,\n): EdgeType<K, S, From, To> | EdgeType<K, EmptySchema> {\n  const schema = options?.schema ?? EMPTY_SCHEMA;\n  validateSchemaKeys(schema, name);\n  if (options?.annotations !== undefined) {\n    assertJsonValue(options.annotations, \"annotations\", `Edge \"${name}\"`);\n  }\n\n  return Object.freeze({\n    [EDGE_TYPE_BRAND]: true as const,\n    kind: name,\n    schema,\n    description: options?.description,\n    annotations: options?.annotations,\n    from: options?.from,\n    to: options?.to,\n  }) as EdgeType<K, S, From, To> | EdgeType<K, EmptySchema>;\n}\n","import { type EdgeType, type NodeType } from \"../core/types\";\n\n// ============================================================\n// Brand Key\n// ============================================================\n\n/** Brand key for MetaEdge */\nexport const META_EDGE_BRAND = \"__metaEdge\" as const;\n\n// ============================================================\n// Inference Types\n// ============================================================\n\n/**\n * How a meta-edge affects queries and validation.\n */\nexport type InferenceType =\n  | \"subsumption\" // Query for X includes instances of subclasses\n  | \"hierarchy\" // Enables broader/narrower traversal\n  | \"substitution\" // Can substitute equivalent types\n  | \"constraint\" // Validation rules\n  | \"composition\" // Part-whole navigation\n  | \"association\" // Discovery/recommendation\n  | \"none\"; // No automatic inference\n\n// ============================================================\n// Meta-Edge Properties\n// ============================================================\n\n/**\n * Properties of a meta-edge.\n */\nexport type MetaEdgeProperties = Readonly<{\n  transitive: boolean; // A→B, B→C implies A→C\n  symmetric: boolean; // A→B implies B→A\n  reflexive: boolean; // A→A is always true\n  inverse: string | undefined; // Name of inverse meta-edge\n  inference: InferenceType; // How this affects queries\n  description: string | undefined;\n}>;\n\n// ============================================================\n// Meta-Edge Type\n// ============================================================\n\n/**\n * A meta-edge definition.\n *\n * Meta-edges represent type-level relationships (between kinds),\n * not instance-level relationships (between nodes).\n */\nexport type MetaEdge<K extends string = string> = Readonly<{\n  [META_EDGE_BRAND]: true;\n  name: K;\n  properties: MetaEdgeProperties;\n}>;\n\n// ============================================================\n// Ontology Relation\n// ============================================================\n\n/**\n * A relation in the ontology (instance of meta-edge between types).\n *\n * @example\n * ```typescript\n * // Podcast subClassOf Media\n * subClassOf(Podcast, Media)\n *\n * // Person equivalentTo schema:Person\n * equivalentTo(Person, \"https://schema.org/Person\")\n * ```\n */\nexport type OntologyRelation = Readonly<{\n  metaEdge: MetaEdge;\n  from: NodeType | EdgeType | string; // string for external IRIs\n  to: NodeType | EdgeType | string;\n}>;\n\n// ============================================================\n// Type Guards\n// ============================================================\n\n/**\n * Checks if a value is a MetaEdge.\n */\nexport function isMetaEdge(value: unknown): value is MetaEdge {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    META_EDGE_BRAND in value &&\n    (value as Record<string, unknown>)[META_EDGE_BRAND] === true\n  );\n}\n\n/**\n * Gets the type name from a NodeType, EdgeType, or IRI string.\n */\nexport function getTypeName(typeOrIri: NodeType | EdgeType | string): string {\n  if (typeof typeOrIri === \"string\") {\n    return typeOrIri;\n  }\n  return typeOrIri.kind;\n}\n"]}
+{"version":3,"sources":["../src/core/node.ts","../src/core/edge.ts","../src/ontology/types.ts"],"names":["validateSchemaKeys"],"mappings":";;;;;AAmCA,SAAS,kBAAA,CACP,QACA,IAAA,EACM;AACN,EAAA,uBAAA,CAAwB,MAAA,EAAQ,IAAA,EAAM,MAAA,EAAQ,kBAAkB,CAAA;AAClE;AAgBO,SAAS,UAAA,CAGd,MAAS,OAAA,EAA+C;AACxD,EAAA,kBAAA,CAAmB,OAAA,CAAQ,QAAQ,IAAI,CAAA;AACvC,EAAA,IAAI,OAAA,CAAQ,gBAAgB,MAAA,EAAW;AACrC,IAAA,eAAA,CAAgB,OAAA,CAAQ,WAAA,EAAa,aAAA,EAAe,CAAA,MAAA,EAAS,IAAI,CAAA,CAAA,CAAG,CAAA;AAAA,EACtE;AAEA,EAAA,OAAO,OAAO,MAAA,CAAO;AAAA,IACnB,CAAC,eAAe,GAAG,IAAA;AAAA,IACnB,IAAA,EAAM,IAAA;AAAA,IACN,QAAQ,OAAA,CAAQ,MAAA;AAAA,IAChB,aAAa,OAAA,CAAQ,WAAA;AAAA,IACrB,aAAa,OAAA,CAAQ;AAAA,GACtB,CAAA;AACH;ACxBA,IAAM,YAAA,GAAe,CAAA,CAAE,MAAA,CAAO,EAAE,CAAA;AAOhC,SAASA,mBAAAA,CACP,QACA,IAAA,EACM;AACN,EAAA,uBAAA,CAAwB,MAAA,EAAQ,IAAA,EAAM,MAAA,EAAQ,kBAAkB,CAAA;AAClE;AAgDO,SAAS,UAAA,CAMd,MACA,OAAA,EACqD;AACrD,EAAA,MAAM,MAAA,GAAS,SAAS,MAAA,IAAU,YAAA;AAClC,EAAAA,mBAAAA,CAAmB,QAAQ,IAAI,CAAA;AAC/B,EAAA,IAAI,OAAA,EAAS,gBAAgB,MAAA,EAAW;AACtC,IAAA,eAAA,CAAgB,OAAA,CAAQ,WAAA,EAAa,aAAA,EAAe,CAAA,MAAA,EAAS,IAAI,CAAA,CAAA,CAAG,CAAA;AAAA,EACtE;AAEA,EAAA,OAAO,OAAO,MAAA,CAAO;AAAA,IACnB,CAAC,eAAe,GAAG,IAAA;AAAA,IACnB,IAAA,EAAM,IAAA;AAAA,IACN,MAAA;AAAA,IACA,aAAa,OAAA,EAAS,WAAA;AAAA,IACtB,aAAa,OAAA,EAAS,WAAA;AAAA,IACtB,MAAM,OAAA,EAAS,IAAA;AAAA,IACf,IAAI,OAAA,EAAS;AAAA,GACd,CAAA;AACH;;;AC7HO,IAAM,eAAA,GAAkB;AA+ExB,SAAS,WAAW,KAAA,EAAmC;AAC5D,EAAA,OACE,OAAO,UAAU,QAAA,IACjB,KAAA,KAAU,QACV,eAAA,IAAmB,KAAA,IAClB,KAAA,CAAkC,eAAe,CAAA,KAAM,IAAA;AAE5D;AAKO,SAAS,YAAY,SAAA,EAAiD;AAC3E,EAAA,IAAI,OAAO,cAAc,QAAA,EAAU;AACjC,IAAA,OAAO,SAAA;AAAA,EACT;AACA,EAAA,OAAO,SAAA,CAAU,IAAA;AACnB","file":"chunk-36LIJXWC.js","sourcesContent":["import { type z } from \"zod\";\n\nimport {\n  assertSchemaKeysAreFree,\n  RESERVED_NODE_KEYS,\n} from \"../store/reserved-keys\";\nimport { assertJsonValue } from \"./json-value\";\nimport { type KindAnnotations, NODE_TYPE_BRAND, type NodeType } from \"./types\";\n\n// ============================================================\n// Node Factory Options\n// ============================================================\n\n/**\n * Options for defining a node type.\n */\nexport type DefineNodeOptions<S extends z.ZodObject<z.ZodRawShape>> = Readonly<{\n  /** Zod schema for node properties */\n  schema: S;\n  /** Optional description for documentation */\n  description?: string;\n  /**\n   * Consumer-owned structured annotations for the kind.\n   *\n   * Stored in the canonical schema and **participates in schema hashing** —\n   * any change bumps the schema version and shows up as a `safe`-severity\n   * diff in `getSchemaChanges`. See `KindAnnotations` for the contract.\n   */\n  annotations?: KindAnnotations;\n}>;\n\n// ============================================================\n// Node Factory\n// ============================================================\n\nfunction validateSchemaKeys(\n  schema: z.ZodObject<z.ZodRawShape>,\n  name: string,\n): void {\n  assertSchemaKeysAreFree(\"Node\", name, schema, RESERVED_NODE_KEYS);\n}\n\n/**\n * Creates a node type definition.\n *\n * @example\n * ```typescript\n * const Person = defineNode(\"Person\", {\n *   schema: z.object({\n *     fullName: z.string().min(1),\n *     email: z.string().email().optional(),\n *   }),\n *   description: \"A person in the system\",\n * });\n * ```\n */\nexport function defineNode<\n  K extends string,\n  S extends z.ZodObject<z.ZodRawShape>,\n>(name: K, options: DefineNodeOptions<S>): NodeType<K, S> {\n  validateSchemaKeys(options.schema, name);\n  if (options.annotations !== undefined) {\n    assertJsonValue(options.annotations, \"annotations\", `Node \"${name}\"`);\n  }\n\n  return Object.freeze({\n    [NODE_TYPE_BRAND]: true as const,\n    kind: name,\n    schema: options.schema,\n    description: options.description,\n    annotations: options.annotations,\n  });\n}\n","import { z } from \"zod\";\n\nimport {\n  assertSchemaKeysAreFree,\n  RESERVED_EDGE_KEYS,\n} from \"../store/reserved-keys\";\nimport { assertJsonValue } from \"./json-value\";\nimport {\n  EDGE_TYPE_BRAND,\n  type EdgeType,\n  type KindAnnotations,\n  type NodeType,\n} from \"./types\";\n\n// ============================================================\n// Edge Factory Options\n// ============================================================\n\n/**\n * Options for defining an edge type.\n */\nexport type DefineEdgeOptions<\n  S extends z.ZodObject<z.ZodRawShape>,\n  From extends readonly NodeType[] | undefined = undefined,\n  To extends readonly NodeType[] | undefined = undefined,\n> = Readonly<{\n  /** Zod schema for edge properties (defaults to empty object) */\n  schema?: S;\n  /** Optional description for documentation */\n  description?: string;\n  /**\n   * Consumer-owned structured annotations for the kind.\n   *\n   * Stored in the canonical schema and **participates in schema hashing** —\n   * any change bumps the schema version and shows up as a `safe`-severity\n   * diff in `getSchemaChanges`. See `KindAnnotations` for the contract.\n   */\n  annotations?: KindAnnotations;\n  /** Node types that can be the source of this edge (domain constraint) */\n  from?: From;\n  /** Node types that can be the target of this edge (range constraint) */\n  to?: To;\n}>;\n\n// ============================================================\n// Empty Schema\n// ============================================================\n\nconst EMPTY_SCHEMA = z.object({});\ntype EmptySchema = typeof EMPTY_SCHEMA;\n\n// ============================================================\n// Edge Factory\n// ============================================================\n\nfunction validateSchemaKeys(\n  schema: z.ZodObject<z.ZodRawShape>,\n  name: string,\n): void {\n  assertSchemaKeysAreFree(\"Edge\", name, schema, RESERVED_EDGE_KEYS);\n}\n\n/**\n * Creates an edge type definition.\n *\n * @example\n * ```typescript\n * // Edge with no properties\n * const hasEpisode = defineEdge(\"hasEpisode\");\n *\n * // Edge with properties\n * const employedAt = defineEdge(\"employedAt\", {\n *   schema: z.object({\n *     isPrimary: z.boolean().default(true),\n *     startedAt: z.date(),\n *   }),\n *   description: \"Employment relationship\",\n * });\n *\n * // Edge with domain/range constraints (can be used directly in defineGraph)\n * const worksAt = defineEdge(\"worksAt\", {\n *   schema: z.object({ role: z.string() }),\n *   from: [Person],\n *   to: [Company],\n * });\n * ```\n */\n// Overload: no options - returns edge without domain/range\nexport function defineEdge<K extends string>(name: K): EdgeType<K, EmptySchema>;\n\n// Overload: options with both from and to - returns edge with domain/range\nexport function defineEdge<\n  K extends string,\n  S extends z.ZodObject<z.ZodRawShape>,\n  From extends readonly NodeType[],\n  To extends readonly NodeType[],\n>(\n  name: K,\n  options: DefineEdgeOptions<S, From, To> & { from: From; to: To },\n): EdgeType<K, S, From, To>;\n\n// Overload: options without from/to - returns edge without domain/range\nexport function defineEdge<\n  K extends string,\n  S extends z.ZodObject<z.ZodRawShape>,\n>(name: K, options: DefineEdgeOptions<S>): EdgeType<K, S>;\n\n// Implementation\nexport function defineEdge<\n  K extends string,\n  S extends z.ZodObject<z.ZodRawShape>,\n  From extends readonly NodeType[] | undefined,\n  To extends readonly NodeType[] | undefined,\n>(\n  name: K,\n  options?: DefineEdgeOptions<S, From, To>,\n): EdgeType<K, S, From, To> | EdgeType<K, EmptySchema> {\n  const schema = options?.schema ?? EMPTY_SCHEMA;\n  validateSchemaKeys(schema, name);\n  if (options?.annotations !== undefined) {\n    assertJsonValue(options.annotations, \"annotations\", `Edge \"${name}\"`);\n  }\n\n  return Object.freeze({\n    [EDGE_TYPE_BRAND]: true as const,\n    kind: name,\n    schema,\n    description: options?.description,\n    annotations: options?.annotations,\n    from: options?.from,\n    to: options?.to,\n  }) as EdgeType<K, S, From, To> | EdgeType<K, EmptySchema>;\n}\n","import { type EdgeType, type NodeType } from \"../core/types\";\n\n// ============================================================\n// Brand Key\n// ============================================================\n\n/** Brand key for MetaEdge */\nexport const META_EDGE_BRAND = \"__metaEdge\" as const;\n\n// ============================================================\n// Inference Types\n// ============================================================\n\n/**\n * How a meta-edge affects queries and validation.\n */\nexport type InferenceType =\n  | \"subsumption\" // Query for X includes instances of subclasses\n  | \"hierarchy\" // Enables broader/narrower traversal\n  | \"substitution\" // Can substitute equivalent types\n  | \"constraint\" // Validation rules\n  | \"composition\" // Part-whole navigation\n  | \"association\" // Discovery/recommendation\n  | \"none\"; // No automatic inference\n\n// ============================================================\n// Meta-Edge Properties\n// ============================================================\n\n/**\n * Properties of a meta-edge.\n */\nexport type MetaEdgeProperties = Readonly<{\n  transitive: boolean; // A→B, B→C implies A→C\n  symmetric: boolean; // A→B implies B→A\n  reflexive: boolean; // A→A is always true\n  inverse: string | undefined; // Name of inverse meta-edge\n  inference: InferenceType; // How this affects queries\n  description: string | undefined;\n}>;\n\n// ============================================================\n// Meta-Edge Type\n// ============================================================\n\n/**\n * A meta-edge definition.\n *\n * Meta-edges represent type-level relationships (between kinds),\n * not instance-level relationships (between nodes).\n */\nexport type MetaEdge<K extends string = string> = Readonly<{\n  [META_EDGE_BRAND]: true;\n  name: K;\n  properties: MetaEdgeProperties;\n}>;\n\n// ============================================================\n// Ontology Relation\n// ============================================================\n\n/**\n * A relation in the ontology (instance of meta-edge between types).\n *\n * @example\n * ```typescript\n * // Podcast subClassOf Media\n * subClassOf(Podcast, Media)\n *\n * // Person equivalentTo schema:Person\n * equivalentTo(Person, \"https://schema.org/Person\")\n * ```\n */\nexport type OntologyRelation = Readonly<{\n  metaEdge: MetaEdge;\n  from: NodeType | EdgeType | string; // string for external IRIs\n  to: NodeType | EdgeType | string;\n}>;\n\n// ============================================================\n// Type Guards\n// ============================================================\n\n/**\n * Checks if a value is a MetaEdge.\n */\nexport function isMetaEdge(value: unknown): value is MetaEdge {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    META_EDGE_BRAND in value &&\n    (value as Record<string, unknown>)[META_EDGE_BRAND] === true\n  );\n}\n\n/**\n * Gets the type name from a NodeType, EdgeType, or IRI string.\n */\nexport function getTypeName(typeOrIri: NodeType | EdgeType | string): string {\n  if (typeof typeOrIri === \"string\") {\n    return typeOrIri;\n  }\n  return typeOrIri.kind;\n}\n"]}

package/dist/{chunk-Q7Q4WSLJ.cjs → chunk-5PDSCELM.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkNI72YOJB_cjs = require('./chunk-NI72YOJB.cjs');
+var chunkKCH7WQA5_cjs = require('./chunk-KCH7WQA5.cjs');
 
 // src/utils/date.ts
 var CANONICAL_ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
@@ -51,7 +51,7 @@ function isCanonicalIsoDate(value) {
 }
 function validateCanonicalIsoDate(value, fieldName) {
   if (!isCanonicalIsoDate(value)) {
-    throw new chunkNI72YOJB_cjs.ValidationError(
+    throw new chunkKCH7WQA5_cjs.ValidationError(
       `Invalid canonical ISO 8601 datetime for "${fieldName}": "${value}". Expected fixed-width UTC: YYYY-MM-DDTHH:mm:ss.sssZ`,
       {
         issues: [
@@ -81,13 +81,13 @@ function isInvertedValidityWindow(validFrom, validTo) {
 }
 function assertEffectiveValidityLowerBound(subject, effectiveValidFrom, validTo) {
   if (!isInvertedValidityWindow(effectiveValidFrom, validTo)) return;
-  throw new chunkNI72YOJB_cjs.ValidationError(
+  throw new chunkKCH7WQA5_cjs.ValidationError(
     `Inverted validity window for ${subject}: the effective validFrom "${effectiveValidFrom}" is after validTo "${validTo}".`,
     {
       issues: [
         {
           path: "validTo",
-          code: chunkNI72YOJB_cjs.INVERTED_VALIDITY_WINDOW_CODE,
+          code: chunkKCH7WQA5_cjs.INVERTED_VALIDITY_WINDOW_CODE,
           message: `Expected the effective validFrom <= validTo, got "${effectiveValidFrom}" > "${validTo}". The effective validFrom is the row's stored lower bound, or the write instant where the write stamps one.`
         }
       ]
@@ -99,13 +99,13 @@ function assertEffectiveValidityLowerBound(subject, effectiveValidFrom, validTo)
 }
 function assertOrderedValidityWindow(subject, validFrom, validTo) {
   if (!isInvertedValidityWindow(validFrom, validTo)) return;
-  throw new chunkNI72YOJB_cjs.ValidationError(
+  throw new chunkKCH7WQA5_cjs.ValidationError(
     `Inverted validity window for ${subject}: validFrom "${validFrom}" is after validTo "${validTo}".`,
     {
       issues: [
         {
           path: "validFrom",
-          code: chunkNI72YOJB_cjs.INVERTED_VALIDITY_WINDOW_CODE,
+          code: chunkKCH7WQA5_cjs.INVERTED_VALIDITY_WINDOW_CODE,
           message: `Expected validFrom <= validTo, got "${validFrom}" > "${validTo}"`
         }
       ]
@@ -115,16 +115,19 @@ function assertOrderedValidityWindow(subject, validFrom, validTo) {
     }
   );
 }
+function preservesImmutableLowerBound(policy) {
+  return policy === "preserve";
+}
 function assertStatedLowerBoundIsApplicable(subject, statedValidFrom, storedValidFrom) {
   if (statedBoundMatchesStored(statedValidFrom, storedValidFrom)) return;
   const storedDescription = storedValidFrom === void 0 ? "the row has no lower bound" : `the row's stored lower bound is "${storedValidFrom}"`;
-  throw new chunkNI72YOJB_cjs.ValidationError(
+  throw new chunkKCH7WQA5_cjs.ValidationError(
     `Unappliable validFrom for ${subject}: stated "${statedValidFrom}", but ${storedDescription} and the row is live.`,
     {
       issues: [
         {
           path: "validFrom",
-          code: chunkNI72YOJB_cjs.IMMUTABLE_VALIDITY_LOWER_BOUND_CODE,
+          code: chunkKCH7WQA5_cjs.IMMUTABLE_VALIDITY_LOWER_BOUND_CODE,
           message: `A live row's lower bound is history and an in-place update never rewrites it, so "${statedValidFrom}" could not be applied.`
         }
       ]
@@ -168,7 +171,7 @@ var RECORDED_REVISION_WIDTH = 16;
 var RECORDED_MAX_REVISION = Number.MAX_SAFE_INTEGER;
 var RECORDED_INSTANT_PATTERN = /^r1:(\d{16}):(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)$/;
 function invalidRecordedInstant(value, path) {
-  return new chunkNI72YOJB_cjs.ValidationError(
+  return new chunkKCH7WQA5_cjs.ValidationError(
     `${path} must be a canonical versioned recorded instant.`,
     {
       issues: [
@@ -206,7 +209,7 @@ function optionalRecordedInstantParts(value, path = "RecordedInstant") {
 }
 function createRecordedInstant(revision, recordedAt) {
   if (!Number.isSafeInteger(revision) || revision < 1 || revision >= RECORDED_MAX_REVISION) {
-    throw new chunkNI72YOJB_cjs.ValidationError(
+    throw new chunkKCH7WQA5_cjs.ValidationError(
       "createRecordedInstant revision must be a valid recorded revision.",
       {
         issues: [
@@ -242,7 +245,7 @@ function asRecordedInstant(value) {
 }
 function resolveReadCoordinate(mode, asOf, suggestion) {
   if (mode !== "asOf" && asOf !== void 0) {
-    throw new chunkNI72YOJB_cjs.ValidationError(
+    throw new chunkKCH7WQA5_cjs.ValidationError(
       `Temporal mode "${mode}" does not take an asOf timestamp.`,
       {
         issues: [
@@ -273,7 +276,7 @@ function withRecordedCoordinate(coordinate, recordedAsOf) {
 }
 function assertValidAsOf(mode, asOf, options) {
   if (mode === "asOf" && asOf === void 0) {
-    throw new chunkNI72YOJB_cjs.ValidationError(
+    throw new chunkKCH7WQA5_cjs.ValidationError(
       'Temporal mode "asOf" requires a timestamp',
       {
         issues: [
@@ -318,11 +321,12 @@ exports.isInvertedValidityWindow = isInvertedValidityWindow;
 exports.nowIso = nowIso;
 exports.optionalRecordedInstantParts = optionalRecordedInstantParts;
 exports.parseRecordedInstant = parseRecordedInstant;
+exports.preservesImmutableLowerBound = preservesImmutableLowerBound;
 exports.recordedInstantRevision = recordedInstantRevision;
 exports.recordedInstantWallTime = recordedInstantWallTime;
 exports.resolveReadCoordinate = resolveReadCoordinate;
 exports.statedBoundMatchesStored = statedBoundMatchesStored;
 exports.validateOptionalCanonicalIsoDate = validateOptionalCanonicalIsoDate;
 exports.withRecordedCoordinate = withRecordedCoordinate;
-//# sourceMappingURL=chunk-Q7Q4WSLJ.cjs.map
-//# sourceMappingURL=chunk-Q7Q4WSLJ.cjs.map
+//# sourceMappingURL=chunk-5PDSCELM.cjs.map
+//# sourceMappingURL=chunk-5PDSCELM.cjs.map

package/dist/chunk-5PDSCELM.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/date.ts","../src/core/temporal.ts"],"names":["ValidationError","INVERTED_VALIDITY_WINDOW_CODE","IMMUTABLE_VALIDITY_LOWER_BOUND_CODE"],"mappings":"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","file":"chunk-5PDSCELM.cjs","sourcesContent":["/**\n * Date encoding utilities for consistent storage.\n *\n * Contract: All dates are stored as ISO 8601 strings in UTC.\n * - Always includes milliseconds\n * - Always UTC (Z suffix)\n * - Sorts correctly as strings\n */\n\nimport {\n  IMMUTABLE_VALIDITY_LOWER_BOUND_CODE,\n  INVERTED_VALIDITY_WINDOW_CODE,\n  ValidationError,\n} from \"../errors\";\n\n/**\n * ISO 8601 datetime pattern.\n * Matches formats like:\n * - 2024-01-15T10:30:00.000Z\n * - 2024-01-15T10:30:00Z\n * - 2024-01-15T10:30:00.123Z\n */\nconst ISO_DATE_PATTERN = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$/;\n\n/**\n * Checks if a string is a valid ISO 8601 datetime.\n *\n * @param value - String to validate\n * @returns True if valid ISO 8601 datetime\n */\nexport function isValidIsoDate(value: string): boolean {\n  if (!ISO_DATE_PATTERN.test(value)) {\n    return false;\n  }\n  // Also check that Date parsing produces a valid date\n  const date = new Date(value);\n  return !Number.isNaN(date.getTime());\n}\n\n/**\n * Validates that a string is a valid ISO 8601 datetime.\n * Throws ValidationError if invalid.\n *\n * @param value - String to validate\n * @param fieldName - Name of field for error message\n * @returns The validated string\n * @throws ValidationError if not a valid ISO datetime\n */\nexport function validateIsoDate(value: string, fieldName: string): string {\n  if (!isValidIsoDate(value)) {\n    throw new ValidationError(\n      `Invalid ISO 8601 datetime for \"${fieldName}\": \"${value}\". ` +\n        `Expected format: YYYY-MM-DDTHH:mm:ss.sssZ`,\n      {\n        issues: [\n          {\n            path: fieldName,\n            message: `Invalid ISO 8601 datetime format. Expected: YYYY-MM-DDTHH:mm:ss.sssZ, got: \"${value}\"`,\n          },\n        ],\n      },\n      {\n        suggestion: `Use a valid ISO 8601 UTC datetime like \"2024-01-15T10:30:00.000Z\"`,\n      },\n    );\n  }\n  return value;\n}\n\n/**\n * Strict canonical ISO 8601 pattern: fixed-width UTC with exactly\n * millisecond precision (`YYYY-MM-DDTHH:mm:ss.sssZ`). Unlike\n * {@link ISO_DATE_PATTERN}, which tolerates a missing or variable-width\n * fractional part, this is the only shape whose lexicographic text order\n * matches chronological order — avoiding cases like `\"...:00.1Z\"` (= `.100`)\n * sorting *after* `\"...:00.101Z\"`.\n */\nconst CANONICAL_ISO_DATE_PATTERN =\n  /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$/;\n\nconst ZONELESS_DATETIME_PATTERN =\n  /^\\d{4}-\\d{2}-\\d{2}[ T]\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?$/;\nconst OFFSET_DATETIME_PATTERN =\n  /^(\\d{4}-\\d{2}-\\d{2})[ T](\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?)(Z|[+-]\\d{2}(?::?\\d{2})?)$/i;\nconst DATE_ONLY_PATTERN = /^\\d{4}-\\d{2}-\\d{2}$/;\n\nfunction normalizedOffset(offset: string): string {\n  if (offset.toUpperCase() === \"Z\") return \"Z\";\n  if (/^[+-]\\d{2}$/.test(offset)) return `${offset}:00`;\n  if (/^[+-]\\d{4}$/.test(offset)) {\n    return `${offset.slice(0, 3)}:${offset.slice(3)}`;\n  }\n  return offset;\n}\n\nfunction databaseTimestampMilliseconds(value: string): number {\n  if (ZONELESS_DATETIME_PATTERN.test(value)) {\n    return Date.parse(`${value.replace(\" \", \"T\")}Z`);\n  }\n  const offsetMatch = OFFSET_DATETIME_PATTERN.exec(value);\n  if (offsetMatch !== null) {\n    const date = offsetMatch[1];\n    const time = offsetMatch[2];\n    const offset = offsetMatch[3];\n    if (date === undefined || time === undefined || offset === undefined) {\n      return Number.NaN;\n    }\n    return Date.parse(`${date}T${time}${normalizedOffset(offset)}`);\n  }\n  if (DATE_ONLY_PATTERN.test(value)) {\n    return Date.parse(`${value}T00:00:00.000Z`);\n  }\n  return Number.NaN;\n}\n\n/**\n * Canonicalizes a database-driver timestamp without interpreting a zoneless\n * string in the host timezone. PostgreSQL drivers can return values such as\n * `2026-06-25 12:00:00`; TypeGraph treats that shape as UTC so the same stored\n * clock value cannot move across hosts or daylight-saving boundaries.\n *\n * Returns `undefined` for an unsupported or unrepresentable value so callers\n * can raise an error specific to their storage boundary.\n */\nexport function canonicalizeDatabaseTimestamp(\n  value: unknown,\n): string | undefined {\n  if (value instanceof Date) {\n    if (Number.isNaN(value.getTime())) return undefined;\n    return value.toISOString();\n  }\n  if (typeof value !== \"string\") return undefined;\n  const milliseconds = databaseTimestampMilliseconds(value);\n  if (Number.isNaN(milliseconds)) return undefined;\n  return new Date(milliseconds).toISOString();\n}\n\n/**\n * Checks if a string is a canonical UTC ISO 8601 datetime with fixed\n * millisecond width (`YYYY-MM-DDTHH:mm:ss.sssZ`).\n */\nexport function isCanonicalIsoDate(value: string): boolean {\n  if (!CANONICAL_ISO_DATE_PATTERN.test(value)) return false;\n  const date = new Date(value);\n  return !Number.isNaN(date.getTime()) && date.toISOString() === value;\n}\n\n/**\n * Validates that a string is a canonical UTC ISO 8601 datetime with fixed\n * millisecond width. Stricter than {@link validateIsoDate} (which also\n * accepts missing or 1–2 digit milliseconds): required wherever the value\n * is compared **as text** against stored timestamps and must sort\n * chronologically — e.g. a temporal `asOf` coordinate, where a\n * variable-width value would mis-order and silently include or exclude the\n * wrong rows. Produce one with `new Date(value).toISOString()`.\n *\n * @param value - String to validate\n * @param fieldName - Name of field for error message\n * @returns The validated string\n * @throws ValidationError if not a canonical UTC ISO datetime\n */\nexport function validateCanonicalIsoDate(\n  value: string,\n  fieldName: string,\n): string {\n  if (!isCanonicalIsoDate(value)) {\n    throw new ValidationError(\n      `Invalid canonical ISO 8601 datetime for \"${fieldName}\": \"${value}\". ` +\n        `Expected fixed-width UTC: YYYY-MM-DDTHH:mm:ss.sssZ`,\n      {\n        issues: [\n          {\n            path: fieldName,\n            message: `Expected canonical UTC ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ), got: \"${value}\"`,\n          },\n        ],\n      },\n      {\n        suggestion: `Use a fixed-width UTC datetime like \"2024-01-15T10:30:00.000Z\" (e.g. new Date(value).toISOString()).`,\n      },\n    );\n  }\n  return value;\n}\n\n/**\n * Validates an optional canonical ISO date string. Returns `undefined` for an\n * absent value; otherwise enforces canonical fixed-width UTC ISO 8601 via\n * {@link validateCanonicalIsoDate}. Used for stored validity-window inputs\n * (`validFrom` / `validTo`) so every timestamp the temporal filters compare as\n * text is canonical and sorts chronologically — the same contract the `asOf`\n * read coordinate already enforces.\n */\nexport function validateOptionalCanonicalIsoDate(\n  value: string | undefined,\n  fieldName: string,\n): string | undefined {\n  if (value === undefined) return undefined;\n  return validateCanonicalIsoDate(value, fieldName);\n}\n\n/**\n * Whether a CANONICAL stated bound names the same instant a row already stores.\n *\n * The one comparison of a caller's bound against a stored one, so the coalesce\n * dirty check (\"would this write move the window?\") and the write guard (\"can\n * this stated bound be applied?\") can never disagree about what \"the same bound\"\n * means. Two copies of it did disagree — one comparing driver text, one\n * comparing instants — which is how a re-stated window wrote on one backend and\n * coalesced on the other.\n *\n * Only the STORED side is canonicalized. It arrives as the driver rendered it,\n * and the dialects do not render a timestamp the same way (SQLite returns the\n * written text; a Postgres driver may hand back a zoned string equivalent to the\n * canonical form without being identical to it). The stated side needs no\n * canonicalization because every write path validates it as canonical first —\n * which is a PRECONDITION here, not an assumption: a non-canonical stated bound\n * would compare unequal to an equivalent stored instant and must be rejected by\n * {@link validateCanonicalIsoDate} rather than silently treated as a mismatch.\n */\nexport function statedBoundMatchesStored(\n  stated: string,\n  stored: string | undefined,\n): boolean {\n  return stated === canonicalizeDatabaseTimestamp(stored);\n}\n\n/**\n * Whether a stated validity window has NEGATIVE width — a row that stopped\n * being true before it started. The one comparison every window refusal is\n * built on, so paths that must report the fault through their own error type\n * (trusted import) decide it identically to the ones that throw a\n * `ValidationError`.\n *\n * PRECONDITION: both endpoints are canonical fixed-width UTC ISO 8601, which is\n * what makes a lexicographic compare a chronological one. Every caller\n * establishes that before comparing, with no exception: the paths that throw a\n * `ValidationError` reach this through {@link validateOptionalCanonicalIsoDate},\n * and trusted import — which skips schema validation for throughput —\n * format-checks the stated window fields of every streamed row against\n * {@link isCanonicalIsoDate} before reaching here. A bound read back from a row\n * needs no check of its own: it is canonical because the write that stored it\n * was held to this same contract — SQLite hands that text back verbatim, and the\n * PostgreSQL row mapper normalizes the driver's shape back to it. So no caller\n * can compare a value that would mis-sort, here or later against an `asOf`\n * coordinate.\n *\n * ZERO width (`validFrom === validTo`) is not inverted: it is what a\n * same-instant retraction produces at millisecond precision, and the store's own\n * output must round-trip.\n */\nexport function isInvertedValidityWindow(\n  validFrom: string | undefined,\n  validTo: string | undefined,\n): boolean {\n  if (validFrom === undefined || validTo === undefined) return false;\n  return validFrom > validTo;\n}\n\n/**\n * Refuses a `validTo` whose EFFECTIVE lower bound would invert the window. On an\n * in-place update the row's stored lower bound is the effective one and must stay\n * <= the new `validTo`; on a resurrection that RESETS `valid_from` it is the\n * write instant, so a lone past `validTo` would be born inverted.\n *\n * A ZERO-width window (`validTo === effectiveValidFrom`) is legal and stays\n * legal: it is what a same-instant retraction produces at millisecond\n * precision, and the identity-import window check sanctions it for the same\n * reason. Only NEGATIVE width refuses.\n *\n * Reached through {@link assertWritableValidityWindow} rather than called\n * directly, so no writer can check the effective bound without also checking a\n * stated pair.\n */\nfunction assertEffectiveValidityLowerBound(\n  subject: string,\n  effectiveValidFrom: string | undefined,\n  validTo: string | undefined,\n): void {\n  if (!isInvertedValidityWindow(effectiveValidFrom, validTo)) return;\n  throw new ValidationError(\n    `Inverted validity window for ${subject}: the effective validFrom \"${effectiveValidFrom}\" is after validTo \"${validTo}\".`,\n    {\n      issues: [\n        {\n          path: \"validTo\",\n          code: INVERTED_VALIDITY_WINDOW_CODE,\n          message: `Expected the effective validFrom <= validTo, got \"${effectiveValidFrom}\" > \"${validTo}\". The effective validFrom is the row's stored lower bound, or the write instant where the write stamps one.`,\n        },\n      ],\n    },\n    {\n      suggestion:\n        \"Provide both validFrom and validTo for a historical window, or drop validTo to keep the row current.\",\n    },\n  );\n}\n\n/**\n * Rejects an inverted validity window. `validFrom > validTo` describes a row\n * that stopped being true before it started, so no current-mode or `asOf` read\n * can ever observe it — the write succeeds and the row is then reachable only\n * through `includeEnded`, which reads as data loss rather than as the error it\n * is. Call this wherever both endpoints are supplied together; both are\n * canonical ISO 8601 by then, so a lexicographic compare is a chronological\n * compare.\n *\n * @param subject - Human-readable identification of the row, for the message\n *   (e.g. `Person \"01H...\"`).\n * @throws ValidationError if both endpoints are present and out of order\n */\nexport function assertOrderedValidityWindow(\n  subject: string,\n  validFrom: string | undefined,\n  validTo: string | undefined,\n): void {\n  if (!isInvertedValidityWindow(validFrom, validTo)) return;\n  throw new ValidationError(\n    `Inverted validity window for ${subject}: validFrom \"${validFrom}\" is after validTo \"${validTo}\".`,\n    {\n      issues: [\n        {\n          path: \"validFrom\",\n          code: INVERTED_VALIDITY_WINDOW_CODE,\n          message: `Expected validFrom <= validTo, got \"${validFrom}\" > \"${validTo}\"`,\n        },\n      ],\n    },\n    {\n      suggestion:\n        \"Pass a validFrom at or before validTo, or omit validTo to leave the window open.\",\n    },\n  );\n}\n\n/**\n * What an UPDATE will do with the row's validity lower bound — the two facts the\n * write guard needs, stated by the writer that knows them.\n *\n * Every update path must decide `appliesStatedValidFrom` explicitly, because the\n * answer is not a property of the guard's other arguments: the same\n * `(validFrom, storedBound, validTo)` triple is a legal window restatement on a\n * resurrection and an unappliable bound on an in-place update.\n */\nexport type UpdateValidityLowerBound = Readonly<{\n  /**\n   * The bound the row will hold when the caller states no `validFrom`: the\n   * stored `valid_from` for an in-place update, the write instant for a\n   * resurrection that stamps a new one, `undefined` where there is no bound to\n   * invert against.\n   */\n  effectiveValidFrom: string | undefined;\n  /**\n   * Whether the write STORES a stated `validFrom`. False for an in-place update\n   * of a live row — `buildUpdateNode` / `buildUpdateEdge` rewrite `valid_from`\n   * only on a resurrection — which is what makes a differing stated bound a\n   * refusal rather than a silent drop.\n   */\n  appliesStatedValidFrom: boolean;\n  /**\n   * Whether `effectiveValidFrom` IS the row's stored `valid_from` — the value an\n   * `expectedValidFrom` predicate would name — rather than a bound this write is\n   * about to stamp itself.\n   *\n   * A node resurrection resets `valid_from` to the write instant and passes THAT\n   * as the effective bound, so its verdict never looked at what the row holds and\n   * a fence on the stored value would predicate the write on something nothing\n   * read. An edge retains its bound through a resurrection, so its effective\n   * bound is the stored one on both legs.\n   */\n  effectiveBoundIsStored: boolean;\n}>;\n\n/**\n * The `expectedValidFrom` predicate a write owes its verdict, shaped for\n * spreading straight into the backend's update params.\n *\n * `{}` means \"assert nothing\"; `{ expectedValidFrom: null }` means \"assert the\n * row still has NO lower bound\". The two are different claims and the object\n * form keeps them distinguishable at every call site — see\n * `UpdateNodeParams.expectedValidFrom`.\n */\nexport type ValidityLowerBoundFence = Readonly<{\n  expectedValidFrom?: string | null;\n}>;\n\n/**\n * What {@link assertWritableValidityWindow} reports back about the verdict it\n * just reached — not about the window, but about what the verdict DEPENDED ON.\n *\n * THE SINGLE OWNER of the question \"must this write assert the row's stored\n * lower bound?\", and it answers by handing over the predicate ITSELF rather than\n * a flag a caller then turns into one. A write asserts every component its\n * verdict read (see `UpdateNodeParams.expectedValidFrom`), and which components\n * those are is decided by which branches the guard actually took — so a caller\n * that could still spell the fence on its own would eventually spell a different\n * one. Interchange import did exactly that: it asserted the probed\n * `valid_from` unconditionally, over-fencing props-only updates the store paths\n * (correctly) left unfenced. There is now nothing to re-derive.\n *\n * Too FEW assertions is a silent race; too many is a refusal of writes that are\n * legitimate. Both failures come from a second spelling.\n */\nexport type ValidityWindowVerdict = Readonly<{\n  /**\n   * The fence this verdict obliges the write to carry. Non-empty when the\n   * verdict consulted the row's STORED `valid_from` — either by comparing a\n   * stated bound against it, or by inverting a lone `validTo` against it — and\n   * empty when the caller named no window at all, when the write applies the\n   * bound it stated, or when the effective bound was one this write will stamp\n   * rather than one the row holds. In those cases the verdict is independent of\n   * what the row carries, and predicating the write on it would refuse a\n   * concurrent recreate that changed nothing this decision looked at.\n   */\n  storedLowerBoundFence: ValidityLowerBoundFence;\n}>;\n\n/**\n * Whether an upsert explicitly treats its stated lower bound as\n * create/resurrection-only input.\n *\n * This predicate owns the policy decision for both write execution and\n * unchanged-upsert coalescing, so those paths cannot drift on whether a live\n * row's stored lower bound is preserved.\n */\nexport function preservesImmutableLowerBound(\n  policy: \"preserve\" | \"refuse\" | undefined,\n): policy is \"preserve\" {\n  return policy === \"preserve\";\n}\n\n/**\n * Refuses a stated `validFrom` the write would not apply.\n *\n * A live row's lower bound is HISTORY: it records when the row started being\n * true, and an in-place update never moves it. Accepting a bound that names a\n * different instant and then dropping it is the API lying — the caller's stated\n * window silently is not the stored one, while the write still spends a version\n * bump and a history row moving nothing. Restating the bound the row already\n * holds stays legal, so a caller that echoes a row's own window back (a merge\n * commit, a re-delivered upsert) is unaffected.\n *\n * Reached through {@link assertWritableValidityWindow} rather than called\n * directly, so no writer can accept a lower bound without declaring whether it\n * applies one.\n */\nfunction assertStatedLowerBoundIsApplicable(\n  subject: string,\n  statedValidFrom: string,\n  storedValidFrom: string | undefined,\n): void {\n  if (statedBoundMatchesStored(statedValidFrom, storedValidFrom)) return;\n  const storedDescription =\n    storedValidFrom === undefined ?\n      \"the row has no lower bound\"\n    : `the row's stored lower bound is \"${storedValidFrom}\"`;\n  throw new ValidationError(\n    `Unappliable validFrom for ${subject}: stated \"${statedValidFrom}\", but ${storedDescription} and the row is live.`,\n    {\n      issues: [\n        {\n          path: \"validFrom\",\n          code: IMMUTABLE_VALIDITY_LOWER_BOUND_CODE,\n          message: `A live row's lower bound is history and an in-place update never rewrites it, so \"${statedValidFrom}\" could not be applied.`,\n        },\n      ],\n    },\n    {\n      suggestion:\n        storedValidFrom === undefined ?\n          \"Omit validFrom: this row has no lower bound to restate, and only a resurrection can give it one.\"\n        : `Restate the stored bound (\"${storedValidFrom}\") or omit validFrom.`,\n    },\n  );\n}\n\n/**\n * THE window-ordering guard a valid-time UPDATE goes through, identically for\n * nodes and edges. Refuses a window of negative width — a row that stopped\n * being true before it started — whether the caller states both endpoints or\n * only the new end. Also refuses a stated lower bound the write cannot apply,\n * so no update accepts a `validFrom` it will ignore.\n *\n * Three checks, because the failures deserve different messages: the caller who\n * supplied both endpoints out of order gets told about the pair, the caller who\n * stated a lower bound this write cannot store gets told which bound the row\n * holds, and the caller whose lone `validTo` inverts against the bound the row\n * will actually carry gets told which bound that is.\n *\n * The stated pair is judged FIRST — an inverted pair is wrong whatever the row\n * holds — and the applicability of the lower bound before the effective-bound\n * check, so a caller is told their bound will not be stored rather than being\n * told about a bound they did not name.\n *\n * INSERTS use {@link assertOrderedValidityWindow} alone. An insert carrying a\n * lone historical `validTo` means \"born already ended\", and the write instant\n * the backend stamps as `valid_from` is a storage convention rather than a\n * caller assertion — the row is deliberately not current and is read back\n * through `includeEnded`. Only an UPDATE has a lower bound the caller can be\n * held to.\n *\n * @param subject - Human-readable identification of the row, for the message\n *   (e.g. `Person \"01H...\"`).\n * @param validFrom - The caller's explicit lower bound, if any.\n * @param lowerBound - What the write will do with the row's lower bound; see\n *   {@link UpdateValidityLowerBound}.\n * @returns {@link ValidityWindowVerdict} — the `expectedValidFrom` fence this\n *   verdict obliges the write to carry, empty when it read no stored bound.\n * @throws ValidationError with issue code {@link INVERTED_VALIDITY_WINDOW_CODE}\n *   or {@link IMMUTABLE_VALIDITY_LOWER_BOUND_CODE}\n */\nexport function assertWritableValidityWindow(\n  subject: string,\n  validFrom: string | undefined,\n  lowerBound: UpdateValidityLowerBound,\n  validTo: string | undefined,\n): ValidityWindowVerdict {\n  assertOrderedValidityWindow(subject, validFrom, validTo);\n\n  // The stated bound is COMPARED against the stored one only here — a write\n  // that applies what the caller stated has nothing to compare it to.\n  const comparedStatedBound =\n    validFrom !== undefined && !lowerBound.appliesStatedValidFrom;\n  if (comparedStatedBound) {\n    assertStatedLowerBoundIsApplicable(\n      subject,\n      validFrom,\n      lowerBound.effectiveValidFrom,\n    );\n  }\n\n  assertEffectiveValidityLowerBound(\n    subject,\n    validFrom ?? lowerBound.effectiveValidFrom,\n    validTo,\n  );\n  // ...and the inversion check falls back to the row's bound only when the\n  // caller named an end without a start. Note this is true whether or not the\n  // row HAS a bound: \"no lower bound to invert against\" is itself a reading of\n  // the row, and a recreate that gives the row one changes the answer.\n  const comparedStoredBoundAgainstEnd =\n    validFrom === undefined && validTo !== undefined;\n\n  const readEffectiveLowerBound =\n    comparedStatedBound || comparedStoredBoundAgainstEnd;\n  return {\n    storedLowerBoundFence:\n      readEffectiveLowerBound && lowerBound.effectiveBoundIsStored ?\n        // eslint-disable-next-line unicorn/no-null -- `expectedValidFrom` distinguishes \"assert IS NULL\" (null) from \"assert nothing\" (an absent key); see UpdateNodeParams.\n        { expectedValidFrom: lowerBound.effectiveValidFrom ?? null }\n      : {},\n  };\n}\n\n/**\n * Encodes a Date to an ISO 8601 string for storage.\n */\nexport function encodeDate(date: Date): string {\n  return date.toISOString();\n}\n\n/**\n * Decodes an ISO 8601 string to a Date.\n * Validates the string format first.\n *\n * @throws ValidationError if not a valid ISO datetime\n */\nexport function decodeDate(isoString: string): Date {\n  validateIsoDate(isoString, \"date\");\n  return new Date(isoString);\n}\n\n/**\n * Returns the current timestamp as an ISO string.\n */\nexport function nowIso(): string {\n  return new Date().toISOString();\n}\n","/**\n * Shared temporal coordinate + validation.\n */\nimport { ValidationError } from \"../errors\";\nimport { validateCanonicalIsoDate } from \"../utils/date\";\nimport { type TemporalMode } from \"./types\";\n\nconst RECORDED_INSTANT_VERSION = \"r1\";\nconst RECORDED_REVISION_WIDTH = 16;\n/** Open interval ceiling for numeric recorded-revision columns. */\nexport const RECORDED_MAX_REVISION = Number.MAX_SAFE_INTEGER;\nconst RECORDED_INSTANT_PATTERN =\n  /^r1:(\\d{16}):(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z)$/;\n\ndeclare const RECORDED_INSTANT_BRAND: unique symbol;\n\n/**\n * A versioned recorded-time anchor containing a fixed-width logical revision\n * and a canonical UTC physical timestamp:\n * `r1:0000000000000001:YYYY-MM-DDTHH:mm:ss.sssZ`.\n *\n * Logical revisions are strictly monotonic per graph and make every commit\n * addressable even when many commits share one wall-clock millisecond. The\n * timestamp is a non-decreasing physical wall-time high-water mark used by\n * diagonal valid-time reads. Same-millisecond commits repeat it; backward clock\n * corrections hold it at the previous value until wall time catches up. The\n * string is canonical and lexicographically ordered by revision, so it can\n * round-trip through plain string checkpoint columns without a custom\n * serializer.\n */\nexport type RecordedInstant = string & {\n  readonly [RECORDED_INSTANT_BRAND]: \"RecordedInstant\";\n};\n\nexport type RecordedInstantParts = Readonly<{\n  revision: number;\n  recordedAt: string;\n}>;\n\nfunction invalidRecordedInstant(value: string, path: string): ValidationError {\n  return new ValidationError(\n    `${path} must be a canonical versioned recorded instant.`,\n    {\n      issues: [\n        {\n          path,\n          message: `Expected ${RECORDED_INSTANT_VERSION}:<${RECORDED_REVISION_WIDTH}-digit revision>:YYYY-MM-DDTHH:mm:ss.sssZ, got \"${value}\"`,\n        },\n      ],\n    },\n    {\n      suggestion:\n        \"Persist the exact string returned by store.recordedNow(); migrate preview-schema checkpoints with migrateLegacyRecordedTime() and migrateRecordedAnchor().\",\n    },\n  );\n}\n\nexport function parseRecordedInstant(\n  value: string,\n  path = \"RecordedInstant\",\n): RecordedInstantParts {\n  const match = RECORDED_INSTANT_PATTERN.exec(value);\n  if (match === null) throw invalidRecordedInstant(value, path);\n  const revisionText = match[1];\n  const recordedAt = match[2];\n  if (revisionText === undefined || recordedAt === undefined) {\n    throw invalidRecordedInstant(value, path);\n  }\n  const revision = Number(revisionText);\n  if (\n    !Number.isSafeInteger(revision) ||\n    revision < 1 ||\n    revision >= RECORDED_MAX_REVISION\n  ) {\n    throw invalidRecordedInstant(value, path);\n  }\n  validateCanonicalIsoDate(recordedAt, path);\n  return { revision, recordedAt };\n}\n\nexport function assertValidRecordedInstant(value: string, path: string): void {\n  parseRecordedInstant(value, path);\n}\n\n/**\n * Splits an optional recorded anchor into the numeric revision that recorded\n * relations store their `recorded_from`/`recorded_to` boundaries as, and the\n * wall time that valid-time windows are measured against. Compilers that\n * consult both halves parse once through this instead of per predicate.\n */\nexport function optionalRecordedInstantParts(\n  value: string | undefined,\n  path = \"RecordedInstant\",\n): RecordedInstantParts | undefined {\n  return value === undefined ? undefined : parseRecordedInstant(value, path);\n}\n\nexport function createRecordedInstant(\n  revision: number,\n  recordedAt: string,\n): RecordedInstant {\n  if (\n    !Number.isSafeInteger(revision) ||\n    revision < 1 ||\n    revision >= RECORDED_MAX_REVISION\n  ) {\n    throw new ValidationError(\n      \"createRecordedInstant revision must be a valid recorded revision.\",\n      {\n        issues: [\n          {\n            path: \"createRecordedInstant.revision\",\n            message: `Expected a safe integer from 1 through ${String(RECORDED_MAX_REVISION - 1)}, got ${String(revision)}`,\n          },\n        ],\n      },\n    );\n  }\n  const revisionText = revision\n    .toString()\n    .padStart(RECORDED_REVISION_WIDTH, \"0\");\n  return asRecordedInstant(\n    `${RECORDED_INSTANT_VERSION}:${revisionText}:${recordedAt}`,\n  );\n}\n\n/**\n * Returns the canonical UTC wall-time component of a recorded anchor.\n *\n * The value is non-decreasing per graph, but it is not the commit-order key;\n * use the complete {@link RecordedInstant} when ordering or replaying commits.\n */\nexport function recordedInstantWallTime(instant: RecordedInstant): string {\n  return parseRecordedInstant(instant).recordedAt;\n}\n\n/** Returns the strict per-graph logical revision carried by an anchor. */\nexport function recordedInstantRevision(instant: RecordedInstant): number {\n  return parseRecordedInstant(instant).revision;\n}\n\n/**\n * Compares two recorded anchors by logical revision.\n *\n * Revisions are local to a graph, so only compare anchors produced by the same\n * graph. The physical wall-time component deliberately does not participate.\n */\nexport function compareRecordedInstants(\n  left: RecordedInstant,\n  right: RecordedInstant,\n): -1 | 0 | 1 {\n  const leftRevision = recordedInstantRevision(left);\n  const rightRevision = recordedInstantRevision(right);\n  if (leftRevision < rightRevision) return -1;\n  if (leftRevision > rightRevision) return 1;\n  return 0;\n}\n\n/**\n * Brands a canonical versioned anchor string as a {@link RecordedInstant}.\n *\n * The escape hatch for an instant that round-trips through untyped storage:\n * captured from {@link Store.recordedNow}, persisted as a plain string, read\n * back, and replayed into `asOfRecorded`. Validates the canonical form eagerly —\n * the same check `asOfRecorded` applies — so a malformed value fails here, at the\n * brand site, rather than deeper in a read. Does *not* assert the instant is a\n * real captured commit; it only guarantees the value is well-formed enough to\n * compare correctly against the recorded relations.\n *\n * @throws {ValidationError} when `value` is not a canonical versioned anchor.\n */\nexport function asRecordedInstant(value: string): RecordedInstant {\n  assertValidRecordedInstant(value, \"asRecordedInstant\");\n  return value as RecordedInstant;\n}\n\n/**\n * The single opaque temporal coordinate every pinned read is resolved\n * against. It carries the valid-time axis plus an optional recorded/system-time\n * axis, so every surface can inject one coordinate object instead of threading\n * each temporal dimension separately.\n */\nexport type ReadCoordinate = Readonly<{\n  /**\n   * The valid-time axis: a resolved temporal mode and (only for `\"asOf\"`) the\n   * instant it is pinned to.\n   */\n  valid: Readonly<{\n    mode: TemporalMode;\n    /** Defined only when `mode` is `\"asOf\"`. */\n    asOf?: string;\n  }>;\n  /** The recorded/system-time axis. Defined only for recorded-pinned views. */\n  recorded?: Readonly<{ asOf: RecordedInstant }>;\n}>;\n\n/**\n * Resolves and validates a `(mode, asOf)` pair into a {@link ReadCoordinate}.\n * Rejects an `asOf` paired with any non-`\"asOf\"` mode rather than silently\n * dropping it — pinning an instant is only meaningful in `\"asOf\"` mode, so a\n * `view({ mode: \"current\", asOf })` is a caller mistake, not a coordinate to\n * quietly discard. Then validates via {@link assertValidAsOf}.\n *\n * @param mode - The temporal mode to pin.\n * @param asOf - The supplied timestamp. Required for `\"asOf\"`; rejected for\n *   every other mode.\n * @param suggestion - Caller-specific remediation hint for the\n *   missing/invalid-timestamp case.\n */\nexport function resolveReadCoordinate(\n  mode: TemporalMode,\n  asOf: string | undefined,\n  suggestion?: string,\n): ReadCoordinate {\n  if (mode !== \"asOf\" && asOf !== undefined) {\n    throw new ValidationError(\n      `Temporal mode \"${mode}\" does not take an asOf timestamp.`,\n      {\n        issues: [\n          {\n            path: \"asOf\",\n            message: `asOf is only valid with mode \"asOf\", not \"${mode}\"`,\n          },\n        ],\n      },\n      {\n        suggestion:\n          'Pin an instant with store.asOf(timestamp) or store.view({ mode: \"asOf\", asOf }); drop asOf for other modes.',\n      },\n    );\n  }\n  assertValidAsOf(\n    mode,\n    asOf,\n    suggestion === undefined ? undefined : { suggestion },\n  );\n  return { valid: asOf === undefined ? { mode } : { mode, asOf } };\n}\n\n/**\n * Adds a recorded/system-time pin to an existing valid-time coordinate.\n * Direct `store.asOfRecorded(T)` passes the diagonal valid-time coordinate\n * (`mode: \"asOf\", asOf: T`); `store.asOf(vt).asOfRecorded(rt)` passes the\n * already-resolved valid coordinate and adds the recorded sibling.\n */\nexport function withRecordedCoordinate(\n  coordinate: ReadCoordinate,\n  recordedAsOf: RecordedInstant,\n): ReadCoordinate {\n  assertValidRecordedInstant(recordedAsOf, \"asOfRecorded\");\n  return {\n    ...coordinate,\n    recorded: { asOf: recordedAsOf },\n  };\n}\n\n/**\n * Validates the `asOf` coordinate of a temporal read: `\"asOf\"` mode\n * requires a timestamp, and any supplied timestamp must be a canonical\n * fixed-width UTC ISO-8601 string (`YYYY-MM-DDTHH:mm:ss.sssZ`). The latter\n * is load-bearing — temporal filters compare `asOf` against `valid_from` /\n * `valid_to` as text on SQLite, so a non-canonical value (date-only, an\n * offset, natural language, or variable-width / missing milliseconds like\n * `.1Z`) would sort and compare wrong rather than error. Reached only through\n * {@link resolveReadCoordinate}, which every temporal read entry point routes\n * through (direct reads, queries, subgraphs, algorithms, and StoreView), so\n * they all fail identically.\n *\n * @param mode - The resolved temporal mode.\n * @param asOf - The supplied timestamp (may be `undefined`).\n * @param options.suggestion - A caller-specific remediation hint for the\n *   missing-timestamp case.\n *\n * @throws {ValidationError} when `mode` is `\"asOf\"` and `asOf` is missing, or\n *   when any supplied `asOf` is not a canonical UTC ISO-8601 timestamp. The\n *   canonical check runs for *every* mode that consumes `asOf`, so a\n *   non-canonical value can never reach a text comparison.\n */\nfunction assertValidAsOf(\n  mode: TemporalMode,\n  asOf: string | undefined,\n  options?: Readonly<{ suggestion?: string }>,\n): void {\n  if (mode === \"asOf\" && asOf === undefined) {\n    throw new ValidationError(\n      'Temporal mode \"asOf\" requires a timestamp',\n      {\n        issues: [\n          { path: \"asOf\", message: \"Timestamp is required for asOf mode\" },\n        ],\n      },\n      {\n        suggestion:\n          options?.suggestion ??\n          'Provide an ISO-8601 timestamp for asOf mode, e.g. \"2026-01-01T00:00:00.000Z\".',\n      },\n    );\n  }\n  if (asOf !== undefined) {\n    validateCanonicalIsoDate(asOf, \"asOf\");\n  }\n}\n\n/**\n * A human-readable description of a coordinate for error messages, e.g.\n * `mode \"current\"` or `mode \"asOf\" asOf 2026-01-01T00:00:00.000Z`. Shared by\n * every refusal path (the `StoreView` read-only / current-only / search facades\n * and the sealed-query builder) so they describe a coordinate identically — and\n * a future axis (recorded time) is reflected everywhere from one place.\n */\nexport function describeCoordinate(coordinate: ReadCoordinate): string {\n  const { mode, asOf } = coordinate.valid;\n  const valid =\n    asOf === undefined ? `mode \"${mode}\"` : `mode \"${mode}\" asOf ${asOf}`;\n  return coordinate.recorded === undefined ?\n      valid\n    : `${valid}, recorded asOf ${coordinate.recorded.asOf}`;\n}\n\n/**\n * The structured error-context fields describing a coordinate, shared by the\n * same refusal paths as {@link describeCoordinate}.\n */\nexport function coordinateContext(\n  coordinate: ReadCoordinate,\n): Record<string, unknown> {\n  const { mode, asOf } = coordinate.valid;\n  return {\n    temporalMode: mode,\n    ...(asOf !== undefined && { asOf }),\n    ...(coordinate.recorded === undefined ?\n      {}\n    : { recordedAsOf: coordinate.recorded.asOf }),\n  };\n}\n"]}

package/dist/{chunk-775A4ZMN.js → chunk-5ZJOB5YS.js}

@@ -1,6 +1,6 @@
-import { assertWhereFieldDeclared } from './chunk-WDGA7IYB.js';
+import { assertWhereFieldDeclared } from './chunk-LNIWCQR4.js';
 import { getEmbeddingIndex, isEmbeddingSchema } from './chunk-PC2UBAUB.js';
-import { ConfigurationError, ValidationError } from './chunk-J3WZ3FA2.js';
+import { ConfigurationError, ValidationError } from './chunk-62ZXBMSD.js';
 import { createDataKeyedBag } from './chunk-DYATYRY4.js';
 
 // src/core/types.ts
@@ -307,5 +307,5 @@ function isKnownKind(graph, name) {
 }
 
 export { EDGE_TYPE_BRAND, NODE_TYPE_BRAND, asEdgeId, asNodeId, autoDeriveVectorIndexes, defineGraph, defineInternalGraph, getEdgeKinds, getNodeKinds, isEdgeType, isEdgeTypeWithEndpoints, isGraphDef, isKnownKind, isNodeType, mergeVectorIndexes };
-//# sourceMappingURL=chunk-775A4ZMN.js.map
-//# sourceMappingURL=chunk-775A4ZMN.js.map
+//# sourceMappingURL=chunk-5ZJOB5YS.js.map
+//# sourceMappingURL=chunk-5ZJOB5YS.js.map

package/dist/{chunk-775A4ZMN.js.map → chunk-5ZJOB5YS.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/types.ts","../src/indexes/auto-derive.ts","../src/core/define-graph.ts"],"names":[],"mappings":"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","file":"chunk-775A4ZMN.js","sourcesContent":["import { type z } from \"zod\";\n\nimport { ValidationError } from \"../errors\";\n\n// ============================================================\n// Cross-cutting Discriminators\n// ============================================================\n\n/**\n * Which side of the bipartite graph a kind lives on. Used everywhere a\n * function takes \"the entity that owns a kind\" — error metadata,\n * extension classifiers, removal queues, schema diffs.\n */\nexport type KindEntity = \"node\" | \"edge\";\n\n/**\n * Which physical surface an index targets. Vector indexes don't own a\n * kind directly (they back a per-`(kind, field)` typed embedding table\n * owned by the active `VectorStrategy`), but they participate in the same\n * materialization and diff pipelines, so they share this discriminator.\n *\n * `\"system\"` marks TypeGraph's own base-relation indexes\n * (`SYSTEM_INDEX_DECLARATIONS`) — graph-independent, but materialized and\n * status-tracked through the same pipeline; their status rows carry the\n * relation key (e.g. `\"recordedNodes\"`) in the `kind` column.\n */\nexport type IndexEntity = \"node\" | \"edge\" | \"vector\" | \"system\";\n\n/**\n * Field-level null-check operations that round-trip through persisted\n * documents (unique-constraint where clauses, index where clauses,\n * graph-extension where clauses, IsNullPredicate). Consolidated so a\n * single rename or extension touches one site.\n */\nexport type NullCheckOp = \"isNull\" | \"isNotNull\";\n\n// ============================================================\n// Brand Keys for Nominal Typing\n// ============================================================\n\n/** Brand key for NodeType */\nexport const NODE_TYPE_BRAND = \"__nodeType\" as const;\n\n/** Brand key for EdgeType */\nexport const EDGE_TYPE_BRAND = \"__edgeType\" as const;\n\n/** Brand symbol for NodeId */\ndeclare const __nodeId: unique symbol;\n\n/** Brand symbol for EdgeId */\ndeclare const __edgeId: unique symbol;\n\nfunction assertNonEmptyId(value: string, path: string): void {\n  if (value.length > 0) {\n    return;\n  }\n\n  throw new ValidationError(\n    `${path} must be a non-empty string.`,\n    {\n      issues: [\n        {\n          path,\n          message: \"Expected a non-empty string.\",\n        },\n      ],\n    },\n    {\n      suggestion:\n        \"Use a persisted node or edge id value, or let TypeGraph generate an id on create.\",\n    },\n  );\n}\n\n// ============================================================\n// Node Type\n// ============================================================\n\n/**\n * Any JSON-serializable value.\n *\n * Mirrors the JSON wire format: primitives, arrays, and string-keyed objects.\n * `null` is included because the JSON spec requires it for \"no value here\";\n * this is the one place in the public API that uses `null` over `undefined`.\n */\nexport type JsonValue =\n  | null\n  | string\n  | number\n  | boolean\n  | readonly JsonValue[]\n  | Readonly<{ [key: string]: JsonValue }>;\n\n/**\n * Consumer-owned per-kind annotations.\n *\n * Stable labels attached to a node or edge kind at definition time — UI hints,\n * audit policy, provenance pointers, tooling annotations.\n *\n * **Consumer-owned, fully.** TypeGraph never reads, validates, or interprets\n * values in this field. Consumers own the entire namespace; there are no\n * reserved keys or extension prefixes. Future library-owned per-kind state,\n * if needed, will use a separate sibling field rather than carving out keys\n * here.\n *\n * **Annotations participate in schema hashing.** Any change to an annotation\n * value (or adding/removing an annotation key) bumps the canonical schema\n * hash and is reported as a `safe`-severity diff by `getSchemaChanges`. If\n * you don't want versioning for a piece of state, do not put it here.\n *\n * Values must be JSON-serializable — `bigint`, `function`, `symbol`, `undefined`,\n * `Date`, and other class instances are rejected at definition time so they can\n * never silently break schema hashing or storage round-trips.\n */\nexport type KindAnnotations = Readonly<Record<string, JsonValue>>;\n\n/**\n * A node type definition.\n *\n * Created via `defineNode()`. Represents a type of node in the graph\n * with an associated Zod schema for properties.\n */\nexport type NodeType<\n  K extends string = string,\n  S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>,\n> = Readonly<{\n  [NODE_TYPE_BRAND]: true;\n  kind: K;\n  schema: S;\n  description: string | undefined;\n  annotations: KindAnnotations | undefined;\n}>;\n\n/**\n * Branded node ID type.\n *\n * Prevents mixing IDs from different node types at compile time.\n */\nexport type NodeId<N extends NodeType> = string &\n  Readonly<{\n    [__nodeId]: N;\n  }>;\n\n/**\n * Brands a non-empty string as a {@link NodeId}.\n *\n * Use this when a persisted node id has round-tripped through untyped storage\n * or an external boundary and must be passed back to read/update/delete\n * surfaces such as `getById`, `getByIds`, `update`, or `delete`.\n * Write surfaces that mint or claim ids, such as `create({ id })` and\n * `upsertById`, intentionally accept plain strings.\n *\n * @throws {ValidationError} when `value` is empty.\n */\nexport function asNodeId<N extends NodeType = NodeType>(\n  value: string,\n): NodeId<N> {\n  assertNonEmptyId(value, \"asNodeId\");\n  return value as NodeId<N>;\n}\n\n/**\n * Infer the props type from a NodeType.\n */\nexport type NodeProps<N extends NodeType> = z.infer<N[\"schema\"]>;\n\n// ============================================================\n// Edge Type\n// ============================================================\n\n/**\n * An edge type definition.\n *\n * Created via `defineEdge()`. Represents a type of edge in the graph\n * with an optional Zod schema for properties.\n *\n * Optionally includes `from` and `to` arrays that define the allowed\n * source and target node types (domain and range constraints).\n */\nexport type EdgeType<\n  K extends string = string,\n  S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>,\n  From extends readonly NodeType[] | undefined = undefined,\n  To extends readonly NodeType[] | undefined = undefined,\n> = Readonly<{\n  [EDGE_TYPE_BRAND]: true;\n  kind: K;\n  schema: S;\n  description: string | undefined;\n  annotations: KindAnnotations | undefined;\n  from: From;\n  to: To;\n}>;\n\n/**\n * Base edge type for use in constraints - accepts any from/to configuration.\n */\nexport type AnyEdgeType = EdgeType<\n  string,\n  z.ZodObject<z.ZodRawShape>,\n  readonly NodeType[] | undefined,\n  readonly NodeType[] | undefined\n>;\n\n/**\n * An edge type that has both from and to constraints defined.\n * Can be used directly in defineGraph without an EdgeRegistration wrapper.\n */\nexport type EdgeTypeWithEndpoints = EdgeType<\n  string,\n  z.ZodObject<z.ZodRawShape>,\n  readonly NodeType[],\n  readonly NodeType[]\n>;\n\n/**\n * Branded edge ID type.\n *\n * Prevents mixing IDs from different edge types at compile time.\n */\nexport type EdgeId<E extends AnyEdgeType = AnyEdgeType> = string &\n  Readonly<{\n    [__edgeId]: E;\n  }>;\n\n/**\n * Brands a non-empty string as an {@link EdgeId}.\n *\n * Use this when a persisted edge id has round-tripped through untyped storage\n * or an external boundary and must be passed back to read/update/delete\n * surfaces such as `getById`, `getByIds`, `update`, or `delete`.\n * Write surfaces that mint ids intentionally accept plain strings.\n *\n * @throws {ValidationError} when `value` is empty.\n */\nexport function asEdgeId<E extends AnyEdgeType = AnyEdgeType>(\n  value: string,\n): EdgeId<E> {\n  assertNonEmptyId(value, \"asEdgeId\");\n  return value as EdgeId<E>;\n}\n\n/**\n * Infer the props type from an EdgeType.\n */\nexport type EdgeProps<E extends AnyEdgeType> = z.infer<E[\"schema\"]>;\n\n// ============================================================\n// Configuration Types\n// ============================================================\n\n/**\n * Delete behaviors for nodes.\n */\nexport type DeleteBehavior = \"restrict\" | \"cascade\" | \"disconnect\";\n\n/**\n * Edge cardinality constraints.\n */\nexport type Cardinality =\n  | \"many\" // No constraint (default)\n  | \"one\" // At most one edge of this kind from any source node\n  | \"unique\" // At most one edge of this kind between any (source, target) pair\n  | \"oneActive\"; // At most one edge with valid_to IS NULL from any source\n\n/**\n * Endpoint existence modes for edge validation.\n */\nexport type EndpointExistence =\n  | \"notDeleted\" // Endpoint deleted_at IS NULL (default)\n  | \"currentlyValid\" // Endpoint not deleted AND temporally valid\n  | \"ever\"; // Endpoint exists in any state\n\n/**\n * Temporal query modes.\n */\nexport type TemporalMode =\n  | \"current\" // Valid now AND not deleted\n  | \"asOf\" // Valid at specific date AND not deleted\n  | \"includeEnded\" // All validity periods AND not deleted\n  | \"includeTombstones\"; // Everything including soft-deleted\n\n/**\n * Uniqueness constraint scope.\n */\nexport type UniquenessScope =\n  | \"kind\" // Unique within this exact kind only\n  | \"kindWithSubClasses\"; // Unique across this kind and all subclasses\n\n/**\n * Collation for uniqueness constraints.\n */\nexport type Collation = \"binary\" | \"caseInsensitive\";\n\n// ============================================================\n// Uniqueness Constraint\n// ============================================================\n\n/**\n * Uniqueness constraint definition.\n */\nexport type UniqueConstraint<\n  S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>,\n> = Readonly<{\n  name: string;\n  fields: readonly (keyof z.infer<S> & string)[];\n  where?: (\n    props: UniqueConstraintPredicateBuilder<S>,\n  ) => UniqueConstraintPredicate;\n  scope: UniquenessScope;\n  collation: Collation;\n}>;\n\n/**\n * Predicate builder for uniqueness constraint where clause.\n * Uses -? to make all fields required in the builder, even if optional in the schema.\n */\ntype UniqueConstraintPredicateBuilder<S extends z.ZodObject<z.ZodRawShape>> =\n  Readonly<{\n    [K in keyof z.infer<S>]-?: UniqueConstraintField;\n  }>;\n\n/**\n * Field operations for uniqueness constraint predicates.\n */\ntype UniqueConstraintField = Readonly<{\n  isNull: () => UniqueConstraintPredicate;\n  isNotNull: () => UniqueConstraintPredicate;\n}>;\n\n/**\n * A uniqueness constraint predicate (internal representation).\n */\ntype UniqueConstraintPredicate = Readonly<{\n  __type: \"unique_predicate\";\n  field: string;\n  op: NullCheckOp;\n}>;\n\n// ============================================================\n// Node Registration\n// ============================================================\n\n/**\n * Node registration in a graph definition.\n */\nexport type NodeRegistration<N extends NodeType = NodeType> = Readonly<{\n  type: N;\n  unique?: readonly UniqueConstraint<N[\"schema\"]>[];\n  onDelete?: DeleteBehavior;\n}>;\n\n// ============================================================\n// Edge Registration\n// ============================================================\n\n/**\n * Edge registration in a graph definition.\n */\nexport type EdgeRegistration<\n  E extends AnyEdgeType = AnyEdgeType,\n  FromTypes extends NodeType = NodeType,\n  ToTypes extends NodeType = NodeType,\n> = Readonly<{\n  type: E;\n  from: readonly FromTypes[];\n  to: readonly ToTypes[];\n  cardinality?: Cardinality;\n  endpointExistence?: EndpointExistence;\n}>;\n\n// ============================================================\n// Graph Defaults\n// ============================================================\n\n/**\n * Default settings for a graph.\n */\nexport type GraphDefaults = Readonly<{\n  onNodeDelete?: DeleteBehavior;\n  temporalMode?: TemporalMode;\n}>;\n\n// ============================================================\n// Type Helpers\n// ============================================================\n\n/**\n * Checks if a value is a NodeType.\n */\nexport function isNodeType(value: unknown): value is NodeType {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    NODE_TYPE_BRAND in value &&\n    (value as Record<string, unknown>)[NODE_TYPE_BRAND] === true\n  );\n}\n\n/**\n * Checks if a value is an EdgeType.\n */\nexport function isEdgeType(value: unknown): value is AnyEdgeType {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    EDGE_TYPE_BRAND in value &&\n    (value as Record<string, unknown>)[EDGE_TYPE_BRAND] === true\n  );\n}\n\n/**\n * Checks if a value is an EdgeType with both from and to constraints defined.\n * Such edges can be used directly in defineGraph without an EdgeRegistration wrapper.\n */\nexport function isEdgeTypeWithEndpoints(\n  value: unknown,\n): value is EdgeTypeWithEndpoints {\n  return (\n    isEdgeType(value) &&\n    Array.isArray(value.from) &&\n    value.from.length > 0 &&\n    Array.isArray(value.to) &&\n    value.to.length > 0\n  );\n}\n","/**\n * Auto-derive vector index declarations from `embedding()` brands on\n * node schemas.\n *\n * Walks each node's top-level Zod shape, finds fields wrapped in\n * `embedding(dimensions, opts)` (including `.optional()` /\n * `.nullable()` wrappers), and emits one `VectorIndexDeclaration` per\n * (kind, field) pair. The declaration carries the resolved index\n * configuration from the embedding brand — metric, indexType, HNSW /\n * IVFFlat params — so the materializer doesn't need to reach back into\n * the Zod schema.\n *\n * Auto-derivation is intentionally limited to TOP-LEVEL embedding\n * fields. Embeddings nested inside object properties are out of scope\n * for v1 — vector slots are materialized as flat `(kind, fieldPath)`\n * storage units, and top-level fields keep that contract explicit.\n *\n * Explicit `defineVectorIndex(node, fieldPath, opts)` declarations\n * passed via `defineGraph({ indexes })` take precedence — when an\n * explicit declaration matches the same (kind, fieldPath) as an\n * auto-derived one, the explicit version wins. This lets consumers\n * override defaults without losing auto-derivation for other fields.\n */\n\nimport { type z } from \"zod\";\n\nimport {\n  getEmbeddingIndex,\n  isEmbeddingSchema,\n  type ResolvedEmbeddingIndex,\n} from \"../core/embedding\";\nimport { type NodeRegistration } from \"../core/types\";\nimport { type IndexDeclaration, type VectorIndexDeclaration } from \"./types\";\n\n/**\n * Auto-derive vector index declarations from embedding brands on a\n * map of node registrations. Returns one declaration per\n * (kind, top-level field) pair. Empty array when no embeddings found.\n *\n * Cross-graph status-table disambiguation does NOT happen here — the\n * declaration name stays clean (`tg_vec_{kind}_{field}_{metric}`) so\n * `pg_indexes` and result-entry inspection are readable. The\n * materializer composes a graph-scoped key (`${graphId}::${name}`)\n * for status-table identity, applied uniformly to both auto-derived\n * and explicit `VectorIndexDeclaration` entries — see\n * `vectorStatusKey` in `store/materialize-indexes.ts`. This keeps\n * the disambiguation rule in one place that BOTH paths go through,\n * rather than depending on the auto-derive caller to produce a\n * graph-scoped name.\n */\nexport function autoDeriveVectorIndexes(\n  nodes: Record<string, NodeRegistration>,\n): readonly VectorIndexDeclaration[] {\n  const out: VectorIndexDeclaration[] = [];\n  for (const registration of Object.values(nodes)) {\n    const node = registration.type;\n    const shape = readObjectShape(node.schema);\n    if (shape === undefined) continue;\n    for (const [fieldName, fieldSchema] of Object.entries(shape)) {\n      const config = readEmbeddingIndex(fieldSchema);\n      if (config === undefined) continue;\n      const dimensions = readEmbeddingDimensions(fieldSchema);\n      if (dimensions === undefined) continue;\n      out.push(buildAutoDerived(node.kind, fieldName, dimensions, config));\n    }\n  }\n  return out;\n}\n\n/**\n * Merge auto-derived declarations with explicit ones, preferring\n * explicit on (kind, fieldPath) collisions. Returns a flat list of all\n * indexes; non-vector entries from `explicit` pass through unchanged.\n */\nexport function mergeVectorIndexes(\n  explicit: readonly IndexDeclaration[],\n  autoDerived: readonly VectorIndexDeclaration[],\n): readonly IndexDeclaration[] {\n  if (autoDerived.length === 0) return explicit;\n  const explicitVectorKeys = new Set<string>();\n  for (const declaration of explicit) {\n    if (declaration.entity === \"vector\") {\n      explicitVectorKeys.add(`${declaration.kind}|${declaration.fieldPath}`);\n    }\n  }\n  const filteredAuto = autoDerived.filter(\n    (entry) => !explicitVectorKeys.has(`${entry.kind}|${entry.fieldPath}`),\n  );\n  return [...explicit, ...filteredAuto];\n}\n\n/**\n * Generate the deterministic vector index name. The visible prefix\n * `tg_vec_<kind>_<field>_<metric>` keeps it scannable in result-entry\n * inspection and the `typegraph_index_materializations` table.\n *\n * Cross-graph disambiguation is handled separately at the\n * materialization boundary (see `vectorStatusKey`) so the declaration\n * name doesn't need to carry `graphId` — the same auto-derived name\n * is reusable across graphs and the materializer composes a\n * graph-scoped status key for both auto-derived and explicit entries\n * uniformly.\n */\nfunction buildAutoDerived(\n  kind: string,\n  fieldName: string,\n  dimensions: number,\n  config: ResolvedEmbeddingIndex,\n): VectorIndexDeclaration {\n  const fieldPath = fieldName;\n  return Object.freeze({\n    entity: \"vector\" as const,\n    name: `tg_vec_${sanitize(kind)}_${sanitize(fieldName)}_${config.metric}`,\n    kind,\n    fieldPath,\n    dimensions,\n    metric: config.metric,\n    indexType: config.indexType,\n    indexParams: Object.freeze({\n      m: config.m,\n      efConstruction: config.efConstruction,\n      lists: config.lists,\n    }),\n  });\n}\n\nfunction sanitize(value: string): string {\n  return value.replaceAll(/[^a-zA-Z0-9]/g, \"_\").toLowerCase();\n}\n\nfunction readObjectShape(\n  schema: z.ZodType,\n): Record<string, z.ZodType> | undefined {\n  if ((schema as { type?: string }).type !== \"object\") return undefined;\n  const shape = (schema.def as { shape?: Record<string, z.ZodType> }).shape;\n  return shape;\n}\n\nfunction readEmbeddingIndex(\n  schema: z.ZodType,\n): ResolvedEmbeddingIndex | undefined {\n  for (const candidate of unwrapChain(schema)) {\n    const config = getEmbeddingIndex(candidate);\n    if (config !== undefined) return config;\n  }\n  return undefined;\n}\n\nfunction readEmbeddingDimensions(schema: z.ZodType): number | undefined {\n  for (const candidate of unwrapChain(schema)) {\n    if (isEmbeddingSchema(candidate)) {\n      return (candidate as unknown as Record<string, number>)[\n        \"_embeddingDimensions\"\n      ];\n    }\n  }\n  return undefined;\n}\n\n/**\n * Yield the schema and every reachable inner schema by repeatedly\n * applying `.unwrap()` (Zod 4 optional/nullable/default) and\n * `.def.innerType` (some wrappers). Cycle-guarded by depth and\n * reference identity. Generators stop at the first non-unwrappable\n * schema OR after 8 levels — deeper wrapping is pathological and not\n * worth supporting.\n */\nfunction* unwrapChain(schema: z.ZodType): Generator<z.ZodType, void, void> {\n  const seen = new Set<z.ZodType>();\n  let current: z.ZodType | undefined = schema;\n  let depth = 0;\n  while (current !== undefined && !seen.has(current) && depth < 8) {\n    seen.add(current);\n    yield current;\n    current = unwrapOnce(current);\n    depth++;\n  }\n}\n\nfunction unwrapOnce(schema: z.ZodType): z.ZodType | undefined {\n  // Zod 4 wrappers expose `.unwrap()` on optional/nullable/default.\n  const candidate = schema as unknown as { unwrap?: () => z.ZodType };\n  if (typeof candidate.unwrap === \"function\") return candidate.unwrap();\n  // Some wrappers expose the inner schema via `.def.innerType`.\n  return (schema as unknown as { def?: { innerType?: z.ZodType } }).def\n    ?.innerType;\n}\n","import { assertWhereFieldDeclared } from \"../constraints\";\nimport { ConfigurationError } from \"../errors/index\";\nimport { type GraphExtension } from \"../graph-extension/extension-types\";\nimport {\n  autoDeriveVectorIndexes,\n  mergeVectorIndexes,\n} from \"../indexes/auto-derive\";\nimport { type IndexDeclaration } from \"../indexes/types\";\nimport { type OntologyRelation } from \"../ontology/types\";\nimport { createDataKeyedBag } from \"../utils/object\";\nimport {\n  type AnyEdgeType,\n  type DeleteBehavior,\n  type EdgeRegistration,\n  type EdgeTypeWithEndpoints,\n  type GraphDefaults,\n  isEdgeType,\n  isEdgeTypeWithEndpoints,\n  type KindEntity,\n  type NodeRegistration,\n  type NodeType,\n  type TemporalMode,\n} from \"./types\";\n\n// ============================================================\n// Graph Definition Brand Symbol\n// ============================================================\n\n/** Brand key for GraphDef */\nconst GRAPH_DEF_BRAND = \"__graphDef\" as const;\n\n// ============================================================\n// Edge Entry Types\n// ============================================================\n\n/**\n * An edge entry in the graph definition.\n * Can be:\n * - EdgeType directly (constrained or unconstrained)\n * - EdgeRegistration object (always works, can override/narrow defaults)\n */\ntype EdgeEntry = EdgeRegistration | AnyEdgeType;\n\n/**\n * Normalized edge map type - all entries become EdgeRegistration.\n * For bare EdgeTypes, constrained endpoints are extracted from the type;\n * unconstrained edges fall back to all node types in the graph.\n */\ntype NormalizedEdges<\n  TNodes extends Record<string, NodeRegistration>,\n  TEdges extends Record<string, EdgeEntry>,\n> = {\n  [K in keyof TEdges]: TEdges[K] extends EdgeRegistration ? TEdges[K]\n  : TEdges[K] extends AnyEdgeType ?\n    EdgeRegistration<\n      TEdges[K],\n      TEdges[K][\"from\"] extends readonly (infer N extends NodeType)[] ? N\n      : TNodes[keyof TNodes][\"type\"],\n      TEdges[K][\"to\"] extends readonly (infer N extends NodeType)[] ? N\n      : TNodes[keyof TNodes][\"type\"]\n    >\n  : never;\n};\n\n// ============================================================\n// Edge Normalization Functions\n// ============================================================\n\n/**\n * Validates that an EdgeRegistration's constraints don't widen beyond\n * the edge type's built-in domain/range constraints.\n */\nfunction validateConstraintNarrowing(\n  name: string,\n  edgeType: EdgeTypeWithEndpoints,\n  registration: EdgeRegistration,\n): void {\n  const builtInFromNames = new Set(edgeType.from.map((node) => node.kind));\n  for (const fromNode of registration.from) {\n    if (!builtInFromNames.has(fromNode.kind)) {\n      throw new ConfigurationError(\n        `Edge \"${name}\" registration has 'from' kind \"${fromNode.kind}\" ` +\n          `not in edge's built-in domain: [${[...builtInFromNames].join(\", \")}]`,\n        {\n          edgeName: name,\n          invalidFrom: fromNode.kind,\n          allowedFrom: [...builtInFromNames],\n        },\n        {\n          suggestion: `Edge registration can only narrow, not widen, the edge type's built-in constraints.`,\n        },\n      );\n    }\n  }\n\n  const builtInToNames = new Set(edgeType.to.map((node) => node.kind));\n  for (const toNode of registration.to) {\n    if (!builtInToNames.has(toNode.kind)) {\n      throw new ConfigurationError(\n        `Edge \"${name}\" registration has 'to' kind \"${toNode.kind}\" ` +\n          `not in edge's built-in range: [${[...builtInToNames].join(\", \")}]`,\n        {\n          edgeName: name,\n          invalidTo: toNode.kind,\n          allowedTo: [...builtInToNames],\n        },\n        {\n          suggestion: `Edge registration can only narrow, not widen, the edge type's built-in constraints.`,\n        },\n      );\n    }\n  }\n}\n\n/**\n * Normalizes a single edge entry to EdgeRegistration.\n */\nfunction normalizeEdgeEntry(\n  name: string,\n  entry: EdgeEntry,\n  allNodeTypes: readonly NodeType[],\n): EdgeRegistration {\n  if (isEdgeType(entry)) {\n    if (isEdgeTypeWithEndpoints(entry)) {\n      // EdgeType with from/to — convert to EdgeRegistration\n      return { type: entry, from: entry.from, to: entry.to };\n    }\n    // Unconstrained EdgeType — allow any→any\n    return { type: entry, from: allNodeTypes, to: allNodeTypes };\n  }\n\n  // Already EdgeRegistration — validate narrowing if edge has built-in constraints\n  if (isEdgeTypeWithEndpoints(entry.type)) {\n    validateConstraintNarrowing(name, entry.type, entry);\n  }\n\n  return entry;\n}\n\n/**\n * Normalizes all edge entries to EdgeRegistration.\n *\n * The accumulator is a {@link createDataKeyedBag}: its keys are EDGE KIND\n * NAMES, which are data. `isValidKindName` admits `__proto__` exactly as it\n * admits `toString`, and a graph literal written with a computed key\n * (`edges: { [\"__proto__\"]: knows }`) carries it as an own key — so\n * `result[name] = …` into a `{}` literal would reach `Object.prototype`'s\n * `__proto__` setter, reparent the accumulator, and drop the declared edge.\n * `config.nodes` needs no such treatment: it is passed through by reference,\n * never re-accumulated.\n */\nfunction normalizeEdges(\n  edges: Record<string, EdgeEntry>,\n  allNodeTypes: readonly NodeType[],\n): Record<string, EdgeRegistration> {\n  const result = createDataKeyedBag<EdgeRegistration>();\n  for (const [name, entry] of Object.entries(edges)) {\n    result[name] = normalizeEdgeEntry(name, entry, allNodeTypes);\n  }\n  // Spread at the boundary: this becomes `graph.edges` on the returned (and\n  // publicly reachable) `GraphDef`. See `createDataKeyedBag` in\n  // ../utils/object.ts.\n  return { ...result };\n}\n\n// ============================================================\n// Graph Definition Configuration\n// ============================================================\n\n/** Durable graph-level configuration for the TypeGraph Identity Profile. */\nexport type GraphIdentityConfig = Readonly<{\n  /** Whether equal ids in different kinds implicitly join one identity class. */\n  sameIdAcrossKinds: \"fold\" | \"ignore\";\n}>;\n\n/**\n * Configuration for defineGraph.\n */\ntype GraphDefConfig<\n  TNodes extends Record<string, NodeRegistration>,\n  TEdges extends Record<string, EdgeEntry>,\n  TOntology extends readonly OntologyRelation[],\n  TIdentity extends GraphIdentityConfig | undefined,\n> = Readonly<{\n  /** Unique identifier for this graph */\n  id: string;\n  /** Node registrations */\n  nodes: TNodes;\n  /** Edge registrations or EdgeTypes with built-in domain/range */\n  edges: TEdges;\n  /** Ontology relations */\n  ontology?: TOntology;\n  /** Graph-wide defaults */\n  defaults?: GraphDefaults;\n  /** Enables the TypeGraph Identity Profile for this graph. */\n  identity?: TIdentity;\n  /**\n   * Index declarations attached to this graph.\n   *\n   * Accepts the outputs of `defineNodeIndex` / `defineEdgeIndex` (which\n   * already return `IndexDeclaration` values) or pre-built declarations\n   * reconstructed from a stored schema or graph extension.\n   *\n   * Validated at definition time: every index must reference a `kind`\n   * that exists in `nodes` / `edges`, and index `name`s must be unique\n   * within the graph.\n   *\n   * Index DDL is **not** generated by `defineGraph`. Indexes flow into\n   * `SerializedSchema.indexes` so they can later be materialized via\n   * `store.materializeIndexes()` — lifting the storage concern out of\n   * the schema-version commit path.\n   */\n  indexes?: readonly IndexDeclaration[];\n}>;\n\n// ============================================================\n// Graph Definition Type\n// ============================================================\n\n/**\n * A graph definition.\n *\n * This is a compile-time artifact that describes the structure of a graph.\n * Use `createStore()` to create a runtime store from this definition.\n */\nexport type GraphDef<\n  TNodes extends Record<string, NodeRegistration> = Record<\n    string,\n    NodeRegistration\n  >,\n  TEdges extends Record<string, EdgeRegistration> = Record<\n    string,\n    EdgeRegistration\n  >,\n  TOntology extends readonly OntologyRelation[] = readonly OntologyRelation[],\n  TIdentity extends GraphIdentityConfig | undefined =\n    GraphIdentityConfig | undefined,\n> = Readonly<{\n  [GRAPH_DEF_BRAND]: true;\n  id: string;\n  nodes: TNodes;\n  edges: TEdges;\n  ontology: TOntology;\n  /** Durable graph-level opt-in to the TypeGraph Identity Profile. */\n  identity: TIdentity;\n  defaults: Readonly<{\n    onNodeDelete: DeleteBehavior;\n    temporalMode: TemporalMode;\n  }>;\n  /**\n   * Index declarations attached to this graph. Preserves whatever the\n   * caller passed to `defineGraph` (including an explicit empty array)\n   * for introspection purposes.\n   *\n   * The serialized canonical form is order-canonicalized (sorted by\n   * `name`) and treats `undefined` and `[]` as the same \"no slice\" form\n   * — an empty array does not bump the schema hash, since indexes are\n   * an unordered set keyed by name and `[]` carries no semantic meaning\n   * that an absent slice doesn't.\n   */\n  indexes: readonly IndexDeclaration[] | undefined;\n  /**\n   * Graph extension this graph was merged with, if any. Set by\n   * `mergeGraphExtension`; never set by `defineGraph` directly.\n   * Exists solely so re-serialization is stable — the rest of the\n   * system reads the merged kinds through `nodes` / `edges` /\n   * `ontology` and never inspects this field. Absent on graphs that\n   * have never been extended; legacy graphs hash byte-identically.\n   */\n  extension: GraphExtension | undefined;\n  /**\n   * Soft-deprecated kind names attached to this graph. Set by the\n   * loader from the persisted schema and by `store.deprecateKinds(...)`\n   * / `store.undeprecateKinds(...)`. A purely informational signal\n   * surfaced for introspection — does not gate reads, writes, or\n   * queries. Defaults to the empty set on freshly-defined graphs.\n   */\n  deprecatedKinds: ReadonlySet<string>;\n}>;\n\n// ============================================================\n// Type Helpers\n// ============================================================\n\n/**\n * Extract node kind names from a GraphDef.\n */\nexport type NodeKinds<G extends GraphDef> = keyof G[\"nodes\"] & string;\n\n/**\n * Extract edge kind names from a GraphDef.\n */\nexport type EdgeKinds<G extends GraphDef> = keyof G[\"edges\"] & string;\n\n/**\n * Get a NodeType from a GraphDef by kind name.\n */\nexport type GetNodeType<\n  G extends GraphDef,\n  K extends NodeKinds<G>,\n> = G[\"nodes\"][K][\"type\"];\n\n/**\n * Get an EdgeType from a GraphDef by kind name.\n */\nexport type GetEdgeType<\n  G extends GraphDef,\n  K extends EdgeKinds<G>,\n> = G[\"edges\"][K][\"type\"];\n\n/**\n * Get all NodeTypes from a GraphDef.\n */\nexport type AllNodeTypes<G extends GraphDef> = {\n  [K in NodeKinds<G>]: G[\"nodes\"][K][\"type\"];\n}[NodeKinds<G>];\n\n/**\n * Get all EdgeTypes from a GraphDef.\n */\nexport type AllEdgeTypes<G extends GraphDef> = {\n  [K in EdgeKinds<G>]: G[\"edges\"][K][\"type\"];\n}[EdgeKinds<G>];\n\n// ============================================================\n// Define Graph Function\n// ============================================================\n\n/**\n * Creates a graph definition.\n *\n * @example\n * ```typescript\n * const graph = defineGraph({\n *   id: \"my_graph\",\n *   nodes: {\n *     Person: { type: Person },\n *     Company: { type: Company },\n *   },\n *   edges: {\n *     // Traditional EdgeRegistration syntax\n *     worksAt: {\n *       type: worksAt,\n *       from: [Person],\n *       to: [Company],\n *       cardinality: \"many\",\n *     },\n *     // Or use EdgeType directly if it has from/to defined\n *     knows,  // EdgeType with built-in domain/range\n *   },\n *   ontology: [\n *     subClassOf(Company, Organization),\n *     disjointWith(Person, Organization),\n *   ],\n *   defaults: {\n *     onNodeDelete: \"restrict\",\n *     temporalMode: \"current\",\n *   },\n * });\n * ```\n */\nexport function defineGraph<\n  const TNodes extends Record<string, NodeRegistration<NodeType>>,\n  const TEdges extends Record<string, EdgeEntry>,\n  const TOntology extends readonly OntologyRelation[],\n  const TIdentity extends GraphIdentityConfig | undefined = undefined,\n>(\n  config: GraphDefConfig<TNodes, TEdges, TOntology, TIdentity>,\n): GraphDef<TNodes, NormalizedEdges<TNodes, TEdges>, TOntology, TIdentity> {\n  return defineGraphUnchecked(config);\n}\n\nfunction defineGraphUnchecked<\n  const TNodes extends Record<string, NodeRegistration<NodeType>>,\n  const TEdges extends Record<string, EdgeEntry>,\n  const TOntology extends readonly OntologyRelation[],\n  const TIdentity extends GraphIdentityConfig | undefined = undefined,\n>(\n  config: GraphDefConfig<TNodes, TEdges, TOntology, TIdentity>,\n): GraphDef<TNodes, NormalizedEdges<TNodes, TEdges>, TOntology, TIdentity> {\n  const defaults = {\n    onNodeDelete: config.defaults?.onNodeDelete ?? \"restrict\",\n    temporalMode: config.defaults?.temporalMode ?? \"current\",\n  } as const;\n\n  const allNodeTypes = Object.values(config.nodes).map((reg) => reg.type);\n  const normalizedEdges = normalizeEdges(config.edges, allNodeTypes);\n  assertUniqueConstraintsAreDeclared(config.nodes);\n  // Vector indexes are auto-derived from `embedding()` brands on node\n  // schemas (see `autoDeriveVectorIndexes`). Explicit declarations\n  // passed via `defineGraph({ indexes })` win on (kind, fieldPath)\n  // collisions so consumers can override defaults — see\n  // `mergeVectorIndexes`. The merged list flows through\n  // `normalizeIndexes` for the standard kind-registered + unique-name\n  // checks.\n  //\n  // Preservation rule: if the consumer never passed `indexes` at all\n  // AND no embedding brands exist, leave `graph.indexes` undefined to\n  // keep the introspection surface stable for legacy graphs. If the\n  // consumer passed an explicit `[]`, surface it as `[]` (not\n  // `undefined`) to match the contract pinned by the\n  // \"preserves an explicit empty indexes array\" test.\n  const autoVectorIndexes = autoDeriveVectorIndexes(config.nodes);\n  const explicitProvided = config.indexes !== undefined;\n  const mergedIndexes = mergeVectorIndexes(\n    config.indexes ?? [],\n    autoVectorIndexes,\n  );\n  const indexes =\n    !explicitProvided && mergedIndexes.length === 0 ?\n      undefined\n    : normalizeIndexes(mergedIndexes, config.nodes, normalizedEdges);\n\n  return Object.freeze({\n    [GRAPH_DEF_BRAND]: true as const,\n    id: config.id,\n    nodes: config.nodes,\n    edges: normalizedEdges,\n    ontology: config.ontology ?? ([] as unknown as TOntology),\n    identity: config.identity as TIdentity,\n    defaults,\n    indexes,\n    extension: undefined,\n    deprecatedKinds: EMPTY_DEPRECATED_KINDS,\n  }) as GraphDef<TNodes, NormalizedEdges<TNodes, TEdges>, TOntology, TIdentity>;\n}\n\n/**\n * @internal Marks a graph definition as framework-owned rather than\n * application-authored.\n *\n * It builds exactly what {@link defineGraph} builds — the name records the\n * caller, it does not reserve anything. There is NO reserved id namespace and\n * no id validation anywhere: an application may define a graph at any id a\n * framework-owned graph uses, the merge-provenance sidecar's\n * `<target>::merge-provenance` convention included. That convention is\n * protected at RUNTIME instead, by the ownership checks in the single gateway\n * that opens a sidecar (`openProvenanceStore`), which refuses an id occupied by\n * anything it cannot prove it owns.\n */\nexport function defineInternalGraph<\n  const TNodes extends Record<string, NodeRegistration<NodeType>>,\n  const TEdges extends Record<string, EdgeEntry>,\n  const TOntology extends readonly OntologyRelation[],\n  const TIdentity extends GraphIdentityConfig | undefined = undefined,\n>(\n  config: GraphDefConfig<TNodes, TEdges, TOntology, TIdentity>,\n): GraphDef<TNodes, NormalizedEdges<TNodes, TEdges>, TOntology, TIdentity> {\n  return defineGraphUnchecked(config);\n}\n\n// Sharing one frozen empty Set keeps the canonical-form hash stable\n// across graphs that never deprecate any kinds.\nconst EMPTY_DEPRECATED_KINDS: ReadonlySet<string> = Object.freeze(\n  new Set<string>(),\n);\n\n// ============================================================\n// Unique Constraint Validation\n// ============================================================\n\n/**\n * Refuses any uniqueness constraint whose `where` clause names a field its kind\n * does not declare.\n *\n * `defineGraph` is the one gate every constraint passes before a write can\n * evaluate it — the store reads constraints off `registration.unique`, and the\n * only other way a registration is built is `mergeGraphExtension`, whose\n * documents `validateGraphExtension` already refuses on the same grounds\n * (`UNKNOWN_UNIQUE_WHERE_FIELD`). Validating here therefore covers every write\n * path at once, instead of at each `checkWherePredicate` call site.\n *\n * Typed callers are already guarded by `UniqueConstraintPredicateBuilder`,\n * which declares exactly the schema's fields; this is the runtime half, for\n * untyped callers whose typo would otherwise produce a constraint that quietly\n * never applies.\n */\nfunction assertUniqueConstraintsAreDeclared(\n  nodes: Record<string, NodeRegistration>,\n): void {\n  for (const registration of Object.values(nodes)) {\n    const constraints = registration.unique;\n    if (constraints === undefined || constraints.length === 0) continue;\n\n    const rawShape = (registration.type.schema as { shape?: unknown }).shape;\n    const shape =\n      typeof rawShape === \"object\" && rawShape !== null ?\n        (rawShape as Readonly<Record<string, unknown>>)\n      : undefined;\n\n    for (const constraint of constraints) {\n      // A schema exposing no `.shape` is not an object schema, so there is no\n      // declared-field set to check the clause against. Skipping the check\n      // silently would disable this guard for exactly the callers it was\n      // written for — untyped ones, who are also the only callers who can put\n      // a non-`ZodObject` here (`defineNode` / `defineEdge` and the\n      // graph-extension compiler all produce `z.object(...)`). So the clause is\n      // REFUSED rather than left unvalidated.\n      //\n      // Narrowly: only a constraint that actually carries a `where` is refused.\n      // A plain `unique: [{ fields }]` needs no shape to be meaningful — it\n      // names props by key and evaluates fine against a non-object schema — and\n      // refusing it would break a working, if unusual, untyped graph for no\n      // safety gain.\n      if (shape === undefined) {\n        if (constraint.where === undefined) continue;\n        throw new ConfigurationError(\n          `Unique constraint \"${constraint.name}\" on node kind \"${registration.type.kind}\" has a \\`where\\` clause, but the kind's schema is not an object schema, so its declared fields cannot be checked.`,\n          {\n            kind: registration.type.kind,\n            constraintName: constraint.name,\n          },\n          {\n            suggestion: `Declare the kind with an object schema (\\`z.object({ ... })\\`) so the \\`where\\` clause can be validated, or drop the \\`where\\` clause.`,\n          },\n        );\n      }\n\n      assertWhereFieldDeclared(registration.type.kind, constraint, shape);\n    }\n  }\n}\n\n// ============================================================\n// Index Normalization\n// ============================================================\n\n/**\n * Validates the `indexes` config slice:\n *\n * - Every index references a kind that exists in the graph's `nodes`\n *   (for node indexes) or `edges` (for edge indexes).\n * - Index `name`s are unique within the graph.\n */\nfunction normalizeIndexes(\n  inputs: readonly IndexDeclaration[],\n  nodes: Record<string, NodeRegistration>,\n  edges: Record<string, EdgeRegistration>,\n): readonly IndexDeclaration[] {\n  if (inputs.length === 0) {\n    return [];\n  }\n\n  const nodeKinds = collectKinds(nodes);\n  const edgeKinds = collectKinds(edges);\n  const seenNames = new Set<string>();\n\n  for (const declaration of inputs) {\n    if (declaration.entity === \"node\" || declaration.entity === \"vector\") {\n      // Vector indexes attach to node kinds (the embedding lives on a\n      // node field). Validation reuses the node-kind check.\n      assertKindRegistered(declaration, nodeKinds, \"node\");\n    } else {\n      assertKindRegistered(declaration, edgeKinds, \"edge\");\n    }\n\n    if (seenNames.has(declaration.name)) {\n      throw new ConfigurationError(\n        `Duplicate index name \"${declaration.name}\" in defineGraph({ indexes }). ` +\n          `Index names must be unique within a graph.`,\n        { indexName: declaration.name },\n        {\n          suggestion: `Pass an explicit { name: \"...\" } to disambiguate.`,\n        },\n      );\n    }\n    seenNames.add(declaration.name);\n  }\n\n  return inputs;\n}\n\nfunction collectKinds(\n  registrations: Record<string, { type: { kind: string } }>,\n): ReadonlySet<string> {\n  const kinds = new Set<string>();\n  for (const registration of Object.values(registrations)) {\n    kinds.add(registration.type.kind);\n  }\n  return kinds;\n}\n\nfunction assertKindRegistered(\n  declaration: IndexDeclaration,\n  registeredKinds: ReadonlySet<string>,\n  entity: KindEntity,\n): void {\n  if (registeredKinds.has(declaration.kind)) return;\n\n  const slot = entity === \"node\" ? \"nodes\" : \"edges\";\n  const suggestion =\n    entity === \"node\" ?\n      `Add { ${declaration.kind}: { type: ${declaration.kind} } } to defineGraph({ nodes }) ` +\n      `or remove the index from \"indexes\".`\n    : `Register the edge in defineGraph({ edges }) or remove the index from \"indexes\".`;\n\n  throw new ConfigurationError(\n    `Index \"${declaration.name}\" references ${entity} kind \"${declaration.kind}\" ` +\n      `which is not registered in this graph's \"${slot}\".`,\n    {\n      indexName: declaration.name,\n      referencedKind: declaration.kind,\n      availableKinds: [...registeredKinds],\n    },\n    { suggestion },\n  );\n}\n\n// ============================================================\n// Graph Definition Utilities\n// ============================================================\n\n/**\n * Checks if a value is a GraphDef.\n */\nexport function isGraphDef(value: unknown): value is GraphDef {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    GRAPH_DEF_BRAND in value &&\n    (value as Record<string, unknown>)[GRAPH_DEF_BRAND] === true\n  );\n}\n\n/**\n * Gets all node kind names from a GraphDef.\n */\nexport function getNodeKinds<G extends GraphDef>(\n  graph: G,\n): readonly (keyof G[\"nodes\"] & string)[] {\n  return Object.keys(graph.nodes);\n}\n\n/**\n * Gets all edge kind names from a GraphDef.\n */\nexport function getEdgeKinds<G extends GraphDef>(\n  graph: G,\n): readonly (keyof G[\"edges\"] & string)[] {\n  return Object.keys(graph.edges);\n}\n\n/**\n * Returns true when `name` is registered as either a node or edge kind\n * on the given graph.\n */\nexport function isKnownKind(graph: GraphDef, name: string): boolean {\n  return Object.hasOwn(graph.nodes, name) || Object.hasOwn(graph.edges, name);\n}\n"]}
+{"version":3,"sources":["../src/core/types.ts","../src/indexes/auto-derive.ts","../src/core/define-graph.ts"],"names":[],"mappings":"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","file":"chunk-5ZJOB5YS.js","sourcesContent":["import { type z } from \"zod\";\n\nimport { ValidationError } from \"../errors\";\n\n// ============================================================\n// Cross-cutting Discriminators\n// ============================================================\n\n/**\n * Which side of the bipartite graph a kind lives on. Used everywhere a\n * function takes \"the entity that owns a kind\" — error metadata,\n * extension classifiers, removal queues, schema diffs.\n */\nexport type KindEntity = \"node\" | \"edge\";\n\n/**\n * Which physical surface an index targets. Vector indexes don't own a\n * kind directly (they back a per-`(kind, field)` typed embedding table\n * owned by the active `VectorStrategy`), but they participate in the same\n * materialization and diff pipelines, so they share this discriminator.\n *\n * `\"system\"` marks TypeGraph's own base-relation indexes\n * (`SYSTEM_INDEX_DECLARATIONS`) — graph-independent, but materialized and\n * status-tracked through the same pipeline; their status rows carry the\n * relation key (e.g. `\"recordedNodes\"`) in the `kind` column.\n */\nexport type IndexEntity = \"node\" | \"edge\" | \"vector\" | \"system\";\n\n/**\n * Field-level null-check operations that round-trip through persisted\n * documents (unique-constraint where clauses, index where clauses,\n * graph-extension where clauses, IsNullPredicate). Consolidated so a\n * single rename or extension touches one site.\n */\nexport type NullCheckOp = \"isNull\" | \"isNotNull\";\n\n// ============================================================\n// Brand Keys for Nominal Typing\n// ============================================================\n\n/** Brand key for NodeType */\nexport const NODE_TYPE_BRAND = \"__nodeType\" as const;\n\n/** Brand key for EdgeType */\nexport const EDGE_TYPE_BRAND = \"__edgeType\" as const;\n\n/** Brand symbol for NodeId */\ndeclare const __nodeId: unique symbol;\n\n/** Brand symbol for EdgeId */\ndeclare const __edgeId: unique symbol;\n\nfunction assertNonEmptyId(value: string, path: string): void {\n  if (value.length > 0) {\n    return;\n  }\n\n  throw new ValidationError(\n    `${path} must be a non-empty string.`,\n    {\n      issues: [\n        {\n          path,\n          message: \"Expected a non-empty string.\",\n        },\n      ],\n    },\n    {\n      suggestion:\n        \"Use a persisted node or edge id value, or let TypeGraph generate an id on create.\",\n    },\n  );\n}\n\n// ============================================================\n// Node Type\n// ============================================================\n\n/**\n * Any JSON-serializable value.\n *\n * Mirrors the JSON wire format: primitives, arrays, and string-keyed objects.\n * `null` is included because the JSON spec requires it for \"no value here\";\n * this is the one place in the public API that uses `null` over `undefined`.\n */\nexport type JsonValue =\n  | null\n  | string\n  | number\n  | boolean\n  | readonly JsonValue[]\n  | Readonly<{ [key: string]: JsonValue }>;\n\n/**\n * Consumer-owned per-kind annotations.\n *\n * Stable labels attached to a node or edge kind at definition time — UI hints,\n * audit policy, provenance pointers, tooling annotations.\n *\n * **Consumer-owned, fully.** TypeGraph never reads, validates, or interprets\n * values in this field. Consumers own the entire namespace; there are no\n * reserved keys or extension prefixes. Future library-owned per-kind state,\n * if needed, will use a separate sibling field rather than carving out keys\n * here.\n *\n * **Annotations participate in schema hashing.** Any change to an annotation\n * value (or adding/removing an annotation key) bumps the canonical schema\n * hash and is reported as a `safe`-severity diff by `getSchemaChanges`. If\n * you don't want versioning for a piece of state, do not put it here.\n *\n * Values must be JSON-serializable — `bigint`, `function`, `symbol`, `undefined`,\n * `Date`, and other class instances are rejected at definition time so they can\n * never silently break schema hashing or storage round-trips.\n */\nexport type KindAnnotations = Readonly<Record<string, JsonValue>>;\n\n/**\n * A node type definition.\n *\n * Created via `defineNode()`. Represents a type of node in the graph\n * with an associated Zod schema for properties.\n */\nexport type NodeType<\n  K extends string = string,\n  S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>,\n> = Readonly<{\n  [NODE_TYPE_BRAND]: true;\n  kind: K;\n  schema: S;\n  description: string | undefined;\n  annotations: KindAnnotations | undefined;\n}>;\n\n/**\n * Branded node ID type.\n *\n * Prevents mixing IDs from different node types at compile time.\n */\nexport type NodeId<N extends NodeType> = string &\n  Readonly<{\n    [__nodeId]: N;\n  }>;\n\n/**\n * Brands a non-empty string as a {@link NodeId}.\n *\n * Use this when a persisted node id has round-tripped through untyped storage\n * or an external boundary and must be passed back to read/update/delete\n * surfaces such as `getById`, `getByIds`, `update`, or `delete`.\n * Write surfaces that mint or claim ids, such as `create({ id })` and\n * `upsertById`, intentionally accept plain strings.\n *\n * @throws {ValidationError} when `value` is empty.\n */\nexport function asNodeId<N extends NodeType = NodeType>(\n  value: string,\n): NodeId<N> {\n  assertNonEmptyId(value, \"asNodeId\");\n  return value as NodeId<N>;\n}\n\n/**\n * Infer the props type from a NodeType.\n */\nexport type NodeProps<N extends NodeType> = z.infer<N[\"schema\"]>;\n\n// ============================================================\n// Edge Type\n// ============================================================\n\n/**\n * An edge type definition.\n *\n * Created via `defineEdge()`. Represents a type of edge in the graph\n * with an optional Zod schema for properties.\n *\n * Optionally includes `from` and `to` arrays that define the allowed\n * source and target node types (domain and range constraints).\n */\nexport type EdgeType<\n  K extends string = string,\n  S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>,\n  From extends readonly NodeType[] | undefined = undefined,\n  To extends readonly NodeType[] | undefined = undefined,\n> = Readonly<{\n  [EDGE_TYPE_BRAND]: true;\n  kind: K;\n  schema: S;\n  description: string | undefined;\n  annotations: KindAnnotations | undefined;\n  from: From;\n  to: To;\n}>;\n\n/**\n * Base edge type for use in constraints - accepts any from/to configuration.\n */\nexport type AnyEdgeType = EdgeType<\n  string,\n  z.ZodObject<z.ZodRawShape>,\n  readonly NodeType[] | undefined,\n  readonly NodeType[] | undefined\n>;\n\n/**\n * An edge type that has both from and to constraints defined.\n * Can be used directly in defineGraph without an EdgeRegistration wrapper.\n */\nexport type EdgeTypeWithEndpoints = EdgeType<\n  string,\n  z.ZodObject<z.ZodRawShape>,\n  readonly NodeType[],\n  readonly NodeType[]\n>;\n\n/**\n * Branded edge ID type.\n *\n * Prevents mixing IDs from different edge types at compile time.\n */\nexport type EdgeId<E extends AnyEdgeType = AnyEdgeType> = string &\n  Readonly<{\n    [__edgeId]: E;\n  }>;\n\n/**\n * Brands a non-empty string as an {@link EdgeId}.\n *\n * Use this when a persisted edge id has round-tripped through untyped storage\n * or an external boundary and must be passed back to read/update/delete\n * surfaces such as `getById`, `getByIds`, `update`, or `delete`.\n * Write surfaces that mint ids intentionally accept plain strings.\n *\n * @throws {ValidationError} when `value` is empty.\n */\nexport function asEdgeId<E extends AnyEdgeType = AnyEdgeType>(\n  value: string,\n): EdgeId<E> {\n  assertNonEmptyId(value, \"asEdgeId\");\n  return value as EdgeId<E>;\n}\n\n/**\n * Infer the props type from an EdgeType.\n */\nexport type EdgeProps<E extends AnyEdgeType> = z.infer<E[\"schema\"]>;\n\n// ============================================================\n// Configuration Types\n// ============================================================\n\n/**\n * Delete behaviors for nodes.\n */\nexport type DeleteBehavior = \"restrict\" | \"cascade\" | \"disconnect\";\n\n/**\n * Edge cardinality constraints.\n */\nexport type Cardinality =\n  | \"many\" // No constraint (default)\n  | \"one\" // At most one edge of this kind from any source node\n  | \"unique\" // At most one edge of this kind between any (source, target) pair\n  | \"oneActive\"; // At most one edge with valid_to IS NULL from any source\n\n/**\n * Endpoint existence modes for edge validation.\n */\nexport type EndpointExistence =\n  | \"notDeleted\" // Endpoint deleted_at IS NULL (default)\n  | \"currentlyValid\" // Endpoint not deleted AND temporally valid\n  | \"ever\"; // Endpoint exists in any state\n\n/**\n * Temporal query modes.\n */\nexport type TemporalMode =\n  | \"current\" // Valid now AND not deleted\n  | \"asOf\" // Valid at specific date AND not deleted\n  | \"includeEnded\" // All validity periods AND not deleted\n  | \"includeTombstones\"; // Everything including soft-deleted\n\n/**\n * Uniqueness constraint scope.\n */\nexport type UniquenessScope =\n  | \"kind\" // Unique within this exact kind only\n  | \"kindWithSubClasses\"; // Unique across this kind and all subclasses\n\n/**\n * Collation for uniqueness constraints.\n */\nexport type Collation = \"binary\" | \"caseInsensitive\";\n\n// ============================================================\n// Uniqueness Constraint\n// ============================================================\n\n/**\n * Uniqueness constraint definition.\n */\nexport type UniqueConstraint<\n  S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>,\n> = Readonly<{\n  name: string;\n  fields: readonly (keyof z.infer<S> & string)[];\n  where?: (\n    props: UniqueConstraintPredicateBuilder<S>,\n  ) => UniqueConstraintPredicate;\n  scope: UniquenessScope;\n  collation: Collation;\n}>;\n\n/**\n * Predicate builder for uniqueness constraint where clause.\n * Uses -? to make all fields required in the builder, even if optional in the schema.\n */\ntype UniqueConstraintPredicateBuilder<S extends z.ZodObject<z.ZodRawShape>> =\n  Readonly<{\n    [K in keyof z.infer<S>]-?: UniqueConstraintField;\n  }>;\n\n/**\n * Field operations for uniqueness constraint predicates.\n */\ntype UniqueConstraintField = Readonly<{\n  isNull: () => UniqueConstraintPredicate;\n  isNotNull: () => UniqueConstraintPredicate;\n}>;\n\n/**\n * A uniqueness constraint predicate (internal representation).\n */\ntype UniqueConstraintPredicate = Readonly<{\n  __type: \"unique_predicate\";\n  field: string;\n  op: NullCheckOp;\n}>;\n\n// ============================================================\n// Node Registration\n// ============================================================\n\n/**\n * Node registration in a graph definition.\n */\nexport type NodeRegistration<N extends NodeType = NodeType> = Readonly<{\n  type: N;\n  unique?: readonly UniqueConstraint<N[\"schema\"]>[];\n  onDelete?: DeleteBehavior;\n}>;\n\n// ============================================================\n// Edge Registration\n// ============================================================\n\n/**\n * Edge registration in a graph definition.\n */\nexport type EdgeRegistration<\n  E extends AnyEdgeType = AnyEdgeType,\n  FromTypes extends NodeType = NodeType,\n  ToTypes extends NodeType = NodeType,\n> = Readonly<{\n  type: E;\n  from: readonly FromTypes[];\n  to: readonly ToTypes[];\n  cardinality?: Cardinality;\n  endpointExistence?: EndpointExistence;\n}>;\n\n// ============================================================\n// Graph Defaults\n// ============================================================\n\n/**\n * Default settings for a graph.\n */\nexport type GraphDefaults = Readonly<{\n  onNodeDelete?: DeleteBehavior;\n  temporalMode?: TemporalMode;\n}>;\n\n// ============================================================\n// Type Helpers\n// ============================================================\n\n/**\n * Checks if a value is a NodeType.\n */\nexport function isNodeType(value: unknown): value is NodeType {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    NODE_TYPE_BRAND in value &&\n    (value as Record<string, unknown>)[NODE_TYPE_BRAND] === true\n  );\n}\n\n/**\n * Checks if a value is an EdgeType.\n */\nexport function isEdgeType(value: unknown): value is AnyEdgeType {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    EDGE_TYPE_BRAND in value &&\n    (value as Record<string, unknown>)[EDGE_TYPE_BRAND] === true\n  );\n}\n\n/**\n * Checks if a value is an EdgeType with both from and to constraints defined.\n * Such edges can be used directly in defineGraph without an EdgeRegistration wrapper.\n */\nexport function isEdgeTypeWithEndpoints(\n  value: unknown,\n): value is EdgeTypeWithEndpoints {\n  return (\n    isEdgeType(value) &&\n    Array.isArray(value.from) &&\n    value.from.length > 0 &&\n    Array.isArray(value.to) &&\n    value.to.length > 0\n  );\n}\n","/**\n * Auto-derive vector index declarations from `embedding()` brands on\n * node schemas.\n *\n * Walks each node's top-level Zod shape, finds fields wrapped in\n * `embedding(dimensions, opts)` (including `.optional()` /\n * `.nullable()` wrappers), and emits one `VectorIndexDeclaration` per\n * (kind, field) pair. The declaration carries the resolved index\n * configuration from the embedding brand — metric, indexType, HNSW /\n * IVFFlat params — so the materializer doesn't need to reach back into\n * the Zod schema.\n *\n * Auto-derivation is intentionally limited to TOP-LEVEL embedding\n * fields. Embeddings nested inside object properties are out of scope\n * for v1 — vector slots are materialized as flat `(kind, fieldPath)`\n * storage units, and top-level fields keep that contract explicit.\n *\n * Explicit `defineVectorIndex(node, fieldPath, opts)` declarations\n * passed via `defineGraph({ indexes })` take precedence — when an\n * explicit declaration matches the same (kind, fieldPath) as an\n * auto-derived one, the explicit version wins. This lets consumers\n * override defaults without losing auto-derivation for other fields.\n */\n\nimport { type z } from \"zod\";\n\nimport {\n  getEmbeddingIndex,\n  isEmbeddingSchema,\n  type ResolvedEmbeddingIndex,\n} from \"../core/embedding\";\nimport { type NodeRegistration } from \"../core/types\";\nimport { type IndexDeclaration, type VectorIndexDeclaration } from \"./types\";\n\n/**\n * Auto-derive vector index declarations from embedding brands on a\n * map of node registrations. Returns one declaration per\n * (kind, top-level field) pair. Empty array when no embeddings found.\n *\n * Cross-graph status-table disambiguation does NOT happen here — the\n * declaration name stays clean (`tg_vec_{kind}_{field}_{metric}`) so\n * `pg_indexes` and result-entry inspection are readable. The\n * materializer composes a graph-scoped key (`${graphId}::${name}`)\n * for status-table identity, applied uniformly to both auto-derived\n * and explicit `VectorIndexDeclaration` entries — see\n * `vectorStatusKey` in `store/materialize-indexes.ts`. This keeps\n * the disambiguation rule in one place that BOTH paths go through,\n * rather than depending on the auto-derive caller to produce a\n * graph-scoped name.\n */\nexport function autoDeriveVectorIndexes(\n  nodes: Record<string, NodeRegistration>,\n): readonly VectorIndexDeclaration[] {\n  const out: VectorIndexDeclaration[] = [];\n  for (const registration of Object.values(nodes)) {\n    const node = registration.type;\n    const shape = readObjectShape(node.schema);\n    if (shape === undefined) continue;\n    for (const [fieldName, fieldSchema] of Object.entries(shape)) {\n      const config = readEmbeddingIndex(fieldSchema);\n      if (config === undefined) continue;\n      const dimensions = readEmbeddingDimensions(fieldSchema);\n      if (dimensions === undefined) continue;\n      out.push(buildAutoDerived(node.kind, fieldName, dimensions, config));\n    }\n  }\n  return out;\n}\n\n/**\n * Merge auto-derived declarations with explicit ones, preferring\n * explicit on (kind, fieldPath) collisions. Returns a flat list of all\n * indexes; non-vector entries from `explicit` pass through unchanged.\n */\nexport function mergeVectorIndexes(\n  explicit: readonly IndexDeclaration[],\n  autoDerived: readonly VectorIndexDeclaration[],\n): readonly IndexDeclaration[] {\n  if (autoDerived.length === 0) return explicit;\n  const explicitVectorKeys = new Set<string>();\n  for (const declaration of explicit) {\n    if (declaration.entity === \"vector\") {\n      explicitVectorKeys.add(`${declaration.kind}|${declaration.fieldPath}`);\n    }\n  }\n  const filteredAuto = autoDerived.filter(\n    (entry) => !explicitVectorKeys.has(`${entry.kind}|${entry.fieldPath}`),\n  );\n  return [...explicit, ...filteredAuto];\n}\n\n/**\n * Generate the deterministic vector index name. The visible prefix\n * `tg_vec_<kind>_<field>_<metric>` keeps it scannable in result-entry\n * inspection and the `typegraph_index_materializations` table.\n *\n * Cross-graph disambiguation is handled separately at the\n * materialization boundary (see `vectorStatusKey`) so the declaration\n * name doesn't need to carry `graphId` — the same auto-derived name\n * is reusable across graphs and the materializer composes a\n * graph-scoped status key for both auto-derived and explicit entries\n * uniformly.\n */\nfunction buildAutoDerived(\n  kind: string,\n  fieldName: string,\n  dimensions: number,\n  config: ResolvedEmbeddingIndex,\n): VectorIndexDeclaration {\n  const fieldPath = fieldName;\n  return Object.freeze({\n    entity: \"vector\" as const,\n    name: `tg_vec_${sanitize(kind)}_${sanitize(fieldName)}_${config.metric}`,\n    kind,\n    fieldPath,\n    dimensions,\n    metric: config.metric,\n    indexType: config.indexType,\n    indexParams: Object.freeze({\n      m: config.m,\n      efConstruction: config.efConstruction,\n      lists: config.lists,\n    }),\n  });\n}\n\nfunction sanitize(value: string): string {\n  return value.replaceAll(/[^a-zA-Z0-9]/g, \"_\").toLowerCase();\n}\n\nfunction readObjectShape(\n  schema: z.ZodType,\n): Record<string, z.ZodType> | undefined {\n  if ((schema as { type?: string }).type !== \"object\") return undefined;\n  const shape = (schema.def as { shape?: Record<string, z.ZodType> }).shape;\n  return shape;\n}\n\nfunction readEmbeddingIndex(\n  schema: z.ZodType,\n): ResolvedEmbeddingIndex | undefined {\n  for (const candidate of unwrapChain(schema)) {\n    const config = getEmbeddingIndex(candidate);\n    if (config !== undefined) return config;\n  }\n  return undefined;\n}\n\nfunction readEmbeddingDimensions(schema: z.ZodType): number | undefined {\n  for (const candidate of unwrapChain(schema)) {\n    if (isEmbeddingSchema(candidate)) {\n      return (candidate as unknown as Record<string, number>)[\n        \"_embeddingDimensions\"\n      ];\n    }\n  }\n  return undefined;\n}\n\n/**\n * Yield the schema and every reachable inner schema by repeatedly\n * applying `.unwrap()` (Zod 4 optional/nullable/default) and\n * `.def.innerType` (some wrappers). Cycle-guarded by depth and\n * reference identity. Generators stop at the first non-unwrappable\n * schema OR after 8 levels — deeper wrapping is pathological and not\n * worth supporting.\n */\nfunction* unwrapChain(schema: z.ZodType): Generator<z.ZodType, void, void> {\n  const seen = new Set<z.ZodType>();\n  let current: z.ZodType | undefined = schema;\n  let depth = 0;\n  while (current !== undefined && !seen.has(current) && depth < 8) {\n    seen.add(current);\n    yield current;\n    current = unwrapOnce(current);\n    depth++;\n  }\n}\n\nfunction unwrapOnce(schema: z.ZodType): z.ZodType | undefined {\n  // Zod 4 wrappers expose `.unwrap()` on optional/nullable/default.\n  const candidate = schema as unknown as { unwrap?: () => z.ZodType };\n  if (typeof candidate.unwrap === \"function\") return candidate.unwrap();\n  // Some wrappers expose the inner schema via `.def.innerType`.\n  return (schema as unknown as { def?: { innerType?: z.ZodType } }).def\n    ?.innerType;\n}\n","import { assertWhereFieldDeclared } from \"../constraints\";\nimport { ConfigurationError } from \"../errors/index\";\nimport { type GraphExtension } from \"../graph-extension/extension-types\";\nimport {\n  autoDeriveVectorIndexes,\n  mergeVectorIndexes,\n} from \"../indexes/auto-derive\";\nimport { type IndexDeclaration } from \"../indexes/types\";\nimport { type OntologyRelation } from \"../ontology/types\";\nimport { createDataKeyedBag } from \"../utils/object\";\nimport {\n  type AnyEdgeType,\n  type DeleteBehavior,\n  type EdgeRegistration,\n  type EdgeTypeWithEndpoints,\n  type GraphDefaults,\n  isEdgeType,\n  isEdgeTypeWithEndpoints,\n  type KindEntity,\n  type NodeRegistration,\n  type NodeType,\n  type TemporalMode,\n} from \"./types\";\n\n// ============================================================\n// Graph Definition Brand Symbol\n// ============================================================\n\n/** Brand key for GraphDef */\nconst GRAPH_DEF_BRAND = \"__graphDef\" as const;\n\n// ============================================================\n// Edge Entry Types\n// ============================================================\n\n/**\n * An edge entry in the graph definition.\n * Can be:\n * - EdgeType directly (constrained or unconstrained)\n * - EdgeRegistration object (always works, can override/narrow defaults)\n */\ntype EdgeEntry = EdgeRegistration | AnyEdgeType;\n\n/**\n * Normalized edge map type - all entries become EdgeRegistration.\n * For bare EdgeTypes, constrained endpoints are extracted from the type;\n * unconstrained edges fall back to all node types in the graph.\n */\ntype NormalizedEdges<\n  TNodes extends Record<string, NodeRegistration>,\n  TEdges extends Record<string, EdgeEntry>,\n> = {\n  [K in keyof TEdges]: TEdges[K] extends EdgeRegistration ? TEdges[K]\n  : TEdges[K] extends AnyEdgeType ?\n    EdgeRegistration<\n      TEdges[K],\n      TEdges[K][\"from\"] extends readonly (infer N extends NodeType)[] ? N\n      : TNodes[keyof TNodes][\"type\"],\n      TEdges[K][\"to\"] extends readonly (infer N extends NodeType)[] ? N\n      : TNodes[keyof TNodes][\"type\"]\n    >\n  : never;\n};\n\n// ============================================================\n// Edge Normalization Functions\n// ============================================================\n\n/**\n * Validates that an EdgeRegistration's constraints don't widen beyond\n * the edge type's built-in domain/range constraints.\n */\nfunction validateConstraintNarrowing(\n  name: string,\n  edgeType: EdgeTypeWithEndpoints,\n  registration: EdgeRegistration,\n): void {\n  const builtInFromNames = new Set(edgeType.from.map((node) => node.kind));\n  for (const fromNode of registration.from) {\n    if (!builtInFromNames.has(fromNode.kind)) {\n      throw new ConfigurationError(\n        `Edge \"${name}\" registration has 'from' kind \"${fromNode.kind}\" ` +\n          `not in edge's built-in domain: [${[...builtInFromNames].join(\", \")}]`,\n        {\n          edgeName: name,\n          invalidFrom: fromNode.kind,\n          allowedFrom: [...builtInFromNames],\n        },\n        {\n          suggestion: `Edge registration can only narrow, not widen, the edge type's built-in constraints.`,\n        },\n      );\n    }\n  }\n\n  const builtInToNames = new Set(edgeType.to.map((node) => node.kind));\n  for (const toNode of registration.to) {\n    if (!builtInToNames.has(toNode.kind)) {\n      throw new ConfigurationError(\n        `Edge \"${name}\" registration has 'to' kind \"${toNode.kind}\" ` +\n          `not in edge's built-in range: [${[...builtInToNames].join(\", \")}]`,\n        {\n          edgeName: name,\n          invalidTo: toNode.kind,\n          allowedTo: [...builtInToNames],\n        },\n        {\n          suggestion: `Edge registration can only narrow, not widen, the edge type's built-in constraints.`,\n        },\n      );\n    }\n  }\n}\n\n/**\n * Normalizes a single edge entry to EdgeRegistration.\n */\nfunction normalizeEdgeEntry(\n  name: string,\n  entry: EdgeEntry,\n  allNodeTypes: readonly NodeType[],\n): EdgeRegistration {\n  if (isEdgeType(entry)) {\n    if (isEdgeTypeWithEndpoints(entry)) {\n      // EdgeType with from/to — convert to EdgeRegistration\n      return { type: entry, from: entry.from, to: entry.to };\n    }\n    // Unconstrained EdgeType — allow any→any\n    return { type: entry, from: allNodeTypes, to: allNodeTypes };\n  }\n\n  // Already EdgeRegistration — validate narrowing if edge has built-in constraints\n  if (isEdgeTypeWithEndpoints(entry.type)) {\n    validateConstraintNarrowing(name, entry.type, entry);\n  }\n\n  return entry;\n}\n\n/**\n * Normalizes all edge entries to EdgeRegistration.\n *\n * The accumulator is a {@link createDataKeyedBag}: its keys are EDGE KIND\n * NAMES, which are data. `isValidKindName` admits `__proto__` exactly as it\n * admits `toString`, and a graph literal written with a computed key\n * (`edges: { [\"__proto__\"]: knows }`) carries it as an own key — so\n * `result[name] = …` into a `{}` literal would reach `Object.prototype`'s\n * `__proto__` setter, reparent the accumulator, and drop the declared edge.\n * `config.nodes` needs no such treatment: it is passed through by reference,\n * never re-accumulated.\n */\nfunction normalizeEdges(\n  edges: Record<string, EdgeEntry>,\n  allNodeTypes: readonly NodeType[],\n): Record<string, EdgeRegistration> {\n  const result = createDataKeyedBag<EdgeRegistration>();\n  for (const [name, entry] of Object.entries(edges)) {\n    result[name] = normalizeEdgeEntry(name, entry, allNodeTypes);\n  }\n  // Spread at the boundary: this becomes `graph.edges` on the returned (and\n  // publicly reachable) `GraphDef`. See `createDataKeyedBag` in\n  // ../utils/object.ts.\n  return { ...result };\n}\n\n// ============================================================\n// Graph Definition Configuration\n// ============================================================\n\n/** Durable graph-level configuration for the TypeGraph Identity Profile. */\nexport type GraphIdentityConfig = Readonly<{\n  /** Whether equal ids in different kinds implicitly join one identity class. */\n  sameIdAcrossKinds: \"fold\" | \"ignore\";\n}>;\n\n/**\n * Configuration for defineGraph.\n */\ntype GraphDefConfig<\n  TNodes extends Record<string, NodeRegistration>,\n  TEdges extends Record<string, EdgeEntry>,\n  TOntology extends readonly OntologyRelation[],\n  TIdentity extends GraphIdentityConfig | undefined,\n> = Readonly<{\n  /** Unique identifier for this graph */\n  id: string;\n  /** Node registrations */\n  nodes: TNodes;\n  /** Edge registrations or EdgeTypes with built-in domain/range */\n  edges: TEdges;\n  /** Ontology relations */\n  ontology?: TOntology;\n  /** Graph-wide defaults */\n  defaults?: GraphDefaults;\n  /** Enables the TypeGraph Identity Profile for this graph. */\n  identity?: TIdentity;\n  /**\n   * Index declarations attached to this graph.\n   *\n   * Accepts the outputs of `defineNodeIndex` / `defineEdgeIndex` (which\n   * already return `IndexDeclaration` values) or pre-built declarations\n   * reconstructed from a stored schema or graph extension.\n   *\n   * Validated at definition time: every index must reference a `kind`\n   * that exists in `nodes` / `edges`, and index `name`s must be unique\n   * within the graph.\n   *\n   * Index DDL is **not** generated by `defineGraph`. Indexes flow into\n   * `SerializedSchema.indexes` so they can later be materialized via\n   * `store.materializeIndexes()` — lifting the storage concern out of\n   * the schema-version commit path.\n   */\n  indexes?: readonly IndexDeclaration[];\n}>;\n\n// ============================================================\n// Graph Definition Type\n// ============================================================\n\n/**\n * A graph definition.\n *\n * This is a compile-time artifact that describes the structure of a graph.\n * Use `createStore()` to create a runtime store from this definition.\n */\nexport type GraphDef<\n  TNodes extends Record<string, NodeRegistration> = Record<\n    string,\n    NodeRegistration\n  >,\n  TEdges extends Record<string, EdgeRegistration> = Record<\n    string,\n    EdgeRegistration\n  >,\n  TOntology extends readonly OntologyRelation[] = readonly OntologyRelation[],\n  TIdentity extends GraphIdentityConfig | undefined =\n    GraphIdentityConfig | undefined,\n> = Readonly<{\n  [GRAPH_DEF_BRAND]: true;\n  id: string;\n  nodes: TNodes;\n  edges: TEdges;\n  ontology: TOntology;\n  /** Durable graph-level opt-in to the TypeGraph Identity Profile. */\n  identity: TIdentity;\n  defaults: Readonly<{\n    onNodeDelete: DeleteBehavior;\n    temporalMode: TemporalMode;\n  }>;\n  /**\n   * Index declarations attached to this graph. Preserves whatever the\n   * caller passed to `defineGraph` (including an explicit empty array)\n   * for introspection purposes.\n   *\n   * The serialized canonical form is order-canonicalized (sorted by\n   * `name`) and treats `undefined` and `[]` as the same \"no slice\" form\n   * — an empty array does not bump the schema hash, since indexes are\n   * an unordered set keyed by name and `[]` carries no semantic meaning\n   * that an absent slice doesn't.\n   */\n  indexes: readonly IndexDeclaration[] | undefined;\n  /**\n   * Graph extension this graph was merged with, if any. Set by\n   * `mergeGraphExtension`; never set by `defineGraph` directly.\n   * Exists solely so re-serialization is stable — the rest of the\n   * system reads the merged kinds through `nodes` / `edges` /\n   * `ontology` and never inspects this field. Absent on graphs that\n   * have never been extended; legacy graphs hash byte-identically.\n   */\n  extension: GraphExtension | undefined;\n  /**\n   * Soft-deprecated kind names attached to this graph. Set by the\n   * loader from the persisted schema and by `store.deprecateKinds(...)`\n   * / `store.undeprecateKinds(...)`. A purely informational signal\n   * surfaced for introspection — does not gate reads, writes, or\n   * queries. Defaults to the empty set on freshly-defined graphs.\n   */\n  deprecatedKinds: ReadonlySet<string>;\n}>;\n\n// ============================================================\n// Type Helpers\n// ============================================================\n\n/**\n * Extract node kind names from a GraphDef.\n */\nexport type NodeKinds<G extends GraphDef> = keyof G[\"nodes\"] & string;\n\n/**\n * Extract edge kind names from a GraphDef.\n */\nexport type EdgeKinds<G extends GraphDef> = keyof G[\"edges\"] & string;\n\n/**\n * Get a NodeType from a GraphDef by kind name.\n */\nexport type GetNodeType<\n  G extends GraphDef,\n  K extends NodeKinds<G>,\n> = G[\"nodes\"][K][\"type\"];\n\n/**\n * Get an EdgeType from a GraphDef by kind name.\n */\nexport type GetEdgeType<\n  G extends GraphDef,\n  K extends EdgeKinds<G>,\n> = G[\"edges\"][K][\"type\"];\n\n/**\n * Get all NodeTypes from a GraphDef.\n */\nexport type AllNodeTypes<G extends GraphDef> = {\n  [K in NodeKinds<G>]: G[\"nodes\"][K][\"type\"];\n}[NodeKinds<G>];\n\n/**\n * Get all EdgeTypes from a GraphDef.\n */\nexport type AllEdgeTypes<G extends GraphDef> = {\n  [K in EdgeKinds<G>]: G[\"edges\"][K][\"type\"];\n}[EdgeKinds<G>];\n\n// ============================================================\n// Define Graph Function\n// ============================================================\n\n/**\n * Creates a graph definition.\n *\n * @example\n * ```typescript\n * const graph = defineGraph({\n *   id: \"my_graph\",\n *   nodes: {\n *     Person: { type: Person },\n *     Company: { type: Company },\n *   },\n *   edges: {\n *     // Traditional EdgeRegistration syntax\n *     worksAt: {\n *       type: worksAt,\n *       from: [Person],\n *       to: [Company],\n *       cardinality: \"many\",\n *     },\n *     // Or use EdgeType directly if it has from/to defined\n *     knows,  // EdgeType with built-in domain/range\n *   },\n *   ontology: [\n *     subClassOf(Company, Organization),\n *     disjointWith(Person, Organization),\n *   ],\n *   defaults: {\n *     onNodeDelete: \"restrict\",\n *     temporalMode: \"current\",\n *   },\n * });\n * ```\n */\nexport function defineGraph<\n  const TNodes extends Record<string, NodeRegistration<NodeType>>,\n  const TEdges extends Record<string, EdgeEntry>,\n  const TOntology extends readonly OntologyRelation[],\n  const TIdentity extends GraphIdentityConfig | undefined = undefined,\n>(\n  config: GraphDefConfig<TNodes, TEdges, TOntology, TIdentity>,\n): GraphDef<TNodes, NormalizedEdges<TNodes, TEdges>, TOntology, TIdentity> {\n  return defineGraphUnchecked(config);\n}\n\nfunction defineGraphUnchecked<\n  const TNodes extends Record<string, NodeRegistration<NodeType>>,\n  const TEdges extends Record<string, EdgeEntry>,\n  const TOntology extends readonly OntologyRelation[],\n  const TIdentity extends GraphIdentityConfig | undefined = undefined,\n>(\n  config: GraphDefConfig<TNodes, TEdges, TOntology, TIdentity>,\n): GraphDef<TNodes, NormalizedEdges<TNodes, TEdges>, TOntology, TIdentity> {\n  const defaults = {\n    onNodeDelete: config.defaults?.onNodeDelete ?? \"restrict\",\n    temporalMode: config.defaults?.temporalMode ?? \"current\",\n  } as const;\n\n  const allNodeTypes = Object.values(config.nodes).map((reg) => reg.type);\n  const normalizedEdges = normalizeEdges(config.edges, allNodeTypes);\n  assertUniqueConstraintsAreDeclared(config.nodes);\n  // Vector indexes are auto-derived from `embedding()` brands on node\n  // schemas (see `autoDeriveVectorIndexes`). Explicit declarations\n  // passed via `defineGraph({ indexes })` win on (kind, fieldPath)\n  // collisions so consumers can override defaults — see\n  // `mergeVectorIndexes`. The merged list flows through\n  // `normalizeIndexes` for the standard kind-registered + unique-name\n  // checks.\n  //\n  // Preservation rule: if the consumer never passed `indexes` at all\n  // AND no embedding brands exist, leave `graph.indexes` undefined to\n  // keep the introspection surface stable for legacy graphs. If the\n  // consumer passed an explicit `[]`, surface it as `[]` (not\n  // `undefined`) to match the contract pinned by the\n  // \"preserves an explicit empty indexes array\" test.\n  const autoVectorIndexes = autoDeriveVectorIndexes(config.nodes);\n  const explicitProvided = config.indexes !== undefined;\n  const mergedIndexes = mergeVectorIndexes(\n    config.indexes ?? [],\n    autoVectorIndexes,\n  );\n  const indexes =\n    !explicitProvided && mergedIndexes.length === 0 ?\n      undefined\n    : normalizeIndexes(mergedIndexes, config.nodes, normalizedEdges);\n\n  return Object.freeze({\n    [GRAPH_DEF_BRAND]: true as const,\n    id: config.id,\n    nodes: config.nodes,\n    edges: normalizedEdges,\n    ontology: config.ontology ?? ([] as unknown as TOntology),\n    identity: config.identity as TIdentity,\n    defaults,\n    indexes,\n    extension: undefined,\n    deprecatedKinds: EMPTY_DEPRECATED_KINDS,\n  }) as GraphDef<TNodes, NormalizedEdges<TNodes, TEdges>, TOntology, TIdentity>;\n}\n\n/**\n * @internal Marks a graph definition as framework-owned rather than\n * application-authored.\n *\n * It builds exactly what {@link defineGraph} builds — the name records the\n * caller, it does not reserve anything. There is NO reserved id namespace and\n * no id validation anywhere: an application may define a graph at any id a\n * framework-owned graph uses, the merge-provenance sidecar's\n * `<target>::merge-provenance` convention included. That convention is\n * protected at RUNTIME instead, by the ownership checks in the single gateway\n * that opens a sidecar (`openProvenanceStore`), which refuses an id occupied by\n * anything it cannot prove it owns.\n */\nexport function defineInternalGraph<\n  const TNodes extends Record<string, NodeRegistration<NodeType>>,\n  const TEdges extends Record<string, EdgeEntry>,\n  const TOntology extends readonly OntologyRelation[],\n  const TIdentity extends GraphIdentityConfig | undefined = undefined,\n>(\n  config: GraphDefConfig<TNodes, TEdges, TOntology, TIdentity>,\n): GraphDef<TNodes, NormalizedEdges<TNodes, TEdges>, TOntology, TIdentity> {\n  return defineGraphUnchecked(config);\n}\n\n// Sharing one frozen empty Set keeps the canonical-form hash stable\n// across graphs that never deprecate any kinds.\nconst EMPTY_DEPRECATED_KINDS: ReadonlySet<string> = Object.freeze(\n  new Set<string>(),\n);\n\n// ============================================================\n// Unique Constraint Validation\n// ============================================================\n\n/**\n * Refuses any uniqueness constraint whose `where` clause names a field its kind\n * does not declare.\n *\n * `defineGraph` is the one gate every constraint passes before a write can\n * evaluate it — the store reads constraints off `registration.unique`, and the\n * only other way a registration is built is `mergeGraphExtension`, whose\n * documents `validateGraphExtension` already refuses on the same grounds\n * (`UNKNOWN_UNIQUE_WHERE_FIELD`). Validating here therefore covers every write\n * path at once, instead of at each `checkWherePredicate` call site.\n *\n * Typed callers are already guarded by `UniqueConstraintPredicateBuilder`,\n * which declares exactly the schema's fields; this is the runtime half, for\n * untyped callers whose typo would otherwise produce a constraint that quietly\n * never applies.\n */\nfunction assertUniqueConstraintsAreDeclared(\n  nodes: Record<string, NodeRegistration>,\n): void {\n  for (const registration of Object.values(nodes)) {\n    const constraints = registration.unique;\n    if (constraints === undefined || constraints.length === 0) continue;\n\n    const rawShape = (registration.type.schema as { shape?: unknown }).shape;\n    const shape =\n      typeof rawShape === \"object\" && rawShape !== null ?\n        (rawShape as Readonly<Record<string, unknown>>)\n      : undefined;\n\n    for (const constraint of constraints) {\n      // A schema exposing no `.shape` is not an object schema, so there is no\n      // declared-field set to check the clause against. Skipping the check\n      // silently would disable this guard for exactly the callers it was\n      // written for — untyped ones, who are also the only callers who can put\n      // a non-`ZodObject` here (`defineNode` / `defineEdge` and the\n      // graph-extension compiler all produce `z.object(...)`). So the clause is\n      // REFUSED rather than left unvalidated.\n      //\n      // Narrowly: only a constraint that actually carries a `where` is refused.\n      // A plain `unique: [{ fields }]` needs no shape to be meaningful — it\n      // names props by key and evaluates fine against a non-object schema — and\n      // refusing it would break a working, if unusual, untyped graph for no\n      // safety gain.\n      if (shape === undefined) {\n        if (constraint.where === undefined) continue;\n        throw new ConfigurationError(\n          `Unique constraint \"${constraint.name}\" on node kind \"${registration.type.kind}\" has a \\`where\\` clause, but the kind's schema is not an object schema, so its declared fields cannot be checked.`,\n          {\n            kind: registration.type.kind,\n            constraintName: constraint.name,\n          },\n          {\n            suggestion: `Declare the kind with an object schema (\\`z.object({ ... })\\`) so the \\`where\\` clause can be validated, or drop the \\`where\\` clause.`,\n          },\n        );\n      }\n\n      assertWhereFieldDeclared(registration.type.kind, constraint, shape);\n    }\n  }\n}\n\n// ============================================================\n// Index Normalization\n// ============================================================\n\n/**\n * Validates the `indexes` config slice:\n *\n * - Every index references a kind that exists in the graph's `nodes`\n *   (for node indexes) or `edges` (for edge indexes).\n * - Index `name`s are unique within the graph.\n */\nfunction normalizeIndexes(\n  inputs: readonly IndexDeclaration[],\n  nodes: Record<string, NodeRegistration>,\n  edges: Record<string, EdgeRegistration>,\n): readonly IndexDeclaration[] {\n  if (inputs.length === 0) {\n    return [];\n  }\n\n  const nodeKinds = collectKinds(nodes);\n  const edgeKinds = collectKinds(edges);\n  const seenNames = new Set<string>();\n\n  for (const declaration of inputs) {\n    if (declaration.entity === \"node\" || declaration.entity === \"vector\") {\n      // Vector indexes attach to node kinds (the embedding lives on a\n      // node field). Validation reuses the node-kind check.\n      assertKindRegistered(declaration, nodeKinds, \"node\");\n    } else {\n      assertKindRegistered(declaration, edgeKinds, \"edge\");\n    }\n\n    if (seenNames.has(declaration.name)) {\n      throw new ConfigurationError(\n        `Duplicate index name \"${declaration.name}\" in defineGraph({ indexes }). ` +\n          `Index names must be unique within a graph.`,\n        { indexName: declaration.name },\n        {\n          suggestion: `Pass an explicit { name: \"...\" } to disambiguate.`,\n        },\n      );\n    }\n    seenNames.add(declaration.name);\n  }\n\n  return inputs;\n}\n\nfunction collectKinds(\n  registrations: Record<string, { type: { kind: string } }>,\n): ReadonlySet<string> {\n  const kinds = new Set<string>();\n  for (const registration of Object.values(registrations)) {\n    kinds.add(registration.type.kind);\n  }\n  return kinds;\n}\n\nfunction assertKindRegistered(\n  declaration: IndexDeclaration,\n  registeredKinds: ReadonlySet<string>,\n  entity: KindEntity,\n): void {\n  if (registeredKinds.has(declaration.kind)) return;\n\n  const slot = entity === \"node\" ? \"nodes\" : \"edges\";\n  const suggestion =\n    entity === \"node\" ?\n      `Add { ${declaration.kind}: { type: ${declaration.kind} } } to defineGraph({ nodes }) ` +\n      `or remove the index from \"indexes\".`\n    : `Register the edge in defineGraph({ edges }) or remove the index from \"indexes\".`;\n\n  throw new ConfigurationError(\n    `Index \"${declaration.name}\" references ${entity} kind \"${declaration.kind}\" ` +\n      `which is not registered in this graph's \"${slot}\".`,\n    {\n      indexName: declaration.name,\n      referencedKind: declaration.kind,\n      availableKinds: [...registeredKinds],\n    },\n    { suggestion },\n  );\n}\n\n// ============================================================\n// Graph Definition Utilities\n// ============================================================\n\n/**\n * Checks if a value is a GraphDef.\n */\nexport function isGraphDef(value: unknown): value is GraphDef {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    GRAPH_DEF_BRAND in value &&\n    (value as Record<string, unknown>)[GRAPH_DEF_BRAND] === true\n  );\n}\n\n/**\n * Gets all node kind names from a GraphDef.\n */\nexport function getNodeKinds<G extends GraphDef>(\n  graph: G,\n): readonly (keyof G[\"nodes\"] & string)[] {\n  return Object.keys(graph.nodes);\n}\n\n/**\n * Gets all edge kind names from a GraphDef.\n */\nexport function getEdgeKinds<G extends GraphDef>(\n  graph: G,\n): readonly (keyof G[\"edges\"] & string)[] {\n  return Object.keys(graph.edges);\n}\n\n/**\n * Returns true when `name` is registered as either a node or edge kind\n * on the given graph.\n */\nexport function isKnownKind(graph: GraphDef, name: string): boolean {\n  return Object.hasOwn(graph.nodes, name) || Object.hasOwn(graph.edges, name);\n}\n"]}