@abloatai/transaction 0.37.0

package/src/wire/commit.ts

@@ -0,0 +1,379 @@
+/**
+ * Canonical runtime contracts for commit settlement.
+ *
+ * A commit crosses several boundaries during its lifetime: the server's
+ * execution cache, the HTTP/WS receipt, and the client's acknowledgement
+ * tracker. Those boundaries intentionally have different envelopes, but they
+ * all compose the same settlement vocabulary from this module:
+ *
+ *   - `confirmed` — the authoritative change is visible at a sync watermark.
+ *   - `queued` — a connected source durably accepted the write and only its
+ *     correlated authoritative source delta (WAL for direct, endpoint event
+ *     for endpoint-only), identified by `correlationId`, may promote it.
+ *
+ * Keeping the variants discriminated here makes an impossible receipt (most
+ * importantly, `queued` without a correlation) unrepresentable at every
+ * untrusted boundary without collapsing the distinct lifecycle envelopes into
+ * one giant object.
+ */
+
+import { z } from 'zod';
+import {
+  onStaleModeSchema,
+  readDependencySchema,
+  staleNotificationSchema,
+  trackDependencySchema,
+} from '../coordination/schema.js';
+import type { ErrorCode } from '../errorCodes.js';
+import { requiredCapabilityWireSchema } from '../errors.js';
+
+/** Matches the permanent source/idempotency-key ceiling. */
+export const COMMIT_CORRELATION_ID_MAX_LENGTH = 255;
+
+/** Opaque server-authored identity shared by a queued receipt and its authoritative source delta. */
+export const correlationIdSchema = z.string().min(1).max(COMMIT_CORRELATION_ID_MAX_LENGTH);
+export type CorrelationId = z.infer<typeof correlationIdSchema>;
+
+export const commitStatusSchema = z.enum(['queued', 'confirmed']);
+export type CommitStatus = z.infer<typeof commitStatusSchema>;
+
+/**
+ * The settlement states a write may block on — extracted from the reported
+ * vocabulary above, never restated beside it. `commitStatusSchema` is every
+ * state a server can report; this is the subset a caller can usefully wait for,
+ * and the two are not the same question: one describes an outcome, the other a
+ * request.
+ *
+ * `.extract` keeps the relationship mechanical in both directions. Renaming a
+ * settlement state breaks this line at build time, and adding one that nobody
+ * can block on — a commit parked for a human, say — does not become a legal
+ * `wait` merely by being added above. Both the `wait` option's runtime
+ * validator and its interface derive from here, so they cannot disagree.
+ */
+export const commitWaitSchema = commitStatusSchema.extract(['queued', 'confirmed']);
+export type CommitWait = z.infer<typeof commitWaitSchema>;
+
+const queuedSettlementShape = {
+  status: z.literal('queued'),
+  correlationId: correlationIdSchema,
+} as const;
+
+const confirmedSettlementShape = {
+  status: z.literal('confirmed'),
+  correlationId: correlationIdSchema.optional(),
+} as const;
+
+const queuedSettlementSchema = z.strictObject(queuedSettlementShape);
+const confirmedSettlementSchema = z.strictObject(confirmedSettlementShape);
+
+/** The one settlement discriminant shared by every commit boundary. */
+export const commitSettlementSchema = z.discriminatedUnion('status', [
+  queuedSettlementSchema,
+  confirmedSettlementSchema,
+]);
+export type CommitSettlement = z.infer<typeof commitSettlementSchema>;
+
+const missingIdsSchema = z.array(z.string().min(1));
+const notificationsSchema = z.array(staleNotificationSchema);
+
+const successfulReceiptCommonShape = {
+  object: z.literal('commit_receipt'),
+  /** Optional convenience id used by some HTTP surfaces. */
+  id: z.string().min(1).optional(),
+  clientTxId: z.string().min(1),
+  serverTxId: z.string().min(1),
+  success: z.literal(true),
+  lastSyncId: z.number().int().nonnegative(),
+  ops: z.number().int().nonnegative(),
+  notifications: notificationsSchema.optional(),
+  missingIds: missingIdsSchema.optional(),
+} as const;
+
+const queuedCommitReceiptSchema = z
+  .object({
+    ...successfulReceiptCommonShape,
+    ...queuedSettlementShape,
+  })
+  .superRefine((receipt, context) => {
+    if (receipt.lastSyncId !== 0) {
+      context.addIssue({
+        code: 'custom',
+        path: ['lastSyncId'],
+        message: 'A queued source receipt cannot claim a confirmed sync watermark',
+      });
+    }
+  });
+
+const confirmedCommitReceiptSchema = z
+  .object({
+    ...successfulReceiptCommonShape,
+    ...confirmedSettlementShape,
+  })
+  .superRefine((receipt, context) => {
+    if (receipt.correlationId && receipt.lastSyncId <= 0) {
+      context.addIssue({
+        code: 'custom',
+        path: ['lastSyncId'],
+        message: 'A source-confirmed receipt requires a positive sync watermark',
+      });
+    }
+  });
+
+/**
+ * Successful HTTP/WS receipt. This schema is deliberately strict about the
+ * settlement discriminant. Zod's default object behavior strips additive
+ * fields, which is forward compatible without allowing server-internal
+ * recovery evidence to leak through a parsed wire receipt.
+ */
+export const commitReceiptSchema = z.discriminatedUnion('status', [
+  queuedCommitReceiptSchema,
+  confirmedCommitReceiptSchema,
+]);
+export type CommitReceiptWire = z.infer<typeof commitReceiptSchema>;
+
+/**
+ * The rejection code is deliberately not narrowed to the {@link ErrorCode}
+ * registry. A newer server may reject a commit with a code this build predates,
+ * and failing the whole receipt over an unrecognized string would turn a
+ * readable rejection into an opaque parse error. `errorCodes.ts` sanctions this
+ * single boundary cast; every code *producer* is constrained at the
+ * `AbloError` constructor instead.
+ */
+const errorCodeSchema = z.custom<ErrorCode>(
+  (value) => typeof value === 'string' && value.length > 0,
+  { message: 'commit rejection code must be a non-empty string' }
+);
+
+/** The failure arm is separate: queued/confirmed always imply `success:true`. */
+export const rejectedCommitReceiptSchema = z.object({
+  object: z.literal('commit_receipt'),
+  clientTxId: z.string(),
+  serverTxId: z.string(),
+  success: z.literal(false),
+  status: z.literal('rejected'),
+  lastSyncId: z.number().int().nonnegative().optional(),
+  ops: z.number().int().nonnegative().optional(),
+  error: z.object({
+    code: errorCodeSchema,
+    message: z.string(),
+    field: z.string().optional(),
+    requiredCapability: requiredCapabilityWireSchema.optional(),
+  }),
+});
+export type RejectedCommitReceiptWire = z.infer<typeof rejectedCommitReceiptSchema>;
+
+export const mutationResultPayloadSchema = z.union([
+  commitReceiptSchema,
+  rejectedCommitReceiptSchema,
+]);
+export type MutationResultPayload = z.infer<typeof mutationResultPayloadSchema>;
+
+export const mutationResultMessageSchema = z.object({
+  type: z.literal('mutation_result'),
+  payload: mutationResultPayloadSchema,
+});
+export type MutationResultMessageWire = z.infer<typeof mutationResultMessageSchema>;
+
+const confirmationTransactionIdsSchema = z
+  .array(z.string().min(1))
+  .min(1)
+  .refine((ids) => new Set(ids).size === ids.length, {
+    message: 'confirmation transaction ids must be unique',
+  });
+
+/**
+ * Server-internal execution result persisted in `mutation_log`.
+ *
+ * `status` remains optional only for pre-settlement hosted rows. At runtime an
+ * omitted value has the established meaning `confirmed`; new source-forwarded
+ * rows must use the explicit queued arm with both public correlation and exact
+ * internal storage ids.
+ */
+const rawCommitExecutionResultSchema = z
+  .strictObject({
+    lastSyncId: z.number().int().nonnegative(),
+    firstSyncId: z.number().int().nonnegative(),
+    status: commitStatusSchema.optional(),
+    correlationId: correlationIdSchema.optional(),
+    confirmationTransactionIds: confirmationTransactionIdsSchema.optional(),
+    notifications: notificationsSchema.optional(),
+    missingIds: missingIdsSchema.optional(),
+  })
+  .superRefine((result, context) => {
+    const validRange =
+      (result.firstSyncId === 0 && result.lastSyncId === 0) ||
+      (result.firstSyncId > 0 && result.firstSyncId <= result.lastSyncId);
+    if (!validRange) {
+      context.addIssue({
+        code: 'custom',
+        path: ['firstSyncId'],
+        message: 'CommitResult sync range is inconsistent',
+      });
+    }
+
+    if (result.status === 'queued') {
+      if (!result.correlationId) {
+        context.addIssue({
+          code: 'custom',
+          path: ['correlationId'],
+          message: 'A queued source result requires a correlationId',
+        });
+      }
+      if (!result.confirmationTransactionIds) {
+        context.addIssue({
+          code: 'custom',
+          path: ['confirmationTransactionIds'],
+          message: 'A queued source result requires durable confirmation ids',
+        });
+      }
+      if (result.firstSyncId !== 0 || result.lastSyncId !== 0) {
+        context.addIssue({
+          code: 'custom',
+          path: ['lastSyncId'],
+          message: 'A queued source result cannot claim a confirmed sync range',
+        });
+      }
+    }
+
+    if (result.confirmationTransactionIds && !result.correlationId) {
+      context.addIssue({
+        code: 'custom',
+        path: ['correlationId'],
+        message: 'Confirmation transaction ids require their source correlation',
+      });
+    }
+    if (result.correlationId && !result.confirmationTransactionIds) {
+      context.addIssue({
+        code: 'custom',
+        path: ['confirmationTransactionIds'],
+        message: 'A source correlation requires exact confirmation transaction ids',
+      });
+    }
+    if (result.correlationId && result.status === undefined) {
+      context.addIssue({
+        code: 'custom',
+        path: ['status'],
+        message: 'Source-correlated results require explicit settlement status',
+      });
+    }
+    if (
+      result.status === 'confirmed' &&
+      result.correlationId &&
+      (result.firstSyncId <= 0 || result.lastSyncId <= 0)
+    ) {
+      context.addIssue({
+        code: 'custom',
+        path: ['lastSyncId'],
+        message: 'A source-confirmed result requires a durable positive sync range',
+      });
+    }
+  });
+export const commitExecutionResultSchema = rawCommitExecutionResultSchema.transform((result) => ({
+  ...result,
+  status: result.status ?? ('confirmed' as const),
+}));
+export type CommitExecutionResultInput = z.input<typeof commitExecutionResultSchema>;
+export type CommitExecutionResult = z.infer<typeof commitExecutionResultSchema>;
+
+const ackCommonShape = {
+  lastSyncId: z.number().int().nonnegative(),
+  notifications: notificationsSchema.optional(),
+  missingIds: missingIdsSchema.optional(),
+} as const;
+
+/** Normalized acknowledgement handed from a mutation transport to the queue. */
+export const commitAckSchema = z.discriminatedUnion('status', [
+  z
+    .strictObject({
+      ...ackCommonShape,
+      ...queuedSettlementShape,
+    })
+    .refine(({ lastSyncId }) => lastSyncId === 0, {
+      path: ['lastSyncId'],
+      message: 'A queued acknowledgement cannot claim a sync watermark',
+    }),
+  z
+    .strictObject({
+      ...ackCommonShape,
+      ...confirmedSettlementShape,
+    })
+    .refine(({ correlationId, lastSyncId }) => correlationId === undefined || lastSyncId > 0, {
+      path: ['lastSyncId'],
+      message: 'A source-confirmed acknowledgement requires a sync watermark',
+    }),
+]);
+export type CommitAck = z.infer<typeof commitAckSchema>;
+
+/**
+ * The boundary an injected mutation executor returns through. It is the
+ * acknowledgement schema itself: settlement is declared, never inferred from
+ * an omission, so a transport cannot report a write as landed by staying
+ * silent about how it landed.
+ */
+export const mutationCommitResultSchema = commitAckSchema;
+export type MutationCommitResultInput = z.input<typeof mutationCommitResultSchema>;
+export type MutationCommitResult = z.infer<typeof mutationCommitResultSchema>;
+
+/**
+ * Public SDK projection returned by `ablo.commits` and model mutations.
+ *
+ * This intentionally does not compose `commitSettlementSchema`: on the WS
+ * facade, `wait:'queued'` currently means locally sealed/enqueued, before a
+ * server has necessarily accepted the write. Renaming that public state to
+ * `enqueued` is a separate protocol change; the authoritative settlement
+ * union above is reserved for server acknowledgements.
+ */
+export const clientCommitReceiptSchema = z.strictObject({
+  id: z.string().min(1),
+  status: commitStatusSchema,
+  lastSyncId: z.number().int().nonnegative().optional(),
+  notifications: notificationsSchema.optional(),
+  missingIds: missingIdsSchema.optional(),
+});
+export type ClientCommitReceipt = z.infer<typeof clientCommitReceiptSchema>;
+
+// ─────────────────────────────────────────────────────────────────────────
+//  The request side of the commit boundary
+// ─────────────────────────────────────────────────────────────────────────
+//
+// `POST /v1/commits` is the chokepoint every write passes through, so its
+// request shape is a boundary contract and belongs here beside the receipt it
+// answers with — not in a route handler. The published OpenAPI reference is
+// derived from these schemas rather than describing them separately, so the
+// documented surface cannot drift from the validated one.
+//
+// The server layers its own decoder-only compatibility spellings on top for
+// already-shipped clients; those are a rollout concern, not the contract.
+
+/** Control fields any operation in a commit may carry. */
+export const commitOperationControlShape = {
+  id: z.string().nullish(),
+  transactionId: z.string().nullish(),
+  readAt: z.number().nullish(),
+  onStale: onStaleModeSchema.nullish(),
+  fenceToken: z.number().nullish(),
+};
+
+/** One write inside a commit, in the canonical spelling. */
+export const commitOperationBodySchema = z.object({
+  ...commitOperationControlShape,
+  action: z.string(),
+  model: z.string(),
+  data: z.record(z.string(), z.unknown()).nullish(),
+});
+export type CommitOperationBody = z.infer<typeof commitOperationBodySchema>;
+
+/**
+ * The `POST /v1/commits` request body.
+ *
+ * `operations` carries the writes; `track` registers durable premises.
+ * Neither is required on its own, because a body with `track` and no
+ * `operations` is how a caller starts watching a row without writing to it.
+ * Request identity travels in the `Idempotency-Key` header.
+ */
+export const commitRequestSchema = z.object({
+  operations: z.array(commitOperationBodySchema).min(1).optional(),
+  reads: z.array(readDependencySchema).nullish(),
+  track: z.array(trackDependencySchema).nullish(),
+});
+export type CommitRequest = z.infer<typeof commitRequestSchema>;

