@nicia-ai/typegraph 0.24.1 → 0.25.0

package/dist/graph-extension/index.d.cts

@@ -0,0 +1,278 @@
+import { G as GraphExtension, K as KindEntity } from '../extension-types-D07e_NTw.cjs';
+export { h as CURRENT_GRAPH_EXTENSION_VERSION, s as ExtensionArrayItemType, t as ExtensionArrayProperty, u as ExtensionBooleanProperty, v as ExtensionEdgeDef, w as ExtensionEdgeIndex, x as ExtensionEmbeddingModifier, y as ExtensionEnumProperty, z as ExtensionIndex, B as ExtensionIndexWhere, F as ExtensionNodeDef, H as ExtensionNodeIndex, M as ExtensionNumberProperty, O as ExtensionObjectFieldProperty, P as ExtensionObjectProperty, Q as ExtensionOntologyRelation, R as ExtensionPropertyType, S as ExtensionSearchableModifier, V as ExtensionStringProperty, W as ExtensionUniqueConstraint, X as ExtensionUniqueWhere, Y as GRAPH_EXTENSION_TOP_LEVEL_KEYS, Z as GraphExtensionTopLevelKey, l as GraphExtensionVersion, L as LEGACY_GRAPH_EXTENSION_VERSION } from '../extension-types-D07e_NTw.cjs';
+import { T as TypeGraphError, h as ErrorCategory } from '../index-CT6nvtxL.cjs';
+import 'zod';
+import '../materialize-indexes-BB9N5uQl.cjs';
+
+/**
+ * Validates and freezes a graph-extension document.
+ *
+ * Authoring entry point — runs validation in **strict** mode: unknown
+ * top-level keys (e.g. `node` instead of `nodes`) and unsupported
+ * string formats (e.g. `"date-time"` with a hyphen instead of
+ * `"datetime"`) fail loudly with `UNKNOWN_DOCUMENT_KEY` /
+ * `UNSUPPORTED_STRING_FORMAT`. The persistence-load path leaves both
+ * checks off so a document committed by a future v1.x writer with
+ * additive fields still parses on an older v1 reader. Callers
+ * accepting raw JSON from an untyped source (e.g. an LLM proposal)
+ * should validate first via `validateGraphExtension` and surface
+ * the structured issues, then pass the validated document here.
+ *
+ * @param input - Document describing additional node kinds, edge
+ *   kinds, and ontology relations. Must satisfy the v1 property-type
+ *   subset documented in `ExtensionPropertyType`.
+ *
+ * @returns The same document, deeply frozen and shape-checked.
+ *
+ * @throws {GraphExtensionValidationError} when the document violates
+ *   the v1 property-type subset, references undeclared kinds, contains
+ *   ontology cycles, etc. The thrown error's `details.issues` array
+ *   carries every failure with a JSON-pointer path.
+ * @throws {GraphExtensionVersionUnsupportedError} when the document
+ *   declares a future major version this library cannot safely decode.
+ *
+ * @example
+ * ```typescript
+ * const extension = defineGraphExtension({
+ *   nodes: {
+ *     Paper: {
+ *       properties: {
+ *         doi:   { type: "string" },
+ *         title: { type: "string", searchable: { language: "english" } },
+ *       },
+ *       unique: [{ name: "paper_doi", fields: ["doi"] }],
+ *     },
+ *   },
+ * });
+ *
+ * const evolved = await store.evolve(extension);
+ * const papers = evolved.getNodeCollectionOrThrow("Paper");
+ * ```
+ */
+declare function defineGraphExtension(input: GraphExtension): GraphExtension;
+
+/**
+ * Errors raised across the graph-extension surface.
+ *
+ * Two flavours:
+ *
+ * - **Validation issues** (`GraphExtensionValidationError` +
+ *   `GraphExtensionIssue` / `GraphExtensionIssueCode`) — produced by
+ *   `validateGraphExtension`. The issue list batches every failure
+ *   with a JSON-pointer `path` so a UI can highlight every offending
+ *   field at once.
+ * - **Operation errors** (every other class in this file, all extending
+ *   `GraphExtensionError`) — thrown one at a time from `evolve`,
+ *   `removeKinds`, `materializeIndexes`, search, etc. Each carries a
+ *   stable string `code` for logging / serialization PLUS a typed
+ *   shape so consumers can `instanceof` for control flow.
+ */
+
+/**
+ * One specific issue raised during graph-extension validation.
+ */
+type GraphExtensionIssue = Readonly<{
+    /**
+     * JSON-pointer path to the offending value, rooted at the document
+     * (e.g. `/nodes/Paper/properties/title/pattern`). The empty string
+     * `""` means "the document itself".
+     */
+    path: string;
+    /** Human-readable explanation of the failure. */
+    message: string;
+    /**
+     * Stable machine-readable code so callers (and tests) can branch on
+     * specific failure modes without parsing messages. New codes are
+     * additive.
+     */
+    code: GraphExtensionIssueCode;
+}>;
+/**
+ * Stable machine codes for every validation failure produced by the
+ * document validator. New codes are additive — existing codes never
+ * change meaning.
+ *
+ * Note: codes here describe per-field validation problems. Operation-
+ * level errors (kind not found, version mismatch on persisted doc,
+ * compile-time-kind removal, etc.) surface as typed Error subclasses
+ * exported below — not as issue codes.
+ */
+/**
+ * Every issue code emitted by `validateGraphExtension`. Const-array form
+ * so tests, codegen, and runtime introspection can iterate the full set
+ * without restating it.
+ */
+declare const GRAPH_EXTENSION_ISSUE_CODES: readonly ["UNSUPPORTED_PROPERTY_TYPE", "INVALID_PROPERTY_REFINEMENT", "NESTED_ARRAY", "NESTED_OBJECT_TOO_DEEP", "INVALID_MODIFIER_TARGET", "INVALID_ENUM_VALUES", "INVALID_NUMBER_BOUNDS", "INVALID_LENGTH_BOUNDS", "INVALID_PATTERN", "INVALID_EMBEDDING_DIMENSIONS", "INVALID_SEARCHABLE_LANGUAGE", "RESERVED_PROPERTY_NAME", "INVALID_KIND_NAME", "DUPLICATE_KIND_NAME", "EMPTY_PROPERTIES", "EMPTY_FROM_OR_TO", "DUPLICATE_UNIQUE_CONSTRAINT", "EMPTY_UNIQUE_FIELDS", "DUPLICATE_UNIQUE_FIELD", "UNKNOWN_UNIQUE_FIELD", "INVALID_UNIQUE_WHERE_OP", "UNKNOWN_UNIQUE_WHERE_FIELD", "INVALID_ANNOTATION", "UNKNOWN_META_EDGE", "ONTOLOGY_CYCLE", "ONTOLOGY_SELF_LOOP", "ONTOLOGY_DISJOINT_CONFLICT", "DUPLICATE_ONTOLOGY_RELATION", "INVALID_DOCUMENT_SHAPE", "UNKNOWN_DOCUMENT_KEY", "UNSUPPORTED_STRING_FORMAT", "INVALID_INDEX_DECLARATION", "DUPLICATE_INDEX_NAME", "EMPTY_INDEX_FIELDS", "UNKNOWN_PROPERTY_KEY"];
+type GraphExtensionIssueCode = (typeof GRAPH_EXTENSION_ISSUE_CODES)[number];
+/**
+ * Base class for every graph-extension error. Consumers can catch
+ * the family with one `instanceof GraphExtensionError` check and
+ * branch on the concrete subclass beneath. Carries the same
+ * `code` / `category` / `details` slots as `TypeGraphError` so existing
+ * `isTypeGraphError` / `isUserRecoverable` helpers continue to apply.
+ */
+declare abstract class GraphExtensionError extends TypeGraphError {
+    readonly code: string;
+    protected constructor(spec: {
+        message: string;
+        code: string;
+        details: Readonly<Record<string, unknown>>;
+        suggestion: string;
+        category?: ErrorCategory;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when `validateGraphExtension` (or `defineGraphExtension`)
+ * rejects an input document for one or more shape/content reasons.
+ *
+ * The `issues` array carries every failure with a JSON-pointer
+ * `path`, so callers presenting the document to a human reviewer can
+ * highlight every offending field at once.
+ */
+declare class GraphExtensionValidationError extends GraphExtensionError {
+    readonly code: "GRAPH_EXTENSION_INVALID";
+    readonly issues: readonly GraphExtensionIssue[];
+    readonly details: Readonly<{
+        issues: readonly GraphExtensionIssue[];
+    }>;
+    constructor(issues: readonly GraphExtensionIssue[], cause?: unknown);
+}
+/**
+ * Thrown when an extension declares a kind whose name collides with an
+ * existing compile-time kind. The graph-extension contract is
+ * additive: graph-extension-declared kinds cannot shadow compile-time kinds.
+ */
+declare class KindCollisionError extends GraphExtensionError {
+    readonly code: "KIND_COLLISION";
+    readonly kindName: string;
+    readonly entity: KindEntity;
+    constructor(kindName: string, entity: KindEntity, graphId: string);
+}
+/**
+ * One classified delta in a `IncompatibleChangeError`.
+ *
+ * `field` is `undefined` for kind-level changes (e.g. tightening edge
+ * endpoints, adding a unique constraint to a populated kind). `detail`
+ * is human-readable and intended for surfaces showing the change to a
+ * reviewer (e.g. `"minLength: 5 → 10"`).
+ */
+/**
+ * Every incompatible-change classification produced by `evolve`'s
+ * delta classifier. Const-array form so tests and reviewer UIs can
+ * enumerate the set without restating it.
+ */
+declare const INCOMPATIBLE_CHANGE_TYPES: readonly ["REMOVE_PROPERTY", "ADD_REQUIRED_PROPERTY", "TIGHTEN_OPTIONALITY", "TIGHTEN_CONSTRAINT", "ADD_PATTERN", "CHANGE_PATTERN", "ADD_FORMAT", "CHANGE_FORMAT", "TIGHTEN_INT", "TIGHTEN_ENUM", "TYPE_CHANGE", "ADD_UNIQUE_ON_POPULATED", "TIGHTEN_EDGE_ENDPOINTS"];
+type IncompatibleChangeType = (typeof INCOMPATIBLE_CHANGE_TYPES)[number];
+type IncompatibleChange = Readonly<{
+    kind: string;
+    field?: string;
+    type: IncompatibleChangeType;
+    detail?: string;
+}>;
+/**
+ * Thrown when `evolve` rejects one or more deltas against an existing
+ * extension kind. Carries a structured `changes` list so a reviewer
+ * UI can show the incompatible deltas across every affected kind in
+ * one shot.
+ */
+declare class IncompatibleChangeError extends GraphExtensionError {
+    readonly code: "INCOMPATIBLE_CHANGE";
+    readonly changes: readonly IncompatibleChange[];
+    constructor(changes: readonly IncompatibleChange[], graphId: string);
+}
+/**
+ * Thrown when an extension's edge or ontology endpoint references a
+ * kind that exists in neither the extension nor the host graph.
+ * Distinct from `KindNotFoundError` because the cause is a
+ * stale persisted extension (a compile-time kind was removed from
+ * source after the extension was committed) rather than a
+ * call-site typo.
+ */
+declare class GraphExtensionUnresolvedEndpointError extends GraphExtensionError {
+    readonly code: "GRAPH_EXTENSION_UNRESOLVED_ENDPOINT";
+    readonly edgeKind: string;
+    readonly side: "from" | "to";
+    readonly endpoint: string;
+    constructor(edgeKind: string, side: "from" | "to", endpoint: string, graphId: string);
+}
+/**
+ * Thrown by `removeKinds` when the removal list contains a compile-
+ * time kind. Compile-time kinds are removed by recompiling and
+ * redeploying — persisting "removed-compile-time-kind" state in
+ * `schema_doc` is incoherent because the kind would resurrect on the
+ * next deploy.
+ */
+declare class RemoveCompileTimeKindError extends GraphExtensionError {
+    readonly code: "REMOVE_COMPILE_TIME_KIND";
+    readonly kindName: string;
+    readonly entity: KindEntity;
+    constructor(kindName: string, entity: KindEntity, graphId: string);
+}
+/**
+ * Thrown by `removeKinds` when a compile-time edge or ontology
+ * relation references the graph-extension kind being removed. Removing the
+ * kind would orphan compile-time references — incoherent at the next
+ * deploy.
+ */
+declare class KindHasReferentsError extends GraphExtensionError {
+    readonly code: "KIND_HAS_REFERENTS";
+    readonly kindName: string;
+    readonly referents: readonly KindReferent[];
+    constructor(kindName: string, referents: readonly KindReferent[], graphId: string);
+}
+type KindReferent = Readonly<{
+    type: "compile-time-edge" | "compile-time-ontology";
+    name: string;
+}>;
+/**
+ * Thrown when a persisted graph extension was authored against a
+ * higher major version of the graph-extension format than the
+ * current library supports. The library refuses to load it rather
+ * than risk silently misreading newer fields.
+ */
+declare class GraphExtensionVersionUnsupportedError extends GraphExtensionError {
+    readonly code: "GRAPH_EXTENSION_VERSION_UNSUPPORTED";
+    readonly persistedVersion: number;
+    readonly currentVersion: number;
+    constructor(persistedVersion: number, currentVersion: number);
+}
+
+/**
+ * Result type for error handling without exceptions.
+ * Use at service boundaries and for operations that can fail.
+ */
+type Result<T, E = Error> = Readonly<{
+    success: true;
+    data: T;
+}> | Readonly<{
+    success: false;
+    error: E;
+}>;
+
+type ValidateGraphExtensionOptions = Readonly<{
+    /**
+     * Reject unknown top-level keys and unsupported string formats.
+     * Used by `defineGraphExtension`, where the document is being
+     * authored fresh against the current library version — typos in
+     * `nodes` / `format: "date-time"` etc. should fail loudly. The
+     * persistence-load path leaves this off so a document committed by
+     * a future v1.x writer with additive fields still parses on an
+     * older v1 reader.
+     */
+    strict?: boolean;
+}>;
+/**
+ * Validates a graph extension.
+ *
+ * Returns the (frozen, deeply normalized) extension on success, or a
+ * `GraphExtensionValidationError` carrying every issue on authoring
+ * failure. Unsupported future major versions throw
+ * `GraphExtensionVersionUnsupportedError` immediately because the
+ * current library cannot safely decode the rest of the document.
+ * Callers that prefer exceptions for validation failures wrap the
+ * returned `Result` with `unwrap()`.
+ */
+declare function validateGraphExtension(input: unknown, options?: ValidateGraphExtensionOptions): Result<GraphExtension, GraphExtensionValidationError>;
+
+export { GRAPH_EXTENSION_ISSUE_CODES, GraphExtension, GraphExtensionError, type GraphExtensionIssue, type GraphExtensionIssueCode, GraphExtensionUnresolvedEndpointError, GraphExtensionValidationError, GraphExtensionVersionUnsupportedError, INCOMPATIBLE_CHANGE_TYPES, type IncompatibleChange, IncompatibleChangeError, type IncompatibleChangeType, KindCollisionError, KindHasReferentsError, type KindReferent, RemoveCompileTimeKindError, defineGraphExtension, validateGraphExtension };

package/dist/graph-extension/index.d.ts

@@ -0,0 +1,278 @@
+import { G as GraphExtension, K as KindEntity } from '../extension-types-D07e_NTw.js';
+export { h as CURRENT_GRAPH_EXTENSION_VERSION, s as ExtensionArrayItemType, t as ExtensionArrayProperty, u as ExtensionBooleanProperty, v as ExtensionEdgeDef, w as ExtensionEdgeIndex, x as ExtensionEmbeddingModifier, y as ExtensionEnumProperty, z as ExtensionIndex, B as ExtensionIndexWhere, F as ExtensionNodeDef, H as ExtensionNodeIndex, M as ExtensionNumberProperty, O as ExtensionObjectFieldProperty, P as ExtensionObjectProperty, Q as ExtensionOntologyRelation, R as ExtensionPropertyType, S as ExtensionSearchableModifier, V as ExtensionStringProperty, W as ExtensionUniqueConstraint, X as ExtensionUniqueWhere, Y as GRAPH_EXTENSION_TOP_LEVEL_KEYS, Z as GraphExtensionTopLevelKey, l as GraphExtensionVersion, L as LEGACY_GRAPH_EXTENSION_VERSION } from '../extension-types-D07e_NTw.js';
+import { T as TypeGraphError, h as ErrorCategory } from '../index-DQheiVQV.js';
+import 'zod';
+import '../materialize-indexes-BYpU2RKh.js';
+
+/**
+ * Validates and freezes a graph-extension document.
+ *
+ * Authoring entry point — runs validation in **strict** mode: unknown
+ * top-level keys (e.g. `node` instead of `nodes`) and unsupported
+ * string formats (e.g. `"date-time"` with a hyphen instead of
+ * `"datetime"`) fail loudly with `UNKNOWN_DOCUMENT_KEY` /
+ * `UNSUPPORTED_STRING_FORMAT`. The persistence-load path leaves both
+ * checks off so a document committed by a future v1.x writer with
+ * additive fields still parses on an older v1 reader. Callers
+ * accepting raw JSON from an untyped source (e.g. an LLM proposal)
+ * should validate first via `validateGraphExtension` and surface
+ * the structured issues, then pass the validated document here.
+ *
+ * @param input - Document describing additional node kinds, edge
+ *   kinds, and ontology relations. Must satisfy the v1 property-type
+ *   subset documented in `ExtensionPropertyType`.
+ *
+ * @returns The same document, deeply frozen and shape-checked.
+ *
+ * @throws {GraphExtensionValidationError} when the document violates
+ *   the v1 property-type subset, references undeclared kinds, contains
+ *   ontology cycles, etc. The thrown error's `details.issues` array
+ *   carries every failure with a JSON-pointer path.
+ * @throws {GraphExtensionVersionUnsupportedError} when the document
+ *   declares a future major version this library cannot safely decode.
+ *
+ * @example
+ * ```typescript
+ * const extension = defineGraphExtension({
+ *   nodes: {
+ *     Paper: {
+ *       properties: {
+ *         doi:   { type: "string" },
+ *         title: { type: "string", searchable: { language: "english" } },
+ *       },
+ *       unique: [{ name: "paper_doi", fields: ["doi"] }],
+ *     },
+ *   },
+ * });
+ *
+ * const evolved = await store.evolve(extension);
+ * const papers = evolved.getNodeCollectionOrThrow("Paper");
+ * ```
+ */
+declare function defineGraphExtension(input: GraphExtension): GraphExtension;
+
+/**
+ * Errors raised across the graph-extension surface.
+ *
+ * Two flavours:
+ *
+ * - **Validation issues** (`GraphExtensionValidationError` +
+ *   `GraphExtensionIssue` / `GraphExtensionIssueCode`) — produced by
+ *   `validateGraphExtension`. The issue list batches every failure
+ *   with a JSON-pointer `path` so a UI can highlight every offending
+ *   field at once.
+ * - **Operation errors** (every other class in this file, all extending
+ *   `GraphExtensionError`) — thrown one at a time from `evolve`,
+ *   `removeKinds`, `materializeIndexes`, search, etc. Each carries a
+ *   stable string `code` for logging / serialization PLUS a typed
+ *   shape so consumers can `instanceof` for control flow.
+ */
+
+/**
+ * One specific issue raised during graph-extension validation.
+ */
+type GraphExtensionIssue = Readonly<{
+    /**
+     * JSON-pointer path to the offending value, rooted at the document
+     * (e.g. `/nodes/Paper/properties/title/pattern`). The empty string
+     * `""` means "the document itself".
+     */
+    path: string;
+    /** Human-readable explanation of the failure. */
+    message: string;
+    /**
+     * Stable machine-readable code so callers (and tests) can branch on
+     * specific failure modes without parsing messages. New codes are
+     * additive.
+     */
+    code: GraphExtensionIssueCode;
+}>;
+/**
+ * Stable machine codes for every validation failure produced by the
+ * document validator. New codes are additive — existing codes never
+ * change meaning.
+ *
+ * Note: codes here describe per-field validation problems. Operation-
+ * level errors (kind not found, version mismatch on persisted doc,
+ * compile-time-kind removal, etc.) surface as typed Error subclasses
+ * exported below — not as issue codes.
+ */
+/**
+ * Every issue code emitted by `validateGraphExtension`. Const-array form
+ * so tests, codegen, and runtime introspection can iterate the full set
+ * without restating it.
+ */
+declare const GRAPH_EXTENSION_ISSUE_CODES: readonly ["UNSUPPORTED_PROPERTY_TYPE", "INVALID_PROPERTY_REFINEMENT", "NESTED_ARRAY", "NESTED_OBJECT_TOO_DEEP", "INVALID_MODIFIER_TARGET", "INVALID_ENUM_VALUES", "INVALID_NUMBER_BOUNDS", "INVALID_LENGTH_BOUNDS", "INVALID_PATTERN", "INVALID_EMBEDDING_DIMENSIONS", "INVALID_SEARCHABLE_LANGUAGE", "RESERVED_PROPERTY_NAME", "INVALID_KIND_NAME", "DUPLICATE_KIND_NAME", "EMPTY_PROPERTIES", "EMPTY_FROM_OR_TO", "DUPLICATE_UNIQUE_CONSTRAINT", "EMPTY_UNIQUE_FIELDS", "DUPLICATE_UNIQUE_FIELD", "UNKNOWN_UNIQUE_FIELD", "INVALID_UNIQUE_WHERE_OP", "UNKNOWN_UNIQUE_WHERE_FIELD", "INVALID_ANNOTATION", "UNKNOWN_META_EDGE", "ONTOLOGY_CYCLE", "ONTOLOGY_SELF_LOOP", "ONTOLOGY_DISJOINT_CONFLICT", "DUPLICATE_ONTOLOGY_RELATION", "INVALID_DOCUMENT_SHAPE", "UNKNOWN_DOCUMENT_KEY", "UNSUPPORTED_STRING_FORMAT", "INVALID_INDEX_DECLARATION", "DUPLICATE_INDEX_NAME", "EMPTY_INDEX_FIELDS", "UNKNOWN_PROPERTY_KEY"];
+type GraphExtensionIssueCode = (typeof GRAPH_EXTENSION_ISSUE_CODES)[number];
+/**
+ * Base class for every graph-extension error. Consumers can catch
+ * the family with one `instanceof GraphExtensionError` check and
+ * branch on the concrete subclass beneath. Carries the same
+ * `code` / `category` / `details` slots as `TypeGraphError` so existing
+ * `isTypeGraphError` / `isUserRecoverable` helpers continue to apply.
+ */
+declare abstract class GraphExtensionError extends TypeGraphError {
+    readonly code: string;
+    protected constructor(spec: {
+        message: string;
+        code: string;
+        details: Readonly<Record<string, unknown>>;
+        suggestion: string;
+        category?: ErrorCategory;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when `validateGraphExtension` (or `defineGraphExtension`)
+ * rejects an input document for one or more shape/content reasons.
+ *
+ * The `issues` array carries every failure with a JSON-pointer
+ * `path`, so callers presenting the document to a human reviewer can
+ * highlight every offending field at once.
+ */
+declare class GraphExtensionValidationError extends GraphExtensionError {
+    readonly code: "GRAPH_EXTENSION_INVALID";
+    readonly issues: readonly GraphExtensionIssue[];
+    readonly details: Readonly<{
+        issues: readonly GraphExtensionIssue[];
+    }>;
+    constructor(issues: readonly GraphExtensionIssue[], cause?: unknown);
+}
+/**
+ * Thrown when an extension declares a kind whose name collides with an
+ * existing compile-time kind. The graph-extension contract is
+ * additive: graph-extension-declared kinds cannot shadow compile-time kinds.
+ */
+declare class KindCollisionError extends GraphExtensionError {
+    readonly code: "KIND_COLLISION";
+    readonly kindName: string;
+    readonly entity: KindEntity;
+    constructor(kindName: string, entity: KindEntity, graphId: string);
+}
+/**
+ * One classified delta in a `IncompatibleChangeError`.
+ *
+ * `field` is `undefined` for kind-level changes (e.g. tightening edge
+ * endpoints, adding a unique constraint to a populated kind). `detail`
+ * is human-readable and intended for surfaces showing the change to a
+ * reviewer (e.g. `"minLength: 5 → 10"`).
+ */
+/**
+ * Every incompatible-change classification produced by `evolve`'s
+ * delta classifier. Const-array form so tests and reviewer UIs can
+ * enumerate the set without restating it.
+ */
+declare const INCOMPATIBLE_CHANGE_TYPES: readonly ["REMOVE_PROPERTY", "ADD_REQUIRED_PROPERTY", "TIGHTEN_OPTIONALITY", "TIGHTEN_CONSTRAINT", "ADD_PATTERN", "CHANGE_PATTERN", "ADD_FORMAT", "CHANGE_FORMAT", "TIGHTEN_INT", "TIGHTEN_ENUM", "TYPE_CHANGE", "ADD_UNIQUE_ON_POPULATED", "TIGHTEN_EDGE_ENDPOINTS"];
+type IncompatibleChangeType = (typeof INCOMPATIBLE_CHANGE_TYPES)[number];
+type IncompatibleChange = Readonly<{
+    kind: string;
+    field?: string;
+    type: IncompatibleChangeType;
+    detail?: string;
+}>;
+/**
+ * Thrown when `evolve` rejects one or more deltas against an existing
+ * extension kind. Carries a structured `changes` list so a reviewer
+ * UI can show the incompatible deltas across every affected kind in
+ * one shot.
+ */
+declare class IncompatibleChangeError extends GraphExtensionError {
+    readonly code: "INCOMPATIBLE_CHANGE";
+    readonly changes: readonly IncompatibleChange[];
+    constructor(changes: readonly IncompatibleChange[], graphId: string);
+}
+/**
+ * Thrown when an extension's edge or ontology endpoint references a
+ * kind that exists in neither the extension nor the host graph.
+ * Distinct from `KindNotFoundError` because the cause is a
+ * stale persisted extension (a compile-time kind was removed from
+ * source after the extension was committed) rather than a
+ * call-site typo.
+ */
+declare class GraphExtensionUnresolvedEndpointError extends GraphExtensionError {
+    readonly code: "GRAPH_EXTENSION_UNRESOLVED_ENDPOINT";
+    readonly edgeKind: string;
+    readonly side: "from" | "to";
+    readonly endpoint: string;
+    constructor(edgeKind: string, side: "from" | "to", endpoint: string, graphId: string);
+}
+/**
+ * Thrown by `removeKinds` when the removal list contains a compile-
+ * time kind. Compile-time kinds are removed by recompiling and
+ * redeploying — persisting "removed-compile-time-kind" state in
+ * `schema_doc` is incoherent because the kind would resurrect on the
+ * next deploy.
+ */
+declare class RemoveCompileTimeKindError extends GraphExtensionError {
+    readonly code: "REMOVE_COMPILE_TIME_KIND";
+    readonly kindName: string;
+    readonly entity: KindEntity;
+    constructor(kindName: string, entity: KindEntity, graphId: string);
+}
+/**
+ * Thrown by `removeKinds` when a compile-time edge or ontology
+ * relation references the graph-extension kind being removed. Removing the
+ * kind would orphan compile-time references — incoherent at the next
+ * deploy.
+ */
+declare class KindHasReferentsError extends GraphExtensionError {
+    readonly code: "KIND_HAS_REFERENTS";
+    readonly kindName: string;
+    readonly referents: readonly KindReferent[];
+    constructor(kindName: string, referents: readonly KindReferent[], graphId: string);
+}
+type KindReferent = Readonly<{
+    type: "compile-time-edge" | "compile-time-ontology";
+    name: string;
+}>;
+/**
+ * Thrown when a persisted graph extension was authored against a
+ * higher major version of the graph-extension format than the
+ * current library supports. The library refuses to load it rather
+ * than risk silently misreading newer fields.
+ */
+declare class GraphExtensionVersionUnsupportedError extends GraphExtensionError {
+    readonly code: "GRAPH_EXTENSION_VERSION_UNSUPPORTED";
+    readonly persistedVersion: number;
+    readonly currentVersion: number;
+    constructor(persistedVersion: number, currentVersion: number);
+}
+
+/**
+ * Result type for error handling without exceptions.
+ * Use at service boundaries and for operations that can fail.
+ */
+type Result<T, E = Error> = Readonly<{
+    success: true;
+    data: T;
+}> | Readonly<{
+    success: false;
+    error: E;
+}>;
+
+type ValidateGraphExtensionOptions = Readonly<{
+    /**
+     * Reject unknown top-level keys and unsupported string formats.
+     * Used by `defineGraphExtension`, where the document is being
+     * authored fresh against the current library version — typos in
+     * `nodes` / `format: "date-time"` etc. should fail loudly. The
+     * persistence-load path leaves this off so a document committed by
+     * a future v1.x writer with additive fields still parses on an
+     * older v1 reader.
+     */
+    strict?: boolean;
+}>;
+/**
+ * Validates a graph extension.
+ *
+ * Returns the (frozen, deeply normalized) extension on success, or a
+ * `GraphExtensionValidationError` carrying every issue on authoring
+ * failure. Unsupported future major versions throw
+ * `GraphExtensionVersionUnsupportedError` immediately because the
+ * current library cannot safely decode the rest of the document.
+ * Callers that prefer exceptions for validation failures wrap the
+ * returned `Result` with `unwrap()`.
+ */
+declare function validateGraphExtension(input: unknown, options?: ValidateGraphExtensionOptions): Result<GraphExtension, GraphExtensionValidationError>;
+
+export { GRAPH_EXTENSION_ISSUE_CODES, GraphExtension, GraphExtensionError, type GraphExtensionIssue, type GraphExtensionIssueCode, GraphExtensionUnresolvedEndpointError, GraphExtensionValidationError, GraphExtensionVersionUnsupportedError, INCOMPATIBLE_CHANGE_TYPES, type IncompatibleChange, IncompatibleChangeError, type IncompatibleChangeType, KindCollisionError, KindHasReferentsError, type KindReferent, RemoveCompileTimeKindError, defineGraphExtension, validateGraphExtension };

package/dist/graph-extension/index.js

@@ -0,0 +1,6 @@
+export { defineGraphExtension } from '../chunk-NHQWXSTS.js';
+export { CURRENT_GRAPH_EXTENSION_VERSION, GRAPH_EXTENSION_ISSUE_CODES, GRAPH_EXTENSION_TOP_LEVEL_KEYS, GraphExtensionError, GraphExtensionUnresolvedEndpointError, GraphExtensionValidationError, GraphExtensionVersionUnsupportedError, INCOMPATIBLE_CHANGE_TYPES, IncompatibleChangeError, KindCollisionError, KindHasReferentsError, LEGACY_GRAPH_EXTENSION_VERSION, RemoveCompileTimeKindError, validateGraphExtension } from '../chunk-4BOWVUGQ.js';
+import '../chunk-DOTEN2FG.js';
+import '../chunk-NZ5PMBTG.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/graph-extension/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}