@abloatai/transaction 0.55.0 → 0.57.0

package/src/resources/modelCreate.ts

@@ -0,0 +1,73 @@
+/** Canonical create identity and result correlation shared by every client. */
+
+import { v5 as uuidv5 } from 'uuid';
+import { AbloConnectionError } from '../errors.js';
+import type { CommitOperationResult } from '../wire/commit.js';
+
+/** Resolve the two supported single-create id spellings. The sibling wins. */
+export function resolveCreateId(
+  explicitId: string | null | undefined,
+  data: unknown,
+): string | undefined {
+  if (typeof explicitId === 'string' && explicitId.length > 0) return explicitId;
+  const inData =
+    typeof data === 'object' && data !== null
+      ? (data as { readonly id?: unknown }).id
+      : undefined;
+  return typeof inData === 'string' && inData.length > 0 ? inData : undefined;
+}
+
+/** Stable across transports and client instances when an idempotency key is supplied. */
+export function createModelId(
+  modelName: string,
+  idempotencyKey?: string | null,
+): string {
+  if (idempotencyKey) {
+    return uuidv5(
+      `${modelName}:${idempotencyKey}`,
+      'aa4ba6d4-bf0b-5b38-9c45-116f79a6e548',
+    );
+  }
+  return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * Return server-authored create rows in input order.
+ *
+ * Fresh receipts carry operationResults. Durable idempotency replays redact
+ * row data, so that path verifies every expected id with a point read. It may
+ * fail under a write-only policy, but it can never report a partial collection
+ * as success.
+ */
+export async function resolveCreatedRows<T>(input: {
+  readonly modelName: string;
+  readonly ids: readonly string[];
+  readonly operationResults?: readonly CommitOperationResult[];
+  readonly readRow: (id: string) => Promise<T | undefined>;
+}): Promise<T[]> {
+  if (input.operationResults?.length === input.ids.length) {
+    const byId = new Map(
+      input.operationResults.map((result) => [
+        (result.row as { readonly id?: unknown }).id,
+        result.row,
+      ]),
+    );
+    const ordered = input.ids.map((id) => byId.get(id));
+    if (ordered.every((row): row is Record<string, unknown> => row !== undefined)) {
+      return ordered as T[];
+    }
+  }
+
+  const rows = await Promise.all(input.ids.map((id) => input.readRow(id)));
+  const missing = input.ids.filter((_id, index) => rows[index] === undefined);
+  if (missing.length > 0) {
+    throw new AbloConnectionError(
+      `${input.modelName} create confirmed, but ${missing.length} of ${input.ids.length} ` +
+        'server rows could not be recovered from its receipt or verified by id.',
+      { code: 'commit_no_result', details: { missingIds: missing } },
+    );
+  }
+  return rows as T[];
+}

package/src/resources/modelOperations.ts

@@ -15,7 +15,7 @@ import type { ResolveClaimMeta } from '../types/global.js';
 import type { AbloError } from '../errors.js';
 import type { StaleNotification, TrackDependency } from '../coordination/schema.js';
 import type { FieldRef, FieldSelector } from '../schema/fieldRef.js';
-import type { BaseModelFields } from '../schema/schema.js';
+import type { BaseModelFields, Clearable } from '../schema/schema.js';
 import type { ClaimHeartbeatPlan } from '../coordination/claimHeartbeatLoop.js';
 import type { Duration } from '../utils/duration.js';
 import type {
@@ -232,6 +232,14 @@ export interface ServerReadOptions<T> {
   expand?: readonly string[];
 }
 
+/** Options for an explicit complete collection traversal. */
+export interface ListAllOptions<T> extends Omit<ServerReadOptions<T>, 'cursor'> {
+  /** Maximum pages to read before refusing an unexpectedly broad traversal. @default 100 */
+  maxPages?: number;
+  /** Stops traversal between page requests and row yields. */
+  signal?: AbortSignal;
+}
+
 /** Options for the single-row async server read `get({ id })`. A subset of
  *  {@link ServerReadOptions} — `where`/`limit`/`orderBy` are fixed by the id. */
 export type ServerRetrieveOptions = Pick<ServerReadOptions<unknown>, 'type' | 'expand'>;
@@ -588,6 +596,21 @@ export interface ModelCreateParams<T, CreateInput>
   readonly claim?: Claim<T> | ClaimTargetOptions<CreateInput> | null;
 }
 
+/**
+ * Creating many rows at once: the same verb, handed a list.
+ *
+ * One atomic commit, so the batch lands whole or not at all, and the rows come
+ * back in the order they were given. There is no `id` beside `data` here the
+ * way there is for a single create, since one id cannot address many rows;
+ * write it into each row instead, which the create input has always allowed.
+ */
+export type ModelCreateManyParams<CreateInput> = Pick<
+  ModelWriteOptions,
+  'idempotencyKey' | 'reads' | 'track'
+> & {
+  readonly data: readonly CreateInput[];
+};
+
 export interface ModelUpdateParams<T, Fields = T>
   extends ModelWriteOptions {
   readonly id: string;
@@ -595,8 +618,12 @@ export interface ModelUpdateParams<T, Fields = T>
    * Patch only fields declared by the model's Zod input shape. Hydrated rows
    * also carry framework fields, relations, methods, and computed values; none
    * of those are writable data.
+   *
+   * Send a field to change it, omit it to leave it, send `null` to clear it —
+   * see {@link Clearable}. `undefined` is not a clear: it is dropped from the
+   * payload and the old value survives.
    */
-  readonly data: Partial<ClaimableFields<Fields>>;
+  readonly data: Clearable<ClaimableFields<Fields>>;
   readonly claim?: Claim<T> | ClaimTargetOptions<Fields> | null;
 }
 

package/src/resources/writeOptionsSchema.ts

@@ -17,6 +17,7 @@
  */
 
 import { z } from 'zod';
+import { logPositionSchema } from '../syncLog/contract.js';
 import type { MutationOptions } from '../resources/mutationOptions.js';
 import { AbloValidationError } from '../errors.js';
 import { commitWaitSchema } from '../wire/commit.js';
@@ -24,7 +25,6 @@ import {
   onStaleModeSchema,
   MAX_READ_SET_ENTRIES,
   readDependencyListSchema,
-  readSetWatermarkSchema,
   readSetProjectionEntryCount,
   trackDependencyListSchema,
 } from '../coordination/schema.js';
@@ -46,7 +46,7 @@ export const writeOptionsSchema = z.object({
   /** Resolve when queued locally (default) or once the server confirms. */
   wait: commitWaitSchema.optional(),
   /** Stale guard: the sync watermark the caller's reasoning was based on. */
-  readAt: readSetWatermarkSchema.nullish(),
+  readAt: logPositionSchema.nullish(),
   /** What the server does when the target moved past `readAt`. */
   onStale: onStaleModeSchema.nullish(),
   /** The held claim's fencing token (Option B), sourced from the claim handle
@@ -107,3 +107,31 @@ const _writeOptionsContractInSync: AssertExact<
   keyof WriteOptionsContract
 > = true;
 void _writeOptionsContractInSync;
+
+/**
+ * Refuse a per-model write that does not name its row.
+ *
+ * `update` and `delete` address the row through the URL, so an absent `id`
+ * used to be spelled into the path by `encodeURIComponent` as the literal
+ * string `"undefined"`. The request was well-formed, it matched no row, and it
+ * came back as an ordinary receipt: `delete({ where: { id } })` reported
+ * success and deleted nothing. `{ where }` is the shape the commit protocol
+ * takes one layer down, so reaching for it here is an easy and quiet mistake.
+ *
+ * The typed surface already rejects it at compile time. This is the same
+ * refusal for callers who reach the transport without those types.
+ */
+export function assertWriteTarget(
+  action: 'update' | 'delete',
+  modelName: string,
+  id: unknown,
+): void {
+  if (typeof id === 'string' && id.length > 0) return;
+  const namedAFilter =
+    typeof id === 'object' && id !== null && 'where' in (id as Record<string, unknown>);
+  throw new AbloValidationError(
+    `A ${modelName} ${action} has to name the row it acts on: ${action}({ id })` +
+      (namedAFilter ? ', not a `where` filter.' : '.'),
+    { code: 'invalid_body', param: 'id' },
+  );
+}

package/src/schema/audit.ts

@@ -0,0 +1,121 @@
+import type { ModelJSON, SchemaJSON } from './serialize.js';
+import { resolveTenancy } from './tenancy.js';
+
+export interface SchemaAuditFinding {
+  readonly code: 'scope_routing_without_access_policy';
+  readonly severity: 'error';
+  readonly model: string;
+  readonly message: string;
+  readonly fix: string;
+}
+
+interface RoutingAnchor {
+  readonly description: string;
+  readonly column: string;
+  readonly parentTable?: string;
+}
+
+function tableName(key: string, model: ModelJSON): string {
+  return model.tableName ?? key;
+}
+
+function fieldColumn(model: ModelJSON, field: string): string {
+  return model.fields[field]?.column ?? field;
+}
+
+function camelToSnake(value: string): string {
+  return value.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+
+function reachesScope(
+  key: string,
+  models: SchemaJSON['models'],
+  seen: ReadonlySet<string> = new Set(),
+): boolean {
+  if (seen.has(key)) return false;
+  const model = models[key];
+  if (!model) return false;
+  if (model.scope) return true;
+  const nextSeen = new Set(seen).add(key);
+  return Object.values(model.relations).some(
+    (relation) => relation.type === 'belongsTo' && reachesScope(relation.target, models, nextSeen),
+  );
+}
+
+function routingAnchors(
+  model: ModelJSON,
+  models: SchemaJSON['models'],
+): readonly RoutingAnchor[] {
+  const anchors: RoutingAnchor[] = [];
+
+  if (model.scope) {
+    anchors.push({ description: `scope root ${String(model.scope)}`, column: 'id' });
+  }
+
+  for (const role of model.entityRoles ?? []) {
+    anchors.push({
+      description: `entity role ${role.kind}`,
+      column: fieldColumn(model, role.source.field),
+    });
+  }
+
+  for (const [relationName, relation] of Object.entries(model.relations)) {
+    if (relation.type !== 'belongsTo' || !reachesScope(relation.target, models)) continue;
+    const target = models[relation.target];
+    if (!target) continue;
+    anchors.push({
+      description: `parent scope ${relationName}`,
+      column: relation.foreignKeyColumn,
+      parentTable: tableName(relation.target, target),
+    });
+  }
+
+  return anchors;
+}
+
+function policyMatches(anchor: RoutingAnchor, model: ModelJSON): boolean {
+  const tenancy = resolveTenancy(model);
+  if (tenancy.kind === 'source') return true;
+  if (tenancy.kind === 'column') {
+    return tenancy.column === anchor.column || tenancy.column === camelToSnake(anchor.column);
+  }
+  if (tenancy.kind === 'parent') {
+    return tenancy.via.localKey === anchor.column &&
+      (anchor.parentTable === undefined || tenancy.via.parentTable === anchor.parentTable);
+  }
+  return false;
+}
+
+/**
+ * Finds mutable models whose sync-group routing is narrower than their row-read
+ * policy. A correctly filtered list or routed stream is not evidence that a
+ * foreign row is unreadable; only the policy is the authorization boundary.
+ */
+export function auditSchemaAccessPolicies(schema: SchemaJSON): readonly SchemaAuditFinding[] {
+  const findings: SchemaAuditFinding[] = [];
+
+  for (const [key, model] of Object.entries(schema.models)) {
+    if (model.mutable === false || model.routingOnly === true) continue;
+    const mismatched = routingAnchors(model, schema.models)
+      .filter((anchor) => !policyMatches(anchor, model));
+    if (mismatched.length === 0) continue;
+
+    const policy = resolveTenancy(model);
+    const routedBy = mismatched.map(({ description, column }) => `${description} (${column})`).join(', ');
+    findings.push({
+      code: 'scope_routing_without_access_policy',
+      severity: 'error',
+      model: key,
+      message:
+        `Model "${key}" routes changes by ${routedBy}, but its row-access policy is ` +
+        `by ${policy.kind}. Sync groups route delivery; they do not authorize reads. ` +
+        `A filtered list or correctly routed live stream is not an authorization proof.`,
+      fix:
+        `Make policy follow the same customer/workspace boundary on every reachable model, ` +
+        `use policy: { by: 'source' } with one Ablo organization per hard tenant, or set ` +
+        `groups.routingOnly: true to explicitly acknowledge an intentionally broader read policy.`,
+    });
+  }
+
+  return findings;
+}

package/src/schema/ddl.ts

@@ -27,6 +27,7 @@ import type { SchemaJSON, ModelJSON } from './serialize.js';
 import type { MigrationStep, BackfillValue, FieldType } from './diff.js';
 import type { FieldMeta } from './field.js';
 import { resolveTenancy, tenancyColumn } from './tenancy.js';
+import type { SubjectRule } from './subject.js';
 
 export interface ProvisionPlan {
   /** The Postgres schema the tables live in (`app_<id>` or `public`). */
@@ -119,6 +120,22 @@ export function sqlType(fieldType: ModelJSON['fields'][string]['type']): string
 
 const BASE_COLUMNS = new Set(['id']);
 
+function subjectPredicate(model: ModelJSON, rule: SubjectRule): string {
+  const meta = model.fields[rule.field];
+  if (!meta) {
+    throw new AbloValidationError(`subject field ${JSON.stringify(rule.field)} is not declared`, {
+      code: 'schema_definition_invalid',
+      param: 'subject.field',
+    });
+  }
+  const column = meta.column ?? camelToSnake(rule.field);
+  const prefix = `${rule.group}:`.replace(/'/g, "''");
+  return (
+    `COALESCE(NULLIF(current_setting('app.current_subject_groups', true), ''), '[]')::jsonb ` +
+    `? ('${prefix}' || ${q(column)}::text)`
+  );
+}
+
 // ── Foreign keys (relation-driven, sync-safe) ────────────────────────────────
 
 /**
@@ -324,7 +341,20 @@ export function generateProvisionPlan(
       statements.push(`ALTER TABLE ${qt} ENABLE ROW LEVEL SECURITY;`);
       statements.push(`ALTER TABLE ${qt} FORCE ROW LEVEL SECURITY;`);
       const policy = `${table}_tenant_isolation`;
-      const predicate = `${q(orgCol)} = current_setting('app.current_org_id', true)`;
+      const predicates = [
+        `${q(orgCol)} = current_setting('app.current_org_id', true)`,
+        ...(model.subject ? [subjectPredicate(model, model.subject)] : []),
+      ];
+      const predicate = predicates.length === 1
+        ? predicates[0]!
+        : predicates.map((part) => `(${part})`).join(' AND ');
+      statements.push(`DROP POLICY IF EXISTS ${q(policy)} ON ${qt};`);
+      statements.push(`CREATE POLICY ${q(policy)} ON ${qt}\n  USING (${predicate})\n  WITH CHECK (${predicate});`);
+    } else if (model.subject) {
+      statements.push(`ALTER TABLE ${qt} ENABLE ROW LEVEL SECURITY;`);
+      statements.push(`ALTER TABLE ${qt} FORCE ROW LEVEL SECURITY;`);
+      const policy = `${table}_subject_isolation`;
+      const predicate = subjectPredicate(model, model.subject);
       statements.push(`DROP POLICY IF EXISTS ${q(policy)} ON ${qt};`);
       statements.push(`CREATE POLICY ${q(policy)} ON ${qt}\n  USING (${predicate})\n  WITH CHECK (${predicate});`);
     }
@@ -585,5 +615,45 @@ export function generateMigrationPlan(
     }
   }
 
+  // Subject authorization is metadata rather than a field diff. Reconcile when
+  // that metadata changes, or when the protected field's physical column
+  // changes. An identical empty migration must remain a true no-op.
+  for (const [key, model] of Object.entries(next.models)) {
+    if ((model.plane ?? 'tenant') === 'control') continue;
+    const previousModel = prev?.models[key];
+    const subjectChanged = JSON.stringify(previousModel?.subject) !== JSON.stringify(model.subject);
+    const subjectColumnChanged = steps.some((step) =>
+      'model' in step && step.model === key &&
+      step.kind === 'alter_field' &&
+      (step.field === model.subject?.field || step.field === previousModel?.subject?.field) &&
+      step.changes.column !== undefined
+    );
+    if (!subjectChanged && !subjectColumnChanged) continue;
+    const table = model.tableName ?? key;
+    const qt = qtFor(table);
+    const orgCol = tenancyColumn(resolveTenancy(model));
+    const tenantPolicy = `${table}_tenant_isolation`;
+    const subjectPolicy = `${table}_subject_isolation`;
+    if (orgCol || model.subject) {
+      statements.push(`ALTER TABLE ${qt} ENABLE ROW LEVEL SECURITY;`);
+      statements.push(`ALTER TABLE ${qt} FORCE ROW LEVEL SECURITY;`);
+      statements.push(`DROP POLICY IF EXISTS ${q(tenantPolicy)} ON ${qt};`);
+      statements.push(`DROP POLICY IF EXISTS ${q(subjectPolicy)} ON ${qt};`);
+      const parts = [
+        ...(orgCol ? [`${q(orgCol)} = current_setting('app.current_org_id', true)`] : []),
+        ...(model.subject ? [subjectPredicate(model, model.subject)] : []),
+      ];
+      const predicate = parts.length === 1
+        ? parts[0]!
+        : parts.map((part) => `(${part})`).join(' AND ');
+      const policy = orgCol ? tenantPolicy : subjectPolicy;
+      statements.push(`CREATE POLICY ${q(policy)} ON ${qt}\n  USING (${predicate})\n  WITH CHECK (${predicate});`);
+    } else if (previousModel?.subject) {
+      statements.push(`DROP POLICY IF EXISTS ${q(subjectPolicy)} ON ${qt};`);
+      statements.push(`ALTER TABLE ${qt} NO FORCE ROW LEVEL SECURITY;`);
+      statements.push(`ALTER TABLE ${qt} DISABLE ROW LEVEL SECURITY;`);
+    }
+  }
+
   return { appSchema: targetSchema, statements, concurrent };
 }

package/src/schema/index.ts

@@ -154,12 +154,16 @@ export {
   type InsertValue,
   type UpsertValue,
   type UpdateValue,
+  type Clearable,
   type DeleteId,
   type DefineSchemaOptions,
   type Casing,
   type CasingConvention,
   type CasingFn,
   composeEntitySyncGroups,
+  syncGroupsForRow,
+  InvalidRecordSubjectError,
+  type RecordSyncGroupSpec,
   intersectRequestedWithAllowed,
   type IdentityRole,
   type IdentityContext,
@@ -210,6 +214,18 @@ export {
   type RelationJSON,
 } from './serialize.js';
 
+export {
+  auditSchemaAccessPolicies,
+  type SchemaAuditFinding,
+} from './audit.js';
+
+export {
+  subjectRuleSchema,
+  subjectGroupForRow,
+  subjectAuthorized,
+  type SubjectRule,
+} from './subject.js';
+
 // Schema projection — derive an app's subset from one canonical schema.
 export { selectModels, omitModels, omittedModelError } from './select.js';
 

package/src/schema/model.ts

@@ -21,6 +21,7 @@
 import { z } from 'zod';
 import type { RelationDef } from './relation.js';
 import type { EntityRole, GroupsInput } from './roles.js';
+import type { SubjectRule } from './subject.js';
 import { getFieldMeta, inferFieldMetaFromZod, type FieldMeta } from './field.js';
 // Tenancy lives in `tenancy.ts`. Authoring uses the `policy` option
 // (`PolicyInput`), which `resolvePolicy` normalizes into the canonical `Tenancy`
@@ -152,6 +153,14 @@ export interface ModelOptions {
    */
   policy?: PolicyInput;
 
+  /**
+   * Credential-bound row authorization below organization tenancy. The named
+   * row field must match a trusted credential group: `{ field: 'workspaceId',
+   * group: 'workspace' }` authorizes only rows whose `workspaceId` has a
+   * matching `workspace:<id>` group on the request.
+   */
+  subject?: SubjectRule;
+
   /**
    * Which database a model's rows live in. `tenant` (the default) is tenant data
    * that provisioning places in the customer's own database; `control` is Ablo's own
@@ -176,6 +185,8 @@ export interface ModelOptions {
    * - `roles` — explicit record-to-group roles keyed on a plain field, for routing
    *   that does not follow a relation, such as fanning a message into a recipient's
    *   inbox. Accepts one role or many.
+   * - `routingOnly: true` — explicitly acknowledges that these delivery groups
+   *   are intentionally narrower than the model's independently safe read policy.
    *
    * ```ts
    * // archiveMember: { userId, archiveId }
@@ -353,6 +364,8 @@ export interface ModelDef<
   /** The canonical tenancy descriptor for this model, normalized from the `policy`
    *  option at build time. See {@link ModelOptions.policy}. */
   readonly tenancy: Tenancy;
+  /** Credential-bound row authorization. See {@link ModelOptions.subject}. */
+  readonly subject?: SubjectRule;
   /** Which database this model's rows live in — `tenant` (default) can be a
    *  customer's own database; `control` is Ablo's. See {@link ModelOptions.plane}. */
   readonly plane?: ModelResidency;
@@ -362,6 +375,8 @@ export interface ModelDef<
   readonly grants?: GrantsRef;
   /** Explicit record-to-group roles, normalized to an array. See {@link ModelOptions.groups}. */
   readonly entityRoles?: readonly EntityRole[];
+  /** Explicit acknowledgement that sync groups are routing, not row access. */
+  readonly routingOnly?: true;
   /** The write-conflict disposition per committer kind, carried as plain data. See
    *  {@link ModelOptions.conflict}. */
   readonly conflict?: ConflictAxis;
@@ -445,11 +460,13 @@ export function model<
     // Normalize the `policy` option into the canonical tenancy descriptor (defaults
     // to a row-local organization column).
     tenancy: resolvePolicy(options?.policy),
+    subject: options?.subject,
     plane: options?.plane ?? DEFAULT_RESIDENCY,
     // Unpack the `groups` option into the individual routing fields the server reads.
     scope: options?.groups?.root,
     grants: options?.groups?.grants,
     entityRoles: normalizeEntityRoles(options?.groups?.roles),
+    routingOnly: options?.groups?.routingOnly,
     // The conflict disposition is already plain data, so it passes through unchanged.
     conflict: options?.conflict,
     mutable: options?.mutable ?? true,

package/src/schema/openapi.ts

@@ -53,6 +53,20 @@ import {
   claimReleaseReplySchema,
 } from '../wire/claims.js';
 import { errorEnvelopeSchema } from '../wire/errorEnvelope.js';
+// The lifecycle promise and the rate-limit fields are contract, not prose about
+// contract: the document renders the same constants the server emits, so the
+// published policy cannot describe a signal the runtime does not send.
+import {
+  API_DEPRECATION_HEADER,
+  API_LIFECYCLE,
+  API_SUNSET_HEADER,
+  API_VERSION_HEADER,
+} from '../wire/apiLifecycle.js';
+import {
+  RATE_LIMIT_HEADER,
+  RATE_LIMIT_POLICY_HEADER,
+  RETRY_AFTER_HEADER,
+} from '../wire/rateLimit.js';
 import { modelReadResponseSchema, modelListResponseSchema } from '../wire/modelResponses.js';
 import { modelMutationRequestSchema } from '../wire/modelMutations.js';
 import { logListResponseSchema, logQuerySchema } from '../wire/feedEvent.js';
@@ -400,6 +414,106 @@ const claimIdParam = (): Json => ({
  */
 const commitBody = (): Json => jsonBody(derive(commitRequestSchema, 'input'));
 
+/**
+ * The response headers every operation carries, declared once under
+ * `components/headers` and referenced from each response.
+ *
+ * A header a caller is expected to act on has to be IN the document to be
+ * actionable: a generated client surfaces what the spec declares and drops what
+ * it does not, so an undeclared `RateLimit` is a header the caller never sees
+ * and therefore never paces against. Declaring them here rather than at each
+ * response is what keeps one description of each — the reason the names are
+ * imported rather than typed out.
+ */
+const RESPONSE_HEADER_COMPONENTS: Readonly<Record<string, Json>> = {
+  AbloVersion: {
+    description:
+      'The date-stamped contract version this response was served under. Record ' +
+      'the value your integration was built against; a change means something ' +
+      'observable was added.',
+    schema: { type: 'string', examples: ['2026-08-15'] },
+  },
+  RateLimitPolicy: {
+    description:
+      'The standing allowance for this credential kind, as a Structured Fields ' +
+      'List: `"secret";q=600;w=12`. It does not move between responses, so read ' +
+      'it once and pace against it.',
+    schema: { type: 'string', examples: ['"secret";q=600;w=12'] },
+  },
+  RateLimit: {
+    description:
+      'This caller\u2019s live position in the allowance: `r` units left, `t` ' +
+      'seconds until they refill. Present once the request is attributed to a ' +
+      'credential.',
+    schema: { type: 'string', examples: ['"secret";r=412;t=8'] },
+  },
+  RetryAfter: {
+    description: 'Whole seconds to wait before retrying. Sent with 429 and 503.',
+    schema: { type: 'integer', minimum: 1, examples: [8] },
+  },
+  RequestId: {
+    description:
+      'Correlation id for this request, repeated in the error envelope\u2019s ' +
+      '`request_id`. Quote it in a support request.',
+    schema: { type: 'string', examples: ['req_52bb7f46-17bc-4f2d-9988-89d1398d2990'] },
+  },
+  Deprecation: {
+    description:
+      'Present only on a route being withdrawn: an sf-Date of when the ' +
+      'deprecation took effect (RFC 9745). The route still answers normally.',
+    schema: { type: 'string', examples: ['@1774483200'] },
+  },
+  Sunset: {
+    description:
+      'Present only on a route being withdrawn: the HTTP-date it stops ' +
+      'answering (RFC 8594). Never less than the published notice window after ' +
+      `\`${API_DEPRECATION_HEADER}\`.`,
+    schema: { type: 'string', examples: ['Tue, 08 Sep 2026 00:00:00 GMT'] },
+  },
+};
+
+const headerRef = (name: string): Json => ({ $ref: `#/components/headers/${name}` });
+
+/** Carried by every response, whatever its status. */
+const UNIVERSAL_RESPONSE_HEADERS: Readonly<Record<string, Json>> = {
+  [API_VERSION_HEADER]: headerRef('AbloVersion'),
+  'X-Request-Id': headerRef('RequestId'),
+  [RATE_LIMIT_POLICY_HEADER]: headerRef('RateLimitPolicy'),
+  [RATE_LIMIT_HEADER]: headerRef('RateLimit'),
+  [API_DEPRECATION_HEADER]: headerRef('Deprecation'),
+  [API_SUNSET_HEADER]: headerRef('Sunset'),
+};
+
+/** Statuses where a wait is what resolves the failure, so `Retry-After` is sent. */
+const RETRY_AFTER_STATUSES = new Set(['429', '503']);
+
+/**
+ * Stamp the documented headers onto every response of every operation.
+ *
+ * Runs after the responses are built — including the canonical error ones — so
+ * a response added later cannot quietly ship without them.
+ */
+function attachResponseHeaders(paths: Json): void {
+  for (const rawPathItem of Object.values(paths)) {
+    const pathItem = rawPathItem as Json;
+    for (const [method, rawOperation] of Object.entries(pathItem)) {
+      if (!HTTP_METHODS.has(method)) continue;
+      const operation = rawOperation as Json;
+      const responses = (operation.responses ?? {}) as Json;
+      for (const [status, rawResponse] of Object.entries(responses)) {
+        const response = rawResponse as Json;
+        response.headers = {
+          ...UNIVERSAL_RESPONSE_HEADERS,
+          ...(RETRY_AFTER_STATUSES.has(status)
+            ? { [RETRY_AFTER_HEADER]: headerRef('RetryAfter') }
+            : {}),
+          ...((response.headers as Json | undefined) ?? {}),
+        };
+      }
+    }
+  }
+}
+
 /** The envelope shared by both specs — same server, same auth, same version. */
 function envelope(options: SchemaToOpenApiOptions, description: string, paths: Json, schemas: Record<string, Json>): Json {
   return {
@@ -407,7 +521,11 @@ function envelope(options: SchemaToOpenApiOptions, description: string, paths: J
     info: {
       title: options.title ?? 'Ablo API',
       version: options.version ?? 'development',
-      description,
+      // The lifecycle policy travels WITH the routes it governs. An agent
+      // deciding whether to integrate needs to know the surface will not move
+      // under it, and a policy published somewhere else is one it has to go
+      // find — so the document that describes the calls describes the promise.
+      description: `${description}\n\n${API_LIFECYCLE}`,
       license: {
         name: 'Apache License 2.0',
         identifier: 'Apache-2.0',
@@ -417,8 +535,9 @@ function envelope(options: SchemaToOpenApiOptions, description: string, paths: J
     security: [{ bearerAuth: [] }],
     components: {
       securitySchemes: {
-        bearerAuth: { type: 'http', scheme: 'bearer', description: 'Your Ablo API key (sk_… / rk_…).' },
+        bearerAuth: { type: 'http', scheme: 'bearer', description: 'Your Ablo API key (sk_\u2026 / rk_\u2026).' },
       },
+      headers: { ...RESPONSE_HEADER_COMPONENTS },
       schemas,
     },
     paths,
@@ -950,6 +1069,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
 
   applyOperationIds(paths, ABLO_OPERATION_IDS);
   attachCanonicalErrors(paths);
+  attachResponseHeaders(paths);
 
   return envelope(
     options,
@@ -1078,6 +1198,7 @@ export function schemaToOpenApi<S extends SchemaRecord>(
   operationIds['GET /v1/commits/{id}'] = 'getCommit';
   applyOperationIds(paths, operationIds);
   attachCanonicalErrors(paths);
+  attachResponseHeaders(paths);
 
   Object.assign(schemas, abloComponentSchemas());