@abloatai/ablo 0.8.0 → 0.9.0

package/dist/errors.js

@@ -18,8 +18,9 @@
  *
  * Both work on every subclass.
  */
-import { errorCodeSpec } from './errorCodes.js';
-export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode } from './errorCodes.js';
+import { z } from 'zod';
+import { errorCodeSpec, classifyRecovery } from './errorCodes.js';
+export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errorCodes.js';
 // ── AbloError hierarchy — the typed error surface ────────────────────
 /** Common shape for all errors thrown by this SDK. */
 export class AbloError extends Error {
@@ -238,15 +239,22 @@ export class SyncSessionError extends AbloAuthenticationError {
      * Check if an HTTP response status indicates a session error
      */
     static isSessionErrorResponse(status, body) {
-        // Prefer the structured error code: ONLY a genuine session / JWT EXPIRY
-        // should drive sign-out + re-auth. A non-expiry auth failure
-        // (api_key_required, jwt_issuer_untrusted, a 403 permission denial, …) must
-        // NOT — re-authenticating re-mints the same credential and loops, which is
-        // exactly the "flash then bounce to /signin" symptom. This mirrors the
-        // canonical wire mapping (401 → Authentication, 403 → Permission).
+        // "Should this response sign the user out?" — TRUE only for a genuine
+        // expiry of the LONG-LIVED login (`recovery: 'session_expiry'`). Decided
+        // via the closed recovery taxonomy rather than a hardcoded code list, so
+        // the access-vs-session split lives in one place (errorCodes.ts). This is
+        // behaviourally identical to the old `session_expired || jwt_expired` list.
+        //
+        // Deliberately NOT true for `access_credential_expiry` (`apikey_expired` —
+        // the Stripe-style ephemeral key): an expired `ek_`/`rk_` is re-mintable
+        // from the still-valid login and must NOT log the user out — the connection
+        // layer silently re-mints instead. Likewise NOT true for `auth_blocked` /
+        // `permission` failures (api_key_required, jwt_issuer_untrusted, 403s):
+        // re-auth re-mints the same rejected credential and loops ("flash then
+        // bounce to /signin").
         const code = extractWireCode(body);
         if (code) {
-            return code === 'session_expired' || code === 'jwt_expired';
+            return classifyRecovery(code) === 'session_expiry';
         }
         // No structured code (bare body, non-Ablo proxy response): a 401 is taken as
         // expiry — the historical default that drives re-auth — while a 403 is a
@@ -254,6 +262,50 @@ export class SyncSessionError extends AbloAuthenticationError {
         return status === 401;
     }
 }
+// ── HTTP → class mapping ──────────────────────────────────────────────
+const OptionalWireStringSchema = z.preprocess((value) => (typeof value === 'string' ? value : undefined), z.string().optional());
+const RequiredCapabilityWireSchema = z
+    .object({
+    scope: z.string(),
+    constraints: z
+        .record(z.string(), z.union([z.array(z.string()), z.string()]))
+        .optional(),
+    issuer: OptionalWireStringSchema,
+    ttlSeconds: z
+        .preprocess((value) => (typeof value === 'number' ? value : undefined), z.number().optional()),
+    nonce: OptionalWireStringSchema,
+})
+    .passthrough();
+const NestedErrorShapeSchema = z
+    .object({
+    code: OptionalWireStringSchema,
+    message: OptionalWireStringSchema,
+    field: OptionalWireStringSchema,
+    requiredCapability: RequiredCapabilityWireSchema.optional().catch(undefined),
+})
+    .passthrough();
+const ErrorFieldSchema = z
+    .preprocess((value) => typeof value === 'string' || (typeof value === 'object' && value !== null)
+    ? value
+    : undefined, z.union([z.string(), NestedErrorShapeSchema]).optional())
+    .catch(undefined);
+const ErrorBodyShapeSchema = z
+    .object({
+    /** Legacy: `error` was a flat code string on older endpoints. Newer
+     *  endpoints (CommitReceipt) carry `error` as a nested object. */
+    error: ErrorFieldSchema,
+    code: OptionalWireStringSchema,
+    reason: OptionalWireStringSchema,
+    message: OptionalWireStringSchema,
+    requiredCapability: RequiredCapabilityWireSchema.optional().catch(undefined),
+})
+    .passthrough();
+function parseErrorBodyShape(body) {
+    if (typeof body !== 'object' || body === null)
+        return {};
+    const parsed = ErrorBodyShapeSchema.safeParse(body);
+    return parsed.success ? parsed.data : {};
+}
 /**
  * Coerce ANY thrown value into an {@link AbloError} — the last-line guarantee
  * that an SDK consumer never catches an untagged error. An already-typed
@@ -340,7 +392,7 @@ export function errorFromWire(message, opts = {}) {
  * frame transports) after extracting code/message from the HTTP body.
  */
 export function translateHttpError(status, body, requestId) {
-    const parsed = typeof body === 'object' && body !== null ? body : {};
+    const parsed = parseErrorBodyShape(body);
     const nested = parsed.error != null && typeof parsed.error === 'object'
         ? parsed.error
         : undefined;
@@ -363,16 +415,14 @@ export function translateHttpError(status, body, requestId) {
  * of emitting a code-less error.
  */
 export function hasWireCode(body) {
-    if (typeof body !== 'object' || body === null)
-        return false;
-    const b = body;
-    if (typeof b.code === 'string')
+    const parsed = parseErrorBodyShape(body);
+    if (typeof parsed.code === 'string')
         return true;
-    if (typeof b.error === 'string')
+    if (typeof parsed.error === 'string')
         return true;
-    return (typeof b.error === 'object' &&
-        b.error !== null &&
-        typeof b.error.code === 'string');
+    return (typeof parsed.error === 'object' &&
+        parsed.error !== null &&
+        typeof parsed.error.code === 'string');
 }
 /**
  * Extract the canonical error `code` from a raw HTTP error body STRING — the
@@ -392,12 +442,12 @@ export function extractWireCode(body) {
     }
     if (typeof parsed !== 'object' || parsed === null)
         return undefined;
-    const b = parsed;
+    const b = parseErrorBodyShape(parsed);
     if (typeof b.code === 'string')
         return b.code;
-    if (typeof b.error === 'object' &&
-        b.error !== null &&
-        typeof b.error.code === 'string') {
+    if (typeof b.error === 'string')
+        return b.error;
+    if (typeof b.error === 'object' && b.error !== null && typeof b.error.code === 'string') {
         return b.error.code;
     }
     return undefined;

package/dist/index.d.ts

@@ -5,8 +5,11 @@
  * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- * const report = await ablo.weatherReports.retrieve('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,7 +26,7 @@
  *   @abloatai/ablo/react    — <AbloProvider>, useQuery, useMutate
  *   @abloatai/ablo/testing  — test harnesses + mocks
  *
- * Reads split by where the data comes from. `ablo.<model>.retrieve(id)` and
+ * 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.
@@ -33,7 +36,7 @@
  *
  * ── 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.
  *
@@ -46,16 +49,22 @@
  * If you don't recognize one, you don't need it — the default path covers you.
  */
 export { Ablo } from './client/Ablo.js';
-export type { AbloOptions, ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ClaimOptions, ClaimedRow, ModelOperations, } from './client/Ablo.js';
+export type { MutationExecutor } from './interfaces/index.js';
+export type { HttpClaimApi, InternalAbloOptions } from './client/Ablo.js';
+export { createAbloHttpClient, type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './client/httpClient.js';
+export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
+export type { AbloOptions, ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './client/Ablo.js';
 export type { AbloPersistence } from './client/persistence.js';
 export { session, agent } from './principal.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
-export { dataSource, abloSource, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
+export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
 export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.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, } 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 type { CommitReceipt, RequiredCapability } from './errors.js';
-export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec } from './errors.js';
+export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errors.js';
+export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
+export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
 export type { Register, DefaultSyncShape } from './types/global.js';
 export { defineMutators } from './mutators/defineMutators.js';
 export { createTransaction, type Transaction } from './mutators/Transaction.js';

package/dist/index.js

@@ -5,8 +5,11 @@
  * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- * const report = await ablo.weatherReports.retrieve('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,7 +26,7 @@
  *   @abloatai/ablo/react    — <AbloProvider>, useQuery, useMutate
  *   @abloatai/ablo/testing  — test harnesses + mocks
  *
- * Reads split by where the data comes from. `ablo.<model>.retrieve(id)` and
+ * 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.
@@ -33,7 +36,7 @@
  *
  * ── 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.
  *
@@ -53,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
@@ -70,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'`.
@@ -82,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, hasWireCode, errorFromWire, toAbloError, 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

@@ -16,7 +16,7 @@
  * still validate by hash — they parse here as `checksummed: false`.
  */
 import { z } from 'zod';
-export declare const API_KEY_KINDS: readonly ["secret", "restricted", "ephemeral"];
+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];
@@ -59,3 +59,18 @@ export declare function generateApiKey(env?: ApiKeyEnv, kind?: ApiKeyKind): {
  * 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

@@ -18,24 +18,29 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { z } from 'zod';
 // ── Vocabulary ──────────────────────────────────────────────────────────
-// The three-key Stripe model:
+// 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.
-// (There is no publishable `pk_` — the minted session token, not a project
-//  identifier, is what the browser holds; it already names the org.)
-export const API_KEY_KINDS = ['secret', 'restricted', 'ephemeral'];
+//   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. */
@@ -44,8 +49,8 @@ const KEY_BODY_LEN = 30;
 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>_<live|test>_<body>`; body charset covers base62 AND legacy base64url. */
-const KEY_RE = /^(sk|rk|ek)_(live|test)_([0-9A-Za-z\-_]+)$/;
+/** `<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 = (() => {
@@ -149,3 +154,18 @@ export function generateApiKey(env = 'live', kind = 'secret') {
 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;