@abloatai/transaction 0.47.0 → 0.49.0

package/src/coordination/schema.ts

@@ -267,6 +267,17 @@ const streamTargetSchema = targetRefSchema
 export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
 export type OnStaleMode = z.infer<typeof onStaleModeSchema>;
 
+/** The exact authoritative position retained for one ReadSet entry. */
+export const readSetWatermarkSchema = z.number().int().nonnegative();
+export type ReadSetWatermark = z.infer<typeof readSetWatermarkSchema>;
+
+/** Maximum decision-input entries one logical commit may ask the server to scan. */
+export const MAX_READ_SET_ENTRIES = 500;
+
+/** A persisted entry cannot overwrite: it observes future writes, not its own. */
+export const trackOnStaleSchema = onStaleModeSchema.exclude(['overwrite']);
+export type TrackOnStale = z.infer<typeof trackOnStaleSchema>;
+
 /**
  * The optimistic guard carried on a commit operation. `readAt` is the
  * snapshot watermark from `context.capture` (null/absent ⇒ unguarded write).
@@ -274,7 +285,7 @@ export type OnStaleMode = z.infer<typeof onStaleModeSchema>;
  * claim — see the claim layer below.
  */
 export const writeGuardSchema = z.object({
-  readAt: z.number().nullish(),
+  readAt: readSetWatermarkSchema.nullish(),
   onStale: onStaleModeSchema.nullish(),
   bypass: z.boolean().optional(),
 });
@@ -445,42 +456,79 @@ export const staleNotificationSchema = z.discriminatedUnion('scope', [
 ]);
 export type StaleNotification = z.infer<typeof staleNotificationSchema>;
 
