@nicia-ai/typegraph 0.24.1 → 0.25.0

package/dist/{index-DXkEXpNz.d.ts → index-CT6nvtxL.d.cts}

@@ -1,3 +1,6 @@
+import { K as KindEntity } from './extension-types-D07e_NTw.cjs';
+import { M as MaterializeIndexesResult } from './materialize-indexes-BB9N5uQl.cjs';
+
 /**
  * TypeGraph Error Hierarchy
  *
@@ -21,6 +24,7 @@
  * }
  * ```
  */
+
 /**
  * Error category for programmatic handling.
  *
@@ -83,7 +87,7 @@ type ValidationIssue = Readonly<{
  */
 type ValidationErrorDetails = Readonly<{
     /** Type of entity being validated */
-    entityType?: "node" | "edge";
+    entityType?: KindEntity;
     /** Kind/type name of the entity */
     kind?: string;
     /** Operation being performed */
@@ -143,12 +147,22 @@ declare class EdgeNotFoundError extends TypeGraphError {
     });
 }
 /**
- * Thrown when a kind is not found in the graph registry.
+ * Thrown when an operation references a kind that isn't registered on
+ * the graph — `getNodeCollectionOrThrow` against an unknown kind, a
+ * `materializeIndexes({ kinds })` filter naming a missing kind, an
+ * extension referencing an unresolved endpoint, search facade typos,
+ * etc. Carries the offending `kindName` and `entity` plus the host
+ * `graphId` so logs are unambiguous when multiple stores share a
+ * process.
  */
 declare class KindNotFoundError extends TypeGraphError {
-    constructor(kind: string, type: "node" | "edge", options?: {
+    readonly kindName: string;
+    readonly entity: KindEntity;
+    constructor(kindName: string, entity: KindEntity, options?: Readonly<{
+        graphId?: string;
+        suggestion?: string;
         cause?: unknown;
-    });
+    }>);
 }
 /**
  * Thrown when a uniqueness constraint name is not found on a node kind.
@@ -281,6 +295,101 @@ declare class MigrationError extends TypeGraphError {
         cause?: unknown;
     });
 }
+/**
+ * Thrown by `Store.evolve(extension, { eager })` when the schema
+ * commit succeeded but the follow-on `materializeIndexes()` produced
+ * one or more failed entries.
+ *
+ * Recovery: the schema commit is NOT rolled back. The new `Store` is
+ * fully constructed and (when `options.ref` was supplied) `ref.current`
+ * already points to it — the caller can read the new store via the ref
+ * and decide how to handle the failed indexes (retry, skip, alert).
+ * The full `MaterializeIndexesResult` is attached as `.materialization`.
+ *
+ * @example
+ * ```ts
+ * const ref = { current: store };
+ * try {
+ *   await store.evolve(extension, { ref, eager: {} });
+ * } catch (error) {
+ *   if (error instanceof EagerMaterializationError) {
+ *     // schema is committed; ref.current is the new store
+ *     log.warn(
+ *       { failed: error.failedIndexNames },
+ *       "indexes did not materialize; will retry",
+ *     );
+ *     await ref.current.materializeIndexes();
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+declare class EagerMaterializationError extends TypeGraphError {
+    /**
+     * The full materialization result, including successful and failed
+     * entries. Same shape as `Store.materializeIndexes()` returns.
+     */
+    readonly materialization: MaterializeIndexesResult;
+    constructor(materialization: MaterializeIndexesResult, graphId: string);
+    /**
+     * Names of just the indexes that failed — derived from
+     * `materialization.results` so the two views can never disagree.
+     */
+    get failedIndexNames(): readonly string[];
+}
+/**
+ * Thrown by `commitSchemaVersion` and `setActiveVersion` when the
+ * caller's view of the active schema version is out of date — another
+ * writer has already advanced it.
+ *
+ * Recovery: re-read the active version with `getActiveSchema(graphId)`,
+ * recompute against the new baseline, and retry. This is a routine
+ * concurrency signal, not a bug.
+ *
+ * `actual` is `0` when no active version exists yet (initial-commit race
+ * where another writer initialized first).
+ */
+declare class StaleVersionError extends TypeGraphError {
+    readonly details: Readonly<{
+        graphId: string;
+        expected: number;
+        actual: number;
+    }>;
+    constructor(details: Readonly<{
+        graphId: string;
+        expected: number;
+        actual: number;
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown by `commitSchemaVersion` when a row already exists at the
+ * target version with a *different* schema hash — i.e. two writers
+ * committed materially different schemas at the same version number.
+ *
+ * Distinct from `StaleVersionError`: this is not a refetch-and-retry
+ * situation, it's a content disagreement that needs operator
+ * intervention. Typically caused by inconsistent application
+ * deployments writing schemas that hash differently.
+ */
+declare class SchemaContentConflictError extends TypeGraphError {
+    readonly details: Readonly<{
+        graphId: string;
+        version: number;
+        existingHash: string;
+        incomingHash: string;
+    }>;
+    constructor(details: Readonly<{
+        graphId: string;
+        version: number;
+        existingHash: string;
+        incomingHash: string;
+    }>, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Thrown when graph configuration is invalid.
  *
@@ -390,4 +499,4 @@ declare function isConstraintError(error: unknown): boolean;
  */
 declare function getErrorSuggestion(error: unknown): string | undefined;
 
-export { BackendDisposedError as B, CardinalityError as C, DatabaseOperationError as D, EdgeNotFoundError as E, KindNotFoundError as K, MigrationError as M, NodeConstraintNotFoundError as N, RestrictedDeleteError as R, SchemaMismatchError as S, TypeGraphError as T, UniquenessError as U, ValidationError as V, CompilerInvariantError as a, ConfigurationError as b, DisjointError as c, EndpointError as d, EndpointNotFoundError as e, type ErrorCategory as f, NodeNotFoundError as g, type TypeGraphErrorOptions as h, UnsupportedPredicateError as i, type ValidationErrorDetails as j, type ValidationIssue as k, VersionConflictError as l, getErrorSuggestion as m, isConstraintError as n, isSystemError as o, isTypeGraphError as p, isUserRecoverable as q };
+export { BackendDisposedError as B, CardinalityError as C, DatabaseOperationError as D, EagerMaterializationError as E, KindNotFoundError as K, MigrationError as M, NodeConstraintNotFoundError as N, RestrictedDeleteError as R, SchemaContentConflictError as S, TypeGraphError as T, UniquenessError as U, type ValidationIssue as V, ValidationError as a, CompilerInvariantError as b, ConfigurationError as c, DisjointError as d, EdgeNotFoundError as e, EndpointError as f, EndpointNotFoundError as g, type ErrorCategory as h, NodeNotFoundError as i, SchemaMismatchError as j, StaleVersionError as k, type TypeGraphErrorOptions as l, UnsupportedPredicateError as m, type ValidationErrorDetails as n, VersionConflictError as o, getErrorSuggestion as p, isConstraintError as q, isSystemError as r, isTypeGraphError as s, isUserRecoverable as t };

package/dist/{index-DXkEXpNz.d.cts → index-DQheiVQV.d.ts}

@@ -1,3 +1,6 @@
+import { K as KindEntity } from './extension-types-D07e_NTw.js';
+import { M as MaterializeIndexesResult } from './materialize-indexes-BYpU2RKh.js';
+
 /**
  * TypeGraph Error Hierarchy
  *
@@ -21,6 +24,7 @@
  * }
  * ```
  */
+
 /**
  * Error category for programmatic handling.
  *
@@ -83,7 +87,7 @@ type ValidationIssue = Readonly<{
  */
 type ValidationErrorDetails = Readonly<{
     /** Type of entity being validated */
-    entityType?: "node" | "edge";
+    entityType?: KindEntity;
     /** Kind/type name of the entity */
     kind?: string;
     /** Operation being performed */
@@ -143,12 +147,22 @@ declare class EdgeNotFoundError extends TypeGraphError {
     });
 }
 /**
- * Thrown when a kind is not found in the graph registry.
+ * Thrown when an operation references a kind that isn't registered on
+ * the graph — `getNodeCollectionOrThrow` against an unknown kind, a
+ * `materializeIndexes({ kinds })` filter naming a missing kind, an
+ * extension referencing an unresolved endpoint, search facade typos,
+ * etc. Carries the offending `kindName` and `entity` plus the host
+ * `graphId` so logs are unambiguous when multiple stores share a
+ * process.
  */
 declare class KindNotFoundError extends TypeGraphError {
-    constructor(kind: string, type: "node" | "edge", options?: {
+    readonly kindName: string;
+    readonly entity: KindEntity;
+    constructor(kindName: string, entity: KindEntity, options?: Readonly<{
+        graphId?: string;
+        suggestion?: string;
         cause?: unknown;
-    });
+    }>);
 }
 /**
  * Thrown when a uniqueness constraint name is not found on a node kind.
@@ -281,6 +295,101 @@ declare class MigrationError extends TypeGraphError {
         cause?: unknown;
     });
 }
+/**
+ * Thrown by `Store.evolve(extension, { eager })` when the schema
+ * commit succeeded but the follow-on `materializeIndexes()` produced
+ * one or more failed entries.
+ *
+ * Recovery: the schema commit is NOT rolled back. The new `Store` is
+ * fully constructed and (when `options.ref` was supplied) `ref.current`
+ * already points to it — the caller can read the new store via the ref
+ * and decide how to handle the failed indexes (retry, skip, alert).
+ * The full `MaterializeIndexesResult` is attached as `.materialization`.
+ *
+ * @example
+ * ```ts
+ * const ref = { current: store };
+ * try {
+ *   await store.evolve(extension, { ref, eager: {} });
+ * } catch (error) {
+ *   if (error instanceof EagerMaterializationError) {
+ *     // schema is committed; ref.current is the new store
+ *     log.warn(
+ *       { failed: error.failedIndexNames },
+ *       "indexes did not materialize; will retry",
+ *     );
+ *     await ref.current.materializeIndexes();
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+declare class EagerMaterializationError extends TypeGraphError {
+    /**
+     * The full materialization result, including successful and failed
+     * entries. Same shape as `Store.materializeIndexes()` returns.
+     */
+    readonly materialization: MaterializeIndexesResult;
+    constructor(materialization: MaterializeIndexesResult, graphId: string);
+    /**
+     * Names of just the indexes that failed — derived from
+     * `materialization.results` so the two views can never disagree.
+     */
+    get failedIndexNames(): readonly string[];
+}
+/**
+ * Thrown by `commitSchemaVersion` and `setActiveVersion` when the
+ * caller's view of the active schema version is out of date — another
+ * writer has already advanced it.
+ *
+ * Recovery: re-read the active version with `getActiveSchema(graphId)`,
+ * recompute against the new baseline, and retry. This is a routine
+ * concurrency signal, not a bug.
+ *
+ * `actual` is `0` when no active version exists yet (initial-commit race
+ * where another writer initialized first).
+ */
+declare class StaleVersionError extends TypeGraphError {
+    readonly details: Readonly<{
+        graphId: string;
+        expected: number;
+        actual: number;
+    }>;
+    constructor(details: Readonly<{
+        graphId: string;
+        expected: number;
+        actual: number;
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown by `commitSchemaVersion` when a row already exists at the
+ * target version with a *different* schema hash — i.e. two writers
+ * committed materially different schemas at the same version number.
+ *
+ * Distinct from `StaleVersionError`: this is not a refetch-and-retry
+ * situation, it's a content disagreement that needs operator
+ * intervention. Typically caused by inconsistent application
+ * deployments writing schemas that hash differently.
+ */
+declare class SchemaContentConflictError extends TypeGraphError {
+    readonly details: Readonly<{
+        graphId: string;
+        version: number;
+        existingHash: string;
+        incomingHash: string;
+    }>;
+    constructor(details: Readonly<{
+        graphId: string;
+        version: number;
+        existingHash: string;
+        incomingHash: string;
+    }>, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Thrown when graph configuration is invalid.
  *
@@ -390,4 +499,4 @@ declare function isConstraintError(error: unknown): boolean;
  */
 declare function getErrorSuggestion(error: unknown): string | undefined;
 
-export { BackendDisposedError as B, CardinalityError as C, DatabaseOperationError as D, EdgeNotFoundError as E, KindNotFoundError as K, MigrationError as M, NodeConstraintNotFoundError as N, RestrictedDeleteError as R, SchemaMismatchError as S, TypeGraphError as T, UniquenessError as U, ValidationError as V, CompilerInvariantError as a, ConfigurationError as b, DisjointError as c, EndpointError as d, EndpointNotFoundError as e, type ErrorCategory as f, NodeNotFoundError as g, type TypeGraphErrorOptions as h, UnsupportedPredicateError as i, type ValidationErrorDetails as j, type ValidationIssue as k, VersionConflictError as l, getErrorSuggestion as m, isConstraintError as n, isSystemError as o, isTypeGraphError as p, isUserRecoverable as q };
+export { BackendDisposedError as B, CardinalityError as C, DatabaseOperationError as D, EagerMaterializationError as E, KindNotFoundError as K, MigrationError as M, NodeConstraintNotFoundError as N, RestrictedDeleteError as R, SchemaContentConflictError as S, TypeGraphError as T, UniquenessError as U, type ValidationIssue as V, ValidationError as a, CompilerInvariantError as b, ConfigurationError as c, DisjointError as d, EdgeNotFoundError as e, EndpointError as f, EndpointNotFoundError as g, type ErrorCategory as h, NodeNotFoundError as i, SchemaMismatchError as j, StaleVersionError as k, type TypeGraphErrorOptions as l, UnsupportedPredicateError as m, type ValidationErrorDetails as n, VersionConflictError as o, getErrorSuggestion as p, isConstraintError as q, isSystemError as r, isTypeGraphError as s, isUserRecoverable as t };