@abloatai/ablo 0.8.0 → 0.9.1

package/dist/mutators/UndoManager.js

@@ -18,6 +18,11 @@
  *     the scope on sync error if they want strict correctness.
  */
 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
@@ -30,18 +35,245 @@ export class UndoScope {
     undoStack = [];
     redoStack = [];
     maxHistory;
+    conflictPolicy;
+    /**
+     * Observers notified after each successful {@link record}. These see FORWARD
+     * user actions only — `undo()`/`redo()` replays move entries between stacks
+     * without calling `record()`, so a listener never observes a reversal. This
+     * is a deliberately domain-agnostic seam: analytics, gamification, and audit
+     * can tap the committed-mutation stream without the scope knowing about them.
+     * A throwing listener is isolated (see {@link emitRecord}) so a faulty
+     * observer can never wedge the editor's recording path.
+     */
+    recordListeners = new Set();
+    /**
+     * Serialization tail. Recording, undo, and redo all chain off this single
+     * promise so they run strictly in the order they were *invoked* — never
+     * interleaved. This is load-bearing for correctness, not just throughput:
+     *   - Ordering: callers fire writes un-awaited (`void mutations.x.update`).
+     *     Without serialization, an entry lands on the stack when its mutator
+     *     *resolves*, so a fast second write can record before a slow first one
+     *     → undo replays in the wrong order.
+     *   - Snapshot integrity: every recording reads/clears the shared models'
+     *     `modifiedProperties` (the undo "before" baseline). Two recordings
+     *     interleaving on the same model corrupt each other's inverse snapshot.
+     * 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 });
     }
-    /** Internal: record a mutator's inverses. Clears the redo stack. */
+    /**
+     * Run `work` after every previously-enqueued scope operation has settled,
+     * in invocation order. The internal `tail` always resolves (failures are
+     * swallowed *for the chain only*) so one rejected mutator can't wedge the
+     * queue; the original settlement is still surfaced to this call's caller.
+     */
+    enqueue(work) {
+        const result = this.tail.then(work, work);
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    /**
+     * Run a recording mutator exclusively on the scope's serialization chain.
+     * 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);
+    }
+    /**
+     * 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') {
+            parseUndoEntry(entry);
+        }
         this.undoStack.push(entry);
         if (this.undoStack.length > this.maxHistory)
             this.undoStack.shift();
         this.redoStack = [];
+        this.emitRecord(entry);
+    }
+    /**
+     * Subscribe to every recorded mutation. Fires synchronously at the tail of
+     * each {@link record} call, after the entry is on the undo stack. Returns an
+     * unsubscribe function — call it on teardown.
+     *
+     * Listeners receive the full {@link UndoEntry} (its `forwards` carry the
+     * `{ kind, modelKey, data }` ops), so a consumer can derive what changed
+     * (e.g. "a slideLayers row of type 'chart' was created") without re-querying.
+     */
+    onRecord(listener) {
+        this.recordListeners.add(listener);
+        return () => {
+            this.recordListeners.delete(listener);
+        };
+    }
+    emitRecord(entry) {
+        for (const listener of this.recordListeners) {
+            try {
+                listener(entry);
+            }
+            catch (err) {
+                // A faulty observer must never break the editor's recording path.
+                if (typeof console !== 'undefined') {
+                    console.error('[UndoScope] onRecord listener threw', err);
+                }
+            }
+        }
     }
     canUndo() {
         return this.undoStack.length > 0;
@@ -49,37 +281,128 @@ export class UndoScope {
     canRedo() {
         return this.redoStack.length > 0;
     }
-    /** Pop the last mutator and apply its inverses. Pushes to redo. */
-    async undo() {
-        const entry = this.undoStack.pop();
-        if (!entry)
-            return;
-        const tx = createTransaction(this.schema, this.store, this.organizationId);
-        await applyOps(tx, entry.inverses);
-        this.redoStack.push(entry);
-        if (this.redoStack.length > this.maxHistory)
-            this.redoStack.shift();
-    }
-    /** Pop the last undone entry and re-apply the forward ops. Pushes to undo. */
-    async redo() {
-        const entry = this.redoStack.pop();
-        if (!entry)
-            return;
-        const tx = createTransaction(this.schema, this.store, this.organizationId);
-        await applyOps(tx, entry.forwards);
-        this.undoStack.push(entry);
-        if (this.undoStack.length > this.maxHistory)
-            this.undoStack.shift();
+    /**
+     * Pop the last mutator and apply its inverses. Pushes to redo.
+     *
+     * Under the default `skip-stale` policy the inverses are filtered against
+     * live state first (paired with the entry's forwards = "what I set"), so a
+     * field a collaborator changed after my op is left untouched — undo reverts
+     * my change only where it still stands.
+     */
+    undo() {
+        return this.enqueue(async () => {
+            const entry = this.undoStack.pop();
+            if (!entry)
+                return;
+            const tx = createTransaction(this.schema, this.store, this.organizationId);
+            const ops = resolveOps(entry.inverses, entry.forwards, this.store, this.conflictPolicy);
+            // 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();
+        });
+    }
+    /**
+     * Pop the last undone entry and re-apply the forward ops. Pushes to undo.
+     * Symmetric to {@link undo}: forwards are filtered against live state
+     * (paired with the entry's inverses = "what undo restored"), so redo
+     * re-asserts my change only where the undone value still stands.
+     */
+    redo() {
+        return this.enqueue(async () => {
+            const entry = this.redoStack.pop();
+            if (!entry)
+                return;
+            const tx = createTransaction(this.schema, this.store, this.organizationId);
+            const ops = resolveOps(entry.forwards, entry.inverses, this.store, this.conflictPolicy);
+            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();
+        });
     }
     /** Drop all history. Use after bootstrap / sync group change / sync error. */
     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/mutators/inverseOp.d.ts

@@ -0,0 +1,129 @@
+/**
+ * inverseOp.ts — the reversible-operation model for the undo system,
+ * expressed as Zod schemas.
+ *
+ * Why schemas (not bare TS types):
+ *   - Single source of truth. The `InverseOp` / `UndoEntry` TypeScript types
+ *     are *derived* from these schemas (`z.infer`), so the wire shape and the
+ *     static type can't drift.
+ *   - A real validation boundary. Inverse ops are stored as plain JSON-shaped
+ *     records (model keys + row data) so the undo manager stays schema-agnostic
+ *     — it replays them through a strongly-typed transaction it doesn't own.
+ *     That JSON boundary is exactly where a runtime check belongs, and is the
+ *     seam a future cross-session persistence layer (IndexedDB-backed history)
+ *     would deserialize through. `parseUndoEntry` is that gate.
+ *
+ * The op kinds mirror the mutator surface 1:1 — single (`create`/`update`/
+ * `delete`) and batch (`createMany`/`updateMany`/`deleteMany`) — so a recorded
+ * entry is symmetric with what was originally invoked.
+ */
+import { z } from 'zod';
+/**
+ * A single reversible operation. Discriminated on `kind` so a malformed op
+ * fails fast with a precise path (e.g. `inverses[2].patch.id`) rather than a
+ * vague union mismatch. Model keys/data are strings/records — the manager is
+ * schema-agnostic; the transaction it replays through is schema-typed.
+ */
+export declare const inverseOpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"create">;
+    modelKey: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"update">;
+    modelKey: z.ZodString;
+    patch: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$catchall<z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"delete">;
+    modelKey: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"createMany">;
+    modelKey: z.ZodString;
+    data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"updateMany">;
+    modelKey: z.ZodString;
+    patches: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$catchall<z.ZodUnknown>>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"deleteMany">;
+    modelKey: z.ZodString;
+    ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>], "kind">;
+/** One undo entry = one mutator invocation's inverses + paired forwards. */
+export declare const undoEntrySchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    inverses: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"create">;
+        modelKey: z.ZodString;
+        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"update">;
+        modelKey: z.ZodString;
+        patch: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$catchall<z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"delete">;
+        modelKey: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"createMany">;
+        modelKey: z.ZodString;
+        data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"updateMany">;
+        modelKey: z.ZodString;
+        patches: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$catchall<z.ZodUnknown>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"deleteMany">;
+        modelKey: z.ZodString;
+        ids: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>], "kind">>;
+    forwards: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"create">;
+        modelKey: z.ZodString;
+        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"update">;
+        modelKey: z.ZodString;
+        patch: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$catchall<z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"delete">;
+        modelKey: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"createMany">;
+        modelKey: z.ZodString;
+        data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"updateMany">;
+        modelKey: z.ZodString;
+        patches: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$catchall<z.ZodUnknown>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"deleteMany">;
+        modelKey: z.ZodString;
+        ids: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;
+/** A single reversible operation (schema-derived). */
+export type InverseOp = z.infer<typeof inverseOpSchema>;
+/** One undo/redo stack entry (schema-derived). */
+export type UndoEntry = z.infer<typeof undoEntrySchema>;
+/**
+ * Validate an untrusted value as an `UndoEntry`. Use at any boundary where an
+ * entry crosses out of internal construction — deserialization from
+ * persistence, or a defensive check at the recording ingestion point. Throws
+ * `AbloValidationError` (code `undo_entry_invalid`) with the failing Zod path
+ * in `details` so the offending op is obvious.
+ */
+export declare function parseUndoEntry(value: unknown): UndoEntry;

package/dist/mutators/inverseOp.js

@@ -0,0 +1,74 @@
+/**
+ * inverseOp.ts — the reversible-operation model for the undo system,
+ * expressed as Zod schemas.
+ *
+ * Why schemas (not bare TS types):
+ *   - Single source of truth. The `InverseOp` / `UndoEntry` TypeScript types
+ *     are *derived* from these schemas (`z.infer`), so the wire shape and the
+ *     static type can't drift.
+ *   - A real validation boundary. Inverse ops are stored as plain JSON-shaped
+ *     records (model keys + row data) so the undo manager stays schema-agnostic
+ *     — it replays them through a strongly-typed transaction it doesn't own.
+ *     That JSON boundary is exactly where a runtime check belongs, and is the
+ *     seam a future cross-session persistence layer (IndexedDB-backed history)
+ *     would deserialize through. `parseUndoEntry` is that gate.
+ *
+ * The op kinds mirror the mutator surface 1:1 — single (`create`/`update`/
+ * `delete`) and batch (`createMany`/`updateMany`/`deleteMany`) — so a recorded
+ * entry is symmetric with what was originally invoked.
+ */
+import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
+/** A row payload — JSON-shaped record used by create/createMany inverses. */
+const rowDataSchema = z.record(z.string(), z.unknown());
+/**
+ * An update patch: an `id` plus the changed fields. Modeled as an object with
+ * a required `id` and an open `catchall`, so `z.infer` yields
+ * `{ id: string } & { [k: string]: unknown }` — the exact shape the recorder
+ * builds and the replayer consumes.
+ */
+const patchSchema = z.object({ id: z.string() }).catchall(z.unknown());
+/**
+ * A single reversible operation. Discriminated on `kind` so a malformed op
+ * fails fast with a precise path (e.g. `inverses[2].patch.id`) rather than a
+ * vague union mismatch. Model keys/data are strings/records — the manager is
+ * schema-agnostic; the transaction it replays through is schema-typed.
+ */
+export const inverseOpSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('create'), modelKey: z.string(), data: rowDataSchema }),
+    z.object({ kind: z.literal('update'), modelKey: z.string(), patch: patchSchema }),
+    z.object({ kind: z.literal('delete'), modelKey: z.string(), id: z.string() }),
+    z.object({ kind: z.literal('createMany'), modelKey: z.string(), data: z.array(rowDataSchema) }),
+    z.object({ kind: z.literal('updateMany'), modelKey: z.string(), patches: z.array(patchSchema) }),
+    z.object({ kind: z.literal('deleteMany'), modelKey: z.string(), ids: z.array(z.string()) }),
+]);
+/** One undo entry = one mutator invocation's inverses + paired forwards. */
+export const undoEntrySchema = z.object({
+    /** Optional label for diagnostics / UI ("Move layer", "Delete slide", etc). */
+    label: z.string().optional(),
+    /** Applied (in array order) to reverse the invocation. */
+    inverses: z.array(inverseOpSchema),
+    /**
+     * Paired forward ops, captured at record time so redo can replay them
+     * without re-running the user's mutator (which may have non-idempotent
+     * side effects like generating new IDs).
+     */
+    forwards: z.array(inverseOpSchema),
+});
+/**
+ * Validate an untrusted value as an `UndoEntry`. Use at any boundary where an
+ * entry crosses out of internal construction — deserialization from
+ * persistence, or a defensive check at the recording ingestion point. Throws
+ * `AbloValidationError` (code `undo_entry_invalid`) with the failing Zod path
+ * in `details` so the offending op is obvious.
+ */
+export function parseUndoEntry(value) {
+    const result = undoEntrySchema.safeParse(value);
+    if (!result.success) {
+        throw new AbloValidationError('Undo entry failed inverse-op schema validation.', {
+            code: 'undo_entry_invalid',
+            details: { issues: result.error.issues },
+        });
+    }
+    return result.data;
+}

