@abloatai/ablo 0.35.0 → 0.37.0

package/dist/transaction/errorCodes.d.ts

@@ -1,403 +0,0 @@
-/**
- * The registry of every stable error code Ablo can produce. Error handling has
- * two levels, and this file defines the finer one.
- *
- *   - The `type` is the coarse category, and each one corresponds to an
- *     {@link AbloError} subclass such as `AbloPermissionError` or
- *     `AbloValidationError`. Catching by `instanceof` is equivalent to switching
- *     on `error.type`.
- *   - The `code` is the fine-grained, machine-readable identifier defined here,
- *     written in `snake_case` (for example `entity_claimed` or `queue_too_deep`).
- *     This is what you switch on to handle a specific situation, and what the
- *     documentation link for an error is built from.
- *
- * The client, the server, and the tool-calling boundary all speak this same
- * vocabulary, which makes the registry part of the API contract. Two things
- * follow from that:
- *
- *   1. {@link ErrorCode} is a closed set — plus the dynamic `policy:${string}`
- *      family — so producing a code that is not registered here is a
- *      compile-time error. The {@link AbloError} constructor accepts only a
- *      registered code. The one place an arbitrary string is accepted as a code
- *      is where an incoming response is parsed, which lets an older client
- *      tolerate a code from a newer server it does not yet recognize.
- *   2. The codes marked `surface: 'wire'` are the ones that cross the network
- *      and are mapped at the HTTP and tool-calling boundaries; the public error
- *      documentation is generated from them. Codes marked `surface: 'client'`
- *      describe local mistakes — accessing the database before opening it, or
- *      writing to a model that was never registered — and are never sent over
- *      the network, so they carry no HTTP status.
- */
-import { z } from 'zod';
-/**
- * The version of the error contract: the envelope shape together with the set of
- * codes and their meanings. It is date-based, and changes only when the contract
- * changes in a way a consumer can observe — a code added or removed, an HTTP
- * status changed, or an envelope field changed. It is emitted in the generated
- * error documentation and returned on the `Ablo-Version` response header, so a
- * consumer can detect when its expected contract has drifted from the server's.
- */
-export declare const ERROR_CONTRACT_VERSION = "2026-07-21";
-/** A coarse grouping of error codes, used to organize metrics and documentation. */
-export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | 'bootstrap' | 'transport' | 'rate_limit' | 'server' | 'client';
-/**
- * A closed classification of how a failure can be recovered from — a level above
- * the raw {@link ErrorCode}. Where a code says what went wrong, a recovery class
- * says what a client should do about it, which is exactly the distinction the
- * connection layer needs to decide between retrying, re-minting a credential, and
- * signing the user out. Every code maps to one of these, and the set is
- * validated at runtime.
- *
- *   - `access_credential_expiry` — the short-lived access credential the client
- *     presents (its ephemeral `ek_` or `rk_` key) has expired, while the
- *     underlying login is still valid. The remedy is to mint a fresh key from the
- *     session and retry the same request. This does not sign the user out; a
- *     short-lived key expiring — for example after a laptop resumes from sleep —
- *     is routine.
- *   - `session_expiry` — the long-lived login itself is gone. This is terminal:
- *     sign out and route to re-authentication.
- *   - `auth_blocked` — the server was reachable but rejected the kind or
- *     configuration of the credential (wrong key type, untrusted issuer, no
- *     organization). Re-authenticating would present the same rejected credential
- *     and loop, so the client should stop rather than reconnect or sign out.
- *   - `permission` — an authorization denial (403) based on scope, role, or
- *     membership.
- *   - `transient` — a temporary failure, such as a server error or lease
- *     contention, that may succeed if the same request is retried unchanged.
- *   - `none` — not a recoverable authentication condition: validation errors,
- *     not-found, local invariants, and any code an older client does not
- *     recognize.
- */
-export declare const RECOVERY_CLASSES: readonly ["access_credential_expiry", "session_expiry", "auth_blocked", "permission", "transient", "none"];
-/** A Zod enum over {@link RECOVERY_CLASSES}, for validating a recovery class at
- *  runtime. */
-export declare const recoveryClassSchema: z.ZodEnum<{
-    permission: "permission";
-    access_credential_expiry: "access_credential_expiry";
-    session_expiry: "session_expiry";
-    auth_blocked: "auth_blocked";
-    transient: "transient";
-    none: "none";
-}>;
-/** The recovery classification of a failure. See {@link RECOVERY_CLASSES}. */
-export type RecoveryClass = z.infer<typeof recoveryClassSchema>;
-/** One entry in the registry: everything known about a single error code.
- *  `httpStatus` is present only for codes that cross the network, since an HTTP
- *  status is a property of the wire boundary rather than of a purely local
- *  error. */
-export interface ErrorCodeSpec {
-    readonly category: ErrorCategory;
-    /** `'wire'` for a code that crosses the network and is part of the API
-     *  contract; `'client'` for a local error that is never serialized. */
-    readonly surface: 'wire' | 'client';
-    /** Canonical HTTP status for the wire boundary. Omitted for client codes. */
-    readonly httpStatus?: number;
-    /** Whether the same request can succeed on a later retry without the caller
-     *  changing anything. `false` for permission, validation, and not-found;
-     *  `true` for transient transport failures and lease contention. */
-    readonly retryable: boolean;
-    /** A one-line, human-readable description of the error — also the source text
-     *  for its documentation page. */
-    readonly message: string;
-    /**
-     * An explicit {@link RecoveryClass}, set only where it differs from what the
-     * category, HTTP status, and `retryable` flag already imply — mainly the few
-     * authentication codes whose remedy the status alone cannot reveal, such as
-     * telling a session expiry apart from an access-credential expiry. For every
-     * other code the recovery class is derived by {@link classifyRecovery}, so
-     * this field can be left unset.
-     */
-    readonly recovery?: RecoveryClass;
-}
-/**
- * The complete set of stable error codes, keyed by code. A code must be added
- * here before it can be thrown, since the {@link AbloError} constructor accepts
- * only codes from this set.
- */
-export declare const ERROR_CODES: {
-    readonly apikey_invalid: ErrorCodeSpec;
-    readonly apikey_revoked: ErrorCodeSpec;
-    readonly apikey_expired: ErrorCodeSpec;
-    readonly apikey_missing: ErrorCodeSpec;
-    readonly api_key_required: ErrorCodeSpec;
-    readonly capability_id_missing: ErrorCodeSpec;
-    readonly exchange_failed: ErrorCodeSpec;
-    readonly identity_resolve_failed: ErrorCodeSpec;
-    readonly auth_no_credentials: ErrorCodeSpec;
-    readonly identity_missing_organization: ErrorCodeSpec;
-    readonly session_expired: ErrorCodeSpec;
-    readonly jwt_invalid: ErrorCodeSpec;
-    readonly jwt_malformed: ErrorCodeSpec;
-    readonly jwt_missing_issuer: ErrorCodeSpec;
-    readonly jwt_issuer_untrusted: ErrorCodeSpec;
-    readonly jwt_signature_invalid: ErrorCodeSpec;
-    readonly jwt_audience_mismatch: ErrorCodeSpec;
-    readonly jwt_missing_subject: ErrorCodeSpec;
-    readonly jwt_missing_organization: ErrorCodeSpec;
-    readonly jwt_expired: ErrorCodeSpec;
-    readonly jwt_org_membership_denied: ErrorCodeSpec;
-    readonly file_upload_auth_required: ErrorCodeSpec;
-    readonly browser_apikey_blocked: ErrorCodeSpec;
-    readonly datasource_connection_unsupported: ErrorCodeSpec;
-    readonly capability_scope_denied: ErrorCodeSpec;
-    readonly issuer_register_forbidden: ErrorCodeSpec;
-    readonly capability_invalid: ErrorCodeSpec;
-    readonly test_database_not_registered: ErrorCodeSpec;
-    readonly tenant_routing_failed: ErrorCodeSpec;
-    readonly database_role_cannot_enforce_rls: ErrorCodeSpec;
-    readonly database_role_unreadable: ErrorCodeSpec;
-    readonly database_tables_unforced_rls: ErrorCodeSpec;
-    readonly database_host_not_allowed: ErrorCodeSpec;
-    readonly connected_database_unreachable: ErrorCodeSpec;
-    readonly byo_role_cannot_enforce_rls: ErrorCodeSpec;
-    readonly byo_role_unreadable: ErrorCodeSpec;
-    readonly byo_tenant_tables_unforced_rls: ErrorCodeSpec;
-    readonly byo_host_not_allowed: ErrorCodeSpec;
-    readonly claim_conflict: ErrorCodeSpec;
-    readonly claim_lost: ErrorCodeSpec;
-    readonly fence_token_stale: ErrorCodeSpec;
-    readonly entity_claimed: ErrorCodeSpec;
-    readonly malformed_claim: ErrorCodeSpec;
-    readonly malformed_subscription: ErrorCodeSpec;
-    readonly malformed_response: ErrorCodeSpec;
-    readonly model_claimed: ErrorCodeSpec;
-    readonly model_claimed_timeout: ErrorCodeSpec;
-    readonly model_claim_not_configured: ErrorCodeSpec;
-    readonly model_join_not_configured: ErrorCodeSpec;
-    readonly stale_context: ErrorCodeSpec;
-    readonly contention_exhausted: ErrorCodeSpec;
-    readonly update_aborted: ErrorCodeSpec;
-    readonly idempotency_conflict: ErrorCodeSpec;
-    readonly idempotency_key_expired: ErrorCodeSpec;
-    readonly source_transport_pinned: ErrorCodeSpec;
-    readonly idempotency_key_too_long: ErrorCodeSpec;
-    readonly write_options_invalid: ErrorCodeSpec;
-    readonly write_payload_invalid: ErrorCodeSpec;
-    readonly source_operation_id_required: ErrorCodeSpec;
-    readonly source_adapter_misconfigured: ErrorCodeSpec;
-    readonly source_event_invalid: ErrorCodeSpec;
-    readonly duration_invalid: ErrorCodeSpec;
-    readonly schema_definition_invalid: ErrorCodeSpec;
-    readonly cli_invalid_arguments: ErrorCodeSpec;
-    readonly commit_operation_required: ErrorCodeSpec;
-    readonly commit_operation_invalid: ErrorCodeSpec;
-    readonly commit_operation_model_required: ErrorCodeSpec;
-    readonly commit_operations_ambiguous: ErrorCodeSpec;
-    readonly commit_too_many_operations: ErrorCodeSpec;
-    readonly model_required_field_missing: ErrorCodeSpec;
-    readonly model_identifier_missing: ErrorCodeSpec;
-    readonly snapshot_reserved_key: ErrorCodeSpec;
-    readonly mesh_message_invalid_input: ErrorCodeSpec;
-    readonly mesh_message_from_id_spoof: ErrorCodeSpec;
-    readonly mesh_message_from_kind_mismatch: ErrorCodeSpec;
-    readonly agent_perception_missing_context: ErrorCodeSpec;
-    readonly entity_not_found: ErrorCodeSpec;
-    readonly model_not_found: ErrorCodeSpec;
-    readonly mutate_update_entity_not_found: ErrorCodeSpec;
-    readonly no_data_source_registered: ErrorCodeSpec;
-    readonly task_id_missing: ErrorCodeSpec;
-    readonly not_null_violation: ErrorCodeSpec;
-    readonly foreign_key_violation: ErrorCodeSpec;
-    readonly unique_violation: ErrorCodeSpec;
-    readonly check_violation: ErrorCodeSpec;
-    readonly constraint_violation: ErrorCodeSpec;
-    readonly column_type_mismatch: ErrorCodeSpec;
-    readonly server_execute_unknown_model: ErrorCodeSpec;
-    readonly mutate_create_unknown_model: ErrorCodeSpec;
-    readonly tenant_model_columns_unknown: ErrorCodeSpec;
-    readonly tenant_model_missing_organization_id: ErrorCodeSpec;
-    readonly schema_mutable_missing_meta: ErrorCodeSpec;
-    readonly schema_scope_kind_invalid: ErrorCodeSpec;
-    readonly schema_field_not_camelcase: ErrorCodeSpec;
-    readonly schema_field_consecutive_caps: ErrorCodeSpec;
-    readonly schema_reserved_field: ErrorCodeSpec;
-    readonly schema_grants_shape_invalid: ErrorCodeSpec;
-    readonly schema_grants_identifier_unsafe: ErrorCodeSpec;
-    readonly schema_grants_relation_kind: ErrorCodeSpec;
-    readonly schema_grants_relation_missing: ErrorCodeSpec;
-    readonly schema_grants_target_not_scope_root: ErrorCodeSpec;
-    readonly drop_field: ErrorCodeSpec;
-    readonly drop_model: ErrorCodeSpec;
-    readonly lossy_recreate: ErrorCodeSpec;
-    readonly made_required: ErrorCodeSpec;
-    readonly required_field_added: ErrorCodeSpec;
-    readonly enum_value_removed: ErrorCodeSpec;
-    readonly risky_cast: ErrorCodeSpec;
-    readonly claim_lease_unavailable: ErrorCodeSpec;
-    readonly claim_not_wired: ErrorCodeSpec;
-    readonly claim_queued: ErrorCodeSpec;
-    readonly claim_wait_aborted: ErrorCodeSpec;
-    readonly claim_wait_poll_interval_required: ErrorCodeSpec;
-    readonly grant_timeout: ErrorCodeSpec;
-    readonly bootstrap_fetch_timeout: ErrorCodeSpec;
-    readonly bootstrap_cancelled: ErrorCodeSpec;
-    readonly bootstrap_offline: ErrorCodeSpec;
-    readonly bootstrap_offline_no_cache: ErrorCodeSpec;
-    readonly bootstrap_response_invalid: ErrorCodeSpec;
-    readonly bootstrap_response_schema_invalid: ErrorCodeSpec;
-    readonly exchange_malformed_response: ErrorCodeSpec;
-    readonly exchange_network_error: ErrorCodeSpec;
-    readonly source_network_error: ErrorCodeSpec;
-    readonly source_unreachable: ErrorCodeSpec;
-    readonly data_source_blocked: ErrorCodeSpec;
-    readonly identity_network_error: ErrorCodeSpec;
-    readonly commit_no_result: ErrorCodeSpec;
-    readonly commit_failed: ErrorCodeSpec;
-    readonly replication_lag_timeout: ErrorCodeSpec;
-    readonly commit_offline_grace_expired: ErrorCodeSpec;
-    readonly queue_too_deep: ErrorCodeSpec;
-    readonly flush_timeout: ErrorCodeSpec;
-    readonly wait_for_timeout: ErrorCodeSpec;
-    readonly instance_at_capacity: ErrorCodeSpec;
-    readonly fetch_unavailable: ErrorCodeSpec;
-    readonly base_url_missing: ErrorCodeSpec;
-    readonly sync_not_ready: ErrorCodeSpec;
-    readonly ws_not_ready: ErrorCodeSpec;
-    readonly quota_exceeded: ErrorCodeSpec;
-    readonly connection_limit_exceeded: ErrorCodeSpec;
-    readonly rate_limit_exceeded: ErrorCodeSpec;
-    readonly internal_error: ErrorCodeSpec;
-    readonly quota_lookup_failed: ErrorCodeSpec;
-    readonly rate_limiter_unavailable: ErrorCodeSpec;
-    readonly invalid_options: ErrorCodeSpec;
-    readonly no_ablo_provider: ErrorCodeSpec;
-    readonly no_sync_group_provider: ErrorCodeSpec;
-    readonly sync_context_missing_provider: ErrorCodeSpec;
-    readonly db_not_opened: ErrorCodeSpec;
-    readonly db_store_not_found: ErrorCodeSpec;
-    readonly db_unknown_action_type: ErrorCodeSpec;
-    readonly idb_unavailable: ErrorCodeSpec;
-    readonly meta_db_not_initialized: ErrorCodeSpec;
-    readonly sync_client_db_missing: ErrorCodeSpec;
-    readonly lazy_ref_db_missing: ErrorCodeSpec;
-    readonly lazy_ref_pool_missing: ErrorCodeSpec;
-    readonly model_class_not_registered: ErrorCodeSpec;
-    readonly model_not_registered: ErrorCodeSpec;
-    readonly model_disposed: ErrorCodeSpec;
-    readonly pool_model_class_not_registered: ErrorCodeSpec;
-    readonly pool_registry_missing: ErrorCodeSpec;
-    readonly pool_subscribe_unregistered: ErrorCodeSpec;
-    readonly registry_invalid_constructor: ErrorCodeSpec;
-    readonly registry_not_initialized: ErrorCodeSpec;
-    readonly registry_property_conflict: ErrorCodeSpec;
-    readonly registry_reference_unknown_target: ErrorCodeSpec;
-    readonly registry_reference_unresolved: ErrorCodeSpec;
-    readonly registry_unknown_model: ErrorCodeSpec;
-    readonly query_returns_unknown_model: ErrorCodeSpec;
-    readonly store_create_schema_missing: ErrorCodeSpec;
-    readonly store_manager_unknown_model: ErrorCodeSpec;
-    readonly store_query_schema_missing: ErrorCodeSpec;
-    readonly store_query_unknown_model: ErrorCodeSpec;
-    readonly transaction_mutate_unknown_model: ErrorCodeSpec;
-    readonly transaction_read_unknown_model: ErrorCodeSpec;
-    readonly mutator_registry_duplicate: ErrorCodeSpec;
-    readonly mutator_registry_unnamed_def: ErrorCodeSpec;
-    readonly mutators_schema_missing: ErrorCodeSpec;
-    readonly undo_scope_schema_missing: ErrorCodeSpec;
-    readonly undo_entry_invalid: ErrorCodeSpec;
-    readonly mock_mutation_failed: ErrorCodeSpec;
-    readonly mock_unsupported_operation: ErrorCodeSpec;
-    readonly invalid_body: ErrorCodeSpec;
-    readonly invalid_json: ErrorCodeSpec;
-    readonly capability_id_required: ErrorCodeSpec;
-    readonly organization_mismatch: ErrorCodeSpec;
-    readonly project_scope_denied: ErrorCodeSpec;
-    readonly project_slug_taken: ErrorCodeSpec;
-    readonly forbidden: ErrorCodeSpec;
-    readonly source_api_key_unresolved: ErrorCodeSpec;
-    readonly capability_auth_disabled: ErrorCodeSpec;
-    readonly capability_rotation_unavailable: ErrorCodeSpec;
-    readonly provisioner_unavailable: ErrorCodeSpec;
-    readonly invalid_model: ErrorCodeSpec;
-    readonly invalid_id: ErrorCodeSpec;
-    readonly unknown_model: ErrorCodeSpec;
-    readonly model_not_tenant_scoped: ErrorCodeSpec;
-    readonly source_tenancy_not_enforced: ErrorCodeSpec;
-    readonly user_scope_not_enforced: ErrorCodeSpec;
-    readonly model_not_provisioned: ErrorCodeSpec;
-    readonly schema_table_invalid: ErrorCodeSpec;
-    readonly schema_scope_invalid: ErrorCodeSpec;
-    readonly entity_fetch_failed: ErrorCodeSpec;
-    readonly events_required: ErrorCodeSpec;
-    readonly ingest_failed: ErrorCodeSpec;
-    readonly migration_failed: ErrorCodeSpec;
-    readonly schema_provisioning_forbidden: ErrorCodeSpec;
-    readonly model_query_failed: ErrorCodeSpec;
-    readonly queries_required: ErrorCodeSpec;
-    readonly query_unsupported_operator: ErrorCodeSpec;
-    readonly query_invalid_like_pattern: ErrorCodeSpec;
-    readonly query_invalid_boolean: ErrorCodeSpec;
-    readonly protocol_version_unsupported: ErrorCodeSpec;
-    readonly database_unreachable: ErrorCodeSpec;
-    readonly database_not_replication_ready: ErrorCodeSpec;
-    readonly database_already_connected: ErrorCodeSpec;
-    readonly replication_publication_drift: ErrorCodeSpec;
-    readonly query_unknown_relation: ErrorCodeSpec;
-    readonly query_relation_target_unknown: ErrorCodeSpec;
-    readonly query_invalid_identifier: ErrorCodeSpec;
-    readonly org_id_required: ErrorCodeSpec;
-    readonly presence_identity_required: ErrorCodeSpec;
-    readonly upload_fields_required: ErrorCodeSpec;
-    readonly upload_items_required: ErrorCodeSpec;
-    readonly presigned_url_failed: ErrorCodeSpec;
-    readonly upload_not_configured: ErrorCodeSpec;
-    readonly task_id_required: ErrorCodeSpec;
-    readonly claim_id_required: ErrorCodeSpec;
-    readonly commit_operation_action_required: ErrorCodeSpec;
-    readonly commit_operation_unsupported: ErrorCodeSpec;
-    readonly usage_invalid: ErrorCodeSpec;
-    readonly invalid_request: ErrorCodeSpec;
-    readonly capability_not_found: ErrorCodeSpec;
-    readonly claim_not_found: ErrorCodeSpec;
-    readonly invalid_participant_kind: ErrorCodeSpec;
-    readonly invalid_sync_group: ErrorCodeSpec;
-    readonly narrow_scope_required: ErrorCodeSpec;
-    readonly wide_scope_forbidden: ErrorCodeSpec;
-    readonly capability_required: ErrorCodeSpec;
-    readonly position_missing_parent: ErrorCodeSpec;
-    readonly position_unknown_sibling: ErrorCodeSpec;
-    readonly schema_too_large: ErrorCodeSpec;
-    readonly request_too_large: ErrorCodeSpec;
-    readonly invalid_schema: ErrorCodeSpec;
-    readonly incompatible_change: ErrorCodeSpec;
-};
-/**
- * The type of a valid error code: any key registered in {@link ERROR_CODES},
- * plus the dynamic `policy:${reason}` family, where a conflict-policy rejection
- * names its reason inline. The {@link AbloError} constructor accepts only this
- * type, so a typo or an unregistered code is a compile-time error. Only the
- * boundary that parses an incoming response casts an arbitrary string to this
- * type, which preserves forward compatibility with a newer server.
- */
-export type ErrorCode = keyof typeof ERROR_CODES | `policy:${string}`;
-/** The subset of {@link ErrorCode} values that cross the network — the codes
- *  that make up the API contract, from which the HTTP and tool-calling
- *  boundaries map and the public documentation is generated. */
-export type WireErrorCode = {
-    [K in keyof typeof ERROR_CODES]: (typeof ERROR_CODES)[K]['surface'] extends 'wire' ? K : never;
-}[keyof typeof ERROR_CODES];
-/** Looks up the {@link ErrorCodeSpec} for a code. Returns `undefined` for the
- *  dynamic `policy:*` family and for any newer code this client does not yet
- *  recognize. */
-export declare function errorCodeSpec(code: string): ErrorCodeSpec | undefined;
-/** Reports whether a code is marked retryable. Unknown and dynamic codes
- *  default to non-retryable, so an unrecognized failure is never retried
- *  automatically. */
-export declare function isRetryableCode(code: string): boolean;
-/**
- * Classifies a code into its {@link RecoveryClass} — the single value the
- * connection layer and the network probe branch on to decide how to recover.
- *
- * The registry is the source of truth. An explicit `recovery` on the code's spec
- * wins; it is set only on the few authentication codes whose remedy the HTTP
- * status cannot reveal. Every other code is derived from its spec:
- *   - retryable                 → `transient`
- *   - HTTP 403                  → `permission`
- *   - remaining `auth` category → `auth_blocked` (the credential-type 401s)
- *   - anything else, or unknown → `none`
- *
- * An unknown code, a dynamic `policy:*` code, or a code this client predates
- * (no spec) defaults to `none`, the same safe default as {@link isRetryableCode}:
- * an unrecognized code is never treated as a credential expiry or a sign-out.
- */
-export declare function classifyRecovery(code: string): RecoveryClass;