@abloatai/ablo 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.9.1
+
+### Patch Changes
+
+- 90b656c: `drizzleDataSource` now takes `(db, schema)` and derives snake_case columns from your schema, so it composes with `ablo migrate` with no parallel Drizzle table. Update calls from `drizzleDataSource(db, tables)` → `drizzleDataSource(db, schema)`. Also adds the `snakeToCamel` export and provisions the adapter's `ablo_outbox` / `ablo_idempotency` tables via `ablo migrate`.
+
 ## 0.9.0
 
 A single options object for every model verb, and a disposable `claim` handle.

package/README.md

@@ -384,7 +384,7 @@ contract; there are no retry or timeout knobs to tune.
 
 ## Production Reference
 
-- [Identity & Sync Groups](./docs/identity.md) — bring your own auth; tell Ablo who's connecting and how org / team / user map to sync-group scope.
+- [Identity & Sync Groups](./docs/identity.md) — use your own authentication; tell Ablo who's connecting and how org / team / user map to sync-group scope.
 - [Schema Contract](./docs/schema-contract.md) — one schema becomes typed model clients, React reads, agent writes, Data Source shape, and schema push.
 - [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, claim coordination, and agent lifecycle.
 - [Integration Guide](./docs/integration-guide.md) — pick the backing mode and integrate React, Data Source, multiplayer, and agents.

package/dist/BaseSyncedStore.d.ts

@@ -22,6 +22,7 @@ import { Model } from './Model.js';
 import { ModelScope } from './ObjectPool.js';
 import type { Schema } from './schema/schema.js';
 import { type ReaderActions } from './mutators/readerActions.js';
+import type { LocalMutation } from './react/context.js';
 import type { AuthCredentialSource } from './auth/credentialSource.js';
 /** Constructor type for Model subclasses (accepts abstract classes) */
 export type ModelConstructor<T extends Model> = abstract new (...args: never[]) => T;
@@ -415,6 +416,15 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * lookup contract; resolves immediately if nothing is in flight.
      */
     waitForConfirmation(modelName: string, modelId: string): Promise<void>;
+    /**
+     * Observe the LOCAL mutation stream for undo recording (see
+     * {@link import('./react/context.js').LocalMutation}). Taps the
+     * TransactionQueue's `transaction:created` event — fired once per local
+     * create/update/delete/archive with `previousData` already captured.
+     * Remote/collaborator deltas apply via `applyDeltaBatchToPool` and never
+     * emit here, so undo is naturally local-only (you can't undo a teammate).
+     */
+    subscribeLocalMutations(handler: (mutation: LocalMutation) => void): () => void;
     /**
      * Execute a bootstrap function with timeout protection and automatic retry.
      * Prevents the common issue where bootstrap hangs on startup.

package/dist/BaseSyncedStore.js

@@ -412,6 +412,28 @@ export class BaseSyncedStore {
     waitForConfirmation(modelName, modelId) {
         return this.syncClient.waitForConfirmation(modelName, modelId);
     }
+    /**
+     * Observe the LOCAL mutation stream for undo recording (see
+     * {@link import('./react/context.js').LocalMutation}). Taps the
+     * TransactionQueue's `transaction:created` event — fired once per local
+     * create/update/delete/archive with `previousData` already captured.
+     * Remote/collaborator deltas apply via `applyDeltaBatchToPool` and never
+     * emit here, so undo is naturally local-only (you can't undo a teammate).
+     */
+    subscribeLocalMutations(handler) {
+        return this.syncClient.subscribe('transaction:created', (data) => {
+            const tx = data;
+            if (!tx || !tx.type || !tx.modelName || !tx.modelId)
+                return;
+            handler({
+                type: tx.type,
+                modelName: tx.modelName,
+                modelId: tx.modelId,
+                data: tx.data ?? null,
+                previousData: tx.previousData ?? null,
+            });
+        });
+    }
     // ── Bootstrap + Retry ────────────────────────────────────────────────────
     /**
      * Execute a bootstrap function with timeout protection and automatic retry.

package/dist/client/Ablo.d.ts

@@ -686,8 +686,8 @@ export type Ablo<S extends SchemaRecord> = {
      * live `ek_`/`rk_` the WebSocket and HTTP transports currently carry (kept
      * fresh by the `getToken` refresh loop), falling back to a configured API
      * key. Returns `null` when no credential is set yet. Use it to authenticate
-     * a side-band request to the same sync-server (e.g. the S3 presign endpoint)
-     * with the very token this client already holds — no extra mint round-trip.
+     * a side-band request to the same server with the very token this client
+     * already holds — no extra mint round-trip.
      */
     getAuthToken(): Promise<string | null>;
     /**

package/dist/client/ApiClient.d.ts

@@ -240,8 +240,8 @@ export interface AbloApi {
      * Resolve the active bearer credential this client authenticates with — the
      * same token its own requests carry in `Authorization`. Returns `null` when
      * no credential is configured. Async because the API key may be supplied as
-     * an async setter. Use it to authenticate side-band requests to the same
-     * sync-server (e.g. the S3 presign endpoint) without re-minting.
+     * an async setter. Use it to authenticate a side-band request to the same
+     * server with the credential this client already holds — no re-mint.
      */
     getAuthToken(): Promise<string | null>;
 }

