@abloatai/transaction 0.37.0

package/src/coordination/claimHeartbeatLoop.ts

@@ -0,0 +1,165 @@
+/**
+ * The auto-heartbeat loop behind `claim({ id, heartbeat: true })` — one
+ * implementation shared by both transports (the WebSocket claim stream and the
+ * private HTTP transport), so the cadence and failure semantics cannot drift.
+ *
+ * A beat is the "still working" signal that keeps a lease alive for the
+ * duration of real work. The loop's failure handling follows the lease-system
+ * convention (SQS visibility heartbeats, Kubernetes leases): a beat that fails
+ * for a transient reason — the network blipped, the server was briefly
+ * unavailable — is simply retried on the next tick, because the lease has
+ * runway to spare by construction (the default cadence is a third of the TTL,
+ * so two consecutive beats can fail before the lease is even at risk). Only a
+ * definitive answer from the server — the lease lapsed and may have been
+ * granted to the next in line ({@link AbloClaimedError}) — stops the loop and
+ * surfaces the loss, because for a caller with no push channel the failed beat
+ * IS the loss notification.
+ */
+
+import { AbloClaimedError } from '../errors.js';
+import type {
+  ClaimHeartbeat,
+  ClaimHeartbeatOptions,
+  Duration,
+} from '../types/streams.js';
+import { toMs } from '../utils/duration.js';
+
+/**
+ * Normalize the public `heartbeat(options?)` argument — a bare Duration is
+ * shorthand for `{ ttl }`. Shared by both transports' handle assembly so the
+ * shorthand cannot drift.
+ */
+export function resolveHeartbeatOptions(
+  input: Duration | ClaimHeartbeatOptions | undefined,
+): ClaimHeartbeatOptions {
+  if (input === undefined) return {};
+  if (typeof input === 'string' || typeof input === 'number') {
+    return { ttl: input };
+  }
+  return input;
+}
+
+/**
+ * The structured spelling of the auto-heartbeat — cadence and both callbacks
+ * in one place, so the lease axis of a claim is two members (`ttl`,
+ * `heartbeat`) rather than four. `true` and a bare Duration remain the
+ * shorthands: `heartbeat: '2m'` ≡ `heartbeat: { every: '2m' }`.
+ */
+export interface ClaimHeartbeatPlan {
+  /** Cadence between beats. Omitted: a third of the TTL, so two beats can
+   *  fail before the lease is at risk. */
+  readonly every?: Duration;
+  /** Called after every successful beat (auto or manual) with the server's
+   *  answer — chiefly `queueDepth`, the cooperative-yield pressure signal. */
+  readonly onBeat?: (beat: ClaimHeartbeat) => void;
+  /** Called once when a beat learns the lease is no longer yours. The loop
+   *  has already stopped; abandon the work or re-claim. */
+  readonly onLost?: (error: AbloClaimedError) => void;
+}
+
+/** What the handle assembly reads, whichever spelling the caller used. */
+export interface ResolvedHeartbeatPlan {
+  /** Whether the auto-beat loop runs at all. */
+  readonly loop: boolean;
+  /** Feed for {@link heartbeatCadenceMs} — `true` means the TTL-derived default. */
+  readonly cadence: true | Duration;
+  readonly onBeat?: (beat: ClaimHeartbeat) => void;
+  readonly onLost?: (error: AbloClaimedError) => void;
+}
+
+/**
+ * One reading of the heartbeat option, shared by both transports' handle
+ * assembly — cadence and callbacks from whichever spelling the caller used
+ * (`true`, a bare Duration, or the structured plan).
+ */
+export function resolveHeartbeatPlan(options: {
+  readonly heartbeat?: true | Duration | ClaimHeartbeatPlan;
+}): ResolvedHeartbeatPlan {
+  const { heartbeat } = options;
+  if (heartbeat !== undefined && typeof heartbeat === 'object') {
+    return {
+      loop: true,
+      cadence: heartbeat.every ?? true,
+      ...(heartbeat.onBeat ? { onBeat: heartbeat.onBeat } : {}),
+      ...(heartbeat.onLost ? { onLost: heartbeat.onLost } : {}),
+    };
+  }
+  return {
+    loop: Boolean(heartbeat),
+    cadence: heartbeat === undefined || heartbeat === true ? true : heartbeat,
+  };
+}
+
+/**
+ * The beat cadence for a lease of `ttlMs`: an explicit duration when the
+ * caller set one, otherwise a third of the TTL (floored at 1s) — the
+ * DynamoDB-lock-client rule, leaving two missed beats of runway before the
+ * lease is at risk while keeping crash recovery within one beat window.
+ */
+export function heartbeatCadenceMs(
+  ttlMs: number,
+  heartbeat: true | Duration,
+): number {
+  if (heartbeat !== true) return toMs(heartbeat);
+  return Math.max(Math.floor(ttlMs / 3), 1_000);
+}
+
+export interface ClaimHeartbeatLoopOptions {
+  /** Send one beat; resolves while the lease is still ours. */
+  beat(): Promise<ClaimHeartbeat>;
+  /** Cadence between beats. Callers default this to a third of the TTL. */
+  intervalMs: number;
+  /**
+   * Called once when a beat comes back with a definitive loss — the lease
+   * expired or was taken. The loop has already stopped by the time this runs.
+   */
+  onLost?(error: AbloClaimedError): void;
+}
+
+/**
+ * Start beating. Returns a stop function; callers stop the loop when the
+ * claim is released (all held-claim assembly sites tie this to `release`).
+ * Beats never overlap: a tick that fires while the previous beat is still
+ * in flight is skipped rather than stacked.
+ */
+export function startClaimHeartbeatLoop(
+  options: ClaimHeartbeatLoopOptions,
+): () => void {
+  let stopped = false;
+  let inFlight = false;
+
+  const stop = (): void => {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(timer);
+  };
+
+  const timer = setInterval(() => {
+    if (stopped || inFlight) return;
+    inFlight = true;
+    options
+      .beat()
+      .catch((error: unknown) => {
+        if (stopped) return;
+        if (error instanceof AbloClaimedError) {
+          stop();
+          options.onLost?.(error);
+          return;
+        }
+        // Transient (connection, brief server unavailability): the next tick
+        // is the retry — the ttl/3 cadence leaves runway for missed beats.
+      })
+      .finally(() => {
+        inFlight = false;
+      });
+  }, options.intervalMs);
+  // The loop must never be what keeps a Node process alive — the held work
+  // is. A worker that finishes without releasing exits anyway, and the lease
+  // lapses on schedule. No-op in browsers (where setInterval returns a number
+  // without `unref`), which is why the call is optional even though the Node
+  // timer type always has it.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  timer.unref?.();
+
+  return stop;
+}

