@abloatai/ablo 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.33.0
+
+### Minor Changes
+
+The declarative seam introduced in 0.32.0 for carrying tenant identity into your row-level-security policies has a clearer name and a simpler shape. `tenantContext` is now `sessionSettings`, and instead of a list of `{ guc, from }` pairs it is a plain map from the Postgres session setting your policies read to the Ablo identity that fills it:
+
+```ts
+defineSchema({
+  models: { document: { /* … */ } },
+  sessionSettings: { 'app.current_org': 'orgId' },
+})
+```
+
+The setting name is the key, so a setting takes exactly one source and a duplicate is unrepresentable rather than something to validate away. If you adopted `tenantContext` in 0.32.0, rename it to `sessionSettings` and turn each `{ guc: 'app.current_org', from: 'orgId' }` into `'app.current_org': 'orgId'`; the exported names followed the rename — `TenantContextMapping` and `TenantContextSource` became `SessionSettings` and `SessionSettingSource`, and `RESERVED_TENANT_CONTEXT_GUCS` became `RESERVED_SESSION_SETTINGS`. The meaning is unchanged: Ablo fills only settings it resolves from your authenticated identity, never from client-supplied data, so a mapping can forward the tenant Ablo already trusts but can never widen a writer's scope, and settings the engine reserves for itself — `row_security`, the timeouts — are still refused at definition time. Schemas pushed before the rename keep parsing.
+
+Claims gain a fairness backstop, off by default. Claims coordinate long work by waiting rather than locking: when another participant holds a row, your `claim` joins a fair FIFO line behind it, and the holder keeps its lease alive for as long as the work runs by beating on a cadence. Nothing bounded a hold, so a holder that kept beating — and never read the `queueDepth` pressure signal each beat returns, the cue to checkpoint and release when others are waiting — could keep a contended row indefinitely, and the line behind it had no recourse but that holder's goodwill. A deployment can now configure, per model, how long a single holding may last while contenders are actually queued; a holder that runs past that fair share is preempted at the server on its next beat, which arrives as the `claim_lost` you already handle — abandon or re-claim, exactly as when a lease lapses. The guarantee is deliberately narrow: a holder with no one waiting is never preempted however long it runs, so open-ended solo work is untouched, and preemption is a fairness decision, never a correctness one — a preempted holder's next write is still checked at commit against the row's version and fencing token, so the worst it can cause is a clean re-read, never a lost update.
+
+### Patch Changes
+
+Connecting a database a second time now behaves the way you'd expect. `ablo connect --apply` publishes exactly the tables you name with `--tables`, and until now it assumed that publication didn't exist yet — so on a database that had already been connected, the step to publish your tables quietly did nothing, and the writer role ended up granted on one set of tables while Ablo was still reading a different, older set. Registration then refused the writer as "not ready," which was correct but baffling: the two halves disagreed and nothing said so. Apply now reconciles the publication to match your `--tables` on every run — adding what's newly named, dropping what's no longer there, the same declarative model a CDC tool like Debezium uses — and prints what it's about to add or drop before it touches anything, so narrowing the set is a decision you see rather than a surprise.
+
+When a readiness check does fail, the reason is finally visible. The direct-write preflight has always returned a precise checklist — which privilege is missing, on which table, and the exact grant to fix it — but the CLI was reading it from the wrong place in the error and rendered a blank message that sent you in circles. The checklist now prints under the failure, one line per unmet requirement, with the fix.
+
 ## 0.32.0
 
 ### Minor Changes

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Let people and AI agents work on the same data without overwriting each other.</strong>
+  <strong>The coordination infrastructure for fleets of AI agents.</strong>
 </p>
 
 <p align="center">
@@ -23,17 +23,28 @@
 
 ---
 
-When an agent and a person change the same thing at once, work gets lost: one
-edit silently clobbers another, or the agent acts on data that already moved.
-Ablo gives them one shared, typed write path so people, server actions, and
-agents can all work on the same rows without working blind.
+Development stopped being the bottleneck; coordination is. The moment a *fleet*
+of agents — not one, and not just people — edits the same rows, work gets lost:
+one agent clobbers another, or acts on data that already moved. Ablo is the
+infrastructure that lets the fleet work as one — the load-bearing coordination
+layer the way operational-transform and presence sit invisibly under a shared
+document. You build the agents; Ablo is the substrate that lets them run together
+on shared state without stepping on each other, with the people and server
+actions alongside them on the exact same path.
 
 The core idea is a **claim**. An agent's work is rarely one instant write; it
