@abloatai/ablo 0.9.2 → 0.9.4

package/dist/core/index.d.ts

@@ -1,36 +1,28 @@
 /**
  * @abloatai/ablo/core — Framework extension
  *
- * Only imported by SyncedStore.ts and ApplicationStore.ts —
- * the 2-3 files that extend or orchestrate the sync engine.
- * Regular model files and components should NOT import from here.
+ * Only imported by the handful of files that extend or orchestrate the
+ * sync engine (the app-shell store/provider stack, sync adapters, demo
+ * harnesses). Regular model files and components should NOT import from
+ * here — the consumer surface is `Ablo({ schema })` on the root.
+ *
+ * TRIMMED to what framework-level consumers actually import (verified by
+ * a monorepo-wide import scan). Everything else the engine defines stays
+ * module-private: if a new framework concern genuinely needs another
+ * primitive, add the export deliberately — don't re-widen the barrel.
  */
-export { BaseSyncedStore, type SyncStatus, type UserContext, type SyncedStoreConfig, type QueryResult, type SmartSyncOptions, type ModelConstructor, type ConcreteModelConstructor, BOOTSTRAP_CONFIG, } from '../BaseSyncedStore.js';
-export { SyncClient, type RehydrationStats } from '../SyncClient.js';
-export { Database, type BootstrapResult, type BootstrapRequirements } from '../Database.js';
+export { BaseSyncedStore, type ModelConstructor, type ConcreteModelConstructor, } from '../BaseSyncedStore.js';
+export { SyncClient } from '../SyncClient.js';
+export { Database } from '../Database.js';
 export { ObjectPool, ModelScope } from '../ObjectPool.js';
 export { Model } from '../Model.js';
-export { LazyReferenceCollection, type LazyCollectionOptions } from '../LazyReferenceCollection.js';
+export { LazyReferenceCollection, type LazyCollectionOptions, } from '../LazyReferenceCollection.js';
+export { ModelRegistry, getActiveRegistry, } from '../ModelRegistry.js';
 export { postQuery, type PostQueryOptions } from '../query/client.js';
-export { probeNetwork, type ProbeResult } from '../sync/NetworkProbe.js';
-export { ConnectionManager, type ConnectionState, type ConnectionEvent, type ConnectionCallbacks, type ConnectionManagerOptions, } from '../sync/ConnectionManager.js';
-export { ModelRegistry, getActiveRegistry, type ExtendedReferenceMetadata, type BackReferenceMetadata } from '../ModelRegistry.js';
 export { computeFKDepthPriority, type InternalAbloOptions } from '../client/Ablo.js';
-export { TransactionQueue } from '../transactions/TransactionQueue.js';
-export { initSyncEngine, resetSyncEngine, isSyncEngineInitialized } from '../context.js';
-export { noopLogger, noopObservability, noopAnalytics, browserOnlineStatus, defaultSessionErrorDetector, emptyConfig, type SyncEngineContext, } from '../SyncEngineContext.js';
-export type { SyncEngineConfig, SyncLogger, SyncObservabilityProvider, SyncAnalytics, MutationExecutor, MutationDispatcher, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, BreadcrumbLevel, SyncBreadcrumbCategory, TransactionFailureDetails, BootstrapFailureDetails, WebSocketErrorDetails, RollbackDetails, SpanAttributes, } from '../interfaces/index.js';
-export { SyncSessionError } from '../errors.js';
-export { QueryProcessor } from './QueryProcessor.js';
-export { QueryView, type QueryViewOptions } from './QueryView.js';
-export { ViewRegistry } from './ViewRegistry.js';
-export { ObjectStore } from '../stores/ObjectStore.js';
-export { NetworkMonitor } from '../NetworkMonitor.js';
-export { SyncWebSocket, type SyncDelta, type VersionVector, type BootstrapHint, type SyncGroupChangePayload, type BootstrapDataEvent, type PresenceUpdateEvent, type SyncWebSocketOptions, } from '../sync/SyncWebSocket.js';
-export { BootstrapHelper, type BootstrapData, type BootstrapOptions, type BootstrapFetchResult } from '../sync/BootstrapHelper.js';
+export type { SyncLogger, SyncObservabilityProvider, MutationExecutor, MutationDispatcher, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, } from '../interfaces/index.js';
+export { SyncWebSocket, type SyncDelta, type SyncWebSocketOptions, } from '../sync/SyncWebSocket.js';
+export { BootstrapHelper } from '../sync/BootstrapHelper.js';
 export { createIntentStream, type AttachableIntentStream, type IntentStreamConfig, } from '../sync/createIntentStream.js';
 export { awaitIntentGrant, type GrantTransport, } from '../sync/awaitIntentGrant.js';