package/src/coordination/claimMeta.ts

@@ -0,0 +1,56 @@
+/**
+ * A claim's application metadata, crossing between the wire and the shape the
+ * program declared for it.
+ *
+ * The wire contract for `meta` is deliberately permissive — `targetRefSchema`
+ * parses it as `z.record(z.string(), z.unknown())` and always will, because a
+ * newer peer must be able to send a field this build has never heard of and
+ * still be understood. The read surface is the opposite: `Register`'s
+ * `ClaimMeta` slot names the one shape this program's claims carry, so
+ * `claim.state({ id })?.target.meta` reads without a guard.
+ *
+ * Those two facts meet here, and only here, in both directions. A decode calls
+ * {@link declaredMeta} on its way from a parsed record to a public `Claim`; the
+ * locator projection calls {@link wireMeta} on the way back out, where a
+ * caller's declared value is put on the socket or in the HTTP body. Between
+ * them they are the one place the SDK takes the caller's word for a shape it
+ * did not check — written down once, with the reason, instead of being asserted
+ * at each crossing.
+ *
+ * The two directions are not symmetric in cost. Losing the declared shape on
+ * the way out is harmless, because the wire has always accepted any record;
+ * gaining it on the way in is the promise the read surface makes, so
+ * `declaredMeta` is the one to audit when a claim reads back a shape its holder
+ * never wrote.
+ */
+
+import type { ResolveClaimMeta } from '../types/global.js';
+
+/**
+ * Read a parsed `meta` as the declared shape. Call it only where a decode hands
+ * a wire value to a public claim, and only for a value already known present —
+ * the absent case is an omitted member, not a declared-shaped `undefined`.
+ *
+ * The exported names are `declaredMeta` and `wireMeta` rather than a `claimMeta`
+ * pair because two claim surfaces already read a caller's `meta` back off the
+ * options it passed in, and spell that local reader `claimMeta`.
+ */
+export function declaredMeta(raw: unknown): ResolveClaimMeta {
+  return raw as ResolveClaimMeta;
+}
+
+/**
+ * Write a declared `meta` as the permissive record the wire carries. Every path
+ * from a caller's target to a frame or request body goes through `subTarget`,
+ * so this has exactly one caller — widening it is how the declared shape stops
+ * being a compile error at the edge of the protocol instead of stopping there.
+ *
+ * The parameter is `unknown` rather than {@link ResolveClaimMeta} on purpose: a
+ * program may register an `interface` for its claim metadata, and an interface
+ * carries no implicit index signature, so a directly-typed parameter would make
+ * the conversion itself unrepresentable at the one site that needs it. Widening
+ * the input is what keeps the assertion single.
+ */
+export function wireMeta(meta: unknown): Record<string, unknown> {
+  return meta as Record<string, unknown>;
+}