package/src/wire/delta.ts

@@ -0,0 +1,173 @@
+/**
+ * The delta wire contract: the object the server broadcasts to a client as the
+ * payload of a `delta` or `sync_response` frame. Both the client SDK and the
+ * server derive their delta types from the schemas here, so the two ends share
+ * one definition and cannot drift apart. This is the delta's home in the wire
+ * layer, alongside the other protocol shapes in `wire/`.
+ *
+ * The wire delta is a projection of the stored `sync_deltas` row (the
+ * `syncDeltaRowSchema` in `../log/syncDeltaRow.ts`) and differs from it
+ * in three ways: it omits `organizationId` (the tenant-isolation predicate is
+ * never broadcast), it uses the full action vocabulary (see
+ * {@link syncDeltaActionSchema}) rather than plain create, update, and delete, and
+ * it carries attribution as nested {@link ParticipantRef}s instead of flat columns.
+ *
+ * The schemas layer a shared core plus per-side extensions:
+ *   - {@link syncDeltaWireCoreSchema} — the fields both sides agree on.
+ *   - {@link clientSyncDeltaSchema} — the core plus the fields only the client reads.
+ *   - {@link serverSyncDeltaSchema} — the core plus the audit attribution the server
+ *     adds to each broadcast, which the client ignores.
+ *
+ * The participant vocabulary the delta carries is declared once elsewhere and
+ * re-served here: the actor union lives in `types/participant.ts` and its
+ * runtime validator in `coordination/schema.ts`. Only `confirmationState` has
+ * its home in this module, since the approval stage of a committed change is
+ * delta attribution and nothing else. All three mirror Postgres enums.
+ */
+
+import { z } from 'zod';
+import { correlationIdSchema } from './commit.js';
+import { participantKindSchema } from '../coordination/schema.js';
+import type { ParticipantKind, ParticipantRef } from '../types/participant.js';
+import type { AssertExact } from '../types/assertExact.js';
+
+// ── Shared participant vocabulary (declared once; re-served on this subpath) ──
+
+/** `participant_kind` — who a delta is attributed to. Declared in
+ *  `coordination/schema.ts`; re-exported so the wire subpath serves the
+ *  vocabulary its delta shapes carry. */
+export { participantKindSchema } from '../coordination/schema.js';
+export type { ParticipantKind } from '../types/participant.js';
+
+/** `confirmation_state` — the approval stage a committed change was in. */
+export const confirmationStateSchema = z.enum([
+  'auto',
+  'previewed',
+  'approved',
+  'required_human_approval',
+  'auto_historical',
+]);
+export type ConfirmationState = z.infer<typeof confirmationStateSchema>;
+
+// ── The delta wire shapes ─────────────────────────────────────────────────────
+
+/**
+ * The full set of action codes a wire delta can carry — a broader vocabulary than
+ * the stored row's create, update, and delete. Each is a single character: `I`
+ * insert, `U` update, `D` delete, `A` archive, `V` revive (unarchive), `C` covering
+ * (the row just became visible to this subscriber), `G` group added, and `S` group
+ * removed.
+ */
+export const syncDeltaActionSchema = z.enum(['I', 'U', 'D', 'A', 'V', 'C', 'G', 'S']);
+export type SyncDeltaAction = z.infer<typeof syncDeltaActionSchema>;
+
+/**
+ * The payload carried on a wire delta: the post-mutation row as an object, a
+ * serialized string (used by the group-change frames on `G` and `S` deltas), or
+ * `null` on deletes. This is wider than the stored row's payload — which is only a
+ * row or null — because the group-change frames encode their payload as a string.
+ */
+export const wireDeltaDataSchema = z
+  .union([z.record(z.string(), z.unknown()), z.string()])
+  .nullable();
+export type WireDeltaData = z.infer<typeof wireDeltaDataSchema>;
+
+/**
+ * A participant reference as carried on a broadcast delta. The server expands the
+ * flat `actor_id` and `actor_kind` stored columns into this nested `{ kind, id }`
+ * shape. The type is the canonical {@link ParticipantRef} from
+ * `types/participant.ts`; the pin below fails to compile if this schema and the
+ * canonical shape ever drift.
+ */
+export const participantRefSchema = z.object({
+  kind: participantKindSchema,
+  id: z.string(),
+});
+export type { ParticipantRef } from '../types/participant.js';
+const _participantRefContract: AssertExact<
+  z.infer<typeof participantRefSchema>,
+  ParticipantRef
+> = true;
+void _participantRefContract;
+
+/**
+ * The fields the server and client agree on for a broadcast delta — the shared core
+ * both projections extend. `transactionId` is typed as the client sees it (an
+ * optional string); {@link serverSyncDeltaSchema} widens it to nullable. There is no
+ * `organizationId` here (it is never broadcast) and no attribution — those fields
+ * differ between the two sides and live in the extensions below.
+ */
+export const syncDeltaWireCoreSchema = z.object({
+  id: z.number(),
+  actionType: syncDeltaActionSchema,
+  modelName: z.string().min(1),
+  modelId: z.string().min(1),
+  data: wireDeltaDataSchema,
+  previousData: wireDeltaDataSchema.optional(),
+  syncGroups: z.array(z.string()),
+  transactionId: z.string().optional(),
+  /** Opaque source-batch identity present only on decoded customer-WAL echoes. */
+  correlationId: correlationIdSchema.optional(),
+  createdAt: z.string(),
+});
+export type SyncDeltaWireCore = z.infer<typeof syncDeltaWireCoreSchema>;
+
+/**
+ * The client's view of a wire delta: the shared core plus the fields only the
+ * client reads. Inferring this schema gives the SDK's `SyncDelta` type.
+ */
+export const clientSyncDeltaSchema = syncDeltaWireCoreSchema.extend({
+  /** @deprecated The actor id as a flat string; superseded by the server's nested
+   *  `actor`. The client does not read it — it exists only so the wire shape round-trips. */
+  createdBy: z.string().optional(),
+  /** A payload slot the client reads locally, such as group-change metadata. */
+  metadata: wireDeltaDataSchema.optional(),
+  /** Echo-matching id the client correlates against its optimistic mutation. */
+  clientMutationId: z.string().optional(),
+});
+export type ClientSyncDelta = z.infer<typeof clientSyncDeltaSchema>;
+
+/**
+ * The server's view of a wire delta: the shared core plus the audit attribution the
+ * server adds to each broadcast. The client structurally ignores these fields. This
+ * projection also narrows `transactionId` to nullable, matching the stored column.
+ */
+export const serverSyncDeltaSchema = syncDeltaWireCoreSchema.extend({
+  /** The plane project the delta was committed on (`''` = the org's default
+   *  project). Server-only: the broadcaster uses it to fan a mixed-project batch
+   *  out ONLY to same-project subscribers. It rides on the frame but the client's
+   *  `clientSyncDeltaSchema` (a non-strict object) strips it — a client only ever
+   *  receives its own project's deltas, so the value is redundant to it. */
+  projectId: z.string(),
+  transactionId: z.string().nullable(),
+  /** @deprecated Duplicates `actor`; read `actor` instead. */
+  createdBy: participantRefSchema.nullable(),
+  /** The participant who performed the action. */
+  actor: participantRefSchema.nullable(),
+  /** The participant on whose authority the actor acted; equal to `actor` for direct human commits. */
+  onBehalfOf: participantRefSchema.nullable(),
+  /** Foreign key to the authorizing capability; non-null for agent and system commits. */
+  capabilityId: z.string().nullable(),
+  confirmationState: confirmationStateSchema.nullable(),
+});
+export type ServerSyncDelta = z.infer<typeof serverSyncDeltaSchema>;
+
+/**
+ * The transaction-layer seam's transport-neutral projection of a broadcast
+ * delta. It removes delivery plumbing (`syncGroups`, `transactionId`, and
+ * `correlationId`) while retaining the row change and optional audit
+ * attribution. `TransactionLayer.observe()` yields this shape.
+ */
+export const deltaSchema = syncDeltaWireCoreSchema
+  .omit({
+    syncGroups: true,
+    transactionId: true,
+    correlationId: true,
+  })
+  .extend({
+    actor: participantRefSchema.nullable().optional(),
+    onBehalfOf: participantRefSchema.nullable().optional(),
+    capabilityId: z.string().nullable().optional(),
+    confirmationState: confirmationStateSchema.nullable().optional(),
+  });
+export type Delta = z.infer<typeof deltaSchema>;