-reads something, thinks, calls an LLM or tool, then writes back. While that is
-happening, the row can change underneath it. So before slow work starts, the
-agent claims the row. If someone else is already working on it, `claim` waits,
-re-reads the fresh row, then hands it over. No stale overwrite, no separate
-agent mutation path.
+reads something, thinks, calls an LLM or a tool, then writes back — and in that
+gap the row can move under it. So before the slow work starts, the agent claims
+the row. If another agent is already on it, `claim` waits its turn in a fair
+line, re-reads the fresh row, then hands it over. No stale overwrite, no separate
+agent mutation path. People are exempt by policy: a human edit is never made to
+queue behind an agent, and by declared conflict rules always wins.
+
+When the row moves anyway — say a record an agent generated against gets bumped
+the moment before it commits — the commit is rejected and the agent is handed
+back exactly the records that changed, so it re-reads only those, not the world.
+The pattern we kept measuring: with real agents contending on shared state, the
+win comes from the coordination layer, not a bigger model. Org beats intelligence.
 
 Under the hood, you define your data once with a Zod schema and get the same
 typed model client for every actor — people, server actions, and agents:
@@ -63,8 +74,9 @@ yet? A **sandbox** `sk_test` key holds throwaway **test data** — like Stripe t
 mode — so you can explore before pointing it at your Postgres. Test-mode only; in
 production every row lives in your database.)
 
-**Built for** collaborative editors, AI agent workflows, background workers on
-your own infrastructure, and internal tools — anywhere people and agents change
+**Built for** fleets of agents working a shared backlog, AI agent workflows on
+your own infrastructure, collaborative editors where agents and people co-edit,
+and internal tools — anywhere agents (and the people alongside them) change
 shared state and everyone has to see it live.
 
 ## Set up

package/dist/cli.cjs

