@abloatai/ablo 0.34.1 → 0.36.0

package/dist/{errorCodes.js → transaction/errorCodes.js}

@@ -37,7 +37,7 @@ import { z } from 'zod';
  * 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 const ERROR_CONTRACT_VERSION = '2026-07-15';
+export const ERROR_CONTRACT_VERSION = '2026-07-23';
 /**
  * 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
@@ -136,6 +136,7 @@ export const ERROR_CODES = {
     database_role_unreadable: wire('permission', 403, false, 'Ablo could not introspect the database role it connects with, so it cannot verify that row-level security is enforced.'),
     database_tables_unforced_rls: wire('permission', 403, false, 'Some synced tables do not have `FORCE ROW LEVEL SECURITY` applied, so the table owner can bypass row isolation. Run `ALTER TABLE ... FORCE ROW LEVEL SECURITY` on each synced table.'),
     database_host_not_allowed: wire('permission', 403, false, "The database host resolves to a private, loopback, or link-local address, which Ablo's servers will not connect to. Use a publicly resolvable host."),
+    connected_database_unreachable: wire('tenant', 503, false, 'Ablo could not reach the database connected to this environment: it refused the credentials on file, or did not answer at all. A database often changes after it is connected — a password is rotated, an instance is replaced — while the connection goes on pointing at what used to be there. The error names the host it tried. If the password changed, `ablo connect rotate` re-keys the roles and re-registers them; if the database itself was replaced, `ablo connect apply` sets up the new one and `ablo connect register` hands it over. Run either with a key for this environment.'),
     // Older spellings of the `database_*` codes above, still sent by some servers
     // and kept so they classify identically. Prefer the `database_*` codes.
     byo_role_cannot_enforce_rls: wire('permission', 403, false, 'The direct Postgres connector role cannot enforce row-level security.'),
@@ -149,11 +150,28 @@ export const ERROR_CODES = {
     // only loop. Recovery belongs to the caller: take a claim, which queues fairly
     // behind the holder (`ablo.<model>.claim`), or re-read and rebase.
     claim_conflict: wire('claim', 409, false, 'Another participant holds a claim on this row, so the write was rejected. Take a claim with `ablo.<model>.claim` to queue fairly behind the holder, or re-read and rebase.'),
-    claim_lost: wire('claim', 409, false, 'The claim held on this row was lost before the write could apply. Re-acquire the claim and retry.'),
+    claim_lost: wire('claim', 409, false, 'The claim held on this row was lost before the write could apply. Re-acquire with `ablo.<model>.claim` and retry from its fresh snapshot.'),
     fence_token_stale: wire('claim', 409, false, 'This write carried a fencing token below the row’s current high-water: a later holder claimed the row, wrote, and moved on while this claim was lapsed, so applying the write would silently overwrite their work. The claim is gone — re-claim the row and retry from the current state.'),
     entity_claimed: wire('claim', 409, false, 'This row is currently claimed by another participant, so the write was blocked. Queue behind the holder with `ablo.<model>.claim`, or wait for the claim to clear.'),
-    malformed_claim: wire('claim', 400, false, 'The claim payload could not be parsed. A claim must name the model and the entity it targets; check the payload shape and resend.'),
+    // A claim payload that cannot be parsed is a malformed request, not
+    // contention — it is filed with `malformed_subscription` below rather than
+    // with the 409s above, so the claim category stays purely about a target
+    // being held. This is the code for a claim that fails to name its target,
+    // over either transport — and for the participant claim behind `join`, which
+    // names scopes rather than a row but fails the same way and to the same
+    // caller. The copy covers both because the caller sees one word, `claim`, and
+    // needs to be told which shape was expected without being handed a lecture on
+    // the two frames.
+    malformed_claim: wire('validation', 400, false, 'The claim payload could not be parsed. A claim on a row must name the model and the entity it targets; a claim on a scope, which is what `join` opens, must name sync groups spelled `kind:id` or `default`. Check the payload shape and resend.'),
     malformed_subscription: wire('validation', 400, false, 'The `update_subscription` payload was malformed; expected `{ syncGroups: string[] }`.'),
+    // The counterpart to the two above, pointing the other way: those are a
+    // client sending the server something it cannot read, this is the server
+    // sending the client something it cannot read. One code covers both
+    // transports — a mis-shaped socket frame and a mis-shaped HTTP body are the
+    // same failure, and the message says which arrived. Not retryable: it means
+    // the two sides are running different versions of the protocol, and waiting
+    // does not change that.
+    malformed_response: wire('transport', 502, false, 'The server sent a message this client could not read, so it was declined whole rather than applied in part. Nothing was changed locally. This normally means the client and the server are running different versions; upgrading the client resolves it.'),
     model_claimed: wire('claim', 409, false, 'Another participant holds a claim on this row. Read `claim.state` to see who holds it, or queue behind them with a claim of your own.'),
     model_claimed_timeout: wire('claim', 409, false, 'Another participant held a claim on this row and did not release it in time. Retry, or read `claim.state` to see who holds it.'),
     model_claim_not_configured: client('claim', 'Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically — there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path).'),
@@ -163,7 +181,7 @@ export const ERROR_CODES = {
     // `readAt`, so resending the identical payload can never succeed. Recovery
     // is a caller-level re-read that produces a NEW request with a fresh
     // watermark — the same shape as `claim_conflict`.
-    stale_context: wire('conflict', 409, false, "The row changed after you read it — the write's `readAt` watermark is older than the current row version. Re-read the row and retry."),
+    stale_context: wire('conflict', 409, false, "The row changed after you read it — the write's `readAt` watermark is older than the current row version. Pass a function to `update(id, current => next)` and the SDK re-reads and retries for you; or re-read and retry by hand."),
     // Raised by the functional `update(id, current => next)` form once its
     // internal reconcile budget is exhausted, because the row stayed continuously
     // contended. The SDK has already retried; the caller decides whether to back
@@ -176,6 +194,7 @@ export const ERROR_CODES = {
     idempotency_key_too_long: wire('validation', 400, false, 'The supplied `Idempotency-Key` exceeds the maximum length. Use a shorter key — a UUID works well.'),
     // ── validation (400 / 422) ─────────────────────────────────────────
     write_options_invalid: client('validation', 'The write options (`idempotencyKey` / `label` / `wait` / `readAt` / `onStale` / `claim`) failed validation against the write-options schema.'),
+    write_payload_invalid: client('validation', 'A write payload contained a value that cannot be represented safely as JSON. Use plain objects, arrays, finite numbers, strings, booleans, null, or valid dates.'),
     source_operation_id_required: client('validation', 'A data-source operation arrived without the entity `id` it targets.'),
     source_adapter_misconfigured: client('validation', 'The data-source ORM adapter could not map a schema model onto the backing client — the client exposes no matching delegate or model. Check that the adapter and schema agree on model names.'),
     // The server validates every incoming data-source event before appending it
@@ -186,7 +205,6 @@ export const ERROR_CODES = {
     duration_invalid: client('validation', 'A duration value was not a number of seconds or a "500ms" | "30s" | "3m" | "24h" string.'),
     schema_definition_invalid: client('validation', 'A schema definition value was invalid (bad column identifier, non-finite backfill, or unsupported schema-JSON version).'),
     cli_invalid_arguments: client('validation', 'The CLI was invoked with an unknown flag or a malformed flag value.'),
-    turn_validation_failed: wire('validation', 422, false, 'The agent turn payload failed server-side validation and was not applied.'),
     commit_operation_required: wire('validation', 400, false, 'A commit must carry `operation` or `operations`.'),
     // Both commit transports — the WebSocket `commit` frame and the HTTP
     // `/v1/commits` endpoint — validate every operation and reject the whole batch
@@ -247,14 +265,18 @@ export const ERROR_CODES = {
     // ── claim / lease (409 / transport) ───────────────────────────────
     claim_lease_unavailable: wire('claim', 503, true, 'The claim-lease coordination subsystem is temporarily unavailable, so the claim could not be processed. Retry shortly.'),
     claim_not_wired: client('claim', 'Claims were used, but this runtime has no claim support wired in. The standard `Ablo({ schema, apiKey })` client wires it up automatically.'),
-    claim_queued: wire('claim', 409, true, 'The claim was queued behind the current lease holder and will be granted in turn. Wait, or read `claim.queue` to see your position.'),
+    claim_queued: wire('claim', 409, true, 'The claim was queued behind the current lease holder and will be granted in turn. Poll `claims.retrieve({ claimId })` for the grant — the id rides on the error — or read `claim.queue` to see the line.'),
     claim_wait_aborted: wire('claim', 409, true, 'The wait for this claim lease was aborted before the lease was granted.'),
-    claim_wait_poll_interval_required: client('claim', 'Waiting on a claim requires a poll interval, and none was provided.'),
-    grant_timeout: wire('claim', 504, true, 'The wait for a capability grant timed out before one arrived. Retry the request.'),
-    slide_intent_missing_deck_id: wire('claim', 400, false, 'This slide claim is missing the id of the deck it belongs to.'),
-    slide_intent_unknown_sibling: wire('claim', 400, false, 'This slide claim references a sibling slide that does not exist in the deck.'),
+    grant_timeout: wire('claim', 504, true, 'The wait for the claim grant timed out before your turn arrived (`waitTimeoutMs`). Claim again to rejoin the line, raise the cap, or re-read and proceed without the claim.'),
     // ── bootstrap (transport) ──────────────────────────────────────────
     bootstrap_fetch_timeout: wire('bootstrap', 504, true, 'The initial bootstrap fetch timed out before the server responded. Retry shortly.'),
+    // Deliberate cancellation, never a failure of the network. It is what the
+    // client hands to `abort()` so the layer above can tell "we stopped this on
+    // purpose" apart from "the transfer died" — the two are indistinguishable
+    // from a bare abort, and retrying the first re-issues requests that were just
+    // killed. Non-retryable by construction: whoever cancelled it either has a
+    // newer request in flight or has already given up.
+    bootstrap_cancelled: client('bootstrap', 'This bootstrap request was cancelled before it finished, because a newer one replaced it or the bootstrap it belonged to had already failed. It is not retried on its own.'),
     bootstrap_offline: wire('bootstrap', 503, true, 'Bootstrap could not run because the client is offline. It can proceed once the network returns.'),
     bootstrap_offline_no_cache: wire('bootstrap', 503, false, 'The client is offline and no cached snapshot is available to start from, so there is no data to load until the network returns.'),
     bootstrap_response_invalid: wire('bootstrap', 502, true, 'The bootstrap response could not be parsed. Retrying may succeed.'),
@@ -270,7 +292,7 @@ export const ERROR_CODES = {
     commit_failed: wire('transport', 500, true, 'The commit reached the server but failed to apply. Retrying may succeed.'),
     replication_lag_timeout: wire('transport', 504, true, "The data source accepted the write, but its correlated authoritative source delta did not arrive before the confirmation deadline. The write may still materialize; retry with the same idempotency key or wait for source ingestion to recover."),
     commit_offline_grace_expired: wire('transport', 503, false, 'The offline grace window expired before this commit could be sent, so it was not applied. Re-apply the change once the connection returns.'),
-    queue_too_deep: wire('transport', 503, true, 'The transaction queue is over its depth limit, so new writes are being rejected until it drains. Retry shortly.'),
+    queue_too_deep: wire('transport', 503, true, 'The line is already past its depth limit. For a claim, more participants were waiting than your `maxQueueDepth` allows — claim again without the cap to wait anyway, or work elsewhere and retry later. For a write, the transaction queue is draining — retry shortly.'),
     flush_timeout: wire('transport', 504, true, 'Flushing the transaction queue timed out before every pending write was sent. Retry once connectivity stabilizes.'),
     wait_for_timeout: wire('transport', 504, true, 'A wait-for condition timed out before it was satisfied. Retry, or extend the timeout.'),
     instance_at_capacity: wire('transport', 503, true, 'The server is at connection capacity. Retry shortly — transient and not specific to your credentials.'),
@@ -294,8 +316,6 @@ export const ERROR_CODES = {
     // fail closed, so the request was rejected rather than admitted unchecked. It
     // is retryable: the next attempt re-probes the backend.
     rate_limiter_unavailable: wire('server', 503, true, 'The rate-limiter backend is unavailable and this endpoint is configured to fail closed; retry shortly.'),
-    turn_open_failed: wire('server', 500, true, 'The agent turn could not be opened on the server. It is safe to retry.'),
-    turn_close_failed: wire('server', 500, true, 'The agent turn could not be closed cleanly on the server. It is safe to retry the close.'),
     // ── client-only invariants (never serialized) ──────────────────────
     invalid_options: client('client', 'The Ablo client was constructed with invalid or incomplete options.'),
     no_ablo_provider: client('client', 'An Ablo hook was used outside of an Ablo provider.'),
@@ -345,12 +365,14 @@ export const ERROR_CODES = {
     forbidden: wire('permission', 403, false, 'The caller lacks permission for this operation.'),
     source_api_key_unresolved: wire('auth', 401, false, 'The API key presented for this data source could not be resolved to a known key. Check the key and its environment.'),
     capability_auth_disabled: wire('server', 503, false, 'Capability authentication is disabled on this server.'),
+    capability_rotation_unavailable: wire('server', 500, false, 'This capability could not be rotated, because the environment it belongs to could not be read from it. It is unchanged and still works. Create a replacement capability and retire this one.'),
     provisioner_unavailable: wire('server', 503, false, 'This deployment has no database provisioner configured, so tables cannot be created here.'),
     invalid_model: wire('validation', 400, false, 'The model name in the request is not a valid model identifier.'),
     invalid_id: wire('validation', 400, false, 'The id in the request is not a valid identifier.'),
     unknown_model: wire('tenant', 400, false, 'Named a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` — the server keeps its own copy of the schema.'),
     model_not_tenant_scoped: wire('tenant', 400, false, 'This model is not tenant-scoped, so it cannot be queried through the tenant-scoped read path.'),
     source_tenancy_not_enforced: wire('tenant', 400, false, "This model is scoped by its connected data source (`policy: { by: 'source' }`), so its tenant is resolved from the source registration rather than a row column. Enforcing that resolution requires the write-through connect path, which is not enabled on this plane yet — so the model cannot be served through the tenant-scoped read or bootstrap path without risking a cross-tenant read. If this model lives on a log plane, scope it with `by: 'column'` or `by: 'parent'` instead."),
+    user_scope_not_enforced: wire('tenant', 400, false, "Rows in this model belong to one person rather than to the whole organization, and that boundary is kept where the rows are stored. This plane is currently served from its log, which carries the organization and the project on every row but not the owner — so the boundary cannot be applied here, and serving the read would show one member another member's private records. It was declined whole and nothing was returned. Serve the plane from its tables, or read with a credential that acts for the organization rather than for a person."),
     model_not_provisioned: wire('tenant', 409, false, "This model is in the plane's registered schema, but its table has not been provisioned yet. Registering a schema with `ablo push` records the model; a plane's physical tables are created separately, out of band, so a model can appear in the schema before its table exists. Provision the plane's tables, then retry the read."),
     schema_table_invalid: wire('schema', 500, false, "The model's table identifier is invalid."),
     schema_scope_invalid: wire('schema', 500, false, "The model's scope predicate could not be built."),
@@ -367,6 +389,7 @@ export const ERROR_CODES = {
     protocol_version_unsupported: wire('transport', 426, false, 'The client sync-protocol version is outside the range this server supports — upgrade the SDK (or the server was rolled back mid-fleet).'),
     database_unreachable: wire('validation', 400, false, "Ablo could not reach this database to check that it can stream replication. The connection string may be wrong, the host may not be reachable from Ablo's servers, or the credentials may not be accepted."),
     database_not_replication_ready: wire('validation', 400, false, 'This database is not set up for logical replication yet. Every failing item — wal_level, the publication, the replication grant, a replica identity — is listed in the error details with its exact fix. `ablo connect` prints the one-time setup; `ablo connect check` verifies it.'),
+    database_already_connected: wire('conflict', 409, false, 'This database is already connected to another environment in your organization. Ablo streams a database from one environment at a time, so connecting it to a second one would leave the two reading the same change stream, and the newer connection would take the stream over from the older. Give this environment a database of its own — on a branching provider a branch of the same database is the usual answer, and it is what sandbox is for. If you meant to move the connection rather than add one, disconnect it from the environment that holds it with `ablo connect deregister` first.'),
     replication_publication_drift: wire('validation', 400, false, 'Your schema maps to tables that are not members of the replication publication, so their changes silently never stream and the source looks frozen. The missing tables and the exact `ALTER PUBLICATION … ADD TABLE …` to add them are in the error details — Ablo never alters your database for you.'),
     query_unknown_relation: wire('validation', 400, false, 'The query references a relation the model does not define. Check the relation name against the schema.'),
     query_relation_target_unknown: wire('schema', 500, false, 'A relation in the query targets a model the schema does not define.'),
@@ -384,20 +407,24 @@ export const ERROR_CODES = {
     usage_invalid: wire('validation', 400, false, 'The usage request was invalid.'),
     invalid_request: wire('validation', 400, false, 'The request parameters were invalid.'),
     capability_not_found: wire('not_found', 404, false, 'No capability exists with the given id.'),
+    claim_not_found: wire('not_found', 404, false, 'No claim of yours exists with the given id. It was released, it expired, or it was never acquired on this plane.'),
     invalid_participant_kind: wire('validation', 400, false, 'The participant kind is not one the server recognizes.'),
     invalid_sync_group: wire('validation', 400, false, 'Sync groups must be `default` or `<namespace>:<id>`.'),
     narrow_scope_required: wire('validation', 400, false, 'This request requires a scope narrowed to specific resources; the presented scope is too broad.'),
     wide_scope_forbidden: wire('permission', 403, false, 'This caller may not use a wide scope. Request a scope narrowed to the resources you need.'),
     capability_required: wire('auth', 401, false, 'This operation requires a capability, and none was presented.'),
-    parent_turn_not_found: wire('not_found', 404, false, 'The referenced parent turn does not exist.'),
-    parent_turn_foreign_agent: wire('permission', 403, false, 'The referenced parent turn belongs to a different agent, so it cannot be used here.'),
-    turn_not_found: wire('not_found', 404, false, 'The referenced turn does not exist.'),
-    turn_foreign_agent: wire('permission', 403, false, 'This turn belongs to a different agent, so the caller cannot act on it.'),
-    invalid_intent: wire('validation', 400, false, 'The claim request was malformed and could not be processed.'),
+    // A row in an ordered collection can be created at a position stated relative
+    // to its neighbours ("before this one"), so the position has to be resolved
+    // against the parent before the row lands. These are the two ways that request
+    // can fail to describe a real place: no parent to resolve against, and a
+    // neighbour that is not in it.
+    position_missing_parent: wire('validation', 400, false, 'This row gives a position but not the parent it belongs to, so the position cannot be resolved. Send the parent id alongside the position.'),
+    position_unknown_sibling: wire('validation', 400, false, 'This row is positioned relative to another row that is not in the same parent. Check that the neighbouring row id is correct and still present.'),
     schema_too_large: wire('validation', 413, false, 'The submitted schema exceeds the maximum size.'),
     request_too_large: wire('validation', 413, false, 'The request body exceeds the maximum size.'),
     invalid_schema: wire('validation', 400, false, 'The submitted schema could not be parsed.'),
     incompatible_change: wire('conflict', 409, false, 'The schema change is incompatible with the schema currently deployed and cannot be applied as-is.'),
+    replication_reset_required: wire('conflict', 409, false, 'A connected log plane has live rows for a mapped model that disappeared. Declare a rename or an explicit drop/reset before advancing the schema.'),
 };
 /** 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

package/dist/{errors.d.ts → transaction/errors.d.ts}

@@ -14,6 +14,7 @@
  *
  * Both work on every subclass.
  */