package/dist/mutators/UndoManager.d.ts

@@ -34,6 +34,23 @@ export interface UndoScopeOptions {
      * {@link UndoConflictPolicy}.
      */
     conflictPolicy?: UndoConflictPolicy;
+    /**
+     * Which models this surface owns. The scope only records mutations whose
+     * resolved schema key passes this predicate, so a spreadsheet edit never
+     * lands on the deck editor's stack (the equivalent of Yjs scoping by
+     * shared-type set). Omit to track every model — fine for a single-surface
+     * app, wrong when two surfaces with independent Cmd+Z share one store.
+     */
+    tracksModel?: (schemaKey: string) => boolean;
+    /**
+     * Opt into recording undo entries by OBSERVING the local-mutation stream
+     * (the best-practice model: undo listens where all local writes converge —
+     * Yjs/Liveblocks). When false (default), the scope records nothing on its
+     * own and relies on legacy manual `record()` calls. Transitional: a scope
+     * must not mix the two, or shared writes double-count. Flip a surface to
+     * `true` only when its manual-record consumers are removed in the same step.
+     */
+    recordFromStream?: boolean;
 }
 /**
  * A single undo stack for one surface. Access via `UndoManager.getScope(name)`.
@@ -72,7 +89,52 @@ export declare class UndoScope<S extends Schema> {
      * Serializing the whole scope closes both holes with one mechanism.
      */
     private tail;
+    /** Predicate selecting which models this surface records (see options). */
+    private readonly tracksModel?;
+    /** registered-name / alias → schema key, built once from the schema. */
+    private readonly schemaKeyByAlias;
+    /** Unsubscribe from the local-mutation stream. */
+    private readonly unsubscribe;
+    /**
+     * True while `undo()`/`redo()` replays ops. Replays write through the same
+     * commit path, so they re-emit on the local-mutation stream; this flag tells
+     * our own listener to ignore them (no echo) — the engine equivalent of Yjs's
+     * `trackedOrigins` exclusion / Liveblocks pausing history during undo.
+     */
+    private replaying;
+    /** Ops collected during the current tick, flushed as ONE entry. */
+    private batch;
+    private flushScheduled;
+    /**
+     * Open grouping session (Liveblocks `history.pause()` / Yjs `stopCapturing`
+     * analogue). While set, stream ops accumulate here ACROSS ticks instead of
+     * flushing per-tick, so a multi-tick action (a drag, a whole streaming AI
+     * response) collapses into ONE Cmd+Z. `endGroup()` flushes it.
+     */
+    private group;
     constructor(schema: S, store: SyncStoreContract, organizationId: string, options?: UndoScopeOptions);
