@abloatai/ablo 0.29.3 → 0.30.1

package/dist/client/resourceTypes.d.ts

@@ -4,7 +4,8 @@
  * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
  * imports.
  */
-import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
+import type { ReadDependency } from '../coordination/schema.js';
+import type { ClientCommitReceipt, CommitStatus } from '../wire/commit.js';
 import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
 export type { ModelTarget, ModelClaim };
 import type { SchemaRecord } from '../schema/schema.js';
@@ -19,9 +20,9 @@ import type { ClaimOptions, ClaimParams, ClaimReadApi, AwaitedClaimMethod } from
  *   `create({ data })` / `update({ id, data })` / `delete({ id })` — writes
  *   `claim({ id })` — a durable claim handle for coordinated writes
  */
-export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ModelOperations, } from './createModelProxy.js';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, ModelOperations, } from './createModelProxy.js';
 export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
-export type CommitWait = 'queued' | 'confirmed';
+export type CommitWait = CommitStatus;
 export type IfClaimedPolicy = 'return' | 'fail';
 export interface ClaimedOptions {
     /**
@@ -37,9 +38,9 @@ export interface ModelReadOptions extends ClaimedOptions {
 }
 export interface ClaimCreateOptions {
     readonly target: ModelTarget;
-    /** Human-readable phase shown to peers — `'editing'`, `'writing'`. The same
-     *  word on every claim surface. */
-    readonly reason: string;
+    /** Peer-visible description of the work — the same field on every claim
+     *  surface. Defaults to `'editing'` when omitted. */
+    readonly description?: string;
     readonly ttl?: Duration;
     /**
      * Join the server's fair FIFO queue when the target is already claimed,
@@ -67,6 +68,8 @@ export interface CommitOperationInput {
     readonly transactionId?: string | null;
     readonly readAt?: number | null;
     readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
+    /** Fencing token (Option B) from the batch's claim handle; server-validated. */
+    readonly fenceToken?: number | null;
 }
 export interface CommitCreateOptions {
     readonly idempotencyKey?: string | null;
@@ -94,26 +97,8 @@ export interface CommitCreateOptions {
      */
     readonly reads?: readonly ReadDependency[] | null;
 }
-export interface CommitReceipt {
-    readonly id: string;
-    readonly status: CommitWait;
-    readonly lastSyncId?: number;
-    /**
-     * Stale-context notifications: present only when this commit guarded a write with
-     * `onStale: 'notify'` and the premise moved concurrently. Each carries the
-     * conflicting field's current value, handed back as data rather than raising an
-     * `AbloStaleContextError`, so the caller — an agent or a human — decides how to
-     * resolve it.
-     */
-    readonly notifications?: readonly StaleNotification[];
-    /**
-     * Ids of update or delete targets in this commit that matched no rows, because
-     * the row does not exist or is outside the caller's organization. Present and
-     * non-empty only when a write missed. The typed resource wrappers turn this into
-     * an `AbloNotFoundError`; a raw `commits.create` caller can inspect it directly.
-     */
-    readonly missingIds?: readonly string[];
-}
+/** Public projection inferred from the canonical runtime schema. */
+export type CommitReceipt = ClientCommitReceipt;
 export interface CommitResource {
     create(options: CommitCreateOptions): Promise<CommitReceipt>;
 }
@@ -131,6 +116,8 @@ export interface ModelMutationOptions extends ClaimedOptions {
     readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
     readonly wait?: CommitWait;
     readonly claim?: Claim | ClaimOptions | null;
+    /** Fencing token (Option B) from the claim; server-validated at commit. */
+    readonly fenceToken?: number | null;
 }
 /**
  * The stateless HTTP claim surface. Most code puts a `claim` directly on the write

package/dist/client/schemaConfig.js

@@ -172,5 +172,10 @@ export function deriveConfigFromSchema(schema) {
         // schema the server currently has active. The server and the `ablo push`
         // command compute this same hash.
         expectedSchemaHash: schemaHash(schema),
+        // For a projection (`selectModels`/`omitModels`), also carry the full source
+        // schema's hash. The drift check accepts a server match on either hash, so a
+        // subset client stays quiet against a server running its full source schema.
+        // Undefined for a directly-authored schema — plain equality applies there.
+        expectedSourceSchemaHash: schema.sourceSchemaHash,
     };
 }

package/dist/client/writeOptionsSchema.d.ts

@@ -34,6 +34,7 @@ export declare const writeOptionsSchema: z.ZodObject<{
         overwrite: "overwrite";
         notify: "notify";
     }>>>;
+    fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     claim: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         id: z.ZodString;
     }, z.core.$loose>]>>>;

package/dist/client/writeOptionsSchema.js

@@ -17,6 +17,7 @@
  */
 import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
+import { commitStatusSchema } from '../wire/commit.js';
 export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
 export const writeOptionsSchema = z.object({
     /** Idempotency key the server records in `mutation_log` to make retries
@@ -25,11 +26,16 @@ export const writeOptionsSchema = z.object({
     /** Human-readable audit tag, persisted to `mutation_log.label`. */
     label: z.string().max(255).optional(),
     /** Resolve when queued locally (default) or once the server confirms. */
-    wait: z.enum(['queued', 'confirmed']).optional(),
+    wait: commitStatusSchema.optional(),
     /** Stale guard: the sync watermark the caller's reasoning was based on. */
     readAt: z.number().int().nonnegative().nullish(),
     /** What the server does when the target moved past `readAt`. */
     onStale: onStaleModeSchema.nullish(),
+    /** The held claim's fencing token (Option B), sourced from the claim handle
+     *  rather than set by hand; the server validates it against the entity's
+     *  high-water. Kept in the schema so it stays aligned with `MutationOptions`
+     *  (the drift guard below) and a malformed token is rejected at the boundary. */
+    fenceToken: z.number().nullish(),
     /** The claim this write belongs to — either a claim id, or a live claim
      *  handle whose `release`/`revoke` functions are preserved untouched. */
     claim: z.union([z.string(), z.looseObject({ id: z.string() })]).nullish(),
@@ -56,5 +62,8 @@ export function assertWriteOptions(value, context) {
         ...(path ? { param: path } : {}),
     });
 }
-const _writeOptionsContractInSync = [true, true];
+const _writeOptionsContractInSync = [
+    true,
+    true,
+];
 void _writeOptionsContractInSync;

package/dist/client/wsMutationExecutor.d.ts

@@ -4,8 +4,9 @@
  * commit time because it does not exist yet when the executor is created. A
  * client wires this up automatically unless you supply your own executor.
  */
-import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
+import type { ReadDependency } from '../coordination/schema.js';
 import type { MutationExecutor, MutationOperation } from '../interfaces/index.js';
+import type { CommitAck } from '../sync/commitFrames.js';
 /**
  * Creates the default mutation executor, which sends each change as a `commit`
  * frame over the sync engine's own WebSocket. The engine owns its socket, so
@@ -22,8 +23,5 @@ import type { MutationExecutor, MutationOperation } from '../interfaces/index.js
  * generation below exists only for direct, one-shot executor consumers.
  */
 export declare function createDefaultMutationExecutor(getWs: () => {
-    sendCommit?: (operations: readonly MutationOperation[], clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null) => Promise<{
-        lastSyncId: number;
-        notifications?: StaleNotification[];
-    }>;
+    sendCommit?: (operations: readonly MutationOperation[], clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null) => Promise<CommitAck>;
 } | null): MutationExecutor;

package/dist/coordination/schema.d.ts

@@ -196,11 +196,11 @@ export declare const claimStatusSchema: z.ZodEnum<{
 export type ClaimStatus = z.infer<typeof claimStatusSchema>;
 export declare const wireClaimSummarySchema: z.ZodObject<{
     field: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
     entityType: z.ZodString;
     entityId: z.ZodString;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     claimId: z.ZodString;
-    reason: z.ZodString;
     declaredAt: z.ZodNumber;
     expiresAt: z.ZodNumber;
 }, z.core.$strip>;
@@ -214,11 +214,11 @@ export declare const claimErrorSchema: z.ZodObject<{
     heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
     heldByClaim: z.ZodOptional<z.ZodObject<{
         field: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
         entityType: z.ZodString;
         entityId: z.ZodString;
         meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         claimId: z.ZodString;
-        reason: z.ZodString;
         declaredAt: z.ZodNumber;
         expiresAt: z.ZodNumber;
     }, z.core.$strip>>;
@@ -228,7 +228,7 @@ export type ClaimError = z.infer<typeof claimErrorSchema>;
 /**
  * A declared, pending-mutation claim — the unit broadcast inside a presence
  * frame's `activeClaims`. The client supplies the descriptive `targetRef`
- * fields, an explanatory `reason`, and a chosen `claimId`; the server stamps
+ * fields, a `description` of the work, and a chosen `claimId`; the server stamps
  * `declaredAt` and `expiresAt` and may set `status` and `error`. Those last
  * two are optional, so one shape serves both the server, which sets them, and
  * the leaner SDK view, which reads a claim without them.
@@ -246,7 +246,7 @@ export declare const wireClaimSchema: z.ZodObject<{
     field: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     claimId: z.ZodString;
-    reason: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
     declaredAt: z.ZodNumber;
     expiresAt: z.ZodNumber;
     status: z.ZodOptional<z.ZodEnum<{
@@ -255,6 +255,7 @@ export declare const wireClaimSchema: z.ZodObject<{
         expired: "expired";
         canceled: "canceled";
     }>>;
+    fenceToken: z.ZodOptional<z.ZodNumber>;
     error: z.ZodOptional<z.ZodObject<{
         code: z.ZodString;
         message: z.ZodOptional<z.ZodString>;
@@ -263,11 +264,11 @@ export declare const wireClaimSchema: z.ZodObject<{
         heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
         heldByClaim: z.ZodOptional<z.ZodObject<{
             field: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
             entityType: z.ZodString;
             entityId: z.ZodString;
             meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             claimId: z.ZodString;
-            reason: z.ZodString;
             declaredAt: z.ZodNumber;
             expiresAt: z.ZodNumber;
         }, z.core.$strip>>;
@@ -296,11 +297,11 @@ export declare const claimRejectionSchema: z.ZodObject<{
     heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
     heldByClaim: z.ZodOptional<z.ZodObject<{
         field: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
         entityType: z.ZodString;
         entityId: z.ZodString;
         meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         claimId: z.ZodString;
-        reason: z.ZodString;
         declaredAt: z.ZodNumber;
         expiresAt: z.ZodNumber;
     }, z.core.$strip>>;
@@ -373,7 +374,6 @@ export declare const modelClaimSchema: z.ZodReadonly<z.ZodObject<{
         agent: "agent";
         system: "system";
     }>>;
-    reason: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     field: z.ZodOptional<z.ZodString>;
     status: z.ZodOptional<z.ZodEnum<{
@@ -382,6 +382,7 @@ export declare const modelClaimSchema: z.ZodReadonly<z.ZodObject<{
     }>>;
     position: z.ZodOptional<z.ZodNumber>;
     expiresAt: z.ZodNumber;
+    fenceToken: z.ZodOptional<z.ZodNumber>;
     target: z.ZodReadonly<z.ZodObject<{
         model: z.ZodString;
         id: z.ZodString;
@@ -399,9 +400,10 @@ export declare const modelClaimSchema: z.ZodReadonly<z.ZodObject<{
 export type ModelClaim = z.infer<typeof modelClaimSchema>;
 /**
  * The `claim_begin` payload a client sends. It carries the descriptive target
- * and reason, an optional duration hint, and the opt-in fair-queue flag. The
- * server stamps the lifecycle and timestamp fields, so they are not part of
- * this inbound shape — this is exactly what the server validates on ingest.
+ * and a `description` of the work, an optional duration hint, and the opt-in
+ * fair-queue flag. The server stamps the lifecycle and timestamp fields, so they
+ * are not part of this inbound shape — this is exactly what the server validates
+ * on ingest.
  */
 export declare const claimBeginPayloadSchema: z.ZodObject<{
     entityType: z.ZodString;
@@ -416,7 +418,7 @@ export declare const claimBeginPayloadSchema: z.ZodObject<{
     field: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     claimId: z.ZodString;
-    reason: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
     estimatedMs: z.ZodOptional<z.ZodNumber>;
     queue: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
@@ -579,6 +581,7 @@ export declare const commitOperationSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 export type CommitOperation = z.infer<typeof commitOperationSchema>;
 /**
@@ -663,7 +666,7 @@ export declare const presenceUpdateFrameSchema: z.ZodObject<{
         field: z.ZodOptional<z.ZodString>;
         meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         claimId: z.ZodString;
-        reason: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
         declaredAt: z.ZodNumber;
         expiresAt: z.ZodNumber;
         status: z.ZodOptional<z.ZodEnum<{
@@ -672,6 +675,7 @@ export declare const presenceUpdateFrameSchema: z.ZodObject<{
             expired: "expired";
             canceled: "canceled";
         }>>;
+        fenceToken: z.ZodOptional<z.ZodNumber>;
         error: z.ZodOptional<z.ZodObject<{
             code: z.ZodString;
             message: z.ZodOptional<z.ZodString>;
@@ -680,11 +684,11 @@ export declare const presenceUpdateFrameSchema: z.ZodObject<{
             heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
             heldByClaim: z.ZodOptional<z.ZodObject<{
                 field: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodString>;
                 entityType: z.ZodString;
                 entityId: z.ZodString;
                 meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                 claimId: z.ZodString;
-                reason: z.ZodString;
                 declaredAt: z.ZodNumber;
                 expiresAt: z.ZodNumber;
             }, z.core.$strip>>;

package/dist/coordination/schema.js

@@ -200,17 +200,30 @@ export const claimStatusSchema = z.enum([
 ]);
 const wireClaimBaseSchema = targetRefSchema.extend({
     claimId: z.string(),
-    /** Human-readable phase: 'editing' | 'reviewing' | 'forecasting' … */
-    reason: z.string(),
+    /**
+     * Peer-visible description of the work being done (`'rewriting the risk
+     * section to match Q3'`). The server stamps a default when a frame carries
+     * none.
+     */
+    description: z.string().optional(),
     /** Server-stamped declaration time (epoch ms). */
     declaredAt: z.number(),
     /** Server-computed TTL deadline (epoch ms). Readers treat as advisory. */
     expiresAt: z.number(),
     status: claimStatusSchema.optional(),
+    /**
+     * The monotonic fencing token the server minted for this grant (Option B).
+     * Strictly increasing per entity across successive grants, so a write that
+     * carries it can be rejected at commit if a later holder already advanced the
+     * entity's high-water. Server-stamped on grant and never client-supplied;
+     * optional so every existing frame stays valid and a token-less write is
+     * simply not fence-checked.
+     */
+    fenceToken: z.number().optional(),
 });
 export const wireClaimSummarySchema = wireClaimBaseSchema.pick({
     claimId: true,
-    reason: true,
+    description: true,
     declaredAt: true,
     expiresAt: true,
     entityType: true,
@@ -234,7 +247,7 @@ export const claimErrorSchema = z.object({
 /**
  * A declared, pending-mutation claim — the unit broadcast inside a presence
  * frame's `activeClaims`. The client supplies the descriptive `targetRef`
- * fields, an explanatory `reason`, and a chosen `claimId`; the server stamps
+ * fields, a `description` of the work, and a chosen `claimId`; the server stamps
  * `declaredAt` and `expiresAt` and may set `status` and `error`. Those last
  * two are optional, so one shape serves both the server, which sets them, and
  * the leaner SDK view, which reads a claim without them.
@@ -295,25 +308,30 @@ export const modelClaimSchema = z
     id: z.string(),
     actor: z.string(),
     participantKind: wireParticipantKindSchema,
-    /** Human-readable phase (`'editing'`). */
-    reason: z.string(),
+    /** Peer-visible description of the work (`'rewriting the risk section'`).
+     *  Optional: a claim may be declared without one. */
     description: z.string().optional(),
     field: z.string().optional(),
     status: z.enum(['active', 'queued']).optional(),
     position: z.number().optional(),
     expiresAt: z.number(),
+    /** The grant's fencing token (Option B), present on a claim you hold. */
+    fenceToken: z.number().optional(),
     target: modelTargetSchema,
 })
     .readonly();
 /**
  * The `claim_begin` payload a client sends. It carries the descriptive target
- * and reason, an optional duration hint, and the opt-in fair-queue flag. The
- * server stamps the lifecycle and timestamp fields, so they are not part of
- * this inbound shape — this is exactly what the server validates on ingest.
+ * and a `description` of the work, an optional duration hint, and the opt-in
+ * fair-queue flag. The server stamps the lifecycle and timestamp fields, so they
+ * are not part of this inbound shape — this is exactly what the server validates
+ * on ingest.
  */
 export const claimBeginPayloadSchema = targetRefSchema.extend({
     claimId: z.string(),
-    reason: z.string(),
+    /** Peer-visible description of the work. The server stamps `'editing'` when a
+     *  frame carries none. */
+    description: z.string().optional(),
     /** Hint for `expiresAt`; the server caps it. */
     estimatedMs: z.number().optional(),
     /**
@@ -481,6 +499,14 @@ 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 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
+     * server checks it against the entity's persisted high-water and rejects a
+     * stale token. Absent (nullish) on every unclaimed write — those are governed
+     * by version-CAS and the Option A blind-write guard, unchanged.
+     */
+    fenceToken: z.number().nullish(),
 });
 // ─────────────────────────────────────────────────────────────────────────
 //  Layer 1 — presence (observation only; it never enforces)

package/dist/errorCodes.d.ts

@@ -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 declare const ERROR_CONTRACT_VERSION = "2026-07-03";
+export declare const ERROR_CONTRACT_VERSION = "2026-07-15";
 /** A coarse grouping of error codes, used to organize metrics and documentation. */
 export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | 'bootstrap' | 'transport' | 'rate_limit' | 'server' | 'client';
 /**
@@ -138,10 +138,7 @@ export declare const ERROR_CODES: {
     readonly jwt_org_membership_denied: ErrorCodeSpec;
     readonly file_upload_auth_required: ErrorCodeSpec;
     readonly browser_apikey_blocked: ErrorCodeSpec;
-    readonly browser_database_url_blocked: ErrorCodeSpec;
-    readonly datasource_registration_failed: ErrorCodeSpec;
     readonly datasource_connection_unsupported: ErrorCodeSpec;
-    readonly datasource_direct_deprecated: ErrorCodeSpec;
     readonly capability_scope_denied: ErrorCodeSpec;
     readonly issuer_register_forbidden: ErrorCodeSpec;
     readonly capability_invalid: ErrorCodeSpec;
@@ -157,6 +154,7 @@ export declare const ERROR_CODES: {
     readonly byo_host_not_allowed: ErrorCodeSpec;
     readonly claim_conflict: ErrorCodeSpec;
     readonly claim_lost: ErrorCodeSpec;
+    readonly fence_token_stale: ErrorCodeSpec;
     readonly entity_claimed: ErrorCodeSpec;
     readonly malformed_claim: ErrorCodeSpec;
     readonly malformed_subscription: ErrorCodeSpec;
@@ -168,6 +166,8 @@ export declare const ERROR_CODES: {
     readonly contention_exhausted: ErrorCodeSpec;
     readonly update_aborted: ErrorCodeSpec;
     readonly idempotency_conflict: ErrorCodeSpec;
+    readonly idempotency_key_expired: ErrorCodeSpec;
+    readonly source_transport_pinned: ErrorCodeSpec;
     readonly idempotency_key_too_long: ErrorCodeSpec;
     readonly write_options_invalid: ErrorCodeSpec;
     readonly source_operation_id_required: ErrorCodeSpec;
@@ -236,9 +236,12 @@ export declare const ERROR_CODES: {
     readonly exchange_malformed_response: ErrorCodeSpec;
     readonly exchange_network_error: ErrorCodeSpec;
     readonly source_network_error: ErrorCodeSpec;
+    readonly source_unreachable: ErrorCodeSpec;
+    readonly data_source_blocked: ErrorCodeSpec;
     readonly identity_network_error: ErrorCodeSpec;
     readonly commit_no_result: ErrorCodeSpec;
     readonly commit_failed: ErrorCodeSpec;
+    readonly replication_lag_timeout: ErrorCodeSpec;
     readonly commit_offline_grace_expired: ErrorCodeSpec;
     readonly queue_too_deep: ErrorCodeSpec;
     readonly flush_timeout: ErrorCodeSpec;
@@ -308,6 +311,8 @@ export declare const ERROR_CODES: {
     readonly invalid_id: ErrorCodeSpec;
     readonly unknown_model: ErrorCodeSpec;
     readonly model_not_tenant_scoped: ErrorCodeSpec;
+    readonly source_tenancy_not_enforced: ErrorCodeSpec;
+    readonly model_not_provisioned: ErrorCodeSpec;
     readonly schema_table_invalid: ErrorCodeSpec;
     readonly schema_scope_invalid: ErrorCodeSpec;
     readonly entity_fetch_failed: ErrorCodeSpec;

package/dist/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-03';
+export const ERROR_CONTRACT_VERSION = '2026-07-15';
 /**
  * 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
@@ -125,15 +125,12 @@ export const ERROR_CODES = {
     jwt_org_membership_denied: wire('auth', 403, false, "The bearer JWT's subject is not an active member of the organization in its `org_id` claim (removed, suspended, or the claim does not match a membership)."),
     file_upload_auth_required: wire('auth', 401, false, 'File uploads require an authenticated session. Sign in and retry.'),
     browser_apikey_blocked: client('auth', 'A raw API key was used from a browser, where anyone can read it. Keep secret keys server-side and hand the browser a short-lived ephemeral key instead.'),
-    browser_database_url_blocked: client('auth', 'A database connection string was used from a browser context. It carries database credentials, so it must stay server-side.'),
-    datasource_registration_failed: client('auth', 'The provided `databaseUrl` could not be registered as a data source. Check that the connection string is valid and the database is reachable.'),
     datasource_connection_unsupported: wire('validation', 400, false, 'This deployment does not accept direct connection-string data sources. Register a signed Data Source endpoint instead.'),
-    datasource_direct_deprecated: wire('validation', 410, false, 'The direct (connection string) datasource is deprecated. Register a signed Data Source endpoint instead — your app owns the write and your credentials never leave it.'),
     // ── permission / capability (403) ──────────────────────────────────
     capability_scope_denied: wire('capability', 403, false, 'This action falls outside the scope granted to the connection, so it was denied.'),
     issuer_register_forbidden: wire('permission', 403, false, 'Registering a trusted issuer requires a secret (`sk_`) API key. The key presented is not a secret key.'),
     capability_invalid: wire('capability', 403, 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`, or construct the client with `databaseUrl` using your test key.'),
+    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, true, "The org's registered database could not be resolved or dialed. Ablo never falls back to shared storage for a dedicated tenant — retry, and check the datasource status if it persists."),
     database_role_cannot_enforce_rls: wire('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.'),
     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.'),
@@ -153,6 +150,7 @@ export const ERROR_CODES = {
     // behind the holder (`ablo.<model>.claim`), or re-read and rebase.
     claim_conflict: wire('claim', 409, false, 'Another participant holds a claim on this row, so the write was rejected. Take a claim with `ablo.<model>.claim` to queue fairly behind the holder, or re-read and rebase.'),
     claim_lost: wire('claim', 409, false, 'The claim held on this row was lost before the write could apply. Re-acquire the claim and retry.'),
+    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.'),
     malformed_subscription: wire('validation', 400, false, 'The `update_subscription` payload was malformed; expected `{ syncGroups: string[] }`.'),
@@ -173,6 +171,8 @@ export const ERROR_CODES = {
     contention_exhausted: client('conflict', 'A functional update kept losing to concurrent writes and exhausted its reconcile budget. Back off and retry, raise `retries`, or move the row to the WebSocket transport.'),
     update_aborted: client('conflict', 'The functional update was aborted via its `AbortSignal` before the write landed; nothing was written.'),
     idempotency_conflict: wire('conflict', 409, false, 'This `Idempotency-Key` was already used with a different request body. Reuse a key only to retry an identical request; otherwise generate a new one.'),
+    idempotency_key_expired: wire('conflict', 409, false, 'This idempotency key belongs to an expired retained source intent and cannot be executed again safely. Use a new key only for a genuinely new write.'),
+    source_transport_pinned: wire('conflict', 409, false, 'An earlier attempt under this idempotency key was pinned to a different source transport. Restore that route and retry the same key; Ablo will not switch a possibly committed write.'),
     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.'),
@@ -262,9 +262,12 @@ export const ERROR_CODES = {
     exchange_malformed_response: wire('transport', 502, true, 'The credential exchange returned a response that could not be parsed. Retrying may succeed.'),
     exchange_network_error: wire('transport', 503, true, 'A network error interrupted the credential exchange. Check connectivity and retry.'),
     source_network_error: wire('transport', 503, true, 'A network error occurred while talking to the data source. Check connectivity and retry.'),
+    source_unreachable: wire('transport', 503, true, 'Ablo could not safely reach the registered direct data source before completing the write. The write remains pinned to direct; retry the same idempotency key after connectivity recovers.'),
+    data_source_blocked: wire('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.'),
     identity_network_error: wire('transport', 503, true, 'A network error occurred while resolving your identity. Check connectivity and retry.'),
     commit_no_result: wire('transport', 504, true, 'The commit was sent, but no result frame arrived, so its outcome is unknown. It is safe to retry.'),
     commit_failed: wire('transport', 500, true, 'The commit reached the server but failed to apply. Retrying may succeed.'),
+    replication_lag_timeout: wire('transport', 504, true, "The data source accepted the write, but its correlated authoritative source delta did not arrive before the confirmation deadline. The write may still materialize; retry with the same idempotency key or wait for source ingestion to recover."),
     commit_offline_grace_expired: wire('transport', 503, false, 'The offline grace window expired before this commit could be sent, so it was not applied. Re-apply the change once the connection returns.'),
     queue_too_deep: wire('transport', 503, true, 'The transaction queue is over its depth limit, so new writes are being rejected until it drains. Retry shortly.'),
     flush_timeout: wire('transport', 504, true, 'Flushing the transaction queue timed out before every pending write was sent. Retry once connectivity stabilizes.'),
@@ -346,6 +349,8 @@ export const ERROR_CODES = {
     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."),
+    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."),
     entity_fetch_failed: wire('server', 500, true, 'The server failed to fetch the requested entity. It is safe to retry.'),

package/dist/errors.js

@@ -226,11 +226,6 @@ export class AbloContentionError extends AbloError {
         this.attempts = attempts;
     }
 }
-function claimReason(claim) {
-    if (!claim)
-        return undefined;
-    return claim.reason;
-}
 function claimDescription(claim) {
     if (!claim)
         return undefined;
@@ -238,6 +233,8 @@ function claimDescription(claim) {
         return claim.description;
     }
     const meta = 'target' in claim ? claim.target?.meta ?? claim.meta : claim.meta;
+    // Fall back through the meta carrier so a frame that stashed its description
+    // there still renders its holder's work.
     return descriptionFromMeta(meta);
 }
 function claimExpiresAt(claim) {
@@ -256,20 +253,18 @@ function secondsUntil(ms, now = Date.now()) {
 }
 export function formatClaimedErrorMessage(args) {
     const holder = claimActor(args.claim, args.heldBy);
-    const reason = claimReason(args.claim);
     const description = claimDescription(args.claim);
     const expiresIn = secondsUntil(claimExpiresAt(args.claim));
-    if (!holder && !reason && !description) {
+    if (!holder && !description) {
         return args.fallback ?? `Model row is claimed: ${args.targetLabel}.`;
     }
     const actor = holder ?? 'another participant';
-    const reasonPart = reason ? ` (${reason})` : '';
     const descriptionPart = description ? `: ${description}` : '';
     const expiresPart = expiresIn !== undefined ? ` - expires in ${expiresIn}s` : '';
     const policyPart = args.policyReason
         ? ` Policy reason: ${args.policyReason}.`
         : '';
-    return `Claimed by ${actor}${reasonPart}${descriptionPart}${expiresPart} on ${args.targetLabel}.${policyPart}`;
+    return `Claimed by ${actor}${descriptionPart}${expiresPart} on ${args.targetLabel}.${policyPart}`;
 }
 /**
  * The target entity is currently claimed by another participant and the caller

package/dist/index.d.ts

@@ -63,6 +63,10 @@ export type { AbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope,
  * the next major release because it was explicitly documented in 0.20.1.
  */
 export type { HeldClaim } from './client/Ablo.js';
+/** The resolved value of the row-free `ablo.<model>.claim(id)` overload — a
+ *  held lease on a key whose row Ablo does not hold (a {@link HeldClaim} with
+ *  no `.data`). */
+export type { HeldLease } from './client/Ablo.js';
 export type { AbloPersistence } from './client/persistence.js';
 export { durableWritesConfigSchema, durableWriteStoreSchema, pendingWriteSchema, } from './transactions/durableWriteStore.js';
 export type { DurableWritesConfig, DurableWriteStore, PendingWrite, } from './transactions/durableWriteStore.js';