@abloatai/ablo 0.34.1 → 0.35.0

package/dist/sync/wsFrameHandlers.js

@@ -1,394 +1,8 @@
 /**
- * Routes each inbound frame from the sync WebSocket to the handler for its
- * type. Handlers work against a minimal {@link WsSession} interface — only
- * the members they actually touch, rather than the transport object itself,
- * which keeps this module free of an import cycle. Reading a message off the
- * socket, parsing its JSON, and tracking heartbeats all happen before this
- * point; every parsed frame then passes through {@link dispatchWsFrame}.
+ * Moved to the settlement core with the duplex transport (ADR 0016): the
+ * inbound frame dispatch is the receiving half of the wire protocol, and the
+ * handlers already worked against the minimal `WsSession` port rather than
+ * the transport object. This path re-exports it so existing importers stay
+ * unchanged.
  */
-import { getContext } from '../context.js';
-import { AbloConnectionError, CapabilityError, errorFromWire, } from '../errors.js';
-import { commitAckSchema, legacyCompatibleCommitReceiptSchema, } from '../wire/commit.js';
-import { subscriptionAckPayloadSchema } from '../coordination/schema.js';
-import { formatConflict } from '../coordination/trace.js';
-import { parseNotifications, recordClaim } from './commitFrames.js';
-/** Narrow arbitrary wire data to a plain string-keyed record. */
-export function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-/**
- * A type guard for the parsed result of an inbound message. A frame is any
- * plain object whose `type`, when present, is a string. Validating the
- * payload itself is left to each handler; delta payloads, for example, are
- * checked against the canonical delta schema before they are applied.
- */
-export function isWsInboundFrame(value) {
-    if (!isRecord(value))
-        return false;
-    const type = value.type;
-    return type === undefined || typeof type === 'string';
-}
-/**
- * Handles the acknowledgement of a `commit` request. The canonical wire
- * shape is `MutationResultMessage`. The payload is parsed defensively
- * rather than cast, since it is untrusted and may be malformed or sent by
- * an older server.
- */
-const handleMutationResult = (session, message) => {
-    const p = (message.payload ?? message);
-    const { clientTxId, success, error } = p;
-    // Defensive: validate notifications against the canonical schema —
-    // untrusted wire data from a possibly-older/newer server.
-    const notifications = parseNotifications(p?.notifications);
-    const missingIds = Array.isArray(p.missingIds)
-        ? [
-            ...new Set(p.missingIds.filter((id) => typeof id === 'string' && id.length > 0)),
-        ]
-        : undefined;
-    const pending = typeof clientTxId === 'string'
-        ? session.pendingMutations.get(clientTxId)
-        : undefined;
-    if (!pending)
-        return;
-    clearTimeout(pending.timeout);
-    // `pending` exists ⇒ clientTxId was a string key (the guard above).
-    session.pendingMutations.delete(clientTxId);
-    if (success) {
-        const parsedReceipt = legacyCompatibleCommitReceiptSchema.safeParse({
-            ...p,
-            notifications,
-            missingIds,
-        });
-        if (!parsedReceipt.success) {
-            pending.reject(new AbloConnectionError('The sync server returned an invalid commit receipt; its outcome remains pending and is safe to retry.', { code: 'commit_no_result', cause: parsedReceipt.error }));
-            return;
-        }
-        const receipt = parsedReceipt.data;
-        // The write succeeded, but a guarded premise shifted underneath it.
-        // Emit the advisory signal so a caller can react, and still resolve
-        // the receipt, since the commit itself went through.
-        if (receipt.notifications && receipt.notifications.length > 0) {
-            const txId = receipt.clientTxId;
-            const event = {
-                clientTxId: txId,
-                rows: receipt.notifications.map((n) => ({
-                    model: n.model,
-                    id: n.id,
-                    fields: n.conflictingFields,
-                    writtenBy: n.writtenBy.kind,
-                })),
-            };
-            const message = formatConflict(event);
-            const ctx = getContext();
-            ctx.logger.warn(message);
-            ctx.observability.breadcrumb(message, 'sync.coordination', 'warning');
-            ctx.observability.captureConflict(event);
-            session.emit('conflict:notified', {
-                clientTxId: txId,
-                notifications: receipt.notifications,
-            });
-        }
-        pending.resolve(commitAckSchema.parse({
-            status: receipt.status,
-            ...(receipt.correlationId
-                ? { correlationId: receipt.correlationId }
-                : {}),
-            lastSyncId: receipt.lastSyncId,
-            ...(receipt.notifications && receipt.notifications.length > 0
-                ? { notifications: receipt.notifications }
-                : {}),
-            ...(receipt.missingIds && receipt.missingIds.length > 0
-                ? { missingIds: receipt.missingIds }
-                : {}),
-        }));
-    }
-    else {
-        // Capture the full server error so the caller can see what actually
-        // rejected the mutation, rather than a generic "mutation failed on
-        // server". Object errors are stringified so structured server payloads,
-        // such as validation issues, survive being wrapped in an Error.
-        let errorMessage;
-        let errorCode;
-        let requiredCapability;
-        if (typeof error === 'string') {
-            errorMessage = error;
-        }
-        else if (error != null && typeof error === 'object') {
-            const obj = error;
-            if (typeof obj.code === 'string')
-                errorCode = obj.code;
-            if (typeof obj.message === 'string') {
-                errorMessage = obj.message;
-            }
-            else {
-                try {
-                    errorMessage = JSON.stringify(error);
-                }
-                catch {
-                    errorMessage = String(error);
-                }
-            }
-            if (obj.requiredCapability != null &&
-                typeof obj.requiredCapability === 'object' &&
-                typeof obj.requiredCapability.scope === 'string') {
-                requiredCapability = obj.requiredCapability;
-            }
-        }
-        else {
-            errorMessage = 'mutation failed on server';
-        }
-        // A stale-context rejection (the write read state that has since
-        // changed) or a foreign-claim conflict is a coordination collision.
-        // The success-with-notifications path above records the conflict, and a
-        // hard rejection must record it too, or the collision count would miss
-        // every rejected write. The conflicting rows ride along on the typed
-        // error's `conflicts` detail.
-        if (errorCode === 'stale_context' ||
-            errorCode === 'claim_conflict' ||
-            errorCode === 'entity_claimed' ||
-            errorCode?.startsWith('policy:') === true) {
-            const rawConflicts = error != null &&
-                typeof error === 'object' &&
-                Array.isArray(error.conflicts)
-                ? error
-                    .conflicts
-                : [];
-            const conflictEvent = {
-                clientTxId: typeof clientTxId === 'string' ? clientTxId : '',
-                rows: rawConflicts.map((r) => ({
-                    model: typeof r.model === 'string' ? r.model : 'unknown',
-                    id: typeof r.id === 'string' ? r.id : 'unknown',
-                    fields: [],
-                })),
-            };
-            const ctx = getContext();
-            ctx.observability.breadcrumb(formatConflict(conflictEvent), 'sync.coordination', 'warning');
-            ctx.observability.captureConflict(conflictEvent);
-        }
-        // Build the proper typed AbloError from the wire code via the
-        // shared factory — the same code→class mapping the HTTP commit
-        // path uses (`translateHttpError`). This keeps rejected commits
-        // inside the typed hierarchy (capability denials →
-        // CapabilityError with `.requiredCapability`; foreign-claim
-        // conflicts → AbloClaimedError; everything else → the subclass
-        // its registry `httpStatus` implies) instead of a hand-rolled
-        // `new Error`, so callers can `instanceof`/`e.type` it and
-        // downstream retry logic can read the contract's retryability.
-        pending.reject(errorFromWire(errorMessage, {
-            code: errorCode,
-            requiredCapability,
-        }));
-    }
-};
-/**
- * Handles the acknowledgement of a `claim` request. The frame has the shape
- * `{ type: 'claim_ack', payload: { claimId, success, syncGroups?,
- * ttlSeconds?, error? } }`.
- */
-const handleClaimAck = (session, message) => {
-    const p = (message.payload ?? {});
-    const { claimId, success, syncGroups, ttlSeconds, error } = p;
-    const pending = typeof claimId === 'string'
-        ? session.pendingClaims.get(claimId)
-        : undefined;
-    if (!pending)
-        return;
-    clearTimeout(pending.timeout);
-    // `pending` exists ⇒ claimId was a string key (the guard above).
-    session.pendingClaims.delete(claimId);
-    if (success) {
-        pending.resolve({
-            syncGroups: Array.isArray(syncGroups) ? syncGroups : [],
-            ttlSeconds: typeof ttlSeconds === 'number' ? ttlSeconds : undefined,
-        });
-    }
-    else {
-        const err = error;
-        const code = err?.code && typeof err.code === 'string'
-            ? err.code
-            : 'claim_rejected';
-        const msg = err?.message && typeof err.message === 'string'
-            ? err.message
-            : 'claim rejected by server';
-        // Capability denials get the typed CapabilityError so
-        // callers can read `.requiredCapability` and attenuate-
-        // and-retry the claim with a narrower token.
-        if (code === 'capability_scope_denied' ||
-            code === 'capability_invalid') {
-            const rc = error
-                ?.requiredCapability;
-            const requiredCapability = rc != null &&
-                typeof rc === 'object' &&
-                typeof rc.scope === 'string'
-                ? rc
-                : undefined;
-            pending.reject(new CapabilityError(code, msg, requiredCapability));
-        }
-        else {
-            // Route through the shared factory so a failed claim_ack is a
-            // typed AbloError (registry code → right subclass), symmetric
-            // with the commit `mutation_result` path — never a bare Error.
-            pending.reject(errorFromWire(msg, { code }));
-        }
-    }
-};
-/**
- * Handles the acknowledgement of an `update_subscription` request. The wire
- * carries no correlation id, so the ack is matched to the oldest pending
- * request in first-in, first-out order, since the server applies and
- * acknowledges subscription updates in the order it receives them. The
- * payload is validated against its canonical schema before use.
- */
-const handleSubscriptionAck = (session, message) => {
-    const pending = session.shiftPendingSubscription();
-    if (!pending)
-        return;
-    clearTimeout(pending.timeout);
-    const parsed = subscriptionAckPayloadSchema.safeParse(message.payload);
-    if (!parsed.success) {
-        // Unreadable ack — resolve the pending request as a failure
-        // rather than hang it until timeout.
-        pending.reject(errorFromWire('malformed subscription_ack from server', {
-            code: 'malformed_subscription',
-        }));
-        return;
-    }
-    const ack = parsed.data;
-    if (ack.success) {
-        // Keep the reconnect URL aligned with current interest: a
-        // reconnect re-subscribes from `this.options.syncGroups`.
-        session.options.syncGroups = ack.syncGroups;
-        pending.resolve({ syncGroups: ack.syncGroups });
-    }
-    else {
-        pending.reject(errorFromWire(ack.error?.message ?? 'update_subscription rejected by server', { code: ack.error?.code ?? 'malformed_subscription' }));
-    }
-};
-/**
- * Handles a `delta` frame, which carries either a single delta or a
- * `{ deltas: [...] }` batch. This only tells the two shapes apart; each
- * delta is validated once downstream, so batch elements are passed along
- * raw rather than parsed here.
- */
-const handleDeltaFrame = (session, message) => {
-    const p = message.payload;
-    if (!isRecord(p))
-        return;
-    if (p.actionType || p.modelName) {
-        session.handleDelta(p);
-    }
-    else if (Array.isArray(p.deltas)) {
-        for (const d of p.deltas) {
-            session.handleDelta(d);
-        }
-        // `p.newVersions` from older servers is ignored; `sync_id` is the
-        // causality token.
-    }
-};
-/**
- * Maps each frame type to its handler. Every named server frame this
- * package understands is dispatched from this table; anything else falls
- * through to the collaboration-event and unknown-type path in
- * {@link dispatchWsFrame}.
- */
-export const wsFrameHandlers = {
-    sync_response: (session, message) => { session.handleSyncResponse(message.payload); },
-    bootstrap_response: (session, message) => { session.handleBootstrapResponse(message.payload); },
-    presence_update: (session, message) => { session.handlePresenceUpdate(message); },
-    mutation_result: handleMutationResult,
-    claim_ack: handleClaimAck,
-    subscription_ack: handleSubscriptionAck,
-    claim_expired: (session, message) => {
-        // Server-initiated expiry notification. Emit as a typed
-        // event so consumers can react (re-claim with a fresh
-        // capability, or accept the drop). The claim is already
-        // inactive server-side by the time this arrives.
-        const p = (message.payload ?? {});
-        if (typeof p.claimId === 'string') {
-            recordClaim('expired', p);
-            session.emit('claim_expired', { claimId: p.claimId });
-        }
-    },
-    claim_rejected: (session, message) => {
-        // The server denied a claim because the target is already held by
-        // another participant. The payload is forwarded as-is for the claim
-        // stream consumer to interpret (peerId, target, and so on).
-        recordClaim('rejected', (message.payload ?? {}));
-        session.emit('claim_rejected', message.payload ?? {});
-    },
-    claim_acquired: (session, message) => {
-        // Opt-in fair queue: the target was free, so the lease is ours
-        // immediately (no waiting). Payload carries { claimId, target }.
-        recordClaim('acquired', (message.payload ?? {}));
-        session.emit('claim_acquired', message.payload ?? {});
-    },
-    claim_queue: (session, message) => {
-        // Per-entity wait-queue snapshot for reactive `queue(id)`. Not a
-        // single claim's state change, so it isn't logged — the per-claim
-        // `queued`/`granted` events already tell that story.
-        session.emit('claim_queue', message.payload ?? {});
-    },
-    claim_queued: (session, message) => {
-        // Opt-in fair queue: our claim is waiting in line. Payload
-        // carries { claimId, target, position }.
-        recordClaim('queued', (message.payload ?? {}));
-        session.emit('claim_queued', message.payload ?? {});
-    },
-    claim_granted: (session, message) => {
-        // Our queued claim reached the head — the lease is now ours.
-        recordClaim('granted', (message.payload ?? {}));
-        session.emit('claim_granted', message.payload ?? {});
-    },
-    claim_lost: (session, message) => {
-        // A held/granted claim was taken from us (TTL lapse, revoke).
-        recordClaim('lost', (message.payload ?? {}));
-        session.emit('claim_lost', message.payload ?? {});
-    },
-    claim_heartbeat_ack: (session, message) => {
-        // Reply to our `claim_heartbeat` — the claim stream correlates it back
-        // to the awaiting caller by claimId. Not logged per-frame: heartbeats
-        // are a cadence, and the interesting transitions (lost) surface through
-        // the caller's error path.
-        session.emit('claim_heartbeat_ack', message.payload ?? {});
-    },
-    delta: handleDeltaFrame,
-};
-/**
- * Routes one parsed inbound frame to its handler. Keepalive frames are
- * ignored, a missing `type` is treated as a bare delta, and any unknown
- * type falls through to the collaboration-event map, whose wire names use
- * underscores and whose event keys use colons.
- */
-export function dispatchWsFrame(session, message) {
-    if (message.type === 'pong' || message.type === 'ping') {
-        // Ignore keepalive messages
-        getContext().logger.debug('Received keepalive', { type: message.type });
-        return;
-    }
-    if (message.type === undefined) {
-        // A bare delta, validated downstream like every other delta.
-        if (message.actionType || message.modelName) {
-            session.handleDelta(message);
-        }
-        return;
-    }
-    // Look up own properties only, so a wire type like 'toString' can't match
-    // an inherited Object.prototype member; such types fall through to the
-    // unknown-type path.
-    const handler = Object.prototype.hasOwnProperty.call(wsFrameHandlers, message.type)
-        ? wsFrameHandlers[message.type]
-        : undefined;
-    if (handler) {
-        handler(session, message);
-        return;
-    }
-    // Collaboration events use underscore wire format (e.g., 'sheet_selection')
-    // Convert to colon format for the event map (e.g., 'sheet:selection')
-    const eventKey = message.type?.replace(/_/g, ':');
-    if (eventKey && session.collaborationEventTypes.has(eventKey)) {
-        session.emit(eventKey, message.payload);
-    }
-    else {
-        getContext().logger.debug('Received unknown message type', { message });
-    }
-}
+export { isRecord, readWsInboundFrame, wsFrameHandlers, dispatchWsFrame, } from '../transaction/transport/wsFrameHandlers.js';