package/src/wire/errorEnvelope.ts

@@ -0,0 +1,133 @@
+/**
+ * Turns any thrown value into the canonical error envelope and an HTTP status,
+ * so every error response carries the same
+ * `{ type, code, param, message, doc_url, request_id }` shape no matter which
+ * route or transport produced it. This is the counterpart to the wire-parsing
+ * helpers in the errors module, which turn a received envelope back into a typed
+ * error.
+ *
+ * It has no dependency on the client runtime, so a server-side handler can
+ * import it on its own to format error responses. A typed {@link AbloError}
+ * passes through with its code and status intact; anything else becomes a
+ * generic 500. A service that needs to classify database-driver failures can
+ * layer that on top before falling back to this baseline.
+ */
+import { z } from 'zod';
+import { AbloError, docUrlForCode } from '../errors.js';
+import { errorCodeSpec } from '../errorCodes.js';
+
+/**
+ * The fixed, public-facing message returned for an unclassified 500. A raw
+ * `err.message` can carry driver text, connection strings, or stack fragments,
+ * so it is never placed on the wire; a caller that needs those details logs the
+ * original error server-side before formatting the response.
+ */
+export const INTERNAL_ERROR_PUBLIC_MESSAGE = 'An internal error occurred.';
+
+const errorEnvelopeItemSchema = z.object({
+  code: z.string().optional(),
+  message: z.string(),
+  param: z.string().optional(),
+}).readonly();
+
+/**
+ * The canonical error envelope schema. Every HTTP error response and every
+ * structured frame error carries these keys. `catchall` preserves typed domain
+ * details such as `missingIds`, `conflicts`, or `retryAfterSeconds` as additive
+ * top-level members, so newer producers remain compatible with older readers.
+ */
+export const errorEnvelopeSchema = z
+  .object({
+    type: z.string(),
+    code: z.string().optional(),
+    param: z.string().optional(),
+    message: z.string(),
+    doc_url: z.string().optional(),
+    request_id: z.string().optional(),
+    errors: z.array(errorEnvelopeItemSchema).readonly().optional(),
+  })
+  .catchall(z.unknown());
+export type ErrorEnvelope = Readonly<z.infer<typeof errorEnvelopeSchema>>;
+
+/** Maps an {@link AbloError} subclass name to its default HTTP status. Each
+ *  subclass is chosen to match the status — a validation error is a 400, a
+ *  permission error a 403 — so a throw site picks the right class and code and
+ *  the status follows. An explicit `httpStatus` is supplied only when it
+ *  diverges, such as a 404 on the base class or a 503 on a server error. */
+export function statusForType(type: string): number {
+  switch (type) {
+    case 'AbloAuthenticationError':
+      return 401;
+    case 'AbloPermissionError':
+      return 403;
+    case 'AbloValidationError':
+      return 400;
+    case 'AbloRateLimitError':
+      return 429;
+    case 'AbloIdempotencyError':
+    case 'AbloStaleContextError':
+    case 'AbloClaimedError':
+      return 409;
+    case 'AbloConnectionError':
+      return 503;
+    case 'AbloServerError':
+      return 500;
+    default:
+      return 500;
+  }
+}
+
+/**
+ * Converts any thrown value into the canonical {@link ErrorEnvelope} and an HTTP
+ * status. A typed {@link AbloError} is serialized through its own `toJSON`, so
+ * its code, param, doc_url, and structured details survive, and its status comes
+ * from an explicit `httpStatus` or, failing that, {@link statusForType}.
+ * Anything else becomes a 500 `internal_error` envelope — never a bare framework
+ * "Internal Server Error" body, and never a raw error string leaked onto the
+ * wire as an unregistered code.
+ *
+ * When `requestId` is supplied and the error does not already carry one, it is
+ * stamped into the body so the response and the `x-request-id` header agree for
+ * support correlation.
+ *
+ * A service that recognizes failures this module cannot — a database driver's
+ * integrity or privilege errors, say — classifies them into an {@link AbloError}
+ * before calling here, and that error then travels the same serialization and
+ * status precedence as every other one. This module deliberately takes no
+ * classifier callback: it would cross a package boundary, where an argument the
+ * built copy does not declare is dropped in silence rather than refused.
+ */
+export function errorEnvelope(
+  err: unknown,
+  requestId?: string,
+): { body: ErrorEnvelope; status: number } {
+  const typed = err instanceof AbloError ? err : undefined;
+  if (typed !== undefined) {
+    // Status precedence: an explicit httpStatus wins; else the code's canonical
+    // status from the registry (so `new AbloError('…', { code: 'entity_not_found' })`
+    // is a 404 without the throw site repeating it); else the subclass default.
+    const status =
+      typed.httpStatus ??
+      (typed.code ? errorCodeSpec(typed.code)?.httpStatus : undefined) ??
+      statusForType(typed.type);
+    const body = typed.toJSON();
+    return {
+      body: requestId && body.request_id === undefined ? { ...body, request_id: requestId } : body,
+      status,
+    };
+  }
+  // Unknown throw: mask it. An unclassified 500 can carry database, driver, or
+  // other internal detail, so the raw message is never echoed here — this
+  // envelope is served directly to browsers. The original error stays with the
+  // caller for logging.
+  return {
+    body: {
+      type: 'AbloServerError',
+      code: 'internal_error',
+      message: INTERNAL_ERROR_PUBLIC_MESSAGE,
+      doc_url: docUrlForCode('internal_error'),
+      ...(requestId ? { request_id: requestId } : {}),
+    },
+    status: 500,
+  };
+}