@abloatai/transaction 0.48.0 → 0.49.0

package/src/coordination/targetConflict.ts

@@ -12,7 +12,7 @@ import type { ClaimTargetDetails } from './locator.js';
  * two places to land and no way to notice when it landed in one. It is one
  * definition here, and both authorities import it.
  *
- * It lives in the settlement core rather than the server because it is the rule
+ * It lives in the confirmation core rather than the server because it is the rule
  * itself, not a deployment of it: a claim authority running against a
  * developer's own database has to answer this question exactly the same way,
  * and a client that wants to predict a refusal before paying for the round trip

package/src/durableWrites.ts

@@ -3,7 +3,7 @@
  *
  * Owns the persistence contract behind `Ablo({ durableWrites })` — a behavior
  * contract of methods, not a serialized shape, which is why it lives here
- * rather than in `transactions/settlement/`. The records that cross this port
+ * rather than in `transactions/confirmation/`. The records that cross this port
  * are owned by `pendingWriteSchema` there; this module never redescribes them.
  *
  * The engine consumes the port through `commitOutboxStore`, and the HTTP client
@@ -12,8 +12,8 @@
 
 import { z } from 'zod';
 import { AbloValidationError } from './errors.js';
-import type { CommitOutboxScope } from './transactions/settlement/commitEnvelope.js';
-import type { PendingWrite } from './transactions/settlement/pendingWrite.js';
+import type { CommitOutboxScope } from './transactions/confirmation/commitEnvelope.js';
+import type { PendingWrite } from './transactions/confirmation/pendingWrite.js';
 
 /**
  * Persistence port used by `Ablo({ durableWrites })`.

package/src/errorCodes.ts

@@ -39,7 +39,7 @@ import { z } from 'zod';
  * error documentation and returned on the `Ablo-Version` response header, so a
  * consumer can detect when its expected contract has drifted from the server's.
  */
-export const ERROR_CONTRACT_VERSION = '2026-08-03';
+export const ERROR_CONTRACT_VERSION = '2026-08-04';
 
 /** A coarse grouping of error codes, used to organize metrics and documentation. */
 export type ErrorCategory =
@@ -129,6 +129,36 @@ export interface ErrorCodeSpec {
    * this field can be left unset.
    */
   readonly recovery?: RecoveryClass;
+  /** Exhaustive sink and alert policy for this code. */
+  readonly observability: ErrorObservabilityPolicy;
+}
+
+export interface ErrorObservabilityPolicy {
+  readonly severity: 'info' | 'warning' | 'error' | 'fatal';
+  readonly sentry: 'log' | 'issue';
+  readonly pagingEligible: boolean;
+  readonly expectedVolume: 'low' | 'normal' | 'high';
+  readonly owner: 'platform' | 'product';
+}
+
+function observabilityPolicy(
+  category: ErrorCategory,
+  httpStatus: number | undefined,
+  operational = false,
+): ErrorObservabilityPolicy {
+  if ((httpStatus ?? 0) >= 500) {
+    return { severity: 'error', sentry: 'issue', pagingEligible: true, expectedVolume: 'low', owner: 'platform' };
+  }
+  if (operational) {
+    return { severity: 'warning', sentry: 'issue', pagingEligible: false, expectedVolume: 'low', owner: 'platform' };
+  }
+  return {
+    severity: category === 'auth' ? 'info' : 'warning',
+    sentry: 'log',
+    pagingEligible: false,
+    expectedVolume: category === 'auth' ? 'high' : 'normal',
+    owner: 'product',
+  };
 }
 
 const wire = (
@@ -136,8 +166,17 @@ const wire = (
   httpStatus: number,
   retryable: boolean,
   message: string,
-  recovery?: RecoveryClass
-): ErrorCodeSpec => ({ category, surface: 'wire', httpStatus, retryable, message, recovery });
+  recovery?: RecoveryClass,
+  operational = false,
+): ErrorCodeSpec => ({
+  category,
+  surface: 'wire',
+  httpStatus,
+  retryable,
+  message,
+  recovery,
+  observability: observabilityPolicy(category, httpStatus, operational),
+});
 
 const client = (
   category: ErrorCategory,
@@ -147,6 +186,7 @@ const client = (
   category,
   surface: 'client',
   retryable: false,
+  observability: observabilityPolicy(category, undefined),
   message,
   ...(recovery !== undefined ? { recovery } : {}),
 });