+import { z } from 'zod';
 import type { ErrorCode } from './errorCodes.js';
 import { type WireClaimSummary, type ModelClaim, type ModelTarget, type ParticipantKind } from './coordination/schema.js';
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errorCodes.js';
@@ -274,7 +275,7 @@ export declare function claimedError(target: {
  * narrow an existing capability into, one that would pass on retry.
  */
 export interface RequiredCapability {
-    /** The operation or capability scope, for example `"slide.update"` or
+    /** The operation or capability scope, for example `"report.update"` or
      *  `"subscribe"`. */
     readonly scope: string;
     /** The concrete constraints the capability must satisfy — for example
@@ -314,19 +315,19 @@ export declare class CapabilityError extends AbloPermissionError {
  * user should be sent to sign in again rather than offered a generic retry.
  *
  * It extends {@link AbloAuthenticationError}, so it is caught both by code using
- * the {@link SyncSessionError.isSessionError} check and by code that catches the
+ * the {@link AbloSessionError.isSessionError} check and by code that catches the
  * authentication category in general.
  */
-export declare class SyncSessionError extends AbloAuthenticationError {
+export declare class AbloSessionError extends AbloAuthenticationError {
     readonly isSessionError = true;
     readonly statusCode: number;
     constructor(message: string, statusCode?: number);
     /**
-     * Returns true when a value is a {@link SyncSessionError}, or any error-like
+     * Returns true when a value is a {@link AbloSessionError}, or any error-like
      * object that reports itself as a session error through an `isSessionError`
      * flag.
      */
-    static isSessionError(error: unknown): error is SyncSessionError;
+    static isSessionError(error: unknown): error is AbloSessionError;
     /**
      * Determines whether an HTTP response means the login session has expired and
      * the user should sign in again. When the body carries a structured Ablo error
@@ -336,7 +337,17 @@ export declare class SyncSessionError extends AbloAuthenticationError {
     static isSessionErrorResponse(status: number, body?: string): boolean;
 }
 /**
- * The WebSocket-close counterpart to {@link SyncSessionError.isSessionErrorResponse}:
+ * @deprecated Renamed to {@link AbloSessionError} — the one engine-named class
+ * in the Ablo* hierarchy, brought in line with the family. Same class, same
+ * `instanceof` identity. Removed in 0.36.0.
+ */
+export declare const SyncSessionError: typeof AbloSessionError;
+/**
+ * @deprecated Renamed to {@link AbloSessionError}. Removed in 0.36.0.
+ */
+export type SyncSessionError = AbloSessionError;
+/**
+ * The WebSocket-close counterpart to {@link AbloSessionError.isSessionErrorResponse}:
  * returns true for close reasons that mean the short-lived access credential
  * (`ek_` or `rk_`) has expired. The server closes such sockets with code 4001
  * and reason `'credential_expired'`. Because the credential is re-mintable from
@@ -345,6 +356,24 @@ export declare class SyncSessionError extends AbloAuthenticationError {
  * reason, such as a revoked key or a genuinely lost login, stays terminal.
  */
 export declare function isAccessCredentialExpiryCloseReason(reason: string): boolean;
+/**
+ * The one definition of the {@link RequiredCapability} wire shape. Every
+ * boundary that carries a denial's capability detail — the error body parsed
+ * here, and the rejected commit receipt in `wire/commit.ts` — composes this
+ * schema rather than restating the fields, so a new member cannot reach one
+ * boundary and miss the other.
+ *
+ * Unknown keys pass through: the server may describe a capability in more
+ * detail than this build knows, and dropping those keys would leave a caller
+ * unable to act on a denial it could otherwise satisfy.
+ */
+export declare const requiredCapabilityWireSchema: z.ZodObject<{
+    scope: z.ZodString;
+    constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>>;
+    issuer: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+    ttlSeconds: z.ZodPreprocess<z.ZodOptional<z.ZodNumber>>;
+    nonce: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+}, z.core.$loose>;
 /**
  * Coerces any thrown value into an {@link AbloError}, so a consumer never catches
  * an untyped error from the SDK. An error that is already an {@link AbloError}
@@ -377,14 +406,9 @@ export declare function errorFromWire(message: string, opts?: {
     requestId?: string;
     requiredCapability?: RequiredCapability;
     claims?: readonly ClaimErrorClaim[];
+    /** Everything the producer attached beyond the envelope's own fields. */
+    details?: Readonly<Record<string, unknown>>;
 }): AbloError;
-/**
- * Translates an HTTP response into the appropriate typed {@link AbloError}. This
- * is the single mapping every request path routes a non-2xx response through, so
- * the error a consumer sees is always the right subclass. After extracting the
- * code and message from the response body, it delegates the class selection to
- * {@link errorFromWire}, the same logic the frame transports use.
- */
 export declare function translateHttpError(status: number, body: unknown, requestId?: string): AbloError;
 /**
  * Reports whether an HTTP error body carries a code that {@link translateHttpError}

package/dist/{errors.js → transaction/errors.js}

@@ -335,27 +335,27 @@ export class CapabilityError extends AbloPermissionError {
  * user should be sent to sign in again rather than offered a generic retry.
  *
  * It extends {@link AbloAuthenticationError}, so it is caught both by code using
- * the {@link SyncSessionError.isSessionError} check and by code that catches the
+ * the {@link AbloSessionError.isSessionError} check and by code that catches the
  * authentication category in general.
  */
-export class SyncSessionError extends AbloAuthenticationError {
+export class AbloSessionError extends AbloAuthenticationError {
     isSessionError = true;
     statusCode;
     constructor(message, statusCode = 401) {
         super(message, { httpStatus: statusCode, code: 'session_expired' });
-        this.name = 'SyncSessionError';
+        this.name = 'AbloSessionError';
         this.statusCode = statusCode;
         if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, SyncSessionError);
+            Error.captureStackTrace(this, AbloSessionError);
         }
     }
     /**
-     * Returns true when a value is a {@link SyncSessionError}, or any error-like
+     * Returns true when a value is a {@link AbloSessionError}, or any error-like
      * object that reports itself as a session error through an `isSessionError`
      * flag.
      */
     static isSessionError(error) {
-        if (error instanceof SyncSessionError) {
+        if (error instanceof AbloSessionError) {
             return true;
         }
         if (error && typeof error === 'object' && 'isSessionError' in error) {
@@ -392,7 +392,13 @@ export class SyncSessionError extends AbloAuthenticationError {
     }
 }
 /**
- * The WebSocket-close counterpart to {@link SyncSessionError.isSessionErrorResponse}:
+ * @deprecated Renamed to {@link AbloSessionError} — the one engine-named class
+ * in the Ablo* hierarchy, brought in line with the family. Same class, same
+ * `instanceof` identity. Removed in 0.36.0.
+ */
+export const SyncSessionError = AbloSessionError;
+/**
+ * The WebSocket-close counterpart to {@link AbloSessionError.isSessionErrorResponse}:
  * returns true for close reasons that mean the short-lived access credential
  * (`ek_` or `rk_`) has expired. The server closes such sockets with code 4001
  * and reason `'credential_expired'`. Because the credential is re-mintable from
@@ -405,7 +411,18 @@ export function isAccessCredentialExpiryCloseReason(reason) {
 }
 // ── HTTP → class mapping ──────────────────────────────────────────────
 const OptionalWireStringSchema = z.preprocess((value) => (typeof value === 'string' ? value : undefined), z.string().optional());
-const RequiredCapabilityWireSchema = z
+/**
+ * The one definition of the {@link RequiredCapability} wire shape. Every
+ * boundary that carries a denial's capability detail — the error body parsed
+ * here, and the rejected commit receipt in `wire/commit.ts` — composes this
+ * schema rather than restating the fields, so a new member cannot reach one
+ * boundary and miss the other.
+ *
+ * Unknown keys pass through: the server may describe a capability in more
+ * detail than this build knows, and dropping those keys would leave a caller
+ * unable to act on a denial it could otherwise satisfy.
+ */
+export const requiredCapabilityWireSchema = z
     .object({
     scope: z.string(),
     constraints: z
@@ -416,19 +433,19 @@ const RequiredCapabilityWireSchema = z
         .preprocess((value) => (typeof value === 'number' ? value : undefined), z.number().optional()),
     nonce: OptionalWireStringSchema,
 })
-    .passthrough();
+    .loose();
 const NestedErrorShapeSchema = z
     .object({
     code: OptionalWireStringSchema,
     message: OptionalWireStringSchema,
     field: OptionalWireStringSchema,
-    requiredCapability: RequiredCapabilityWireSchema.optional().catch(undefined),
+    requiredCapability: requiredCapabilityWireSchema.optional().catch(undefined),
     heldBy: OptionalWireStringSchema,
     policyReason: OptionalWireStringSchema,
     heldByClaim: wireClaimSummarySchema.optional().catch(undefined),
     claims: z.array(wireClaimSummarySchema).optional().catch(undefined),
 })
-    .passthrough();
+    .loose();
 const ErrorFieldSchema = z
     .preprocess((value) => typeof value === 'string' || (typeof value === 'object' && value !== null)
     ? value
@@ -442,13 +459,13 @@ const ErrorBodyShapeSchema = z
     code: OptionalWireStringSchema,
     reason: OptionalWireStringSchema,
     message: OptionalWireStringSchema,
-    requiredCapability: RequiredCapabilityWireSchema.optional().catch(undefined),
+    requiredCapability: requiredCapabilityWireSchema.optional().catch(undefined),
     heldBy: OptionalWireStringSchema,
     policyReason: OptionalWireStringSchema,
     heldByClaim: wireClaimSummarySchema.optional().catch(undefined),
     claims: z.array(wireClaimSummarySchema).optional().catch(undefined),
 })
-    .passthrough();
+    .loose();
 function parseErrorBodyShape(body) {
     if (typeof body !== 'object' || body === null)
         return {};
@@ -489,7 +506,7 @@ export function toAbloError(err) {
  * subclass, with its `code`, status, and retryability intact.
  */
 export function errorFromWire(message, opts = {}) {
-    const { code, requestId, requiredCapability, claims } = opts;
+    const { code, requestId, requiredCapability, claims, details } = opts;
     // Effective status: an explicit HTTP status wins; otherwise fall back to
     // the code's canonical status from the registry (undefined for unknown /
     // forward-compat codes, which then map to the base AbloError).
@@ -498,7 +515,12 @@ export function errorFromWire(message, opts = {}) {
     // may send a code this SDK predates). Cast to ErrorCode here — the one
     // sanctioned crossing — so internal producers stay statically checked.
     const publicCode = (code === 'claim_conflict' ? 'claim_conflict' : code);
-    const baseOpts = { code: publicCode, httpStatus, requestId };
+    const baseOpts = {
+        code: publicCode,
+        httpStatus,
+        requestId,
+        ...(details && Object.keys(details).length > 0 ? { details } : {}),
+    };
     // ── Code-first specials (transport-independent) ──────────────────────
     // A scoped credential was denied — route through CapabilityError so callers
     // can read `.requiredCapability` to attenuate-and-retry.
@@ -519,6 +541,14 @@ export function errorFromWire(message, opts = {}) {
     if (code === 'stale_context') {
         return new AbloStaleContextError(message, baseOpts);
     }
+    // The database connected to the caller's environment could not be reached.
+    // It rides a 503, but the generic 5xx rule below would rebuild it as an
+    // `AbloServerError` — telling the reader Ablo is broken and to wait, when the
+    // remedy is on their side and the server already classified it as a
+    // connection failure. Keep the class the producer chose.
+    if (code === 'connected_database_unreachable') {
+        return new AbloConnectionError(message, baseOpts);
+    }
     // ── Status-driven dispatch (HTTP parity) ─────────────────────────────
     if (httpStatus === 401)
         return new AbloAuthenticationError(message, baseOpts);
@@ -541,6 +571,38 @@ export function errorFromWire(message, opts = {}) {
  * code and message from the response body, it delegates the class selection to
  * {@link errorFromWire}, the same logic the frame transports use.
  */
+/**
+ * The keys the error envelope spends on itself. {@link AbloError.toJSON} spreads
+ * `details` FLAT alongside them rather than nesting it, so everything here is
+ * the envelope and everything else was `details` — which is how
+ * {@link translateHttpError} puts it back.
+ */
+const ENVELOPE_KEYS = new Set([
+    'type',
+    'code',
+    'param',
+    'message',
+    'doc_url',
+    'request_id',
+    // Read into typed properties below, so they are not detail as well.
+    'error',
+    'reason',
+    'requiredCapability',
+    'claims',
+    'heldByClaim',
+]);
+/** The non-envelope remainder of an error body — what `details` was before it
+ *  was spread. Empty when the producer attached nothing. */
+function detailsFromBody(body) {
+    if (typeof body !== 'object' || body === null)
+        return undefined;
+    const rest = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (!ENVELOPE_KEYS.has(key))
+            rest[key] = value;
+    }
+    return Object.keys(rest).length > 0 ? rest : undefined;
+}
 export function translateHttpError(status, body, requestId) {
     const parsed = parseErrorBodyShape(body);
     const nested = parsed.error != null && typeof parsed.error === 'object'
@@ -561,12 +623,19 @@ export function translateHttpError(status, body, requestId) {
             : nested?.heldByClaim
                 ? [nested.heldByClaim]
                 : undefined);
+    // The envelope carries `request_id`, so a caller that has only the body still
+    // gets the correlation id — without this it was dropped unless the caller
+    // happened to read the header and pass it in separately.
+    const bodyRequestId = typeof body === 'object' && body !== null && 'request_id' in body
+        ? body.request_id
+        : undefined;
     return errorFromWire(message, {
         code,
         httpStatus: status,
-        requestId,
+        requestId: requestId ?? (typeof bodyRequestId === 'string' ? bodyRequestId : undefined),
         requiredCapability,
         claims,
+        details: detailsFromBody(body),
     });
 }
 /**

package/dist/transaction/footprint.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The footprint — every object Ablo leaves inside a customer's own database,
+ * declared once.
+ *
+ * Four things need this list and each used to carry its own copy: the setup SQL
+ * that creates the objects, the replication runtime that reads them, the audit
+ * that tells a customer what Ablo put there, and (eventually) the teardown that
+ * removes them. They drifted, as hand-maintained copies do — `ABLO_PUBLICATION`
+ * was declared twice, under a comment insisting the literals "MUST equal the
+ * CLI's" and pointing at a file that no longer held it, and the audit went on
+ * looking for a footprint from an earlier era while seeing none of what Ablo
+ * installs today.
+ *
+ * The audit is the copy that matters most. A customer runs it to answer "what is
+ * still in my database", and a stale list answers "nothing" — which reads as
+ * clean rather than as unexamined. So the list lives here, every consumer
+ * derives from it, and an object added to Ablo's setup is visible to the audit
+ * because it could not have been added anywhere else.
+ *
+ * Retired objects stay in the list, marked {@link FootprintArtifact.retired}.
+ * They are no longer installed, but a database connected to an older Ablo still
+ * holds them, and those are precisely the ones a customer would never think to
+ * look for.
+ */
+/** The Postgres object class, which decides how the audit looks it up. */
+export type FootprintKind = 'publication' | 'slot' | 'role' | 'table' | 'type';
+export interface FootprintArtifact {
+    readonly kind: FootprintKind;
+    readonly name: string;
+    /** What it is for, in the words a customer reading an audit would want. */
+    readonly purpose: string;
+    /**
+     * Installed only for a data source that reports through the signed endpoint
+     * rather than the write-ahead log.
+     */
+    readonly endpointOnly?: boolean;
+    /**
+     * No longer installed by any current version. A database that once ran an
+     * older Ablo still holds it; the audit reports it so it can be cleaned up.
+     */
+    readonly retired?: boolean;
+    /**
+     * What it costs to leave behind, when leaving it behind costs something. The
+     * audit leads with this, because "you still have an object named X" is not a
+     * reason to act and "this one is retaining your write-ahead log" is.
+     */
+    readonly hazard?: string;
+}
+/**
+ * The publication Ablo's replication reads from. Constant by design: a
+ * publication declares what streams, and several readers are meant to share one
+ * (`publication_names` is a per-stream option, not slot state).
+ */
+export declare const ABLO_PUBLICATION = "ablo_publication";
+/**
+ * The replication slot that holds Ablo's position in the write-ahead log.
+ *
+ * Constant, and it should not be — a slot stores ONE position, so two
+ * connections sharing this name compete for the same marker. It is why a
+ * database can be connected to one plane at a time. ADR 0020 derives it per
+ * connection; {@link isValidReplicationSlotName} is the check a derived name
+ * has to pass.
+ */
+export declare const ABLO_REPLICATION_SLOT = "ablo_slot";
+/** The least-privilege login Ablo reads with. Per-connection under ADR 0020. */
+export declare const ABLO_REPLICATION_ROLE = "ablo_replicator";
+/** The separate least-privilege login used only for row writes. */
+export declare const ABLO_WRITE_ROLE = "ablo_writer";
+/** The bookkeeping table that makes a retried write land once. */
+export declare const ABLO_IDEMPOTENCY_TABLE = "ablo_idempotency";
+/** The transactional outbox an endpoint source reports through. */
+export declare const ABLO_OUTBOX_TABLE = "ablo_outbox";
+/**
+ * Postgres will not accept a replication slot name outside this shape — the
+ * check is in `ReplicationSlotValidateNameInternal`, and identifier quoting does
+ * not exempt a name from it. Anything derived into a slot name is validated
+ * here, at the point it is derived, rather than failing at the point it is used.
+ */
+export declare const REPLICATION_SLOT_NAME: RegExp;
+export declare function isValidReplicationSlotName(name: string): boolean;
+/** The four plane axes a connection is identified by. */
+export interface FootprintPlane {
+    readonly organizationId: string;
+    readonly environment: string;
+    /** '' for the organization-default project. */
+    readonly projectId?: string;
+    /** '' for the default sandbox. */
+    readonly sandboxId?: string;
+}
+/** The names one connection owns. Nothing here is shared with another plane. */
+export interface FootprintNames {
+    readonly slot: string;
+    readonly publication: string;
+    readonly replicationRole: string;
+    readonly writeRole: string;
+}
+/**
+ * The objects this connection owns, named so no other connection can claim them.
+ *
+ * A slot stores ONE position, so two connections sharing a name compete for the
+ * same marker and Postgres reports nothing — which is why the constants these
+ * replace made a database connectable to one plane at a time. The publication
+ * and roles are derived from the same digest so a database's footprint reads as
+ * one set per connection rather than a mix of shared and private objects.
+ *
+ * Stable: the same plane always derives the same names, so re-running setup is a
+ * no-op rather than a second installation.
+ */
+export declare function footprintNamesFor(plane: FootprintPlane): FootprintNames;
+/** Everything Ablo has ever put in a customer's database, current and retired. */
+export declare const ABLO_FOOTPRINT: readonly FootprintArtifact[];

package/dist/transaction/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The Ablo settlement core (ADR 0013).
+ *
+ * The transaction layer that the reactive client is a consumer of, not the
+ * other way round. The root barrel is deliberate: it exports the seam —
+ * {@link TransactionLayer} — plus exactly the vocabulary its signatures
+ * reference and the error hierarchy callers catch. Everything else stays on
+ * subpaths; every addition here is a decision
+ * (docs/plans/transaction-layer-barrel-design.md).
+ */
+export type { TransactionLayer, ListQuery, CommitReceipt } from './transactionLayer.js';
+export { Ablo } from './ablo.js';
+export type { AbloHttpClient, AbloHttpClientOptions, HttpModelClient, } from './transport/httpClient.js';
+export type { Delta, HeldClaim, HeldLease, ClaimTarget, ClaimLeaseOptions, } from './types/streams.js';
+export type { ModelData } from './types/modelData.js';
+export { LogPosition, logPositionSchema, parseLogPosition } from './logPosition.js';
+export type { LogPositionSnapshot } from './logPosition.js';
+export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloContentionError, AbloClaimedError, AbloSessionError, toAbloError, } from './errors.js';
+export * from './errorCodes.js';
+export * from './environment.js';