-export { OfflineTransactionStore, offlineTxStore, Priority } from '../sync/OfflineTransactionStore.js';
-export { PropertyType, LoadStrategy, MutationOperationType } from '../types/index.js';
-export type { PropertyMetadata, ReferenceMetadata, ModelMetadata, SyncAction, DeltaPacket, BootstrapMetadata, DatabaseMetadata, } from '../types/index.js';
-export type { ModelData } from '../BaseSyncedStore.js';
+export { LoadStrategy } from '../types/index.js';

package/dist/core/index.js

@@ -1,52 +1,33 @@
 /**
  * @abloatai/ablo/core — Framework extension
  *
- * Only imported by SyncedStore.ts and ApplicationStore.ts —
- * the 2-3 files that extend or orchestrate the sync engine.
- * Regular model files and components should NOT import from here.
+ * Only imported by the handful of files that extend or orchestrate the
+ * sync engine (the app-shell store/provider stack, sync adapters, demo
+ * harnesses). Regular model files and components should NOT import from
+ * here — the consumer surface is `Ablo({ schema })` on the root.
+ *
+ * TRIMMED to what framework-level consumers actually import (verified by
+ * a monorepo-wide import scan). Everything else the engine defines stays
+ * module-private: if a new framework concern genuinely needs another
+ * primitive, add the export deliberately — don't re-widen the barrel.
  */
-// Base store class
-export { BaseSyncedStore, BOOTSTRAP_CONFIG, } from '../BaseSyncedStore.js';
-// Core infrastructure
+// Base store class + the constructor shapes subclasses reference
+export { BaseSyncedStore, } from '../BaseSyncedStore.js';
+// Core infrastructure classes
 export { SyncClient } from '../SyncClient.js';
 export { Database } from '../Database.js';
 export { ObjectPool, ModelScope } from '../ObjectPool.js';
 export { Model } from '../Model.js';
-export { LazyReferenceCollection } from '../LazyReferenceCollection.js';
-// Undo runtime — `useUndoScope` hook from `@abloatai/ablo/react` is
-// the canonical access path. Type counterparts (`Ablo.Mutator.UndoScope`,
-// `Ablo.Mutator.UndoEntry`, `Ablo.Mutator.InverseOp`) live on the main `Ablo`
-// namespace. Direct class access (tests, non-React hosts) imports via
-// the package's internal subpath.
-// Lower-level network primitives — exposed here for the per-app demand
-// loaders. The main barrel hides these so consumer code converges on
-// `ablo.<model>.fetch(...)` for hydration. Loaders that haven't been
-// migrated yet can keep importing from `/core`.
+export { LazyReferenceCollection, } from '../LazyReferenceCollection.js';
+export { ModelRegistry, getActiveRegistry, } from '../ModelRegistry.js';
+// Lower-level network read — for per-app demand loaders that haven't
+// migrated to `ablo.<model>.list(...)` yet.
 export { postQuery } from '../query/client.js';
-export { probeNetwork } from '../sync/NetworkProbe.js';
-export { ConnectionManager, } from '../sync/ConnectionManager.js';
-export { ModelRegistry, getActiveRegistry } from '../ModelRegistry.js';
 // FK-cycle / dependency-order helper — used by schema-aware test
-// fixtures and scaffolding tools to compute commit ordering. Lives
-// here because it traverses model relations and isn't part of the
-// consumer-facing API.
+// fixtures and scaffolding tools to compute commit ordering.
 export { computeFKDepthPriority } from '../client/Ablo.js';
-export { TransactionQueue } from '../transactions/TransactionQueue.js';
-// ── Provider-facing DI types (was the deleted `/config` subpath) ──
-// Adapters that the consumer wires into `<AbloProvider>` props
-// (logger, observability, mutation executor, session-error
-// detector, etc.) implement these interfaces. Lives on `/core`
-// because most consumers don't need them; only apps that wrap the
-// provider with custom adapters reach for them.
-export { initSyncEngine, resetSyncEngine, isSyncEngineInitialized } from '../context.js';
-export { noopLogger, noopObservability, noopAnalytics, browserOnlineStatus, defaultSessionErrorDetector, emptyConfig, } from '../SyncEngineContext.js';
-export { SyncSessionError } from '../errors.js';
-export { QueryProcessor } from './QueryProcessor.js';
-export { QueryView } from './QueryView.js';
-export { ViewRegistry } from './ViewRegistry.js';
-export { ObjectStore } from '../stores/ObjectStore.js';
-export { NetworkMonitor } from '../NetworkMonitor.js';
-// Sync layer
+// Sync layer — the wire socket + delta shape, for sync adapters and the
+// multi-agent demo harnesses.
 export { SyncWebSocket, } from '../sync/SyncWebSocket.js';
 export { BootstrapHelper } from '../sync/BootstrapHelper.js';
 // Intent coordination primitives (the lower-level pieces behind the
