@nicia-ai/typegraph 0.34.0 → 0.36.0

package/dist/{index-DGX6D9j1.d.ts → index-BFvdmBPV.d.ts}

@@ -1,5 +1,5 @@
-import { K as KindEntity } from './extension-types-YGFJPrzK.js';
-import { M as MaterializeIndexesResult } from './materialize-indexes-CAkIYFV-.js';
+import { K as KindEntity } from './extension-types-ixRpJVUp.js';
+import { M as MaterializeIndexesResult } from './materialize-indexes-te9TPMMJ.js';
 
 /**
  * TypeGraph Error Hierarchy
@@ -119,6 +119,13 @@ declare class ValidationError extends TypeGraphError {
         suggestion?: string;
     });
 }
+/**
+ * Details for NodeNotFoundError.
+ */
+type NodeNotFoundErrorDetails = Readonly<{
+    kind: string;
+    id: string;
+}>;
 /**
  * Thrown when a node is not found.
  *
@@ -134,18 +141,35 @@ declare class ValidationError extends TypeGraphError {
  * ```
  */
 declare class NodeNotFoundError extends TypeGraphError {
+    readonly details: NodeNotFoundErrorDetails;
     constructor(kind: string, id: string, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for EdgeNotFoundError.
+ */
+type EdgeNotFoundErrorDetails = Readonly<{
+    kind: string;
+    id: string;
+}>;
 /**
  * Thrown when an edge is not found.
  */
 declare class EdgeNotFoundError extends TypeGraphError {
+    readonly details: EdgeNotFoundErrorDetails;
     constructor(kind: string, id: string, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for KindNotFoundError.
+ */
+type KindNotFoundErrorDetails = Readonly<{
+    kindName: string;
+    entity: KindEntity;
+    graphId?: string;
+}>;
 /**
  * Thrown when an operation references a kind that isn't registered on
  * the graph — `getNodeCollectionOrThrow` against an unknown kind, a
@@ -156,6 +180,7 @@ declare class EdgeNotFoundError extends TypeGraphError {
  * process.
  */
 declare class KindNotFoundError extends TypeGraphError {
+    readonly details: KindNotFoundErrorDetails;
     readonly kindName: string;
     readonly entity: KindEntity;
     constructor(kindName: string, entity: KindEntity, options?: Readonly<{
@@ -164,76 +189,120 @@ declare class KindNotFoundError extends TypeGraphError {
         cause?: unknown;
     }>);
 }
+/**
+ * Details for NodeConstraintNotFoundError.
+ */
+type NodeConstraintNotFoundErrorDetails = Readonly<{
+    constraintName: string;
+    kind: string;
+}>;
 /**
  * Thrown when a uniqueness constraint name is not found on a node kind.
  */
 declare class NodeConstraintNotFoundError extends TypeGraphError {
+    readonly details: NodeConstraintNotFoundErrorDetails;
     constructor(constraintName: string, kind: string, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for NodeIndexNotFoundError.
+ */
+type NodeIndexNotFoundErrorDetails = Readonly<{
+    indexName: string;
+    kind: string;
+}>;
 /**
  * Thrown when a declared node index name is not found on a node kind.
  */
 declare class NodeIndexNotFoundError extends TypeGraphError {
+    readonly details: NodeIndexNotFoundErrorDetails;
     constructor(indexName: string, kind: string, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for EndpointNotFoundError.
+ */
+type EndpointNotFoundErrorDetails = Readonly<{
+    edgeKind: string;
+    endpoint: "from" | "to";
+    nodeKind: string;
+    nodeId: string;
+}>;
 /**
  * Thrown when edge endpoint node does not exist or is deleted.
  */
 declare class EndpointNotFoundError extends TypeGraphError {
-    constructor(details: Readonly<{
-        edgeKind: string;
-        endpoint: "from" | "to";
-        nodeKind: string;
-        nodeId: string;
-    }>, options?: {
+    readonly details: EndpointNotFoundErrorDetails;
+    constructor(details: EndpointNotFoundErrorDetails, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for EndpointError.
+ */
+type EndpointErrorDetails = Readonly<{
+    edgeKind: string;
+    endpoint: "from" | "to";
+    actualKind: string;
+    expectedKinds: readonly string[];
+}>;
 /**
  * Thrown when edge endpoint has wrong node type.
  */
 declare class EndpointError extends TypeGraphError {
-    constructor(details: Readonly<{
-        edgeKind: string;
-        endpoint: "from" | "to";
-        actualKind: string;
-        expectedKinds: readonly string[];
-    }>, options?: {
+    readonly details: EndpointErrorDetails;
+    constructor(details: EndpointErrorDetails, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for UniquenessError.
+ */
+type UniquenessErrorDetails = Readonly<{
+    constraintName: string;
+    kind: string;
+    existingId: string;
+    newId: string;
+    fields: readonly string[];
+}>;
 /**
  * Thrown when uniqueness constraint is violated.
  */
 declare class UniquenessError extends TypeGraphError {
-    constructor(details: Readonly<{
-        constraintName: string;
-        kind: string;
-        existingId: string;
-        newId: string;
-        fields: readonly string[];
-    }>, options?: {
+    readonly details: UniquenessErrorDetails;
+    constructor(details: UniquenessErrorDetails, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for CardinalityError.
+ */
+type CardinalityErrorDetails = Readonly<{
+    edgeKind: string;
+    fromKind: string;
+    fromId: string;
+    cardinality: string;
+    existingCount: number;
+}>;
 /**
  * Thrown when cardinality constraint is violated.
  */
 declare class CardinalityError extends TypeGraphError {
-    constructor(details: Readonly<{
-        edgeKind: string;
-        fromKind: string;
-        fromId: string;
-        cardinality: string;
-        existingCount: number;
-    }>, options?: {
+    readonly details: CardinalityErrorDetails;
+    constructor(details: CardinalityErrorDetails, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for DisjointError.
+ */
+type DisjointErrorDetails = Readonly<{
+    nodeId: string;
+    attemptedKind: string;
+    conflictingKind: string;
+}>;
 /**
  * Thrown when disjointness constraint is violated.
  *
@@ -241,27 +310,38 @@ declare class CardinalityError extends TypeGraphError {
  * a Person and an Organization if they are declared disjoint.
  */
 declare class DisjointError extends TypeGraphError {
-    constructor(details: Readonly<{
-        nodeId: string;
-        attemptedKind: string;
-        conflictingKind: string;
-    }>, options?: {
+    readonly details: DisjointErrorDetails;
+    constructor(details: DisjointErrorDetails, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for RestrictedDeleteError.
+ */
+type RestrictedDeleteErrorDetails = Readonly<{
+    nodeKind: string;
+    nodeId: string;
+    edgeCount: number;
+    edgeKinds: readonly string[];
+}>;
 /**
  * Thrown when deletion is blocked due to existing edges (restrict behavior).
  */
 declare class RestrictedDeleteError extends TypeGraphError {
-    constructor(details: Readonly<{
-        nodeKind: string;
-        nodeId: string;
-        edgeCount: number;
-        edgeKinds: readonly string[];
-    }>, options?: {
+    readonly details: RestrictedDeleteErrorDetails;
+    constructor(details: RestrictedDeleteErrorDetails, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for VersionConflictError.
+ */
+type VersionConflictErrorDetails = Readonly<{
+    kind: string;
+    id: string;
+    expectedVersion: number;
+    actualVersion: number;
+}>;
 /**
  * Thrown when optimistic locking detects a concurrent modification.
  *
@@ -269,40 +349,53 @@ declare class RestrictedDeleteError extends TypeGraphError {
  * The operation with the stale version fails.
  */
 declare class VersionConflictError extends TypeGraphError {
-    constructor(details: Readonly<{
-        kind: string;
-        id: string;
-        expectedVersion: number;
-        actualVersion: number;
-    }>, options?: {
+    readonly details: VersionConflictErrorDetails;
+    constructor(details: VersionConflictErrorDetails, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for SchemaMismatchError.
+ */
+type SchemaMismatchErrorDetails = Readonly<{
+    graphId: string;
+    expectedHash: string;
+    actualHash: string;
+}>;
 /**
  * Thrown when the schema in code doesn't match the schema in the database.
  */
 declare class SchemaMismatchError extends TypeGraphError {
-    constructor(details: Readonly<{
-        graphId: string;
-        expectedHash: string;
-        actualHash: string;
-    }>, options?: {
+    readonly details: SchemaMismatchErrorDetails;
+    constructor(details: SchemaMismatchErrorDetails, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for MigrationError.
+ */
+type MigrationErrorDetails = Readonly<{
+    graphId: string;
+    fromVersion: number;
+    toVersion: number;
+    reason?: string;
+}>;
 /**
  * Thrown when schema migration fails.
  */
 declare class MigrationError extends TypeGraphError {
-    constructor(message: string, details: Readonly<{
-        graphId: string;
-        fromVersion: number;
-        toVersion: number;
-        reason?: string;
-    }>, options?: {
+    readonly details: MigrationErrorDetails;
+    constructor(message: string, details: MigrationErrorDetails, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for EagerMaterializationError.
+ */
+type EagerMaterializationErrorDetails = Readonly<{
+    graphId: string;
+    failedIndexNames: readonly string[];
+}>;
 /**
  * Thrown by `Store.evolve(extension, { eager })` when the schema
  * commit succeeded but the follow-on `materializeIndexes()` produced
@@ -334,6 +427,7 @@ declare class MigrationError extends TypeGraphError {
  * ```
  */
 declare class EagerMaterializationError extends TypeGraphError {
+    readonly details: EagerMaterializationErrorDetails;
     /**
      * The full materialization result, including successful and failed
      * entries. Same shape as `Store.materializeIndexes()` returns.
@@ -346,6 +440,15 @@ declare class EagerMaterializationError extends TypeGraphError {
      */
     get failedIndexNames(): readonly string[];
 }
+/**
+ * Details for StaleVersionError. `actual` is `0` when no active version
+ * exists yet (initial-commit race where another writer initialized first).
+ */
+type StaleVersionErrorDetails = Readonly<{
+    graphId: string;
+    expected: number;
+    actual: number;
+}>;
 /**
  * Thrown by `commitSchemaVersion` and `setActiveVersion` when the
  * caller's view of the active schema version is out of date — another
@@ -354,24 +457,22 @@ declare class EagerMaterializationError extends TypeGraphError {
  * 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?: {
+    readonly details: StaleVersionErrorDetails;
+    constructor(details: StaleVersionErrorDetails, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for SchemaContentConflictError.
+ */
+type SchemaContentConflictErrorDetails = Readonly<{
+    graphId: string;
+    version: number;
+    existingHash: string;
+    incomingHash: string;
+}>;
 /**
  * Thrown by `commitSchemaVersion` when a row already exists at the
  * target version with a *different* schema hash — i.e. two writers
@@ -383,18 +484,8 @@ declare class StaleVersionError extends TypeGraphError {
  * 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?: {
+    readonly details: SchemaContentConflictErrorDetails;
+    constructor(details: SchemaContentConflictErrorDetails, options?: {
         cause?: unknown;
     });
 }
@@ -410,6 +501,73 @@ declare class ConfigurationError extends TypeGraphError {
         suggestion?: string;
     });
 }
+/**
+ * The stable `details.code` values raised by the recorded-capture guards on a
+ * history- or revision-tracked store. These are the sanctioned branch points
+ * for a portable caller that must pick a transaction strategy without
+ * substring-matching {@link ConfigurationError} messages.
+ *
+ * - `RECORDED_CAPTURE_REQUIRES_CALLBACK_TRANSACTION`: `store.withTransaction`
+ *   was called on a history-enabled store, which has no flush point before the
+ *   caller commits — use `store.withRecordedTransaction` instead.
+ * - `RECORDED_CAPTURE_RAW_SQL_DISABLED`: a raw SQL escape (`tx.sql`,
+ *   `backend.executeStatement`/`executeDdl`) was reached on a history-enabled
+ *   store, where it would bypass recorded-time capture.
+ * - `REVISION_TRACKING_RAW_SQL_DISABLED`: the same raw SQL escape on a
+ *   revision-tracked store, where it would bypass the revision anchor.
+ *
+ * @see isRecordedCaptureGuardError
+ */
+declare const RECORDED_CAPTURE_GUARD_CODES: readonly ["RECORDED_CAPTURE_REQUIRES_CALLBACK_TRANSACTION", "RECORDED_CAPTURE_RAW_SQL_DISABLED", "REVISION_TRACKING_RAW_SQL_DISABLED"];
+/** A stable, branchable code raised by a recorded-capture guard. */
+type RecordedCaptureGuardCode = (typeof RECORDED_CAPTURE_GUARD_CODES)[number];
+/**
+ * A {@link ConfigurationError} narrowed to carry a {@link RecordedCaptureGuardCode}
+ * in `details.code` — the shape {@link isRecordedCaptureGuardError} guarantees.
+ * `C` narrows `details.code` to a single code when the guard was called with a
+ * specific one; it defaults to the full union.
+ */
+type RecordedCaptureGuardError<C extends RecordedCaptureGuardCode = RecordedCaptureGuardCode> = ConfigurationError & Readonly<{
+    details: Readonly<{
+        code: C;
+    }>;
+}>;
+/**
+ * Type guard for the recorded-capture guard errors, so a portable caller can
+ * branch on the invariant a store enforced instead of substring-matching the
+ * message. Pass `code` to narrow to a single guard; omit it to match any.
+ *
+ * Distinguishes "history capture forbids raw SQL here" from "this backend has
+ * no transactions" (the latter carries no guard code — see
+ * `TransactionContext.sqlAvailability` for the capability discriminant).
+ *
+ * Passing `code` also narrows `details.code` to that literal on the guarded
+ * branch, so a caller can read the payload without re-checking.
+ *
+ * @example
+ * ```typescript
+ * // `withTransaction` is a compile error on a history-enabled store, so widen
+ * // to the base Store surface to reach the runtime guard this branches on.
+ * const store: Store<typeof graph> = historyStore;
+ * try {
+ *   store.withTransaction(externalTx);
+ * } catch (error) {
+ *   if (
+ *     isRecordedCaptureGuardError(
+ *       error,
+ *       "RECORDED_CAPTURE_REQUIRES_CALLBACK_TRANSACTION",
+ *     )
+ *   ) {
+ *     // error.details.code is now the literal, not the union.
+ *     await historyStore.withRecordedTransaction(externalTx, run);
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+declare function isRecordedCaptureGuardError<C extends RecordedCaptureGuardCode>(error: unknown, code: C): error is RecordedCaptureGuardError<C>;
+declare function isRecordedCaptureGuardError(error: unknown): error is RecordedCaptureGuardError;
 /**
  * Why a store's strategy-owned storage is not usable on the current
  * connection. Drives the {@link StoreNotInitializedError} message and
@@ -424,6 +582,15 @@ declare class ConfigurationError extends TypeGraphError {
  *   recorded an error. Boot may retry; the hot path refuses.
  */
 type StoreNotInitializedReason = "missing" | "stale" | "failed";
+/**
+ * Details for StoreNotInitializedError. `graphId`/`reason` are always
+ * present; callers may merge additional context (e.g. `logicalName`) via
+ * `options.details`.
+ */
+type StoreNotInitializedErrorDetails = Readonly<{
+    graphId: string;
+    reason: StoreNotInitializedReason;
+}> & Readonly<Record<string, unknown>>;
 /**
  * Thrown when a fulltext-dependent operation runs against a connection
  * whose strategy-owned storage has not been durably materialized.
@@ -436,11 +603,22 @@ type StoreNotInitializedReason = "missing" | "stale" | "failed";
  * loudly here instead of lazily emitting DDL on the hot path.
  */
 declare class StoreNotInitializedError extends TypeGraphError {
+    readonly details: StoreNotInitializedErrorDetails;
     constructor(graphId: string, reason: StoreNotInitializedReason, options?: {
         cause?: unknown;
-        details?: Record<string, unknown>;
+        details?: Readonly<Record<string, unknown>> & Readonly<{
+            graphId?: never;
+            reason?: never;
+        }>;
     });
 }
+/**
+ * Details for DatabaseOperationError.
+ */
+type DatabaseOperationErrorDetails = Readonly<{
+    operation: string;
+    entity: string;
+}>;
 /**
  * Thrown when a database operation fails unexpectedly.
  *
@@ -448,13 +626,20 @@ declare class StoreNotInitializedError extends TypeGraphError {
  * not a user-recoverable error.
  */
 declare class DatabaseOperationError extends TypeGraphError {
-    constructor(message: string, details: Readonly<{
-        operation: string;
-        entity: string;
-    }>, options?: {
+    readonly details: DatabaseOperationErrorDetails;
+    constructor(message: string, details: DatabaseOperationErrorDetails, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Details for EmbeddingDimensionChangedError.
+ */
+type EmbeddingDimensionChangedErrorDetails = Readonly<{
+    kind: string;
+    fieldPath: string;
+    declaredDimensions?: number;
+    storedDimensions?: number;
+}>;
 /**
  * Thrown when an embedding field's declared dimension no longer matches the
  * dimension of its materialized per-field storage — i.e. a field's
@@ -465,12 +650,8 @@ declare class DatabaseOperationError extends TypeGraphError {
  * the new dimension and re-embed existing rows.
  */
 declare class EmbeddingDimensionChangedError extends TypeGraphError {
-    constructor(message: string, details: Readonly<{
-        kind: string;
-        fieldPath: string;
-        declaredDimensions?: number;
-        storedDimensions?: number;
-    }>, options?: {
+    readonly details: EmbeddingDimensionChangedErrorDetails;
+    constructor(message: string, details: EmbeddingDimensionChangedErrorDetails, options?: {
         cause?: unknown;
     });
 }
@@ -506,6 +687,33 @@ declare class BackendDisposedError extends TypeGraphError {
         cause?: unknown;
     });
 }
+/**
+ * Thrown when a statement is issued on a transaction-scoped backend after
+ * its transaction boundary has already returned.
+ *
+ * The usual source is a callback that lets work escape it. `Promise.all`
+ * rejects on its first rejection while its siblings keep running, so
+ *
+ * ```typescript
+ * await store.transaction(async (tx) => {
+ *   await Promise.all([tx.nodes.Doc.create(a), tx.nodes.Doc.create(b)]);
+ * });
+ * ```
+ *
+ * leaves `b`'s remaining statements in flight when `a` fails. Those
+ * statements have nowhere safe to go: the driver is about to emit `ROLLBACK`
+ * on the same pinned connection and then hand it back to the pool, where a
+ * late arrival would execute inside somebody else's transaction. TypeGraph
+ * refuses them here instead.
+ *
+ * The error is normally invisible — `Promise.all` has already rejected with
+ * the original failure, and discards this one.
+ */
+declare class TransactionClosedError extends TypeGraphError {
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Type guard for TypeGraphError.
  *
@@ -557,4 +765,4 @@ declare function isConstraintError(error: unknown): boolean;
  */
 declare function getErrorSuggestion(error: unknown): string | undefined;
 
-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, EmbeddingDimensionChangedError as f, EndpointError as g, EndpointNotFoundError as h, type ErrorCategory as i, NodeIndexNotFoundError as j, NodeNotFoundError as k, SchemaMismatchError as l, StaleVersionError as m, StoreNotInitializedError as n, type StoreNotInitializedReason as o, type TypeGraphErrorOptions as p, UnsupportedPredicateError as q, type ValidationErrorDetails as r, VersionConflictError as s, getErrorSuggestion as t, isConstraintError as u, isSystemError as v, isTypeGraphError as w, isUserRecoverable as x };
+export { VersionConflictError as $, RestrictedDeleteError as A, BackendDisposedError as B, CardinalityError as C, DatabaseOperationError as D, EagerMaterializationError as E, type RestrictedDeleteErrorDetails as F, type SchemaContentConflictErrorDetails as G, SchemaMismatchError as H, type SchemaMismatchErrorDetails as I, StaleVersionError as J, KindNotFoundError as K, type StaleVersionErrorDetails as L, MigrationError as M, NodeConstraintNotFoundError as N, StoreNotInitializedError as O, type StoreNotInitializedErrorDetails as P, type StoreNotInitializedReason as Q, RECORDED_CAPTURE_GUARD_CODES as R, SchemaContentConflictError as S, TypeGraphError as T, TransactionClosedError as U, type ValidationIssue as V, type TypeGraphErrorOptions as W, UniquenessError as X, type UniquenessErrorDetails as Y, UnsupportedPredicateError as Z, type ValidationErrorDetails as _, ValidationError as a, type VersionConflictErrorDetails as a0, getErrorSuggestion as a1, isConstraintError as a2, isRecordedCaptureGuardError as a3, isSystemError as a4, isTypeGraphError as a5, isUserRecoverable as a6, type CardinalityErrorDetails as b, CompilerInvariantError as c, ConfigurationError as d, type DatabaseOperationErrorDetails as e, DisjointError as f, type DisjointErrorDetails as g, type EagerMaterializationErrorDetails as h, EdgeNotFoundError as i, type EdgeNotFoundErrorDetails as j, EmbeddingDimensionChangedError as k, type EmbeddingDimensionChangedErrorDetails as l, EndpointError as m, type EndpointErrorDetails as n, EndpointNotFoundError as o, type EndpointNotFoundErrorDetails as p, type ErrorCategory as q, type KindNotFoundErrorDetails as r, type MigrationErrorDetails as s, type NodeConstraintNotFoundErrorDetails as t, NodeIndexNotFoundError as u, type NodeIndexNotFoundErrorDetails as v, NodeNotFoundError as w, type NodeNotFoundErrorDetails as x, type RecordedCaptureGuardCode as y, type RecordedCaptureGuardError as z };