@abloatai/ablo 0.7.0 → 0.9.0

package/dist/index.js

@@ -5,8 +5,11 @@
  * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- * await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
- * await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
+ * const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
+ * await ablo.weatherReports.update({
+ *   id: 'report_stockholm',
+ *   data: { status: 'ready' },
+ * });
  *
  * type Entry = Ablo.Peer;
  * ```
@@ -23,13 +26,17 @@
  *   @abloatai/ablo/react    — <AbloProvider>, useQuery, useMutate
  *   @abloatai/ablo/testing  — test harnesses + mocks
  *
- * Consumer code should converge on `ablo.<model>.load(...)`, which routes
- * through the engine's `HydrationCoordinator` and dedupes single-flight
- * hydrations.
+ * Reads split by where the data comes from. `ablo.<model>.retrieve({ id })` and
+ * `.list({ where })` are the async **server** reads (pool → IDB → network via
+ * the `HydrationCoordinator`, single-flight deduped); they're the default and
+ * what hosted/stateless callers want, since their local graph starts empty.
+ * `ablo.<model>.get(id)` / `.getAll(...)` / `.getCount(...)` are synchronous
+ * **local-graph** snapshots with no network round-trip — for reactive React
+ * selectors (`useAblo((ablo) => ablo.<model>.get(id))`) once the graph is warm.
  *
  * ── What to import (read this first) ────────────────────────────────
  * Default path — this is all most apps and agents ever need:
- *   • `Ablo` (default export) + `AbloOptions` + the `Model*Options` bags
+ *   • `Ablo` (default export) + `AbloOptions` + the `Model*Params` bags
  *   • the `Ablo*Error` classes, to discriminate failures in catch blocks
  * That's it. If you're reaching past those, you're in advanced territory.
  *
@@ -49,6 +56,8 @@
 // `import Ablo from '@abloatai/ablo'` works; named export so
 // `import { Ablo }` also compiles.
 export { Ablo } from './client/Ablo.js';
+export { createAbloHttpClient, } from './client/httpClient.js';
+export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
 // Participant types live under `Ablo.Participant.*` —
 // `Ablo.Participant.Joined`, `Ablo.Participant.Manager`,
 // `Ablo.Participant.JoinOptions`, etc. Same dot-access shape as
@@ -66,7 +75,7 @@ export default Ablo;
 // storage — if you haven't deliberately chosen to keep your own DB
 // canonical, skip this entirely. Type counterparts live under
 // `Ablo.Source.*` (`Ablo.Source.Operation`, `Ablo.Source.Commit.Params`).
-export { dataSource, abloSource, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
+export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
 // Schema DSL is intentionally published from `@abloatai/ablo/schema`.
 // Keeping it out of the root import preserves one clean runtime surface:
 // `import Ablo from '@abloatai/ablo'`.
@@ -78,7 +87,11 @@ export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
 // Typed error hierarchy — Stripe-style. One import gets every class
 // consumers need to discriminate failures (`e instanceof AbloX` or
 // `e.type === 'AbloX'`) plus the HTTP-response translator.
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, } from './errors.js';
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
+export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
+// Storage-wedge detection — lets app shells render a recovery screen when the
+// IndexedDB backing store is stuck (see core/openIDBWithTimeout.ts).
+export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
 // Advanced — most apps never import this. Custom (Zero-style) mutators:
 // `ablo.<model>.create/update/delete` already covers normal writes. Reach
 // for `defineMutators` only when you need a named, multi-step mutation with

package/dist/keys/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Canonical Ablo API-key format — the single source of truth for how keys
+ * are minted, hashed, and validated. Both the sync-server (`apiKeyStore`)
+ * and the web control-plane (`generate-key.ts`) consume THIS module, so the
+ * format can no longer drift between the two mint sites (it used to live as
+ * a hand-copied twin kept in sync by a comment).
+ *
+ * Node-only — uses `node:crypto`. Exposed via the `@abloatai/ablo/keys`
+ * subpath and NEVER re-exported from the browser-facing `.` entry, so the
+ * client bundle never pulls in `node:crypto`.
+ *
+ * Format (GitHub-style): `<sk|rk|ek>_<live|test>_<30 base62 body><6-char
+ * base62 CRC32 checksum>`. The identifiable prefix + CRC32 checksum let
+ * secret scanners detect leaks and let us reject typo'd/forged keys OFFLINE
+ * (no DB round-trip). Legacy keys (a ~43-char base64url body, no checksum)
+ * still validate by hash — they parse here as `checksummed: false`.
+ */
+import { z } from 'zod';
+export declare const API_KEY_KINDS: readonly ["secret", "restricted", "ephemeral", "publishable"];
+export type ApiKeyKind = (typeof API_KEY_KINDS)[number];
+export declare const API_KEY_ENVS: readonly ["live", "test"];
+export type ApiKeyEnv = (typeof API_KEY_ENVS)[number];
+/** A structurally-valid Ablo API key, parsed into its parts. */
+export interface ParsedApiKey {
+    /** The original plaintext. */
+    raw: string;
+    kind: ApiKeyKind;
+    env: ApiKeyEnv;
+    /** The chars after `<prefix>_<env>_` (body + checksum for new keys). */
+    body: string;
+    /** True when this is the new checksummed format (36-char base62 body). */
+    checksummed: boolean;
+}
+/**
+ * Canonical schema for an Ablo API key. `parse`/`safeParse` returns a typed
+ * {@link ParsedApiKey}; a new checksummed-format key with a BAD checksum is
+ * rejected (the offline-reject), while a legacy key parses as
+ * `checksummed: false` and passes (the server still hash-validates it).
+ */
+export declare const apiKeySchema: z.ZodPipe<z.ZodString, z.ZodTransform<ParsedApiKey, string>>;
+/** Parse + fully validate (incl. checksum). Returns null when invalid. */
+export declare function parseApiKey(raw: string): ParsedApiKey | null;
+/** True when the key uses the new checksummed format (regardless of validity). */
+export declare function isChecksummedKey(raw: string): boolean;
+/** Verify the embedded checksum. Meaningful only for checksummed-format keys. */
+export declare function keyChecksumMatches(raw: string): boolean;
+/**
+ * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
+ * once), its SHA-256 hash (persisted), and the 12-char display prefix.
+ */
+export declare function generateApiKey(env?: ApiKeyEnv, kind?: ApiKeyKind): {
+    plaintext: string;
+    hash: string;
+    prefix: string;
+};
+/**
+ * Stable SHA-256 hex of a plaintext key. A fast hash is CORRECT here (not
+ * bcrypt) — API keys are high-entropy random, so there's no dictionary to
+ * defend against. Used at both write (mint) and lookup.
+ */
+export declare function hashApiKey(plaintext: string): string;
+/** `whsec_` label prefix per the Standard Webhooks spec (not part of the key material). */
+export declare const WEBHOOK_SECRET_PREFIX = "whsec_";
+/**
+ * Mint a webhook signing secret per the Standard Webhooks spec
+ * (https://www.standardwebhooks.com): a base64-encoded random key, 24–64 bytes,
+ * labelled with the `whsec_` prefix. We use 32 bytes (256 bits) — comfortably
+ * inside the range and matching Stripe/Svix. Unlike an API key this is NOT
+ * hashed at rest: signing (`signAbloSourceRequest`) needs the live key, so it is
+ * stored by reference via the secret store, returned to the customer once at
+ * creation, and never echoed again (Stripe's policy).
+ */
+export declare function generateWebhookSecret(): {
+    plaintext: string;
+    last4: string;
+};

package/dist/keys/index.js

@@ -0,0 +1,171 @@
+/**
+ * Canonical Ablo API-key format — the single source of truth for how keys
+ * are minted, hashed, and validated. Both the sync-server (`apiKeyStore`)
+ * and the web control-plane (`generate-key.ts`) consume THIS module, so the
+ * format can no longer drift between the two mint sites (it used to live as
+ * a hand-copied twin kept in sync by a comment).
+ *
+ * Node-only — uses `node:crypto`. Exposed via the `@abloatai/ablo/keys`
+ * subpath and NEVER re-exported from the browser-facing `.` entry, so the
+ * client bundle never pulls in `node:crypto`.
+ *
+ * Format (GitHub-style): `<sk|rk|ek>_<live|test>_<30 base62 body><6-char
+ * base62 CRC32 checksum>`. The identifiable prefix + CRC32 checksum let
+ * secret scanners detect leaks and let us reject typo'd/forged keys OFFLINE
+ * (no DB round-trip). Legacy keys (a ~43-char base64url body, no checksum)
+ * still validate by hash — they parse here as `checksummed: false`.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { z } from 'zod';
+// ── Vocabulary ──────────────────────────────────────────────────────────
+// The Stripe-style key model:
+//   secret (sk_)      — backend / server-to-server / agents. Full authority. Never in a browser.
+//   restricted (rk_)  — scoped SERVER key (agent session tokens / capabilities).
+//   ephemeral (ek_)   — short-lived, backend-minted, USER-scoped BROWSER session credential
+//                       (Stripe ephemeral keys). Carries participantKind:'user' + baked syncGroups.
+//   publishable (pk_) — long-lived, browser-safe, org-scoped, READ-ONLY project key
+//                       (Stripe `pk_` / Supabase anon key). Used DIRECTLY as the bearer
+//                       (never exchanged, never expires → nothing to refresh). The org owns
+//                       it; it grants read access to the org's data plane and cannot write
+//                       or reach any control-plane operation.
+export const API_KEY_KINDS = ['secret', 'restricted', 'ephemeral', 'publishable'];
+export const API_KEY_ENVS = ['live', 'test'];
+const PREFIX_BY_KIND = {
+    secret: 'sk',
+    restricted: 'rk',
+    ephemeral: 'ek',
+    publishable: 'pk',
+};
+const KIND_BY_PREFIX = {
+    sk: 'secret',
+    rk: 'restricted',
+    ek: 'ephemeral',
+    pk: 'publishable',
+};
+const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+/** Random base62 chars before the checksum. */
+const KEY_BODY_LEN = 30;
+/** base62(CRC32): 62^6 (~5.7e10) > 2^32, so a CRC32 always fits in 6 chars. */
+const CHECKSUM_LEN = 6;
+/** A new checksummed body is exactly this long and pure base62. */
+const CHECKSUMMED_BODY_LEN = KEY_BODY_LEN + CHECKSUM_LEN;
+/** `<sk|rk|ek|pk>_<live|test>_<body>`; body charset covers base62 AND legacy base64url. */
+const KEY_RE = /^(sk|rk|ek|pk)_(live|test)_([0-9A-Za-z\-_]+)$/;
+const BASE62_RE = /^[0-9A-Za-z]+$/;
+// ── Checksum (standard CRC-32, GitHub-compatible) ───────────────────────
+const CRC32_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(s) {
+    let c = 0xffffffff;
+    for (let i = 0; i < s.length; i++) {
+        c = (CRC32_TABLE[(c ^ s.charCodeAt(i)) & 0xff] ^ (c >>> 8)) >>> 0;
+    }
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** 6-char base62 encoding of the CRC32 of `payload`. */
+function checksum6(payload) {
+    let n = crc32(payload);
+    let out = '';
+    for (let i = 0; i < CHECKSUM_LEN; i++) {
+        out = BASE62[n % 62] + out;
+        n = Math.floor(n / 62);
+    }
+    return out;
+}
+/** `len` cryptographically-random base62 chars (rejection-sampled, no bias). */
+function randomBase62(len) {
+    let out = '';
+    while (out.length < len) {
+        for (const b of randomBytes(len * 2)) {
+            if (b < 248) {
+                out += BASE62[b % 62];
+                if (out.length === len)
+                    break;
+            }
+        }
+    }
+    return out;
+}
+function bodyIsChecksummed(body) {
+    return body.length === CHECKSUMMED_BODY_LEN && BASE62_RE.test(body);
+}
+/**
+ * Canonical schema for an Ablo API key. `parse`/`safeParse` returns a typed
+ * {@link ParsedApiKey}; a new checksummed-format key with a BAD checksum is
+ * rejected (the offline-reject), while a legacy key parses as
+ * `checksummed: false` and passes (the server still hash-validates it).
+ */
+export const apiKeySchema = z.string().transform((raw, ctx) => {
+    const m = KEY_RE.exec(raw);
+    if (!m) {
+        ctx.addIssue({ code: 'custom', message: 'not a valid Ablo API key format' });
+        return z.NEVER;
+    }
+    const [, prefix, env, body] = m;
+    const checksummed = bodyIsChecksummed(body);
+    if (checksummed && checksum6(raw.slice(0, -CHECKSUM_LEN)) !== body.slice(KEY_BODY_LEN)) {
+        ctx.addIssue({ code: 'custom', message: 'API key checksum mismatch' });
+        return z.NEVER;
+    }
+    return { raw, kind: KIND_BY_PREFIX[prefix], env: env, body, checksummed };
+});
+// ── Derived validators (thin wrappers over the same spec) ───────────────
+/** Parse + fully validate (incl. checksum). Returns null when invalid. */
+export function parseApiKey(raw) {
+    const r = apiKeySchema.safeParse(raw);
+    return r.success ? r.data : null;
+}
+/** True when the key uses the new checksummed format (regardless of validity). */
+export function isChecksummedKey(raw) {
+    const m = KEY_RE.exec(raw);
+    return m !== null && bodyIsChecksummed(m[3]);
+}
+/** Verify the embedded checksum. Meaningful only for checksummed-format keys. */
+export function keyChecksumMatches(raw) {
+    const m = KEY_RE.exec(raw);
+    if (!m || !bodyIsChecksummed(m[3]))
+        return false;
+    return checksum6(raw.slice(0, -CHECKSUM_LEN)) === m[3].slice(KEY_BODY_LEN);
+}
+// ── Mint + hash (node:crypto) ───────────────────────────────────────────
+/**
+ * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
+ * once), its SHA-256 hash (persisted), and the 12-char display prefix.
+ */
+export function generateApiKey(env = 'live', kind = 'secret') {
+    const body = randomBase62(KEY_BODY_LEN);
+    const payload = `${PREFIX_BY_KIND[kind]}_${env}_${body}`;
+    const plaintext = `${payload}${checksum6(payload)}`;
+    return { plaintext, hash: hashApiKey(plaintext), prefix: plaintext.slice(0, 12) };
+}
+/**
+ * Stable SHA-256 hex of a plaintext key. A fast hash is CORRECT here (not
+ * bcrypt) — API keys are high-entropy random, so there's no dictionary to
+ * defend against. Used at both write (mint) and lookup.
+ */
+export function hashApiKey(plaintext) {
+    return createHash('sha256').update(plaintext).digest('hex');
+}
+/** `whsec_` label prefix per the Standard Webhooks spec (not part of the key material). */
+export const WEBHOOK_SECRET_PREFIX = 'whsec_';
+/**
+ * Mint a webhook signing secret per the Standard Webhooks spec
+ * (https://www.standardwebhooks.com): a base64-encoded random key, 24–64 bytes,
+ * labelled with the `whsec_` prefix. We use 32 bytes (256 bits) — comfortably
+ * inside the range and matching Stripe/Svix. Unlike an API key this is NOT
+ * hashed at rest: signing (`signAbloSourceRequest`) needs the live key, so it is
+ * stored by reference via the secret store, returned to the customer once at
+ * creation, and never echoed again (Stripe's policy).
+ */
+export function generateWebhookSecret() {
+    const plaintext = `${WEBHOOK_SECRET_PREFIX}${randomBytes(32).toString('base64')}`;
+    return { plaintext, last4: plaintext.slice(-4) };
+}

package/dist/mutators/UndoManager.d.ts

@@ -19,56 +19,21 @@
  */
 import type { Schema } from '../schema/schema.js';
 import type { SyncStoreContract } from '../react/context.js';
-/**
- * A single reversible operation. The runtime captures these during a
- * recorded transaction and replays them (in reverse order) on undo.
- * Model keys and data shapes are stored as strings/records so the manager
- * is schema-agnostic — the transaction it replays through is schema-typed.
- */
-export type InverseOp = {
-    kind: 'create';
-    modelKey: string;
-    data: Record<string, unknown>;
-} | {
-    kind: 'update';
-    modelKey: string;
-    patch: {
-        id: string;
-    } & Record<string, unknown>;
-} | {
-    kind: 'delete';
-    modelKey: string;
-    id: string;
-} | {
-    kind: 'createMany';
-    modelKey: string;
-    data: Record<string, unknown>[];
-} | {
-    kind: 'updateMany';
-    modelKey: string;
-    patches: Array<{
-        id: string;
-    } & Record<string, unknown>>;
-} | {
-    kind: 'deleteMany';
-    modelKey: string;
-    ids: string[];
-};
-/** One undo entry = one mutator invocation's set of inverses, in reverse order. */
-export interface UndoEntry {
-    /** Optional label for diagnostics / UI ("Move layer", "Delete slide", etc). */
-    label?: string;
-    inverses: InverseOp[];
-    /**
-     * 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: InverseOp[];
-}
+import { type InverseOp, type UndoEntry } from './inverseOp.js';
+import { type UndoConflictPolicy } from './undoApply.js';
+export type { InverseOp, UndoEntry };
+export type { UndoConflictPolicy } from './undoApply.js';
 export interface UndoScopeOptions {
     /** Max number of undo entries. Older entries drop off the bottom. Default: 100. */
     maxHistory?: number;
+    /**
+     * How undo/redo treats a field a collaborator changed after your op.
+     * Default `skip-stale` — your undo reverts your change only where it still
+     * stands, never clobbering a concurrent collaborator edit (per-user undo).
+     * `last-writer-wins` restores the legacy clobbering behavior. See
+     * {@link UndoConflictPolicy}.
+     */
+    conflictPolicy?: UndoConflictPolicy;
 }
 /**
  * A single undo stack for one surface. Access via `UndoManager.getScope(name)`.
@@ -82,14 +47,85 @@ export declare class UndoScope<S extends Schema> {
     private undoStack;
     private redoStack;
     private readonly maxHistory;
+    private readonly 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.
+     */
+    private readonly recordListeners;
+    /**
+     * 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.
+     */
+    private tail;
     constructor(schema: S, store: SyncStoreContract, organizationId: string, options?: UndoScopeOptions);
-    /** 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.
+     */
+    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.
+     */
+    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(entry: UndoEntry): void;
+    /**
+     * 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: (entry: UndoEntry) => void): () => void;
+    private emitRecord;
     canUndo(): boolean;
     canRedo(): boolean;
-    /** Pop the last mutator and apply its inverses. Pushes to redo. */
+    /**
+     * 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(): Promise<void>;
-    /** Pop the last undone entry and re-apply the forward ops. Pushes to undo. */
+    /**
+     * 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(): Promise<void>;
     /** Drop all history. Use after bootstrap / sync group change / sync error. */
     clear(): void;

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() {