package/dist/mutators/readerActions.d.ts

@@ -4,7 +4,7 @@ import type { SyncStoreContract } from '../react/context.js';
  * React-free imperative reads over a store: one-off `retrieve`/`list`/`count`
  * snapshots that do NOT subscribe to changes. Used by the transaction system
  * and `BaseSyncedStore`. For reactive reads in components use
- * `useAblo((ablo) => ablo.<model>.retrieve(id) / .list(opts))`.
+ * `useAblo((ablo) => ablo.<model>.retrieve({ id }) / .list(opts))`.
  */
 export interface ReaderFindOptions<T> {
     /** Equality filter — uses FK index when the field is registered. */

package/dist/mutators/undoApply.d.ts

@@ -0,0 +1,42 @@
+/**
+ * undoApply.ts — conflict-aware resolution of undo/redo ops (per-user undo).
+ *
+ * The undo stack is already per-client (only local mutator invocations call
+ * `UndoScope.record`; a collaborator's edits arrive as inbound sync deltas and
+ * never land here). What this module adds is the second half of "undo per
+ * user": when replaying a recorded op, only touch a field whose CURRENT value
+ * still equals what THIS op established — so undo reverts your own change only
+ * where it still stands, and never clobbers a field a collaborator changed
+ * after you (the Yjs/CRDT "selective undo" principle, adapted to our
+ * field-level last-writer-wins model).
+ *
+ * `resolveOps(apply, paired, store, policy)`:
+ *   - `apply`  — the ops we're about to replay (inverses on undo, forwards on redo).
+ *   - `paired` — their counterparts, carrying the value this op established
+ *     (forwards on undo = "what I set"; inverses on redo = "what undo restored").
+ *   - For `update`/`updateMany` ops it drops fields whose live value no longer
+ *     matches the established value. `create`/`delete` families are structural
+ *     and applied unconditionally (undoing your create removes the row you
+ *     added; undoing your delete restores it).
+ *
+ * With no collaborator, the live value always equals what you set, so nothing
+ * is dropped — single-user undo is byte-for-byte unchanged.
+ */
+import type { SyncStoreContract } from '../react/context.js';
+import type { InverseOp } from './inverseOp.js';
+/**
+ * How undo/redo handles a field a collaborator changed after your op:
+ *   - `skip-stale` (default): leave it — your change is already superseded, so
+ *     reverting it would clobber theirs. This is the per-user guarantee.
+ *   - `last-writer-wins`: apply the op verbatim (legacy behavior). Your undo
+ *     overwrites their change.
+ */
+export type UndoConflictPolicy = 'skip-stale' | 'last-writer-wins';
+export declare const DEFAULT_UNDO_CONFLICT_POLICY: UndoConflictPolicy;
+/** Structural equality for JSON-shaped values (scalars, arrays, plain objects). */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Filter the ops to apply so they don't clobber concurrent collaborator edits.
+ * See the module docblock. `last-writer-wins` returns the ops unchanged.
+ */
+export declare function resolveOps(apply: InverseOp[], paired: InverseOp[], store: SyncStoreContract, policy: UndoConflictPolicy): InverseOp[];