@abloatai/ablo 0.34.0 → 0.35.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-21';
 /**
  * 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.'),
@@ -152,8 +153,21 @@ export const ERROR_CODES = {
     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.'),
     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.
+    malformed_claim: wire('validation', 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.'),
     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).'),
@@ -176,6 +190,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 +201,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
@@ -251,10 +265,15 @@ export const ERROR_CODES = {
     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.'),
     // ── 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.'),
@@ -294,8 +313,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 +362,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 +386,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,16 +404,19 @@ 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.'),

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/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';

package/dist/transaction/index.js

@@ -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).
+ */
+// The client entry point (ADR 0016). The bare import constructs the
+// coordination layer over request/response transport; the reactive
+// materialiser is the consumer package's entry point, layered above it.
+export { Ablo } from './ablo.js';
+export { LogPosition, logPositionSchema, parseLogPosition } from './logPosition.js';
+// The error hierarchy callers catch.
+export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloContentionError, AbloClaimedError, AbloSessionError, toAbloError, } from './errors.js';
+// Pre-seam leaf surfaces, kept for compatibility with the first extraction.
+export * from './errorCodes.js';
+export * from './environment.js';

package/dist/transaction/keys/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The Ablo API-key format: how keys are minted, hashed, and validated, in one
+ * place so every component that issues or checks a key agrees on the format.
+ *
+ * This module uses `node:crypto` and is therefore Node-only. It is published on
+ * the `@abloatai/ablo/keys` subpath and kept off the main browser-facing entry
+ * so a browser bundle never pulls in `node:crypto`.
+ *
+ * A key looks like `<sk|rk|ek|pk>_<live|test>_<30 base62 chars><6-char base62
+ * CRC32 checksum>`. The middle segment is the stable environment prefix, mapped
+ * on parse to `production` or `sandbox`. The recognizable prefix lets secret
+ * scanners spot a leaked key, and the trailing checksum lets the format reject a
+ * mistyped or forged key locally, without a database round-trip. Older keys
+ * (roughly a 43-character base64url body with no checksum) still validate by hash
+ * and parse here with `checksummed: false`.
+ */
+import { z } from 'zod';
+import { type KeyEnvironment } from '../environment.js';
+export declare const API_KEY_KINDS: readonly ["secret", "restricted", "ephemeral", "publishable"];
+export type ApiKeyKind = (typeof API_KEY_KINDS)[number];
+export declare const API_KEY_ENVS: readonly ["production", "sandbox"];
+export type ApiKeyEnv = KeyEnvironment;
+/** A structurally-valid Ablo API key, parsed into its parts. */
+export interface ParsedApiKey {
+    /** The original plaintext. */
+    raw: string;
+    kind: ApiKeyKind;
+    env: ApiKeyEnv;
+    /** The chars after `<prefix>_<env>_` (body + checksum for new keys). */
+    body: string;
+    /** True when this is the new checksummed format (36-char base62 body). */
+    checksummed: boolean;
+}
+/**
+ * The Zod schema for an Ablo API key. `parse` and `safeParse` return a typed
+ * {@link ParsedApiKey}. A checksummed-format key whose checksum does not match is
+ * rejected without any network call; an older key with no checksum parses with
+ * `checksummed: false` and is left for the server to validate by hash.
+ */
+export declare const apiKeySchema: z.ZodPipe<z.ZodString, z.ZodTransform<ParsedApiKey, string>>;
+/** Parse + fully validate (incl. checksum). Returns null when invalid. */
+export declare function parseApiKey(raw: string): ParsedApiKey | null;
+/**
+ * Read the environment off a STORED display prefix (`keyPrefix`, the first 12
+ * chars — `rk_test_abcd`), rather than off a full plaintext key.
+ *
+ * A key row records its environment nowhere but its prefix, so this is how a
+ * server-side flow that only has the row — rotation, most importantly — recovers
+ * the credential's own mode. Returns null when the prefix is not a recognizable
+ * key spelling, so callers can fail closed rather than fall back to a default.
+ */
+export declare function environmentFromStoredKeyPrefix(prefix: string): KeyEnvironment | null;
+/** True when the key uses the new checksummed format (regardless of validity). */
+export declare function isChecksummedKey(raw: string): boolean;
+/** Verify the embedded checksum. Meaningful only for checksummed-format keys. */
+export declare function keyChecksumMatches(raw: string): boolean;
+/**
+ * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
+ * once), its SHA-256 hash (persisted), and the 12-char display prefix.
+ */
+export declare function generateApiKey(env?: ApiKeyEnv, kind?: ApiKeyKind): {
+    plaintext: string;
+    hash: string;
+    prefix: string;
+};
+/**
+ * The stable SHA-256 hex digest of a plaintext key, computed both when a key is
+ * minted and when one is looked up. A fast hash is the right choice here rather
+ * than a password hash like bcrypt: API keys are long random strings, so there is
+ * no dictionary of guesses to slow down.
+ */
+export declare function hashApiKey(plaintext: string): string;
+/** `whsec_` label prefix per the Standard Webhooks spec (not part of the key material). */
+export declare const WEBHOOK_SECRET_PREFIX = "whsec_";
+/**
+ * Mints a webhook signing secret following the Standard Webhooks specification
+ * (https://www.standardwebhooks.com): a base64-encoded random key of 24–64 bytes,
+ * labelled with the `whsec_` prefix. This uses 32 bytes (256 bits), comfortably
+ * inside that range. Unlike an API key, a signing secret is not hashed at rest,
+ * because signing a request with {@link signAbloSourceRequest} needs the live
+ * value. It is therefore kept in a secret store, returned to the customer once at
+ * creation, and never shown again.
+ */
+export declare function generateWebhookSecret(): {
+    plaintext: string;
+    last4: string;
+};