@abloatai/humans 0.37.0

package/dist/local/sync/schemas.js

@@ -0,0 +1,94 @@
+/**
+ * Zod validation schemas for sync engine server responses.
+ *
+ * Validates data at the fetch boundary before it enters the sync engine.
+ * Unknown keys are kept, so a server that adds a field does not break a client
+ * that predates it.
+ */
+import { z } from 'zod';
+import { globalRuntime } from "../context.js";
+import { AbloValidationError } from "@abloatai/transaction/errors";
+import { syncDeltaWireCoreSchema } from '@abloatai/transaction/wire/delta';
+// ─── Server Delta Schema ─────────────────────────────────────────────────────
+/**
+ * A delta as it arrives in a bootstrap payload.
+ *
+ * The bootstrap routes return the same rows the broadcast path does, so the
+ * fields are taken from {@link syncDeltaWireCoreSchema} rather than restated
+ * here — a delta is one shape, and this is the reader for it, not a second
+ * definition of it. Unknown keys are kept, because the server sends its own
+ * wider projection (attribution, `projectId`) that later stages may read.
+ */
+export const ServerDeltaSchema = syncDeltaWireCoreSchema
+    .pick({
+    id: true,
+    actionType: true,
+    modelName: true,
+    modelId: true,
+    data: true,
+})
+    .loose();
+// ─── Model Value Schema ─────────────────────────────────────────────────────
+// A model's values can arrive in more than one shape depending on how the
+// server serialized them:
+//   - Array: an already-parsed JSON array (the common case)
+//   - String: a JSON array still encoded as a string, which must be parsed
+//   - null: no matching rows
+// This schema normalizes every variant into an array before downstream use.
+const ModelValueSchema = z
+    .union([z.array(z.unknown()), z.string(), z.null()])
+    .transform((val) => {
+    if (val === null)
+        return [];
+    if (typeof val === 'string') {
+        try {
+            const parsed = JSON.parse(val);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    return val;
+});
+// ─── Bootstrap Response Schema ───────────────────────────────────────────────
+export const BootstrapResponseSchema = z
+    .object({
+    type: z.enum(['full', 'partial']),
+    lastSyncId: z.number(),
+    models: z.record(z.string(), ModelValueSchema).optional(),
+    deltas: z.array(ServerDeltaSchema).optional(),
+    deltaCount: z.number().optional(),
+    failedModels: z.array(z.string()).optional(),
+    timestamp: z.number().default(() => Date.now()),
+    // The server's active schema hash, used to detect schema drift. Optional:
+    // absent when the server predates this field or the tenant has never
+    // pushed a schema.
+    schemaHash: z.string().optional(),
+    // Present when a paged single-model request stopped at its row limit
+    // with rows remaining: pass it back as the next page's cursor. Absent
+    // on the final page, on unpaged responses, and from older servers.
+    nextCursor: z.string().optional(),
+})
+    .loose();
+// ─── Parse Helpers ───────────────────────────────────────────────────────────
+/**
+ * Validates a raw bootstrap response from the server and returns the typed
+ * result. On failure it records a diagnostic breadcrumb and throws an
+ * {@link AbloValidationError} describing which fields were invalid.
+ */
+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('; ');
+        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',
+        });
+        throw new AbloValidationError(`Invalid bootstrap response: ${issues}`, {
+            code: 'bootstrap_response_schema_invalid',
+        });
+    }
+    return result.data;
+}

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