package/src/coordination/events.ts

@@ -0,0 +1,86 @@
+/**
+ * In-process observation events emitted by the transaction layer's
+ * coordination protocol. The wire claim and stale-write contracts live in
+ * `coordination/schema.ts`; these two projections are the stable event shapes
+ * an observer receives after those frames have been interpreted.
+ */
+
+import type { ParticipantKind } from '../types/participant.js';
+
+export type { ClaimEventReason } from './schema.js';
+import type { ClaimEventReason } from './schema.js';
+
+/** The participant that blocked a claim — present on `rejected`. */
+export interface ClaimCounterparty {
+  /** Who holds it. */
+  actor?: string;
+  /**
+   * Whether the holder is a person, an agent, or the system — the distinction
+   * a caller acts on, since yielding to a person and queueing behind an agent
+   * are different decisions. It lives here rather than on the event because
+   * only a counterparty has a kind worth reporting: on an acquisition the
+   * participant is you, and you already know what you are.
+   */
+  participantKind?: ParticipantKind;
+  /** The lease they hold, so a caller can poll or wait on it by id. */
+  claimId?: string;
+  /** When their lease lapses without a heartbeat. */
+  expiresAt?: number;
+  /** What they said they were doing — prose, for a person to read. */
+  description?: string;
+}
+
+/** A single state transition in the lifecycle of a claim. */
+export interface ClaimEvent {
+  phase:
+    | 'acquired'
+    | 'queued'
+    | 'granted'
+    | 'lost'
+    | 'rejected'
+    | 'expired';
+  claimId?: string;
+  model?: string;
+  id?: string;
+  field?: string;
+  actor?: string;
+  position?: number;
+  /**
+   * What this claim's holder said they were doing — prose, written for a
+   * person. Separate from {@link ClaimEvent.reason}, which is machine-readable
+   * and only ever says why a claim ended. One field used to carry both, so an
+   * `acquired` event's "reason" was really a description and a `rejected`
+   * event's was really a cause.
+   */
+  description?: string;
+  /** Why the claim ended or was refused. Absent while it is simply alive. */
+  reason?: ClaimEventReason;
+  /**
+   * A policy's own words when a policy decided the outcome — free text by
+   * nature, and kept beside the closed {@link ClaimEvent.reason} rather than
+   * collapsed into it.
+   */
+  policyReason?: string;
+  /**
+   * Who blocked this claim. Present on `rejected`, where the wire already
+   * carried the holder and this projection used to discard it.
+   */
+  heldBy?: ClaimCounterparty;
+}
+
+/** A committed notify-instead-of-abort stale-write collision. */
+export interface ConflictEvent {
+  clientTxId: string;
+  rows: readonly {
+    model: string;
+    id: string;
+    fields: readonly string[];
+    writtenBy?: ParticipantKind;
+  }[];
+}
+
+/** The narrow behavior a transaction-layer coordination observer implements. */
+export interface CoordinationObserver {
+  captureClaim(event: ClaimEvent): void;
+  captureConflict(event: ConflictEvent): void;
+}

