@abloatai/transaction 0.47.0 → 0.49.0

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/footprint.ts

@@ -51,25 +51,14 @@ export interface FootprintArtifact {
 
 // ── The names, for the code that creates and reads these objects ────────────
 
-/**
- * The publication Ablo's replication reads from. Constant by design: a
- * publication declares what streams, and several readers are meant to share one
- * (`publication_names` is a per-stream option, not slot state).
- */
+/** Prefix used to derive a branch-scoped publication name. The exact unsuffixed
+ * name is retained only so `ablo connect scan` can identify an old installation. */
 export const ABLO_PUBLICATION = 'ablo_publication';
-/**
- * The replication slot that holds Ablo's position in the write-ahead log.
- *
- * Constant, and it should not be — a slot stores ONE position, so two
- * connections sharing this name compete for the same marker. It is why a
- * database can be connected to one plane at a time. ADR 0020 derives it per
- * connection; {@link isValidReplicationSlotName} is the check a derived name
- * has to pass.
- */
+/** Prefix used to derive the branch-scoped replication slot. */
 export const ABLO_REPLICATION_SLOT = 'ablo_slot';
-/** The least-privilege login Ablo reads with. Per-connection under ADR 0020. */
+/** Prefix used to derive the branch-scoped least-privilege replication login. */
 export const ABLO_REPLICATION_ROLE = 'ablo_replicator';
-/** The separate least-privilege login used only for row writes. */
+/** Prefix used to derive the branch-scoped login used only for row writes. */
 export const ABLO_WRITE_ROLE = 'ablo_writer';
 /** The bookkeeping table that makes a retried write land once. */
 export const ABLO_IDEMPOTENCY_TABLE = 'ablo_idempotency';
@@ -90,15 +79,15 @@ export function isValidReplicationSlotName(name: string): boolean {
 
 // ── Per-connection names (ADR 0020) ─────────────────────────────────────────
 
-/** The immutable branch coordinates a connection is identified by. */
-export interface FootprintPlane {
+/** The immutable branch coordinates that identify one customer Data Source. */
+export interface DataSourceIdentity {
   readonly organizationId: string;
   readonly branchId: string;
   /** Omitted for the organization-default project. */
   readonly projectId?: string;
 }
 
-/** The names one connection owns. Nothing here is shared with another plane. */
+/** The names one connection owns. Nothing here is shared with another Data Source. */
 export interface FootprintNames {
   readonly slot: string;
   readonly publication: string;
@@ -114,7 +103,7 @@ export interface FootprintNames {
 const SUFFIX_LENGTH = 16;
 
 /**
- * FNV-1a over the plane, in hex.
+ * FNV-1a over the Data Source identity, in hex.
  *
  * Deliberately not a cryptographic hash: this module is imported by the CLI,
  * which runs in environments without `node:crypto` guaranteed, and the property
@@ -123,13 +112,14 @@ const SUFFIX_LENGTH = 16;
  * over different seeds give the sixteen hex characters, which is ample for the
  * handful of planes any one database is ever connected to.
  */
-function planeDigest(plane: FootprintPlane): string {
+function dataSourceDigest(identity: DataSourceIdentity): string {
   // The organization-default project may be omitted or repeated as the
   // organization id; both spell the same branch coordinates.
-  const project = plane.projectId === plane.organizationId ? '' : (plane.projectId ?? '');
+  const project =
+    identity.projectId === identity.organizationId ? '' : (identity.projectId ?? '');
   // Delimit the coordinates. Concatenation alone makes structurally different
   // planes such as ("ab", "c") and ("a", "bc") hash the same input.
-  const key = [plane.organizationId, project, plane.branchId].join('\0');
+  const key = [identity.organizationId, project, identity.branchId].join('\0');
 
   const round = (seed: number): string => {
     let hash = seed;
@@ -148,16 +138,15 @@ function planeDigest(plane: FootprintPlane): string {
  * The objects this connection owns, named so no other connection can claim them.
  *
  * A slot stores ONE position, so two connections sharing a name compete for the
- * same marker and Postgres reports nothing — which is why the constants these
- * replace made a database connectable to one plane at a time. The publication
+ * same marker and Postgres reports nothing. The publication
  * and roles are derived from the same digest so a database's footprint reads as
  * one set per connection rather than a mix of shared and private objects.
  *
  * Stable: the same plane always derives the same names, so re-running setup is a
  * no-op rather than a second installation.
  */
-export function footprintNamesFor(plane: FootprintPlane): FootprintNames {
-  const suffix = planeDigest(plane);
+export function footprintNamesFor(identity: DataSourceIdentity): FootprintNames {
+  const suffix = dataSourceDigest(identity);
   const names: FootprintNames = {
     slot: `${ABLO_REPLICATION_SLOT}_${suffix}`,
     publication: `${ABLO_PUBLICATION}_${suffix}`,

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;

package/src/resources/httpResources.ts

@@ -15,14 +15,19 @@ import type { ClaimHeartbeatReply, ClaimState } from '../wire/claims.js';
 import type {
   ClientCommitReceipt,
   CommitWait,
+  CommitRecord,
+  CommitRecordList,
+  CommitRecordListOptions,
+  CommitRecordWhere,
 } from '../wire/commit.js';
 import type { LogListResponse, LogQuery } from '../wire/feedEvent.js';
-// Re-exported, not redeclared. `wire/commit.ts` owns the settlement vocabulary
+import type { ModelListEvidence } from '../wire/modelResponses.js';
+// Re-exported, not redeclared. `wire/commit.ts` owns the commit-status vocabulary
 // and derives the waitable subset from it; this module serves that name to SDK
 // consumers. Restating the subset here as its own union produced a type that
 // matched the canonical one only by both happening to list the same two
 // strings — and would have silently disagreed with the runtime `wait`
-// validator the moment a third settlement state existed.
+// validator the moment a third commit status existed.
 export type { CommitWait };
 // `ModelTarget` (the `model` and `id` locator) and `ModelClaim` (the resolved
 // claim view) are defined in `../coordination/schema`, derived from a single
@@ -39,7 +44,7 @@ import type { SyncGroupInput } from '../schema/roles.js';
 import type {
   CapabilityCan,
   CapabilityOperation,
-  CapabilityScope,
+  EffectiveAuthority,
 } from '../auth/capability.js';
 import type {
   Claim,
@@ -48,7 +53,7 @@ import type {
   Duration,
   HeldClaim,
 } from '../types/streams.js';
-import type { ModelUpdater, ContentionOptions } from './functionalUpdate.js';
+import type { ModelUpdater, FunctionalUpdateOptions } from './functionalUpdate.js';
 import type {
   ClaimOptions,
   ClaimAttemptEvent,
@@ -93,6 +98,12 @@ export interface HttpTransportRead<T = Record<string, unknown>> {
   readonly claims: readonly ModelClaim[];
 }
 
+/** @internal Exact collection envelope retained until the typed facade captures evidence. */
+export interface HttpTransportList<T = Record<string, unknown>> {
+  readonly data: readonly T[];
+  readonly evidence?: readonly ModelListEvidence[];
+}
+
 export type IfClaimedPolicy = 'return' | 'fail';
 
 export interface ClaimedOptions {
@@ -160,6 +171,8 @@ export interface CommitOperationInput {
   readonly id?: string | null;
   readonly data?: Record<string, unknown> | null;
   readonly transactionId?: string | null;
+  /** Claim identity derived from a held claim; not an application id. */
+  readonly claimId?: string | null;
   readonly readAt?: number | null;
   readonly onStale?: OnStaleMode | null;
   /** Fencing token (Option B) from the batch's claim handle; server-validated. */
@@ -207,6 +220,8 @@ export type CommitReceipt = ClientCommitReceipt;
 
 export interface CommitResource {
   create(options: CommitCreateOptions): Promise<CommitReceipt>;
+  get(options: { readonly id: string }): Promise<CommitRecord | null>;
+  list(options?: CommitRecordListOptions): Promise<CommitRecordList>;
 }
 
 export interface HttpLogListOptions
@@ -276,6 +291,10 @@ export interface ModelMutationOptions extends ClaimedOptions {
   readonly idempotencyKey?: string | null;
   readonly readAt?: number | null;
   readonly onStale?: OnStaleMode | null;
+  /** Commit-lifetime read dependencies checked before this mutation lands. */
+  readonly reads?: readonly ReadDependency[] | null;
+  /** Persisted read dependencies registered by this mutation. */
+  readonly track?: readonly TrackDependency[] | null;
   readonly claim?: Claim | ClaimOptions | null;
   /** Fencing token (Option B) from the claim; server-validated at commit. */
   readonly fenceToken?: number | null;
@@ -332,7 +351,7 @@ export interface HttpTransportModel<
    * and `limit`. The typed public client always exposes `ablo.<model>.list`;
    * this protocol shape is private transport machinery.
    */
-  list(options?: ServerReadOptions<T>): Promise<T[]>;
+  list(options?: ServerReadOptions<T>): Promise<HttpTransportList<T>>;
   /**
    * Creates a row and returns the confirmed server row, including framework
    * defaults such as `createdAt` and `createdBy`. Matches the stateful client's
@@ -354,7 +373,7 @@ export interface HttpTransportModel<
   update(
     id: string,
     updater: ModelUpdater<T>,
-    options?: ContentionOptions,
+    options?: FunctionalUpdateOptions,
   ): Promise<CommitReceipt | undefined>;
   delete(params: ModelMutationOptions & { readonly id: string }): Promise<CommitReceipt>;
   /**
@@ -475,7 +494,7 @@ export interface AbloSession {
   organizationId: string;
   /** The grant this token carries, on both axes — the same shape the key row
    *  stores and the gates enforce. */
-  scope: CapabilityScope;
+  scope: EffectiveAuthority;
   userMeta: Record<string, unknown>;
 }
 
@@ -492,7 +511,7 @@ export interface SessionRotation {
   token: string;
   expiresAt: string | null;
   organizationId: string;
-  scope: CapabilityScope;
+  scope: EffectiveAuthority;
   rotatedFrom: {
     id: string;
     expiresAt: string;

package/src/resources/modelOperations.ts

@@ -3,7 +3,7 @@
  * caller passes to a read, a write, or a claim.
  *
  * These types describe the *change or the query being requested*, never a local
- * copy of the rows it touches, so they sit in the settlement core and are shared
+ * copy of the rows it touches, so they sit in the commit core and are shared
  * by every transport and every caller (ADR 0013 §4, ADR 0016). The factory that
  * binds them to reactive model instances — `createModelProxy` — stays with the
  * reactive consumer, along with `ModelOperations` and `ModelCollaboration`,
@@ -562,7 +562,7 @@ export interface ModelRetrieveParams extends ServerRetrieveOptions {
  * Options shared by schema model writes.
  *
  * Reactive clients apply the row change optimistically before returning from
- * the call. The returned promise has one stable settlement contract across
+ * the call. The returned promise has one stable confirmation contract across
  * reactive and stateless clients: it resolves only after authoritative
  * confirmation. Callers that need an earlier queued receipt use the lower-level
  * `commits.create` resource instead.

package/src/resources/mutationOptions.ts

@@ -3,7 +3,7 @@
  *
  * Every field here defines, orders, settles, or authorises *the change itself*
  * — request identity, commit disposition, fencing, and the premise it rests on.
- * None of it touches a local copy of rows, so it belongs with the settlement
+ * None of it touches a local copy of rows, so it belongs with the commit
  * core rather than the reactive consumer (ADR 0013 §4, ADR 0016).
  */
 

package/src/resources/where.ts

@@ -10,7 +10,7 @@
  * key — for example, fetching every block whose `sectionId` falls in a set of ids.
  *
  * These types describe the *request*, not any local copy of the rows it returns,
- * so they live with the settlement core rather than the reactive consumer.
+ * so they live with the commit core rather than the reactive consumer.
  */
 
 import { z } from 'zod';