@abloatai/ablo 0.26.0 → 0.28.0

package/dist/webhooks/index.js

@@ -1,10 +1,8 @@
 /**
- * `@abloatai/ablo/webhooks` — the webhook event catalog + delta mapping.
- *
- * Customers import {@link AbloWebhookEvent} to type their handler; the server
- * uses {@link deltaToWebhookEvent} to turn transaction-log deltas into events
- * for Svix to deliver. Signature verification is NOT here — the customer uses
- * the open Standard Webhooks library (`svix` / `standardwebhooks`), so Ablo
- * ships no crypto.
+ * The public entry point for webhooks. Import {@link AbloWebhookEvent} to type
+ * your event handler, and use {@link deltaToWebhookEvent} to turn a committed
+ * change from the transaction log into an event to deliver. This module does not
+ * verify signatures and ships no cryptography; recipients verify deliveries with
+ * a standard webhooks library.
  */
 export { deltaToWebhookEvent, } from './events.js';

package/dist/wire/bootstrapReason.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/** Machine-readable reasons a live delta stream must resume via catch-up. */
+export declare const bootstrapReasonSchema: z.ZodEnum<{
+    too_far_behind: "too_far_behind";
+    too_many_deltas: "too_many_deltas";
+    missing_entities: "missing_entities";
+    stream_gap: "stream_gap";
+}>;
+export type BootstrapReason = z.infer<typeof bootstrapReasonSchema>;

package/dist/wire/bootstrapReason.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+/** Machine-readable reasons a live delta stream must resume via catch-up. */
+export const bootstrapReasonSchema = z.enum([
+    'too_far_behind',
+    'too_many_deltas',
+    'missing_entities',
+    'stream_gap',
+]);

package/dist/{schema/sync-delta-wire.d.ts → wire/delta.d.ts}

@@ -1,35 +1,51 @@
 /**
- * Canonical Zod contract for the WIRE delta — the broadcast object that travels
- * server → client (the `delta` / `sync_response` frame payload). This is the
- * "same contract across both" seam: the SDK client and the sync-server each
- * derive their `SyncDelta` type from THESE schemas via `z.infer`, instead of
- * hand-maintaining two interfaces that drift (they had: the server typed
- * `actionType` as `string` and `createdBy` as a nested ref; the client typed
- * `actionType` as the 8-value union and `createdBy` as a flat string — a silent
- * divergence the client never noticed because it ignores attribution).
+ * 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/`.
  *
- * Distinct from {@link import('./sync-delta-row.js').syncDeltaRowSchema} — that
- * is the STORED ROW (has `organizationId`, flat `actor_id`/`actor_kind`
- * columns, single-char action). The wire delta is a PROJECTION: no
- * `organizationId` (the server-trusted isolation predicate is never broadcast),
- * the full Linear action vocabulary, and attribution hydrated into nested
- * {@link ParticipantRef}s.
+ * The wire delta is a projection of the stored `sync_deltas` row (see
+ * {@link import('../schema/syncDeltaRow.js').syncDeltaRowSchema}) 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.
  *
- * Shape (per the "shared core + layer extensions" decision):
- *   - {@link syncDeltaWireCoreSchema} — the fields BOTH sides agree on.
- *   - {@link clientSyncDeltaSchema}    — core + the SDK-only extras.
- *   - {@link serverSyncDeltaSchema}    — core + the audit attribution the server
- *                                        enriches each broadcast with (the client
- *                                        structurally ignores these).
+ * 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.
  *
- * Monorepo is on Zod v4.
+ * The two participant enums below (`participantKind`, `confirmationState`) are the
+ * shared vocabulary of the protocol. They live here, at the wire layer, so the
+ * stored-row schema can import them downward rather than the wire delta reaching
+ * up into the schema DSL for them.
  */
 import { z } from 'zod';
