@abloatai/ablo 0.34.0 → 0.35.0

package/dist/transaction/coordination/claimMeta.js

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+/**
+ * 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) {
+    return raw;
+}
+/**
+ * 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) {
+    return meta;
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Creates a {@link ClaimStream} over a live sync connection. A claim is a
+ * short-lived, advisory lease a participant takes on an entity (or a field of
+ * one) to signal "I'm working on this"; the stream lets you take claims, see
+ * everyone else's, and watch the wait queue when a claim is contended.
+ *
+ * The stream is built directly on the sync WebSocket and shares that one
+ * connection. It learns about other participants' claims from the same
+ * `presence_update` frames the {@link createPresenceStream} presence stream
+ * consumes — the server piggybacks each participant's `activeClaims` on every
+ * presence frame — and sends its own claims as `claim_begin` and
+ * `claim_abandon` frames.
+ *
+ * Wire frames:
+ *   • Outbound `claim_begin` — announce a claim: `{ claimId, entityType,
+ *       entityId, description, field?, estimatedMs? }`.
+ *   • Outbound `claim_abandon` — release it: `{ claimId, entityType?,
+ *       entityId? }`.
+ *   • Inbound, via presence — `event.activeClaims`, each stamped with
+ *       `declaredAt` and `expiresAt`.
+ *   • Inbound `claim_rejected` — the server refused the claim, with conflict
+ *       metadata.
+ */
+import type { WsTransport } from '../transport/wsTransport.js';
+import type { ClaimOptions, Claim, ClaimStream, PresenceTarget } from '../types/streams.js';
+import { type Logger } from '../logger.js';
+/**
+ * The wire capability the claim stream actually uses: subscribe to typed
+ * inbound frames, check liveness, and send outbound frames. The duplex
+ * `WsTransport` satisfies it, so production wiring is unchanged — but depending on the port
+ * rather than the whole socket class lets a test drive it with a plain object,
+ * no cast. `Pick` carries the exact (generic, typed-payload) `subscribe`
+ * signature, so every handler stays fully typed.
+ */
+export type ClaimTransport = Pick<WsTransport, 'subscribe' | 'isConnected' | 'send'>;
+export interface ClaimStreamConfig {
+    /** Identity used to filter our own active claims out of `others`. */
+    participantId: string;
+    /** Where the coordination trace is logged. Defaults to silent. */
+    logger?: Logger;
+}
+export interface AttachableClaimStream extends ClaimStream {
+    /**
+     * Mints a lease directly: sends the `claim_begin` frame and returns a held
+     * {@link Claim} that carries no row `data` (the resource layer reads the row
+     * and stamps it). This is an internal entry point, not part of the public
+     * {@link ClaimStream}; application code takes a claim through
+     * `ablo.<model>.claim({ id })`, which is built on this.
+     */
+    claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
+    attach(transport: ClaimTransport): void;
+    /**
+     * Seeds the participant identity once the host resolves it. The stream can
+     * be built before identity is known — a hosted client learns who it is
+     * from its credential's scope during connect — and until then the
+     * construction-time id (possibly empty) would let the participant's own
+     * claims into `others`. Idempotent; later frames filter on the new id.
+     */
+    setParticipant(participant: {
+        id: string;
+    }): void;
+    dispose(): void;
+}
+export declare function createClaimStream(config: ClaimStreamConfig, transport?: ClaimTransport | null): AttachableClaimStream;

package/dist/transaction/coordination/createClaimStream.js

