@nicia-ai/typegraph 0.24.1 → 0.25.0

package/dist/extension-types-D07e_NTw.d.cts

@@ -0,0 +1,543 @@
+import { z } from 'zod';
+
+/**
+ * Which side of the bipartite graph a kind lives on. Used everywhere a
+ * function takes "the entity that owns a kind" — error metadata,
+ * extension classifiers, removal queues, schema diffs.
+ */
+type KindEntity = "node" | "edge";
+/**
+ * Which physical surface an index targets. Vector indexes don't own a
+ * kind directly (they're partial indexes on `typegraph_node_embeddings`
+ * scoped by node-kind), but they participate in the same materialization
+ * and diff pipelines, so they share this discriminator.
+ */
+type IndexEntity = "node" | "edge" | "vector";
+/**
+ * Field-level null-check operations that round-trip through persisted
+ * documents (unique-constraint where clauses, index where clauses,
+ * graph-extension where clauses, IsNullPredicate). Consolidated so a
+ * single rename or extension touches one site.
+ */
+type NullCheckOp = "isNull" | "isNotNull";
+/** Brand key for NodeType */
+declare const NODE_TYPE_BRAND: "__nodeType";
+/** Brand key for EdgeType */
+declare const EDGE_TYPE_BRAND: "__edgeType";
+/** Brand symbol for NodeId */
+declare const __nodeId: unique symbol;
+/** Brand symbol for EdgeId */
+declare const __edgeId: unique symbol;
+/**
+ * Any JSON-serializable value.
+ *
+ * Mirrors the JSON wire format: primitives, arrays, and string-keyed objects.
+ * `null` is included because the JSON spec requires it for "no value here";
+ * this is the one place in the public API that uses `null` over `undefined`.
+ */
+type JsonValue = null | string | number | boolean | readonly JsonValue[] | Readonly<{
+    [key: string]: JsonValue;
+}>;
+/**
+ * Consumer-owned per-kind annotations.
+ *
+ * Stable labels attached to a node or edge kind at definition time — UI hints,
+ * audit policy, provenance pointers, tooling annotations.
+ *
+ * **Consumer-owned, fully.** TypeGraph never reads, validates, or interprets
+ * values in this field. Consumers own the entire namespace; there are no
+ * reserved keys or extension prefixes. Future library-owned per-kind state,
+ * if needed, will use a separate sibling field rather than carving out keys
+ * here.
+ *
+ * **Annotations participate in schema hashing.** Any change to an annotation
+ * value (or adding/removing an annotation key) bumps the canonical schema
+ * hash and is reported as a `safe`-severity diff by `getSchemaChanges`. If
+ * you don't want versioning for a piece of state, do not put it here.
+ *
+ * Values must be JSON-serializable — `bigint`, `function`, `symbol`, `undefined`,
+ * `Date`, and other class instances are rejected at definition time so they can
+ * never silently break schema hashing or storage round-trips.
+ */
+type KindAnnotations = Readonly<Record<string, JsonValue>>;
+/**
+ * A node type definition.
+ *
+ * Created via `defineNode()`. Represents a type of node in the graph
+ * with an associated Zod schema for properties.
+ */
+type NodeType<K extends string = string, S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> = Readonly<{
+    [NODE_TYPE_BRAND]: true;
+    kind: K;
+    schema: S;
+    description: string | undefined;
+    annotations: KindAnnotations | undefined;
+}>;
+/**
+ * Branded node ID type.
+ *
+ * Prevents mixing IDs from different node types at compile time.
+ */
+type NodeId<N extends NodeType> = string & Readonly<{
+    [__nodeId]: N;
+}>;
+/**
+ * Infer the props type from a NodeType.
+ */
+type NodeProps<N extends NodeType> = z.infer<N["schema"]>;
+/**
+ * An edge type definition.
+ *
+ * Created via `defineEdge()`. Represents a type of edge in the graph
+ * with an optional Zod schema for properties.
+ *
+ * Optionally includes `from` and `to` arrays that define the allowed
+ * source and target node types (domain and range constraints).
+ */
+type EdgeType<K extends string = string, S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, From extends readonly NodeType[] | undefined = undefined, To extends readonly NodeType[] | undefined = undefined> = Readonly<{
+    [EDGE_TYPE_BRAND]: true;
+    kind: K;
+    schema: S;
+    description: string | undefined;
+    annotations: KindAnnotations | undefined;
+    from: From;
+    to: To;
+}>;
+/**
+ * Base edge type for use in constraints - accepts any from/to configuration.
+ */
+type AnyEdgeType = EdgeType<string, z.ZodObject<z.ZodRawShape>, readonly NodeType[] | undefined, readonly NodeType[] | undefined>;
+/**
+ * An edge type that has both from and to constraints defined.
+ * Can be used directly in defineGraph without an EdgeRegistration wrapper.
+ */
+type EdgeTypeWithEndpoints = EdgeType<string, z.ZodObject<z.ZodRawShape>, readonly NodeType[], readonly NodeType[]>;
+/**
+ * Branded edge ID type.
+ *
+ * Prevents mixing IDs from different edge types at compile time.
+ */
+type EdgeId<E extends AnyEdgeType = AnyEdgeType> = string & Readonly<{
+    [__edgeId]: E;
+}>;
+/**
+ * Infer the props type from an EdgeType.
+ */
+type EdgeProps<E extends AnyEdgeType> = z.infer<E["schema"]>;
+/**
+ * Delete behaviors for nodes.
+ */
+type DeleteBehavior = "restrict" | "cascade" | "disconnect";
+/**
+ * Edge cardinality constraints.
+ */
+type Cardinality = "many" | "one" | "unique" | "oneActive";
+/**
+ * Endpoint existence modes for edge validation.
+ */
+type EndpointExistence = "notDeleted" | "currentlyValid" | "ever";
+/**
+ * Temporal query modes.
+ */
+type TemporalMode = "current" | "asOf" | "includeEnded" | "includeTombstones";
+/**
+ * Uniqueness constraint scope.
+ */
+type UniquenessScope = "kind" | "kindWithSubClasses";
+/**
+ * Collation for uniqueness constraints.
+ */
+type Collation = "binary" | "caseInsensitive";
+/**
+ * Uniqueness constraint definition.
+ */
+type UniqueConstraint<S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> = Readonly<{
+    name: string;
+    fields: readonly (keyof z.infer<S> & string)[];
+    where?: (props: UniqueConstraintPredicateBuilder<S>) => UniqueConstraintPredicate;
+    scope: UniquenessScope;
+    collation: Collation;
+}>;
+/**
+ * Predicate builder for uniqueness constraint where clause.
+ * Uses -? to make all fields required in the builder, even if optional in the schema.
+ */
+type UniqueConstraintPredicateBuilder<S extends z.ZodObject<z.ZodRawShape>> = Readonly<{
+    [K in keyof z.infer<S>]-?: UniqueConstraintField;
+}>;
+/**
+ * Field operations for uniqueness constraint predicates.
+ */
+type UniqueConstraintField = Readonly<{
+    isNull: () => UniqueConstraintPredicate;
+    isNotNull: () => UniqueConstraintPredicate;
+}>;
+/**
+ * A uniqueness constraint predicate (internal representation).
+ */
+type UniqueConstraintPredicate = Readonly<{
+    __type: "unique_predicate";
+    field: string;
+    op: NullCheckOp;
+}>;
+/**
+ * Node registration in a graph definition.
+ */
+type NodeRegistration<N extends NodeType = NodeType> = Readonly<{
+    type: N;
+    unique?: readonly UniqueConstraint<N["schema"]>[];
+    onDelete?: DeleteBehavior;
+}>;
+/**
+ * Edge registration in a graph definition.
+ */
+type EdgeRegistration<E extends AnyEdgeType = AnyEdgeType, FromTypes extends NodeType = NodeType, ToTypes extends NodeType = NodeType> = Readonly<{
+    type: E;
+    from: readonly FromTypes[];
+    to: readonly ToTypes[];
+    cardinality?: Cardinality;
+    endpointExistence?: EndpointExistence;
+}>;
+/**
+ * Default settings for a graph.
+ */
+type GraphDefaults = Readonly<{
+    onNodeDelete?: DeleteBehavior;
+    temporalMode?: TemporalMode;
+}>;
+/**
+ * Checks if a value is a NodeType.
+ */
+declare function isNodeType(value: unknown): value is NodeType;
+/**
+ * Checks if a value is an EdgeType.
+ */
+declare function isEdgeType(value: unknown): value is AnyEdgeType;
+/**
+ * Checks if a value is an EdgeType with both from and to constraints defined.
+ * Such edges can be used directly in defineGraph without an EdgeRegistration wrapper.
+ */
+declare function isEdgeTypeWithEndpoints(value: unknown): value is EdgeTypeWithEndpoints;
+
+declare const ALL_META_EDGE_NAMES: readonly ["subClassOf", "broader", "narrower", "relatedTo", "equivalentTo", "sameAs", "differentFrom", "disjointWith", "partOf", "hasPart", "inverseOf", "implies"];
+type MetaEdgeName = (typeof ALL_META_EDGE_NAMES)[number];
+
+/**
+ * Pure-value document format for graph extensions.
+ *
+ * A `GraphExtension` is a plain JSON-serializable description of
+ * additional node kinds, edge kinds, and ontology relations that should
+ * be merged into a graph at runtime. The document is the canonical
+ * artifact: every restart re-compiles it back to the same Zod-bearing
+ * `NodeType` / `EdgeType` / `OntologyRelation` shapes.
+ *
+ * The supported property-type subset is intentionally narrower than full
+ * JSON Schema — only what compiles cleanly to Zod and what real
+ * agent-induced schemas use in practice. Anything outside this set fails
+ * loudly at `defineGraphExtension(...)`.
+ */
+
+/**
+ * Per-property modifier: tag the field as fulltext-searchable.
+ *
+ * Compiles to a `searchable({ language })`-wrapped Zod string when applied
+ * to a `string` property. Rejected on any other property type at validation
+ * time.
+ */
+type ExtensionSearchableModifier = Readonly<{
+    language?: string;
+}>;
+/**
+ * Per-property modifier: declare a vector embedding with the given
+ * dimensionality. Compiles to `embedding(dimensions)` and is only valid on
+ * `array` properties whose item type is `number`. Rejected elsewhere.
+ */
+type ExtensionEmbeddingModifier = Readonly<{
+    dimensions: number;
+}>;
+/**
+ * Modifiers shared by every graph-extension property type.
+ *
+ * `optional: true` flips the field from required-with-graph-extension-validation
+ * to `.optional()` and removes it from the parent object's `required`
+ * list. `searchable` and `embedding` only apply to specific underlying
+ * types — see the per-modifier docs.
+ */
+type ExtensionPropertyModifiers = Readonly<{
+    optional?: boolean;
+    searchable?: ExtensionSearchableModifier;
+    embedding?: ExtensionEmbeddingModifier;
+    description?: string;
+}>;
+/**
+ * String property. Compiles to `z.string()` plus the requested refinements.
+ * `format` accepts the two formats motivated by induced schemas in
+ * practice — covers ISO datetimes, URIs, email addresses, UUIDs, and
+ * date-only strings. Each format routes to the corresponding Zod
+ * factory (`z.iso.datetime()`, `z.url()`, `z.email()`, `z.uuid()`,
+ * `z.iso.date()`); other JSON-Schema formats are deliberately not
+ * supported in v1.
+ */
+type ExtensionStringProperty = Readonly<{
+    type: "string";
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: "datetime" | "uri" | "email" | "uuid" | "date";
+}> & ExtensionPropertyModifiers;
+/**
+ * Number property. `int: true` requires whole numbers; `min` / `max` are
+ * inclusive bounds. Compiles to `z.number().int()?.min(...)?.max(...)`.
+ */
+type ExtensionNumberProperty = Readonly<{
+    type: "number";
+    min?: number;
+    max?: number;
+    int?: boolean;
+}> & ExtensionPropertyModifiers;
+/**
+ * Boolean property. Compiles to `z.boolean()`.
+ */
+type ExtensionBooleanProperty = Readonly<{
+    type: "boolean";
+}> & ExtensionPropertyModifiers;
+/**
+ * Closed-set string enum. Compiles to `z.enum([...values])`. Must contain
+ * at least one value; duplicate values are rejected at validation time.
+ */
+type ExtensionEnumProperty = Readonly<{
+    type: "enum";
+    values: readonly string[];
+}> & ExtensionPropertyModifiers;
+/**
+ * Array property. `items` is any of the scalar property types or an
+ * object property — nested arrays are forbidden in v1. Compiles to
+ * `z.array(<items>)`. The `embedding` modifier turns this into a
+ * vector embedding instead of a generic array.
+ */
+type ExtensionArrayProperty = Readonly<{
+    type: "array";
+    items: ExtensionArrayItemType;
+}> & ExtensionPropertyModifiers;
+/**
+ * Element types allowed inside an array — every leaf property type plus
+ * single-level object. Nesting an array inside an array is rejected at
+ * validation time so the v1 surface stays a flat tree.
+ */
+type ExtensionArrayItemType = ExtensionStringProperty | ExtensionNumberProperty | ExtensionBooleanProperty | ExtensionEnumProperty | ExtensionObjectProperty;
+/**
+ * Object property. `properties` is a single nesting level; deeper objects
+ * are rejected at validation time so the v1 surface is auditable at a
+ * glance.
+ */
+type ExtensionObjectProperty = Readonly<{
+    type: "object";
+    properties: Readonly<Record<string, ExtensionObjectFieldProperty>>;
+}> & ExtensionPropertyModifiers;
+/**
+ * Property types allowed inside an `object`'s `properties` — leaf scalars
+ * and arrays only. Nested objects are blocked here to enforce the
+ * single-nesting-level rule.
+ */
+type ExtensionObjectFieldProperty = ExtensionStringProperty | ExtensionNumberProperty | ExtensionBooleanProperty | ExtensionEnumProperty | ExtensionArrayProperty;
+/**
+ * Top-level property descriptor for a node or edge field.
+ *
+ * The discriminated union covers every type in the v1 subset; arbitrary
+ * `unknown` inputs are validated against this set at
+ * `defineGraphExtension(...)` time.
+ */
+type ExtensionPropertyType = ExtensionStringProperty | ExtensionNumberProperty | ExtensionBooleanProperty | ExtensionEnumProperty | ExtensionArrayProperty | ExtensionObjectProperty;
+/**
+ * Document-side `where` clause for a unique constraint.
+ *
+ * Mirrors `serializeWherePredicate`'s capability — the only operations
+ * round-trippable through the persisted form are `isNull` and `isNotNull`.
+ * Anything richer (equality, `in`, etc.) is rejected at validation time.
+ */
+type ExtensionUniqueWhere = Readonly<{
+    field: string;
+    op: NullCheckOp;
+}>;
+/**
+ * Unique constraint declaration. `fields` must reference declared
+ * properties on the kind. Defaults match the existing `UniqueConstraint`:
+ * `scope: "kind"`, `collation: "binary"`.
+ */
+type ExtensionUniqueConstraint = Readonly<{
+    name: string;
+    fields: readonly string[];
+    scope?: "kind" | "kindWithSubClasses";
+    collation?: "binary" | "caseInsensitive";
+    where?: ExtensionUniqueWhere;
+}>;
+/**
+ * Graph-extension declaration of a node kind.
+ *
+ * Property names follow the same reserved-key rules as compile-time
+ * `defineNode` (`id`, `kind`, `meta`, and the `$`-prefix accessor
+ * namespace are forbidden). Annotation values must be JSON.
+ */
+type ExtensionNodeDef = Readonly<{
+    description?: string;
+    annotations?: KindAnnotations;
+    properties: Readonly<Record<string, ExtensionPropertyType>>;
+    unique?: readonly ExtensionUniqueConstraint[];
+}>;
+/**
+ * Graph-extension declaration of an edge kind.
+ *
+ * `from` / `to` reference node kind names — either kinds declared in this
+ * same document or compile-time kinds the document is being merged into.
+ * Endpoints that resolve to nothing within the document are flagged as
+ * soft references at validation time but not rejected; the final
+ * cross-graph check happens when the document is merged into a host
+ * `GraphDef`.
+ */
+type ExtensionEdgeDef = Readonly<{
+    description?: string;
+    annotations?: KindAnnotations;
+    from: readonly string[];
+    to: readonly string[];
+    properties?: Readonly<Record<string, ExtensionPropertyType>>;
+}>;
+/**
+ * Document-level analogue of compile-time `defineNodeIndex` /
+ * `defineEdgeIndex`. Mirrors `serializeWherePredicate`'s persistence-
+ * round-trippable subset: only `isNull` / `isNotNull` predicates are
+ * supported in v1, matching `ExtensionUniqueWhere`.
+ */
+type ExtensionIndexWhere = Readonly<{
+    field: string;
+    op: NullCheckOp;
+}>;
+/**
+ * Graph-extension-declared node index. `kind` references either a kind
+ * declared in this same document or a compile-time host kind resolved
+ * at merge time. `fields` and `coveringFields` are top-level property
+ * names — JSON-pointer paths are not supported in v1, matching the
+ * `ExtensionUniqueConstraint` v1 surface.
+ */
+type ExtensionNodeIndex = Readonly<{
+    entity: "node";
+    kind: string;
+    name?: string;
+    fields: readonly string[];
+    coveringFields?: readonly string[];
+    unique?: boolean;
+    scope?: "graphAndKind" | "graph" | "none";
+    where?: ExtensionIndexWhere;
+}>;
+/**
+ * Graph-extension-declared edge index. `direction` mirrors
+ * `EdgeIndexDirection`; `kind` references a graph-extension or compile-time
+ * edge kind.
+ */
+type ExtensionEdgeIndex = Readonly<{
+    entity: "edge";
+    kind: string;
+    name?: string;
+    direction?: "out" | "in" | "none";
+    fields: readonly string[];
+    coveringFields?: readonly string[];
+    unique?: boolean;
+    scope?: "graphAndKind" | "graph" | "none";
+    where?: ExtensionIndexWhere;
+}>;
+type ExtensionIndex = ExtensionNodeIndex | ExtensionEdgeIndex;
+/**
+ * Graph-extension ontology relation. `metaEdge` is one of the built-in
+ * meta-edge names (subClassOf, broader, disjointWith, etc.).
+ *
+ * `from` / `to` are either node-kind names declared in this document or
+ * external IRI strings. The pure-value document does not distinguish the
+ * two — the compiler treats endpoints that match a declared kind as
+ * `NodeType` references and falls back to passing the raw string for
+ * IRIs (matching the existing `OntologyRelation` shape, where
+ * `from`/`to` are `NodeType | EdgeType | string`).
+ */
+type ExtensionOntologyRelation = Readonly<{
+    metaEdge: MetaEdgeName;
+    from: string;
+    to: string;
+}>;
+/**
+ * Stable default major used when a stored document omits `version`.
+ *
+ * Pinned to `1` permanently. Pre-versioning documents (those persisted
+ * before the field existed) and documents that explicitly omit
+ * `version` are interpreted as `1` regardless of which major the
+ * library currently supports. Splitting this from
+ * `CURRENT_GRAPH_EXTENSION_VERSION` is load-bearing for future major
+ * bumps: when v2 ships, `CURRENT` becomes `2` but `LEGACY` stays at
+ * `1`, so a v1-era stored document still parses as v1 (and the
+ * version-mismatch path can route it through a migration) rather than
+ * being silently misinterpreted as v2.
+ */
+declare const LEGACY_GRAPH_EXTENSION_VERSION: 1;
+/**
+ * Current major version of the `GraphExtension` format.
+ *
+ * Documents with a higher major version than this constant are
+ * rejected with `GRAPH_EXTENSION_VERSION_UNSUPPORTED` — there is no
+ * automatic downgrade path. Minor / additive changes ride forward-
+ * compat via `.loose()` on every nested object schema.
+ */
+declare const CURRENT_GRAPH_EXTENSION_VERSION: 1;
+/**
+ * Type of the `GraphExtension.version` field. Stays `number`
+ * rather than `typeof CURRENT_GRAPH_EXTENSION_VERSION` because the
+ * field can carry any major across the library version range a
+ * stored document might have been written by — the
+ * document-vs-supported check happens in the validator, not at the
+ * type level. Pinning to the current literal would prevent a v1
+ * v1 library from typing a v2 document at all, which is the wrong
+ * relationship: we WANT a v1 library to receive v2 documents and
+ * report `GRAPH_EXTENSION_VERSION_UNSUPPORTED` cleanly.
+ */
+type GraphExtensionVersion = number;
+/**
+ * The canonical pure-value graph-extension document.
+ *
+ * Frozen at construction. Round-trips losslessly through `JSON.stringify`
+ * / `JSON.parse`; the `GraphExtension → CompiledExtension` direction
+ * is provided by `compileGraphExtension(...)`. There is no
+ * `Zod → GraphExtension` direction because graph-extension kinds always
+ * originate as documents.
+ *
+ * `version` is the major-version tag for the document format. The
+ * compiler accepts documents whose version is equal to the current
+ * supported major (today: 1) or absent (the canonical persisted form
+ * omits `version` when it equals the legacy default — see
+ * `serializer.ts` — so the round-trip default is "absent means legacy
+ * major"). Higher majors surface as
+ * `GRAPH_EXTENSION_VERSION_UNSUPPORTED` so a newer-version extension
+ * committed by a future writer can't be silently misread by an older
+ * runtime. See `graph-extensions.md` for the format-versioning policy.
+ */
+type GraphExtension = Readonly<{
+    version?: GraphExtensionVersion;
+    nodes?: Readonly<Record<string, ExtensionNodeDef>>;
+    edges?: Readonly<Record<string, ExtensionEdgeDef>>;
+    ontology?: readonly ExtensionOntologyRelation[];
+    /**
+     * Graph-extension-declared relational indexes. Each entry references a
+     * node or edge kind by name — either declared in this document or
+     * a compile-time host kind that the document is being merged into.
+     * Vector indexes auto-derive from `embedding()` modifiers on
+     * graph-extension kinds; this slot is for explicit relational indexes
+     * (analogue of compile-time `defineGraph({ indexes: [...] })`).
+     */
+    indexes?: readonly ExtensionIndex[];
+}>;
+/**
+ * Top-level v1 slots a `GraphExtension` document may carry. Single
+ * source of truth for both the strict-authoring validator (typo rejection
+ * via `defineGraphExtension`) and the persistence Zod schema (which
+ * leaves the field set loose for forward compatibility but uses this
+ * list to drive the Zod object shape).
+ */
+declare const GRAPH_EXTENSION_TOP_LEVEL_KEYS: readonly ["version", "nodes", "edges", "ontology", "indexes"];
+type GraphExtensionTopLevelKey = (typeof GRAPH_EXTENSION_TOP_LEVEL_KEYS)[number];
+
+export { type AnyEdgeType as A, type ExtensionIndexWhere as B, type Collation as C, type DeleteBehavior as D, type EdgeRegistration as E, type ExtensionNodeDef as F, type GraphExtension as G, type ExtensionNodeIndex as H, type IndexEntity as I, type JsonValue as J, type KindEntity as K, LEGACY_GRAPH_EXTENSION_VERSION as L, type ExtensionNumberProperty as M, type NodeType as N, type ExtensionObjectFieldProperty as O, type ExtensionObjectProperty as P, type ExtensionOntologyRelation as Q, type ExtensionPropertyType as R, type ExtensionSearchableModifier as S, type TemporalMode as T, type UniquenessScope as U, type ExtensionStringProperty as V, type ExtensionUniqueConstraint as W, type ExtensionUniqueWhere as X, GRAPH_EXTENSION_TOP_LEVEL_KEYS as Y, type GraphExtensionTopLevelKey as Z, type NullCheckOp as a, type NodeRegistration as b, type GraphDefaults as c, type EdgeType as d, type KindAnnotations as e, type Cardinality as f, type EndpointExistence as g, CURRENT_GRAPH_EXTENSION_VERSION as h, type EdgeId as i, type EdgeProps as j, type EdgeTypeWithEndpoints as k, type GraphExtensionVersion as l, type NodeId as m, type NodeProps as n, type UniqueConstraint as o, isEdgeType as p, isEdgeTypeWithEndpoints as q, isNodeType as r, type ExtensionArrayItemType as s, type ExtensionArrayProperty as t, type ExtensionBooleanProperty as u, type ExtensionEdgeDef as v, type ExtensionEdgeIndex as w, type ExtensionEmbeddingModifier as x, type ExtensionEnumProperty as y, type ExtensionIndex as z };