+    /**
+     * Open a grouping session: every stream-recorded op until {@link endGroup}
+     * collapses into a single undo entry. Mirrors Liveblocks `history.pause()` —
+     * call on gesture start (pointerdown) or AI-response start. Idempotent-ish:
+     * a second call closes the previous group first.
+     */
+    beginGroup(label?: string): void;
+    /** Close the grouping session and record the accumulated ops as one entry. */
+    endGroup(label?: string): void;
+    /** Resolve a stream mutation's registered name to its schema key, or null. */
+    private resolveSchemaKey;
+    /**
+     * Stream listener — the sole place entries are born. Skips replay echoes
+     * and out-of-scope models, derives the forward+inverse op from the
+     * mutation's `data`/`previousData`, and defers the stack push to a
+     * per-tick flush so a burst of writes (e.g. align 5 layers) becomes ONE
+     * undo step — riding the same tick boundary the TransactionQueue batches on.
+     */
+    private onLocalMutation;
+    private scheduleFlush;
+    /** Coalesce the tick's collected ops into one entry and record it. */
+    private flushBatch;
     /**
      * Run `work` after every previously-enqueued scope operation has settled,
      * in invocation order. The internal `tail` always resolves (failures are
@@ -82,20 +144,24 @@ export declare class UndoScope<S extends Schema> {
     private enqueue;
     /**
      * Run a recording mutator exclusively on the scope's serialization chain.
-     * `useMutators` calls this so the snapshot → write → `record()` sequence is
-     * atomic relative to other invocations, undo, and redo.
+     * Used by the legacy manual-record path (`useMutators` + `RecordingTransaction`)
+     * so the snapshot → write → `record()` sequence is atomic relative to undo/
+     * redo. The stream-recording path doesn't need this (it derives entries from
+     * already-committed mutations); kept until all surfaces migrate off manual.
      */
     runRecorded<T>(work: () => Promise<T>): Promise<T>;
     /**
-     * Internal: record a mutator's inverses. Clears the redo stack.
-     *
-     * Entries here are produced internally by `RecordingTransaction` (trusted),
-     * so the schema check is DEV-ONLY: it catches recorder bugs in dev/test
-     * (rejecting a malformed op at ingestion, with its path, instead of letting
-     * it crash later inside `applyOps`) without paying a Zod parse on every user
-     * action in production. The real validation boundary is `parseUndoEntry`,
-     * applied when entries are deserialized from persistence (untrusted input).
-     * Best practice: validate at trust boundaries, type-check internal calls.
+     * Record one entry onto the undo stack. Clears the redo stack. Fed by
+     * {@link flushBatch}/{@link endGroup} from the local-mutation stream, and
+     * still called directly by the legacy manual-record consumers
+     * (`useMutators`, the AI mutation pipeline) until they migrate. Entries are
+     * built internally (trusted), so the schema check is DEV-ONLY: it catches
+     * recorder bugs in dev/test (rejecting a malformed op at ingestion, with its
+     * path, instead of letting it crash later inside `applyOps`) without paying a
+     * Zod parse on every user action in production. The real validation boundary
+     * is `parseUndoEntry`, applied when entries are deserialized from persistence
+     * (untrusted input). Best practice: validate at trust boundaries, type-check
+     * internal calls.
      */
     record(entry: UndoEntry): void;
     /**
@@ -134,6 +200,12 @@ export declare class UndoScope<S extends Schema> {
         undo: number;
         redo: number;
     };
+    /**
+     * Detach from the local-mutation stream and drop listeners. Scopes are
+     * cached for the store's lifetime by `UndoManager`, so this is mainly for
+     * tests and explicit teardown.
+     */
+    dispose(): void;
 }
 /**
  * Central registry of named undo scopes. One per-app instance, created once

package/dist/mutators/UndoManager.js

@@ -20,6 +20,9 @@
 import { createTransaction } from './Transaction.js';
 import { parseUndoEntry } from './inverseOp.js';
 import { resolveOps, DEFAULT_UNDO_CONFLICT_POLICY, } from './undoApply.js';
+/** Normalize a registered model name to the queue's lowercased alias form
+ * (mirrors TransactionQueue's `normalizeModelKey`). */
+const normalizeModelAlias = (modelName) => modelName.replace('Model', '').toLowerCase();
 /**
  * A single undo stack for one surface. Access via `UndoManager.getScope(name)`.
  * Consumers call `record(entry)` after each mutator; `undo()` / `redo()` to
@@ -57,12 +60,148 @@ export class UndoScope {
      * Serializing the whole scope closes both holes with one mechanism.
      */
     tail = Promise.resolve();