package/src/coordination/index.ts

@@ -0,0 +1,181 @@
+/**
+ * The `@abloatai/transaction/coordination` entry point. It re-exports the wire
+ * schemas and inferred types for the three coordination layers: presence (who
+ * is currently active), claims (taking exclusive hold of a target before
+ * writing it), and stale-context guards (rejecting a write that was based on an
+ * out-of-date read). The definitions themselves live in the sibling schema
+ * module.
+ *
+ * Exports are listed by name rather than re-exported wholesale, so every symbol
+ * that becomes part of this package's public API is a deliberate choice.
+ */
+
+// Runtime schemas + helpers.
+export {
+  // Shared primitives
+  participantKindSchema,
+  wireParticipantKindSchema,
+  participantKindFromWire,
+  descriptionFromMeta,
+  claimDescription,
+  DEFAULT_CLAIM_DESCRIPTION,
+  targetRefSchema,
+  // Layer 3 — optimistic stale-context
+  onStaleModeSchema,
+  writeGuardSchema,
+  staleNotificationSchema,
+  readDependencySchema,
+  trackDependencySchema,
+  // Layer 2 — pessimistic claim / claim-lease
+  claimStatusSchema,
+  wireClaimStatusSchema,
+  wireClaimSummarySchema,
+  claimErrorSchema,
+  wireClaimSchema,
+  claimRejectionSchema,
+  // The rest of the claim frames, each the validation boundary for one
+  // server-sent event — see WS_INBOUND_FRAMES for where they are applied.
+  claimLostSchema,
+  claimAcquiredSchema,
+  claimGrantedSchema,
+  claimQueuedSchema,
+  claimQueueSchema,
+  claimQueueEntrySchema,
+  claimExpiredSchema,
+  claimEventReasonSchema,
+  modelTargetSchema,
+  // The one claim record, and the peer-visible projection of it.
+  claimRecordSchema,
+  heldClaimStatusSchema,
+  modelClaimSchema,
+  claimBeginPayloadSchema,
+  claimAbandonPayloadSchema,
+  claimReorderPayloadSchema,
+  claimHeartbeatPayloadSchema,
+  claimHeartbeatAckPayloadSchema,
+  claimHeartbeatBatchPayloadSchema,
+  claimHeartbeatBatchAckPayloadSchema,
+  // Read interest — what a connection receives, leased (`claim`/`release`,
+  // the frames behind `join`) and unleased (`update_subscription`).
+  MAX_FRAME_SYNC_GROUPS,
+  participantClaimPayloadSchema,
+  participantReleasePayloadSchema,
+  updateSubscriptionPayloadSchema,
+  subscriptionAckPayloadSchema,
+  // Commit operation — carries the optimistic write-guard
+  commitOperationTypeSchema,
+  commitOperationSchema,
+  // Layer 1 — presence
+  presenceKindSchema,
+  presenceActivitySchema,
+  presenceUpdateSchema,
+  presenceUpdatePayloadSchema,
+  // Deprecated alias, removed in 0.36.0 — this line publishes it.
+  // eslint-disable-next-line @typescript-eslint/no-deprecated
+  presenceUpdateFrameSchema,
+} from './schema.js';
+
+// Conflict-policy runtime — the engine detects a conflict, and the policy
+// decides what to do about it. These are re-exported here so that server-side
+// code can reach both the coordination vocabulary and its default conflict
+// resolution from this one subpath, without importing the full client from the
+// package root.
+export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../policy/types.js';
+export type {
+  Conflict,
+  ConflictAxis,
+  ConflictDecision,
+  ConflictKind,
+  ConflictOperation,
+  ConflictPolicy,
+  StaleContextConflict,
+  ClaimHeldConflict,
+} from '../policy/types.js';
+
+// Inferred types, one per schema (plus the standalone aliases).
+export type {
+  // Shared primitives
+  ParticipantKind,
+  TargetRef,
+  // Layer 3 — optimistic stale-context
+  OnStaleMode,
+  WriteGuard,
+  StaleNotification,
+  ReadDependency,
+  TrackDependency,
+  // Layer 2 — pessimistic claim / claim-lease
+  ClaimStatus,
+  WireClaimStatus,
+  WireClaimSummary,
+  ClaimError,
+  WireClaim,
+  ClaimRejection,
+  ClaimLost,
+  ClaimAcquired,
+  ClaimGranted,
+  ClaimQueued,
+  ClaimQueue,
+  ClaimQueueEntry,
+  ClaimExpired,
+  ClaimEventReason,
+  ModelTarget,
+  ClaimRecord,
+  HeldClaimStatus,
+  ModelClaim,
+  ClaimBeginPayload,
+  ClaimAbandonPayload,
+  ClaimReorderPayload,
+  ClaimHeartbeatPayload,
+  ClaimHeartbeatAckPayload,
+  ClaimHeartbeatBatchPayload,
+  ClaimHeartbeatBatchAckPayload,
+  // Read interest — leased and unleased
+  ParticipantClaimPayload,
+  ParticipantReleasePayload,
+  UpdateSubscriptionPayload,
+  SubscriptionAckPayload,
+  // Commit operation — carries the optimistic write-guard
+  CommitOperationType,
+  CommitOperation,
+  AnyCommitOperation,
+  // Layer 1 — presence
+  PresenceKind,
+  PresenceActivity,
+  PresenceUpdate,
+  PresenceUpdatePayload,
+  // eslint-disable-next-line @typescript-eslint/no-deprecated
+  PresenceUpdateFrame,
+} from './schema.js';
+
+// In-process observation events. These are behavior-facing projections, not
+// duplicate wire declarations; the wire contracts remain in schema.ts.
+export type {
+  ClaimEvent,
+  ClaimCounterparty,
+  ConflictEvent,
+  CoordinationObserver,
+} from './events.js';
+
+// The conflict rule itself — whether two claims on one row collide. It is the
+// protocol's decision, not the server's deployment of it, so it lives here and
+// every claim authority imports it.
+export { targetsConflict } from './targetConflict.js';
+
+// The locator itself — what a claim points at, and the projections that keep
+// its three entity spellings (`entityType`/`entityId`, `model`/`id`,
+// `type`/`id`) saying the same thing while they coexist.
+export type {
+  BatchFence,
+  ClaimTargetDetails,
+  ClaimTargetSource,
+  EntityLocator,
+} from './locator.js';
+export {
+  batchFence,
+  fenceTokenFor,
+  isTargetTuple,
+  subTarget,
+  wireTarget,
+  modelTarget,
+  streamTarget,
+} from './locator.js';