@@ -0,0 +1,475 @@
+/**
+ * Creates a {@link ClaimStream} over a live sync connection. A claim is a
+ * short-lived, advisory lease a participant takes on an entity (or a field of
+ * one) to signal "I'm working on this"; the stream lets you take claims, see
+ * everyone else's, and watch the wait queue when a claim is contended.
+ *
+ * The stream is built directly on the sync WebSocket and shares that one
+ * connection. It learns about other participants' claims from the same
+ * `presence_update` frames the {@link createPresenceStream} presence stream
+ * consumes — the server piggybacks each participant's `activeClaims` on every
+ * presence frame — and sends its own claims as `claim_begin` and
+ * `claim_abandon` frames.
+ *
+ * Wire frames:
+ *   • Outbound `claim_begin` — announce a claim: `{ claimId, entityType,
+ *       entityId, description, field?, estimatedMs? }`.
+ *   • Outbound `claim_abandon` — release it: `{ claimId, entityType?,
+ *       entityId? }`.
+ *   • Inbound, via presence — `event.activeClaims`, each stamped with
+ *       `declaredAt` and `expiresAt`.
+ *   • Inbound `claim_rejected` — the server refused the claim, with conflict
+ *       metadata.
+ */
+import { asyncIteratorFrom } from '../utils/asyncIterator.js';
+import { toMs } from '../utils/duration.js';
+import { claimDescription, descriptionFromMeta, participantKindFromWire, } from './schema.js';
+import { isTargetTuple, subTarget, streamTarget, wireTarget, } from './locator.js';
+import { declaredMeta } from './claimMeta.js';
+import { AbloClaimedError, AbloConnectionError } from '../errors.js';
+import { resolveHeartbeatOptions } from './claimHeartbeatLoop.js';
+import { noopLogger } from '../logger.js';
+/** Readable target for the coordination trace: `documents:abc` / `documents:abc.title`. */
+function claimLabel(type, id, field) {
+    return field ? `${type}:${id}.${field}` : `${type}:${id}`;
+}
+/**
+ * How long a heartbeat waits for its `claim_heartbeat_ack` before giving up
+ * as transient (the auto-heartbeat loop's next tick retries). Comfortably
+ * above a round trip, comfortably below the ttl/3 beat cadence.
+ */
+const HEARTBEAT_ACK_TIMEOUT_MS = 10_000;
+export function createClaimStream(config, transport = null) {
+    // Mutable: the host seeds the resolved identity via `setParticipant` once
+    // it is known; the own-claim filter always reads the current value.
+    let participantId = config.participantId;
+    const logger = config.logger ?? noopLogger;
+    // ── State: others' open claims, keyed by claimId ───────────────
+    const activeByClaimId = new Map();
+    let claimsSnapshot = Object.freeze([]);
+    // ── State: our own open claims (for re-announce on reconnect) ───
+    const ownClaims = new Map();
+    // ── State: per-entity wait queues, from `claim_queue` frames ────
+    // Keyed `type:id`; the value is the FIFO line of queued claims. Powers
+    // the reactive `queue(target)` read — who's waiting and what they intend.
+    const queueByEntity = new Map();
+    const entityKey = (type, id) => `${type}:${id}`;
+    const EMPTY_QUEUE = Object.freeze([]);
+    // Last queue position we logged per own-claim, so advancing in line is traced
+    // once per change (not re-logged on every server re-fan of the same line).
+    const lastLoggedQueuePos = new Map();
+    // ── Subscribers ──────────────────────────────────────────────────
+    const listeners = new Set();
+    const rejectionListeners = new Set();
+    const lostListeners = new Set();
+    // ── State: in-flight heartbeats awaiting their ack, keyed by claimId ──
+    const pendingHeartbeats = new Map();
+    const settleHeartbeat = (claimId, settle) => {
+        const pending = pendingHeartbeats.get(claimId);
+        if (!pending)
+            return;
+        pendingHeartbeats.delete(claimId);
+        clearTimeout(pending.timer);
+        settle(pending);
+    };
+    const notifyListeners = () => {
+        claimsSnapshot = Object.freeze(Array.from(activeByClaimId.values()));
+        for (const l of listeners) {
+            try {
+                l();
+            }
+            catch {
+                /* listener errors don't break siblings */
+            }
+        }
+    };
+    // ── Wire wiring ──────────────────────────────────────────────────
+    let attached = null;
+    const unsubs = [];
+    function attach(t) {
+        if (attached)
+            return;
+        attached = t;
+        // (1) Inbound presence frames carry every participant's full
+        //     active-claim set. Prune previous claims by holder, then
+        //     re-add from the frame — the frame is authoritative for that
+        //     participant's open claims at that moment.
+        unsubs.push(t.subscribe('presence_update', (event) => {
+            if (!event.userId)
+                return;
+            if (event.userId === participantId)
+                return;
+            let mutated = false;
+            if (event.kind === 'leave') {
+                for (const [id, claim] of activeByClaimId) {
+                    if (claim.heldBy === event.userId) {
+                        activeByClaimId.delete(id);
+                        mutated = true;
+                    }
+                }
+                if (mutated)
+                    notifyListeners();
+                return;
+            }
+            for (const [id, claim] of activeByClaimId) {
+                if (claim.heldBy === event.userId) {
+                    activeByClaimId.delete(id);
+                    mutated = true;
+                }
+            }
+            for (const claim of event.activeClaims ?? []) {
+                // Terminal-status entries (committed / expired / canceled) are
+                // one-shot "this claim ended" signals. The holder sweep above
+                // already removed the prior active entry; skipping the re-add
+                // drops it from `others`, which is what resolves a contender's
+                // `settled()`. Absent status means active (wire back-compat).
+                if (claim.status && claim.status !== 'active')
+                    continue;
+                // Resolve the always-present public field, tolerating a frame that
+                // carries the value in `meta` rather than as an explicit description.
+                const description = claim.description ??
+                    descriptionFromMeta(claim.meta) ??
+                    'editing';
+                // The frame is parsed permissively, on purpose; `declaredMeta` is where
+                // that wire value becomes the shape the program declared.
+                const { meta, ...details } = subTarget(claim);
+                activeByClaimId.set(claim.claimId, {
+                    object: 'claim',
+                    id: claim.claimId,
+                    status: 'active',
+                    heldBy: event.userId,
+                    participantKind: participantKindFromWire(event.participantKind, event.isAgent),
+                    target: {
+                        ...streamTarget(claim),
+                        ...details,
+                        ...(meta !== undefined ? { meta: declaredMeta(meta) } : {}),
+                    },
+                    description,
+                    ttlSeconds: Math.max(0, Math.floor((claim.expiresAt - Date.now()) / 1000)),
+                    createdAt: claim.declaredAt,
+                    expiresAt: claim.expiresAt,
+                });
+                mutated = true;
+            }
+            if (mutated)
+                notifyListeners();
+        }));
+        // (2) Server-side rejection frames.
+        unsubs.push(t.subscribe('claim_rejected', (rejection) => {
+            if (!rejection.claimId)
+                return;
+            if (ownClaims.has(rejection.claimId)) {
+                const tgt = rejection.target
+                    ? claimLabel(rejection.target.entityType, rejection.target.entityId, rejection.target.field)
+                    : rejection.claimId;
+                logger.info(`claim: rejected ${tgt}${rejection.heldBy ? ` — held by ${rejection.heldBy}` : ''}`, { claimId: rejection.claimId, reason: rejection.reason });
+            }
+            // Drop the rejected own-claim so reconnect doesn't re-announce
+            // a claim the server already rejected (would just spam both
+            // sides with conflicts).
+            ownClaims.delete(rejection.claimId);
+            for (const l of rejectionListeners) {
+                try {
+                    l(rejection);
+                }
+                catch {
+                    /* isolate */
+                }
+            }
+        }));
+        // (2a) Server-side loss frames — you held the claim, then lost it
+        //      (preempted or expired). Distinct from a rejection, which is a claim
+        //      the server refused.
+        unsubs.push(
+        // The frame is validated by the transport's dispatcher against the same
+        // schema this parameter's type comes from, so it arrives proven.
+        t.subscribe('claim_lost', (lost) => {
+            if (ownClaims.has(lost.claimId)) {
+                const c = ownClaims.get(lost.claimId);
+                logger.info(`claim: lost ${c ? claimLabel(c.entityType, c.entityId, c.field) : lost.claimId} (preempted or expired)`, { claimId: lost.claimId });
+            }
+            // Drop the lost own-claim so reconnect doesn't re-announce a lease we
+            // no longer hold.
+            ownClaims.delete(lost.claimId);
+            for (const l of lostListeners) {
+                try {
+                    l(lost);
+                }
+                catch {
+                    /* isolate */
+                }
+            }
+        }));
+        // (2b) Per-entity wait-queue snapshots. The server fans the full line
+        //      out on every queue mutation; we replace our cached line for that
+        //      entity and notify so `queue(target)` reads reactively.
+        unsubs.push(t.subscribe('claim_queue', (p) => {
+            const key = entityKey(p.target.type, p.target.id);
+            const line = p.queue;
+            if (line.length === 0)
+                queueByEntity.delete(key);
+            else
+                // The wait line crosses from the wire into the public `Claim` shape
+                // like every other read does, so its meta goes through `declaredMeta`
+                // rather than arriving as the open record the frame was parsed as.
+                queueByEntity.set(key, Object.freeze(line.map((entry) => {
+                    const { meta, ...target } = entry.target;
+                    return {
+                        ...entry,
+                        target: {
+                            ...target,
+                            ...(meta !== undefined ? { meta: declaredMeta(meta) } : {}),
+                        },
+                    };
+                })));
+            // If we are in this line, trace our position (the "agent queued behind a
+            // claim" moment) — once per position change, so advancing is visible.
+            const ourIndex = line.findIndex((c) => ownClaims.has(c.id));
+            const ourClaim = ourIndex >= 0 ? line[ourIndex] : undefined;
+            if (ourClaim) {
+                const ourId = ourClaim.id;
+                if (lastLoggedQueuePos.get(ourId) !== ourIndex) {
+                    lastLoggedQueuePos.set(ourId, ourIndex);
+                    logger.info(`claim: queued for ${claimLabel(p.target.type, p.target.id)} — position ${ourIndex + 1} of ${line.length}, waiting`, { claimId: ourId });
+                }
+            }
+            notifyListeners();
+        }));
+        // (2c) Heartbeat replies — correlate back to the awaiting beat by
+        //      claimId. `held` resolves with the extended expiry; `queued` and
+        //      `lost` reject with a typed claimed error, because a heartbeat on
+        //      a handle we thought we held coming back as anything but `held`
+        //      means the lease is no longer ours.
+        unsubs.push(t.subscribe('claim_heartbeat_ack', (ack) => {
+            settleHeartbeat(ack.claimId, ({ resolve, reject }) => {
+                if (ack.status === 'held' && ack.expiresAt !== undefined) {
+                    resolve({
+                        expiresAt: ack.expiresAt,
+                        ...(ack.queueDepth !== undefined
+                            ? { queueDepth: ack.queueDepth }
+                            : {}),
+                    });
+                    return;
+                }
+                const c = ownClaims.get(ack.claimId);
+                reject(new AbloClaimedError(`The lease behind ${c ? claimLabel(c.entityType, c.entityId, c.field) : `claim ${ack.claimId}`} is no longer held — it expired or was granted onward while this participant was working. Re-acquire the claim and retry; a write attempted under the old lease is rejected by its \`readAt\` guard.`, { code: 'claim_lost' }));
+            });
+        }));
+        // (3) On reconnect, re-announce every open self-claim — the
+        //     server's claim state is in-memory and is lost across
+        //     restarts. Without this, peers would see our claims vanish
+        //     whenever the connection blipped.
+        unsubs.push(t.subscribe('connected', () => {
+            for (const [claimId, claim] of ownClaims) {
+                sendBegin(claimId, claim);
+            }
+        }));
+    }
+    if (transport)
+        attach(transport);
+    // ── Outbound ────────────────────────────────────────────────────
+    function sendBegin(claimId, claim) {
+        if (!attached?.isConnected())
+            return;
+        attached.send({
+            type: 'claim_begin',
+            payload: {
+                claimId,
+                ...wireTarget(claim),
+                description: claim.description,
+                ...subTarget(claim),
+                estimatedMs: claim.estimatedMs,
+                queue: claim.queue,
+            },
+        });
+    }
+    function sendReorder(entityType, entityId, order) {
+        if (!attached?.isConnected())
+            return;
+        attached.send({
+            type: 'claim_reorder',
+            payload: {
+                entityType,
+                entityId,
+                // The wire shape identifies a waiter by heldBy + claimId; map the
+                // ergonomic `Claim[]` (what `queueFor` returns) down to that.
+                order: order.map((i) => ({ heldBy: i.heldBy, claimId: i.id })),
+            },
+        });
+    }
+    /**
+     * Send one heartbeat and await its ack. Rejects with
+     * {@link AbloConnectionError} (transient — the auto-heartbeat loop retries
+     * on its next tick) when the socket is down or the ack times out, and with
+     * {@link AbloClaimedError} (definitive) when the server answers that the
+     * lease is no longer ours.
+     */
+    function sendHeartbeat(claimId, claim, options) {
+        if (!attached?.isConnected()) {
+            return Promise.reject(new AbloConnectionError(`The heartbeat for ${claimLabel(claim.entityType, claim.entityId, claim.field)} was skipped because the connection is down. The keepalive renews held leases automatically on reconnect; the next beat retries.`));
+        }
+        return new Promise((resolve, reject) => {
+            settleHeartbeat(claimId, ({ reject: rejectPrior }) => {
+                rejectPrior(new AbloConnectionError('A newer heartbeat for this claim superseded the one still awaiting its reply.'));
+            });
+            const timer = setTimeout(() => {
+                settleHeartbeat(claimId, ({ reject: rejectTimeout }) => {
+                    rejectTimeout(new AbloConnectionError(`No reply to the heartbeat for ${claimLabel(claim.entityType, claim.entityId, claim.field)} arrived within ${HEARTBEAT_ACK_TIMEOUT_MS / 1000}s. The next beat retries.`));
+                });
+            }, HEARTBEAT_ACK_TIMEOUT_MS);
+            pendingHeartbeats.set(claimId, { resolve, reject, timer });
+            attached?.send({
+                type: 'claim_heartbeat',
+                payload: {
+                    claimId,
+                    entityType: claim.entityType,
+                    entityId: claim.entityId,
+                    ...(options.ttl !== undefined ? { ttlMs: toMs(options.ttl) } : {}),
+                    ...(options.details !== undefined ? { details: options.details } : {}),
+                },
+            });
+        });
+    }
+    function sendAbandon(claimId, claim) {
+        if (!attached?.isConnected())
+            return;
+        // Carry the target so the server can dequeue us if we were only *waiting*
+        // (a queued claim isn't in the holder set it would otherwise scan). Held
+        // claims are found by claimId regardless; the target is harmless there.
+        attached.send({
+            type: 'claim_abandon',
+            payload: {
+                claimId,
+                entityType: claim?.entityType,
+                entityId: claim?.entityId,
+            },
+        });
+    }
+    // The locator half derives from `OwnClaim` rather than being restated: a
+    // member spelled out here is a member that dies before `sendBegin`, which is
+    // how `fields` used to be lost between `claim()` and the socket.
+    function mintHandle(args) {
+        const claimId = crypto.randomUUID();
+        const estimatedMs = args.ttl !== undefined ? toMs(args.ttl) : undefined;
+        // The handle the caller reads back is a public claim, so its `meta` is the
+        // declared shape; the `OwnClaim` below stays wire-typed, because that is
+        // what goes on the socket.
+        const { meta, ...details } = subTarget(args);
+        const claim = {
+            ...wireTarget(args),
+            ...subTarget(args),
+            description: args.description,
+            estimatedMs,
+            queue: args.queue,
+        };
+        ownClaims.set(claimId, claim);
+        sendBegin(claimId, claim);
+        // Coordination trace (info): the creator can see their human/agent claims.
+        logger.info(`claim: requesting ${claimLabel(claim.entityType, claim.entityId, claim.field)} for "${claim.description}"` +
+            (claim.queue ? ' (will queue if contended)' : ''), { claimId });
+        let revoked = false;
+        const revoke = () => {
+            if (revoked)
+                return;
+            revoked = true;
+            ownClaims.delete(claimId);
+            sendAbandon(claimId, claim);
+            logger.info(`claim: released ${claimLabel(claim.entityType, claim.entityId, claim.field)}`, { claimId });
+        };
+        return {
+            object: 'claim',
+            id: claimId,
+            status: 'active',
+            description: args.description,
+            target: {
+                ...streamTarget(args),
+                ...details,
+                ...(meta !== undefined ? { meta: declaredMeta(meta) } : {}),
+            },
+            release: async () => {
+                revoke();
+            },
+            revoke,
+            heartbeat: (options) => sendHeartbeat(claimId, claim, resolveHeartbeatOptions(options)),
+            [Symbol.asyncDispose]: async () => {
+                revoke();
+            },
+        };
+    }
+    function resolveTarget(target) {
+        if (isTargetTuple(target))
+            return { type: target[0], id: target[1] };
+        return target;
+    }
+    return {
+        claim(target, opts) {
+            const resolved = resolveTarget(target);
+            return mintHandle({
+                ...wireTarget(resolved),
+                ...subTarget(resolved),
+                description: claimDescription({ ...opts, meta: resolved.meta }),
+                ttl: opts?.ttl,
+                queue: opts?.queue,
+            });
+        },
+        get others() {
+            return claimsSnapshot;
+        },
+        queueFor(target) {
+            const ref = resolveTarget(target);
+            return queueByEntity.get(entityKey(ref.type, ref.id)) ?? EMPTY_QUEUE;
+        },
+        reorder(target, order) {
+            const ref = resolveTarget(target);
+            sendReorder(ref.type, ref.id, order);
+        },
+        onChange: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        onRejected: (listener) => {
+            rejectionListeners.add(listener);
+            return () => {
+                rejectionListeners.delete(listener);
+            };
+        },
+        onLost: (listener) => {
+            lostListeners.add(listener);
+            return () => {
+                lostListeners.delete(listener);
+            };
+        },
+        [Symbol.asyncIterator]() {
+            return asyncIteratorFrom((onChange) => {
+                listeners.add(onChange);
+                return () => {
+                    listeners.delete(onChange);
+                };
+            }, () => claimsSnapshot);
+        },
+        attach,
+        setParticipant(participant) {
+            participantId = participant.id;
+        },
+        dispose() {
+            for (const off of unsubs)
+                off();
+            unsubs.length = 0;
+            for (const claimId of [...pendingHeartbeats.keys()]) {
+                settleHeartbeat(claimId, ({ reject }) => {
+                    reject(new AbloConnectionError('The claim stream was disposed while this heartbeat was awaiting its reply.'));
+                });
+            }
+            listeners.clear();
+            rejectionListeners.clear();
+            lostListeners.clear();
+            activeByClaimId.clear();
+            ownClaims.clear();
+            queueByEntity.clear();
+            claimsSnapshot = Object.freeze([]);
+            attached = null;
+        },
+    };
+}

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

@@ -0,0 +1,74 @@
+/**
+ * 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/dist/transaction/coordination/events.js

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export {};