@@ -0,0 +1,31 @@
+import type { RuntimeContext } from '../RuntimeContext.js';
+import type { SyncClient } from '../SyncClient.js';
+import type { Database } from '../Database.js';
+import type { InstanceCache } from '../InstanceCache.js';
+import type { ConnectionManager } from './ConnectionManager.js';
+import type { SubscriptionManager } from './SubscriptionManager.js';
+import type { SyncStatus } from '../storeContract.js';
+import type { BootstrapHint, BootstrapDataEvent, PresenceUpdate, SyncWebSocket, EventMap } from './SyncWebSocket.js';
+import type { SyncDelta } from './SyncWebSocket.js';
+export interface SocketEventHost<TCollaboration extends EventMap<TCollaboration>> {
+    syncWebSocket: SyncWebSocket<TCollaboration>;
+    syncClient: SyncClient;
+    database: Database;
+    objectPool: InstanceCache;
+    areaOfInterest: SubscriptionManager;
+    runtime: RuntimeContext;
+    dataReady: boolean;
+    connectionManager: ConnectionManager | null;
+    disposers: (() => void)[];
+    onConnectionEvent?: (event: string) => void;
+    updateSyncStatus(updates: Partial<SyncStatus>): void;
+    processDeltaWithBatching(delta: SyncDelta): void;
+    applyDeltaFrame(deltas: SyncDelta[]): void;
+    handleBootstrapRequired(hint: BootstrapHint): void;
+    handleBootstrapData(data: BootstrapDataEvent): void;
+    handlePresenceUpdate(data: PresenceUpdate): void;
+    performCredentialRefresh(): Promise<'refreshed' | 'session_error' | 'network_error'>;
+    handleTerminalSessionError(error: Error): void;
+    nudgeReconnect(): void;
+}
+export declare function wireSocketEvents<TCollaboration extends EventMap<TCollaboration>>(deps: SocketEventHost<TCollaboration>): void;

package/dist/local/sync/socketEventWiring.js

