@abloatai/humans 0.37.0

package/src/local/sync/schemaDrift.ts

@@ -0,0 +1,86 @@
+/**
+ * The semantic schema-drift classifier — the question that matters is not
+ * "did the schema change at all?" (one whole-schema hash answers that, and
+ * welds every client to every push) but "does THIS client use anything that
+ * changed?". This module compares only the models the client declares against
+ * the server's per-model surface (`GET /api/schema`), so:
+ *
+ *   - a purely additive server change (models this build never references) is
+ *     SILENCE — deployed clients don't care what they don't use;
+ *   - a model this build declares that the server doesn't have is named, with
+ *     the push as the fix;
+ *   - a shared model whose content differs is named, so "which field moved"
+ *     is one `ablo status` away instead of a hash-guessing game.
+ *
+ * Pure and transport-free; the BootstrapFetcher owns fetching the surface.
+ */
+
+/** One model as the server's schema read-back reports it. */
+export interface ServerSchemaModel {
+  readonly key: string;
+  /** Per-model content hash; absent on servers older than this check. */
+  readonly hash?: string;
+}
+
+export type SchemaDriftFinding =
+  /** Every model this client declares exists server-side with matching content
+   *  (the server may know more — that's an additive lead, not drift). */
+  | { readonly kind: 'aligned' }
+  /** Models this build declares that the server has no idea about — writes to
+   *  them will be declined until the schema is pushed. */
+  | { readonly kind: 'unpushed'; readonly models: readonly string[] }
+  /** Shared models whose content differs between this build and the server
+   *  (may also carry unpushed models found alongside). */
+  | {
+      readonly kind: 'changed';
+      readonly models: readonly string[];
+      readonly unpushed: readonly string[];
+    }
+  /** The server surface carries no per-model hashes (older server) — the
+   *  caller falls back to the whole-hash comparison. */
+  | { readonly kind: 'unknown' };
+
+export function classifySchemaDrift(
+  clientModels: Readonly<Record<string, string>>,
+  serverModels: readonly ServerSchemaModel[],
+): SchemaDriftFinding {
+  if (serverModels.length > 0 && serverModels.every((m) => !m.hash)) {
+    return { kind: 'unknown' };
+  }
+  const server = new Map(serverModels.map((m) => [m.key, m.hash]));
+  const unpushed: string[] = [];
+  const changed: string[] = [];
+  for (const [key, hash] of Object.entries(clientModels)) {
+    const serverHash = server.get(key);
+    if (serverHash === undefined) unpushed.push(key);
+    else if (serverHash !== hash) changed.push(key);
+  }
+  if (changed.length > 0) return { kind: 'changed', models: changed, unpushed };
+  if (unpushed.length > 0) return { kind: 'unpushed', models: unpushed };
+  return { kind: 'aligned' };
+}
+
+/**
+ * The warning for a real, named divergence. Calm and specific: which models,
+ * what that means for this client, and the one next step. Never speaks about
+ * hashes — the point of the semantic check is that nobody has to compare hex.
+ */
+export function describeSchemaDrift(
+  finding: Extract<SchemaDriftFinding, { kind: 'unpushed' | 'changed' }>,
+  serverLabel: string,
+): string {
+  if (finding.kind === 'unpushed') {
+    return (
+      `Ablo: This build declares models the server at ${serverLabel} doesn't have yet ` +
+      `(${finding.models.join(', ')}). Writes to them will be declined until the schema is ` +
+      `pushed — run \`ablo push\` (and \`ablo status\` to confirm it targets this server).`
+    );
+  }
+  const alsoUnpushed = finding.unpushed.length > 0 ? ` (${finding.unpushed.join(', ')} not pushed yet)` : '';
+  return (
+    `Ablo: These models differ between this build and the server at ${serverLabel}: ` +
+    `${finding.models.join(', ')}${alsoUnpushed}. Reads and writes touching what changed may be ` +
+    `declined — \`ablo status\` shows the deployed shape; pushing your schema or deploying a ` +
+    `current build aligns them.`
+  );
+}

package/src/local/sync/schemas.ts