+    /** Predicate selecting which models this surface records (see options). */
+    tracksModel;
+    /** registered-name / alias → schema key, built once from the schema. */
+    schemaKeyByAlias = new Map();
+    /** Unsubscribe from the local-mutation stream. */
+    unsubscribe;
+    /**
+     * True while `undo()`/`redo()` replays ops. Replays write through the same
+     * commit path, so they re-emit on the local-mutation stream; this flag tells
+     * our own listener to ignore them (no echo) — the engine equivalent of Yjs's
+     * `trackedOrigins` exclusion / Liveblocks pausing history during undo.
+     */
+    replaying = false;
+    /** Ops collected during the current tick, flushed as ONE entry. */
+    batch = [];
+    flushScheduled = false;
+    /**
+     * Open grouping session (Liveblocks `history.pause()` / Yjs `stopCapturing`
+     * analogue). While set, stream ops accumulate here ACROSS ticks instead of
+     * flushing per-tick, so a multi-tick action (a drag, a whole streaming AI
+     * response) collapses into ONE Cmd+Z. `endGroup()` flushes it.
+     */
+    group = null;
     constructor(schema, store, organizationId, options = {}) {
         this.schema = schema;
         this.store = store;
         this.organizationId = organizationId;
         this.maxHistory = options.maxHistory ?? 100;
         this.conflictPolicy = options.conflictPolicy ?? DEFAULT_UNDO_CONFLICT_POLICY;
+        this.tracksModel = options.tracksModel;
+        // Build the registered-name → schema-key alias map. The mutation stream
+        // reports `model.getModelName()` (e.g. `'SlideLayer'`), but inverse ops
+        // and the replay transaction are keyed by the SCHEMA key (e.g.
+        // `'slideLayers'`). Map every reasonable spelling to the schema key.
+        for (const schemaKey of Object.keys(this.schema.models)) {
+            const def = this.schema.models[schemaKey];
+            const typename = def?.typename ?? schemaKey;
+            for (const alias of [schemaKey, typename]) {
+                this.schemaKeyByAlias.set(alias, schemaKey);
+                this.schemaKeyByAlias.set(alias.toLowerCase(), schemaKey);
+                this.schemaKeyByAlias.set(normalizeModelAlias(alias), schemaKey);
+            }
+        }
+        // Subscribe to the local-mutation stream ONLY when this scope opts into
+        // stream recording. Transitional flag: surfaces still on the legacy
+        // manual-record path (mutator `RecordingTransaction`, AI pipeline
+        // sessions) keep `recordFromStream: false` so writes aren't double-counted.
+        // Once every surface is migrated, stream recording becomes the only path
+        // and the flag is removed. Optional on the contract so minimal test
+        // doubles can omit it (undo then records nothing).
+        this.unsubscribe =
+            options.recordFromStream && this.store.subscribeLocalMutations
+                ? this.store.subscribeLocalMutations((m) => this.onLocalMutation(m))
+                : () => { };
+    }
+    /**
+     * Open a grouping session: every stream-recorded op until {@link endGroup}
+     * collapses into a single undo entry. Mirrors Liveblocks `history.pause()` —
+     * call on gesture start (pointerdown) or AI-response start. Idempotent-ish:
+     * a second call closes the previous group first.
+     */
+    beginGroup(label) {
+        if (this.group)
+            this.endGroup();
+        this.group = { label, ops: [] };
+    }
+    /** Close the grouping session and record the accumulated ops as one entry. */
+    endGroup(label) {
+        const g = this.group;
+        if (!g)
+            return;
+        this.group = null;
+        const forwards = g.ops.map((c) => c.forward);
+        const inverses = g.ops
+            .map((c) => c.inverse)
+            .filter((i) => i !== null)
+            .reverse();
+        if (forwards.length === 0 && inverses.length === 0)
+            return;
+        this.record({ label: label ?? g.label, inverses, forwards });
+    }
+    /** Resolve a stream mutation's registered name to its schema key, or null. */
+    resolveSchemaKey(modelName) {
+        return (this.schemaKeyByAlias.get(modelName) ??
+            this.schemaKeyByAlias.get(normalizeModelAlias(modelName)) ??
+            null);
+    }
+    /**
+     * Stream listener — the sole place entries are born. Skips replay echoes
+     * and out-of-scope models, derives the forward+inverse op from the
+     * mutation's `data`/`previousData`, and defers the stack push to a
+     * per-tick flush so a burst of writes (e.g. align 5 layers) becomes ONE
+     * undo step — riding the same tick boundary the TransactionQueue batches on.
+     */
+    onLocalMutation(m) {
+        if (this.replaying)
+            return;
+        const schemaKey = this.resolveSchemaKey(m.modelName);
+        if (!schemaKey)
+            return;
+        if (this.tracksModel && !this.tracksModel(schemaKey))
+            return;
+        const ops = buildUndoOps(m, schemaKey);
+        if (!ops)
+            return;
+        // Inside a grouping session, accumulate across ticks (flushed on
+        // endGroup); otherwise coalesce per-tick.
+        if (this.group) {
+            this.group.ops.push(ops);
+            return;
+        }
+        this.batch.push(ops);
+        this.scheduleFlush();
+    }
+    scheduleFlush() {
+        if (this.flushScheduled)
+            return;
+        this.flushScheduled = true;
+        const run = () => {
+            this.flushScheduled = false;
+            this.flushBatch();
+        };
+        if (typeof queueMicrotask === 'function')
+            queueMicrotask(run);
+        else
+            void Promise.resolve().then(run);
+    }
+    /** Coalesce the tick's collected ops into one entry and record it. */
+    flushBatch() {
+        if (this.batch.length === 0)
+            return;
+        const collected = this.batch;
+        this.batch = [];
+        const forwards = collected.map((c) => c.forward);
+        // Undo applies inverses in REVERSE order of how the forwards ran.
+        const inverses = collected
+            .map((c) => c.inverse)
+            .filter((i) => i !== null)
+            .reverse();
+        if (forwards.length === 0 && inverses.length === 0)
+            return;
+        this.record({ inverses, forwards });
     }
     /**
      * Run `work` after every previously-enqueued scope operation has settled,
@@ -77,22 +216,26 @@ export class UndoScope {
     }
     /**
      * Run a recording mutator exclusively on the scope's serialization chain.
-     * `useMutators` calls this so the snapshot → write → `record()` sequence is
-     * atomic relative to other invocations, undo, and redo.
+     * Used by the legacy manual-record path (`useMutators` + `RecordingTransaction`)
+     * so the snapshot → write → `record()` sequence is atomic relative to undo/
+     * redo. The stream-recording path doesn't need this (it derives entries from
+     * already-committed mutations); kept until all surfaces migrate off manual.
      */
     runRecorded(work) {
         return this.enqueue(work);
     }
     /**
-     * Internal: record a mutator's inverses. Clears the redo stack.
-     *
-     * Entries here are produced internally by `RecordingTransaction` (trusted),
-     * so the schema check is DEV-ONLY: it catches recorder bugs in dev/test
-     * (rejecting a malformed op at ingestion, with its path, instead of letting
-     * it crash later inside `applyOps`) without paying a Zod parse on every user
-     * action in production. The real validation boundary is `parseUndoEntry`,
-     * applied when entries are deserialized from persistence (untrusted input).
-     * Best practice: validate at trust boundaries, type-check internal calls.
+     * Record one entry onto the undo stack. Clears the redo stack. Fed by
+     * {@link flushBatch}/{@link endGroup} from the local-mutation stream, and
+     * still called directly by the legacy manual-record consumers
+     * (`useMutators`, the AI mutation pipeline) until they migrate. Entries are
+     * built internally (trusted), so the schema check is DEV-ONLY: it catches
+     * recorder bugs in dev/test (rejecting a malformed op at ingestion, with its
+     * path, instead of letting it crash later inside `applyOps`) without paying a
+     * Zod parse on every user action in production. The real validation boundary
+     * is `parseUndoEntry`, applied when entries are deserialized from persistence
+     * (untrusted input). Best practice: validate at trust boundaries, type-check
+     * internal calls.
      */
     record(entry) {
         if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
@@ -153,7 +296,15 @@ export class UndoScope {
                 return;
             const tx = createTransaction(this.schema, this.store, this.organizationId);
             const ops = resolveOps(entry.inverses, entry.forwards, this.store, this.conflictPolicy);
-            await applyOps(tx, ops);
+            // Suppress our own stream listener so replayed writes don't record as
+            // new undo entries. Cleared in `finally` even if a replay op throws.
+            this.replaying = true;
+            try {
+                await applyOps(tx, ops);
+            }
+            finally {
+                this.replaying = false;
+            }
             this.redoStack.push(entry);
             if (this.redoStack.length > this.maxHistory)
                 this.redoStack.shift();
@@ -172,7 +323,13 @@ export class UndoScope {
                 return;
             const tx = createTransaction(this.schema, this.store, this.organizationId);
             const ops = resolveOps(entry.forwards, entry.inverses, this.store, this.conflictPolicy);
-            await applyOps(tx, ops);
+            this.replaying = true;
+            try {
+                await applyOps(tx, ops);
+            }
+            finally {
+                this.replaying = false;
+            }
             this.undoStack.push(entry);
             if (this.undoStack.length > this.maxHistory)
                 this.undoStack.shift();
@@ -182,11 +339,70 @@ export class UndoScope {
     clear() {
         this.undoStack = [];
         this.redoStack = [];
+        this.batch = [];
     }
     /** Introspection — for debug panels / e2e tests. */
     size() {
         return { undo: this.undoStack.length, redo: this.redoStack.length };
     }
+    /**
+     * Detach from the local-mutation stream and drop listeners. Scopes are
+     * cached for the store's lifetime by `UndoManager`, so this is mainly for
+     * tests and explicit teardown.
+     */
+    dispose() {
+        this.unsubscribe();
+        this.recordListeners.clear();
+        this.batch = [];
+    }
+}
+/**
+ * Derive the forward + inverse op for a single local mutation. Returns null
+ * when the mutation can't be reversed (e.g. an update with no captured
+ * previous values), so the caller can drop it rather than push a half-entry.
+ */
+function buildUndoOps(m, modelKey) {
+    const id = m.modelId;
+    const stripId = (o) => {
+        const out = { ...(o ?? {}) };
+        delete out.id;
+        return out;
+    };
+    switch (m.type) {
+        case 'create':
+            return {
+                forward: { kind: 'create', modelKey, data: { ...stripId(m.data), id } },
+                inverse: { kind: 'delete', modelKey, id },
+            };
+        case 'update': {
+            const next = stripId(m.data);
+            const prev = stripId(m.previousData);
+            return {
+                forward: { kind: 'update', modelKey, patch: { id, ...next } },
+                // No previous values captured → not reversible; drop the inverse.
+                inverse: Object.keys(prev).length > 0
+                    ? { kind: 'update', modelKey, patch: { id, ...prev } }
+                    : null,
+            };
+        }
+        case 'delete':
+            return {
+                forward: { kind: 'delete', modelKey, id },
+                inverse: { kind: 'create', modelKey, data: { ...stripId(m.previousData), id } },
+            };
+        case 'archive':
+            return {
+                forward: { kind: 'update', modelKey, patch: { id, archivedAt: new Date() } },
+                inverse: { kind: 'update', modelKey, patch: { id, archivedAt: null } },
+            };
+        case 'unarchive':
+            return {
+                forward: { kind: 'update', modelKey, patch: { id, archivedAt: null } },
+                inverse: { kind: 'update', modelKey, patch: { id, archivedAt: new Date() } },
+            };
+        default:
+            return null;
+    }
 }
 // ── Manager ────────────────────────────────────────────────────────────────
 /**

package/dist/react/context.d.ts

@@ -5,11 +5,42 @@ import type { QueryView, QueryViewOptions } from '../core/QueryView.js';
 import type { ViewRegistry } from '../core/ViewRegistry.js';
 import type { Schema } from '../schema/schema.js';
 import type { SyncStatus } from '../BaseSyncedStore.js';
+/**
+ * A single LOCAL mutation as observed off the commit stream — the substrate
+ * the undo system records from. One is emitted per local create/update/
+ * delete/archive (remote/collaborator deltas never appear here: they apply
+ * through a separate pool path that doesn't queue mutations). `previousData`
+ * holds the pre-edit field values (captured from the model's
+ * `modifiedProperties` first-old-wins baseline), so an inverse op is fully
+ * derivable from the event alone — no separate snapshot pass.
+ *
+ * This mirrors how Yjs's `UndoManager` derives reverse-ops by observing the
+ * doc and Liveblocks' `room.history` records room ops: undo listens to the
+ * one place all local writes converge, rather than wrapping the write call.
+ */
+export interface LocalMutation {
+    type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
+    /** Registered model name (e.g. `'SlideLayer'`); resolved to a schema key by the recorder. */
+    modelName: string;
+    modelId: string;
+    /** New field values (create/update). */
+    data?: Record<string, unknown> | null;
+    /** Pre-edit field values (update → inverse patch; delete → full re-create row). */
+    previousData?: Record<string, unknown> | null;
+}
 /**
  * Minimal store interface that the SDK hooks need.
  * Consumers provide their concrete store (e.g., SyncedStore) that implements this.
  */
 export interface SyncStoreContract {
+    /**
+     * Subscribe to the LOCAL mutation stream (optimistic, pre-ack) for undo
+     * recording. Optional so minimal test doubles can omit it — when absent,
+     * undo scopes simply record nothing. The concrete store
+     * (`BaseSyncedStore`) wires this to the TransactionQueue's
+     * `transaction:created` event. Returns an unsubscribe function.
+     */
+    subscribeLocalMutations?(handler: (mutation: LocalMutation) => void): () => void;
     retrieve(modelClass: abstract new (...args: never[]) => Model, id: string): Model | undefined;
     queryByClass(modelClass: abstract new (...args: never[]) => Model, options?: {
         predicate?: (model: Model) => boolean;

package/dist/schema/ddl.d.ts

@@ -54,6 +54,14 @@ export interface MigrationPlan {
 /** Per-app schema name for an app (organization) id. */
 export declare function appSchemaName(organizationId: string): string;
 export declare function camelToSnake(identifier: string): string;
+/**
+ * Pure snake_case → camelCase — the inverse of {@link camelToSnake}, matching
+ * `postgres.toCamel` semantics. Read-side translation: a column read back from a
+ * BYO database (e.g. via `drizzleDataSource`) maps to the same JS field the SDK
+ * wrote, so `camelToSnake('operatorId') === 'operator_id'` and
+ * `snakeToCamel('operator_id') === 'operatorId'` round-trip.
+ */
+export declare function snakeToCamel(identifier: string): string;
 /** Quote an identifier (defense-in-depth; inputs are already slug/snake). */
 export declare function q(identifier: string): string;
 export declare function sqlType(fieldType: ModelJSON['fields'][string]['type']): string;

package/dist/schema/ddl.js

@@ -31,6 +31,16 @@ export function appSchemaName(organizationId) {
 export function camelToSnake(identifier) {
     return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
 }
+/**
+ * Pure snake_case → camelCase — the inverse of {@link camelToSnake}, matching
+ * `postgres.toCamel` semantics. Read-side translation: a column read back from a
+ * BYO database (e.g. via `drizzleDataSource`) maps to the same JS field the SDK
+ * wrote, so `camelToSnake('operatorId') === 'operator_id'` and
+ * `snakeToCamel('operator_id') === 'operatorId'` round-trip.
+ */
+export function snakeToCamel(identifier) {
+    return identifier.replace(/_+([a-z0-9])/g, (_, ch) => ch.toUpperCase());
+}
 /** Quote an identifier (defense-in-depth; inputs are already slug/snake). */
 export function q(identifier) {
     return `"${identifier.replace(/"/g, '""')}"`;

package/dist/schema/index.d.ts

@@ -32,7 +32,7 @@ export { mutable, readOnly, type SugarOptions } from './sugar.js';
 export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
 export { selectModels } from './select.js';
-export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';
+export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, type BackfillValue, type MigrationStep, type FieldChanges, type FieldColumnChange, type FieldTypeChange, type NullabilityChange, type EnumValuesChange, type IndexChange, type CastSafety, type FieldType, type RenameHints, type MigrationSignal, type MigrationClassification, type WarningCode, type BlockerCode, } from './diff.js';
 export { generateTypes } from './generate.js';
 export { query, defineQueries, type QueryDef, type QueryRecord, type Queries, type InferQueryInput, type InferQueryResult, } from './queries.js';

package/dist/schema/index.js

@@ -52,7 +52,7 @@ export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash,
 // Schema projection — derive an app's subset from one canonical schema.
 export { selectModels } from './select.js';
 // Schema → Postgres DDL (pure; shared by the hosted server and the CLI)
-export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, q, sqlType, } from './ddl.js';
+export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, } from './ddl.js';
 // Schema diff + migration planning (pure; SQL emission lowered by ddl.ts)
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, } from './diff.js';
 // Schema → TypeScript type emission (the `generate` half; pure)