@abloatai/humans 0.37.0

package/dist/local/sync/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 '@abloatai/transaction/utils/asyncIterator';
+import { toMs } from '@abloatai/transaction/utils/duration';
+import { claimDescription, descriptionFromMeta, participantKindFromWire, } from '@abloatai/transaction/coordination/schema';
+import { isTargetTuple, subTarget, streamTarget, wireTarget, } from '@abloatai/transaction/coordination/locator';
+import { declaredMeta } from '@abloatai/transaction/coordination/claimMeta';
+import { AbloClaimedError, AbloConnectionError } from '@abloatai/transaction/errors';
+import { resolveHeartbeatOptions } from '@abloatai/transaction/coordination/claimHeartbeatLoop';
+import { noopLogger } from '@abloatai/transaction/logger';
+/** 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/local/sync/createSnapshot.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Captures a local {@link Snapshot} of a chosen set of entities, along with a
+ * watermark, so a caller can detect when that state has gone stale. This is
+ * what an LLM caller threads into a prompt: `stamp` flows into later writes as
+ * `readAt`, so the server rejects a mutation premised on data that has since
+ * changed; `signal` is an `AbortSignal` that fires as soon as any captured
+ * entity receives a delta, so a mid-generation invalidation can abort the token
+ * stream instead of producing output against stale context.
+ *
+ * It reads the current entity state from the in-memory pool, reads the engine's
+ * current `lastSyncId` as the watermark, and subscribes to delta frames on the
+ * existing sync connection — no second connection.
+ */
+import type { InstanceCache } from '../InstanceCache.js';
+import type { Schema } from '@abloatai/transaction/schema/schema';
+import type { SyncWebSocket } from './SyncWebSocket.js';
+import type { Snapshot } from '@abloatai/transaction/types/streams';
+export interface CreateSnapshotArgs<TSchema extends Schema = Schema, K extends keyof TSchema['models'] & string = keyof TSchema['models'] & string> {
+    pool: InstanceCache;
+    /** Live transport for delta subscriptions. May be null if the engine
+     *  hasn't connected yet — the snapshot still resolves with current
+     *  pool state, but `signal` won't fire until reconnect. */
+    transport: SyncWebSocket | null;
+    /** Returns the engine's current `lastSyncId`. Read at snapshot time
+     *  to stamp the watermark; not re-read after. */
+    getLastSyncId: () => number;
+    entities: Readonly<Record<K, string | readonly string[]>>;
+}
+export declare function createSnapshot<TSchema extends Schema, K extends keyof TSchema['models'] & string>(args: CreateSnapshotArgs<TSchema, K>): Snapshot<TSchema, K>;

package/dist/local/sync/createSnapshot.js