@@ -56,11 +37,6 @@ export { BootstrapHelper } from '../sync/BootstrapHelper.js';
 // orchestration and e2e harnesses — NOT on the consumer `.` root.
 export { createIntentStream, } from '../sync/createIntentStream.js';
 export { awaitIntentGrant, } from '../sync/awaitIntentGrant.js';
-// Offline transaction queue — moved out of the main barrel in the headless
-// audit cleanup (see docs/headless-audit.md §4.1 Task 23). The class
-// touches indexedDB + crypto.subtle and therefore cannot live on the main
-// headless-clean import path. Framework-level consumers (the few files
-// that orchestrate sync) import from /core explicitly.
-export { OfflineTransactionStore, offlineTxStore, Priority } from '../sync/OfflineTransactionStore.js';
-// Types used by framework-level code
-export { PropertyType, LoadStrategy, MutationOperationType } from '../types/index.js';
+// Schema/model load strategy enum — referenced by model registration in
+// framework code.
+export { LoadStrategy } from '../types/index.js';

package/dist/errorCodes.d.ts

@@ -134,9 +134,15 @@ export declare const ERROR_CODES: {
     readonly browser_apikey_blocked: ErrorCodeSpec;
     readonly browser_database_url_blocked: ErrorCodeSpec;
     readonly datasource_registration_failed: ErrorCodeSpec;
+    readonly datasource_connection_unsupported: ErrorCodeSpec;
     readonly capability_scope_denied: ErrorCodeSpec;
     readonly issuer_register_forbidden: ErrorCodeSpec;
     readonly capability_invalid: ErrorCodeSpec;
+    readonly test_database_not_registered: ErrorCodeSpec;
+    readonly database_role_cannot_enforce_rls: ErrorCodeSpec;
+    readonly database_role_unreadable: ErrorCodeSpec;
+    readonly database_tables_unforced_rls: ErrorCodeSpec;
+    readonly database_host_not_allowed: ErrorCodeSpec;
     readonly byo_role_cannot_enforce_rls: ErrorCodeSpec;
     readonly byo_role_unreadable: ErrorCodeSpec;
     readonly byo_tenant_tables_unforced_rls: ErrorCodeSpec;
@@ -152,6 +158,13 @@ export declare const ERROR_CODES: {
     readonly stale_context: ErrorCodeSpec;
     readonly idempotency_conflict: ErrorCodeSpec;
     readonly idempotency_key_too_long: ErrorCodeSpec;
+    readonly write_options_invalid: ErrorCodeSpec;
+    readonly source_operation_id_required: ErrorCodeSpec;
+    readonly source_adapter_misconfigured: ErrorCodeSpec;
+    readonly source_event_invalid: ErrorCodeSpec;
+    readonly duration_invalid: ErrorCodeSpec;
+    readonly schema_definition_invalid: ErrorCodeSpec;
+    readonly cli_invalid_arguments: ErrorCodeSpec;
     readonly turn_validation_failed: ErrorCodeSpec;
     readonly commit_operation_required: ErrorCodeSpec;
     readonly commit_operation_model_required: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -123,11 +123,19 @@ export const ERROR_CODES = {
     file_upload_auth_required: wire('auth', 401, false, 'File upload requires an authenticated session.'),
     browser_apikey_blocked: client('auth', 'Raw API keys must not be used from a browser context.'),
     browser_database_url_blocked: client('auth', 'A database connection string must not be used from a browser context — it carries DB credentials.'),
-    datasource_registration_failed: client('auth', 'Failed to register the provided databaseUrl for the direct Postgres connector.'),
+    datasource_registration_failed: client('auth', 'Failed to register the provided databaseUrl as a datasource.'),
+    datasource_connection_unsupported: wire('validation', 400, false, 'This deployment cannot register a direct (connection string) datasource — use the signed endpoint kind.'),
     // ── permission / capability (403) ──────────────────────────────────
     capability_scope_denied: wire('capability', 403, false, "The connection's resolved scope does not cover the attempted action."),
     issuer_register_forbidden: wire('permission', 403, false, 'Registering a trusted issuer requires a secret (sk_) API key.'),
     capability_invalid: wire('capability', 403, false, 'The capability is unknown, revoked, or expired.'),
+    test_database_not_registered: wire('permission', 403, false, 'Test mode requires a registered dev database for this org — run `npx ablo init`, or construct the client with `databaseUrl` using your test key.'),
+    database_role_cannot_enforce_rls: wire('permission', 403, false, 'The connected database role cannot enforce row-level security (superuser or BYPASSRLS).'),
+    database_role_unreadable: wire('permission', 403, false, 'The connected database role could not be introspected.'),
+    database_tables_unforced_rls: wire('permission', 403, false, 'Synced tables in the connected database do not have FORCE ROW LEVEL SECURITY applied.'),
+    database_host_not_allowed: wire('permission', 403, false, 'The connected database host resolves to a private, loopback, or link-local address and cannot be used.'),
+    // Deprecated spellings of the `database_*` codes above — still emitted by
+    // older servers; kept so they classify identically. Do not use in new code.
     byo_role_cannot_enforce_rls: wire('permission', 403, false, 'The direct Postgres connector role cannot enforce row-level security.'),
     byo_role_unreadable: wire('permission', 403, false, 'The direct Postgres connector role could not be introspected.'),
     byo_tenant_tables_unforced_rls: wire('permission', 403, false, 'Tenant tables do not have RLS forced under the direct Postgres connector role.'),
@@ -146,6 +154,13 @@ export const ERROR_CODES = {
     idempotency_conflict: wire('conflict', 409, false, 'The same Idempotency-Key was reused with a different request body.'),
     idempotency_key_too_long: wire('validation', 400, false, 'The supplied Idempotency-Key exceeds the maximum length.'),
     // ── validation (400 / 422) ─────────────────────────────────────────
+    write_options_invalid: client('validation', 'The write options (`idempotencyKey` / `label` / `wait` / `readAt` / `onStale` / `intent`) failed validation against the write-options schema.'),
+    source_operation_id_required: client('validation', 'A data-source operation arrived without the entity `id` it targets.'),
+    source_adapter_misconfigured: client('validation', 'The data-source ORM adapter could not map a schema model onto the backing client (missing delegate or model).'),
+    source_event_invalid: client('validation', 'A data-source outbox event could not be built — the operation carries no entity id and none was supplied.'),
+    duration_invalid: client('validation', 'A duration value was not a number of seconds or a "500ms" | "30s" | "3m" | "24h" string.'),
+    schema_definition_invalid: client('validation', 'A schema definition value was invalid (bad column identifier, non-finite backfill, or unsupported schema-JSON version).'),
+    cli_invalid_arguments: client('validation', 'The CLI was invoked with an unknown flag or a malformed flag value.'),
     turn_validation_failed: wire('validation', 422, false, 'The agent turn failed server-side validation.'),
     commit_operation_required: wire('validation', 400, false, 'A commit must carry `operation` or `operations`.'),
     commit_operation_model_required: wire('validation', 400, false, 'A commit operation is missing its `model`.'),

package/dist/index.d.ts

@@ -64,6 +64,9 @@ export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionErr
 export type { CommitReceipt, RequiredCapability } 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 { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './client/writeOptionsSchema.js';
+export type { WriteOptionsInput } from './client/writeOptionsSchema.js';
+export type { WriteOptions, MutationOptions } from './interfaces/index.js';
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
 export type { Register, DefaultSyncShape } from './types/global.js';
 export { defineMutators } from './mutators/defineMutators.js';

package/dist/index.js

@@ -89,6 +89,13 @@ export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
 // `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, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
+// THE write-options contract — the one Zod schema for the option bag every
+// write door accepts (`ablo.<model>.create/update/delete`, `commits.create`,
+// the HTTP model routes). The SDK validates against it at each boundary;
+// it's exported so consumers can validate/compose options ahead of a call
+// (e.g. an agent tool's input schema). Runtime twin of `MutationOptions`,
+// drift-guarded at compile time.
+export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './client/writeOptionsSchema.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';

package/dist/interfaces/index.d.ts

@@ -171,6 +171,16 @@ export interface MutationOptions {
      */
     causedByTaskId?: string | null;
 }
+/**
+ * The `MutationOptions` subset carried per-write through the offline
+ * transaction lane (SyncClient → TransactionQueue → wire operation).
+ * ONE shared type so the proxy's public params, the queue, and the wire
+ * can never narrow each other silently again — `wait` and `intent` are
+ * deliberately absent because they resolve client-side before staging
+ * (`wait` at the proxy's confirmation await, `intent` server-side via
+ * the active lease on the entity).
+ */
+export type WriteOptions = Pick<MutationOptions, 'readAt' | 'onStale' | 'idempotencyKey' | 'label'>;
 /** A single mutation operation in a batch. `options` rides along so the
  *  server can cache+replay via `mutation_log`. */
 export interface MutationOperation {

package/dist/mutators/UndoManager.d.ts

@@ -52,11 +52,6 @@ export interface UndoScopeOptions {
      */
     recordFromStream?: boolean;
 }
-/**
- * A single undo stack for one surface. Access via `UndoManager.getScope(name)`.
- * Consumers call `record(entry)` after each mutator; `undo()` / `redo()` to
- * traverse the stacks.
- */
 export declare class UndoScope<S extends Schema> {
     private readonly schema;
     private readonly store;
@@ -121,6 +116,23 @@ export declare class UndoScope<S extends Schema> {
      * response) collapses into ONE Cmd+Z. `endGroup()` flushes it.
      */
     private group;
+    /**
+     * ASYNC replay-echo suppression, keyed by `${modelKey}:${id}`.
+     *
+     * The synchronous {@link replaying} flag only catches echoes delivered INLINE
+     * during `applyOps`. The real engine doesn't emit `transaction:created`
+     * synchronously: `SyncClient` defers the commit behind `scheduleSync()` +
+     * `await persistMutationQueue()` (an IndexedDB write), so a replayed write's
+     * echo lands on the stream AFTER `undo()`/`redo()` has already reset
+     * `replaying` and pushed the entry. That late echo would be recorded as a
+     * NEW edit — and `record()` clears the redo stack, so every undo silently
+     * destroyed its own redo. We mark the (modelKey,id) of every op we're about
+     * to replay here (synchronously, before the write), and consume one mark when
+     * the matching mutation arrives — independent of WHEN it arrives. Entries
+     * carry a TTL so a never-arriving echo (offline: the commit is skipped) can't
+     * leak and wrongly suppress a much-later genuine edit to the same row.
+     */
+    private readonly pendingReplayEchoes;
     constructor(schema: S, store: SyncStoreContract, organizationId: string, options?: UndoScopeOptions);
     /**
      * Open a grouping session: every stream-recorded op until {@link endGroup}
@@ -131,6 +143,20 @@ export declare class UndoScope<S extends Schema> {
     beginGroup(label?: string): void;
     /** Close the grouping session and record the accumulated ops as one entry. */
     endGroup(label?: string): void;
+    /** Every `${modelKey}:${id}` a set of ops will touch (all op kinds). */
+    private replayEchoKeys;
+    /**
+     * Arm async-echo suppression for the rows a replay is about to write. Called
+     * synchronously, before `applyOps`, so the marks exist no matter how long the
+     * engine takes to surface the echo on the stream. See {@link pendingReplayEchoes}.
+     */
+    private markReplayEchoes;
+    /**
+     * If `${schemaKey}:${modelId}` has an armed echo mark, consume one and report
+     * that this mutation is our own replay echo (caller drops it). Prunes expired
+     * marks opportunistically so a skipped/never-arriving echo can't leak.
+     */
+    private consumeReplayEcho;
     /** Resolve a stream mutation's registered name to its schema key, or null. */
     private resolveSchemaKey;
     /**

package/dist/mutators/UndoManager.js

@@ -28,6 +28,13 @@ const normalizeModelAlias = (modelName) => modelName.replace('Model', '').toLowe
  * Consumers call `record(entry)` after each mutator; `undo()` / `redo()` to
  * traverse the stacks.
  */
+/**
+ * How long a marked replay-echo stays armed before it's pruned. The real echo
+ * arrives within a couple of IndexedDB round-trips (tens of ms); this is a
+ * generous safety ceiling so a never-arriving echo (e.g. the commit was skipped
+ * offline) can't suppress a genuine later edit to the same row indefinitely.
+ */
+const REPLAY_ECHO_TTL_MS = 5000;
 export class UndoScope {
     schema;
     store;
@@ -92,6 +99,23 @@ export class UndoScope {
      * response) collapses into ONE Cmd+Z. `endGroup()` flushes it.
      */
     group = null;
+    /**
+     * ASYNC replay-echo suppression, keyed by `${modelKey}:${id}`.
+     *
+     * The synchronous {@link replaying} flag only catches echoes delivered INLINE
+     * during `applyOps`. The real engine doesn't emit `transaction:created`
+     * synchronously: `SyncClient` defers the commit behind `scheduleSync()` +
+     * `await persistMutationQueue()` (an IndexedDB write), so a replayed write's
+     * echo lands on the stream AFTER `undo()`/`redo()` has already reset
+     * `replaying` and pushed the entry. That late echo would be recorded as a
+     * NEW edit — and `record()` clears the redo stack, so every undo silently
+     * destroyed its own redo. We mark the (modelKey,id) of every op we're about
+     * to replay here (synchronously, before the write), and consume one mark when
+     * the matching mutation arrives — independent of WHEN it arrives. Entries
+     * carry a TTL so a never-arriving echo (offline: the commit is skipped) can't
+     * leak and wrongly suppress a much-later genuine edit to the same row.
+     */
+    pendingReplayEchoes = new Map();
     constructor(schema, store, organizationId, options = {}) {
         this.schema = schema;
         this.store = store;
@@ -150,6 +174,80 @@ export class UndoScope {
             return;
         this.record({ label: label ?? g.label, inverses, forwards });
     }
+    /** Every `${modelKey}:${id}` a set of ops will touch (all op kinds). */
+    *replayEchoKeys(ops) {
+        for (const op of ops) {
+            switch (op.kind) {
+                case 'create': {
+                    const id = op.data.id;
+                    if (typeof id === 'string')
+                        yield `${op.modelKey}:${id}`;
+                    break;
+                }
+                case 'update':
+                    yield `${op.modelKey}:${op.patch.id}`;
+                    break;
+                case 'delete':
+                    yield `${op.modelKey}:${op.id}`;
+                    break;
+                case 'createMany':
+                    for (const d of op.data) {
+                        const id = d.id;
+                        if (typeof id === 'string')
+                            yield `${op.modelKey}:${id}`;
+                    }
+                    break;
+                case 'updateMany':
+                    for (const p of op.patches)
+                        yield `${op.modelKey}:${p.id}`;
+                    break;
+                case 'deleteMany':
+                    for (const id of op.ids)
+                        yield `${op.modelKey}:${id}`;
+                    break;
+            }
+        }
+    }
+    /**
+     * Arm async-echo suppression for the rows a replay is about to write. Called
+     * synchronously, before `applyOps`, so the marks exist no matter how long the
+     * engine takes to surface the echo on the stream. See {@link pendingReplayEchoes}.
+     */
+    markReplayEchoes(ops) {
+        const expiresAt = Date.now() + REPLAY_ECHO_TTL_MS;
+        for (const key of this.replayEchoKeys(ops)) {
+            const existing = this.pendingReplayEchoes.get(key);
+            if (existing) {
+                existing.count += 1;
+                existing.expiresAt = expiresAt;
+            }
+            else {
+                this.pendingReplayEchoes.set(key, { count: 1, expiresAt });
+            }
+        }
+    }
+    /**
+     * If `${schemaKey}:${modelId}` has an armed echo mark, consume one and report
+     * that this mutation is our own replay echo (caller drops it). Prunes expired
+     * marks opportunistically so a skipped/never-arriving echo can't leak.
+     */
+    consumeReplayEcho(schemaKey, modelId) {
+        if (this.pendingReplayEchoes.size === 0)
+            return false;
+        const now = Date.now();
+        for (const [k, v] of this.pendingReplayEchoes) {
+            if (v.expiresAt <= now)
+                this.pendingReplayEchoes.delete(k);
+        }
+        const key = `${schemaKey}:${modelId}`;
+        const pending = this.pendingReplayEchoes.get(key);
+        if (!pending)
+            return false;
+        pending.count -= 1;
+        if (pending.count <= 0)
+            this.pendingReplayEchoes.delete(key);
+        return true;
+    }
     /** Resolve a stream mutation's registered name to its schema key, or null. */
     resolveSchemaKey(modelName) {
         return (this.schemaKeyByAlias.get(modelName) ??
@@ -169,6 +267,13 @@ export class UndoScope {
         const schemaKey = this.resolveSchemaKey(m.modelName);
         if (!schemaKey)
             return;
+        // Drop the ASYNC echo of our own replayed writes. The engine surfaces a
+        // replay's `transaction:created` only after an IndexedDB-gated commit, i.e.
+        // after `replaying` has already reset — so the synchronous flag above misses
+        // it. The (modelKey,id) marks armed in `markReplayEchoes` catch it whenever
+        // it lands, which is what stops every undo from wiping its own redo stack.
+        if (this.consumeReplayEcho(schemaKey, m.modelId))
+            return;
         if (this.tracksModel && !this.tracksModel(schemaKey))
             return;
         const ops = buildUndoOps(m, schemaKey);
@@ -331,7 +436,10 @@ export class UndoScope {
             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.
+            // new undo entries. `replaying` covers inline echoes; `markReplayEchoes`
+            // covers the engine's async (IDB-gated) echo that lands after this method
+            // returns. Cleared in `finally` even if a replay op throws.
+            this.markReplayEchoes(ops);
             this.replaying = true;
             try {
                 await applyOps(tx, ops);
@@ -366,6 +474,8 @@ export class UndoScope {
                 return;
             const tx = createTransaction(this.schema, this.store, this.organizationId);
             const ops = resolveOps(entry.forwards, entry.inverses, this.store, this.conflictPolicy);
+            // See undo(): arm async-echo suppression before the replayed writes.
+            this.markReplayEchoes(ops);
             this.replaying = true;
             try {
                 await applyOps(tx, ops);
@@ -391,6 +501,7 @@ export class UndoScope {
         this.undoStack = [];
         this.redoStack = [];
         this.batch = [];
+        this.pendingReplayEchoes.clear();
         this.emitChange();
     }
     /** Introspection — for debug panels / e2e tests. */
@@ -407,6 +518,7 @@ export class UndoScope {
         this.recordListeners.clear();
         this.changeListeners.clear();
         this.batch = [];
+        this.pendingReplayEchoes.clear();
     }
 }
 /**

package/dist/schema/ddl.js

@@ -17,6 +17,7 @@
  *  - `generateMigrationPlan` — the destructive-aware counterpart driven by the
  *    {@link diffSchema} step list (drops, renames, type casts, backfills).
  */
+import { AbloValidationError } from '../errors.js';
 import { resolveTenancy, tenancyColumn } from './tenancy.js';
 // ── Identifier safety ────────────────────────────────────────────────────────
 /** Postgres unquoted-identifier-safe slug: lowercase `[a-z0-9_]`, ≤50 chars. */
@@ -289,7 +290,7 @@ function sqlLiteral(value, fieldType) {
     switch (fieldType) {
         case 'number':
             if (typeof value !== 'number' || !Number.isFinite(value)) {
-                throw new Error(`backfill for a number field must be a finite number, got ${JSON.stringify(value)}`);
+                throw new AbloValidationError(`backfill for a number field must be a finite number, got ${JSON.stringify(value)}`, { code: 'schema_definition_invalid' });
             }
             return String(value);
         case 'boolean':
@@ -314,6 +315,14 @@ export function generateMigrationPlan(steps, opts) {
     const qs = q(targetSchema);
     const statements = [];
     const concurrent = [];
+    // The app schema must exist before any statement targets it. On a fresh
+    // org's FIRST push (`prev = null`) the migration plan IS the provisioning —
+    // `app_<orgId>` has never been created, and skipping this line made every
+    // first push die with `3F000 invalid_schema_name` at statement 0. Idempotent
+    // (`IF NOT EXISTS`), so emitting it on every later migration is free.
+    if (steps.length > 0 && targetSchema !== 'public') {
+        statements.push(`CREATE SCHEMA IF NOT EXISTS ${qs};`);
+    }
     const qtFor = (table) => `${qs}.${q(table)}`;
     const tableOfModel = (schema, key) => {
         const m = schema?.models[key];
@@ -326,8 +335,8 @@ export function generateMigrationPlan(steps, opts) {
         switch (step.kind) {
             case 'create_model': {
                 // Reuse the provisioner for the full table (base cols + fields + enum
-                // checks + RLS), minus its `CREATE SCHEMA` (the schema already exists
-                // mid-migration).
+                // checks + RLS), minus its `CREATE SCHEMA` (the plan header above
+                // already emitted it once — don't repeat it per model).
                 const def = next.models[step.model];
                 if (!def)
                     break;

package/dist/schema/field.js

@@ -23,6 +23,7 @@
  *   });
  */
 import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
 // ── Helpers ───────────────────────────────────────────────────────────────
 /** Distinguish a Zod schema from a plain object shape (ZodRawShape). */
 function isZodSchema(value) {
@@ -179,7 +180,7 @@ export function resolveFieldMeta(schema) {
 }
 function assertColumnName(column) {
     if (!/^[a-zA-Z_][a-zA-Z0-9_]{0,62}$/.test(column)) {
-        throw new Error(`field.from(): invalid column identifier ${JSON.stringify(column)}`);
+        throw new AbloValidationError(`field.from(): invalid column identifier ${JSON.stringify(column)}`, { code: 'schema_definition_invalid' });
     }
 }
 /** Add sync-engine chain methods to a Zod schema without disturbing its type. */

package/dist/schema/model.d.ts

@@ -188,14 +188,16 @@ export interface ModelOptions {
     entityRoles?: EntityRole | readonly EntityRole[];
     /**
      * Whether clients may issue CREATE/UPDATE/DELETE mutations for this
-     * model via the `commit` wire protocol. Default: false.
+     * model via the `commit` wire protocol. Default: **true** — declaring a
+     * model in the schema IS the opt-in; if you put an entity in your synced
+     * schema, you almost always want to write it (product decision
+     * 2026-06-10, reversing the earlier default-deny that made every fresh
+     * quickstart's first write die with `server_execute_unknown_model`).
      *
-     * Safety-by-default: a newly-declared schema entity is read-only from
-     * the client side until the author explicitly opts into wire mutability.
-     * Prevents the class of bug where adding a new entity to the schema
-     * silently exposes it as a write surface (the 2026-04-20 `AgentJob`
-     * incident) OR where internal tables (`sync_deltas`, `presences`,
-     * digest/ingestion tables) become writable by accident.
+     * Opt OUT for server-managed projections (stats, digests, audit views):
+     * `mutable: false`, or the `readOnly.*` sugar which sets it for you.
+     * That keeps the 2026-04-20 `AgentJob`-class protection available where
+     * it matters, as a deliberate marking instead of a silent default.
      *
      * The server's `buildModelMap` (src/server/commit.ts) derives
      * the mutation allowlist from this flag — no parallel hardcoded list.

package/dist/schema/model.js

@@ -99,7 +99,7 @@ export function model(shape, relations, options) {
         scope: options?.scope,
         grants: options?.grants,
         entityRoles: normalizeEntityRoles(options?.entityRoles),
-        mutable: options?.mutable,
+        mutable: options?.mutable ?? true,
         lazyObservable: options?.lazyObservable,
         computed: options?.computed,
         autoFill: options?.autoFill,

package/dist/schema/schema.js

@@ -167,7 +167,13 @@ export function defineSchema(models, options) {
         const persist = def.persist
             ? { ...def.persist, store: def.persist.store ?? typename }
             : undefined;
-        resolvedModels[name] = { ...def, typename, persist };
+        // Physical table defaults to the schema key — the SAME rule the
+        // provisioner/planner use (`tableName ?? key`), resolved here once so the
+        // serialized artifact always carries it. Required now that models are
+        // mutable by default: the server's `buildModelMap` rejects a mutable
+        // model with no `tableName`, which would otherwise break every commit.
+        const tableName = def.tableName ?? name;
+        resolvedModels[name] = { ...def, typename, tableName, persist };
     }
     validateSyncGroupSchema(resolvedModels);
     return {

package/dist/schema/serialize.js

@@ -25,6 +25,7 @@
  *     `FieldMeta` (the server does no field-shape validation anyway)
  */
 import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
 import { baseFieldsSchema, } from './schema.js';
 /** Current schema-JSON envelope version. Bump on a breaking change to the
  * JSON shape itself (not the user's schema). v2 replaced the per-model
@@ -201,7 +202,7 @@ export function fromSchemaJSON(json) {
 export function parseSchema(json) {
     const parsed = JSON.parse(json);
     if (parsed.v !== SCHEMA_JSON_VERSION) {
-        throw new Error(`parseSchema: unsupported schema-JSON version ${parsed.v} (expected ${SCHEMA_JSON_VERSION})`);
+        throw new AbloValidationError(`parseSchema: unsupported schema-JSON version ${parsed.v} (expected ${SCHEMA_JSON_VERSION})`, { code: 'schema_definition_invalid' });
     }
     return fromSchemaJSON(parsed);
 }

package/dist/server/storage-mode.d.ts

@@ -7,11 +7,18 @@
  *   - `hosted`     — Ablo's control-plane database.
  *   - `selfHosted` — the customer's database, same execution path as hosted.
  *   - `source`     — a customer-owned endpoint (credentialless ingestion).
+ *
+ * @internal Deployment topology, not product vocabulary. Customers never see a
+ * "storage mode" — their story is `Ablo({ schema, apiKey, databaseUrl })` and
+ * one `datasource` resource (docs/plans/sync-engine-stripe-story-scope.md).
+ * This export exists for the sync-server host only.
  */
 import { z } from 'zod';
+/** @internal See module note — host-deployment vocabulary, never customer-facing. */
 export declare const storageModeSchema: z.ZodEnum<{
     source: "source";
     hosted: "hosted";
     selfHosted: "selfHosted";
 }>;
+/** @internal See module note — host-deployment vocabulary, never customer-facing. */
 export type StorageMode = z.infer<typeof storageModeSchema>;