@nicia-ai/typegraph 0.49.0 → 0.51.0

package/dist/index-D7d1u2gr.d.ts

@@ -1,1132 +0,0 @@
-import { bj as KindEntity } from './types-BqFZTQmV.js';
-import { M as MaterializeIndexesResult, S as SchemaDiff } from './materialize-indexes-DJ3ykH59.js';
-
-/**
- * TypeGraph Error Hierarchy
- *
- * All errors extend TypeGraphError with:
- * - `code`: Machine-readable error code for programmatic handling
- * - `category`: Classification for error handling strategies
- * - `suggestion`: Optional recovery guidance for users
- * - `details`: Structured context about the error
- *
- * @example
- * ```typescript
- * try {
- *   await store.nodes.Person.create({ name: "" });
- * } catch (error) {
- *   if (isTypeGraphError(error)) {
- *     console.error(error.toUserMessage());
- *     if (isUserRecoverable(error)) {
- *       // Show to user for correction
- *     }
- *   }
- * }
- * ```
- */
-
-/**
- * Error category for programmatic handling.
- *
- * - `user`: Caused by invalid input or incorrect usage. Recoverable by fixing input.
- * - `constraint`: Business rule or schema constraint violation. Recoverable by changing data.
- * - `system`: Internal error or infrastructure issue. May require investigation or retry.
- */
-type ErrorCategory = "user" | "constraint" | "system";
-/**
- * Options for TypeGraphError constructor.
- */
-type TypeGraphErrorOptions = Readonly<{
-    /** Structured context about the error */
-    details?: Record<string, unknown>;
-    /** Error category for handling strategies */
-    category: ErrorCategory;
-    /** Recovery guidance for users */
-    suggestion?: string;
-    /** Underlying cause of the error */
-    cause?: unknown;
-}>;
-/**
- * Base error class for all TypeGraph errors.
- *
- * Provides structured error information for both programmatic handling
- * and user-friendly messages.
- */
-declare class TypeGraphError extends Error {
-    /** Machine-readable error code (e.g., "VALIDATION_ERROR") */
-    readonly code: string;
-    /** Error category for handling strategies */
-    readonly category: ErrorCategory;
-    /** Structured context about the error */
-    readonly details: Readonly<Record<string, unknown>>;
-    /** Recovery guidance for users */
-    readonly suggestion?: string;
-    constructor(message: string, code: string, options: TypeGraphErrorOptions);
-    /**
-     * Returns a user-friendly error message with suggestion if available.
-     */
-    toUserMessage(): string;
-    /**
-     * Returns a detailed string representation for logging.
-     */
-    toLogString(): string;
-}
-/**
- * Validation issue from Zod or custom validation.
- */
-type ValidationIssue = Readonly<{
-    /** Path to the invalid field (e.g., "address.city") */
-    path: string;
-    /** Human-readable error message */
-    message: string;
-    /** Zod error code if from Zod validation */
-    code?: string;
-    /**
-     * The identity assertion the issue is about, carried structurally so
-     * consumers (e.g. interchange import error reporting) never have to parse
-     * the human-readable message for it.
-     */
-    assertionId?: string;
-}>;
-/**
- * The stable {@link ValidationIssue.code} every inverted-validity-window
- * refusal carries, so a caller can recognize that specific failure without
- * matching on the message. `ValidationError`'s own code is the family-wide
- * `VALIDATION_ERROR`, so the discriminator lives on the issue — mirroring the
- * identity-import window refusal (`IDENTITY_IMPORT_INVALID_WINDOW`).
- *
- * A write carrying it was refused because `validTo` precedes the row's
- * effective `validFrom`: the row would have stopped being true before it
- * started, observable at no `asOf` coordinate at all. Zero-width windows
- * (`validTo === validFrom`) are legal and never raise it.
- */
-declare const INVERTED_VALIDITY_WINDOW_CODE = "INVERTED_VALIDITY_WINDOW";
-/**
- * The stable {@link ValidationIssue.code} carried by a refusal to accept a
- * `validFrom` the write cannot apply: the target row is LIVE, and an in-place
- * update never rewrites a live row's lower bound — that bound is history.
- * `ValidationError`'s own code is the family-wide `VALIDATION_ERROR`, so the
- * discriminator lives on the issue — mirroring
- * {@link INVERTED_VALIDITY_WINDOW_CODE}.
- *
- * Only a bound naming a DIFFERENT instant than the row already stores raises it.
- * Restating the stored bound is legal and writes nothing new, and a resurrection
- * — which does rewrite `valid_from` — applies a stated bound rather than
- * refusing it.
- *
- * The message names both instants: the one stated and the one the row stores, so
- * the caller can restate the stored bound without a second read.
- */
-declare const IMMUTABLE_VALIDITY_LOWER_BOUND_CODE = "IMMUTABLE_VALIDITY_LOWER_BOUND";
-/**
- * Stable {@link ValidationIssue.code} for an edge-id ownership mismatch.
- *
- * Edge ids are graph-global. A collection-scoped write therefore has to prove
- * that the stored row has the collection's kind and, when the caller supplies
- * endpoints, the same immutable endpoints. This refusal prevents a collection
- * from mutating another kind's row and prevents an upsert from silently
- * ignoring an attempted repoint.
- */
-declare const EDGE_IDENTITY_MISMATCH_CODE = "EDGE_IDENTITY_MISMATCH";
-/**
- * The stable {@link ValidationIssue.code} every "this id is already taken"
- * create refusal carries, whichever way the create found out: its own existence
- * probe, or the engine refusing the INSERT. `ValidationError`'s own code is the
- * family-wide `VALIDATION_ERROR`, so the discriminator lives on the issue —
- * mirroring {@link INVERTED_VALIDITY_WINDOW_CODE}.
- *
- * `details.entityType` says whether a node or an edge was refused and
- * `details.kind` names its kind. `details.id` names the taken id, and is absent
- * only when the refused statement inserted MORE THAN ONE row: the engine reports
- * that the statement collided without saying which row did.
- */
-declare const ENTITY_ALREADY_EXISTS_CODE = "ENTITY_ALREADY_EXISTS";
-/**
- * Details for ValidationError.
- */
-type ValidationErrorDetails = Readonly<{
-    /** Type of entity being validated */
-    entityType?: KindEntity;
-    /** Kind/type name of the entity */
-    kind?: string;
-    /** Operation being performed */
-    operation?: "create" | "update" | "delete" | "hardDelete";
-    /** Entity ID if updating */
-    id?: string;
-    /** Individual validation issues */
-    issues: readonly ValidationIssue[];
-}>;
-/**
- * Thrown when schema validation fails during node or edge operations.
- *
- * @example
- * ```typescript
- * try {
- *   await store.nodes.Person.create({ email: "invalid" });
- * } catch (error) {
- *   if (error instanceof ValidationError) {
- *     console.log(error.details.issues);
- *     // [{ path: "email", message: "Invalid email" }]
- *   }
- * }
- * ```
- */
-declare class ValidationError extends TypeGraphError {
-    readonly details: ValidationErrorDetails;
-    constructor(message: string, details: ValidationErrorDetails, options?: {
-        cause?: unknown;
-        suggestion?: string;
-    });
-}
-/**
- * Details for NodeNotFoundError.
- */
-type NodeNotFoundErrorDetails = Readonly<{
-    kind: string;
-    id: string;
-}>;
-/**
- * Thrown when a node is not found.
- *
- * @example
- * ```typescript
- * try {
- *   await store.nodes.Person.get("nonexistent-id");
- * } catch (error) {
- *   if (error instanceof NodeNotFoundError) {
- *     console.log(error.details.kind, error.details.id);
- *   }
- * }
- * ```
- */
-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
- * `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 {
-    readonly details: KindNotFoundErrorDetails;
-    readonly kindName: string;
-    readonly entity: KindEntity;
-    constructor(kindName: string, entity: KindEntity, options?: Readonly<{
-        graphId?: string;
-        suggestion?: string;
-        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 {
-    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 {
-    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 {
-    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 {
-    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.
- *
- * Disjoint types cannot share the same ID - a node cannot be both
- * a Person and an Organization if they are declared disjoint.
- */
-declare class DisjointError extends TypeGraphError {
-    readonly details: DisjointErrorDetails;
-    constructor(details: DisjointErrorDetails, options?: {
-        cause?: unknown;
-    });
-}
-type IdentityContradictionErrorDetails = Readonly<{
-    /**
-     * The identity write that could not stand. `merge` is the post-write
-     * affected-class assertion a graph merge runs inside its commit
-     * transaction, which names the whole merge rather than a single assertion
-     * because the contradiction is a property of the state the merge would
-     * leave behind.
-     */
-    operation: "assertSame" | "assertDifferent" | "fold" | "import" | "merge";
-    a: Readonly<{
-        kind: string;
-        id: string;
-    }>;
-    b: Readonly<{
-        kind: string;
-        id: string;
-    }>;
-    reason: "different-assertion" | "same-class" | "disjoint-kinds";
-    conflictingAssertionId?: string;
-    conflictingKinds?: readonly [string, string];
-}>;
-/** Thrown when an identity mutation would make the ledger contradictory. */
-declare class IdentityContradictionError extends TypeGraphError {
-    readonly details: IdentityContradictionErrorDetails;
-    constructor(details: IdentityContradictionErrorDetails, options?: Readonly<{
-        cause?: unknown;
-    }>);
-}
-type IdentityValidityWindowErrorDetails = Readonly<{
-    reason: "future-valid-from" | "future-valid-to" | "inverted" | "overlapping-open-window";
-    validFrom: string;
-    validTo?: string;
-    operationInstant: string;
-}>;
-/** Thrown when an identity assertion validity window cannot be applied. */
-declare class IdentityValidityWindowError extends TypeGraphError {
-    readonly details: IdentityValidityWindowErrorDetails;
-    constructor(details: IdentityValidityWindowErrorDetails);
-}
-type IdentityEndpointValidityErrorDetails = Readonly<{
-    endpoint: Readonly<{
-        kind: string;
-        id: string;
-    }>;
-    assertionWindow: Readonly<{
-        validFrom: string;
-        validTo?: string;
-    }>;
-    endpointWindow: Readonly<{
-        validFrom?: string;
-        validTo?: string;
-        deletedAt?: string;
-    }>;
-}>;
-/** Thrown when an identity endpoint does not exist throughout the assertion window. */
-declare class IdentityEndpointValidityError extends TypeGraphError {
-    readonly details: IdentityEndpointValidityErrorDetails;
-    constructor(details: IdentityEndpointValidityErrorDetails);
-}
-type IdentitySeparationViolationErrorDetails = Readonly<{
-    graphId: string;
-    /**
-     * `"database"` when the CHECK constraint on the separation relation aborted
-     * the write — the backstop firing as designed. `"writer"` when the write was
-     * accepted, which means the relation was provisioned without its constraint
-     * and only the writer's own re-check caught the contradiction.
-     */
-    enforcedBy: "database" | "writer";
-    /** The single class key both endpoints collapsed onto. */
-    classKey: string;
-    /** The `different` assertion whose endpoints landed in one class. */
-    assertionId: string;
-    a: Readonly<{
-        kind: string;
-        id: string;
-    }>;
-    b: Readonly<{
-        kind: string;
-        id: string;
-    }>;
-}>;
-/**
- * Thrown when the derived separation relation refuses a write that would place
- * both endpoints of a current `different` assertion in one identity class.
- *
- * This is the database-level backstop beneath the plan-time simulation and the
- * applier's validation. Reaching it means an earlier layer let a contradiction
- * through: the transaction is aborted rather than committed, but the layer that
- * should have refused it typed and early is worth investigating.
- */
-declare class IdentitySeparationViolationError extends TypeGraphError {
-    readonly details: IdentitySeparationViolationErrorDetails;
-    constructor(details: IdentitySeparationViolationErrorDetails, options?: Readonly<{
-        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 {
-    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.
- *
- * This occurs when two operations try to update the same entity simultaneously.
- * The operation with the stale version fails.
- */
-declare class VersionConflictError extends TypeGraphError {
-    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 {
-    readonly details: SchemaMismatchErrorDetails;
-    constructor(details: SchemaMismatchErrorDetails, options?: {
-        cause?: unknown;
-    });
-}
-/**
- * Details for MigrationError.
- */
-/**
- * Why a migration operation failed. A stable discriminant so callers can
- * branch on the outcome instead of matching the message text, which is free
- * to be reworded in any release.
- */
-declare const MIGRATION_FAILURE_REASONS: readonly ["schema-behind", "breaking-change", "no-active-version", "version-not-found", "kind-removal"];
-type MigrationFailureReason = (typeof MIGRATION_FAILURE_REASONS)[number];
-/**
- * Structured context for a {@link MigrationError}, discriminated on `reason`.
- *
- * Modelled as a union rather than one shape with optional fields so the
- * payload a reason promises is the payload it must carry: narrowing on
- * `reason === "kind-removal"` gives you a non-optional `droppedKinds`, and the
- * constructor cannot be handed a `kind-removal` without one.
- *
- * The common fields are repeated per member rather than factored into a shared
- * base alias, which would be a hoisted-unexported symbol on the public
- * entrypoint.
- */
-type MigrationErrorDetails = Readonly<{
-    graphId: string;
-    fromVersion: number;
-    toVersion: number;
-    /** Stable discriminant — branch on this, not the message. */
-    reason: "schema-behind" | "breaking-change";
-    /**
-     * The structured diff behind the failure. Carries per-change `severity`
-     * alongside `hasChanges` / `hasBreakingChanges`, so a caller can decide
-     * "additive → proceed, incompatible → ask the user" without re-querying.
-     */
-    diff?: SchemaDiff;
-}> | Readonly<{
-    graphId: string;
-    fromVersion: number;
-    toVersion: number;
-    reason: "no-active-version" | "version-not-found";
-}> | Readonly<{
-    graphId: string;
-    fromVersion: number;
-    toVersion: number;
-    reason: "kind-removal";
-    /**
-     * The dropped kinds that still held rows, and so caused the refusal. A
-     * kind the commit drops but that is already empty is permitted and does
-     * NOT appear here. Both lists are sorted; at least one is non-empty.
-     */
-    droppedKinds: Readonly<{
-        nodes: readonly string[];
-        edges: readonly string[];
-    }>;
-}>;
-/**
- * Thrown when schema migration fails.
- */
-declare class MigrationError extends TypeGraphError {
-    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
- * 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 {
-    readonly details: EagerMaterializationErrorDetails;
-    /**
-     * 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[];
-}
-/**
- * Details for StaleVersionError. `actual` is the active version the rejecting
- * read observed, and is `0` only when the graph genuinely has no active version
- * (an initial-commit race where another writer initialized first, or a graph
- * whose schema rows were removed out of band). A concurrent advance always
- * reports the newly active version, so `0` is a reliable signal of absence
- * rather than of contention.
- */
-type StaleVersionErrorDetails = Readonly<{
-    graphId: string;
-    expected: number;
-    actual: number;
-}>;
-/**
- * Thrown by `commitSchemaVersion`, `setActiveVersion`, and the schema write
- * fence a schema-managed Store write takes, 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.
- */
-declare class StaleVersionError extends TypeGraphError {
-    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
- * 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: SchemaContentConflictErrorDetails;
-    constructor(details: SchemaContentConflictErrorDetails, options?: {
-        cause?: unknown;
-    });
-}
-/**
- * Thrown when graph configuration is invalid.
- *
- * This includes invalid schema definitions, ontology conflicts,
- * and other configuration issues detected at graph creation time.
- */
-declare class ConfigurationError extends TypeGraphError {
-    constructor(message: string, details?: Record<string, unknown>, options?: {
-        cause?: unknown;
-        suggestion?: string;
-    });
-}
-/**
- * Why a destructive contribution rebuild is refused.
- *
- * - `vector-source-unavailable` — the projection is vector storage.
- *   TypeGraph stores caller-supplied embeddings and nothing else: the
- *   vectors exist only in the table a rebuild would drop, so there is no
- *   source to reconstruct them from. Dropping anyway would silently
- *   destroy the embeddings and hand back storage that looks healthy and
- *   returns nothing. `store.reembedVectorField(kind, fieldPath, {
- *   embed })` is the sanctioned destructive path — it takes the callback
- *   that can regenerate what the drop destroys.
- * - `no-drop-ddl` — the active strategy declares no `dropDdl` for the
- *   contribution, so TypeGraph does not know how to tear its storage
- *   down. Synthesizing a `DROP TABLE` from the resolved name would
- *   guess at a teardown the strategy never sanctioned.
- * - `no-schema-fence` — the backend exposes no transactional schema
- *   fence (`schemaWriteTransaction`), so the drop, recreate, refill, and
- *   stamp could not be made atomic. Running them unfenced could leave
- *   storage attested but empty, or a concurrent schema writer
- *   interleaved with the drop.
- * - `shared-storage-in-use` — the contribution's recorded shape is stale,
- *   so only recreating its storage repairs it, but that storage is one
- *   table holding other graphs' rows as well. Their content is derived
- *   from their own nodes through their own schemas, so this process cannot
- *   put it back. A rebuild that dropped anyway would leave every other
- *   graph's search silently empty; one that re-stamped this graph's marker
- *   without the drop would bless a physical shape nothing verified.
- */
-type ContributionRebuildRefusal = "vector-source-unavailable" | "no-drop-ddl" | "no-schema-fence" | "shared-storage-in-use";
-/**
- * Thrown when `store.rebuildContribution()` cannot honor a rebuild.
- *
- * A refusal, never a partial attempt: nothing has been dropped when this
- * throws. The point is that the alternative — proceeding — destroys data
- * that cannot be reconstructed, so the operation declines instead of
- * quietly doing less than its name promises.
- */
-declare class ContributionRebuildUnsupportedError extends TypeGraphError {
-    readonly reason: ContributionRebuildRefusal;
-    constructor(reason: ContributionRebuildRefusal, details?: Readonly<Record<string, unknown>>, options?: {
-        cause?: unknown;
-    });
-}
-/**
- * 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, options?: Readonly<{
-        oscillating?: boolean;
-    }>);
-}
-/** 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" | "identity_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;
-    }>);
-}
-/**
- * Thrown to a graph export stream's consumer when the caller's `AbortSignal`
- * settled the stream instead of it reaching its end.
- *
- * Raised only after the export has given back everything it took, so receiving
- * it means the connection is already usable again. WHAT it took depends on the
- * backend: an export on one reporting `capabilities.transactions` holds a
- * repeatable-read snapshot (and, on a serialized connection, that connection's
- * stream lease), and both are settled before this is thrown; an export on a
- * backend without transactions holds neither, and its remaining reads are
- * simply abandoned — its already-delivered chunks were never one snapshot to
- * begin with. The message says which case applies. `cause` carries the signal's
- * own `reason` when the caller supplied one.
- */
-declare class ExportStreamCancelledError extends TypeGraphError {
-    constructor(message: string, details?: Readonly<Record<string, unknown>>, options?: Readonly<{
-        cause?: unknown;
-        suggestion?: string;
-    }>);
-}
-/**
- * Thrown when an export stream's consumer leaves a delivered chunk
- * unacknowledged for longer than its configured idle timeout.
- *
- * The timeout measures consumer idleness only: it starts when a chunk is
- * yielded and stops when the consumer asks for the next one. Receiving this
- * error means the timed-out export has settled its snapshot transaction and
- * released any serialized connection lease it held. `details.idleTimeoutMs`
- * carries the configured bound.
- */
-declare class ExportStreamIdleTimeoutError extends TypeGraphError {
-    constructor(graphId: string, idleTimeoutMs: number, transactional: boolean);
-}
-/**
- * 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
- * is surfaced in `details.reason` for programmatic handling.
- *
- * - `missing`: no durable materialization marker exists — the database
- *   was never initialized for this graph's runtime contributions.
- * - `stale`: a marker exists but its recorded signature no longer
- *   matches the resolved contribution DDL (strategy swap or DDL drift).
- *   The hot path refuses rather than silently re-materializing.
- * - `failed`: the most recent boot-time materialization attempt
- *   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- 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 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 {
-    readonly details: StoreNotInitializedErrorDetails;
-    constructor(graphId: string, reason: StoreNotInitializedReason, options?: {
-        cause?: unknown;
-        details?: Readonly<Record<string, unknown>> & Readonly<{
-            graphId?: never;
-            reason?: never;
-        }>;
-    });
-}
-/** Details for a runtime contribution whose durable marker outlived storage. */
-type ContributionUnavailableErrorDetails = Readonly<{
-    graphId: string;
-    logicalName: "fulltext";
-    physicalName: string;
-    state: "physical-storage-missing";
-}>;
-/**
- * Thrown when a gated fulltext operation discovers that materialized storage
- * disappeared after its durable marker recorded successful initialization.
- */
-declare class ContributionUnavailableError extends TypeGraphError {
-    readonly details: ContributionUnavailableErrorDetails;
-    constructor(graphId: string, physicalName: string, options?: Readonly<{
-        cause?: unknown;
-    }>);
-}
-/**
- * Details for DatabaseOperationError.
- */
-type DatabaseOperationErrorDetails = Readonly<{
-    operation: string;
-    entity: string;
-    /**
-     * `"duplicate_key"` means the engine refused the write because the entity's
-     * identity is already taken — the shape a concurrent create of the same new id
-     * produces on an engine that does not serialize the two writers. It is a
-     * *classified* driver failure, so callers that own a better error for the
-     * condition (the create paths, which report it as "already exists") translate
-     * it rather than surfacing it.
-     */
-    reason?: "no_row_returned" | "duplicate_key";
-    /**
-     * The entities the failed statement tried to insert, carried structurally so a
-     * translating caller never has to parse the driver's message for them. One
-     * element for a single insert; for a batch, every row in the failing chunk —
-     * the engine reports the collision without saying which row lost.
-     */
-    attempted?: readonly Readonly<{
-        kind: string;
-        id: string;
-    }>[];
-}>;
-/**
- * Thrown when a database operation fails unexpectedly.
- *
- * This indicates a system-level failure in the database backend,
- * not a user-recoverable error.
- */
-declare class DatabaseOperationError extends TypeGraphError {
-    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
- * `embedding(N)` was changed to `embedding(M)`. The stored vectors are invalid
- * under the new dimension and cannot be converted, only recomputed, so this is
- * a deliberate app-driven migration: call
- * `store.reembedVectorField(kind, fieldPath, ...)` to recreate the storage at
- * the new dimension and re-embed existing rows.
- */
-declare class EmbeddingDimensionChangedError extends TypeGraphError {
-    readonly details: EmbeddingDimensionChangedErrorDetails;
-    constructor(message: string, details: EmbeddingDimensionChangedErrorDetails, options?: {
-        cause?: unknown;
-    });
-}
-/**
- * Thrown when a query predicate cannot be compiled for the target database.
- */
-declare class UnsupportedPredicateError extends TypeGraphError {
-    constructor(message: string, details?: Readonly<Record<string, unknown>>, options?: {
-        cause?: unknown;
-        suggestion?: string;
-    });
-}
-/**
- * Thrown when a compiler invariant is violated.
- *
- * This indicates a bug in the query compiler — the compiler reached
- * a state that should be unreachable. These errors are not user-recoverable.
- */
-declare class CompilerInvariantError extends TypeGraphError {
-    constructor(message: string, details?: Readonly<Record<string, unknown>>, options?: {
-        cause?: unknown;
-    });
-}
-/**
- * Thrown when an operation is attempted on a backend that has been disposed.
- *
- * This typically occurs during runtime teardown — for example, when a
- * Cloudflare Workers test runner resets Durable Object storage while
- * the TypeGraph backend still has queued operations.
- */
-declare class BackendDisposedError extends TypeGraphError {
-    constructor(options?: {
-        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.
- *
- * @example
- * ```typescript
- * try {
- *   await store.nodes.Person.create({});
- * } catch (error) {
- *   if (isTypeGraphError(error)) {
- *     console.log(error.code, error.category);
- *   }
- * }
- * ```
- */
-declare function isTypeGraphError(error: unknown): error is TypeGraphError;
-/**
- * Check if error is recoverable by user action (user or constraint error).
- *
- * User-recoverable errors can typically be resolved by:
- * - Fixing invalid input data
- * - Using different IDs or values
- * - Deleting conflicting data first
- *
- * @example
- * ```typescript
- * if (isUserRecoverable(error)) {
- *   showErrorToUser(error.toUserMessage());
- * } else {
- *   logAndAlertOps(error);
- * }
- * ```
- */
-declare function isUserRecoverable(error: unknown): boolean;
-/**
- * Check if error indicates a system/infrastructure issue.
- *
- * System errors typically require:
- * - Retry logic (for transient failures)
- * - Investigation (for persistent failures)
- * - Ops team notification
- */
-declare function isSystemError(error: unknown): boolean;
-/**
- * Check if error is a constraint violation.
- */
-declare function isConstraintError(error: unknown): boolean;
-/**
- * Extract suggestion from error if available.
- */
-declare function getErrorSuggestion(error: unknown): string | undefined;
-
-export { type NodeIndexNotFoundErrorDetails as $, IdentityContradictionError as A, BackendDisposedError as B, CardinalityError as C, DatabaseOperationError as D, EDGE_IDENTITY_MISMATCH_CODE as E, type IdentityContradictionErrorDetails as F, GraphAlgorithmConvergenceError as G, IdentityEndpointValidityError as H, IMMUTABLE_VALIDITY_LOWER_BOUND_CODE as I, type IdentityEndpointValidityErrorDetails as J, IdentitySeparationViolationError as K, type IdentitySeparationViolationErrorDetails as L, IdentityValidityWindowError as M, type IdentityValidityWindowErrorDetails as N, InvalidEdgeWeightError as O, type InvalidEdgeWeightErrorDetails as P, type InvalidEdgeWeightReason as Q, KindNotFoundError as R, type KindNotFoundErrorDetails as S, MIGRATION_FAILURE_REASONS as T, MigrationError as U, type ValidationIssue as V, type MigrationErrorDetails as W, type MigrationFailureReason as X, NodeConstraintNotFoundError as Y, type NodeConstraintNotFoundErrorDetails as Z, NodeIndexNotFoundError as _, ValidationError as a, NodeNotFoundError as a0, type NodeNotFoundErrorDetails as a1, RECORDED_CAPTURE_GUARD_CODES as a2, type RecordedCaptureGuardCode as a3, type RecordedCaptureGuardError as a4, RestrictedDeleteError as a5, type RestrictedDeleteErrorDetails as a6, SchemaContentConflictError as a7, type SchemaContentConflictErrorDetails as a8, SchemaMismatchError as a9, type SchemaMismatchErrorDetails as aa, StaleVersionError as ab, type StaleVersionErrorDetails as ac, StoreNotInitializedError as ad, type StoreNotInitializedErrorDetails as ae, type StoreNotInitializedReason as af, TransactionClosedError as ag, TrustedImportError as ah, type TrustedImportErrorReason as ai, TypeGraphError as aj, type TypeGraphErrorOptions as ak, UniquenessError as al, type UniquenessErrorDetails as am, UnsupportedBackendCapabilityError as an, UnsupportedPredicateError as ao, type ValidationErrorDetails as ap, VersionConflictError as aq, type VersionConflictErrorDetails as ar, getErrorSuggestion as as, isConstraintError as at, isRecordedCaptureGuardError as au, isSystemError as av, isTypeGraphError as aw, isUserRecoverable as ax, type CardinalityErrorDetails as b, CompilerInvariantError as c, ConfigurationError as d, type ContributionRebuildRefusal as e, ContributionRebuildUnsupportedError as f, ContributionUnavailableError as g, type ContributionUnavailableErrorDetails as h, type DatabaseOperationErrorDetails as i, DisjointError as j, type DisjointErrorDetails as k, ENTITY_ALREADY_EXISTS_CODE as l, EagerMaterializationError as m, type EagerMaterializationErrorDetails as n, EdgeNotFoundError as o, type EdgeNotFoundErrorDetails as p, EmbeddingDimensionChangedError as q, type EmbeddingDimensionChangedErrorDetails as r, EndpointError as s, type EndpointErrorDetails as t, EndpointNotFoundError as u, type EndpointNotFoundErrorDetails as v, type ErrorCategory as w, ExportStreamCancelledError as x, ExportStreamIdleTimeoutError as y, INVERTED_VALIDITY_WINDOW_CODE as z };