@@ -5431,6 +5431,55 @@ BEGIN
 END $$;`
   ];
 }
+function reconcilePublicationPlan(current, desiredTables) {
+  const pub = quoteIdent(ABLO_PUBLICATION);
+  const desiredAll = desiredTables.length === 0;
+  const target = desiredAll ? "FOR ALL TABLES" : `FOR TABLE ${desiredTables.map(quoteIdent).join(", ")}`;
+  if (!current.exists) {
+    return {
+      sql: [`CREATE PUBLICATION ${pub} ${target};`],
+      added: desiredAll ? [] : [...desiredTables],
+      removed: [],
+      recreated: false
+    };
+  }
+  if (current.allTables !== desiredAll) {
+    return {
+      sql: [`DROP PUBLICATION IF EXISTS ${pub};`, `CREATE PUBLICATION ${pub} ${target};`],
+      added: desiredAll ? [] : desiredTables.filter((t) => !current.tables.includes(t)),
+      removed: current.allTables ? [] : current.tables.filter((t) => !desiredTables.includes(t)),
+      recreated: true
+    };
+  }
+  if (desiredAll) {
+    return { sql: [], added: [], removed: [], recreated: false };
+  }
+  const added = desiredTables.filter((t) => !current.tables.includes(t));
+  const removed = current.tables.filter((t) => !desiredTables.includes(t));
+  if (added.length === 0 && removed.length === 0) {
+    return { sql: [], added: [], removed: [], recreated: false };
+  }
+  return {
+    sql: [`ALTER PUBLICATION ${pub} SET TABLE ${desiredTables.map(quoteIdent).join(", ")};`],
+    added,
+    removed,
+    recreated: false
+  };
+}
+async function readPublicationState(sql) {
+  const pubRows = await sql.unsafe(
+    `SELECT puballtables FROM pg_publication WHERE pubname = $1`,
+    [ABLO_PUBLICATION]
+  );
+  const pubRow = pubRows[0];
+  if (!pubRow) return { exists: false, allTables: false, tables: [] };
+  if (pubRow.puballtables) return { exists: true, allTables: true, tables: [] };
+  const tableRows = await sql.unsafe(
+    `SELECT tablename FROM pg_publication_tables WHERE pubname = $1 AND schemaname = 'public' ORDER BY tablename`,
+    [ABLO_PUBLICATION]
+  );
+  return { exists: true, allTables: false, tables: tableRows.map((r2) => r2.tablename) };
+}
 async function probeReadiness(sql, opts = {}) {
   const publication = opts.publication ?? ABLO_PUBLICATION;
   const items = [];
@@ -5568,7 +5617,7 @@ async function registerDirectDataSource(opts) {
       )
     );
   } else if (code === "database_not_replication_ready" || code === "data_source_blocked") {
-    for (const f of body.details?.failures ?? []) {
+    for (const f of body.failures ?? body.details?.failures ?? []) {
       console.error(
         `  ${import_picocolors6.default.red("\u2717")} ${import_picocolors6.default.bold(f.item ?? "item")}${f.actual ? import_picocolors6.default.dim(` (${f.actual})`) : ""}`
       );
@@ -5580,7 +5629,8 @@ async function registerDirectDataSource(opts) {
   Apply the fixes, verify with ${import_picocolors6.default.bold("ablo connect check")}, then re-run.`)
     );
   } else if (code === "database_unreachable" || code === "source_unreachable") {
-    if (body.details?.reason) console.error(import_picocolors6.default.dim(`  ${body.details.reason}`));
+    const reason = body.reason ?? body.details?.reason;
+    if (reason) console.error(import_picocolors6.default.dim(`  ${reason}`));
     console.error(
       import_picocolors6.default.dim(
         `  Ablo's servers must be able to reach this database \u2014 a localhost or private-network
@@ -5592,7 +5642,7 @@ async function registerDirectDataSource(opts) {
   console.error();
   return false;
 }
-var import_picocolors6, import_zod6, ABLO_PUBLICATION, ABLO_REPLICATION_ROLE, ABLO_WRITE_ROLE, DIRECT_DATA_SOURCE_ROUTES, DataSourceRegisterSuccess, DataSourceRegisterError;
+var import_picocolors6, import_zod6, ABLO_PUBLICATION, ABLO_REPLICATION_ROLE, ABLO_WRITE_ROLE, DIRECT_DATA_SOURCE_ROUTES, DataSourceRegisterSuccess, ReadinessFailure, DataSourceRegisterError;
 var init_connectSetup = __esm({
   "src/cli/connectSetup.ts"() {
     "use strict";
@@ -5614,17 +5664,20 @@ var init_connectSetup = __esm({
       host: import_zod6.z.string().optional(),
       status: import_zod6.z.string().optional()
     });
+    ReadinessFailure = import_zod6.z.object({
+      item: import_zod6.z.string().optional(),
+      actual: import_zod6.z.string().optional(),
+      fix: import_zod6.z.string().optional()
+    });
     DataSourceRegisterError = import_zod6.z.object({
       code: import_zod6.z.string().optional(),
       message: import_zod6.z.string().optional(),
+      // Canonical: top-level, spread from the engine's `details`.
+      failures: import_zod6.z.array(ReadinessFailure).optional(),
+      reason: import_zod6.z.string().optional(),
+      // Fallback: a wrapping proxy or older engine that nested the same payload.
       details: import_zod6.z.object({
-        failures: import_zod6.z.array(
-          import_zod6.z.object({
-            item: import_zod6.z.string().optional(),
-            actual: import_zod6.z.string().optional(),
-            fix: import_zod6.z.string().optional()
-          })
-        ).optional(),
+        failures: import_zod6.z.array(ReadinessFailure).optional(),
         reason: import_zod6.z.string().optional()
       }).optional(),
       error: import_zod6.z.object({ code: import_zod6.z.string().optional(), message: import_zod6.z.string().optional() }).optional()
@@ -5829,18 +5882,21 @@ function connectApplyPlan(input) {
       sql: []
     }
   ];
+  const reconcile2 = input.existingPublication ? reconcilePublicationPlan(input.existingPublication, tables) : null;
+  const publicationSql = reconcile2 ? reconcile2.sql : [
+    `DO $$ BEGIN
+  CREATE PUBLICATION ${quoteIdent(ABLO_PUBLICATION)} ${publicationTarget};
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;`
+  ];
+  const publicationDetail = reconcile2?.sql.length === 0 ? "already publishing exactly these tables \u2014 nothing to change" : tables.length > 0 ? `a read stream of the ${tables.length} table${tables.length === 1 ? "" : "s"} you chose` : "a read stream of your tables";
   return [
     ...walStep,
     {
       key: "publication",
       title: "Publish your tables to Ablo",
-      detail: tables.length > 0 ? `a read stream of the ${tables.length} table${tables.length === 1 ? "" : "s"} you chose` : "a read stream of your tables",
-      sql: [
-        `DO $$ BEGIN
-  CREATE PUBLICATION ${quoteIdent(ABLO_PUBLICATION)} ${publicationTarget};
-EXCEPTION WHEN duplicate_object THEN NULL;
-END $$;`
-      ]
+      detail: publicationDetail,
+      sql: publicationSql
     },
     {
       key: "replication-role",
@@ -6046,6 +6102,10 @@ async function runConnectApply(args) {
   }
   const provider = detectProvider(target);
   const walReady = await currentWalLevel(admin) === "logical";
+  const existingPublication = await readPublicationState(admin).catch(
+    () => ({ exists: false, allTables: false, tables: [] })
+  );
+  const pubReconcile = reconcilePublicationPlan(existingPublication, args.tables);
   const replicationPassword = generateRolePassword();
   const writePassword = generateRolePassword();
   const buildPlan = (mode2) => connectApplyPlan({
@@ -6057,9 +6117,21 @@ async function runConnectApply(args) {
       writeClause: passwordClause(writePassword, mode2)
     },
     walAlreadyLogical: walReady,
-    provider
+    provider,
+    existingPublication
   });
   const steps = buildPlan("scram-verifier");
+  if (pubReconcile.removed.length > 0 || pubReconcile.recreated) {
+    console.log(
+      `  ${import_picocolors8.default.yellow("!")} ${import_picocolors8.default.bold(ABLO_PUBLICATION)} already publishes a different set; reconciling to your ${import_picocolors8.default.bold("--tables")}:`
+    );
+    for (const t of pubReconcile.added) console.log(`      ${import_picocolors8.default.green("+")} ${t}`);
+    for (const t of pubReconcile.removed)
+      console.log(`      ${import_picocolors8.default.red("-")} ${t} ${import_picocolors8.default.dim("(stops replicating to Ablo)")}`);
+    if (pubReconcile.recreated && existingPublication.allTables)
+      console.log(`      ${import_picocolors8.default.red("-")} ${import_picocolors8.default.dim("every other table (was FOR ALL TABLES)")}`);
+    console.log();
+  }
   printPlan2(steps, args.showSql);
   if (!args.yes) {
     if (!process.stdout.isTTY) {

package/dist/schema/index.d.ts

@@ -30,7 +30,7 @@ export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncD
 export { model, scopeKindOf, type ModelDef, type ModelOptions, type LoadStrategy, type PersistOptions, type RelationRecord, type GrantsRef, type ConflictAxis, } from './model.js';
 export { coordination, humansOverwrite, humansReject, humansNotify, agentsOverwrite, agentsReject, agentsNotify, systemOverwrite, systemReject, systemNotify, type ConflictRule, } from './coordination.js';
 export { mutable, readOnly, type SugarOptions } from './sugar.js';
-export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type Row, type InferModel, type InferCreate, type InferRow, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, intersectRequestedWithAllowed, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, type TenantContextMapping, type TenantContextSource, RESERVED_TENANT_CONTEXT_GUCS, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type Row, type InferModel, type InferCreate, type InferRow, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, intersectRequestedWithAllowed, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, type SessionSettings, type SessionSettingSource, RESERVED_SESSION_SETTINGS, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
 export { selectModels, omitModels } from './select.js';
 export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';

package/dist/schema/index.js

@@ -56,7 +56,7 @@ export { coordination, humansOverwrite, humansReject, humansNotify, agentsOverwr
 // sensible defaults for everything else.
 export { mutable, readOnly } from './sugar.js';
 // Schema definition + type inference
-export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, intersectRequestedWithAllowed, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, RESERVED_TENANT_CONTEXT_GUCS, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, intersectRequestedWithAllowed, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, RESERVED_SESSION_SETTINGS, } from './schema.js';
 // Schema ⇄ JSON — serialize a schema for transport and rebuild it on the far side.
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, } from './serialize.js';
 // Schema projection — derive an app's subset from one canonical schema.

package/dist/schema/schema.d.ts

@@ -30,36 +30,32 @@ export type CasingConvention = 'snake_case' | 'camelCase';
 export type CasingFn = (jsField: string) => string;
 /** `defineSchema`'s casing option. Identity when unset. */
 export type Casing = CasingConvention | CasingFn;
-/** Options for `defineSchema`. */
 /**
- * A server-authored context value that can fill a customer's row-level-security
- * GUC. Deliberately a closed set — every member is resolved by Ablo from the
- * authenticated `ek_` and the plane, never from client-supplied data — so a
- * mapping can forward the tenant identity Ablo already trusts but can never
+ * A server-authored identity value that can fill one of a customer's Postgres
+ * session settings. Deliberately a closed set — every member is resolved by Ablo
+ * from the authenticated `ek_` and the plane, never from client-supplied data —
+ * so a mapping can forward the tenant identity Ablo already trusts but can never
  * widen a writer's scope. Mirrors the fields the engine sets on the direct-write
  * connection (`app.current_org_id`, `app.current_project_id`, …).
  */
-export type TenantContextSource = 'orgId' | 'projectId' | 'environment' | 'sandboxId' | 'participantId' | 'participantKind';
+export type SessionSettingSource = 'orgId' | 'projectId' | 'environment' | 'sandboxId' | 'participantId' | 'participantKind';
 /**
- * Maps a Postgres session GUC the customer's RLS policies read to the Ablo
- * context value that fills it. See {@link DefineSchemaOptions.tenantContext} and
- * ADR 0011.
+ * A map from a Postgres session-setting name the customer's RLS policies read to
+ * the Ablo identity that fills it — e.g. `{ 'app.current_org': 'orgId' }`. The
+ * setting name is the key (it takes exactly one source), so a duplicate is
+ * unrepresentable rather than validated away. See
+ * {@link DefineSchemaOptions.sessionSettings} and ADR 0011.
  */
-export interface TenantContextMapping {
-    /** The GUC name the customer's policies read, e.g. `app.current_app_org_id`. */
-    readonly guc: string;
-    /** Which server-authored context value fills it. */
-    readonly from: TenantContextSource;
-}
+export type SessionSettings = Readonly<Record<string, SessionSettingSource>>;
 /**
- * GUCs Ablo already sets on its direct-write connection. A `tenantContext`
- * mapping FORWARDS Ablo's trusted context into a customer's own policy GUC — it
- * may never reassign one of these, which would let a schema push relax the
- * engine's own scoping, timeouts, or `row_security`. Shared with the engine's
- * direct-write seam so authoring-time validation and the runtime guard read one
- * list. See ADR 0011.
+ * Session settings Ablo already sets on its direct-write connection. A
+ * `sessionSettings` entry FORWARDS Ablo's trusted context into a setting the
+ * customer's own policies read — it may never reassign one of these, which would
+ * let a schema push relax the engine's own scoping, timeouts, or `row_security`.
+ * Shared with the engine's direct-write seam so authoring-time validation and
+ * the runtime guard read one list. See ADR 0011.
  */
-export declare const RESERVED_TENANT_CONTEXT_GUCS: readonly string[];
+export declare const RESERVED_SESSION_SETTINGS: readonly string[];
 export interface DefineSchemaOptions {
     /**
      * How to translate camelCase JS field names into database column
@@ -90,26 +86,27 @@ export interface DefineSchemaOptions {
      */
     readonly identityRoles?: readonly IdentityRole[];
     /**
-     * Declares how Ablo's direct-write connection carries tenant context into the
-     * GUCs your row-level-security policies read (ADR 0011). Before every direct
-     * write, Ablo already sets a fixed bundle (`app.current_org_id`,
-     * `app.current_project_id`, …) with `SET LOCAL`. If your policies read a
-     * differently-named GUC that your own app sets per-connection — e.g. a
-     * restrictive policy on `current_setting('app.current_app_org_id')` — declare
-     * the mapping here so Ablo forwards its trusted context into that GUC too, and
-     * your RLS governs Ablo's writes:
+     * Extra Postgres session settings Ablo's direct-write connection applies from
+     * your authenticated identity, so your row-level-security policies read them
+     * (ADR 0011). Before every direct write, Ablo already `SET LOCAL`s a fixed
+     * bundle (`app.current_org_id`, `app.current_project_id`, …). If your policies
+     * read a differently-named setting your own app sets per-connection — e.g. a
+     * restrictive policy on `current_setting('app.current_org')` — map that
+     * setting to the identity that fills it, and Ablo sets it too:
      *
      * ```ts
      * defineSchema({ ... }, {
-     *   tenantContext: [{ guc: 'app.current_app_org_id', from: 'orgId' }],
+     *   sessionSettings: { 'app.current_org': 'orgId' },
      * })
      * ```
      *
-     * Do NOT carve a policy exception for the writer role — that exempts exactly
-     * the writes you want governed. Leave unset when your policies read the GUCs
-     * Ablo already sets (or when a table has no RLS). Empty array when unset.
+     * The key is the setting name your policies read; the value is a closed set of
+     * identities Ablo authenticates, so a mapping can narrow what the writer sees
+     * but never widen it. Do NOT carve a policy exception for the writer role —
+     * that exempts exactly the writes you want governed. Leave unset when your
+     * policies read the settings Ablo already applies (or when a table has no RLS).
      */
-    readonly tenantContext?: readonly TenantContextMapping[];
+    readonly sessionSettings?: SessionSettings;
 }
 /** A record of model names → model definitions */
 export type SchemaRecord = Record<string, ModelDef>;
@@ -165,12 +162,12 @@ export interface Schema<S extends SchemaRecord = SchemaRecord> {
      */
     readonly identityRoles: readonly IdentityRole[];
     /**
-     * Tenant-context GUC mappings registered via `defineSchema({...},
-     * { tenantContext })` (ADR 0011). The engine's direct-write path reads this to
-     * `SET LOCAL` each declared GUC from server-authored context before applying
-     * DML, so the customer's RLS governs Ablo's writes. Empty array when unset.
+     * Session settings registered via `defineSchema({...}, { sessionSettings })`
+     * (ADR 0011). The engine's direct-write path reads this to `SET LOCAL` each
+     * named setting from server-authored context before applying DML, so the
+     * customer's RLS governs Ablo's writes. Empty object when unset.
      */
-    readonly tenantContext: readonly TenantContextMapping[];
+    readonly sessionSettings: SessionSettings;
     /**
      * Set only on a projection produced by `selectModels`/`omitModels`: the
      * content hash of the FULL source schema the subset was cut from. A subset

package/dist/schema/schema.js

@@ -45,14 +45,14 @@ function camelToSnake(identifier) {
     return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
 }
 /**
- * GUCs Ablo already sets on its direct-write connection. A `tenantContext`
- * mapping FORWARDS Ablo's trusted context into a customer's own policy GUC — it
- * may never reassign one of these, which would let a schema push relax the
- * engine's own scoping, timeouts, or `row_security`. Shared with the engine's
- * direct-write seam so authoring-time validation and the runtime guard read one
- * list. See ADR 0011.
+ * Session settings Ablo already sets on its direct-write connection. A
+ * `sessionSettings` entry FORWARDS Ablo's trusted context into a setting the
+ * customer's own policies read — it may never reassign one of these, which would
+ * let a schema push relax the engine's own scoping, timeouts, or `row_security`.
+ * Shared with the engine's direct-write seam so authoring-time validation and
+ * the runtime guard read one list. See ADR 0011.
  */
-export const RESERVED_TENANT_CONTEXT_GUCS = [
+export const RESERVED_SESSION_SETTINGS = [
     'statement_timeout',
     'lock_timeout',
     'row_security',
@@ -221,45 +221,39 @@ export function defineSchema(models, options) {
         resolvedModels[name] = { ...def, typename, tableName, persist };
     }
     validateSyncGroupSchema(resolvedModels);
-    validateTenantContext(options?.tenantContext ?? []);
+    validateSessionSettings(options?.sessionSettings ?? {});
     return {
         // Cast back to S: we only added values to optional fields that were
         // already part of ModelDef, so the shape is structurally unchanged.
         models: resolvedModels,
         validators: validators,
         identityRoles: options?.identityRoles ?? [],
-        tenantContext: options?.tenantContext ?? [],
+        sessionSettings: options?.sessionSettings ?? {},
     };
 }
 /**
- * Reject tenant-context mappings that couldn't do what the author intends —
+ * Reject session-setting mappings that couldn't do what the author intends —
  * caught here at definition time rather than silently dropped on the write path.
- * A mapping must name a non-empty customer GUC, must not reassign one of the
- * engine's reserved GUCs, and each GUC may be mapped at most once.
+ * Each key must name a non-empty setting the customer's policies read, and must
+ * not reassign one Ablo already manages. Uniqueness needs no check: the map is
+ * keyed by the setting name, so a duplicate is unrepresentable.
  */
-function validateTenantContext(mappings) {
-    const seen = new Set();
-    for (const { guc } of mappings) {
-        const name = guc.trim();
+function validateSessionSettings(settings) {
+    for (const setting of Object.keys(settings)) {
+        const name = setting.trim();
         if (name === '') {
-            throw new AbloValidationError(`[defineSchema] tenantContext: a mapping has an empty \`guc\`. Name the ` +
-                `Postgres setting your row-level-security policies read, e.g. ` +
-                `\`{ guc: 'app.current_app_org_id', from: 'orgId' }\`.`, { code: 'schema_definition_invalid', param: 'tenantContext' });
+            throw new AbloValidationError(`[defineSchema] sessionSettings: a key is empty. Name the Postgres ` +
+                `setting your row-level-security policies read, e.g. ` +
+                `\`{ 'app.current_org': 'orgId' }\`.`, { code: 'schema_definition_invalid', param: 'sessionSettings' });
         }
-        if (RESERVED_TENANT_CONTEXT_GUCS.includes(name)) {
-            throw new AbloValidationError(`[defineSchema] tenantContext: \`${name}\` is a setting Ablo already ` +
+        if (RESERVED_SESSION_SETTINGS.includes(name)) {
+            throw new AbloValidationError(`[defineSchema] sessionSettings: \`${name}\` is a setting Ablo already ` +
                 `manages on its write connection, so a mapping can't reassign it — ` +
                 `that would let a schema relax the engine's own scoping. Point your ` +
-                `policies at a GUC your app owns (e.g. \`app.current_app_org_id\`) and ` +
-                `map Ablo's trusted context into that instead. Reserved: ` +
-                `${RESERVED_TENANT_CONTEXT_GUCS.join(', ')}.`, { code: 'schema_definition_invalid', param: `tenantContext.${name}` });
+                `policies at a setting your app owns (e.g. \`app.current_org\`) and ` +
+                `map Ablo's trusted identity into that instead. Reserved: ` +
+                `${RESERVED_SESSION_SETTINGS.join(', ')}.`, { code: 'schema_definition_invalid', param: `sessionSettings.${name}` });
         }
-        if (seen.has(name)) {
-            throw new AbloValidationError(`[defineSchema] tenantContext: \`${name}\` is mapped more than once. ` +
-                `A GUC takes exactly one source — keep the mapping you mean and drop ` +
-                `the duplicate.`, { code: 'schema_definition_invalid', param: `tenantContext.${name}` });
-        }
-        seen.add(name);
     }
 }
 /**

package/dist/schema/select.js

@@ -52,7 +52,7 @@ export function selectModels(schema, keys) {
         models: models,
         validators: validators,
         identityRoles: schema.identityRoles,
-        tenantContext: schema.tenantContext,
+        sessionSettings: schema.sessionSettings,
         // Record the full source's hash so the drift check can recognize this subset
         // as current against a server running that full schema. Prefer the source's
         // OWN `sourceSchemaHash` when it is itself a projection, so a subset-of-a-

package/dist/schema/serialize.d.ts

@@ -31,7 +31,7 @@ import type { Tenancy } from './tenancy.js';
 import type { ModelResidency } from './residency.js';
 import type { GrantsRef, LoadStrategy, PersistOptions, AutoFillRule, ConflictAxis } from './model.js';
 import type { RelationType } from './relation.js';
-import { type Schema, type IdentityRole, type EntityRole, type TenantContextMapping } from './schema.js';
+import { type Schema, type IdentityRole, type EntityRole, type SessionSettings } from './schema.js';
 /** Current schema-JSON envelope version. Bump this on a breaking change to the
  * JSON shape itself — not to a user's schema. */
 declare const SCHEMA_JSON_VERSION: 3;