@@ -234,6 +274,18 @@ export const ERROR_CODES = {
     'Your session has expired or is no longer valid. Sign in again to continue.',
     'session_expiry'
   ),
+  better_auth_request_failed: wire(
+    'auth',
+    400,
+    false,
+    'The authentication request was rejected. Check the submitted credentials or request and try again.'
+  ),
+  better_auth_upstream_failed: wire(
+    'server',
+    500,
+    true,
+    'The authentication service could not complete the request. Retry the request; if it continues to fail, contact support.'
+  ),
   // `jwt_invalid` is the general fallback; the codes below it split out specific
   // failure modes, so an integrator can tell a wrong JWKS registration from a
   // token with no organization claim from a wrong audience, instead of getting
@@ -361,25 +413,37 @@ export const ERROR_CODES = {
     'permission',
     403,
     false,
-    'The database role Ablo connects with is a superuser or has `BYPASSRLS`, so Postgres will not enforce row-level security for it. Connect with a role that is subject to RLS.'
+    'The database role Ablo connects with is a superuser or has `BYPASSRLS`, so Postgres will not enforce row-level security for it. Connect with a role that is subject to RLS.',
+    undefined,
+    true,
   ),
   database_role_unreadable: wire(
     'permission',
     403,
     false,
-    'Ablo could not introspect the database role it connects with, so it cannot verify that row-level security is enforced.'
+    'Ablo could not introspect the database role it connects with, so it cannot verify that row-level security is enforced.',
+    undefined,
+    true,
   ),
   database_tables_unforced_rls: wire(
     'permission',
     403,
     false,
-    'Some synced tables do not have `FORCE ROW LEVEL SECURITY` applied, so the table owner can bypass row isolation. Run `ALTER TABLE ... FORCE ROW LEVEL SECURITY` on each synced table.'
+    'Some synced tables do not have `FORCE ROW LEVEL SECURITY` applied, so the table owner can bypass row isolation. Run `ALTER TABLE ... FORCE ROW LEVEL SECURITY` on each synced table.',
+    undefined,
+    true,
   ),
   database_host_not_allowed: wire(
     'permission',
     403,
     false,
-    "The database host resolves to a private, loopback, or link-local address, which Ablo's servers will not connect to directly. Use a publicly resolvable direct endpoint, private networking, or `ablo dev --local` with a signed Data Source reverse channel."
+    "The database host did not resolve exclusively to an allowed address for this route. Use a publicly resolvable direct endpoint, or configure the matching PrivateLink, peering, or VPN route. Localhost has its own `database_loopback_requires_connector` workflow."
+  ),
+  database_loopback_requires_connector: wire(
+    'validation',
+    400,
+    false,
+    'Ablo Cloud cannot open a direct PostgreSQL connection to localhost on your machine. For localhost-first development, run `ablo migrate` once and keep `ablo dev --local` running; use a network-reachable direct route only when Ablo must observe arbitrary SQL writes through WAL.'
   ),
   connected_database_unreachable: wire(
     'tenant',
@@ -436,7 +500,7 @@ export const ERROR_CODES = {
     'claim',
     409,
     false,
-    'This write carried a fencing token below the row’s current high-water: a later holder claimed the row, wrote, and moved on while this claim was lapsed, so applying the write would silently overwrite their work. The claim is gone — re-claim the row and retry from the current state.'
+    'This claim is no longer current because another participant completed newer work on the row. Re-claim the row and retry from the fresh state.'
   ),
   entity_claimed: wire(
     'claim',
@@ -492,7 +556,7 @@ export const ERROR_CODES = {
   ),
   model_claim_not_configured: client(
     'claim',
-    'Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically — there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path).'
+    'Claiming is unavailable on this model client. Construct it through the standard Ablo({ schema, apiKey }) client and retry.'
   ),
   model_join_not_configured: client(
     'claim',
@@ -741,7 +805,9 @@ export const ERROR_CODES = {
     'not_found',
     404,
     false,
-    'This branch is not connected to your database yet. Run `ablo connect` for a cloud-reachable direct Postgres endpoint, or `ablo dev --local` to register and serve a localhost Data Source, then retry.'
+    'This branch is not connected to your database yet. Run `ablo connect` for a cloud-reachable direct Postgres endpoint, or `ablo dev --local` to register and serve a localhost Data Source, then retry.',
+    undefined,
+    true,
   ),
   source_connector_no_source_registered: wire(
     'not_found',
@@ -1187,6 +1253,30 @@ export const ERROR_CODES = {
   ),
 
   // ── server (5xx) ───────────────────────────────────────────────────
+  session_check_failed: wire(
+    'server',
+    503,
+    true,
+    'Ablo could not verify the current login session. Retry shortly.'
+  ),
+  mint_failed: wire(
+    'server',
+    502,
+    true,
+    'Ablo could not mint the requested runtime credential. Retry shortly.'
+  ),
+  server_side_only: wire(
+    'permission', 403, false, 'This endpoint is available only to trusted server-side callers.'
+  ),
+  unknown_auth_host: wire(
+    'auth', 400, false, 'The authentication host is not recognized.'
+  ),
+  no_active_organization: wire(
+    'tenant', 400, false, 'Select an active organization before continuing.'
+  ),
+  data_session_unsupported: wire(
+    'validation', 400, false, 'This sign-in host cannot create the requested data session.'
+  ),
   internal_error: wire(
     'server',
     500,
@@ -1439,7 +1529,9 @@ export const ERROR_CODES = {
     'permission',
     403,
     false,
-    'Schema registration could not create tables in the target database: the engine is not permitted to run DDL there.'
+    'Schema registration could not create tables in the target database: the engine is not permitted to run DDL there.',
+    undefined,
+    true,
   ),
   model_query_failed: wire(
     'validation',
@@ -1633,6 +1725,10 @@ export const ERROR_CODES = {
   ),
   request_too_large: wire('validation', 413, false, 'The request body exceeds the maximum size.'),
   invalid_schema: wire('validation', 400, false, 'The submitted schema could not be parsed.'),
+  operational_warning: client(
+    'server',
+    'Ablo handled an operational degradation that remains searchable for diagnosis.'
+  ),
   incompatible_change: wire(
     'conflict',
     409,

package/src/errorObservation.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+
+export const errorObservationSeveritySchema = z.enum([
+  'debug', 'info', 'warning', 'error', 'fatal',
+]);
+
+export const errorObservationChannelSchema = z.enum([
+  'http', 'websocket', 'connector', 'background', 'process', 'cli', 'browser',
+]);
+
+const TRUNCATION_MARKER = '…[truncated]';
+
+/**
+ * Keep an observation field inside its wire bound without dropping the event.
+ * This lives beside the schema so producers cannot accidentally enforce a
+ * different limit. Redaction still happens before parsing at each boundary.
+ */
+export function boundObservationString(value: string, maxLength: number): string {
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, maxLength - TRUNCATION_MARKER.length)}${TRUNCATION_MARKER}`;
+}
+
+const boundedString = (maxLength: number) =>
+  z.preprocess(
+    (value) => typeof value === 'string' ? boundObservationString(value, maxLength) : value,
+    z.string().max(maxLength),
+  );
+
+const boundedCauseSchema = z.object({
+  type: boundedString(200),
+  message: boundedString(2_000),
+});
+
+/** Runtime-neutral private event vocabulary shared by every error boundary. */
+export const errorObservationSchema = z.object({
+  eventId: boundedString(200).pipe(z.string().min(1)),
+  occurredAt: z.iso.datetime(),
+  service: boundedString(100).pipe(z.string().min(1)),
+  stage: boundedString(100).pipe(z.string().min(1)),
+  release: boundedString(200).optional(),
+  severity: errorObservationSeveritySchema,
+  channel: errorObservationChannelSchema,
+  scope: boundedString(200).pipe(z.string().min(1)),
+  operation: boundedString(300).pipe(z.string().min(1)),
+  errorCode: boundedString(200).pipe(z.string().min(1)),
+  errorType: boundedString(200).pipe(z.string().min(1)),
+  category: boundedString(100).pipe(z.string().min(1)),
+  retryable: z.boolean(),
+  /** Whether application code converted the failure into an expected outcome. */
+  handled: z.boolean(),
+  publicMessage: boundedString(2_000),
+  internalMessage: boundedString(4_000).optional(),
+  stack: boundedString(20_000).optional(),
+  httpStatus: z.number().int().min(100).max(599).optional(),
+  requestId: boundedString(200).optional(),
+  traceId: boundedString(200).optional(),
+  spanId: boundedString(200).optional(),
+  organizationId: boundedString(200).optional(),
+  projectId: boundedString(200).optional(),
+  branchId: boundedString(200).optional(),
+  keyKind: boundedString(100).optional(),
+  storageKind: boundedString(100).optional(),
+  storageTransport: boundedString(100).optional(),
+  dataSourceId: boundedString(200).optional(),
+  connectorState: boundedString(100).optional(),
+  model: boundedString(200).optional(),
+  cause: z.array(boundedCauseSchema).max(5).optional(),
+  diagnosticContext: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type ErrorObservation = Readonly<z.infer<typeof errorObservationSchema>>;
+export type ErrorObservationChannel = z.infer<typeof errorObservationChannelSchema>;
+export type ErrorObservationSeverity = z.infer<typeof errorObservationSeveritySchema>;
+
+const SENSITIVE_KEYS = [
+  'password', 'secret', 'token', 'apikey', 'authorization', 'cookie',
+  'databaseurl', 'connectionstring', 'ek', 'sk', 'rk', 'body', 'payload', 'sql', 'query',
+];
+const MASK = '[redacted]';
+const SECRET_PATTERNS = [
+  /postgres(?:ql)?:\/\/[^\s"']+/gi,
+  /\b[a-z]{2,4}_[A-Za-z0-9]{12,}\b/g,
+];
+
+export function redactObservationString(value: string): string {
+  return SECRET_PATTERNS.reduce((current, pattern) => current.replace(pattern, MASK), value);
+}
+
+function isSensitiveObservationKey(key: string): boolean {
+  const normalized = key.toLowerCase().replace(/[^a-z]/g, '');
+  return SENSITIVE_KEYS.some(
+    (sensitive) => normalized === sensitive || (sensitive.length > 3 && normalized.includes(sensitive)),
+  );
+}
+
+/** Runtime-neutral, circular-safe sanitizer used before any observation sink. */
+export function sanitizeObservationValue(
+  value: unknown,
+  depth = 0,
+  seen = new WeakSet(),
+): unknown {
+  if (depth > 6) return '[truncated]';
+  if (typeof value === 'string') return redactObservationString(value);
+  if (value && typeof value === 'object') {
+    if (seen.has(value)) return '[circular]';
+    seen.add(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeObservationValue(item, depth + 1, seen));
+  }
+  if (value && typeof value === 'object') {
+    const sanitized: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      sanitized[key] = isSensitiveObservationKey(key)
+        ? MASK
+        : sanitizeObservationValue(item, depth + 1, seen);
+    }
+    return sanitized;
+  }
+  return value;
+}

package/src/errors.ts

@@ -64,6 +64,8 @@ export class AbloError extends Error {
    *  `x-request-id` header or a live commit's rejection frame. Include it in
    *  support requests. */
   readonly requestId?: string;
+  /** Opaque id of the exact private observation associated with this error. */
+  readonly eventId?: string;
   /** The specific input that caused the error, as a model or field path such as
    *  `'dataroomMember.grants.subject'`, so tooling can point at the exact
    *  offending value. */
@@ -96,6 +98,7 @@ export class AbloError extends Error {
     if (options?.requestId !== undefined) this.requestId = options.requestId;
     if (options?.param !== undefined) this.param = options.param;
     if (options?.details !== undefined) this.details = options.details;
+    if (typeof options?.details?.event_id === 'string') this.eventId = options.details.event_id;
     const docUrl = options?.docUrl ?? (options?.code ? docUrlForCode(options.code) : undefined);
     if (docUrl !== undefined) this.docUrl = docUrl;
     if (options?.cause !== undefined) {
@@ -142,7 +145,8 @@ export class AbloError extends Error {
     const code = this.code ? ` [${this.code}]` : '';
     const docs = this.docUrl ? ` (see ${this.docUrl})` : '';
     const req = this.requestId ? ` [request_id: ${this.requestId}]` : '';
-    return `${this.name}${code}: ${this.message}${docs}${req}`;
+    const event = this.eventId ? ` [event_id: ${this.eventId}]` : '';
+    return `${this.name}${code}: ${this.message}${docs}${req}${event}`;
   }
 }
 

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * The Ablo settlement core (ADR 0013).
+ * The Ablo confirmation core (ADR 0013).
  *
  * The transaction layer that the reactive client is a consumer of, not the
  * other way round. The root barrel is deliberate: it exports the seam —
@@ -31,8 +31,15 @@ export { Ablo } from './ablo.js';
 export type {
   AbloHttpClient,
   AbloHttpClientOptions,
+  CapturedRow,
   HttpModelClient,
+  HttpModelMutationParams,
 } from './transport/httpClient.js';
+export type {
+  FunctionalUpdateOptions,
+  /** @deprecated Use `FunctionalUpdateOptions`. */
+  ContentionOptions,
+} from './resources/functionalUpdate.js';
 
 // The types the seam's signatures reference.
 export type {

package/src/internal/read-set.ts

@@ -0,0 +1,18 @@
+/**
+ * Package-private ReadSet integration seam used by the reactive materialiser.
+ * Application code declares dependencies through `reads: [returnedRow]`.
+ */
+export {
+  abortReadSetCommit,
+  capturePointRead,
+  createReadSetContext,
+  commitRecordIdentity,
+  consumeReadSet,
+  prepareReadSet,
+  publishCommitRecord,
+} from '../readSetContext.js';
+export { recordWebSocketCommitReceipt } from '../commitRecordRuntime.js';
+export type {
+  PreparedReadSet,
+  ReadSetContext,
+} from '../readSetContext.js';

package/src/logger.ts

@@ -3,7 +3,7 @@
  *
  * A contract with no framework and no local state: credential exchange, commit,
  * and claim all need to log with no UI and no offline store present, so the port
- * belongs to the settlement core (ADR 0016). The consumer supplies the
+ * belongs to the confirmation core (ADR 0016). The consumer supplies the
  * implementation; the SDK ships a no-op default.
  */
 export interface Logger {

package/src/observability.ts

@@ -1,5 +1,5 @@
 /**
- * The observability the settlement core reports on its own behalf.
+ * The observability the confirmation core reports on its own behalf.
  *
  * Coordination outcomes — a claim changing state, a stale-write collision that
  * notified instead of aborting — happen with no UI and no local store anywhere,

package/src/readSetContext.ts

@@ -0,0 +1,164 @@
+/**
+ * Client-local opaque evidence for rows returned by authoritative reads.
+ *
+ * The name is retained internally to avoid churn across the two transports,
+ * but this is not an execution context: it has no async carrier and no ambient
+ * scope. Evidence is keyed only by the exact object returned to the caller.
+ */
+import {
+  readDependencySchema,
+  type CommitReadSetEntry,
+  type OnStaleMode,
+  type ReadDependency,
+} from './coordination/schema.js';
+import { AbloValidationError } from './errors.js';
+import type { CommitRecord } from './wire/commit.js';
+
+type ClientIdentity = object;
+
+/** @internal One exact returned-row assertion. */
+export interface CapturedReadEvidence {
+  readonly client: ClientIdentity;
+  readonly entry: CommitReadSetEntry;
+  readonly row: object;
+}
+
+/** @internal Per-client registry. Weak keys do not retain application rows. */
+export interface ReadRegistry {
+  readonly byRow: WeakMap<object, CapturedReadEvidence>;
+  readonly commitRecords: Map<string, CommitRecord>;
+  onCommitRecord?: (record: CommitRecord) => void | Promise<void>;
+}
+
+/** @internal Client-local evidence registry handle. */
+export interface ReadSetContext {
+  getStore(): ReadRegistry;
+}
+
+export interface PreparedReadSet {
+  readonly readAt?: number;
+  readonly onStale?: OnStaleMode;
+  readonly reads?: readonly ReadDependency[] | null;
+  readonly consumed: readonly CapturedReadEvidence[];
+  readonly automaticCommit: false;
+  readonly idempotencyKey?: string;
+}
+
+/** @internal Creates one isolated evidence registry for one Ablo client. */
+export function createReadSetContext(options?: {
+  readonly onCommitRecord?: (record: CommitRecord) => void | Promise<void>;
+}): ReadSetContext {
+  const registry: ReadRegistry = {
+    byRow: new WeakMap(),
+    commitRecords: new Map(),
+    ...(options?.onCommitRecord ? { onCommitRecord: options.onCommitRecord } : {}),
+  };
+  return { getStore: () => registry };
+}
+
+/** @internal Retains and reports one immutable logical commit snapshot. */
+export function publishCommitRecord(
+  context: ReadSetContext | undefined,
+  record: CommitRecord,
+): void {
+  const registry = context?.getStore();
+  if (!registry) return;
+  registry.commitRecords.set(record.id, record);
+  try {
+    const observed = registry.onCommitRecord?.(record);
+    if (observed) void Promise.resolve(observed).catch(() => undefined);
+  } catch {
+    // Observability must never change a commit's outcome.
+  }
+}
+
+/** @internal Associates evidence with the exact row object returned to a caller. */
+export function capturePointRead(
+  context: ReadSetContext | undefined,
+  client: ClientIdentity,
+  model: string,
+  id: string,
+  row: unknown,
+  readAt: number,
+): void {
+  if (!context || typeof row !== 'object' || row === null) return;
+  const rowObject = row as object;
+  context.getStore().byRow.set(rowObject, {
+    client,
+    row: rowObject,
+    entry: {
+      target: { scope: 'row', model, id },
+      watermark: readAt,
+      lifetime: 'commit',
+      onStale: 'reject',
+    },
+  });
+}
+
+/** @internal Resolves only dependencies explicitly supplied through `reads`. */
+export function prepareReadSet(
+  context: ReadSetContext | undefined,
+  client: ClientIdentity,
+  explicitReadAt: number | null | undefined,
+  explicitOnStale: OnStaleMode | null | undefined,
+  explicitIdempotencyKey: string | null | undefined,
+  reads: readonly unknown[] | null | undefined,
+): PreparedReadSet {
+  const registry = context?.getStore();
+  const consumed: CapturedReadEvidence[] = [];
+  const resolvedReads: ReadDependency[] = [];
+
+  for (const entry of reads ?? []) {
+    const captured =
+      registry && typeof entry === 'object' && entry !== null
+        ? registry.byRow.get(entry)
+        : undefined;
+    if (captured?.client === client) {
+      const target = captured.entry.target;
+      if (target.scope !== 'row') {
+        throw new AbloValidationError('Captured read evidence must name a row.', {
+          code: 'write_options_invalid', param: 'reads',
+        });
+      }
+      resolvedReads.push({
+        model: target.model,
+        id: target.id,
+        readAt: captured.entry.watermark,
+      });
+      consumed.push(captured);
+      continue;
+    }
+    const canonical = readDependencySchema.safeParse(entry);
+    if (canonical.success) {
+      resolvedReads.push(canonical.data);
+      continue;
+    }
+    throw new AbloValidationError(
+      'A row passed through `reads` was not the exact object returned by this Ablo client. Re-read it and pass that object directly.',
+      { code: 'write_options_invalid', param: 'reads' },
+    );
+  }
+
+  return {
+    ...(explicitReadAt != null ? { readAt: explicitReadAt } : {}),
+    ...(explicitOnStale != null ? { onStale: explicitOnStale } : {}),
+    ...(reads !== undefined ? { reads: reads === null ? null : resolvedReads } : {}),
+    consumed,
+    automaticCommit: false,
+    ...(explicitIdempotencyKey != null ? { idempotencyKey: explicitIdempotencyKey } : {}),
+  };
+}
+
+/** @internal Commit identity is the explicit request idempotency identity. */
+export function commitRecordIdentity(
+  _context: ReadSetContext | undefined,
+  attemptId: string,
+): { readonly id: string } {
+  return { id: attemptId };
+}
+
+/** @internal Explicit row evidence is reusable; successful writes do not consume it. */
+export function consumeReadSet(..._args: readonly unknown[]): void {}
+
+/** @internal There is no ambient automatic-commit reservation to release. */
+export function abortReadSetCommit(..._args: readonly unknown[]): void {}

package/src/resources/functionalUpdate.ts

@@ -28,6 +28,7 @@ import {
   AbloClaimedError,
   AbloContentionError,
 } from '../errors.js';
+import type { ReadDependency } from '../coordination/schema.js';
 
 /**
  * The functional form of an update: given the freshly-read row, return the
@@ -38,8 +39,8 @@ export type ModelUpdater<T> = (
   current: T,
 ) => Partial<T> | null | undefined | Promise<Partial<T> | null | undefined>;
 
-/** Tuning for the functional update's internal reconcile loop. */
-export interface ContentionOptions {
+/** Options for the functional `update(id, reducer, options)` form. */
+export interface FunctionalUpdateOptions<Dependency = ReadDependency> {
   /**
    * Max reconcile rounds under contention before throwing
    * {@link AbloContentionError}. Each round re-reads the latest row and re-runs
@@ -48,8 +49,19 @@ export interface ContentionOptions {
   readonly retries?: number;
   /** Abort the reconcile loop (e.g. the request was cancelled). */
   readonly signal?: AbortSignal;
+  /**
+   * Cross-target state this reducer decision depends on. Captured point rows
+   * are resolved by the public client; canonical dependencies remain the
+   * low-level escape hatch. Dependencies survive reconcilable CAS failures and
+   * are consumed only with the successful attempt.
+   */
+  readonly reads?: readonly Dependency[] | null;
 }
 
+/** @deprecated Use {@link FunctionalUpdateOptions}. */
+export type ContentionOptions<Dependency = ReadDependency> =
+  FunctionalUpdateOptions<Dependency>;
+
 /** Reconcile rounds before a hot row is declared permanently contended. */
 export const DEFAULT_CONTENTION_RETRIES = 16;
 
@@ -104,9 +116,9 @@ export interface ReconcileTransport<T, R> {
  * both transports so the guarantee is provably identical. Returns the write's
  * result, or `undefined` when the updater opted out of writing.
  */
-export async function reconcileFunctionalUpdate<T, R>(
+export async function reconcileFunctionalUpdate<T, R, Read = ReadDependency>(
   updater: ModelUpdater<T>,
-  options: ContentionOptions | undefined,
+  options: FunctionalUpdateOptions<Read> | undefined,
   transport: ReconcileTransport<T, R>,
 ): Promise<R | undefined> {
   const retries = options?.retries ?? DEFAULT_CONTENTION_RETRIES;