@@ -0,0 +1,130 @@
+import { AbloSessionError, isAccessCredentialExpiryCloseReason } from '@abloatai/transaction/errors';
+export function wireSocketEvents(deps) {
+    // Connection events → forward to connection lifecycle callback
+    const onConnected = deps.syncWebSocket.subscribe('connected', () => {
+        deps.syncClient.markConnected();
+        deps.onConnectionEvent?.('WS_CONNECTED');
+        if (deps.dataReady) {
+            deps.updateSyncStatus({ state: 'idle', offlineSince: undefined });
+        }
+        else {
+            deps.updateSyncStatus({ offlineSince: undefined });
+        }
+        // Re-assert read interest on every (re)connect. After a transient
+        // reconnect the socket re-sends its URL groups, but interest may have
+        // changed while offline; after a full reconnect the new socket's URL
+        // carries only base groups. `resync` re-pushes the current desired set
+        // so the server-side index matches what the user is actually viewing.
+        void deps.areaOfInterest.resync();
+    });
+    const onDisconnected = deps.syncWebSocket.subscribe('disconnected', () => {
+        deps.syncClient.disconnect();
+        deps.onConnectionEvent?.('WS_DISCONNECTED');
+        deps.updateSyncStatus({ state: 'offline', offlineSince: new Date() });
+    });
+    const onReconnecting = deps.syncWebSocket.subscribe('reconnecting', (...args) => {
+        const [{ attempt, delay }] = args;
+        deps.runtime.logger.info('[BaseSyncedStore] WebSocket reconnecting', { attempt, delay });
+        deps.updateSyncStatus({ state: 'reconnecting' });
+    });
+    // Delta events → feed into processing pipeline
+    const onDelta = deps.syncWebSocket.subscribe('delta', (delta) => {
+        deps.processDeltaWithBatching(delta);
+    });
+    const onDeltaBatch = deps.syncWebSocket.subscribe('delta_batch', (deltas) => {
+        // A catch-up/reconnect frame is already complete — apply it as ONE
+        // atomic flush so the gallery re-renders once, not once per 50-delta
+        // chunk. See `applyDeltaFrame`.
+        deps.applyDeltaFrame(deltas);
+    });
+    // Bootstrap events
+    const onBootstrapRequired = deps.syncWebSocket.subscribe('bootstrap_required', (hint) => { deps.handleBootstrapRequired(hint); });
+    const onBootstrapData = deps.syncWebSocket.subscribe('bootstrap_data', (...args) => {
+        const data = args[0];
+        deps.handleBootstrapData(data);
+    });
+    const onPresenceUpdate = deps.syncWebSocket.subscribe('presence_update', (...args) => {
+        const data = args[0];
+        deps.handlePresenceUpdate(data);
+    });
+    // Error events
+    const onError = deps.syncWebSocket.subscribe('error', (error) => {
+        if (error.message === 'Network is offline' || error.message === 'WebSocket connection failed') {
+            deps.updateSyncStatus({ state: 'offline', offlineSince: new Date() });
+        }
+        else {
+            deps.updateSyncStatus({ state: 'error', error });
+        }
+    });
+    // Terminal session loss (revocation / the login itself is gone): notify,
+    // route the FSM to its terminal state, and clear local data.
+    const handleTerminalSessionError = (error) => {
+        deps.onConnectionEvent?.('WS_SESSION_ERROR');
+        deps.handleTerminalSessionError(error);
+    };
+    const onSessionError = deps.syncWebSocket.subscribe('session_error', (error) => {
+        // WS analog of HTTP's `apikey_expired` (see AbloSessionError.
+        // isSessionErrorResponse): the hub's keepalive reaper closes sockets
+        // whose SHORT-LIVED access credential (`ek_`/`rk_`) passed its expiry
+        // with `4001 credential_expired`. That is re-mintable from the
+        // still-valid login — recover silently (un-latch, single-flight
+        // re-mint, reconnect) instead of signing out and clearing local data.
+        // Only a mint that answers `null` (the login itself is gone) falls
+        // through to the terminal path. Without this branch, every credential
+        // TTL elapse wedged the socket behind the write-once session latch.
+        if (AbloSessionError.isSessionError(error) && isAccessCredentialExpiryCloseReason(error.message)) {
+            deps.runtime.observability.breadcrumb('WebSocket closed for expired access credential — re-minting', 'sync.websocket', 'warning');
+            // Un-latch BEFORE the async mint so the FSM's own recovery
+            // (probe → refreshing_credential → reconnect) is never blocked on
+            // our .then() ordering.
+            deps.syncWebSocket.clearSessionError();
+            void deps.performCredentialRefresh().then((outcome) => {
+                if (outcome === 'refreshed') {
+                    if (deps.connectionManager) {
+                        // Kick a parked FSM; a concurrent probe joins the same
+                        // single-flight mint, so this never double-mints.
+                        deps.nudgeReconnect();
+                    }
+                    else {
+                        // Agent/system clients have no connection FSM
+                        // (createConnectionManager returns null for kind 'agent') —
+                        // reconnect the socket directly; connect() reads the
+                        // freshly-minted credential from the credential source.
+                        deps.syncWebSocket.resetReconnectAttempts();
+                        deps.syncWebSocket.connect();
+                    }
+                    return;
+                }
+                if (outcome === 'session_error') {
+                    // The mint endpoint rejected: the long-lived login is gone.
+                    // Re-latch so writes reject with the permanent session type
+                    // (see SyncWebSocket.notConnectedError) instead of parking.
+                    deps.syncWebSocket.setSessionErrorDetected();
+                    handleTerminalSessionError(error);
+                }
+                // 'network_error' → transient mint failure. The WS_DISCONNECTED
+                // that follows this event already put the FSM on its probe/backoff
+                // loop, which retries through the same single-flight refresh.
+            });
+            return;
+        }
+        handleTerminalSessionError(error);
+    });
+    // Handshake failed: WS close before open. The HTTP status is hidden
+    // behind close code 1006, so we can't tell whether the server rejected
+    // auth (401/403) or the connection never reached the server (DNS/TLS/LB).
+    // Forward a dedicated event so the connection-lifecycle owner can run
+    // an authenticated HTTP probe to disambiguate.
+    const onHandshakeFailed = deps.syncWebSocket.subscribe('handshake_failed', () => {
+        deps.onConnectionEvent?.('WS_HANDSHAKE_FAILED');
+        deps.updateSyncStatus({ state: 'offline', offlineSince: new Date() });
+    });
+    const onReconnectFailed = deps.syncWebSocket.subscribe('reconnect_failed', (...args) => {
+        const [{ attempts }] = args;
+        // consumer register: reconnection exhausted — the app is now offline
+        deps.runtime.logger.warn('Lost connection to the sync service and could not reconnect. Your app is now offline; changes will sync once the connection is restored.');
+        deps.runtime.logger.debug('[BaseSyncedStore] WebSocket reconnection gave up', { attempts });
+        deps.updateSyncStatus({ state: 'reconnecting' });
+    });
+    deps.disposers.push(onConnected, onDisconnected, onReconnecting, onDelta, onDeltaBatch, onBootstrapRequired, onBootstrapData, onPresenceUpdate, onError, onSessionError, onHandshakeFailed, onReconnectFailed, () => { deps.areaOfInterest.dispose(); });
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Holds the resume state of one WebSocket sync session: the `lastSyncId`
+ * watermark, which marks the highest delta the client has seen, and an opaque
+ * server cursor used for incremental sync. The transport carries both across
+ * reconnects so the session can resume where it left off.
+ *
+ * The watermark advances under a strict rule — it moves forward only on an
+ * acknowledgement that is gated on durable persistence — which the transport
+ * enforces at its acknowledgement and delta-handling call sites.
+ */
+export declare class SyncCursor {
+    lastSyncId: number;
+    syncCursor: string | null;
+    constructor(lastSyncId: number);
+    /**
+     * Advances the watermark in response to an acknowledgement. This becomes the
+     * value the next incremental-sync request and the connect handshake send, and
+     * the value {@link SyncCursor.getLastSyncId} reports when persisting on a
+     * clean shutdown. The move is monotonic: a stale, lower acknowledgement never
+     * pulls the watermark backward.
+     */
+    ackAdvance(syncId: number): void;
+    /**
+     * Sets the watermark outright, used when restoring persisted state.
+     */
+    setLastSyncId(syncId: number): void;
+    /**
+     * Sets the opaque server cursor used for incremental sync.
+     */
+    setSyncCursor(cursor: string | null): void;
+    /**
+     * Returns the current opaque server cursor, or null if none is set.
+     */
+    getSyncCursor(): string | null;
+    /**
+     * Returns the highest delta id seen this session, for persistence on a clean
+     * shutdown.
+     */
+    getLastSyncId(): number;
+}

package/dist/local/sync/syncCursor.js

@@ -0,0 +1,55 @@
+/**
+ * Holds the resume state of one WebSocket sync session: the `lastSyncId`
+ * watermark, which marks the highest delta the client has seen, and an opaque
+ * server cursor used for incremental sync. The transport carries both across
+ * reconnects so the session can resume where it left off.
+ *
+ * The watermark advances under a strict rule — it moves forward only on an
+ * acknowledgement that is gated on durable persistence — which the transport
+ * enforces at its acknowledgement and delta-handling call sites.
+ */
+export class SyncCursor {
+    lastSyncId;
+    syncCursor;
+    constructor(lastSyncId) {
+        this.lastSyncId = lastSyncId;
+        this.syncCursor = null;
+    }
+    /**
+     * Advances the watermark in response to an acknowledgement. This becomes the
+     * value the next incremental-sync request and the connect handshake send, and
+     * the value {@link SyncCursor.getLastSyncId} reports when persisting on a
+     * clean shutdown. The move is monotonic: a stale, lower acknowledgement never
+     * pulls the watermark backward.
+     */
+    ackAdvance(syncId) {
+        if (syncId > this.lastSyncId) {
+            this.lastSyncId = syncId;
+        }
+    }
+    /**
+     * Sets the watermark outright, used when restoring persisted state.
+     */
+    setLastSyncId(syncId) {
+        this.lastSyncId = syncId;
+    }
+    /**
+     * Sets the opaque server cursor used for incremental sync.
+     */
+    setSyncCursor(cursor) {
+        this.syncCursor = cursor;
+    }
+    /**
+     * Returns the current opaque server cursor, or null if none is set.
+     */
+    getSyncCursor() {
+        return this.syncCursor;
+    }
+    /**
+     * Returns the highest delta id seen this session, for persistence on a clean
+     * shutdown.
+     */
+    getLastSyncId() {
+        return this.lastSyncId || 0;
+    }
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Derives a client's sync plan from its {@link Schema}. Walking the schema's
+ * models and relations, it produces two declarative arrays consumed when the
+ * store is constructed: the foreign-key indexes to register on the in-memory
+ * object pool, and the enrichment rules that attach related parents to
+ * incoming rows. See {@link deriveSyncPlanFromSchema}.
+ */
+import type { Schema } from '@abloatai/transaction/schema/schema';
+/** A foreign-key index to register on the in-memory object pool when the store is constructed. */
+export interface ForeignKeyIndexSpec {
+    /**
+     * The name of the child model, where the foreign-key field lives, and the
+     * name the object pool indexes by. Use the wire type-name casing (for
+     * example `'Block'`, not `'block'`), since that is the value
+     * stamped onto reconstructed models and the key the pool looks up.
+     */
+    readonly modelName: string;
+    /** The foreign-key field name on the child model, for example `'sectionId'`. */
+    readonly fieldName: string;
+}
+/**
+ * A declarative rule for enriching an incoming row with its related parent.
+ *
+ * When a delta for `modelName` arrives and its row has been constructed, the
+ * store reads the row's `foreignKey` value, looks up the matching parent in
+ * the object pool, and attaches it under `relationKey`. Enrichment is
+ * best-effort: if the parent is not in the pool yet — for example, it arrives
+ * later in the same bootstrap batch — the step is skipped without error.
+ */
+export interface EnrichmentPlanEntry {
+    /** The child model whose incoming deltas should be enriched. */
+    readonly modelName: string;
+    /** The foreign-key field on the child that points at the parent's id. */
+    readonly foreignKey: string;
+    /** The property name under which to attach the parent model. */
+    readonly relationKey: string;
+}
+/**
+ * Walks a schema and derives the two sync-plan arrays used when the store is
+ * constructed: the foreign-key indexes to register on the object pool and the
+ * enrichment plan. See {@link ForeignKeyIndexSpec} and
+ * {@link EnrichmentPlanEntry}.
+ *
+ * Both are drawn from each `belongsTo` relation that sets `options.index` or
+ * `options.enrich`; relations without those options are skipped. Enabling them
+ * is opt-in, so adding a `belongsTo` relation never silently changes how deltas
+ * apply or how lookups resolve. A `hasMany` or `hasOne` relation registers its
+ * index on the target model, since that is where the foreign key lives. The
+ * function has no side effects and is called once at construction.
+ */
+export declare function deriveSyncPlanFromSchema(schema: Schema): {
+    enrichmentPlan: EnrichmentPlanEntry[];
+    foreignKeyIndexes: ForeignKeyIndexSpec[];
+};

package/dist/local/sync/syncPlan.js

@@ -0,0 +1,50 @@
+/**
+ * Derives a client's sync plan from its {@link Schema}. Walking the schema's
+ * models and relations, it produces two declarative arrays consumed when the
+ * store is constructed: the foreign-key indexes to register on the in-memory
+ * object pool, and the enrichment rules that attach related parents to
+ * incoming rows. See {@link deriveSyncPlanFromSchema}.
+ */
+/**
+ * Walks a schema and derives the two sync-plan arrays used when the store is
+ * constructed: the foreign-key indexes to register on the object pool and the
+ * enrichment plan. See {@link ForeignKeyIndexSpec} and
+ * {@link EnrichmentPlanEntry}.
+ *
+ * Both are drawn from each `belongsTo` relation that sets `options.index` or
+ * `options.enrich`; relations without those options are skipped. Enabling them
+ * is opt-in, so adding a `belongsTo` relation never silently changes how deltas
+ * apply or how lookups resolve. A `hasMany` or `hasOne` relation registers its
+ * index on the target model, since that is where the foreign key lives. The
+ * function has no side effects and is called once at construction.
+ */
+export function deriveSyncPlanFromSchema(schema) {
+    const enrichmentPlan = [];
+    const foreignKeyIndexes = [];
+    for (const [modelName, def] of Object.entries(schema.models)) {
+        const typename = def.typename ?? modelName;
+        for (const [relationKey, rel] of Object.entries(def.relations)) {
+            if (rel.type === 'belongsTo') {
+                if (rel.options?.index) {
+                    foreignKeyIndexes.push({ modelName: typename, fieldName: rel.foreignKey });
+                }
+                if (rel.options?.enrich) {
+                    enrichmentPlan.push({
+                        modelName: typename,
+                        foreignKey: rel.foreignKey,
+                        relationKey,
+                    });
+                }
+            }
+            else if (rel.type === 'hasMany' || rel.type === 'hasOne') {
+                // For hasMany and hasOne, the foreign key lives on the target model,
+                // not the current one, so register the index on the target. Its wire
+                // type name is resolved from the schema here.
+                const targetDef = schema.models[rel.target];
+                const targetTypename = targetDef?.typename ?? rel.target;
+                foreignKeyIndexes.push({ modelName: targetTypename, fieldName: rel.foreignKey });
+            }
+        }
+    }
+    return { enrichmentPlan, foreignKeyIndexes };
+}

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

@@ -0,0 +1,20 @@
+import type { RuntimeContext } from '../RuntimeContext.js';
+import type { SyncStatus } from '../storeContract.js';
+export interface TerminalSessionLifecycleContext {
+    readonly runtime: RuntimeContext;
+    readonly listeners: Set<(error: Error) => void>;
+    purgeAuthenticatedState(): Promise<void>;
+    updateSyncStatus(updates: Partial<SyncStatus>): void;
+}
+/**
+ * Owns the one-way authenticated -> terminal transition. Cleanup is
+ * single-flight and listeners run only after the local boundary has settled.
+ */
+export declare class TerminalSessionLifecycle {
+    private readonly context;
+    private inFlight;
+    constructor(context: TerminalSessionLifecycleContext);
+    start(error: Error): void;
+    settled(): Promise<void> | null;
+    private run;
+}

package/dist/local/sync/terminalSessionLifecycle.js

@@ -0,0 +1,50 @@
+/**
+ * Owns the one-way authenticated -> terminal transition. Cleanup is
+ * single-flight and listeners run only after the local boundary has settled.
+ */
+export class TerminalSessionLifecycle {
+    context;
+    inFlight = null;
+    constructor(context) {
+        this.context = context;
+    }
+    start(error) {
+        if (this.inFlight)
+            return;
+        this.context.runtime.observability.captureWebSocketError({
+            context: 'session-error',
+            error: error.message,
+        });
+        this.context.updateSyncStatus({
+            state: 'error',
+            error,
+            isSessionError: true,
+        });
+        this.inFlight = this.run(error);
+    }
+    settled() {
+        return this.inFlight;
+    }
+    async run(sessionError) {
+        let reportedError = sessionError;
+        try {
+            await this.context.purgeAuthenticatedState();
+        }
+        catch (cleanupError) {
+            this.context.runtime.logger.error('Your session ended, but authenticated local data could not be completely removed.');
+            this.context.runtime.logger.debug('[TerminalSessionLifecycle] Local cleanup failed', cleanupError);
+            reportedError =
+                cleanupError instanceof Error
+                    ? cleanupError
+                    : new Error(String(cleanupError));
+        }
+        for (const listener of this.context.listeners) {
+            try {
+                listener(reportedError);
+            }
+            catch (listenerError) {
+                this.context.runtime.logger.debug('[TerminalSessionLifecycle] Session-error listener failed', listenerError);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export { isRecord, readWsInboundFrame, wsFrameHandlers, dispatchWsFrame, type PendingCommit, type PendingClaim, type PendingSubscription, type WsInboundFrame, type WsSession, type WsFrameHandler, } from '@abloatai/transaction/transport/wsFrameHandlers';

package/dist/local/sync/wsFrameHandlers.js

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export { isRecord, readWsInboundFrame, wsFrameHandlers, dispatchWsFrame, } from '@abloatai/transaction/transport/wsFrameHandlers';

package/dist/local/transactions/databaseCommitOutbox.d.ts

@@ -0,0 +1,15 @@
+import type { DurableWriteStore } from '@abloatai/transaction/durableWrites';
+import type { PendingWrite } from '@abloatai/transaction/transactions/settlement/pendingWrite';
+export interface CommitOutboxDatabase {
+    sealTransactionRecord(record: PendingWrite, consumedRecordIds: readonly string[]): Promise<unknown>;
+    getPersistedTransactions(): Promise<readonly unknown[]>;
+    removeTransaction(id: string): Promise<void>;
+}
+/** IndexedDB-backed durable commit adapter owned by the human materialiser. */
+export declare class DatabaseCommitOutboxStore implements DurableWriteStore {
+    private readonly database;
+    constructor(database: CommitOutboxDatabase);
+    seal(envelope: PendingWrite, consumedRecordIds: readonly string[]): Promise<void>;
+    list(): Promise<readonly unknown[]>;
+    remove(envelopeRecordId: string): Promise<void>;
+}

package/dist/local/transactions/databaseCommitOutbox.js

@@ -0,0 +1,16 @@
+/** IndexedDB-backed durable commit adapter owned by the human materialiser. */
+export class DatabaseCommitOutboxStore {
+    database;
+    constructor(database) {
+        this.database = database;
+    }
+    async seal(envelope, consumedRecordIds) {
+        await this.database.sealTransactionRecord(envelope, consumedRecordIds);
+    }
+    list() {
+        return this.database.getPersistedTransactions();
+    }
+    remove(envelopeRecordId) {
+        return this.database.removeTransaction(envelopeRecordId);
+    }
+}

package/dist/local/transactions/localMutation.d.ts

@@ -0,0 +1,10 @@
+import type { LocalMutationPort } from './mutations/localMutation.js';
+type EmitLocalMutation = (event: string, payload: unknown) => void;
+/**
+ * Human-side optimistic-write adapter.
+ *
+ * Settlement retains ordering and receipts; this adapter owns the local
+ * pre-image ledger and announces apply/rollback work to the materialiser.
+ */
+export declare function createLocalMutationPort(emit: EmitLocalMutation): LocalMutationPort;
+export {};

package/dist/local/transactions/localMutation.js

@@ -0,0 +1,37 @@
+/**
+ * Human-side optimistic-write adapter.
+ *
+ * Settlement retains ordering and receipts; this adapter owns the local
+ * pre-image ledger and announces apply/rollback work to the materialiser.
+ */
+export function createLocalMutationPort(emit) {
+    const updates = new Map();
+    const track = (event, model, transaction) => {
+        updates.set(transaction.id, {
+            model,
+            previousState: event === 'optimistic:create' ? null : transaction.previousData,
+            transaction,
+        });
+        emit(event, { model, transaction });
+    };
+    return {
+        updates,
+        applyCreate: (model, transaction) => track('optimistic:create', model, transaction),
+        applyUpdate: (model, transaction) => track('optimistic:update', model, transaction),
+        applyDelete: (model, transaction) => track('optimistic:delete', model, transaction),
+        rollback: (transaction, reason, error) => {
+            const optimistic = updates.get(transaction.id);
+            if (!optimistic)
+                return Promise.resolve();
+            emit('optimistic:rollback', {
+                model: optimistic.model,
+                previousState: optimistic.previousState,
+                transaction,
+                reason: reason ?? 'unknown',
+                error,
+            });
+            updates.delete(transaction.id);
+            return Promise.resolve();
+        },
+    };
+}