@@ -75,8 +75,8 @@ export interface SchemaJSON {
     readonly v: typeof SCHEMA_JSON_VERSION;
     readonly models: Record<string, ModelJSON>;
     readonly identityRoles: readonly IdentityRole[];
-    /** Optional so schemas pushed before ADR 0011 still parse (defaults to `[]`). */
-    readonly tenantContext?: readonly TenantContextMapping[];
+    /** Optional so schemas pushed before ADR 0011 still parse (defaults to `{}`). */
+    readonly sessionSettings?: SessionSettings;
 }
 /**
  * Project a `Schema` to its JSON form. Drops the client-only closures

package/dist/schema/serialize.js

@@ -93,7 +93,9 @@ export function toSchemaJSON(schema) {
         v: SCHEMA_JSON_VERSION,
         models,
         identityRoles: schema.identityRoles,
-        ...(schema.tenantContext.length > 0 ? { tenantContext: schema.tenantContext } : {}),
+        ...(Object.keys(schema.sessionSettings).length > 0
+            ? { sessionSettings: schema.sessionSettings }
+            : {}),
     };
 }
 /** Serialize a `Schema` to a JSON string (the `ablo push` payload). */
@@ -205,7 +207,7 @@ export function fromSchemaJSON(json) {
         models: models,
         validators: validators,
         identityRoles: json.identityRoles,
-        tenantContext: json.tenantContext ?? [],
+        sessionSettings: json.sessionSettings ?? {},
     };
 }
 /** Parse a `Schema` from a JSON string (inverse of {@link serializeSchema}). */