+/** `participant_kind` — who a delta is attributed to. */
+export declare const participantKindSchema: z.ZodEnum<{
+    user: "user";
+    agent: "agent";
+    system: "system";
+}>;
+export type ParticipantKind = z.infer<typeof participantKindSchema>;
+/** `confirmation_state` — the approval stage a committed change was in. */
+export declare const confirmationStateSchema: z.ZodEnum<{
+    auto: "auto";
+    previewed: "previewed";
+    approved: "approved";
+    required_human_approval: "required_human_approval";
+    auto_historical: "auto_historical";
+}>;
+export type ConfirmationState = z.infer<typeof confirmationStateSchema>;
 /**
- * `action_type` on the WIRE — the full Linear-compatible vocabulary a broadcast
- * carries (vs the stored row's core CRUD). `I`nsert, `U`pdate, `D`elete,
- * `A`rchive, `V` reVive/unarchive, `C`overing (gained visibility), `G`roupAdded,
- * `S` groupRemoved.
+ * 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 declare const syncDeltaActionSchema: z.ZodEnum<{
     I: "I";
@@ -43,16 +59,17 @@ export declare const syncDeltaActionSchema: z.ZodEnum<{
 }>;
 export type SyncDeltaAction = z.infer<typeof syncDeltaActionSchema>;
 /**
- * A wire delta payload: the post-mutation row object, a control-frame STRING
- * (e.g. a serialized group-change payload on `G`/`S` deltas), or `null` (on
- * deletes). Wider than the stored `data` (row-or-null) precisely because the
- * group/permission frames serialize a string.
+ * 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 declare const wireDeltaDataSchema: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
 export type WireDeltaData = z.infer<typeof wireDeltaDataSchema>;
 /**
- * A nested participant reference as carried on a BROADCAST delta. The server
- * hydrates the flat `actor_id`/`actor_kind` stored columns into this.
+ * 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.
  */
 export declare const participantRefSchema: z.ZodObject<{
     kind: z.ZodEnum<{
@@ -64,11 +81,11 @@ export declare const participantRefSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ParticipantRef = z.infer<typeof participantRefSchema>;
 /**
- * The fields BOTH server and client agree on for a broadcast delta — the shared
- * contract. `transactionId` is modelled as the client sees it (optional string);
- * the server projection widens it to nullable. No `organizationId` (never
- * broadcast). No `createdBy`/attribution here — those types differ per layer and
- * live in the extensions below.
+ * 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 declare const syncDeltaWireCoreSchema: z.ZodObject<{
     id: z.ZodNumber;
@@ -92,8 +109,8 @@ export declare const syncDeltaWireCoreSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type SyncDeltaWireCore = z.infer<typeof syncDeltaWireCoreSchema>;
 /**
- * Client projection — core + the SDK-only fields the client reads locally.
- * `z.infer` of this is the SDK's `SyncDelta` (see `sync/SyncWebSocket.ts`).
+ * 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 declare const clientSyncDeltaSchema: z.ZodObject<{
     id: z.ZodNumber;
@@ -120,9 +137,9 @@ export declare const clientSyncDeltaSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ClientSyncDelta = z.infer<typeof clientSyncDeltaSchema>;
 /**
- * Server projection — core + the audit attribution the server enriches each
- * broadcast with (for the audit pane). The client ignores all of it. Overrides
- * `transactionId` to nullable (the server's stored-column reality).
+ * 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 declare const serverSyncDeltaSchema: z.ZodObject<{
     id: z.ZodNumber;

package/dist/wire/delta.js

@@ -0,0 +1,114 @@
+/**
+ * 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 (see
+ * {@link import('../schema/syncDeltaRow.js').syncDeltaRowSchema}) 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 two participant enums below (`participantKind`, `confirmationState`) are the
+ * shared vocabulary of the protocol. They live here, at the wire layer, so the
+ * stored-row schema can import them downward rather than the wire delta reaching
+ * up into the schema DSL for them.
+ */
+import { z } from 'zod';
+// ── Shared participant vocabulary (mirrors the corresponding Postgres enums) ──
+/** `participant_kind` — who a delta is attributed to. */
+export const participantKindSchema = z.enum(['user', 'agent', 'system']);
+/** `confirmation_state` — the approval stage a committed change was in. */
+export const confirmationStateSchema = z.enum([
+    'auto',
+    'previewed',
+    'approved',
+    'required_human_approval',
+    'auto_historical',
+]);
+// ── 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']);
+/**
+ * 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();
+/**
+ * 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.
+ */
+export const participantRefSchema = z.object({
+    kind: participantKindSchema,
+    id: z.string(),
+});
+/**
+ * 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(),
+    createdAt: z.string(),
+});
+/**
+ * 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(),
+});
+/**
+ * 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({
+    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(),
+    /** Foreign key to the task for the AI turn whose prompt caused this delta. */
+    causedByTaskId: z.string().nullable(),
+});