-/**
- * One entry in a commit's batch premise — a read it was based on, so the
- * server can ask "did anything I looked at change?" — broader than the
- * write-target check, which only validates the rows being written. The server
- * re-runs stale detection against each entry at its `readAt`; a moved premise
- * fires the entry's `onStale` disposition (default `reject`) across the whole
- * batch (`notify` holds every write and notifies, `reject` aborts, `overwrite`
- * proceeds silently). An entry comes at one of two granularities:
- *
- *   • Row   — `{ model, id, readAt, fields? }`: did this specific row, or these
- *             specific fields, change?
- *   • Group — `{ group, readAt }`: did anything in this sync group change?
- *             `group` is a sync-group key such as `report:abc` or `section:s1`, the
- *             same unit a participant watches and claims.
- *
- * See `packages/ablo/docs/concurrency-convention.md` (§4) for the
- * governing convention and the receive → reconcile loop.
- */
-const readRowDependencySchema = z.object({
+/** One row named by a commit-lifetime ReadSet entry. */
+export const readSetRowTargetSchema = z.object({
+  scope: z.literal('row'),
   model: z.string(),
   id: z.string(),
-  readAt: z.number(),
   fields: z.array(z.string()).readonly().optional(),
-  onStale: onStaleModeSchema.optional(),
 });
+export type ReadSetRowTarget = z.infer<typeof readSetRowTargetSchema>;
 
-const readGroupDependencySchema = z.object({
-  /**
-   * The caller-facing view of the format: `reads: [{ group: 'report:abc' }]`
-   * type-checks inline, `'nonsense'` does not. The
-   * {@link groupStaleNotificationSchema} this premise fires uses the branded
-   * view, because there Ablo is the author.
-   */
+/** One sync group named by a ReadSet entry. */
+export const readSetGroupTargetSchema = z.object({
+  scope: z.literal('group'),
   group: syncGroupRefSchema,
-  readAt: z.number(),
-  onStale: onStaleModeSchema.optional(),
+});
+export type ReadSetGroupTarget = z.infer<typeof readSetGroupTargetSchema>;
+
+export const commitReadSetTargetSchema = z.discriminatedUnion('scope', [
+  readSetRowTargetSchema,
+  readSetGroupTargetSchema,
+]);
+export type CommitReadSetTarget = z.infer<typeof commitReadSetTargetSchema>;
+
+/** Persisted row tracking is row-grained; it has no field storage axis. */
+export const persistedReadSetRowTargetSchema = readSetRowTargetSchema.omit({ fields: true });
+export const persistedReadSetTargetSchema = z.discriminatedUnion('scope', [
+  persistedReadSetRowTargetSchema,
+  readSetGroupTargetSchema,
+]);
+export type PersistedReadSetTarget = z.infer<typeof persistedReadSetTargetSchema>;
+
+/** One exact input to the decision made by this commit. */
+export const commitReadSetEntrySchema = z.object({
+  target: commitReadSetTargetSchema,
+  watermark: readSetWatermarkSchema,
+  lifetime: z.literal('commit'),
+  onStale: onStaleModeSchema,
+});
+export type CommitReadSetEntry = z.infer<typeof commitReadSetEntrySchema>;
+
+/** One exact input retained after the declaring commit settles. */
+export const persistedReadSetEntrySchema = z.object({
+  target: persistedReadSetTargetSchema,
+  watermark: readSetWatermarkSchema,
+  lifetime: z.literal('persisted'),
+  onStale: trackOnStaleSchema,
+});
+export type PersistedReadSetEntry = z.infer<typeof persistedReadSetEntrySchema>;
+
+export const readSetEntrySchema = z.discriminatedUnion('lifetime', [
+  commitReadSetEntrySchema,
+  persistedReadSetEntrySchema,
+]);
+export type ReadSetEntry = z.infer<typeof readSetEntrySchema>;
+
+export const readSetSchema = z
+  .array(readSetEntrySchema)
+  .max(MAX_READ_SET_ENTRIES)
+  .readonly();
+export type ReadSet = z.infer<typeof readSetSchema>;
+
+/**
+ * Wire projection of a commit-lifetime ReadSet entry. The public field names
+ * stay compatible (`readAt`, flat row/group target); every member is selected
+ * from the canonical entry rather than restated beside it.
+ */
+const readRowDependencySchema = readSetRowTargetSchema.omit({ scope: true }).extend({
+  readAt: commitReadSetEntrySchema.shape.watermark,
+  onStale: commitReadSetEntrySchema.shape.onStale.optional(),
+});
+
+const readGroupDependencySchema = readSetGroupTargetSchema.omit({ scope: true }).extend({
+  readAt: commitReadSetEntrySchema.shape.watermark,
+  onStale: commitReadSetEntrySchema.shape.onStale.optional(),
 });
 
 export const readDependencySchema = z.union([
@@ -490,14 +538,14 @@ export const readDependencySchema = z.union([
 export type ReadDependency = z.infer<typeof readDependencySchema>;
 
 /**
- * A durable premise — what a participant is watching so that a later
+ * A durable ReadSet entry — what a participant is watching so that a later
  * change to it opens a {@link StaleNotification}. Where a {@link ReadDependency}
  * is checked once at commit and discarded, a `TrackDependency` is kept and
  * re-checked against every future delta. The row form watches one object; the
  * group form watches a whole sync group ("anything in `report:abc`"). See
  * `packages/ablo/docs/groups.md` for how it drives change propagation.
  *
- * It is a PROJECTION of the ephemeral premise, not a second declaration of the
+ * It is a projection of the canonical persisted entry, not a second declaration of the
  * same reference: a track names its target exactly as a read does, and the
  * three ways it differs are stated here as omissions the compiler holds.
  *
@@ -514,18 +562,10 @@ export type ReadDependency = z.infer<typeof readDependencySchema>;
  *     registered the track, so a caller with nothing to say about when it last
  *     looked gets "from here on".
  *
- * A field added to the premise reaches both halves; a field the durable half
+ * A field added to the ReadSet target reaches both halves; a field the durable half
  * genuinely cannot carry has to be omitted here on purpose, in one line, rather
  * than by being quietly left out of a copy.
  */
-/**
- * A track's disposition — the premise enum with `overwrite` subtracted, derived
- * from it rather than spelled again, so a mode added to the convention reaches
- * a track unless it is deliberately excluded here.
- */
-export const trackOnStaleSchema = onStaleModeSchema.exclude(['overwrite']);
-export type TrackOnStale = z.infer<typeof trackOnStaleSchema>;
-
 /**
  * What a track does when the caller says nothing — reporting, the behavior every
  * track had before the disposition existed, so an existing registration is
@@ -539,18 +579,32 @@ export type TrackOnStale = z.infer<typeof trackOnStaleSchema>;
 export const DEFAULT_TRACK_ON_STALE: TrackOnStale = 'notify';
 
 const trackBaseSchema = {
-  readAt: z.number().optional(),
-  onStale: trackOnStaleSchema.optional(),
+  readAt: persistedReadSetEntrySchema.shape.watermark.optional(),
+  onStale: persistedReadSetEntrySchema.shape.onStale.optional(),
 } as const;
 
 export const trackDependencySchema = z.union([
-  readRowDependencySchema
-    .omit({ onStale: true, fields: true, readAt: true })
-    .extend(trackBaseSchema),
-  readGroupDependencySchema.omit({ onStale: true, readAt: true }).extend(trackBaseSchema),
+  persistedReadSetRowTargetSchema.omit({ scope: true }).extend(trackBaseSchema),
+  readSetGroupTargetSchema.omit({ scope: true }).extend(trackBaseSchema),
 ]);
 export type TrackDependency = z.infer<typeof trackDependencySchema>;
 
+/** Bounded wire projections of the two ReadSet lifetimes. */
+export const readDependencyListSchema = z
+  .array(readDependencySchema)
+  .max(MAX_READ_SET_ENTRIES);
+export const trackDependencyListSchema = z
+  .array(trackDependencySchema)
+  .max(MAX_READ_SET_ENTRIES);
+
+/** Shared combined-cardinality rule for envelopes carrying both projections. */
+export function readSetProjectionEntryCount(value: {
+  readonly reads?: readonly unknown[] | null;
+  readonly track?: readonly unknown[] | null;
+}): number {
+  return (value.reads?.length ?? 0) + (value.track?.length ?? 0);
+}
+
 // ─────────────────────────────────────────────────────────────────────────
 //  Layer 2 — pessimistic claims and leases
 // ─────────────────────────────────────────────────────────────────────────
@@ -1328,7 +1382,12 @@ export type UpdateSubscriptionPayload = z.infer<
 export const subscriptionAckPayloadSchema = z.object({
   success: z.boolean(),
   syncGroups: z.array(z.string()),
-  error: z.object({ code: z.string(), message: z.string() }).optional(),
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+    request_id: z.string().optional(),
+    event_id: z.string().optional(),
+  }).optional(),
 });
 export type SubscriptionAckPayload = z.infer<
   typeof subscriptionAckPayloadSchema
@@ -1360,6 +1419,12 @@ export const commitOperationSchema = writeGuardSchema.extend({
   input: z.record(z.string(), z.unknown()).nullish(),
   /** Per-op client tx id, echoed on the broadcast delta. */
   transactionId: z.string().nullish(),
+  /**
+   * The server-issued claim identity this operation was performed under.
+   * Distinct from `transactionId`: a claim attributes and fences coordinated
+   * ownership, while a transaction id correlates the resulting source echo.
+   */
+  claimId: z.string().min(1).nullish(),
   /**
    * The fencing token from the held claim this write belongs to (Option B).
    * Present only on a write issued under a claim that was granted one; the

package/src/coordination/targetConflict.ts

@@ -12,7 +12,7 @@ import type { ClaimTargetDetails } from './locator.js';
  * two places to land and no way to notice when it landed in one. It is one
  * definition here, and both authorities import it.
  *
- * It lives in the settlement core rather than the server because it is the rule
+ * It lives in the confirmation core rather than the server because it is the rule
  * itself, not a deployment of it: a claim authority running against a
  * developer's own database has to answer this question exactly the same way,
  * and a client that wants to predict a refusal before paying for the round trip

package/src/durableWrites.ts

@@ -3,7 +3,7 @@
  *
  * Owns the persistence contract behind `Ablo({ durableWrites })` — a behavior
  * contract of methods, not a serialized shape, which is why it lives here
- * rather than in `transactions/settlement/`. The records that cross this port
+ * rather than in `transactions/confirmation/`. The records that cross this port
  * are owned by `pendingWriteSchema` there; this module never redescribes them.
  *
  * The engine consumes the port through `commitOutboxStore`, and the HTTP client
@@ -12,8 +12,8 @@
 
 import { z } from 'zod';
 import { AbloValidationError } from './errors.js';
-import type { CommitOutboxScope } from './transactions/settlement/commitEnvelope.js';
-import type { PendingWrite } from './transactions/settlement/pendingWrite.js';
+import type { CommitOutboxScope } from './transactions/confirmation/commitEnvelope.js';
+import type { PendingWrite } from './transactions/confirmation/pendingWrite.js';
 
 /**
  * Persistence port used by `Ablo({ durableWrites })`.

package/src/errorCodes.ts

@@ -39,7 +39,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-30';
+export const ERROR_CONTRACT_VERSION = '2026-08-04';
 
 /** A coarse grouping of error codes, used to organize metrics and documentation. */
 export type ErrorCategory =
@@ -129,6 +129,36 @@ export interface ErrorCodeSpec {
    * this field can be left unset.
    */
   readonly recovery?: RecoveryClass;
+  /** Exhaustive sink and alert policy for this code. */
+  readonly observability: ErrorObservabilityPolicy;
+}
+
+export interface ErrorObservabilityPolicy {
+  readonly severity: 'info' | 'warning' | 'error' | 'fatal';
+  readonly sentry: 'log' | 'issue';
+  readonly pagingEligible: boolean;
+  readonly expectedVolume: 'low' | 'normal' | 'high';
+  readonly owner: 'platform' | 'product';
+}
+
+function observabilityPolicy(
+  category: ErrorCategory,
+  httpStatus: number | undefined,
+  operational = false,
+): ErrorObservabilityPolicy {
+  if ((httpStatus ?? 0) >= 500) {
+    return { severity: 'error', sentry: 'issue', pagingEligible: true, expectedVolume: 'low', owner: 'platform' };
+  }
+  if (operational) {
+    return { severity: 'warning', sentry: 'issue', pagingEligible: false, expectedVolume: 'low', owner: 'platform' };
+  }
+  return {
+    severity: category === 'auth' ? 'info' : 'warning',
+    sentry: 'log',
+    pagingEligible: false,
+    expectedVolume: category === 'auth' ? 'high' : 'normal',
+    owner: 'product',
+  };
 }
 
 const wire = (
@@ -136,8 +166,17 @@ const wire = (
   httpStatus: number,
   retryable: boolean,
   message: string,
-  recovery?: RecoveryClass
-): ErrorCodeSpec => ({ category, surface: 'wire', httpStatus, retryable, message, recovery });
+  recovery?: RecoveryClass,
+  operational = false,
+): ErrorCodeSpec => ({
+  category,
+  surface: 'wire',
+  httpStatus,
+  retryable,
+  message,
+  recovery,
+  observability: observabilityPolicy(category, httpStatus, operational),
+});
 
 const client = (
   category: ErrorCategory,
@@ -147,6 +186,7 @@ const client = (
   category,
   surface: 'client',
   retryable: false,
+  observability: observabilityPolicy(category, undefined),
   message,
   ...(recovery !== undefined ? { recovery } : {}),
 });
@@ -234,6 +274,18 @@ export const ERROR_CODES = {
     'Your session has expired or is no longer valid. Sign in again to continue.',
     'session_expiry'
   ),
+  better_auth_request_failed: wire(
+    'auth',
+    400,
+    false,
+    'The authentication request was rejected. Check the submitted credentials or request and try again.'
+  ),
+  better_auth_upstream_failed: wire(
+    'server',
+    500,
+    true,
+    'The authentication service could not complete the request. Retry the request; if it continues to fail, contact support.'
+  ),
   // `jwt_invalid` is the general fallback; the codes below it split out specific
   // failure modes, so an integrator can tell a wrong JWKS registration from a
   // token with no organization claim from a wrong audience, instead of getting
@@ -319,6 +371,18 @@ export const ERROR_CODES = {
     false,
     'This deployment does not accept direct connection-string data sources. Register a signed Data Source endpoint instead.'
   ),
+  source_connector_localhost_required: wire(
+    'validation',
+    400,
+    false,
+    'A connector-only development Data Source must use a localhost descriptor. Use `ablo dev --local`; use the ordinary signed HTTPS endpoint registration for a deployed handler.'
+  ),
+  source_connector_unauthenticated: wire(
+    'auth',
+    401,
+    false,
+    'The localhost Data Source connector could not authenticate. Rerun `ablo dev --local` so it mints and uses a fresh branch-bound secret key.'
+  ),
 
   // ── permission / capability (403) ──────────────────────────────────
   capability_scope_denied: wire(
@@ -339,12 +403,6 @@ export const ERROR_CODES = {
     false,
     'This capability cannot be used — it is unknown, revoked, or expired. Request a fresh grant.'
   ),
-  test_database_not_registered: wire(
-    'permission',
-    403,
-    false,
-    'Test mode requires a registered dev database for this org — run `npx ablo init` to register one for your test key.'
-  ),
   tenant_routing_failed: wire(
     'server',
     500,
@@ -355,25 +413,37 @@ export const ERROR_CODES = {
     'permission',
     403,
     false,
-    'The database role Ablo connects with is a superuser or has `BYPASSRLS`, so Postgres will not enforce row-level security for it. Connect with a role that is subject to RLS.'
+    'The database role Ablo connects with is a superuser or has `BYPASSRLS`, so Postgres will not enforce row-level security for it. Connect with a role that is subject to RLS.',
+    undefined,
+    true,
   ),
   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.'
+    'Ablo could not introspect the database role it connects with, so it cannot verify that row-level security is enforced.',
+    undefined,
+    true,
   ),
   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.'
+    '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.',
+    undefined,
+    true,
   ),
   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."
+    "The database host did not resolve exclusively to an allowed address for this route. Use a publicly resolvable direct endpoint, or configure the matching PrivateLink, peering, or VPN route. Localhost has its own `database_loopback_requires_connector` workflow."
+  ),
+  database_loopback_requires_connector: wire(
+    'validation',
+    400,
+    false,
+    'Ablo Cloud cannot open a direct PostgreSQL connection to localhost on your machine. For localhost-first development, run `ablo migrate` once and keep `ablo dev --local` running; use a network-reachable direct route only when Ablo must observe arbitrary SQL writes through WAL.'
   ),
   connected_database_unreachable: wire(
     'tenant',
@@ -430,7 +500,7 @@ export const ERROR_CODES = {
     '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.'
+    'This claim is no longer current because another participant completed newer work on the row. Re-claim the row and retry from the fresh state.'
   ),
   entity_claimed: wire(
     'claim',
@@ -486,7 +556,7 @@ export const ERROR_CODES = {
   ),
   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).'
+    'Claiming is unavailable on this model client. Construct it through the standard Ablo({ schema, apiKey }) client and retry.'
   ),
   model_join_not_configured: client(
     'claim',
@@ -699,6 +769,18 @@ export const ERROR_CODES = {
     false,
     'The participant is not allowed to execute this mutator.'
   ),
+  source_connector_requires_secret_key: wire(
+    'permission',
+    403,
+    false,
+    'A Data Source reverse channel must authenticate with the branch-bound secret (`sk_`) key created by `ablo dev`; browser, ephemeral, restricted, and management keys cannot serve a database.'
+  ),
+  source_connector_production_not_enabled: wire(
+    'permission',
+    403,
+    false,
+    'This production Data Source has not opted into reverse-channel transport. `ablo dev --local` is for child branches; use a direct production endpoint or explicitly enable the supported production reverse-channel route.'
+  ),
 
   // ── not found (404) ────────────────────────────────────────────────
   entity_not_found: wire(
@@ -723,7 +805,15 @@ export const ERROR_CODES = {
     'not_found',
     404,
     false,
-    'No database is connected to this plane yet, so there is nothing to check. Connect one with `ablo connect apply`, then run the check again.'
+    'This branch is not connected to your database yet. Run `ablo connect` for a cloud-reachable direct Postgres endpoint, or `ablo dev --local` to register and serve a localhost Data Source, then retry.',
+    undefined,
+    true,
+  ),
+  source_connector_no_source_registered: wire(
+    'not_found',
+    404,
+    false,
+    'The branch has no endpoint Data Source for this connector to serve. Run `ablo dev --local` with the current CLI, which registers the connector-only source before opening the socket.'
   ),
   task_id_missing: wire(
     'server',
@@ -978,7 +1068,55 @@ export const ERROR_CODES = {
     'transport',
     503,
     true,
-    'A network error occurred while talking to the data source. Check connectivity and retry.'
+    'A network error occurred while talking to the data source. For localhost mode, keep `ablo dev --local` running and check its connector output; for a direct source, check database connectivity and retry.'
+  ),
+  source_request_failed: wire(
+    'transport',
+    502,
+    true,
+    'The signed Data Source returned a failure without a more specific code. Inspect the `ablo dev --local` process or deployed endpoint logs, then retry with the same idempotency key.'
+  ),
+  source_connector_not_attached: wire(
+    'transport',
+    503,
+    true,
+    'This branch uses localhost connector-only storage, but no connector is attached. Start or restart `ablo dev --local` and keep that process running.'
+  ),
+  source_connector_timeout: wire(
+    'transport',
+    504,
+    true,
+    'The local Data Source handler did not answer before the connector deadline. Check the local Postgres connection and handler logs; the same idempotent request may be retried.'
+  ),
+  source_connector_send_failed: wire(
+    'transport',
+    502,
+    true,
+    'The connector socket closed while Ablo was forwarding a signed Data Source request. Keep `ablo dev --local` running; Ablo retries after the connector reconnects.'
+  ),
+  source_connector_disconnected: wire(
+    'transport',
+    503,
+    true,
+    'The localhost Data Source connector disconnected with a request in flight. The connector reconnects automatically; retry after it reports ready.'
+  ),
+  source_connector_superseded: wire(
+    'transport',
+    503,
+    true,
+    'A newer localhost Data Source connector replaced this one. Stop duplicate `ablo dev --local` processes and use the newest process; in-flight requests are safe to retry.'
+  ),
+  source_connector_shutdown: wire(
+    'transport',
+    503,
+    true,
+    'The Ablo service shut down the connector while a request was in flight. The connector reconnects automatically after the service returns.'
+  ),
+  source_connector_protocol_error: wire(
+    'transport',
+    400,
+    false,
+    'The CLI and Ablo service disagreed on the Data Source connector frame protocol, or a malformed frame arrived. Upgrade the Ablo CLI and SDK together, then restart `ablo dev --local`.'
   ),
   source_unreachable: wire(
     'transport',
@@ -990,7 +1128,19 @@ export const ERROR_CODES = {
     'transport',
     503,
     false,
-    "The plane's data source is not in a verified, resolvable state. Fix its registration, secret, or configuration; Ablo will not fall through to hosted storage."
+    "This branch's database connection is not ready. Check its credentials and configuration; Ablo will not send reads or writes anywhere else."
+  ),
+  source_connector_handler_error: wire(
+    'server',
+    500,
+    true,
+    'The local signed Data Source handler threw while processing a request. Read the `ablo dev --local` error immediately above it, fix the database or adapter failure, and retry.'
+  ),
+  source_connector_internal_error: wire(
+    'server',
+    500,
+    true,
+    'Ablo could not establish the Data Source reverse channel because of an internal service failure. Retry; if it persists, report the request id.'
   ),
   identity_network_error: wire(
     'transport',
@@ -1103,6 +1253,30 @@ export const ERROR_CODES = {
   ),
 
   // ── server (5xx) ───────────────────────────────────────────────────
+  session_check_failed: wire(
+    'server',
+    503,
+    true,
+    'Ablo could not verify the current login session. Retry shortly.'
+  ),
+  mint_failed: wire(
+    'server',
+    502,
+    true,
+    'Ablo could not mint the requested runtime credential. Retry shortly.'
+  ),
+  server_side_only: wire(
+    'permission', 403, false, 'This endpoint is available only to trusted server-side callers.'
+  ),
+  unknown_auth_host: wire(
+    'auth', 400, false, 'The authentication host is not recognized.'
+  ),
+  no_active_organization: wire(
+    'tenant', 400, false, 'Select an active organization before continuing.'
+  ),
+  data_session_unsupported: wire(
+    'validation', 400, false, 'This sign-in host cannot create the requested data session.'
+  ),
   internal_error: wire(
     'server',
     500,
@@ -1140,7 +1314,7 @@ export const ERROR_CODES = {
   ),
   db_identity_mismatch: client(
     'client',
-    'The local database belongs to a different authenticated identity or data plane.'
+    'The local database is connected to a different organization, project, or branch.'
   ),
   db_cleanup_failed: client(
     'client',
@@ -1306,19 +1480,19 @@ export const ERROR_CODES = {
     '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."
+    "This model gets its tenant identity from the connected Data Source, but that connection is not ready for scoped reads yet. Ablo refused the read to prevent data from crossing tenant boundaries. Connect the branch and retry; for internally logged models, use `by: 'column'` or `by: 'parent'`."
   ),
   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."
+    "Rows in this model belong to one person rather than the whole organization, but the current read source does not carry the owner identity needed to enforce that boundary. Ablo returned nothing to prevent one member from seeing another member's private records. Use a read source that preserves owner identity, or a credential that acts for the organization."
   ),
   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."
+    "This model is in the branch's registered schema, but its table does not exist in the connected database yet. `ablo push` records the model but does not change a customer's database. Apply the table migration in your database, then retry the read."
   ),
   schema_table_invalid: wire('schema', 500, false, "The model's table identifier is invalid."),
   schema_scope_invalid: wire(
@@ -1355,7 +1529,9 @@ export const ERROR_CODES = {
     'permission',
     403,
     false,
-    'Schema registration could not create tables in the target database: the engine is not permitted to run DDL there.'
+    'Schema registration could not create tables in the target database: the engine is not permitted to run DDL there.',
+    undefined,
+    true,
   ),
   model_query_failed: wire(
     'validation',
@@ -1492,7 +1668,7 @@ export const ERROR_CODES = {
     '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.'
+    'No claim of yours exists with the given id. It was released, expired, or belongs to a different branch.'
   ),
   invalid_participant_kind: wire(
     'validation',
@@ -1549,6 +1725,10 @@ export const ERROR_CODES = {
   ),
   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.'),
+  operational_warning: client(
+    'server',
+    'Ablo handled an operational degradation that remains searchable for diagnosis.'
+  ),
   incompatible_change: wire(
     'conflict',
     409,
@@ -1559,7 +1739,7 @@ export const ERROR_CODES = {
     'conflict',
     409,
     false,
-    'A connected log plane has live rows for a mapped model that disappeared. Declare a rename or an explicit drop/reset before advancing the schema.'
+    'This branch has live replicated rows for a mapped model that disappeared. Declare a rename or an explicit drop/reset before advancing the schema.'
   ),
 } as const satisfies Record<string, ErrorCodeSpec>;