@abloatai/ablo 0.31.0 → 0.33.0

package/dist/coordination/schema.d.ts

@@ -245,6 +245,8 @@ export declare const wireClaimSchema: z.ZodObject<{
     }, z.core.$strip>>;
     field: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    fenceToken: z.ZodOptional<z.ZodNumber>;
+    acquiredAt: z.ZodOptional<z.ZodNumber>;
     claimId: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     declaredAt: z.ZodNumber;
@@ -255,7 +257,6 @@ 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>;
@@ -665,6 +666,8 @@ export declare const presenceUpdateFrameSchema: z.ZodObject<{
         }, z.core.$strip>>;
         field: z.ZodOptional<z.ZodString>;
         meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        fenceToken: z.ZodOptional<z.ZodNumber>;
+        acquiredAt: z.ZodOptional<z.ZodNumber>;
         claimId: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
         declaredAt: z.ZodNumber;
@@ -675,7 +678,6 @@ 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>;

package/dist/coordination/schema.js

@@ -198,6 +198,28 @@ export const claimStatusSchema = z.enum([
     'expired',
     'canceled',
 ]);
+/**
+ * Server-owned grant stamps — minted once when a claim is first granted and
+ * preserved verbatim across a re-announce of the same `claimId`, so neither a
+ * reconnect nor a client-supplied value can move them (unlike `declaredAt`,
+ * which the client sends afresh each announce). Both optional: a frame without
+ * them stays valid, and the feature each backs simply does not engage.
+ */
+const grantStampFields = {
+    /**
+     * The monotonic fencing token minted for this grant (Option B). Strictly
+     * increasing per entity across successive grants, so a write that carries it
+     * is rejected at commit if a later holder already advanced the entity's
+     * high-water. A token-less write is simply not fence-checked.
+     */
+    fenceToken: z.number().optional(),
+    /**
+     * Lease origin (epoch ms): when THIS holding was acquired. The cumulative-
+     * hold ceiling measures a holder's fair share from here — and because it
+     * survives a re-announce, a reconnect cannot rewind the clock.
+     */
+    acquiredAt: z.number().optional(),
+};
 const wireClaimBaseSchema = targetRefSchema.extend({
     claimId: z.string(),
     /**
@@ -211,15 +233,7 @@ const wireClaimBaseSchema = targetRefSchema.extend({
     /** 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(),
+    ...grantStampFields,
 });
 export const wireClaimSummarySchema = wireClaimBaseSchema.pick({
     claimId: true,

package/dist/errorCodes.d.ts

@@ -192,6 +192,7 @@ export declare const ERROR_CODES: {
     readonly entity_not_found: ErrorCodeSpec;
     readonly model_not_found: ErrorCodeSpec;
     readonly mutate_update_entity_not_found: ErrorCodeSpec;
+    readonly no_data_source_registered: ErrorCodeSpec;
     readonly task_id_missing: ErrorCodeSpec;
     readonly not_null_violation: ErrorCodeSpec;
     readonly foreign_key_violation: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -207,6 +207,7 @@ export const ERROR_CODES = {
     entity_not_found: wire('not_found', 404, false, 'No row exists with the requested id. It may have been deleted, or the id may belong to a different environment.'),
     model_not_found: wire('not_found', 404, false, 'No row of this model exists with the requested id. It may have been deleted, or the id may belong to a different environment.'),
     mutate_update_entity_not_found: wire('not_found', 404, false, 'The row targeted by this update does not exist — it may have been deleted since you read it. Re-read before retrying.'),
+    no_data_source_registered: wire('not_found', 404, false, 'No database is connected to this plane yet, so there is nothing to check. Connect one with `ablo connect apply`, then run the check again.'),
     task_id_missing: wire('server', 502, true, 'The task-create response arrived without a task id, so the result cannot be used. Retry the request.'),
     // ── data integrity / database constraints ──────────────────────────
     // Emitted when a database integrity constraint rejects a write. None are
@@ -365,7 +366,7 @@ export const ERROR_CODES = {
     query_invalid_boolean: wire('validation', 400, false, 'The query compared a boolean column against an invalid boolean literal.'),
     protocol_version_unsupported: wire('transport', 426, false, 'The client sync-protocol version is outside the range this server supports — upgrade the SDK (or the server was rolled back mid-fleet).'),
     database_unreachable: wire('validation', 400, false, "Ablo could not reach this database to check that it can stream replication. The connection string may be wrong, the host may not be reachable from Ablo's servers, or the credentials may not be accepted."),
-    database_not_replication_ready: wire('validation', 400, false, 'This database is not set up for logical replication yet. Every failing item — wal_level, the publication, the replication grant, a replica identity — is listed in the error details with its exact fix. `ablo connect` prints the one-time setup; `ablo connect --check` verifies it.'),
+    database_not_replication_ready: wire('validation', 400, false, 'This database is not set up for logical replication yet. Every failing item — wal_level, the publication, the replication grant, a replica identity — is listed in the error details with its exact fix. `ablo connect` prints the one-time setup; `ablo connect check` verifies it.'),
     replication_publication_drift: wire('validation', 400, false, 'Your schema maps to tables that are not members of the replication publication, so their changes silently never stream and the source looks frozen. The missing tables and the exact `ALTER PUBLICATION … ADD TABLE …` to add them are in the error details — Ablo never alters your database for you.'),
     query_unknown_relation: wire('validation', 400, false, 'The query references a relation the model does not define. Check the relation name against the schema.'),
     query_relation_target_unknown: wire('schema', 500, false, 'A relation in the query targets a model the schema does not define.'),

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, } 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, } 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,7 +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 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 SessionSettingSource = 'orgId' | 'projectId' | 'environment' | 'sandboxId' | 'participantId' | 'participantKind';
+/**
+ * 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 type SessionSettings = Readonly<Record<string, SessionSettingSource>>;
+/**
+ * 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_SESSION_SETTINGS: readonly string[];
 export interface DefineSchemaOptions {
     /**
      * How to translate camelCase JS field names into database column
@@ -60,6 +85,28 @@ export interface DefineSchemaOptions {
      * authentication provider attached to the identity.
      */
     readonly identityRoles?: readonly IdentityRole[];
+    /**
+     * 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({ ... }, {
+     *   sessionSettings: { 'app.current_org': 'orgId' },
+     * })
+     * ```
+     *
+     * 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 sessionSettings?: SessionSettings;
 }
 /** A record of model names → model definitions */
 export type SchemaRecord = Record<string, ModelDef>;
@@ -114,6 +161,13 @@ export interface Schema<S extends SchemaRecord = SchemaRecord> {
      * to derive a participant's allowed sync-group set.
      */
     readonly identityRoles: readonly IdentityRole[];
+    /**
+     * 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 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

@@ -44,6 +44,26 @@ function resolveCasing(fn) {
 function camelToSnake(identifier) {
     return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
 }
+/**
+ * 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_SESSION_SETTINGS = [
+    'statement_timeout',
+    'lock_timeout',
+    'row_security',
+    'search_path',
+    'app.current_org_id',
+    'app.current_project_id',
+    'app.current_environment',
+    'app.current_sandbox_id',
+    'app.current_participant_id',
+    'app.current_participant_kind',
+];
 /**
  * Base fields every synced model gets automatically.
  *
@@ -201,14 +221,41 @@ export function defineSchema(models, options) {
         resolvedModels[name] = { ...def, typename, tableName, persist };
     }
     validateSyncGroupSchema(resolvedModels);
+    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 ?? [],
+        sessionSettings: options?.sessionSettings ?? {},
     };
 }
+/**
+ * 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.
+ * 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 validateSessionSettings(settings) {
+    for (const setting of Object.keys(settings)) {
+        const name = setting.trim();
+        if (name === '') {
+            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_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 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}` });
+        }
+    }
+}
 /**
  * Validates the relation-driven sync-group declarations (`scope` and `grants`)
  * at schema-build time, so a mistyped membership edge fails here — with a

package/dist/schema/select.js

@@ -52,6 +52,7 @@ export function selectModels(schema, keys) {
         models: models,
         validators: validators,
         identityRoles: schema.identityRoles,
+        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 } 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,6 +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 sessionSettings?: SessionSettings;
 }
 /**
  * Project a `Schema` to its JSON form. Drops the client-only closures

package/dist/schema/serialize.js

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

package/dist/source/adapters/drizzle.js

@@ -37,7 +37,7 @@ import { AbloValidationError } from '../../errors.js';
 import { sql } from 'drizzle-orm';
 import { outboxEventSchema } from '../contract.js';
 import { adapterTableMigrations } from '../migrations.js';
-import { assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, sourceChangeIntentHash, } from '../idempotency.js';
+import { assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, SOURCE_IDEMPOTENCY_RETENTION, sourceChangeIntentHash, } from '../idempotency.js';
 import { toSchemaJSON } from '../../schema/serialize.js';
 import { camelToSnake, snakeToCamel } from '../../schema/ddl.js';
 import { tenancyColumn } from '../../schema/tenancy.js';
@@ -183,9 +183,10 @@ export function drizzleDataSource(db, schema) {
             )`);
                 }
                 await tx.execute(sql `
-          INSERT INTO ablo_idempotency (client_tx_id, response, request_hash)
+          INSERT INTO ablo_idempotency (client_tx_id, response, request_hash, expires_at)
           VALUES (
-            ${change.correlationId}, ${JSON.stringify(rows)}::jsonb, ${requestHash}
+            ${change.correlationId}, ${JSON.stringify(rows)}::jsonb, ${requestHash},
+            now() + ${SOURCE_IDEMPOTENCY_RETENTION}::interval
           )`);
                 if (change.echo?.kind === 'postgres-wal') {
                     await tx.execute(sql `SELECT pg_logical_emit_message(true, ${ABLO_POSTGRES_COMMIT_ECHO_PREFIX}, ${change.echo.payload})`);

package/dist/source/adapters/kysely.js

@@ -18,7 +18,7 @@
  */
 import { AbloValidationError } from '../../errors.js';
 import { changeSetSchema, outboxEventSchema, sourceCommitEchoMarkerSchema, } from '../contract.js';
-import { assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, sourceChangeIntentHash, } from '../idempotency.js';
+import { assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, sourceChangeIntentHash, SOURCE_IDEMPOTENCY_RETENTION, } from '../idempotency.js';
 import { adapterTableMigrations, idempotencyLedgerMigrations, } from '../migrations.js';
 import { ABLO_POSTGRES_COMMIT_ECHO_PREFIX } from '../types.js';
 import { createKyselyMutationCore, kyselyOperationRowId, } from './kyselyMutationCore.js';
@@ -32,10 +32,10 @@ function rawQuery(queryId, sql, parameters) {
     };
 }
 function reserveLedgerQuery(correlationId, requestHash) {
-    return rawQuery('ablo-idempotency-reserve', `INSERT INTO ablo_idempotency (client_tx_id, response, request_hash)
-     VALUES ($1, $2::jsonb, $3)
+    return rawQuery('ablo-idempotency-reserve', `INSERT INTO ablo_idempotency (client_tx_id, response, request_hash, expires_at)
+     VALUES ($1, $2::jsonb, $3, now() + $4::interval)
      ON CONFLICT (client_tx_id) DO NOTHING
-     RETURNING client_tx_id`, [correlationId, '[]', requestHash]);
+     RETURNING client_tx_id`, [correlationId, '[]', requestHash, SOURCE_IDEMPOTENCY_RETENTION]);
 }
 function completeLedgerQuery(correlationId, rows) {
     return rawQuery('ablo-idempotency-complete', `UPDATE ablo_idempotency

package/dist/source/adapters/prisma.js

@@ -16,7 +16,7 @@
 import { AbloValidationError } from '../../errors.js';
 import { outboxEventSchema } from '../contract.js';
 import { adapterTableMigrations } from '../migrations.js';
-import { assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, sourceChangeIntentHash, } from '../idempotency.js';
+import { assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, SOURCE_IDEMPOTENCY_RETENTION, sourceChangeIntentHash, } from '../idempotency.js';
 import { ABLO_POSTGRES_COMMIT_ECHO_PREFIX, } from '../types.js';
 const lowerFirst = (s) => (s ? s.charAt(0).toLowerCase() + s.slice(1) : s);
 /**
@@ -162,8 +162,8 @@ export function prismaDataSource(prisma, schema, options = {}) {
                correlation_id, transaction_id, occurred_at
              ) VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7, $8)`, `${change.correlationId}:${index}`, op.model, entityId, op.type, JSON.stringify(op.type === 'DELETE' ? null : row), change.correlationId, op.transactionId ?? null, Date.now());
                 }
-                await tx.$executeRawUnsafe(`INSERT INTO ablo_idempotency (client_tx_id, response, request_hash)
-           VALUES ($1, $2::jsonb, $3)`, change.correlationId, JSON.stringify(rows), requestHash);
+                await tx.$executeRawUnsafe(`INSERT INTO ablo_idempotency (client_tx_id, response, request_hash, expires_at)
+           VALUES ($1, $2::jsonb, $3, now() + $4::interval)`, change.correlationId, JSON.stringify(rows), requestHash, SOURCE_IDEMPOTENCY_RETENTION);
                 if (change.echo?.kind === 'postgres-wal') {
                     // Cast the returned LSN to text. `pg_logical_emit_message` yields a
                     // `pg_lsn`, and Prisma's driver adapter can't deserialize that OID

package/dist/source/idempotency.d.ts

@@ -38,9 +38,24 @@ export declare function sourceChangeIntentHash(change: ChangeSet): string;
 /** Fail closed for changed intent and legacy rows that lack hash evidence. */
 export declare function assertSourceIdempotencyIntent(cachedHash: unknown, requestHash: string): void;
 /**
- * Enforce the initial permanent-retention contract. New rows use Postgres
- * `infinity`; this check also fails explicitly if a future bounded-retention
- * policy leaves an expired tombstone. Missing expiry evidence is accepted only
- * for adapters reading rows written before the column existed.
+ * How long a ledger row stays replayable, as a Postgres interval. New rows are
+ * written with `expires_at = now() + this`, so the customer can prune anything
+ * past it — the writer can't (it holds no DELETE, by design), so pruning is a
+ * job for their own admin/cron: `DELETE FROM ablo_idempotency WHERE expires_at <
+ * now()`.
+ *
+ * This is an ops/UX window, not a safety one: {@link assertSourceIdempotencyRetention}
+ * already refuses to replay an expired key (fail-closed), so an expired row can
+ * never be safely re-applied whether or not it has been pruned. The window only
+ * governs how late a retry can still collect its cached response before it's
+ * told to start over. 30 days comfortably covers an offline client's queued
+ * commits while keeping the table bounded.
+ */
+export declare const SOURCE_IDEMPOTENCY_RETENTION = "30 days";
+/**
+ * Enforce the retention contract on replay. A row past its `expires_at` is
+ * refused (fail-closed) rather than re-applied, so pruning expired rows is
+ * always safe. Rows written before the column existed (`infinity`/null) are
+ * accepted — they predate bounded retention and never expire.
  */
 export declare function assertSourceIdempotencyRetention(expiresAt: unknown, now?: number): void;

package/dist/source/idempotency.js

@@ -102,10 +102,25 @@ export function assertSourceIdempotencyIntent(cachedHash, requestHash) {
     }
 }
 /**
- * Enforce the initial permanent-retention contract. New rows use Postgres
- * `infinity`; this check also fails explicitly if a future bounded-retention
- * policy leaves an expired tombstone. Missing expiry evidence is accepted only
- * for adapters reading rows written before the column existed.
+ * How long a ledger row stays replayable, as a Postgres interval. New rows are
+ * written with `expires_at = now() + this`, so the customer can prune anything
+ * past it — the writer can't (it holds no DELETE, by design), so pruning is a
+ * job for their own admin/cron: `DELETE FROM ablo_idempotency WHERE expires_at <
+ * now()`.
+ *
+ * This is an ops/UX window, not a safety one: {@link assertSourceIdempotencyRetention}
+ * already refuses to replay an expired key (fail-closed), so an expired row can
+ * never be safely re-applied whether or not it has been pruned. The window only
+ * governs how late a retry can still collect its cached response before it's
+ * told to start over. 30 days comfortably covers an offline client's queued
+ * commits while keeping the table bounded.
+ */
+export const SOURCE_IDEMPOTENCY_RETENTION = '30 days';
+/**
+ * Enforce the retention contract on replay. A row past its `expires_at` is
+ * refused (fail-closed) rather than re-applied, so pruning expired rows is
+ * always safe. Rows written before the column existed (`infinity`/null) are
+ * accepted — they predate bounded retention and never expire.
  */
 export function assertSourceIdempotencyRetention(expiresAt, now = Date.now()) {
     if (expiresAt == null ||

package/dist/source/migrations.d.ts

@@ -10,7 +10,10 @@
  * it records changes in its own `sync_deltas` log instead.
  */
 import type { Migration } from './contract.js';
-/** The permanent ledger shared by direct and endpoint mutation wrappers. */
+/** The idempotency ledger shared by direct and endpoint mutation wrappers. New
+ *  rows carry a bounded `expires_at` (set by the adapter at write time) so the
+ *  customer can prune them; the `infinity` column default is only a fallback for
+ *  a row inserted without one. */
 export declare function idempotencyLedgerMigrations(): readonly Migration[];
 /** Endpoint-only transactional outbox and its correlation columns. */
 export declare function endpointOutboxMigrations(): readonly Migration[];

package/dist/source/migrations.js

@@ -9,7 +9,32 @@
  * own database when you run a Data Source. Ablo's hosted storage does not use them;
  * it records changes in its own `sync_deltas` log instead.
  */
-/** The permanent ledger shared by direct and endpoint mutation wrappers. */
+/**
+ * Add a column to `ablo_idempotency` only when it is genuinely missing.
+ *
+ * `ADD COLUMN IF NOT EXISTS` performs its ownership check before the existence
+ * short-circuit, so on a ledger owned by another role the no-op re-run still
+ * errors "must be owner of table ablo_idempotency" — the setup's re-run promise
+ * breaks. `pg_attribute` is readable regardless of table ownership, so this DO
+ * block resolves the ledger through the search path and runs the `ALTER` only
+ * when the column is absent — a true no-op on a table that already has it.
+ */
+function addColumnIfAbsent(column, definition) {
+    return `DO $$
+DECLARE ledger regclass := to_regclass('ablo_idempotency');
+BEGIN
+  IF ledger IS NOT NULL AND NOT EXISTS (
+    SELECT 1 FROM pg_attribute
+    WHERE attrelid = ledger AND attname = '${column}' AND attnum > 0 AND NOT attisdropped
+  ) THEN
+    ALTER TABLE ablo_idempotency ADD COLUMN ${column} ${definition};
+  END IF;
+END $$;`;
+}
+/** The idempotency ledger shared by direct and endpoint mutation wrappers. New
+ *  rows carry a bounded `expires_at` (set by the adapter at write time) so the
+ *  customer can prune them; the `infinity` column default is only a fallback for
+ *  a row inserted without one. */
 export function idempotencyLedgerMigrations() {
     return [
         {
@@ -27,13 +52,19 @@ export function idempotencyLedgerMigrations() {
             // Nullable only for rows created by older adapter versions. New writes
             // always populate it; replaying a legacy NULL row fails closed because
             // the adapter cannot prove that the intent matches.
-            up: `ALTER TABLE ablo_idempotency
-  ADD COLUMN IF NOT EXISTS request_hash TEXT;`,
+            //
+            // The column already exists on any current table (the CREATE above
+            // includes it), so this only matters when upgrading a pre-existing
+            // ledger. `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` checks ownership
+            // BEFORE it evaluates IF NOT EXISTS, so on a ledger that predates the
+            // setup — owned by another role — the no-op still errors "must be owner".
+            // Guard on the catalog (readable regardless of ownership) so the ALTER
+            // runs only when the column is genuinely absent, keeping re-runs safe.
+            up: addColumnIfAbsent('request_hash', 'TEXT'),
         },
         {
             name: 'ablo_idempotency_permanent_retention',
-            up: `ALTER TABLE ablo_idempotency
-  ADD COLUMN IF NOT EXISTS expires_at TIMESTAMPTZ NOT NULL DEFAULT 'infinity';`,
+            up: addColumnIfAbsent('expires_at', `TIMESTAMPTZ NOT NULL DEFAULT 'infinity'`),
         },
     ];
 }

package/docs/agent-messaging.md

@@ -9,7 +9,7 @@ HTTP, or be replayed from the sync cursor.
 
 | Need | Use | Why |
 | --- | --- | --- |
-| "I am holding this row because..." | `claim({ reason, description, meta })` | Live and low-latency. Peers see it through presence while the claim exists. |
+| "I am holding this row because..." | `claim({ description, meta })` | Live and low-latency. Peers see it through presence while the claim exists. |
 | "Remember this handoff/status/request" | A `messages` model | Durable row. Ordered in `sync_deltas`, replayed after reconnect, readable by HTTP agents. |
 
 Claim context is ephemeral. If a participant was offline, reconnected later, or
@@ -90,7 +90,6 @@ about work currently protected by a claim.
 ```ts
 const claim = await ablo.workItems.claim({
   id: workItemId,
-  reason: "reformatting",
   description: "normalizing the pricing table",
   meta: { estimateSeconds: 120 },
   queue: false,

package/docs/api.md

@@ -124,7 +124,7 @@ coordination surface is `claim.state({ id })` / `claim.queue({ id })` /
 | `id` | string | Unique identifier for the claim. |
 | `status` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'` | The whole lifecycle, in one field. `active` is the holder; `queued` is a waiter in the FIFO line behind it. |
 | `target` | `{ type, id, field? }` | What is being coordinated. |
-| `reason` | string | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. Serialized on the wire as `action`. |
+| `description` | string | Peer-visible phrase for the work in progress — `'editing'`, `'writing'`, `'reviewing the risk section'`. Defaults to `'editing'`, and rides back in the rejection a blocked writer receives. |
 | `heldBy` | string | Participant id holding the claim. |
 | `participantKind` | `'user' \| 'agent' \| 'system'` | Who's behind it — a human (`user`), an AI (`agent`), or automated infrastructure (`system`). |
 | `createdAt` | number? | Ms-epoch the holder opened it. Optional — derived shapes may omit it. |
@@ -136,7 +136,7 @@ coordination surface is `claim.state({ id })` / `claim.queue({ id })` /
   "id": "claim_3MtwBwLkdIwHu7ix",
   "status": "active",
   "target": { "type": "weatherReports", "id": "report_stockholm", "field": "status" },
-  "reason": "editing",
+  "description": "editing",
   "heldBy": "agent:report-writer",
   "participantKind": "agent",
   "expiresAt": 1716580000000
@@ -176,12 +176,12 @@ Reads never block on a claim — to wait for a row to free up, `claim({ id })` i
 const claim = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 if (claim) {
   claim.heldBy;
-  claim.reason;
+  claim.description;
 }
 
 const handle = await ablo.weatherReports.claim({
   id: 'report_stockholm',
-  reason: 'editing',
+  description: 'editing',
   ttl: '2m',
 });
 await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' } });