@abloatai/transaction 0.48.0 → 0.50.0

package/src/auth/capabilityLifecycle.ts

@@ -4,7 +4,7 @@ import {
   hasWireCode,
   translateHttpError,
 } from '../errors.js';
-import { capabilityScopeSchema } from './capability.js';
+import { effectiveAuthoritySchema } from './capability.js';
 import type {
   RotateSessionParams,
   SessionRevocation,
@@ -27,7 +27,8 @@ export const capabilityRotationResponseSchema = z.object({
   token: z.string().trim().min(1),
   expiresAt: z.iso.datetime().nullable(),
   organizationId: z.string().min(1),
-  scope: capabilityScopeSchema,
+  branchRoot: z.boolean().default(false),
+  scope: effectiveAuthoritySchema,
   rotatedFrom: z.object({
     capabilityId: z.string().min(1),
     expiresAt: z.iso.datetime(),

package/src/auth/identity.ts

@@ -34,6 +34,7 @@ import type { AuthCredentialSource } from '../auth/credentialSource.js';
 import type { CredentialProvider } from './credentialResult.js';
 import { resolveApiKeyValue, resolveBootstrapBaseUrl } from './apiKey.js';
 import type { DeliveryPartitionRoute } from './deliveryPartition.js';
+import type { EffectiveAuthority } from './capability.js';
 
 export interface IdentityResolveInput {
   readonly options: {
@@ -71,6 +72,8 @@ export interface ResolvedIdentity {
   readonly syncGroups: readonly string[] | undefined;
   readonly participantKind: ParticipantKind;
   readonly deliveryPartition: DeliveryPartitionRoute | null;
+  /** Effective authority confirmed by the server (or explicit self-hosted configuration). */
+  readonly authority: EffectiveAuthority;
   /** Set only on the hosted-cloud path; the caller keeps it to stop refreshes on shutdown. */
   readonly refreshScheduler: RefreshScheduler | null;
 }
@@ -195,6 +198,16 @@ export async function resolveParticipantIdentity(
         syncGroups: options.syncGroups,
         participantKind: kind,
         deliveryPartition: null,
+        authority: {
+          organizationId: accountScope,
+          projectId: accountScope,
+          branchId: internalOptions.branchId ?? null,
+          participantKind: kind,
+          participantId: userId,
+          operations: [],
+          syncGroups: options.syncGroups ?? [],
+          deliveryPartition: null,
+        },
         refreshScheduler: null,
       };
     }
@@ -246,6 +259,7 @@ async function resolveViaIdentity(
     syncGroups: mergedSyncGroups,
     participantKind: identity.participantKind,
     deliveryPartition: identity.deliveryPartition,
+    authority: identity.authority,
     refreshScheduler: null,
   };
 }
@@ -322,7 +336,7 @@ async function resolveHosted(input: HostedInput): Promise<ResolvedIdentity> {
     accountScope: exchange.scope.organizationId,
     projectId: exchange.scope.projectId ?? exchange.scope.organizationId,
     branchId: exchange.scope.branchId,
-    branchRoot: exchange.scope.branchRoot,
+    branchRoot: exchange.branchRoot,
     // teamIds isn't needed because the server already encoded
     // team-level access into scope.syncGroups.
     teamIds: undefined,
@@ -330,6 +344,7 @@ async function resolveHosted(input: HostedInput): Promise<ResolvedIdentity> {
     syncGroups: exchange.scope.syncGroups,
     participantKind: input.kind,
     deliveryPartition: exchange.scope.deliveryPartition,
+    authority: exchange.scope,
     refreshScheduler,
   };
 }

package/src/auth/index.ts

@@ -74,6 +74,7 @@ export {
   capabilityOperationSchema,
   capabilityCanSchema,
   capabilityCanSchemaFor,
+  effectiveAuthoritySchema,
   capabilityScopeSchema,
   capabilityRequestSchema,
   capabilityMintResponseSchema,
@@ -88,6 +89,7 @@ export type {
   CapabilityOperation,
   CapabilityCan,
   CapabilityGrant,
+  EffectiveAuthority,
   CapabilityScope,
   CapabilityMintResponse,
   CapabilityRequest,

package/src/auth/schemas.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { participantKindSchema } from '../coordination/schema.js';
 import {
   capabilityMintResponseSchema,
+  effectiveAuthoritySchema,
   grantedOperationSchema,
   type CapabilityMintResponse,
 } from './capability.js';
@@ -26,6 +27,8 @@ export const IdentityResolveResponseSchema = z.object({
   branchRoot: z.boolean().default(false),
   syncGroups: z.array(z.string()),
   deliveryPartition: deliveryPartitionRouteSchema.nullable().default(null),
+  /** Canonical server-confirmed authority of the authenticated credential. */
+  authority: effectiveAuthoritySchema,
   userMeta: z.record(z.string(), z.unknown()),
 });
 

package/src/auth/sessionMint.ts

@@ -93,7 +93,6 @@ export async function mintSession<S extends SchemaRecord>(
         organizationId: res.organizationId,
         projectId: res.projectId,
         branchId: res.branchId,
-        branchRoot: res.branchRoot,
         syncGroups: res.syncGroups,
         operations: res.operations,
         participantKind: 'user',

package/src/commitRecordRuntime.ts

@@ -0,0 +1,245 @@
+import {
+  DEFAULT_TRACK_ON_STALE,
+  type CommitReadSetEntry,
+  type ReadDependency,
+  type ReadSetEntry,
+  type TrackDependency,
+} from './coordination/schema.js';
+import {
+  commitRecordIdentity,
+  publishCommitRecord,
+  type ReadSetContext,
+} from './readSetContext.js';
+import {
+  commitRecordSchema,
+  type CommitOperationBody,
+  type CommitReceiptWire,
+} from './wire/commit.js';
+
+interface HttpCommitObservation {
+  readonly receipt: CommitReceiptWire;
+  readonly method: string;
+  readonly path: string;
+  readonly body: unknown;
+}
+
+interface WebSocketCommitObservation {
+  readonly receipt: CommitReceiptWire;
+  readonly operations: readonly {
+    readonly type: string;
+    readonly model: string;
+    readonly id: string;
+    readonly input?: Record<string, unknown>;
+    readonly claimId?: string | null;
+    readonly readAt?: number | null;
+    readonly onStale?: CommitOperationBody['onStale'] | null;
+    readonly fenceToken?: number | null;
+  }[];
+  readonly reads?: readonly ReadDependency[] | null;
+  readonly track?: readonly TrackDependency[] | null;
+}
+
+function commitEntry(dependency: ReadDependency): CommitReadSetEntry {
+  return {
+    target: 'group' in dependency
+      ? { scope: 'group', group: dependency.group }
+      : {
+          scope: 'row',
+          model: dependency.model,
+          id: dependency.id,
+          ...(dependency.fields ? { fields: dependency.fields } : {}),
+        },
+    watermark: dependency.readAt,
+    lifetime: 'commit',
+    onStale: dependency.onStale ?? 'reject',
+  };
+}
+
+function persistedEntry(
+  dependency: TrackDependency,
+  defaultWatermark: number,
+): ReadSetEntry {
+  return {
+    target: 'group' in dependency
+      ? { scope: 'group', group: dependency.group }
+      : { scope: 'row', model: dependency.model, id: dependency.id },
+    watermark: dependency.readAt ?? defaultWatermark,
+    lifetime: 'persisted',
+    onStale: dependency.onStale ?? DEFAULT_TRACK_ON_STALE,
+  };
+}
+
+function bodyRecord(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function retainedOperations(operations: readonly CommitOperationBody[]) {
+  return operations.map(({ data: _data, ...operation }) => ({
+    ...operation,
+    data: { retention: 'redacted' as const },
+  }));
+}
+
+function commitEvidence(
+  receipt: CommitReceiptWire,
+  operations: readonly CommitOperationBody[],
+  transport: 'http' | 'websocket',
+) {
+  return {
+    attempts: [{
+      id: receipt.clientTxId,
+      observedAt: receipt.createdAt,
+      transport,
+      kind: 'execution' as const,
+    }],
+    actor: {
+      kind: receipt.authority.participantKind,
+      id: receipt.authority.participantId,
+    },
+    // A receipt does not prove which live claim grant the server matched.
+    // Durable server records populate this from the claim gate instead.
+    claims: [],
+  };
+}
+
+function operationFromModelRequest(
+  observation: HttpCommitObservation,
+  body: Record<string, unknown>,
+): CommitOperationBody[] {
+  const segments = observation.path.split('/').filter(Boolean);
+  const modelIndex = segments.indexOf('models');
+  if (modelIndex < 0) return [];
+  const model = decodeURIComponent(segments[modelIndex + 1] ?? '');
+  const pathId = segments[modelIndex + 2];
+  const action = observation.method === 'POST'
+    ? 'create'
+    : observation.method === 'DELETE'
+      ? 'delete'
+      : 'update';
+  return [{
+    action,
+    model,
+    ...(pathId ? { id: decodeURIComponent(pathId) } : typeof body.id === 'string' ? { id: body.id } : {}),
+    ...(body.data && typeof body.data === 'object'
+      ? { data: body.data as Record<string, unknown> }
+      : {}),
+    ...(typeof body.readAt === 'number' ? { readAt: body.readAt } : {}),
+    ...(typeof body.onStale === 'string'
+      ? { onStale: body.onStale as CommitOperationBody['onStale'] }
+      : {}),
+    ...(typeof body.fenceToken === 'number' ? { fenceToken: body.fenceToken } : {}),
+    ...(typeof body.claim === 'string' ? { claimId: body.claim } : {}),
+  }];
+}
+
+/** @internal Joins exact HTTP request and receipt projections. */
+export function recordHttpCommitReceipt(
+  context: ReadSetContext | undefined,
+  observation: HttpCommitObservation,
+): void {
+  if (!context?.getStore()) return;
+  const body = bodyRecord(observation.body);
+  const operations = Array.isArray(body.operations)
+    ? body.operations as CommitOperationBody[]
+    : operationFromModelRequest(observation, body);
+  const reads = Array.isArray(body.reads) ? body.reads as ReadDependency[] : [];
+  const track = Array.isArray(body.track) ? body.track as TrackDependency[] : [];
+  const readSet: ReadSetEntry[] = reads.map(commitEntry);
+  for (const operation of operations) {
+    if (typeof operation.readAt !== 'number' || !operation.id) continue;
+    readSet.push(commitEntry({
+      model: operation.model,
+      id: operation.id,
+      readAt: operation.readAt,
+      onStale: operation.onStale ?? 'reject',
+    }));
+  }
+  readSet.push(...track.map((entry) => persistedEntry(entry, observation.receipt.lastSyncId)));
+
+  const record = commitRecordSchema.parse({
+    id: commitRecordIdentity(context, observation.receipt.clientTxId).id,
+    createdAt: observation.receipt.createdAt,
+    status: observation.receipt.status,
+    statusAt: observation.receipt.statusAt,
+    lastSyncId: observation.receipt.lastSyncId,
+    ...(observation.receipt.correlationId
+      ? { correlationId: observation.receipt.correlationId }
+      : {}),
+    readSet,
+    operations: retainedOperations(operations),
+    ...commitEvidence(observation.receipt, operations, 'http'),
+    authority: observation.receipt.authority,
+    receipt: {
+      clientTxId: observation.receipt.clientTxId,
+      serverTxId: observation.receipt.serverTxId,
+      ops: observation.receipt.ops,
+      ...(observation.receipt.notifications
+        ? { notifications: observation.receipt.notifications }
+        : {}),
+      ...(observation.receipt.missingIds
+        ? { missingIds: observation.receipt.missingIds }
+        : {}),
+    },
+  });
+  publishCommitRecord(context, record);
+}
+
+/** @internal Joins an exact commit frame and its authoritative WS receipt. */
+export function recordWebSocketCommitReceipt(
+  context: ReadSetContext | undefined,
+  observation: WebSocketCommitObservation,
+): void {
+  if (!context?.getStore()) return;
+  const operations: CommitOperationBody[] = observation.operations.map((operation) => ({
+    action: operation.type.toLowerCase() as CommitOperationBody['action'],
+    model: operation.model,
+    id: operation.id,
+    ...(operation.input ? { data: operation.input } : {}),
+    ...(operation.claimId ? { claimId: operation.claimId } : {}),
+    ...(typeof operation.readAt === 'number' ? { readAt: operation.readAt } : {}),
+    ...(operation.onStale ? { onStale: operation.onStale } : {}),
+    ...(typeof operation.fenceToken === 'number'
+      ? { fenceToken: operation.fenceToken }
+      : {}),
+  }));
+  const readSet: ReadSetEntry[] = (observation.reads ?? []).map(commitEntry);
+  for (const operation of operations) {
+    if (typeof operation.readAt !== 'number' || !operation.id) continue;
+    readSet.push(commitEntry({
+      model: operation.model,
+      id: operation.id,
+      readAt: operation.readAt,
+      onStale: operation.onStale ?? 'reject',
+    }));
+  }
+  readSet.push(...(observation.track ?? []).map((entry) =>
+    persistedEntry(entry, observation.receipt.lastSyncId)));
+  const record = commitRecordSchema.parse({
+    id: commitRecordIdentity(context, observation.receipt.clientTxId).id,
+    createdAt: observation.receipt.createdAt,
+    status: observation.receipt.status,
+    statusAt: observation.receipt.statusAt,
+    lastSyncId: observation.receipt.lastSyncId,
+    ...(observation.receipt.correlationId
+      ? { correlationId: observation.receipt.correlationId }
+      : {}),
+    readSet,
+    operations: retainedOperations(operations),
+    ...commitEvidence(observation.receipt, operations, 'websocket'),
+    authority: observation.receipt.authority,
+    receipt: {
+      clientTxId: observation.receipt.clientTxId,
+      serverTxId: observation.receipt.serverTxId,
+      ops: observation.receipt.ops,
+      ...(observation.receipt.notifications
+        ? { notifications: observation.receipt.notifications }
+        : {}),
+      ...(observation.receipt.missingIds
+        ? { missingIds: observation.receipt.missingIds }
+        : {}),
+    },
+  });
+  publishCommitRecord(context, record);
+}

package/src/coordination/index.ts

@@ -22,6 +22,17 @@ export {
   targetRefSchema,
   // Layer 3 — optimistic stale-context
   onStaleModeSchema,
+  MAX_READ_SET_ENTRIES,
+  readSetWatermarkSchema,
+  readSetRowTargetSchema,
+  readSetGroupTargetSchema,
+  commitReadSetTargetSchema,
+  persistedReadSetRowTargetSchema,
+  persistedReadSetTargetSchema,
+  commitReadSetEntrySchema,
+  persistedReadSetEntrySchema,
+  readSetEntrySchema,
+  readSetSchema,
   writeGuardSchema,
   staleNotificationSchema,
   rowStaleNotificationSchema,
@@ -29,7 +40,10 @@ export {
   stalePropagationSchema,
 
   readDependencySchema,
+  readDependencyListSchema,
+  readSetProjectionEntryCount,
   trackDependencySchema,
+  trackDependencyListSchema,
   // Layer 2 — pessimistic claim / claim-lease
   claimStatusSchema,
   wireClaimStatusSchema,
@@ -103,6 +117,15 @@ export type {
   TargetRef,
   // Layer 3 — optimistic stale-context
   OnStaleMode,
+  ReadSetWatermark,
+  ReadSetRowTarget,
+  ReadSetGroupTarget,
+  CommitReadSetTarget,
+  PersistedReadSetTarget,
+  CommitReadSetEntry,
+  PersistedReadSetEntry,
+  ReadSetEntry,
+  ReadSet,
   WriteGuard,
   StaleNotification,
   RowStaleNotification,
@@ -179,6 +202,7 @@ export type {
 } from './locator.js';
 export {
   batchFence,
+  claimIdFor,
   fenceTokenFor,
   isTargetTuple,
   subTarget,
@@ -186,4 +210,3 @@ export {
   modelTarget,
   streamTarget,
 } from './locator.js';
-

package/src/coordination/locator.ts

@@ -198,3 +198,20 @@ export function fenceTokenFor(
     ? fence.token
     : null;
 }
+
+/**
+ * The claim identity an operation carries when it writes the row named by a
+ * held claim. Like the fence token, a claim id cannot travel to another row.
+ */
+export function claimIdFor(
+  source: EntityLocator | null | undefined,
+  claimId: string | null | undefined,
+  model: string,
+  id: string | null,
+): string | null {
+  if (source == null || claimId == null || id === null) return null;
+  const target = modelTarget(source);
+  return model.toLowerCase() === target.model.toLowerCase() && id === target.id
+    ? claimId
+    : null;
+}

package/src/coordination/schema.ts

@@ -267,6 +267,17 @@ const streamTargetSchema = targetRefSchema
 export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
 export type OnStaleMode = z.infer<typeof onStaleModeSchema>;
 
+/** The exact authoritative position retained for one ReadSet entry. */
+export const readSetWatermarkSchema = z.number().int().nonnegative();
+export type ReadSetWatermark = z.infer<typeof readSetWatermarkSchema>;
+
+/** Maximum decision-input entries one logical commit may ask the server to scan. */
+export const MAX_READ_SET_ENTRIES = 500;
+
+/** A persisted entry cannot overwrite: it observes future writes, not its own. */
+export const trackOnStaleSchema = onStaleModeSchema.exclude(['overwrite']);
+export type TrackOnStale = z.infer<typeof trackOnStaleSchema>;
+
 /**
  * The optimistic guard carried on a commit operation. `readAt` is the
  * snapshot watermark from `context.capture` (null/absent ⇒ unguarded write).
@@ -274,7 +285,7 @@ export type OnStaleMode = z.infer<typeof onStaleModeSchema>;
  * claim — see the claim layer below.
  */
 export const writeGuardSchema = z.object({
-  readAt: z.number().nullish(),
+  readAt: readSetWatermarkSchema.nullish(),
   onStale: onStaleModeSchema.nullish(),
   bypass: z.boolean().optional(),
 });
@@ -445,42 +456,79 @@ export const staleNotificationSchema = z.discriminatedUnion('scope', [
 ]);
 export type StaleNotification = z.infer<typeof staleNotificationSchema>;
 
-/**
- * One entry in a commit's batch premise — a read it was based on, so the
- * server can ask "did anything I looked at change?" — broader than the
- * write-target check, which only validates the rows being written. The server
- * re-runs stale detection against each entry at its `readAt`; a moved premise
- * fires the entry's `onStale` disposition (default `reject`) across the whole
- * batch (`notify` holds every write and notifies, `reject` aborts, `overwrite`
- * proceeds silently). An entry comes at one of two granularities:
- *
- *   • Row   — `{ model, id, readAt, fields? }`: did this specific row, or these
- *             specific fields, change?
- *   • Group — `{ group, readAt }`: did anything in this sync group change?
- *             `group` is a sync-group key such as `report:abc` or `section:s1`, the
- *             same unit a participant watches and claims.
- *
- * See `packages/ablo/docs/concurrency-convention.md` (§4) for the
- * governing convention and the receive → reconcile loop.
- */
-const readRowDependencySchema = z.object({
+/** One row named by a commit-lifetime ReadSet entry. */
+export const readSetRowTargetSchema = z.object({
+  scope: z.literal('row'),
   model: z.string(),
   id: z.string(),
-  readAt: z.number(),
   fields: z.array(z.string()).readonly().optional(),
-  onStale: onStaleModeSchema.optional(),
 });
+export type ReadSetRowTarget = z.infer<typeof readSetRowTargetSchema>;
 
-const readGroupDependencySchema = z.object({
-  /**
-   * The caller-facing view of the format: `reads: [{ group: 'report:abc' }]`
-   * type-checks inline, `'nonsense'` does not. The
-   * {@link groupStaleNotificationSchema} this premise fires uses the branded
-   * view, because there Ablo is the author.
-   */
+/** One sync group named by a ReadSet entry. */
+export const readSetGroupTargetSchema = z.object({
+  scope: z.literal('group'),
   group: syncGroupRefSchema,
-  readAt: z.number(),
-  onStale: onStaleModeSchema.optional(),
+});
+export type ReadSetGroupTarget = z.infer<typeof readSetGroupTargetSchema>;
+
+export const commitReadSetTargetSchema = z.discriminatedUnion('scope', [
+  readSetRowTargetSchema,
+  readSetGroupTargetSchema,
+]);
+export type CommitReadSetTarget = z.infer<typeof commitReadSetTargetSchema>;
+
+/** Persisted row tracking is row-grained; it has no field storage axis. */
+export const persistedReadSetRowTargetSchema = readSetRowTargetSchema.omit({ fields: true });
+export const persistedReadSetTargetSchema = z.discriminatedUnion('scope', [
+  persistedReadSetRowTargetSchema,
+  readSetGroupTargetSchema,
+]);
+export type PersistedReadSetTarget = z.infer<typeof persistedReadSetTargetSchema>;
+
+/** One exact input to the decision made by this commit. */
+export const commitReadSetEntrySchema = z.object({
+  target: commitReadSetTargetSchema,
+  watermark: readSetWatermarkSchema,
+  lifetime: z.literal('commit'),
+  onStale: onStaleModeSchema,
+});
+export type CommitReadSetEntry = z.infer<typeof commitReadSetEntrySchema>;
+
+/** One exact input retained after the declaring commit settles. */
+export const persistedReadSetEntrySchema = z.object({
+  target: persistedReadSetTargetSchema,
+  watermark: readSetWatermarkSchema,
+  lifetime: z.literal('persisted'),
+  onStale: trackOnStaleSchema,
+});
+export type PersistedReadSetEntry = z.infer<typeof persistedReadSetEntrySchema>;
+
+export const readSetEntrySchema = z.discriminatedUnion('lifetime', [
+  commitReadSetEntrySchema,
+  persistedReadSetEntrySchema,
+]);
+export type ReadSetEntry = z.infer<typeof readSetEntrySchema>;
+
+export const readSetSchema = z
+  .array(readSetEntrySchema)
+  .max(MAX_READ_SET_ENTRIES)
+  .readonly();
+export type ReadSet = z.infer<typeof readSetSchema>;
+
+/**
+ * Wire projection of a commit-lifetime ReadSet entry. The public field names
+ * stay compatible (`readAt`, flat row/group target); every member is selected
+ * from the canonical entry rather than restated beside it.
+ */
+const readRowDependencySchema = readSetRowTargetSchema.omit({ scope: true }).extend({
+  readAt: commitReadSetEntrySchema.shape.watermark,
+  onStale: commitReadSetEntrySchema.shape.onStale.optional(),
+});
+
+const readGroupDependencySchema = readSetGroupTargetSchema.omit({ scope: true }).extend({
+  readAt: commitReadSetEntrySchema.shape.watermark,
+  onStale: commitReadSetEntrySchema.shape.onStale.optional(),
 });
 
 export const readDependencySchema = z.union([
@@ -490,14 +538,14 @@ export const readDependencySchema = z.union([
 export type ReadDependency = z.infer<typeof readDependencySchema>;
 
 /**
- * A durable premise — what a participant is watching so that a later
+ * A durable ReadSet entry — what a participant is watching so that a later
  * change to it opens a {@link StaleNotification}. Where a {@link ReadDependency}
  * is checked once at commit and discarded, a `TrackDependency` is kept and
  * re-checked against every future delta. The row form watches one object; the
  * group form watches a whole sync group ("anything in `report:abc`"). See
  * `packages/ablo/docs/groups.md` for how it drives change propagation.
  *
- * It is a PROJECTION of the ephemeral premise, not a second declaration of the
+ * It is a projection of the canonical persisted entry, not a second declaration of the
  * same reference: a track names its target exactly as a read does, and the
  * three ways it differs are stated here as omissions the compiler holds.
  *
@@ -514,18 +562,10 @@ export type ReadDependency = z.infer<typeof readDependencySchema>;
  *     registered the track, so a caller with nothing to say about when it last
  *     looked gets "from here on".
  *
- * A field added to the premise reaches both halves; a field the durable half
+ * A field added to the ReadSet target reaches both halves; a field the durable half
  * genuinely cannot carry has to be omitted here on purpose, in one line, rather
  * than by being quietly left out of a copy.
  */
-/**
- * A track's disposition — the premise enum with `overwrite` subtracted, derived
- * from it rather than spelled again, so a mode added to the convention reaches
- * a track unless it is deliberately excluded here.
- */
-export const trackOnStaleSchema = onStaleModeSchema.exclude(['overwrite']);
-export type TrackOnStale = z.infer<typeof trackOnStaleSchema>;
-
 /**
  * What a track does when the caller says nothing — reporting, the behavior every
  * track had before the disposition existed, so an existing registration is
@@ -539,18 +579,32 @@ export type TrackOnStale = z.infer<typeof trackOnStaleSchema>;
 export const DEFAULT_TRACK_ON_STALE: TrackOnStale = 'notify';
 
 const trackBaseSchema = {
-  readAt: z.number().optional(),
-  onStale: trackOnStaleSchema.optional(),
+  readAt: persistedReadSetEntrySchema.shape.watermark.optional(),
+  onStale: persistedReadSetEntrySchema.shape.onStale.optional(),
 } as const;
 
 export const trackDependencySchema = z.union([
-  readRowDependencySchema
-    .omit({ onStale: true, fields: true, readAt: true })
-    .extend(trackBaseSchema),
-  readGroupDependencySchema.omit({ onStale: true, readAt: true }).extend(trackBaseSchema),
+  persistedReadSetRowTargetSchema.omit({ scope: true }).extend(trackBaseSchema),
+  readSetGroupTargetSchema.omit({ scope: true }).extend(trackBaseSchema),
 ]);
 export type TrackDependency = z.infer<typeof trackDependencySchema>;
 
+/** Bounded wire projections of the two ReadSet lifetimes. */
+export const readDependencyListSchema = z
+  .array(readDependencySchema)
+  .max(MAX_READ_SET_ENTRIES);
+export const trackDependencyListSchema = z
+  .array(trackDependencySchema)
+  .max(MAX_READ_SET_ENTRIES);
+
+/** Shared combined-cardinality rule for envelopes carrying both projections. */
+export function readSetProjectionEntryCount(value: {
+  readonly reads?: readonly unknown[] | null;
+  readonly track?: readonly unknown[] | null;
+}): number {
+  return (value.reads?.length ?? 0) + (value.track?.length ?? 0);
+}
+
 // ─────────────────────────────────────────────────────────────────────────
 //  Layer 2 — pessimistic claims and leases
 // ─────────────────────────────────────────────────────────────────────────
@@ -1328,7 +1382,12 @@ export type UpdateSubscriptionPayload = z.infer<
 export const subscriptionAckPayloadSchema = z.object({
   success: z.boolean(),
   syncGroups: z.array(z.string()),
-  error: z.object({ code: z.string(), message: z.string() }).optional(),
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+    request_id: z.string().optional(),
+    event_id: z.string().optional(),
+  }).optional(),
 });
 export type SubscriptionAckPayload = z.infer<
   typeof subscriptionAckPayloadSchema
@@ -1360,6 +1419,12 @@ export const commitOperationSchema = writeGuardSchema.extend({
   input: z.record(z.string(), z.unknown()).nullish(),
   /** Per-op client tx id, echoed on the broadcast delta. */
   transactionId: z.string().nullish(),
+  /**
+   * The server-issued claim identity this operation was performed under.
+   * Distinct from `transactionId`: a claim attributes and fences coordinated
+   * ownership, while a transaction id correlates the resulting source echo.
+   */
+  claimId: z.string().min(1).nullish(),
   /**
    * The fencing token from the held claim this write belongs to (Option B).
    * Present only on a write issued under a claim that was granted one; the