package/src/coordination/locator.ts

@@ -0,0 +1,200 @@
+/**
+ * The locator — what a claim points at, in every spelling it travels under.
+ *
+ * A target has two halves. The sub-entity half (`path`, `range`, `field`,
+ * `fields`, `meta`) is spelled identically everywhere; the entity half is not.
+ * It is `entityType`/`entityId` on the wire, `model`/`id` on the HTTP DTO and
+ * the SDK's model surface, and `type`/`id` on the claim handle and the wait
+ * line. The three coexist deliberately — unifying them changes every surface at
+ * once, and that is scheduled behind the protocol version — but while they
+ * coexist, the translation between them belongs in one place.
+ *
+ * It was copied member by member at more than twenty sites instead, which is
+ * how `fields` came to be added to the schema and to the conflict rule while
+ * several hops quietly dropped it: the rule learned to compare field sets while
+ * no path carried one, so the fix looked complete and changed nothing. Widening
+ * the locator again should touch this module and the schema, not every hop.
+ */
+
+import type { ClaimPart, ModelTarget, TargetRef, WireClaim } from './schema.js';
+import {
+  fieldSelection,
+  type FieldRef,
+  type FieldSelector,
+} from '../schema/fieldRef.js';
+import { partName } from './schema.js';
+import type { ClaimTarget, PresenceTarget } from '../types/streams.js';
+import type { ResolveClaimMeta } from '../types/global.js';
+// The one declared→wire conversion for claim metadata; `declaredMeta` is its
+// counterpart, called by the decodes that build a public claim.
+import { wireMeta } from './claimMeta.js';
+
+/**
+ * The part of a claim that narrows it below the whole entity. A claim with none
+ * of these set is a claim on the entity itself.
+ *
+ * `meta` is carried because it travels with the target everywhere else, not
+ * because the rule reads it: application metadata is opaque to coordination and
+ * never decides a conflict.
+ */
+export type ClaimTargetDetails = Pick<
+  WireClaim,
+  'field' | 'fields' | 'meta'
+>;
+
+/**
+ * A locator as a *caller* may hold it — identical to {@link ClaimTargetDetails}
+ * except that `meta` may already be the shape the program registered on
+ * `Register`'s `ClaimMeta` slot, which an `interface` registration makes
+ * distinct from the wire's open record.
+ *
+ * A projection that only accepted the wire spelling would push the conversion
+ * back out to every call site that starts from a public target — the claim
+ * handle, the model surface, the HTTP claim params — which is the same
+ * member-by-member copying this module exists to end.
+ */
+export type ClaimTargetSource<T = Record<string, unknown>> =
+  Omit<ClaimTargetDetails, 'meta' | 'field' | 'fields'> & {
+  /** A schema field reference, wire name, or low-level app-defined part. */
+  readonly field?: string | ClaimPart | FieldRef;
+  readonly fields?:
+    | readonly (string | ClaimPart | FieldRef)[]
+    | FieldSelector<T>;
+  readonly meta?: ClaimTargetDetails['meta'] | ResolveClaimMeta;
+};
+
+/**
+ * Copy the sub-entity part of a locator from one target shape to another.
+ *
+ * These five members are spelled identically wherever a target appears, so this
+ * owns all of them and the entity half is handled by its own projections below.
+ *
+ * Absent members are omitted rather than set to `undefined`, so a projected
+ * target can be spread into an object under `exactOptionalPropertyTypes`.
+ *
+ * The result is wire-shaped, `meta` included: this is the projection every path
+ * out of the SDK goes through, so it is also the single declared→wire crossing
+ * for claim metadata. The way back is {@link declaredMeta}, at the two decodes
+ * that build a public claim.
+ */
+export function subTarget<T = Record<string, unknown>>(
+  // `null` as well as absent, because the claim body declares its target
+  // nullish and the projection is most useful exactly where that body is read.
+  source: ClaimTargetSource<T> | null | undefined,
+  model?: string,
+): ClaimTargetDetails {
+  if (!source) return {};
+  const selection =
+    typeof source.fields === 'function'
+      ? source.fields(fieldSelection(model ?? ''))
+      : source.fields;
+  const selectedFields =
+    selection === undefined
+      ? undefined
+      : Array.isArray(selection)
+        ? selection
+        : [selection];
+  return {
+    // Part names cross to their wire spelling here — the one declared→wire
+    // seam — so a `part('B2')` object never leaks into a frame or a URL.
+    ...(source.field !== undefined ? { field: partName(source.field) } : {}),
+    ...(selectedFields !== undefined ? { fields: selectedFields.map(partName) } : {}),
+    ...(source.meta !== undefined ? { meta: wireMeta(source.meta) } : {}),
+  };
+}
+
+/**
+ * Whether a target was given in the `[type, id]` shorthand rather than the
+ * object form.
+ *
+ * A predicate rather than an assertion, because `Array.isArray` leaves a
+ * readonly tuple in both branches and the alternative — asserting the object
+ * form — describes the locator by hand at every call site that resolves one.
+ */
+export function isTargetTuple(
+  target: PresenceTarget,
+): target is readonly [type: string, id: string] {
+  return Array.isArray(target);
+}
+
+/**
+ * An entity named in any of the three spellings a claim travels under.
+ *
+ * The union is discriminated by which key is present, and `{ model, id }` and
+ * `{ type, id }` share `id` — so the read below tests `entityType` first, then
+ * `model`, and falls through to `type`. A source carrying both `model` and
+ * `type` is not expressible here and does not occur; it would take the earlier
+ * branch if it did.
+ */
+export type EntityLocator =
+  | Pick<TargetRef, 'entityType' | 'entityId'>
+  | Pick<ModelTarget, 'model' | 'id'>
+  | Pick<ClaimTarget, 'type' | 'id'>;
+
+/** The entity as a name and an identifier, whichever spelling named it. */
+function entityOf(source: EntityLocator): readonly [string, string] {
+  if ('entityType' in source) return [source.entityType, source.entityId];
+  if ('model' in source) return [source.model, source.id];
+  return [source.type, source.id];
+}
+
+/** The entity half in the wire's spelling — claim frames, presence activity. */
+export function wireTarget(
+  source: EntityLocator,
+): Pick<TargetRef, 'entityType' | 'entityId'> {
+  const [entityType, entityId] = entityOf(source);
+  return { entityType, entityId };
+}
+
+/** The entity half in the spelling SDK callers and the HTTP routes read. */
+export function modelTarget(
+  source: EntityLocator,
+): Pick<ModelTarget, 'model' | 'id'> {
+  const [model, id] = entityOf(source);
+  return { model, id };
+}
+
+/** The entity half as the claim handle and the wait line carry it. */
+export function streamTarget(
+  source: EntityLocator,
+): Pick<ClaimTarget, 'type' | 'id'> {
+  const [type, id] = entityOf(source);
+  return { type, id };
+}
+
+/**
+ * A batch claim's grant: its fencing token, and the one row it was granted over.
+ *
+ * A claim's `readAt` generalises across a batch; its token does not. The token
+ * is evidence of one row's place in the grant order, so it belongs only on the
+ * operation writing the row the claim covers. Presented anywhere else the server
+ * refuses it, because a token that travels is a fence any writer can raise.
+ */
+export type BatchFence = Pick<ModelTarget, 'model' | 'id'> & {
+  readonly token: number;
+};
+
+/** The batch's grant, or nothing when there is no claim, or none with a token. */
+export function batchFence(
+  source: EntityLocator | null | undefined,
+  token: number | null | undefined,
+): BatchFence | null {
+  return source == null || token == null
+    ? null
+    : { ...modelTarget(source), token };
+}
+
+/**
+ * The token an operation carries: its own if it names one, the batch's when it
+ * writes the claimed row, otherwise none.
+ */
+export function fenceTokenFor(
+  fence: BatchFence | null,
+  model: string,
+  id: string | null,
+): number | null {
+  if (fence === null || id === null) return null;
+  return model.toLowerCase() === fence.model.toLowerCase() && id === fence.id
+    ? fence.token
+    : null;
+}