@@ -0,0 +1,118 @@
+/**
+ * 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 type { RuntimeContext } from "../RuntimeContext.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();
+
+export type ValidatedServerDelta = z.infer<typeof ServerDeltaSchema>;
+
+// ─── 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): unknown[] => {
+    if (val === null) return [];
+    if (typeof val === 'string') {
+      try {
+        const parsed: unknown = 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();
+
+export type ValidatedBootstrapResponse = z.infer<typeof BootstrapResponseSchema>;
+
+// ─── 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: unknown,
+  runtime: RuntimeContext = globalRuntime,
+): ValidatedBootstrapResponse {
+  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/src/local/sync/socketEventWiring.ts

@@ -0,0 +1,196 @@
+import { AbloSessionError, isAccessCredentialExpiryCloseReason } from '@abloatai/transaction/errors';
+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 function wireSocketEvents<TCollaboration extends EventMap<TCollaboration>>(
+  deps: SocketEventHost<TCollaboration>,
+): void {
+
+    // 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: SyncDelta) => {
+      deps.processDeltaWithBatching(delta);
+    });
+
+    const onDeltaBatch = deps.syncWebSocket.subscribe('delta_batch', (deltas: SyncDelta[]) => {
+      // 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: BootstrapHint) => { 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: 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: Error): void => {
+      deps.onConnectionEvent?.('WS_SESSION_ERROR');
+      deps.handleTerminalSessionError(error);
+    };
+
+    const onSessionError = deps.syncWebSocket.subscribe('session_error', (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/src/local/sync/syncCursor.ts

@@ -0,0 +1,62 @@
+/**
+ * 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: number;
+  syncCursor: string | null;
+
+  constructor(lastSyncId: number) {
+    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: number): void {
+    if (syncId > this.lastSyncId) {
+      this.lastSyncId = syncId;
+    }
+  }
+
+  /**
+   * Sets the watermark outright, used when restoring persisted state.
+   */
+  setLastSyncId(syncId: number): void {
+    this.lastSyncId = syncId;
+  }
+
+  /**
+   * Sets the opaque server cursor used for incremental sync.
+   */
+  setSyncCursor(cursor: string | null): void {
+    this.syncCursor = cursor;
+  }
+
+  /**
+   * Returns the current opaque server cursor, or null if none is set.
+   */
+  getSyncCursor(): string | null {
+    return this.syncCursor;
+  }
+
+  /**
+   * Returns the highest delta id seen this session, for persistence on a clean
+   * shutdown.
+   */
+  getLastSyncId(): number {
+    return this.lastSyncId || 0;
+  }
+}

package/src/local/sync/syncPlan.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 function deriveSyncPlanFromSchema(schema: Schema): {
+  enrichmentPlan: EnrichmentPlanEntry[];
+  foreignKeyIndexes: ForeignKeyIndexSpec[];
+} {
+  const enrichmentPlan: EnrichmentPlanEntry[] = [];
+  const foreignKeyIndexes: ForeignKeyIndexSpec[] = [];
+
+  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/src/local/sync/terminalSessionLifecycle.ts

@@ -0,0 +1,66 @@
+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 class TerminalSessionLifecycle {
+  private inFlight: Promise<void> | null = null;
+
+  constructor(private readonly context: TerminalSessionLifecycleContext) {}
+
+  start(error: Error): void {
+    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(): Promise<void> | null {
+    return this.inFlight;
+  }
+
+  private async run(sessionError: Error): Promise<void> {
+    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/src/local/sync/wsFrameHandlers.ts

@@ -0,0 +1,20 @@
+/**
+ * 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/src/local/transactions/databaseCommitOutbox.ts

@@ -0,0 +1,33 @@
+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 class DatabaseCommitOutboxStore implements DurableWriteStore {
+  constructor(private readonly database: CommitOutboxDatabase) {}
+
+  async seal(
+    envelope: PendingWrite,
+    consumedRecordIds: readonly string[],
+  ): Promise<void> {
+    await this.database.sealTransactionRecord(envelope, consumedRecordIds);
+  }
+
+  list(): Promise<readonly unknown[]> {
+    return this.database.getPersistedTransactions();
+  }
+
+  remove(envelopeRecordId: string): Promise<void> {
+    return this.database.removeTransaction(envelopeRecordId);
+  }
+}