@abloatai/ablo 0.13.0 → 0.15.0

package/dist/client/auth.js

@@ -54,6 +54,14 @@ export function resolveDatabaseUrl(input) {
  * explicit option instead of flipping their mode for them. Warns once per process
  * so it never spams, and falls back to `console.warn` when no logger is supplied
  * (the `transport: 'api'` client has none).
+ *
+ * Suppressed entirely on the hosted/token path: if an `apiKey` resolves (option
+ * or `ABLO_API_KEY` env), the caller has chosen the hosted capability-token /
+ * Data Source transport, which is mutually exclusive with direct `databaseUrl`
+ * mode. A `DATABASE_URL` sitting in that environment is unrelated infra (Prisma,
+ * Drizzle, the sync-server) — never an omitted option — so nudging would be a
+ * false positive. This is the first-party hosted app's exact shape, where the
+ * stray nudge otherwise reaches end-user desktop logs.
  */
 let warnedDatabaseUrlEnvIgnored = false;
 export function warnIfDatabaseUrlEnvIgnored(input, warn) {
@@ -61,6 +69,9 @@ export function warnIfDatabaseUrlEnvIgnored(input, warn) {
         return;
     if (input.options.databaseUrl != null)
         return;
+    // Hosted/token path → DATABASE_URL is unrelated infra, not an omitted option.
+    if (resolveApiKey(input) != null)
+        return;
     const envUrl = input.env.DATABASE_URL;
     if (typeof envUrl !== 'string' || envUrl.length === 0)
         return;

package/dist/client/createModelProxy.d.ts

@@ -109,8 +109,13 @@ export interface ModelCollaboration<T> {
      * `null` when the target is free. The wiring site computes it because
      * only it knows the local participant id (needed to distinguish "I
      * hold it" from "someone else holds it").
+     *
+     * Named `state` to match the public `ablo.<model>.claim.state({ id })` read —
+     * one verb for "who holds this" across every claim surface; the only
+     * difference is this internal contract takes an explicit `{ model, id }`
+     * target because it isn't bound to a single model.
      */
-    observe(target: {
+    state(target: {
         model: string;
         id: string;
     }): Claim | null;
@@ -202,10 +207,11 @@ export interface ClaimTargetOptions<T = Record<string, unknown>> {
      * work-distribution dedup ("if someone else has this job, skip it") where
      * waiting would mean double-processing.
      *
-     * Named `queue` to match every other claim surface (low-level
-     * `claims.claim`, HTTP `claim.create`, and the wire). The high-level typed
-     * claim defaults it ON because it serializes writers; the low-level lease
-     * and HTTP default it OFF — they return/resolve immediately and can't
+     * Named `queue` to match every other claim surface — `ablo.<model>.claim`
+     * on both the WS and HTTP clients (take-a-claim is the callable `claim({ id
+     * })` on both; the HTTP reads are just awaited) and the wire. The high-level
+     * typed claim defaults it ON because it serializes writers; the low-level
+     * lease and HTTP default it OFF — they return/resolve immediately and can't
      * transparently wait for a grant.
      */
     queue?: boolean;
@@ -276,9 +282,18 @@ export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
  * handle. `state`, `queue`, and `reorder` are coordination reads/scheduler
  * controls for UI and operators.
  */
-export interface ClaimApi<T> {
-    /** Take a claim and get an explicit held-work handle back. */
-    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
+/**
+ * Coordination reads + scheduler controls on a claim namespace, in their
+ * REACTIVE (synchronous) form — `state`/`queue`/`reorder` resolve against the
+ * local pool with no round-trip, which is what lets `useAblo((ablo) =>
+ * ablo.x.claim.state({ id }))` read coordination state inside a React render.
+ *
+ * This is the single source of truth for the claim read surface: the stateless
+ * HTTP client exposes the *awaited* projection of EXACTLY these methods
+ * (`HttpClaimApi` in `Ablo.ts`, derived via {@link AwaitedClaimMethod}), so the
+ * two transports can never drift — edit a signature here and HTTP follows.
+ */
+export interface ClaimReadApi<T = Record<string, unknown>> {
     /**
      * Current holder for a row, or `null` when free. Use this for UI badges and
      * preflight checks, not for the normal write path.
@@ -299,6 +314,16 @@ export interface ClaimApi<T> {
     /** Release a manual claim handle early. Single-write claims auto-release. */
     release(params: ClaimLookupParams<T> | ClaimHandle<T>): Promise<void>;
 }
+/**
+ * The awaited form of a claim method: a synchronous return becomes a `Promise`,
+ * an already-async one (`release`) is left untouched. Used to derive the
+ * stateless HTTP claim surface from the reactive {@link ClaimReadApi}.
+ */
+export type AwaitedClaimMethod<F> = F extends (...args: infer A) => infer R ? R extends Promise<unknown> ? (...args: A) => R : (...args: A) => Promise<R> : F;
+export interface ClaimApi<T> extends ClaimReadApi<T> {
+    /** Take a claim and get an explicit held-work handle back. */
+    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
+}
 export interface ModelRetrieveParams extends ServerRetrieveOptions {
     readonly id: string;
 }

package/dist/client/createModelProxy.js

@@ -141,7 +141,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // Is someone ELSE already on this target? Read the local coordination
         // snapshot up front — it decides whether we'll need to re-read after the
         // claim (a free / already-mine target can't have changed under us).
-        const held = collaboration.observe({ model: wireModel, id });
+        const held = collaboration.state({ model: wireModel, id });
         const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
         const failFast = options?.queue === false;
         // Fail-fast (`queue: false`): if another participant already holds it,
@@ -215,7 +215,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         const snapshot = collaboration.createSnapshot(schemaKey, id);
         const reason = options?.reason ?? 'editing';
         // The self-claim's `EntityRef` mirrors what a peer's `claim.state` would
-        // report (`observe` maps `held.target.model` → `type`), so a holder and a
+        // report (`state` maps `held.target.model` → `type`), so a holder and a
         // peer see the SAME target.type for one row — the wire model token.
         const selfTarget = {
             type: wireModel,
@@ -271,7 +271,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             // presence. Soft + fire-and-forget — never blocks or rejects the read.
             void collaboration?.enterScope?.({ [schemaKey]: params.id });
             // Self-awareness: the server excludes a holder's OWN presence frames and
-            // the client skips them, so `observe` returns null for a row WE hold.
+            // the client skips them, so `state` returns null for a row WE hold.
             // Synthesize the active claim for self from the stored lease so the
             // holder sees its own claim (the JSDoc contract on `claim.state`).
             const own = activeClaims.get(params.id);
@@ -287,7 +287,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     expiresAt: own.expiresAt,
                 };
             }
-            return collaboration?.observe({ model: wireModel, id: params.id }) ?? null;
+            return collaboration?.state({ model: wireModel, id: params.id }) ?? null;
         },
         queue(params) {
             return {

package/dist/client/sessionMint.js

@@ -40,6 +40,7 @@ export async function mintSession(params, ctx) {
             apiKey,
             baseUrl,
             userId: params.user.id,
+            ...(params.organizationId ? { organizationId: params.organizationId } : {}),
             ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
             ttlSeconds: params.ttlSeconds ?? 900,
             ...(ctx.fetch ? { fetch: ctx.fetch } : {}),

package/dist/client/writeOptionsSchema.d.ts

@@ -17,9 +17,8 @@
 import { z } from 'zod';
 export declare const onStaleModeSchema: z.ZodEnum<{
     reject: "reject";
-    force: "force";
-    flag: "flag";
-    merge: "merge";
+    overwrite: "overwrite";
+    notify: "notify";
 }>;
 export declare const writeOptionsSchema: z.ZodObject<{
     idempotencyKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -31,9 +30,8 @@ export declare const writeOptionsSchema: z.ZodObject<{
     readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         reject: "reject";
-        force: "force";
-        flag: "flag";
-        merge: "merge";
+        overwrite: "overwrite";
+        notify: "notify";
     }>>>;
     claim: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         id: z.ZodString;

package/dist/client/writeOptionsSchema.js

@@ -16,7 +16,7 @@
  */
 import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
-export const onStaleModeSchema = z.enum(['reject', 'force', 'flag', 'merge']);
+export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
 export const writeOptionsSchema = z.object({
     /** Server-side mutation_log cache key; `null` opts out of retry-safety. */
     idempotencyKey: z.string().min(1).max(255).nullish(),

package/dist/coordination/schema.d.ts

@@ -82,15 +82,19 @@ export declare const targetRefSchema: z.ZodObject<{
 export type TargetRef = z.infer<typeof targetRefSchema>;
 /**
  * Mode applied when a write's snapshot watermark (`readAt`) is older than the
- * target row's latest delta. `'reject'` is the default whenever `readAt` is
- * present. `'flag'` and `'merge'` are reserved — the wire accepts them, the
- * server does not yet enforce them.
+ * target row's latest delta. Three dispositions, split by the non-coercion
+ * convention (see docs/concurrency-convention.md):
+ *   • `notify`    — NON-COERCIVE: hold the write, return a `StaleNotification`
+ *                   with the current value; the actor (agent or human) resolves.
+ *   • `reject`    — coercive escape hatch: throw `AbloStaleContextError`
+ *                   (default when `readAt` is present).
+ *   • `overwrite` — coercive escape hatch: apply blindly last-writer-wins, no
+ *                   signal.
  */
 export declare const onStaleModeSchema: z.ZodEnum<{
     reject: "reject";
-    force: "force";
-    flag: "flag";
-    merge: "merge";
+    overwrite: "overwrite";
+    notify: "notify";
 }>;
 export type OnStaleMode = z.infer<typeof onStaleModeSchema>;
 /**
@@ -103,13 +107,88 @@ export declare const writeGuardSchema: z.ZodObject<{
     readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         reject: "reject";
-        force: "force";
-        flag: "flag";
-        merge: "merge";
+        overwrite: "overwrite";
+        notify: "notify";
     }>>>;
     bypass: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type WriteGuard = z.infer<typeof writeGuardSchema>;
+/**
+ * The advisory signal returned to a committer whose write hit a stale-context
+ * conflict under `onStale: 'notify'` — the engine's answer to "the typed value
+ * you reasoned against changed while you were away."
+ *
+ * Philosophy: NON-COERCION. The engine's job is to surface the truthful current
+ * state and let the intelligent actor — agent OR human — decide what to do; it
+ * does NOT force an outcome. The two *forcing* dispositions are `reject`
+ * (force-abort, discards the work) and `overwrite` (force-clobber). This
+ * notification is the non-coercive path: instead of throwing, the server hands
+ * back the conflicting field's *current* value as data so the actor can solve
+ * it. The CLAIM is the prospective form of the same principle (coordinate
+ * before acting); this notification is the in-flight form (here's what changed,
+ * you resolve). Both an agent reasoning over the change and a human watching the
+ * row are valid resolvers. (Cf. CoAgent/MTPO, arXiv:2606.15376, which bets the
+ * resolver is specifically an LLM; Ablo's bet is the same non-coercion, actor
+ * left to agent or human.) Rides on the commit ack alongside `lastSyncId`; an
+ * empty/absent array means no premise moved.
+ *
+ * Only `notify` produces this: the conflicting op was HELD (not written), and
+ * the actor reconciles against `currentValues` and re-commits. (`reject` throws,
+ * `overwrite` is silent — neither notifies.)
+ */
+export declare const staleNotificationSchema: z.ZodObject<{
+    object: z.ZodOptional<z.ZodLiteral<"stale_notification">>;
+    model: z.ZodString;
+    id: z.ZodString;
+    readAt: z.ZodNumber;
+    observedSyncId: z.ZodNumber;
+    conflictingFields: z.ZodArray<z.ZodString>;
+    currentValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    writtenBy: z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    group: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StaleNotification = z.infer<typeof staleNotificationSchema>;
+/**
+ * A read DEPENDENCY declared on a commit — the STORM "did anything I looked at
+ * change?" layer (vs. the write-target check that only validates the rows being
+ * written). The server re-runs stale detection against each declared read at
+ * `readAt`; a moved premise fires the entry's `onStale` disposition (default
+ * `reject`) over the WHOLE batch (`notify` holds every write + notifies;
+ * `reject` aborts; `overwrite` proceeds silently). Two granularities, choice:
+ *
+ *   • ROW   — `{ model, id, readAt, fields? }`: did this specific row (optionally
+ *             these fields) change? The literal STORM/per-object premise.
+ *   • GROUP — `{ group, readAt }`: did ANYTHING in this sync group change? `group`
+ *             is a sync-group key like `deck:abc` or `slide:s1` — the same unit a
+ *             human/agent watches and claims. Coarser, and more Ablo-native.
+ */
+export declare const readDependencySchema: z.ZodUnion<readonly [z.ZodObject<{
+    model: z.ZodString;
+    id: z.ZodString;
+    readAt: z.ZodNumber;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    onStale: z.ZodOptional<z.ZodEnum<{
+        reject: "reject";
+        overwrite: "overwrite";
+        notify: "notify";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    group: z.ZodString;
+    readAt: z.ZodNumber;
+    onStale: z.ZodOptional<z.ZodEnum<{
+        reject: "reject";
+        overwrite: "overwrite";
+        notify: "notify";
+    }>>;
+}, z.core.$strip>]>;
+export type ReadDependency = z.infer<typeof readDependencySchema>;
 /**
  * Lifecycle of an claim — the Stripe `PaymentIntent.status` shape. Absent on
  * the wire ⇒ `'active'` (additive back-compat). The server stamps `'active'`
@@ -407,9 +486,8 @@ export declare const commitOperationSchema: z.ZodObject<{
     readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         reject: "reject";
-        force: "force";
-        flag: "flag";
-        merge: "merge";
+        overwrite: "overwrite";
+        notify: "notify";
     }>>>;
     bypass: z.ZodOptional<z.ZodBoolean>;
     type: z.ZodEnum<{

package/dist/coordination/schema.js

@@ -80,11 +80,16 @@ export const targetRefSchema = z.object({
 // ─────────────────────────────────────────────────────────────────────────
 /**
  * Mode applied when a write's snapshot watermark (`readAt`) is older than the
- * target row's latest delta. `'reject'` is the default whenever `readAt` is
- * present. `'flag'` and `'merge'` are reserved — the wire accepts them, the
- * server does not yet enforce them.
+ * target row's latest delta. Three dispositions, split by the non-coercion
+ * convention (see docs/concurrency-convention.md):
+ *   • `notify`    — NON-COERCIVE: hold the write, return a `StaleNotification`
+ *                   with the current value; the actor (agent or human) resolves.
+ *   • `reject`    — coercive escape hatch: throw `AbloStaleContextError`
+ *                   (default when `readAt` is present).
+ *   • `overwrite` — coercive escape hatch: apply blindly last-writer-wins, no
+ *                   signal.
  */
-export const onStaleModeSchema = z.enum(['reject', 'force', 'flag', 'merge']);
+export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
 /**
  * The optimistic guard carried on a commit operation. `readAt` is the
  * snapshot watermark from `context.capture` (null/absent ⇒ unguarded write).
@@ -96,6 +101,96 @@ export const writeGuardSchema = z.object({
     onStale: onStaleModeSchema.nullish(),
     bypass: z.boolean().optional(),
 });
+/**
+ * The advisory signal returned to a committer whose write hit a stale-context
+ * conflict under `onStale: 'notify'` — the engine's answer to "the typed value
+ * you reasoned against changed while you were away."
+ *
+ * Philosophy: NON-COERCION. The engine's job is to surface the truthful current
+ * state and let the intelligent actor — agent OR human — decide what to do; it
+ * does NOT force an outcome. The two *forcing* dispositions are `reject`
+ * (force-abort, discards the work) and `overwrite` (force-clobber). This
+ * notification is the non-coercive path: instead of throwing, the server hands
+ * back the conflicting field's *current* value as data so the actor can solve
+ * it. The CLAIM is the prospective form of the same principle (coordinate
+ * before acting); this notification is the in-flight form (here's what changed,
+ * you resolve). Both an agent reasoning over the change and a human watching the
+ * row are valid resolvers. (Cf. CoAgent/MTPO, arXiv:2606.15376, which bets the
+ * resolver is specifically an LLM; Ablo's bet is the same non-coercion, actor
+ * left to agent or human.) Rides on the commit ack alongside `lastSyncId`; an
+ * empty/absent array means no premise moved.
+ *
+ * Only `notify` produces this: the conflicting op was HELD (not written), and
+ * the actor reconciles against `currentValues` and re-commits. (`reject` throws,
+ * `overwrite` is silent — neither notifies.)
+ */
+export const staleNotificationSchema = z.object({
+    /** Stripe-style object tag — every returned object names its type. */
+    object: z.literal('stale_notification').optional(),
+    /** Model name of the conflicting row. */
+    model: z.string(),
+    /** Row id. */
+    id: z.string(),
+    /** The watermark the committer reasoned against (its `readAt`). */
+    readAt: z.number(),
+    /**
+     * Newest delta id on the row — the committer's new watermark. Re-capture
+     * context at/after this id to reconcile.
+     */
+    observedSyncId: z.number(),
+    /**
+     * Fields whose concurrent change collided with this write (intersection of
+     * the committer's written columns and a newer delta's `changed_fields`).
+     * Empty ⇒ a whole-entity change (CREATE/DELETE/legacy delta).
+     */
+    conflictingFields: z.array(z.string()),
+    /**
+     * Post-conflict live values of `conflictingFields` — the part a plain stale
+     * error never carried. Lets the LLM self-heal without a round-trip read.
+     */
+    currentValues: z.record(z.string(), z.unknown()),
+    /** Who wrote the conflicting delta. */
+    writtenBy: z.object({
+        kind: participantKindSchema,
+        id: z.string(),
+    }),
+    /**
+     * Set when this notification is for a GROUP read-dependency (e.g. `deck:abc`,
+     * `slide:s1`) rather than a single row — "something in the group you read
+     * changed." For a group notification `conflictingFields`/`currentValues` are
+     * empty (the change could span many rows); re-read the group at
+     * `observedSyncId` to reconcile. Absent ⇒ a row-scoped notification.
+     */
+    group: z.string().optional(),
+});
+/**
+ * A read DEPENDENCY declared on a commit — the STORM "did anything I looked at
+ * change?" layer (vs. the write-target check that only validates the rows being
+ * written). The server re-runs stale detection against each declared read at
+ * `readAt`; a moved premise fires the entry's `onStale` disposition (default
+ * `reject`) over the WHOLE batch (`notify` holds every write + notifies;
+ * `reject` aborts; `overwrite` proceeds silently). Two granularities, choice:
+ *
+ *   • ROW   — `{ model, id, readAt, fields? }`: did this specific row (optionally
+ *             these fields) change? The literal STORM/per-object premise.
+ *   • GROUP — `{ group, readAt }`: did ANYTHING in this sync group change? `group`
+ *             is a sync-group key like `deck:abc` or `slide:s1` — the same unit a
+ *             human/agent watches and claims. Coarser, and more Ablo-native.
+ */
+export const readDependencySchema = z.union([
+    z.object({
+        model: z.string(),
+        id: z.string(),
+        readAt: z.number(),
+        fields: z.array(z.string()).optional(),
+        onStale: onStaleModeSchema.optional(),
+    }),
+    z.object({
+        group: z.string(),
+        readAt: z.number(),
+        onStale: onStaleModeSchema.optional(),
+    }),
+]);
 // ─────────────────────────────────────────────────────────────────────────
 //  Layer 2 — PESSIMISTIC claim / claim-lease
 // ─────────────────────────────────────────────────────────────────────────

package/dist/errorCodes.d.ts

@@ -37,7 +37,7 @@ import { z } from 'zod';
  * code, a changed HTTP status, an envelope field. Emitted in `errors.json`
  * and on the `Ablo-Version` response header so a consumer can detect drift.
  */
-export declare const ERROR_CONTRACT_VERSION = "2026-06-13";
+export declare const ERROR_CONTRACT_VERSION = "2026-06-20";
 /** Coarse grouping for metrics dashboards and docs sectioning. */
 export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | 'claim' | 'bootstrap' | 'transport' | 'rate_limit' | 'server' | 'client';
 /**
@@ -239,8 +239,10 @@ export declare const ERROR_CODES: {
     readonly ws_not_ready: ErrorCodeSpec;
     readonly quota_exceeded: ErrorCodeSpec;
     readonly connection_limit_exceeded: ErrorCodeSpec;
+    readonly rate_limit_exceeded: ErrorCodeSpec;
     readonly internal_error: ErrorCodeSpec;
     readonly quota_lookup_failed: ErrorCodeSpec;
+    readonly rate_limiter_unavailable: ErrorCodeSpec;
     readonly turn_open_failed: ErrorCodeSpec;
     readonly turn_close_failed: ErrorCodeSpec;
     readonly invalid_options: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -37,7 +37,7 @@ import { z } from 'zod';
  * code, a changed HTTP status, an envelope field. Emitted in `errors.json`
  * and on the `Ablo-Version` response header so a consumer can detect drift.
  */
-export const ERROR_CONTRACT_VERSION = '2026-06-13';
+export const ERROR_CONTRACT_VERSION = '2026-06-20';
 /**
  * The closed taxonomy of *how a failure recovers* — one rung above the raw
  * `code`. Where `code` says **what** went wrong, `RecoveryClass` says **what
@@ -258,9 +258,18 @@ export const ERROR_CODES = {
     // ── quota / rate limit (429) ──────────────────────────────────────
     quota_exceeded: wire('rate_limit', 429, true, 'The organization exceeded its configured usage quota.'),
     connection_limit_exceeded: wire('rate_limit', 429, true, 'Too many concurrent WebSocket connections for this principal or organization. Close idle connections, or retry once others drain.'),
+    // Per-CREDENTIAL request-rate limit — the fast (RPS/burst) axis, distinct from
+    // the slow-axis `quota_exceeded` (org daily/monthly usage). Keyed per API key,
+    // so one noisy key backs off without affecting the rest of the org. The
+    // `Retry-After` header carries the bucket-refill delay.
+    rate_limit_exceeded: wire('rate_limit', 429, true, 'This API key is sending requests too quickly; slow down and retry after the indicated delay.'),
     // ── server (5xx) ───────────────────────────────────────────────────
     internal_error: wire('server', 500, true, 'An unexpected server error occurred.'),
     quota_lookup_failed: wire('server', 503, true, 'The quota decision could not be loaded.'),
+    // The per-key rate-limiter backend (Redis) was unreachable and the API is
+    // configured to FAIL CLOSED on that path, so the request was rejected rather
+    // than admitted unchecked. Retryable: the next attempt re-probes the backend.
+    rate_limiter_unavailable: wire('server', 503, true, 'The rate-limiter backend is unavailable and this endpoint is configured to fail closed; retry shortly.'),
     turn_open_failed: wire('server', 500, true, 'The agent turn failed to open.'),
     turn_close_failed: wire('server', 500, true, 'The agent turn failed to close cleanly.'),
     // ── client-only invariants (never serialized) ──────────────────────

package/dist/index.d.ts

@@ -57,6 +57,7 @@ export type { AbloPersistence } from './client/persistence.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
 export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
+export { createSourceConnector, type SourceConnector, type SourceConnectorOptions, type ConnectorStatus, } from './source/connector.js';
 export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
 export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 export type { CommitReceipt, RequiredCapability } from './errors.js';
@@ -67,6 +68,8 @@ export type { Environment, KeyPrefixEnvironment } from './environment.js';
 export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './client/writeOptionsSchema.js';
 export type { WriteOptionsInput } from './client/writeOptionsSchema.js';
 export type { WriteOptions, MutationOptions } from './interfaces/index.js';
+export { staleNotificationSchema, readDependencySchema } from './coordination/schema.js';
+export type { StaleNotification, ReadDependency } from './coordination/schema.js';
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
 export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, } from './surface.js';
 export type { ModelVerb, ListOptionKey, AbloOptionKey } from './surface.js';

package/dist/index.js

@@ -69,6 +69,10 @@ export default Ablo;
 // canonical, skip this entirely. Type counterparts live under
 // `Ablo.Source.*` (`Ablo.Source.Operation`, `Ablo.Source.Commit.Params`).
 export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
+// Reverse-channel connector: serve the Data Source `commit`/`load`/`list` leg
+// over an OUTBOUND WebSocket (localhost / locked-down VPC, no public inbound
+// URL). The dial-out counterpart to `createPushQueue` for the `events` leg.
+export { createSourceConnector, } from './source/connector.js';
 // Schema DSL is intentionally published from `@abloatai/ablo/schema`.
 // Keeping it out of the root import preserves one clean runtime surface:
 // `import Ablo from '@abloatai/ablo'`.
@@ -90,6 +94,11 @@ export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromK
 // (e.g. an agent tool's input schema). Runtime twin of `MutationOptions`,
 // drift-guarded at compile time.
 export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './client/writeOptionsSchema.js';
+// Notify-instead-of-abort signal: the value handed back to a committer whose
+// write hit a stale-context conflict under `onStale: 'notify' so its
+// agent can self-heal rather than discard work (see coordination/schema.ts and
+// docs/coordination.md → "Notify, do not abort").
+export { staleNotificationSchema, readDependencySchema } from './coordination/schema.js';
 // Storage-wedge detection — lets app shells render a recovery screen when the
 // IndexedDB backing store is stuck (see core/openIDBWithTimeout.ts).
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';

package/dist/interfaces/index.d.ts

@@ -5,6 +5,7 @@
  * Consumers implement them to wire in their own logging, observability,
  * GraphQL client, session handling, and analytics.
  */
+import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 export interface SyncLogger {
     debug(message: string, ...args: unknown[]): void;
     info(message: string, ...args: unknown[]): void;
@@ -140,6 +141,13 @@ export interface ModelDebugLoggerContract {
 /** Result of a successful `commit()` — server's sync cursor after the batch landed. */
 export interface CommitResult {
     lastSyncId: number;
+    /**
+     * Stale-context notifications (CoAgent/MTPO notify-instead-of-abort). Present
+     * only when a write guarded with `onStale: 'notify' collided with a
+     * concurrent change; the committer self-heals from these rather than
+     * receiving an `AbloStaleContextError`. See `StaleNotification`.
+     */
+    notifications?: StaleNotification[];
 }
 /**
  * Per-call knobs attached to any mutation. Mirrors Stripe's options
@@ -159,7 +167,7 @@ export interface MutationOptions {
     label?: string;
     wait?: 'queued' | 'confirmed';
     readAt?: number | null;
-    onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    onStale?: 'reject' | 'overwrite' | 'notify' | null;
     /** Claim-pin attribution: the id (or `{ id }`) of the claim this write
      *  belongs to. Distinct from the `claim` HANDLE on the model write params —
      *  this is the low-level reference the commit carries to bypass the holder's
@@ -174,6 +182,14 @@ export interface MutationOptions {
      * id). Kept optional for wire-compat; always `null` from the client.
      */
     causedByTaskId?: string | null;
+    /**
+     * Batch-level read dependencies (the STORM "did anything I looked at change?"
+     * layer). Each entry is a row (`{model,id,readAt,fields?}`) or a sync group
+     * (`{group,readAt}`) this write was premised on; the server validates none
+     * moved since `readAt` and fires the entry's `onStale` over the batch.
+     * Distinct from per-op `readAt` (which guards only the row being written).
+     */
+    reads?: ReadDependency[] | null;
 }
 /**
  * The `MutationOptions` subset carried per-write through the offline
@@ -208,7 +224,7 @@ export interface MutationOperation {
      */
     transactionId?: string;
     readAt?: number | null;
-    onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    onStale?: 'reject' | 'overwrite' | 'notify' | null;
     /**
      * Per-op idempotency + audit metadata. `idempotencyKey` doubles as
      * the `mutation_log.client_tx_id` cache key; `label` is persisted to

package/dist/policy/types.d.ts

@@ -39,6 +39,13 @@ export interface StaleContextConflict extends ConflictBase {
      * cosmetic field. See `docs/internal/per-field-conflict-detection.md`.
      */
     readonly conflictingFields?: readonly string[];
+    /**
+     * The committer's declared `onStale` intent for this op. The default policy
+     * honors it: `'notify'` → notify+hold, anything else → reject. A custom policy
+     * may override (e.g. gate notify on claim ownership). Absent ⇒ treat as
+     * `'reject'` (the unguarded-write default).
+     */
+    readonly requestedMode?: 'reject' | 'overwrite' | 'notify';
 }
 export interface ClaimHeldConflict extends ConflictBase {
     readonly kind: 'claim_held';
@@ -83,6 +90,22 @@ export type ConflictDecision = {
  | {
     readonly action: 'preempt';
     readonly reason?: string;
+}
+/**
+ * Notify-instead-of-abort (non-coercion). Only meaningful for a
+ * `stale_context` conflict, and the engine's aligned disposition: HOLD the
+ * conflicting op (don't write it) and return a `StaleNotification` with the
+ * current value so the actor (agent or human) resolves and re-commits. The
+ * rest of the batch still commits. Maps from `onStale: 'notify'`.
+ *
+ * Serialization order is supplied by the monotonic `sync_id` landing order
+ * (the stale committer always yields/recomputes — an asymmetry that rules out
+ * a symmetric notify-rewrite livelock). Unbounded retry is bounded by the
+ * client's reconciliation retry cap.
+ */
+ | {
+    readonly action: 'notify';
+    readonly reason?: string;
 };
 /**
  * Pluggable decision function. Sync or async.
@@ -98,9 +121,18 @@ export type ConflictDecision = {
  */
 export type ConflictPolicy = (conflict: Conflict) => ConflictDecision | Promise<ConflictDecision>;
 /**
- * Default: reject every conflict. Safe fallback when no custom policy
- * is wired — the engine never silently allows a stale or
- * claim-conflicting write through.
+ * Default policy.
+ *
+ * `claim_held` conflicts always reject (a foreign claim is honored unless a
+ * privileged policy preempts). `stale_context` conflicts honor the committer's
+ * declared `onStale` intent:
+ *
+ *   • `'notify'` → notify + hold (op withheld; the actor resolves)
+ *   • anything else (incl. `'reject'`, absent) → reject
+ *
+ * `'overwrite'` never reaches a policy — it's a hard opt-out resolved before
+ * detection. This preserves the legacy always-reject default for callers that
+ * don't opt into `notify`.
  */
 export declare const defaultPolicy: ConflictPolicy;
 /**