package/dist/wire/errorEnvelope.d.ts

@@ -1,15 +1,13 @@
 /**
- * The constant public message for an unclassified 500. Mirrors
- * `apps/sync-server/src/errors.ts`'s `INTERNAL_ERROR_PUBLIC_MESSAGE` —
- * the parity test in apps/sync-server pins the two producers together. A raw
- * `err.message` (driver text, connection strings, stack fragments) must never
- * be the wire message; callers that need the detail log the original error
- * server-side before/at the envelope call.
+ * 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 declare const INTERNAL_ERROR_PUBLIC_MESSAGE = "An internal error occurred.";
-/** The canonical wire envelope — Stripe's error-object shape. Every HTTP error
- *  response and every structured frame error carries this exact set of keys,
- *  regardless of which route or transport produced it. */
+/** The canonical error envelope. Every HTTP error response and every structured
+ *  frame error carries this exact set of keys, regardless of which route or
+ *  transport produced it. */
 export interface ErrorEnvelope {
     readonly type: string;
     readonly code?: string;
@@ -17,38 +15,39 @@ export interface ErrorEnvelope {
     readonly message: string;
     readonly doc_url?: string;
     readonly request_id?: string;
-    /** Aggregate field-level failures — so one 4xx can report EVERY invalid input
-     *  at once (schema push, batch commit, CLI-arg validation) instead of failing
-     *  on the first. `param` stays the single-field convenience case. (RFC 9457
-     *  `errors[]` / JSON:API `errors[]` / Google `BadRequest.fieldViolations[]`.) */
+    /** Field-level failures collected together, so a single 4xx can report every
+     *  invalid input at once — for example a schema push, a batch commit, or CLI
+     *  argument validation — instead of failing on the first. Use `param` for the
+     *  single-field case. */
     readonly errors?: readonly {
         readonly code?: string;
         readonly message: string;
         readonly param?: string;
     }[];
-    /** Typed-details slot: `AbloError.toJSON()` spreads its `details` (e.g.
-     *  `missingIds`, `conflicts`, `retryAfterSeconds`) as top-level members.
-     *  Consumers MUST ignore members they don't recognize (forward-compat). */
+    /** Additional typed details. {@link AbloError} serialization spreads its
+     *  `details` — such as `missingIds`, `conflicts`, or `retryAfterSeconds` — as
+     *  top-level members here. Ignore any member you do not recognize, so new ones
+     *  can be added without breaking you. */
     readonly [key: string]: unknown;
 }
-/** {@link AbloError} subclass → default HTTP status. The subclass is chosen to
- *  match status semantics (a validation error is a 400, a permission error a
- *  403), so a throw site only picks the right class + code and the status
- *  follows — an explicit `httpStatus` is passed only when it diverges (e.g. a
- *  404 on the base class, a 503 on AbloServerError). Mirrors the same table in
- *  apps/sync-server's self-contained `errors.ts`. */
+/** 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 declare function statusForType(type: string): number;
 /**
- * Convert ANY thrown value into the canonical {@link ErrorEnvelope} plus an
- * HTTP status. A typed {@link AbloError} is serialized via its own `toJSON`
- * (so `code`/`param`/`doc_url`/structured `details` survive) and gets its
- * status from an explicit `httpStatus` or, failing that, {@link statusForType}.
- * Anything else degrades to a 500 `internal_error` envelope — never a bare
- * framework "Internal Server Error" text body, and never a raw error string
- * leaked onto the wire as an unregistered code.
+ * 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.
  *
- * `requestId` is stamped into the body when the error didn't already carry one,
- * so the response and the `x-request-id` header agree for support correlation.
+ * 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.
  */
 export declare function errorEnvelope(err: unknown, requestId?: string): {
     body: ErrorEnvelope;

package/dist/wire/errorEnvelope.js

@@ -1,38 +1,31 @@
 /**
- * ERROR egress — turn ANY thrown value into Stripe's error-object envelope plus
- * an HTTP status, so every error response across the Ablo surface carries the
- * identical `{ type, code, param, message, doc_url, request_id }` shape
- * regardless of which route or service produced it.
+ * 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.
  *
- * This is the wire-PRODUCE counterpart to `errors.ts`'s wire-PARSE
- * (`translateHttpError`/`errorFromWire`). It lives in `wire/` — not in the main
- * SDK entry — so a server-side consumer (a Next.js route) can import it without
- * dragging in the client runtime (mobx/react/IndexedDB).
- *
- * The classifier is the UNIVERSAL baseline: a typed {@link AbloError} passes
- * through (subclass + code + httpStatus preserved), everything else degrades to
- * a 500 `internal_error`. Service-specific normalization that needs a DB driver
- * (apps/sync-server classifies raw Postgres SQLSTATE + MutatorError) is layered
- * on top in that service — it is intentionally NOT pulled into the shared,
- * dependency-free contract.
+ * 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 { AbloError, docUrlForCode } from '../errors.js';
 import { errorCodeSpec } from '../errorCodes.js';
 /**
- * The constant public message for an unclassified 500. Mirrors
- * `apps/sync-server/src/errors.ts`'s `INTERNAL_ERROR_PUBLIC_MESSAGE` —
- * the parity test in apps/sync-server pins the two producers together. A raw
- * `err.message` (driver text, connection strings, stack fragments) must never
- * be the wire message; callers that need the detail log the original error
- * server-side before/at the envelope call.
+ * 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.';
-/** {@link AbloError} subclass → default HTTP status. The subclass is chosen to
- *  match status semantics (a validation error is a 400, a permission error a
- *  403), so a throw site only picks the right class + code and the status
- *  follows — an explicit `httpStatus` is passed only when it diverges (e.g. a
- *  404 on the base class, a 503 on AbloServerError). Mirrors the same table in
- *  apps/sync-server's self-contained `errors.ts`. */
+/** 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) {
     switch (type) {
         case 'AbloAuthenticationError':
@@ -56,16 +49,17 @@ export function statusForType(type) {
     }
 }
 /**
- * Convert ANY thrown value into the canonical {@link ErrorEnvelope} plus an
- * HTTP status. A typed {@link AbloError} is serialized via its own `toJSON`
- * (so `code`/`param`/`doc_url`/structured `details` survive) and gets its
- * status from an explicit `httpStatus` or, failing that, {@link statusForType}.
- * Anything else degrades to a 500 `internal_error` envelope — never a bare
- * framework "Internal Server Error" text body, and never a raw error string
- * leaked onto the wire as an unregistered code.
+ * 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.
  *
- * `requestId` is stamped into the body when the error didn't already carry one,
- * so the response and the `x-request-id` header agree for support correlation.
+ * 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.
  */
 export function errorEnvelope(err, requestId) {
     if (err instanceof AbloError) {
@@ -81,10 +75,10 @@ export function errorEnvelope(err, requestId) {
             status,
         };
     }
-    // Unknown throw → mask. The server copy deliberately never echoes a raw
-    // message on an unclassified 500 (it can carry pg/driver/internal detail);
-    // this producer must not either — sync-web's dashboard routes serve THIS
-    // envelope to browsers. The raw error stays with the caller for logging.
+    // 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',