@abloatai/ablo 0.35.0 → 0.36.0

package/dist/sync/deltaPipeline.js

@@ -11,8 +11,9 @@
  * and {@link flushPendingDeltas}.
  */
 import { runInAction } from 'mobx';
-import { getContext } from '../context.js';
+import { globalRuntime } from '../context.js';
 import { ModelScope } from '../InstanceCache.js';
+import { runStage, pluginsForStage, } from '../transaction/plugin.js';
 /**
  * Handles a sync-group ('G' or 'S') delta whose handler rejected after the
  * applied watermark had already advanced. That delta will never be redelivered,
@@ -22,7 +23,7 @@ import { ModelScope } from '../InstanceCache.js';
  * It never throws, because it runs inside the pipeline's fire-and-forget path.
  */
 export function handleGroupHandlerFailure(ctx, delta, error) {
-    getContext().logger.error('Your access changed but cached data could not be cleared — resetting local data.', {
+    (ctx.runtime ?? globalRuntime).logger.error('Your access changed but cached data could not be cleared — resetting local data.', {
         syncId: delta.id,
         error: error instanceof Error ? error.message : String(error),
     });
@@ -166,6 +167,8 @@ export function enqueueDelta(ctx, delta, options = {}) {
     if (delta.actionType === 'D') {
         ctx.cascadeCancelTransactionsForDeletedParent(delta.modelName, delta.modelId);
     }
+    // The delta is accepted and queued — the `receive` stage boundary.
+    runStage(ctx.stagePlugins ?? [], 'receive', { delta });
     ctx.pendingDeltas.push(delta);
     return true;
 }
@@ -190,7 +193,9 @@ export function scheduleDeltaFlush(ctx) {
 export async function flushPendingDeltas(ctx) {
     if (ctx.pendingDeltas.length === 0)
         return;
+    const stagePlugins = ctx.stagePlugins ?? [];
     const deduplicatedDeltas = ctx.deduplicateDeltas(ctx.pendingDeltas);
+    runStage(stagePlugins, 'dedupe', { deltas: deduplicatedDeltas });
     // Custom entities → apply straight to the pool, skipping the local store.
     const customDeltas = deduplicatedDeltas.filter((d) => ctx.isCustomEntity(d.modelName));
     if (customDeltas.length > 0) {
@@ -237,8 +242,18 @@ export async function flushPendingDeltas(ctx) {
         transactionId: d.transactionId,
     })));
     const dbResults = batch.results;
-    // Apply the batch results to the in-memory pool.
-    ctx.applyDeltaBatchToPool(dbResults);
+    runStage(stagePlugins, 'persist', { deltas: regularDeltas });
+    // Apply the batch results to the in-memory graph. When a plugin has
+    // declared the `apply` stage, its handlers ARE the apply — the
+    // materialiser attached where it said it would. The direct call is the
+    // bridge for stores constructed without plugins (subclasses, tests),
+    // whose own apply is the whole pipeline.
+    if (pluginsForStage(stagePlugins, 'apply').length > 0) {
+        runStage(stagePlugins, 'apply', { changes: dbResults });
+    }
+    else {
+        ctx.applyDeltaBatchToPool(dbResults);
+    }
     // Acknowledge and advance the sync cursor, gated on persistence.
     //
     // We must acknowledge `persistedSyncId` — the high-water mark of deltas whose
@@ -251,8 +266,10 @@ export async function flushPendingDeltas(ctx) {
     if (persistedSyncId > ctx.lastAckedId) {
         ctx.acknowledge(persistedSyncId);
         ctx.advancePersisted(persistedSyncId);
+        runStage(stagePlugins, 'acknowledge', { syncId: persistedSyncId });
     }
     // Cache invalidation happens automatically via the 'models:changed' event.
+    runStage(stagePlugins, 'notify', { changes: dbResults });
     ctx.pendingDeltas = [];
     if (ctx.batchTimer) {
         clearTimeout(ctx.batchTimer);

package/dist/sync/groupChange.d.ts

@@ -9,6 +9,7 @@
  * Every handler takes a {@link GroupChangeContext}, the narrow facade through
  * which it reaches the client's local storage and connection lifecycle hooks.
  */
+import type { RuntimeContext } from '../RuntimeContext.js';
 import type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload } from './SyncWebSocket.js';
 /**
  * The collaborators the group-change handlers depend on. It gathers the
@@ -55,6 +56,8 @@ export interface GroupChangeContext {
     handleGroupAdded(payload: GroupAddedPayload, syncId: number): Promise<void>;
     computeUpdatedSyncGroups(payload: SyncGroupChangePayload): string[];
     forceFullRebootstrap(): void;
+    /** The owning client's runtime. Defaults to the module-global bridge. */
+    readonly runtime?: RuntimeContext;
 }
 /**
  * Handles a 'G' (group-change) delta. The server sends two shapes of this

package/dist/sync/groupChange.js

@@ -9,7 +9,9 @@
  * Every handler takes a {@link GroupChangeContext}, the narrow facade through
  * which it reaches the client's local storage and connection lifecycle hooks.
  */
-import { getContext } from '../context.js';
+import { globalRuntime } from '../context.js';
+/** The context's runtime, falling back to the module-global bridge. */
+const runtimeOf = (ctx) => ctx.runtime ?? globalRuntime;
 /**
  * Marker returned when a group-change payload cannot be parsed, kept distinct
  * from a valid null or absent payload, which the handlers accept normally.
@@ -22,14 +24,14 @@ const MALFORMED_PAYLOAD = Symbol('malformed-group-change-payload');
  * would leave the delta pipeline after the watermark has already advanced. The
  * delta is never re-delivered, so the security clear it carried would be lost.
  */
-function parseGroupChangePayload(delta) {
+function parseGroupChangePayload(delta, runtime) {
     if (typeof delta.data !== 'string')
         return delta.data;
     try {
         return JSON.parse(delta.data);
     }
     catch (error) {
-        getContext().logger.debug('[BaseSyncedStore] Malformed group-change payload', {
+        runtime.logger.debug('[BaseSyncedStore] Malformed group-change payload', {
             syncId: delta.id,
             actionType: delta.actionType,
             error: error instanceof Error ? error.message : String(error),
@@ -44,7 +46,7 @@ function parseGroupChangePayload(delta) {
  * re-bootstrap from the server.
  */
 async function clearForUnknownGroupChange(ctx, delta, kind) {
-    getContext().logger.debug(`[BaseSyncedStore] Unreadable ${kind} payload — clearing cached data and re-bootstrapping`, { syncId: delta.id });
+    runtimeOf(ctx).logger.debug(`[BaseSyncedStore] Unreadable ${kind} payload — clearing cached data and re-bootstrapping`, { syncId: delta.id });
     // Revoked data must not persist if the device goes offline before the
     // re-bootstrap, the same reasoning as the explicit removed-groups path.
     await ctx.database.clear();
@@ -64,7 +66,7 @@ async function clearForUnknownGroupChange(ctx, delta, kind) {
  *   and refetch), clearing cached data first if any group was removed.
  */
 export async function handleSyncGroupChange(ctx, delta) {
-    const raw = parseGroupChangePayload(delta);
+    const raw = parseGroupChangePayload(delta, runtimeOf(ctx));
     if (raw === MALFORMED_PAYLOAD) {
         // The payload is unreadable, so we cannot tell which groups changed, and
         // this delta will never be re-delivered because the watermark has already
@@ -88,7 +90,7 @@ export async function handleSyncGroupChange(ctx, delta) {
         removedGroups: rawObj.removedGroups ?? [],
         addedGroups: rawObj.addedGroups ?? [],
     };
-    getContext().logger.info('[BaseSyncedStore] Sync group change received (legacy)', {
+    runtimeOf(ctx).logger.info('[BaseSyncedStore] Sync group change received (legacy)', {
         removedGroups: payload.removedGroups,
         addedGroups: payload.addedGroups,
         syncId: delta.id,
@@ -99,7 +101,7 @@ export async function handleSyncGroupChange(ctx, delta) {
     if (payload.removedGroups.length > 0) {
         await ctx.database.clear();
         ctx.objectPool.clear();
-        getContext().logger.info('[BaseSyncedStore] Cleared cached data due to revoked sync groups', {
+        runtimeOf(ctx).logger.info('[BaseSyncedStore] Cleared cached data due to revoked sync groups', {
             removedGroups: payload.removedGroups,
         });
     }
@@ -114,7 +116,7 @@ export async function handleSyncGroupChange(ctx, delta) {
  * through the normal insert path.
  */
 export async function handleGroupAdded(ctx, payload, syncId) {
-    getContext().logger.info('[BaseSyncedStore] Group added (incremental)', {
+    runtimeOf(ctx).logger.info('[BaseSyncedStore] Group added (incremental)', {
         group: payload.group,
         syncId,
     });
@@ -130,7 +132,7 @@ export async function handleGroupAdded(ctx, payload, syncId) {
  * local state and forces a re-bootstrap with the updated group list.
  */
 export async function handleGroupRemoved(ctx, delta) {
-    const raw = parseGroupChangePayload(delta);
+    const raw = parseGroupChangePayload(delta, runtimeOf(ctx));
     if (raw === MALFORMED_PAYLOAD) {
         // The payload is unreadable: access was revoked but we cannot tell which
         // group. Fall back to a full clear, the safe direction for an
@@ -141,12 +143,12 @@ export async function handleGroupRemoved(ctx, delta) {
     const rawObj = (raw ?? {});
     const groupKey = typeof rawObj.group === 'string' ? rawObj.group : undefined;
     if (!groupKey) {
-        getContext().logger.debug('[BaseSyncedStore] Group removed delta missing group key', {
+        runtimeOf(ctx).logger.debug('[BaseSyncedStore] Group removed delta missing group key', {
             syncId: delta.id,
         });
         return;
     }
-    getContext().logger.info('[BaseSyncedStore] Group removed', {
+    runtimeOf(ctx).logger.info('[BaseSyncedStore] Group removed', {
         group: groupKey,
         syncId: delta.id,
     });
@@ -181,7 +183,7 @@ export function computeUpdatedSyncGroups(ctx, payload) {
  */
 export function forceFullRebootstrap(ctx) {
     if (ctx.getBootstrapMode() === 'none') {
-        getContext().logger.info('[BaseSyncedStore] forceFullRebootstrap skipped (bootstrapMode=none)');
+        runtimeOf(ctx).logger.info('[BaseSyncedStore] forceFullRebootstrap skipped (bootstrapMode=none)');
         return;
     }
     ctx.database.markRequiresFullBootstrap();
@@ -219,7 +221,7 @@ export async function checkSyncGroupShrinkage(ctx) {
         const currentGroups = new Set(currentSyncGroups);
         const removedGroups = stored.filter((g) => !currentGroups.has(g));
         if (removedGroups.length > 0) {
-            getContext().logger.info('[BaseSyncedStore] Sync groups shrank — forcing full bootstrap', {
+            runtimeOf(ctx).logger.info('[BaseSyncedStore] Sync groups shrank — forcing full bootstrap', {
                 removedGroups,
                 storedCount: stored.length,
                 currentCount: currentGroups.size,
@@ -235,7 +237,7 @@ export async function checkSyncGroupShrinkage(ctx) {
         });
     }
     catch (error) {
-        getContext().logger.debug('[BaseSyncedStore] Failed to check sync group shrinkage', {
+        runtimeOf(ctx).logger.debug('[BaseSyncedStore] Failed to check sync group shrinkage', {
             error: error instanceof Error ? error.message : String(error),
         });
     }

package/dist/sync/participants.d.ts

@@ -1,3 +1,4 @@
+import type { JoinOptions } from '../transaction/resources/modelOperations.js';
 import type { SyncWebSocket } from './SyncWebSocket.js';
 import type { Schema } from '../transaction/schema/schema.js';
 import type { Claim, Activity, ClaimTarget, ClaimStream, Peer, PresenceStream, PresenceTarget } from '../transaction/types/streams.js';
@@ -17,7 +18,13 @@ export interface EngineParticipant {
     readonly presence: PresenceStream;
     readonly claims: ClaimStream;
 }
-export interface ParticipantJoinOptions {
+/**
+ * The options for a participant join. It extends the public per-model
+ * {@link JoinOptions} rather than restating its members, so the lease dial is
+ * declared once, in the core, and this surface adds only what a lower-level
+ * join can additionally say.
+ */
+export interface ParticipantJoinOptions extends JoinOptions {
     /**
      * The initial focus target, named in your schema's vocabulary and optionally
      * narrowed to a path, field, or range. When `scope` is omitted, this target
@@ -34,7 +41,17 @@ export interface ParticipantJoinOptions {
     readonly scope?: ParticipantScope;
     /** Present a narrower capability for this logical participant. */
     readonly capabilityToken?: string;
-    /** How long the claim lives, in seconds or a compact duration string (`30s`, `5m`). */
+    /**
+     * @deprecated Use `ttl`. Removed in 0.37.0.
+     *
+     * One lease, spelled two ways, and the seconds spelling was the one that
+     * misled: it accepted a duration string, so `ablo.<model>.join(ids, { ttl:
+     * '5m' })` reached this surface as `ttlSeconds: '5m'` — a field whose name
+     * asserts a unit its value did not carry. `ttl` takes the same values and is
+     * the spelling every other lease in the SDK already uses (`claim`'s `ttl`,
+     * `ClaimLeaseOptions.ttl`). The wire is unchanged: it has always carried
+     * seconds, and still does.
+     */
     readonly ttlSeconds?: number | string | null;
     /**
      * The activity to announce as soon as the claim is acknowledged. Defaults to

package/dist/sync/participants.js

@@ -17,7 +17,9 @@ export function createParticipantManager(config) {
             if (syncGroups.length > 0) {
                 await transport.sendClaim(claimId, syncGroups, {
                     capabilityToken: options.capabilityToken,
-                    ttlSeconds: parseParticipantTtlSeconds(options.ttlSeconds),
+                    // `ttl` is the spelling; `ttlSeconds` is the deprecated one, read
+                    // second so a caller passing both gets the current name honored.
+                    ttlSeconds: parseParticipantTtlSeconds(options.ttl ?? options.ttlSeconds),
                 });
             }
             const participant = createJoinedParticipant({

package/dist/sync/schemas.d.ts

@@ -6,6 +6,7 @@
  * that predates it.
  */
 import { z } from 'zod';
+import type { RuntimeContext } from "../RuntimeContext.js";
 /**
  * A delta as it arrives in a bootstrap payload.
  *
@@ -67,4 +68,4 @@ export type ValidatedBootstrapResponse = z.infer<typeof BootstrapResponseSchema>
  * result. On failure it records a diagnostic breadcrumb and throws an
  * {@link AbloValidationError} describing which fields were invalid.
  */
-export declare function parseBootstrapResponse(raw: unknown): ValidatedBootstrapResponse;
+export declare function parseBootstrapResponse(raw: unknown, runtime?: RuntimeContext): ValidatedBootstrapResponse;

package/dist/sync/schemas.js

@@ -6,7 +6,7 @@
  * that predates it.
  */
 import { z } from 'zod';
-import { getContext } from "../context.js";
+import { globalRuntime } from "../context.js";
 import { AbloValidationError } from "../transaction/errors.js";
 import { syncDeltaWireCoreSchema } from '../transaction/wire/delta.js';
 // ─── Server Delta Schema ─────────────────────────────────────────────────────
@@ -77,11 +77,11 @@ export const BootstrapResponseSchema = z
  * result. On failure it records a diagnostic breadcrumb and throws an
  * {@link AbloValidationError} describing which fields were invalid.
  */
-export function parseBootstrapResponse(raw) {
+export function parseBootstrapResponse(raw, runtime = globalRuntime) {
     const result = BootstrapResponseSchema.safeParse(raw);
     if (!result.success) {
         const issues = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
-        getContext().observability.breadcrumb('Bootstrap response validation failed', 'sync.bootstrap', 'error', {
+        runtime.observability.breadcrumb('Bootstrap response validation failed', 'sync.bootstrap', 'error', {
             issues,
             rawType: typeof raw,
             rawKeys: raw && typeof raw === 'object' ? Object.keys(raw).join(',') : 'n/a',

package/dist/syncLog/contract.d.ts

@@ -0,0 +1,20 @@
+/** Canonical sync-log identity and position contracts shared by client/server. */
+import { z } from 'zod';
+export declare const deltaPositionSchema: z.ZodNumber;
+export type DeltaPosition = z.infer<typeof deltaPositionSchema>;
+export declare const clientMutationIdSchema: z.ZodString;
+export type ClientMutationId = z.infer<typeof clientMutationIdSchema>;
+export declare const sourceCorrelationIdSchema: z.ZodString;
+export type SourceCorrelationId = z.infer<typeof sourceCorrelationIdSchema>;
+export declare const sourceChangeIdSchema: z.ZodString;
+export type SourceChangeId = z.infer<typeof sourceChangeIdSchema>;
+export declare const replicationLsnSchema: z.ZodString;
+export type ReplicationLSN = z.infer<typeof replicationLsnSchema>;
+export declare const commitDispatchMarkerSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"sync_deltas">;
+    organizationId: z.ZodString;
+    environment: z.ZodString;
+    firstSyncId: z.ZodNumber;
+    lastSyncId: z.ZodNumber;
+}, z.core.$strict>;
+export type CommitDispatchMarker = z.infer<typeof commitDispatchMarkerSchema>;

package/dist/syncLog/contract.js

@@ -0,0 +1,19 @@
+/** Canonical sync-log identity and position contracts shared by client/server. */
+import { z } from 'zod';
+import { environmentSchema } from '../environment.js';
+export const deltaPositionSchema = z.number().int().nonnegative().safe();
+export const clientMutationIdSchema = z.string().min(1).max(255);
+export const sourceCorrelationIdSchema = z.string().min(1).max(255);
+export const sourceChangeIdSchema = z.string().min(1).max(512);
+export const replicationLsnSchema = z.string().regex(/^[0-9A-Fa-f]+\/[0-9A-Fa-f]+$/);
+export const commitDispatchMarkerSchema = z.strictObject({
+    kind: z.literal('sync_deltas'),
+    organizationId: z.string().min(1),
+    environment: environmentSchema,
+    firstSyncId: deltaPositionSchema,
+    lastSyncId: deltaPositionSchema,
+}).superRefine((value, ctx) => {
+    if (value.firstSyncId <= 0 || value.lastSyncId < value.firstSyncId) {
+        ctx.addIssue({ code: 'custom', message: 'invalid delta position range' });
+    }
+});

package/dist/syncLog/index.d.ts

@@ -0,0 +1 @@
+export * from './contract.js';

package/dist/syncLog/index.js

@@ -0,0 +1 @@
+export * from './contract.js';

package/dist/transaction/auth/capability.d.ts

@@ -148,6 +148,41 @@ export declare const capabilityScopeSchema: z.ZodObject<{
     participantId: z.ZodString;
 }, z.core.$strip>;
 export type CapabilityScope = z.infer<typeof capabilityScopeSchema>;
+/**
+ * What `POST /v1/capabilities` answers with — **201**, the credential is minted.
+ *
+ * This is the first call any non-TypeScript client makes, and until it had a
+ * schema the published contract described it as `{ type: 'object' }`: a caller
+ * working from the reference could see that a capability could be minted and
+ * not where the token was in the reply.
+ *
+ * `scope` echoes what was MINTED, not what was asked. A `wideScope` mint stores
+ * the org-wide default and read-your-writes widens the verb axis, so a client
+ * that assumed its request came back verbatim would report a scope narrower
+ * than the one being enforced.
+ *
+ * `userMeta` is the caller's own blob, echoed. Ablo has no view into their user
+ * directory — the API key is what is trusted — so this is deliberately open.
+ */
+export declare const capabilityMintResponseSchema: z.ZodObject<{
+    capabilityId: z.ZodString;
+    token: z.ZodString;
+    expiresAt: z.ZodString;
+    organizationId: z.ZodString;
+    scope: z.ZodObject<{
+        organizationId: z.ZodString;
+        syncGroups: z.ZodArray<z.ZodString>;
+        operations: z.ZodArray<z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>>;
+        participantKind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        participantId: z.ZodString;
+    }, z.core.$strip>;
+    userMeta: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type CapabilityMintResponse = z.infer<typeof capabilityMintResponseSchema>;
 /**
  * `POST /v1/capabilities` — mint a capability for a participant.
  *

package/dist/transaction/auth/capability.js

@@ -157,6 +157,31 @@ export const capabilityScopeSchema = z.object({
     participantKind: participantKindSchema,
     participantId: z.string().min(1),
 });
+/**
+ * What `POST /v1/capabilities` answers with — **201**, the credential is minted.
+ *
+ * This is the first call any non-TypeScript client makes, and until it had a
+ * schema the published contract described it as `{ type: 'object' }`: a caller
+ * working from the reference could see that a capability could be minted and
+ * not where the token was in the reply.
+ *
+ * `scope` echoes what was MINTED, not what was asked. A `wideScope` mint stores
+ * the org-wide default and read-your-writes widens the verb axis, so a client
+ * that assumed its request came back verbatim would report a scope narrower
+ * than the one being enforced.
+ *
+ * `userMeta` is the caller's own blob, echoed. Ablo has no view into their user
+ * directory — the API key is what is trusted — so this is deliberately open.
+ */
+export const capabilityMintResponseSchema = z.object({
+    capabilityId: z.string().min(1),
+    token: z.string().min(1),
+    /** ISO 8601. */
+    expiresAt: z.string().min(1),
+    organizationId: z.string().min(1),
+    scope: capabilityScopeSchema,
+    userMeta: z.record(z.string(), z.unknown()),
+});
 /**
  * `POST /v1/capabilities` — mint a capability for a participant.
  *

package/dist/transaction/coordination/awaitClaimGrant.d.ts

@@ -44,6 +44,13 @@ export declare function awaitClaimGrant(transport: GrantTransport, claimId: stri
      * already ahead of us). Omit to wait however deep the queue is.
      */
     maxQueueDepth?: number;
+    /**
+     * Abort the wait from outside — the same signal that cancels everything
+     * else in the program. Rejects with `claim_wait_aborted`; once the grant
+     * has arrived the signal is ignored, so a held lease is never torn down
+     * by a late abort.
+     */
+    signal?: AbortSignal;
     /** Where grant transitions are logged. Defaults to silent. */
     logger?: Logger;
 }): Promise<ClaimGrantInfo>;

package/dist/transaction/coordination/awaitClaimGrant.js

@@ -101,6 +101,18 @@ export function awaitClaimGrant(transport, claimId, options) {
                 });
             }
         }));
+        if (options?.signal) {
+            const signal = options.signal;
+            const abort = () => settle(() => {
+                reject(new AbloClaimedError(`The wait for claim ${claimId} was aborted before the grant arrived.`, { code: 'claim_wait_aborted' }));
+            });
+            if (signal.aborted) {
+                abort();
+                return;
+            }
+            signal.addEventListener('abort', abort, { once: true });
+            unsubs.push(() => { signal.removeEventListener('abort', abort); });
+        }
         if (options?.timeoutMs && options.timeoutMs > 0) {
             timer = setTimeout(() => {
                 settle(() => {

package/dist/transaction/coordination/claimHeartbeatLoop.d.ts

@@ -23,6 +23,40 @@ import type { ClaimHeartbeat, ClaimHeartbeatOptions, Duration } from '../types/s
  * shorthand cannot drift.
  */
 export declare function resolveHeartbeatOptions(input: Duration | ClaimHeartbeatOptions | undefined): ClaimHeartbeatOptions;
+/**
+ * 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 declare function resolveHeartbeatPlan(options: {
+    readonly heartbeat?: true | Duration | ClaimHeartbeatPlan;
+}): ResolvedHeartbeatPlan;
 /**
  * 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

package/dist/transaction/coordination/claimHeartbeatLoop.js

@@ -30,6 +30,26 @@ export function resolveHeartbeatOptions(input) {
     }
     return input;
 }
+/**
+ * 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) {
+    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

package/dist/transaction/coordination/index.d.ts

@@ -9,11 +9,11 @@
  * 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.
  */
-export { targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, claimDescription, DEFAULT_CLAIM_DESCRIPTION, targetRefSchema, onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, trackDependencySchema, claimStatusSchema, wireClaimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, claimLostSchema, claimAcquiredSchema, claimGrantedSchema, claimQueuedSchema, claimQueueSchema, claimQueueEntrySchema, claimExpiredSchema, claimEventReasonSchema, modelTargetSchema, claimRecordSchema, heldClaimStatusSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateSchema, presenceUpdatePayloadSchema, presenceUpdateFrameSchema, } from './schema.js';
+export { targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, claimDescription, DEFAULT_CLAIM_DESCRIPTION, targetRefSchema, onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, trackDependencySchema, claimStatusSchema, wireClaimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, claimLostSchema, claimAcquiredSchema, claimGrantedSchema, claimQueuedSchema, claimQueueSchema, claimQueueEntrySchema, claimExpiredSchema, claimEventReasonSchema, modelTargetSchema, claimRecordSchema, heldClaimStatusSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, MAX_FRAME_SYNC_GROUPS, participantClaimPayloadSchema, participantReleasePayloadSchema, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateSchema, presenceUpdatePayloadSchema, presenceUpdateFrameSchema, } from './schema.js';
 export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../policy/types.js';
 export type { Conflict, ConflictAxis, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, ClaimHeldConflict, } from '../policy/types.js';
-export type { TargetRange, ParticipantKind, TargetRef, OnStaleMode, WriteGuard, StaleNotification, ReadDependency, TrackDependency, 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, UpdateSubscriptionPayload, SubscriptionAckPayload, CommitOperationType, CommitOperation, AnyCommitOperation, PresenceKind, PresenceActivity, PresenceUpdate, PresenceUpdatePayload, PresenceUpdateFrame, } from './schema.js';
+export type { TargetRange, ParticipantKind, TargetRef, OnStaleMode, WriteGuard, StaleNotification, ReadDependency, TrackDependency, 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, ParticipantClaimPayload, ParticipantReleasePayload, UpdateSubscriptionPayload, SubscriptionAckPayload, CommitOperationType, CommitOperation, AnyCommitOperation, PresenceKind, PresenceActivity, PresenceUpdate, PresenceUpdatePayload, PresenceUpdateFrame, } from './schema.js';
 export type { ClaimEvent, ClaimCounterparty, ConflictEvent, CoordinationObserver, } from './events.js';
 export { targetsConflict } from './targetConflict.js';
-export type { ClaimTargetDetails, ClaimTargetSource, EntityLocator, } from './locator.js';
-export { isTargetTuple, subTarget, wireTarget, modelTarget, streamTarget, } from './locator.js';
+export type { BatchFence, ClaimTargetDetails, ClaimTargetSource, EntityLocator, } from './locator.js';
+export { batchFence, fenceTokenFor, isTargetTuple, subTarget, wireTarget, modelTarget, streamTarget, } from './locator.js';

package/dist/transaction/coordination/index.js

@@ -22,8 +22,9 @@ claimStatusSchema, wireClaimStatusSchema, wireClaimSummarySchema, claimErrorSche
 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 — area-of-interest navigation
-updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, 
+// 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
@@ -41,4 +42,4 @@ export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '.
 // 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';
-export { isTargetTuple, subTarget, wireTarget, modelTarget, streamTarget, } from './locator.js';
+export { batchFence, fenceTokenFor, isTargetTuple, subTarget, wireTarget, modelTarget, streamTarget, } from './locator.js';

package/dist/transaction/coordination/locator.d.ts

@@ -15,7 +15,7 @@
  * 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 { ModelTarget, TargetRef, WireClaim } from './schema.js';
+import type { ClaimPart, ModelTarget, TargetRef, WireClaim } from './schema.js';
 import type { ClaimTarget, PresenceTarget } from '../types/streams.js';
 import type { ResolveClaimMeta } from '../types/global.js';
 /**
@@ -38,7 +38,10 @@ export type ClaimTargetDetails = Pick<WireClaim, 'path' | 'range' | 'field' | 'f
  * handle, the model surface, the HTTP claim params — which is the same
  * member-by-member copying this module exists to end.
  */
-export type ClaimTargetSource = Omit<ClaimTargetDetails, 'meta'> & {
+export type ClaimTargetSource = Omit<ClaimTargetDetails, 'meta' | 'field' | 'fields'> & {
+    /** A schema field name, or an app-defined part named with `part()`. */
+    readonly field?: string | ClaimPart;
+    readonly fields?: readonly (string | ClaimPart)[];
     readonly meta?: ClaimTargetDetails['meta'] | ResolveClaimMeta;
 };
 /**
@@ -81,3 +84,21 @@ export declare function wireTarget(source: EntityLocator): Pick<TargetRef, 'enti
 export declare function modelTarget(source: EntityLocator): Pick<ModelTarget, 'model' | 'id'>;
 /** The entity half as the claim handle and the wait line carry it. */
 export declare function streamTarget(source: EntityLocator): Pick<ClaimTarget, '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 declare function batchFence(source: EntityLocator | null | undefined, token: number | null | undefined): BatchFence | null;
+/**
+ * The token an operation carries: its own if it names one, the batch's when it
+ * writes the claimed row, otherwise none.
+ */
+export declare function fenceTokenFor(fence: BatchFence | null, model: string, id: string | null): number | null;