package/docs/coordination.md

@@ -473,6 +473,18 @@ Each beat's answer carries two more things:
   the lease. Durable progress belongs in the data itself — write a row, and
   every subscriber already sees it.
 
+Cooperative yield has a server-side backstop your deployment can turn on: a
+**cumulative-hold ceiling**. Left unset — the default — a holder that keeps
+beating holds the row as long as it likes, and the line behind it depends on
+that holder reading `queueDepth` and releasing of its own accord. With a ceiling
+configured for a model, a holder that runs past its fair share *while contenders
+are queued* is preempted at the server: its next beat comes back `claim_lost`
+(reason `preempted`) — the same loss you already handle, so abandon or re-claim,
+and any write attempted under the old lease is fenced regardless. A holder with
+no one waiting is never preempted, however long it runs. It is the same idea as
+an SQS message that cannot stay invisible past a hard cap however often its lock
+is refreshed, narrowed here to bite only under real contention.
+
 Works identically on both transports: the realtime client sends a
 `claim_heartbeat` frame; the HTTP client posts
 `POST /api/v1/models/{model}/{id}/claim/heartbeat` (`{ ttl?, claimId?, details? }`).
@@ -603,7 +615,7 @@ inspect the `code`.
 
 | error | `code` | thrown when | carries |
 |---|---|---|---|
-| `AbloClaimedError` | `claim_lost` | A held/queued claim was taken away — the holder disconnected (reaped on the keepalive cycle), went silent past its TTL, or was revoked — while you were holding or waiting. | `claims?` |
+| `AbloClaimedError` | `claim_lost` | A held/queued claim was taken away — the holder disconnected (reaped on the keepalive cycle), went silent past its TTL, was revoked, or was preempted (a privileged reorder, or a configured cumulative-hold ceiling reached while contenders waited) — while you were holding or waiting. | `claims?` |
 | `AbloClaimedError` | `claim_queued` | **HTTP transport only.** A contended `claim` (default `queue: true`) could not block-wait for the lease (no socket), so it rejected immediately instead of queueing. Retryable — re-attempt the claim. | `claims?` |
 | `AbloClaimedError` | `grant_timeout` | The optional `timeoutMs` elapsed while you were still queued for a grant. | `claims?` |
 | `AbloClaimedError` | `queue_too_deep` | `claim` was passed `maxQueueDepth` and the wait line was already that deep when you tried to join — fail-fast instead of waiting. | `claims?` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",