@abloatai/ablo 0.8.0 → 0.9.0

package/dist/mutators/UndoManager.js

@@ -18,6 +18,8 @@
  *     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';
 /**
  * A single undo stack for one surface. Access via `UndoManager.getScope(name)`.
  * Consumers call `record(entry)` after each mutator; `undo()` / `redo()` to
@@ -30,18 +32,105 @@ 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();
     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;
     }
-    /** 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.
+     * `useMutators` calls this so the snapshot → write → `record()` sequence is
+     * atomic relative to other invocations, undo, and redo.
+     */
+    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(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,27 +138,45 @@ 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);
+            await applyOps(tx, ops);
+            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);
+            await applyOps(tx, ops);
+            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() {

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[];

package/dist/mutators/undoApply.js

@@ -0,0 +1,143 @@
+/**
+ * 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.
+ */
+export const DEFAULT_UNDO_CONFLICT_POLICY = 'skip-stale';
+/** Structural equality for JSON-shaped values (scalars, arrays, plain objects). */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
+        return false;
+    }
+    const aArr = Array.isArray(a);
+    if (aArr !== Array.isArray(b))
+        return false;
+    if (aArr) {
+        const av = a;
+        const bv = b;
+        if (av.length !== bv.length)
+            return false;
+        for (let i = 0; i < av.length; i++) {
+            if (!deepEqual(av[i], bv[i]))
+                return false;
+        }
+        return true;
+    }
+    const ao = a;
+    const bo = b;
+    const ak = Object.keys(ao);
+    const bk = Object.keys(bo);
+    if (ak.length !== bk.length)
+        return false;
+    for (const k of ak) {
+        if (!Object.prototype.hasOwnProperty.call(bo, k))
+            return false;
+        if (!deepEqual(ao[k], bo[k]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Map `id → { field: establishedValue }` from the paired ops. Only update-family
+ * ops carry per-field values worth comparing.
+ */
+function buildEstablished(paired) {
+    const map = new Map();
+    for (const op of paired) {
+        if (op.kind === 'update') {
+            map.set(op.patch.id, op.patch);
+        }
+        else if (op.kind === 'updateMany') {
+            for (const p of op.patches)
+                map.set(p.id, p);
+        }
+    }
+    return map;
+}
+/** Read the live value of a field from the store's pool, or `undefined`. */
+function readCurrentField(store, id, field) {
+    const model = store.pool.get(id);
+    if (!model)
+        return undefined;
+    const json = model.toJSON?.();
+    return json ? json[field] : undefined;
+}
+/**
+ * Keep only the fields whose live value still equals what this op established
+ * (`established[field]`). Returns `null` if nothing survives (the whole op is a
+ * no-op — every field was superseded by a collaborator).
+ */
+function filterStalePatch(store, patch, established) {
+    const out = { id: patch.id };
+    let kept = 0;
+    for (const field of Object.keys(patch)) {
+        if (field === 'id')
+            continue;
+        if (established && field in established) {
+            // Apply only if the field still holds the value WE established — i.e. no
+            // collaborator overwrote it since. Otherwise skip (don't clobber them).
+            if (deepEqual(readCurrentField(store, patch.id, field), established[field])) {
+                out[field] = patch[field];
+                kept++;
+            }
+        }
+        else {
+            // No paired value to compare against. The recorder always pairs fields,
+            // so this is theoretical; apply to preserve undo functionality.
+            out[field] = patch[field];
+            kept++;
+        }
+    }
+    return kept > 0 ? out : null;
+}
+/**
+ * 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 function resolveOps(apply, paired, store, policy) {
+    if (policy === 'last-writer-wins')
+        return apply;
+    const established = buildEstablished(paired);
+    const out = [];
+    for (const op of apply) {
+        if (op.kind === 'update') {
+            const filtered = filterStalePatch(store, op.patch, established.get(op.patch.id));
+            if (filtered)
+                out.push({ kind: 'update', modelKey: op.modelKey, patch: filtered });
+        }
+        else if (op.kind === 'updateMany') {
+            const patches = op.patches
+                .map((p) => filterStalePatch(store, p, established.get(p.id)))
+                .filter((p) => p !== null);
+            if (patches.length > 0) {
+                out.push({ kind: 'updateMany', modelKey: op.modelKey, patches });
+            }
+        }
+        else {
+            // create / createMany / delete / deleteMany — structural, applied as-is.
+            out.push(op);
+        }
+    }
+    return out;
+}

package/dist/query/client.d.ts

@@ -3,7 +3,7 @@
  *
  * Thin wrapper over fetch() that:
  *   - POSTs a QueryBatch as JSON
- *   - Handles auth via `credentials: 'include'` (session cookie)
+ *   - Sends the bearer credential via withAuthHeaders (Authorization header)
  *   - Throws on non-2xx responses
  *   - Parses the response into a typed QueryBatchResult
  *
@@ -12,6 +12,7 @@
  * without duplicating the fetch boilerplate.
  */
 import type { QueryBatch, QueryBatchResult } from './types.js';
+import { type AuthTokenGetter } from '../auth/credentialSource.js';
 export interface PostQueryOptions {
     /**
      * Full base URL of the sync server including the `/api` prefix.
@@ -22,14 +23,14 @@ export interface PostQueryOptions {
     /** Timeout in ms for the fetch request. Default: 30000. */
     fetchTimeout?: number;
     /**
-     * Bearer credential — a restricted (`rk_`) API key — attached as
-     * `Authorization: Bearer <token>`. Required for Node consumers
-     * (agent-worker, server-side tests) that have no session cookie to
-     * ride. Browser consumers can omit this and fall back to
-     * `credentials: 'include'`. When both are present the server prefers
-     * the Bearer header (see `apiKeyProvider` in
-     * `apps/sync-server/src/auth`), so passing the token in browser code
-     * is harmless. (Field name predates the Biscuit→opaque-key migration.)
+     * Live bearer credential getter. Preferred over `capabilityToken` because it
+     * is read per request, so token refreshes propagate without reconstructing
+     * query helpers.
+     */
+    getAuthToken?: AuthTokenGetter;
+    /**
+     * Compatibility fallback for callers that have only a copied token string.
+     * New SDK internals should pass `getAuthToken`.
      */
     capabilityToken?: string;
 }

package/dist/query/client.js

@@ -3,7 +3,7 @@
  *
  * Thin wrapper over fetch() that:
  *   - POSTs a QueryBatch as JSON
- *   - Handles auth via `credentials: 'include'` (session cookie)
+ *   - Sends the bearer credential via withAuthHeaders (Authorization header)
  *   - Throws on non-2xx responses
  *   - Parses the response into a typed QueryBatchResult
  *
@@ -13,6 +13,7 @@
  */
 import { z } from 'zod';
 import { translateHttpError } from '../errors.js';
+import { withAuthHeaders } from '../auth/credentialSource.js';
 // ── Response validation ─────────────────────────────────────────────────
 //
 // Each result slot is an array of rows (or an object for bundled
@@ -49,14 +50,10 @@ export async function postQuery(options, batch) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
     try {
-        const headers = { 'Content-Type': 'application/json' };
-        if (options.capabilityToken) {
-            headers.Authorization = `Bearer ${options.capabilityToken}`;
-        }
+        const headers = withAuthHeaders(options.getAuthToken, { 'Content-Type': 'application/json' }, options.capabilityToken);
         const response = await fetch(url, {
             method: 'POST',
             headers,
-            credentials: 'include',
             body: JSON.stringify(batch),
             signal: controller.signal,
         });