@@ -0,0 +1,116 @@
+/**
+ * Captures a local {@link Snapshot} of a chosen set of entities, along with a
+ * watermark, so a caller can detect when that state has gone stale. This is
+ * what an LLM caller threads into a prompt: `stamp` flows into later writes as
+ * `readAt`, so the server rejects a mutation premised on data that has since
+ * changed; `signal` is an `AbortSignal` that fires as soon as any captured
+ * entity receives a delta, so a mid-generation invalidation can abort the token
+ * stream instead of producing output against stale context.
+ *
+ * It reads the current entity state from the in-memory pool, reads the engine's
+ * current `lastSyncId` as the watermark, and subscribes to delta frames on the
+ * existing sync connection — no second connection.
+ */
+import { AbloValidationError } from '@abloatai/transaction/errors';
+import { modelAsRow } from '../Model.js';
+/**
+ * The snapshot result exposes `stamp`, `signal`, and `onChange` at its top
+ * level, alongside one bucket per model. If a schema declares a model with one
+ * of these names, the two would collide, so snapshot creation throws instead.
+ */
+const RESERVED_SNAPSHOT_KEYS = new Set([
+    'stamp',
+    'signal',
+    'onChange',
+]);
+export function createSnapshot(args) {
+    const { pool, transport, getLastSyncId, entities } = args;
+    // ── Validate keys ────────────────────────────────────────────────
+    for (const key of Object.keys(entities)) {
+        if (RESERVED_SNAPSHOT_KEYS.has(key)) {
+            throw new AbloValidationError(`engine.snapshot: model key "${key}" collides with a reserved ` +
+                `snapshot field (stamp / signal / onChange). Rename the model ` +
+                'in your schema.', { code: 'snapshot_reserved_key' });
+        }
+    }
+    // ── Watermark ────────────────────────────────────────────────────
+    const stamp = getLastSyncId();
+    // ── Capture data + watched set ───────────────────────────────────
+    const watched = new Set(); // `${type}:${id}`
+    const data = {};
+    for (const [type, idOrIds] of Object.entries(entities)) {
+        const ids = Array.isArray(idOrIds)
+            ? idOrIds
+            : [idOrIds];
+        const bucket = {};
+        for (const id of ids) {
+            const m = pool.get(id);
+            // Only include if the model actually has the requested type —
+            // pool keys models globally by id, so `pool.get(id)` could
+            // return a different model that happens to share the id (rare,
+            // but type guards keep the surface honest).
+            if (m &&
+                typeof m.getModelName === 'function' &&
+                m.getModelName() === type) {
+                bucket[id] = modelAsRow(m);
+            }
+            watched.add(`${type}:${id}`);
+        }
+        data[type] = bucket;
+    }
+    // ── Invalidation wiring ──────────────────────────────────────────
+    const listeners = new Set();
+    const controller = new AbortController();
+    const fireChange = (change) => {
+        if (!controller.signal.aborted) {
+            controller.abort(new Error('snapshot invalidated — underlying entity received a delta'));
+        }
+        for (const l of listeners) {
+            try {
+                l(change);
+            }
+            catch {
+                /* listener errors don't break siblings */
+            }
+        }
+    };
+    let unsubDelta = null;
+    if (transport) {
+        unsubDelta = transport.subscribe('delta', (delta) => {
+            const key = `${delta.modelName}:${delta.modelId}`;
+            if (!watched.has(key))
+                return;
+            // Every delta to a captured entity is reported as 'semantic' severity.
+            fireChange({
+                model: delta.modelName,
+                id: delta.modelId,
+                severity: 'semantic',
+            });
+        });
+    }
+    // ── Build the flat result ────────────────────────────────────────
+    const result = {
+        stamp,
+        signal: controller.signal,
+        onChange: (listener) => {
+            listeners.add(listener);
+            // The caller unsubscribes its own listener via the returned function.
+            // The underlying delta subscription lives for the snapshot's lifetime;
+            // there is no explicit dispose because a snapshot is short-lived (one
+            // LLM call's worth) and the subscription is cheap.
+            return () => {
+                listeners.delete(listener);
+                // Once the last listener is gone and the abort has fired, drop the
+                // delta subscription too — nothing is listening anymore.
+                if (listeners.size === 0 && controller.signal.aborted && unsubDelta) {
+                    unsubDelta();
+                    unsubDelta = null;
+                }
+            };
+        },
+    };
+    for (const [modelName, bucket] of Object.entries(data)) {
+        result[modelName] = bucket;
+    }
+    return result;
+}

package/dist/local/sync/credentialLifecycle.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Moved to the settlement core with the duplex transport (ADR 0016): keeping
+ * a long-lived socket's credential fresh is connection plumbing an agent needs
+ * as much as a browser does. This path re-exports it so existing importers
+ * stay unchanged.
+ */
+export { DEFAULT_PREROLL_INTERVAL_MS, MIN_PREROLL_DELAY_MS, computePrerollDelayMs, CredentialLifecycle, type CredentialRefreshOutcome, type CredentialRecoveryOutcome, type CredentialRefreshResult, type CredentialRefresher, type CredentialLifecycleContext, } from '@abloatai/transaction/transport/credentialLifecycle';

package/dist/local/sync/credentialLifecycle.js

@@ -0,0 +1,7 @@
+/**
+ * Moved to the settlement core with the duplex transport (ADR 0016): keeping
+ * a long-lived socket's credential fresh is connection plumbing an agent needs
+ * as much as a browser does. This path re-exports it so existing importers
+ * stay unchanged.
+ */
+export { DEFAULT_PREROLL_INTERVAL_MS, MIN_PREROLL_DELAY_MS, computePrerollDelayMs, CredentialLifecycle, } from '@abloatai/transaction/transport/credentialLifecycle';