@nicia-ai/typegraph 0.35.0 → 0.37.0

package/dist/{index-Bks_3HHK.d.cts → index-BPM59vsg.d.cts}

@@ -1,5 +1,5 @@
-import { K as KindEntity } from './extension-types-ixRpJVUp.cjs';
-import { M as MaterializeIndexesResult } from './materialize-indexes-B4e9360H.cjs';
+import { K as KindEntity } from './extension-types-BM2ACfYO.cjs';
+import { M as MaterializeIndexesResult } from './materialize-indexes-CuR3gAZb.cjs';
 
 /**
  * TypeGraph Error Hierarchy
@@ -501,6 +501,118 @@ declare class ConfigurationError extends TypeGraphError {
         suggestion?: string;
     });
 }
+/**
+ * Thrown when an iterative graph algorithm exhausts its caller-visible round
+ * budget before reaching its convergence predicate.
+ */
+declare class GraphAlgorithmConvergenceError extends TypeGraphError {
+    constructor(algorithm: string, maxIterations: number);
+}
+/** Stable reasons a weighted traversal can reject an edge's weight value. */
+type InvalidEdgeWeightReason = "missing" | "negative" | "non_numeric" | "out_of_range";
+/** Details for InvalidEdgeWeightError. */
+type InvalidEdgeWeightErrorDetails = Readonly<{
+    /** Id of the first offending edge, in binary-collation order. */
+    edgeId: string;
+    /** Kind of the offending edge. */
+    edgeKind: string;
+    /** The audited weight property. */
+    property: string;
+    /** Why the weight was rejected. */
+    reason: InvalidEdgeWeightReason;
+    /** The offending value, when one was present and renderable. */
+    value?: string;
+}>;
+/**
+ * Thrown when a weighted graph algorithm finds an edge whose weight property
+ * violates the weighted-traversal contract (missing without a default,
+ * non-numeric, or negative). Raised before any traversal rounds run, so a
+ * weighted call either observes a fully valid weight domain or fails fast.
+ */
+declare class InvalidEdgeWeightError extends TypeGraphError {
+    readonly details: InvalidEdgeWeightErrorDetails;
+    constructor(details: InvalidEdgeWeightErrorDetails);
+}
+/** Thrown when an operation requires a backend capability it does not expose. */
+declare class UnsupportedBackendCapabilityError extends TypeGraphError {
+    constructor(operation: string, capability: string, details?: Readonly<Record<string, unknown>>, suggestion?: string);
+}
+/** Stable reasons an intentionally trusted initial import can be rejected. */
+type TrustedImportErrorReason = "backend_unsupported" | "database_not_empty" | "fulltext_unsupported" | "history_unsupported" | "invalid_stream" | "revision_tracking_unsupported" | "uniqueness_unsupported" | "vector_unsupported";
+/** Thrown when the trusted initial-import contract is unavailable or violated. */
+declare class TrustedImportError extends TypeGraphError {
+    constructor(message: string, reason: TrustedImportErrorReason, details?: Readonly<Record<string, unknown>>, options?: Readonly<{
+        cause?: unknown;
+        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
@@ -525,14 +637,14 @@ type StoreNotInitializedErrorDetails = Readonly<{
     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.
+ * Thrown when a fulltext- or vector-dependent operation runs against a
+ * connection whose strategy-owned storage has not been durably materialized.
  *
  * `createStore()` is a synchronous, zero-I/O attach: it never creates
  * tables, repairs DDL, or writes materialization markers. The durable
  * marker is written exclusively by the async boot path
- * (`createStoreWithSchema`). When a fulltext read/write — or an
- * adopted/business transaction — observes no valid marker, it refuses
+ * (`createStoreWithSchema`). When a fulltext or embedding read/write — or
+ * an adopted/business transaction — observes no valid marker, it refuses
  * loudly here instead of lazily emitting DDL on the hot path.
  */
 declare class StoreNotInitializedError extends TypeGraphError {
@@ -698,4 +810,4 @@ declare function isConstraintError(error: unknown): boolean;
  */
 declare function getErrorSuggestion(error: unknown): string | undefined;
 
-export { isConstraintError as $, SchemaMismatchError as A, BackendDisposedError as B, CardinalityError as C, DatabaseOperationError as D, EagerMaterializationError as E, type SchemaMismatchErrorDetails as F, StaleVersionError as G, type StaleVersionErrorDetails as H, StoreNotInitializedError as I, type StoreNotInitializedErrorDetails as J, KindNotFoundError as K, type StoreNotInitializedReason as L, MigrationError as M, NodeConstraintNotFoundError as N, TransactionClosedError as O, type TypeGraphErrorOptions as P, type UniquenessErrorDetails as Q, RestrictedDeleteError as R, SchemaContentConflictError as S, TypeGraphError as T, UniquenessError as U, type ValidationIssue as V, UnsupportedPredicateError as W, type ValidationErrorDetails as X, VersionConflictError as Y, type VersionConflictErrorDetails as Z, getErrorSuggestion as _, ValidationError as a, isSystemError as a0, isTypeGraphError as a1, isUserRecoverable as a2, 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 RestrictedDeleteErrorDetails as y, type SchemaContentConflictErrorDetails as z };
+export { type TrustedImportErrorReason as $, type RecordedCaptureGuardCode as A, BackendDisposedError as B, CardinalityError as C, DatabaseOperationError as D, EagerMaterializationError as E, type RecordedCaptureGuardError as F, GraphAlgorithmConvergenceError as G, RestrictedDeleteError as H, InvalidEdgeWeightError as I, type RestrictedDeleteErrorDetails as J, KindNotFoundError as K, type SchemaContentConflictErrorDetails as L, MigrationError as M, NodeConstraintNotFoundError as N, SchemaMismatchError as O, type SchemaMismatchErrorDetails as P, StaleVersionError as Q, RECORDED_CAPTURE_GUARD_CODES as R, SchemaContentConflictError as S, TypeGraphError as T, type StaleVersionErrorDetails as U, type ValidationIssue as V, StoreNotInitializedError as W, type StoreNotInitializedErrorDetails as X, type StoreNotInitializedReason as Y, TransactionClosedError as Z, TrustedImportError as _, ValidationError as a, type TypeGraphErrorOptions as a0, UniquenessError as a1, type UniquenessErrorDetails as a2, UnsupportedBackendCapabilityError as a3, UnsupportedPredicateError as a4, type ValidationErrorDetails as a5, VersionConflictError as a6, type VersionConflictErrorDetails as a7, getErrorSuggestion as a8, isConstraintError as a9, isRecordedCaptureGuardError as aa, isSystemError as ab, isTypeGraphError as ac, isUserRecoverable as ad, 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 InvalidEdgeWeightErrorDetails as r, type InvalidEdgeWeightReason as s, type KindNotFoundErrorDetails as t, type MigrationErrorDetails as u, type NodeConstraintNotFoundErrorDetails as v, NodeIndexNotFoundError as w, type NodeIndexNotFoundErrorDetails as x, NodeNotFoundError as y, type NodeNotFoundErrorDetails as z };

package/dist/{index-6CSUAq-x.d.ts → index-BeacbPoe.d.ts}

@@ -1,5 +1,5 @@
-import { K as KindEntity } from './extension-types-ixRpJVUp.js';
-import { M as MaterializeIndexesResult } from './materialize-indexes-te9TPMMJ.js';
+import { K as KindEntity } from './extension-types-BM2ACfYO.js';
+import { M as MaterializeIndexesResult } from './materialize-indexes-zK2J_flP.js';
 
 /**
  * TypeGraph Error Hierarchy
@@ -501,6 +501,118 @@ declare class ConfigurationError extends TypeGraphError {
         suggestion?: string;
     });
 }
+/**
+ * Thrown when an iterative graph algorithm exhausts its caller-visible round
+ * budget before reaching its convergence predicate.
+ */
+declare class GraphAlgorithmConvergenceError extends TypeGraphError {
+    constructor(algorithm: string, maxIterations: number);
+}
+/** Stable reasons a weighted traversal can reject an edge's weight value. */
+type InvalidEdgeWeightReason = "missing" | "negative" | "non_numeric" | "out_of_range";
+/** Details for InvalidEdgeWeightError. */
+type InvalidEdgeWeightErrorDetails = Readonly<{
+    /** Id of the first offending edge, in binary-collation order. */
+    edgeId: string;
+    /** Kind of the offending edge. */
+    edgeKind: string;
+    /** The audited weight property. */
+    property: string;
+    /** Why the weight was rejected. */
+    reason: InvalidEdgeWeightReason;
+    /** The offending value, when one was present and renderable. */
+    value?: string;
+}>;
+/**
+ * Thrown when a weighted graph algorithm finds an edge whose weight property
+ * violates the weighted-traversal contract (missing without a default,
+ * non-numeric, or negative). Raised before any traversal rounds run, so a
+ * weighted call either observes a fully valid weight domain or fails fast.
+ */
+declare class InvalidEdgeWeightError extends TypeGraphError {
+    readonly details: InvalidEdgeWeightErrorDetails;
+    constructor(details: InvalidEdgeWeightErrorDetails);
+}
+/** Thrown when an operation requires a backend capability it does not expose. */
+declare class UnsupportedBackendCapabilityError extends TypeGraphError {
+    constructor(operation: string, capability: string, details?: Readonly<Record<string, unknown>>, suggestion?: string);
+}
+/** Stable reasons an intentionally trusted initial import can be rejected. */
+type TrustedImportErrorReason = "backend_unsupported" | "database_not_empty" | "fulltext_unsupported" | "history_unsupported" | "invalid_stream" | "revision_tracking_unsupported" | "uniqueness_unsupported" | "vector_unsupported";
+/** Thrown when the trusted initial-import contract is unavailable or violated. */
+declare class TrustedImportError extends TypeGraphError {
+    constructor(message: string, reason: TrustedImportErrorReason, details?: Readonly<Record<string, unknown>>, options?: Readonly<{
+        cause?: unknown;
+        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
@@ -525,14 +637,14 @@ type StoreNotInitializedErrorDetails = Readonly<{
     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.
+ * Thrown when a fulltext- or vector-dependent operation runs against a
+ * connection whose strategy-owned storage has not been durably materialized.
  *
  * `createStore()` is a synchronous, zero-I/O attach: it never creates
  * tables, repairs DDL, or writes materialization markers. The durable
  * marker is written exclusively by the async boot path
- * (`createStoreWithSchema`). When a fulltext read/write — or an
- * adopted/business transaction — observes no valid marker, it refuses
+ * (`createStoreWithSchema`). When a fulltext or embedding read/write — or
+ * an adopted/business transaction — observes no valid marker, it refuses
  * loudly here instead of lazily emitting DDL on the hot path.
  */
 declare class StoreNotInitializedError extends TypeGraphError {
@@ -698,4 +810,4 @@ declare function isConstraintError(error: unknown): boolean;
  */
 declare function getErrorSuggestion(error: unknown): string | undefined;
 
-export { isConstraintError as $, SchemaMismatchError as A, BackendDisposedError as B, CardinalityError as C, DatabaseOperationError as D, EagerMaterializationError as E, type SchemaMismatchErrorDetails as F, StaleVersionError as G, type StaleVersionErrorDetails as H, StoreNotInitializedError as I, type StoreNotInitializedErrorDetails as J, KindNotFoundError as K, type StoreNotInitializedReason as L, MigrationError as M, NodeConstraintNotFoundError as N, TransactionClosedError as O, type TypeGraphErrorOptions as P, type UniquenessErrorDetails as Q, RestrictedDeleteError as R, SchemaContentConflictError as S, TypeGraphError as T, UniquenessError as U, type ValidationIssue as V, UnsupportedPredicateError as W, type ValidationErrorDetails as X, VersionConflictError as Y, type VersionConflictErrorDetails as Z, getErrorSuggestion as _, ValidationError as a, isSystemError as a0, isTypeGraphError as a1, isUserRecoverable as a2, 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 RestrictedDeleteErrorDetails as y, type SchemaContentConflictErrorDetails as z };
+export { type TrustedImportErrorReason as $, type RecordedCaptureGuardCode as A, BackendDisposedError as B, CardinalityError as C, DatabaseOperationError as D, EagerMaterializationError as E, type RecordedCaptureGuardError as F, GraphAlgorithmConvergenceError as G, RestrictedDeleteError as H, InvalidEdgeWeightError as I, type RestrictedDeleteErrorDetails as J, KindNotFoundError as K, type SchemaContentConflictErrorDetails as L, MigrationError as M, NodeConstraintNotFoundError as N, SchemaMismatchError as O, type SchemaMismatchErrorDetails as P, StaleVersionError as Q, RECORDED_CAPTURE_GUARD_CODES as R, SchemaContentConflictError as S, TypeGraphError as T, type StaleVersionErrorDetails as U, type ValidationIssue as V, StoreNotInitializedError as W, type StoreNotInitializedErrorDetails as X, type StoreNotInitializedReason as Y, TransactionClosedError as Z, TrustedImportError as _, ValidationError as a, type TypeGraphErrorOptions as a0, UniquenessError as a1, type UniquenessErrorDetails as a2, UnsupportedBackendCapabilityError as a3, UnsupportedPredicateError as a4, type ValidationErrorDetails as a5, VersionConflictError as a6, type VersionConflictErrorDetails as a7, getErrorSuggestion as a8, isConstraintError as a9, isRecordedCaptureGuardError as aa, isSystemError as ab, isTypeGraphError as ac, isUserRecoverable as ad, 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 InvalidEdgeWeightErrorDetails as r, type InvalidEdgeWeightReason as s, type KindNotFoundErrorDetails as t, type MigrationErrorDetails as u, type NodeConstraintNotFoundErrorDetails as v, NodeIndexNotFoundError as w, type NodeIndexNotFoundErrorDetails as x, NodeNotFoundError as y, type NodeNotFoundErrorDetails as z };