package/dist/testing/fixtures/bootstrap.d.ts

@@ -5,7 +5,7 @@
  * known point. These helpers produce the same shapes, so tests can exercise
  * client sync logic without a live server.
  */
-import type { BootstrapType } from '../../types/index.js';
+import type { BootstrapType } from '../../transaction/types/index.js';
 export type BootstrapModelData = Record<string, Record<string, unknown>[]>;
 export interface BootstrapResponse {
     type: BootstrapType;

package/dist/testing/fixtures/deltas.d.ts

@@ -4,7 +4,7 @@
  * format the server sends: an insert, update, delete, archive, and so on.
  * These helpers let tests construct deltas without a live server.
  */
-import type { SyncActionType, SyncAction } from '../../types/index.js';
+import type { SyncActionType, SyncAction } from '../../stores/syncAction.js';
 /** Reset the delta counter (call in beforeEach for deterministic IDs) */
 export declare function resetDeltaCounter(): void;
 export interface CreateDeltaOptions {

package/dist/testing/fixtures/httpResponses.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Response bodies for a fake HTTP server, built in the shapes the real one
+ * answers with.
+ *
+ * A test that hand-rolls `{ data, stamp }` is asserting against a server it
+ * invented. That is how a client and its server drift apart while every test
+ * stays green: the fixture and the client agree, and neither has met the
+ * route. Each builder here is `satisfies`-pinned to the wire schema the server
+ * answers with and the client parses — so a change to the contract breaks these
+ * fixtures at compile time, and the tests that use them describe a server that
+ * exists.
+ *
+ * Only the fields a test actually varies are parameters; everything else is a
+ * plausible default, because a fixture that makes you fill in `object: 'model'`
+ * teaches nothing and gets copy-pasted wrong.
+ */
+import type { ModelReadResponse, ModelListResponse, ClaimAcquiredResponse, ClaimQueuedResponse, ClaimListResponse, ClaimHeartbeatReply } from '../../transaction/wire/index.js';
+import type { ModelClaim } from '../../transaction/coordination/index.js';
+/** `GET /v1/models/{model}/{id}`. Pass `data: null` for a miss. */
+export declare function modelReadResponse(args: {
+    model: string;
+    id: string;
+    data: unknown;
+    stamp?: number;
+    claims?: readonly ModelClaim[];
+}): ModelReadResponse;
+/** `GET /v1/models/{model}`. */
+export declare function modelListResponse(args: {
+    model: string;
+    data: readonly unknown[];
+    hasMore?: boolean;
+    nextCursor?: string | null;
+    stamp?: number;
+}): ModelListResponse;
+/** One claim in the shape the HTTP claim routes return it. */
+export declare function modelClaim(args: {
+    id: string;
+    model: string;
+    entityId: string;
+    actor?: string;
+    participantKind?: ModelClaim['participantKind'];
+    description?: string;
+    status?: 'active' | 'queued';
+    position?: number;
+    expiresAt?: number;
+    fenceToken?: number;
+    field?: string;
+}): ModelClaim;
+/** `POST /v1/models/{model}/{id}/claim` — 201, the lease is yours. */
+export declare function claimAcquiredResponse(claim: ModelClaim): ClaimAcquiredResponse;
+/** `POST /v1/models/{model}/{id}/claim` — 202, you are in the wait line. */
+export declare function claimQueuedResponse(args: {
+    claimId: string;
+    position: number;
+    heldBy?: string;
+    expiresAt?: number;
+}): ClaimQueuedResponse;
+/** `GET /v1/claims`. */
+export declare function claimListResponse(args?: {
+    claims?: readonly ModelClaim[];
+    queue?: readonly ModelClaim[];
+}): ClaimListResponse;
+/** `POST /v1/models/{model}/{id}/claim/heartbeat`. */
+export declare function claimHeartbeatReply(args: {
+    claimId: string;
+    status?: 'held' | 'queued';
+    expiresAt?: number;
+    queueDepth?: number;
+    position?: number;
+}): ClaimHeartbeatReply;

package/dist/testing/fixtures/httpResponses.js

@@ -0,0 +1,90 @@
+/**
+ * Response bodies for a fake HTTP server, built in the shapes the real one
+ * answers with.
+ *
+ * A test that hand-rolls `{ data, stamp }` is asserting against a server it
+ * invented. That is how a client and its server drift apart while every test
+ * stays green: the fixture and the client agree, and neither has met the
+ * route. Each builder here is `satisfies`-pinned to the wire schema the server
+ * answers with and the client parses — so a change to the contract breaks these
+ * fixtures at compile time, and the tests that use them describe a server that
+ * exists.
+ *
+ * Only the fields a test actually varies are parameters; everything else is a
+ * plausible default, because a fixture that makes you fill in `object: 'model'`
+ * teaches nothing and gets copy-pasted wrong.
+ */
+/** `GET /v1/models/{model}/{id}`. Pass `data: null` for a miss. */
+export function modelReadResponse(args) {
+    return {
+        object: 'model',
+        model: args.model,
+        id: args.id,
+        data: args.data,
+        stamp: args.stamp ?? 0,
+        claims: args.claims ?? [],
+    };
+}
+/** `GET /v1/models/{model}`. */
+export function modelListResponse(args) {
+    return {
+        object: 'list',
+        model: args.model,
+        data: [...args.data],
+        has_more: args.hasMore ?? false,
+        next_cursor: args.nextCursor ?? null,
+        stamp: args.stamp ?? 0,
+    };
+}
+/** One claim in the shape the HTTP claim routes return it. */
+export function modelClaim(args) {
+    return {
+        id: args.id,
+        actor: args.actor ?? 'user_fixture',
+        participantKind: args.participantKind ?? 'user',
+        description: args.description ?? 'editing',
+        ...(args.field !== undefined ? { field: args.field } : {}),
+        ...(args.status !== undefined ? { status: args.status } : {}),
+        ...(args.position !== undefined ? { position: args.position } : {}),
+        expiresAt: args.expiresAt ?? Date.now() + 60_000,
+        ...(args.fenceToken !== undefined ? { fenceToken: args.fenceToken } : {}),
+        target: { model: args.model, id: args.entityId },
+    };
+}
+/** `POST /v1/models/{model}/{id}/claim` — 201, the lease is yours. */
+export function claimAcquiredResponse(claim) {
+    return { id: claim.id, object: 'claim', claim };
+}
+/** `POST /v1/models/{model}/{id}/claim` — 202, you are in the wait line. */
+export function claimQueuedResponse(args) {
+    return {
+        status: 'queued',
+        claimId: args.claimId,
+        position: args.position,
+        ...(args.heldBy !== undefined ? { heldBy: args.heldBy } : {}),
+        ...(args.expiresAt !== undefined ? { expiresAt: args.expiresAt } : {}),
+    };
+}
+/** `GET /v1/claims`. */
+export function claimListResponse(args = {}) {
+    return {
+        object: 'list',
+        claims: args.claims ?? [],
+        queue: args.queue ?? [],
+    };
+}
+/** `POST /v1/models/{model}/{id}/claim/heartbeat`. */
+export function claimHeartbeatReply(args) {
+    const status = args.status ?? 'held';
+    return {
+        object: 'claim_heartbeat',
+        claimId: args.claimId,
+        status,
+        ...(status === 'held'
+            ? {
+                expiresAt: args.expiresAt ?? Date.now() + 60_000,
+                ...(args.queueDepth !== undefined ? { queueDepth: args.queueDepth } : {}),
+            }
+            : { position: args.position ?? 0 }),
+    };
+}

package/dist/testing/fixtures/models.js

@@ -7,7 +7,7 @@
  */
 import { Model } from '../../Model.js';
 import { ModelRegistry } from '../../ModelRegistry.js';
-import { PropertyType, LoadStrategy } from '../../types/index.js';
+import { PropertyType, LoadStrategy } from '../../transaction/types/index.js';
 // ─────────────────────────────────────────────
 // Test Model Classes
 // ─────────────────────────────────────────────

package/dist/testing/helpers/wait.js

@@ -2,7 +2,7 @@
  * Asynchronous helpers for tests whose assertions depend on timing — for
  * flushing pending work, polling for a condition, or waiting a fixed delay.
  */
-import { AbloConnectionError } from '../../errors.js';
+import { AbloConnectionError } from '../../transaction/errors.js';
 /**
  * Flushes all pending microtasks, such as resolved promises and
  * `queueMicrotask` callbacks. Useful for testing work the transaction queue

package/dist/testing/mocks/MockMutationExecutor.d.ts

@@ -6,7 +6,7 @@
  * so tests can drive the delta-confirmation flow that depends on those ids.
  */
 import type { MutationExecutor, MutationOperation, MutationOptions, CommitResult } from '../../interfaces/index.js';
-import type { StaleNotification } from '../../coordination/schema.js';
+import type { StaleNotification } from '../../transaction/coordination/schema.js';
 export interface CapturedMutation {
     method: string;
     modelName?: string;
@@ -24,7 +24,7 @@ export interface MockMutationExecutorOptions {
     shouldSucceed?: boolean;
     /** A delay applied before each call resolves, in milliseconds, to simulate a slow network. */
     latencyMs?: number;
-    /** Optional explicit receipt status. Omission preserves legacy confirmed semantics. */
+    /** The settlement status each commit reports. Defaults to `'confirmed'`. */
     status?: CommitResult['status'];
     /** Optional server-issued source/WAL correlation returned with queued receipts. */
     correlationId?: string;