@abloatai/ablo 0.9.1 → 0.9.3

package/dist/client/registerDataSource.js

@@ -1,12 +1,13 @@
 /**
- * Self-serve direct-Postgres connector registration.
- *
- * Historical note: this module name says "DataSource", but this path registers
- * a direct database URL. It is not the signed `dataSource(...)` endpoint path.
+ * Self-serve direct-kind datasource registration.
  *
  * When a client is constructed with `databaseUrl`, the SDK registers that
  * connection string BEFORE bootstrap so the server resolves the org's data plane
- * to that direct connector.
+ * to that direct connection.
+ *
+ * Targets the unified `POST /v1/datasources` resource; on a 404 (an older
+ * server without the unified route) it falls back to the legacy
+ * `POST /v1/datasource` alias so an SDK upgrade never strands registration.
  *
  * The org is derived server-side from the API key — the caller never sends an
  * organization id. The connection string is sent once over TLS and is never
@@ -15,36 +16,43 @@
  */
 import { AbloError } from '../errors.js';
 /**
- * POST the connection string to the self-serve direct connector route. Resolves
- * on success (the org is now a dedicated tenant pointed at this DB); throws an
- * `AbloError` with `datasource_registration_failed` otherwise so `ready()`
- * surfaces it instead of silently bootstrapping against the wrong store.
+ * POST the connection string to the self-serve datasource route. Resolves on
+ * success (the org's data plane now points at this DB); throws an `AbloError`
+ * with `datasource_registration_failed` otherwise so `ready()` surfaces it
+ * instead of silently bootstrapping against the wrong store.
  */
 export async function registerDataSource(input) {
     if (!input.apiKey) {
-        throw new AbloError('databaseUrl requires an apiKey to register the direct Postgres connector (the org is derived from the key).', { code: 'datasource_registration_failed' });
+        throw new AbloError('databaseUrl requires an apiKey to register the database connection (the org is derived from the key).', { code: 'datasource_registration_failed' });
     }
     const doFetch = input.fetchImpl ?? fetch;
-    const endpoint = `${input.baseUrl.replace(/\/+$/, '')}/v1/datasource`;
-    let response;
-    try {
-        response = await doFetch(endpoint, {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                authorization: `Bearer ${input.apiKey}`,
-            },
-            body: JSON.stringify({
-                connectionString: input.databaseUrl,
-                ...(input.schema ? { schema: input.schema } : {}),
-            }),
-        });
-    }
-    catch (cause) {
-        throw new AbloError('Could not reach the Ablo API to register the direct Postgres connector.', {
-            code: 'datasource_registration_failed',
-            cause,
-        });
+    const base = input.baseUrl.replace(/\/+$/, '');
+    const body = JSON.stringify({
+        connectionString: input.databaseUrl,
+        ...(input.schema ? { schema: input.schema } : {}),
+    });
+    const post = async (endpoint) => {
+        try {
+            return await doFetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${input.apiKey}`,
+                },
+                body,
+            });
+        }
+        catch (cause) {
+            throw new AbloError('Could not reach the Ablo API to register the database connection.', {
+                code: 'datasource_registration_failed',
+                cause,
+            });
+        }
+    };
+    let response = await post(`${base}/v1/datasources`);
+    if (response.status === 404) {
+        // Older server without the unified resource — use the legacy alias.
+        response = await post(`${base}/v1/datasource`);
     }
     if (!response.ok) {
         let detail = '';
@@ -54,6 +62,6 @@ export async function registerDataSource(input) {
         catch {
             // ignore body read failures — the status alone is enough to fail loud
         }
-        throw new AbloError(`Direct Postgres connector registration failed (HTTP ${response.status}). ${detail}`, { code: 'datasource_registration_failed', httpStatus: response.status });
+        throw new AbloError(`Database connection registration failed (HTTP ${response.status}). ${detail}`, { code: 'datasource_registration_failed', httpStatus: response.status });
     }
 }

package/dist/client/writeOptionsSchema.d.ts

@@ -0,0 +1,50 @@
+/**
+ * THE write-options schema — one Zod schema for the write dialect every
+ * door speaks (`ablo.<model>.create/update/delete`, `commits.create`, the
+ * HTTP model routes). Validated once at each public boundary so a plain-JS
+ * caller passing `onStale: 'rejct'` fails loudly at the call site with a
+ * typed `AbloValidationError`, not silently (or 400) at the server.
+ *
+ * Mirrors `source/contract.ts`: the schema is the runtime twin of the
+ * `MutationOptions` interface, with a compile-time drift guard at the
+ * bottom so the two can never silently diverge.
+ *
+ * Validation-only by design: callers keep their ORIGINAL options object.
+ * Zod's parse output strips unknown keys, and the `intent` slot legally
+ * carries live handles (`IntentLeaseHandle` / claim leases) whose
+ * `release`/`revoke` functions must survive — so we assert, never replace.
+ */
+import { z } from 'zod';
+export declare const onStaleModeSchema: z.ZodEnum<{
+    reject: "reject";
+    force: "force";
+    flag: "flag";
+    merge: "merge";
+}>;
+export declare const writeOptionsSchema: z.ZodObject<{
+    idempotencyKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    label: z.ZodOptional<z.ZodString>;
+    wait: z.ZodOptional<z.ZodEnum<{
+        confirmed: "confirmed";
+        queued: "queued";
+    }>>;
+    readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        reject: "reject";
+        force: "force";
+        flag: "flag";
+        merge: "merge";
+    }>>>;
+    intent: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$loose>]>>>;
+    causedByTaskId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type WriteOptionsInput = z.infer<typeof writeOptionsSchema>;
+/**
+ * Assert a write-options bag against THE schema. Throws a typed
+ * `AbloValidationError` (`code: 'write_options_invalid'`, Stripe-style
+ * `param` pointing at the offending field) and returns nothing — the
+ * caller keeps its original object.
+ */
+export declare function assertWriteOptions(value: unknown, context?: string): void;

package/dist/client/writeOptionsSchema.js

@@ -0,0 +1,57 @@
+/**
+ * THE write-options schema — one Zod schema for the write dialect every
+ * door speaks (`ablo.<model>.create/update/delete`, `commits.create`, the
+ * HTTP model routes). Validated once at each public boundary so a plain-JS
+ * caller passing `onStale: 'rejct'` fails loudly at the call site with a
+ * typed `AbloValidationError`, not silently (or 400) at the server.
+ *
+ * Mirrors `source/contract.ts`: the schema is the runtime twin of the
+ * `MutationOptions` interface, with a compile-time drift guard at the
+ * bottom so the two can never silently diverge.
+ *
+ * Validation-only by design: callers keep their ORIGINAL options object.
+ * Zod's parse output strips unknown keys, and the `intent` slot legally
+ * carries live handles (`IntentLeaseHandle` / claim leases) whose
+ * `release`/`revoke` functions must survive — so we assert, never replace.
+ */
+import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
+export const onStaleModeSchema = z.enum(['reject', 'force', 'flag', 'merge']);
+export const writeOptionsSchema = z.object({
+    /** Server-side mutation_log cache key; `null` opts out of retry-safety. */
+    idempotencyKey: z.string().min(1).max(255).nullish(),
+    /** Human-readable audit tag, persisted to `mutation_log.label`. */
+    label: z.string().max(255).optional(),
+    /** Resolve when queued locally (default) or once the server confirms. */
+    wait: z.enum(['queued', 'confirmed']).optional(),
+    /** Stale guard: the sync watermark the caller's reasoning was based on. */
+    readAt: z.number().int().nonnegative().nullish(),
+    /** What the server does when the target moved past `readAt`. */
+    onStale: onStaleModeSchema.nullish(),
+    /** Claim/intent attribution — an id, or a live lease handle (loose: the
+     *  handle's `release`/`revoke` functions ride along untouched). */
+    intent: z.union([z.string(), z.looseObject({ id: z.string() })]).nullish(),
+    /** Dormant wire-compat field; always `null` from current clients. */
+    causedByTaskId: z.string().nullish(),
+});
+/**
+ * Assert a write-options bag against THE schema. Throws a typed
+ * `AbloValidationError` (`code: 'write_options_invalid'`, Stripe-style
+ * `param` pointing at the offending field) and returns nothing — the
+ * caller keeps its original object.
+ */
+export function assertWriteOptions(value, context) {
+    if (value == null)
+        return;
+    const result = writeOptionsSchema.safeParse(value);
+    if (result.success)
+        return;
+    const issue = result.error.issues[0];
+    const path = issue?.path.map(String).join('.') ?? '';
+    throw new AbloValidationError(`Invalid write options${context ? ` on \`${context}\`` : ''}${path ? ` at \`${path}\`` : ''}: ${issue?.message ?? 'failed validation'}.`, {
+        code: 'write_options_invalid',
+        ...(path ? { param: path } : {}),
+    });
+}
+const _writeOptionsContractInSync = [true, true];
+void _writeOptionsContractInSync;

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`.'),
@@ -176,8 +191,8 @@ export const ERROR_CODES = {
     check_violation: wire('validation', 400, false, 'A value violates a database check constraint.'),
     constraint_violation: wire('validation', 400, false, 'A database integrity constraint was violated.'),
     // ── tenant / unknown model (400) ───────────────────────────────────
-    server_execute_unknown_model: wire('tenant', 400, false, 'The server-execute request named a model not in the tenant schema.'),
-    mutate_create_unknown_model: wire('tenant', 400, false, 'A create targeted a model not in the tenant schema.'),
+    server_execute_unknown_model: wire('tenant', 400, false, 'Wrote to a model the server does not know. The server keeps its own copy of the schema — run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` before writing to new or changed models.'),
+    mutate_create_unknown_model: wire('tenant', 400, false, 'Created a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` first — the server keeps its own copy of the schema.'),
     tenant_model_columns_unknown: wire('tenant', 400, false, "The tenant model's columns could not be resolved."),
     tenant_model_missing_organization_id: wire('tenant', 400, false, 'The tenant model is missing the organization_id column required for isolation.'),
     // ── schema migration / declaration (validation) ────────────────────
@@ -286,7 +301,7 @@ export const ERROR_CODES = {
     provisioner_unavailable: wire('server', 503, false, 'No database provisioner is configured.'),
     invalid_model: wire('validation', 400, false, 'The request named an invalid model.'),
     invalid_id: wire('validation', 400, false, 'The request carried an invalid id.'),
-    unknown_model: wire('tenant', 400, false, 'The request named a model not in the tenant schema.'),
+    unknown_model: wire('tenant', 400, false, 'Named a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` — the server keeps its own copy of the schema.'),
     model_not_tenant_scoped: wire('tenant', 400, false, 'The model is not tenant-scoped and cannot be queried this way.'),
     schema_table_invalid: wire('schema', 500, false, "The model's table identifier is invalid."),
     schema_scope_invalid: wire('schema', 500, false, "The model's scope predicate could not be built."),

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

@@ -61,7 +61,7 @@ export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_UR
 // Participant types live under `Ablo.Participant.*` —
 // `Ablo.Participant.Joined`, `Ablo.Participant.Manager`,
 // `Ablo.Participant.JoinOptions`, etc. Same dot-access shape as
-// `Ablo.Peer`, `Ablo.Claim`, `Ablo.Turn`. No flat re-exports.
+// `Ablo.Peer`, `Ablo.Claim`. No flat re-exports.
 // Advanced — most apps never import this. Principal constructors for
 // delegated agent paths (`Ablo({ kind: 'agent', as: session({...}) })`).
 // The default `Ablo({ schema, apiKey })` resolves identity from the key;
@@ -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

@@ -164,13 +164,23 @@ export interface MutationOptions {
         readonly id: string;
     } | null;
     /**
-     * Active agent turn id to stamp on every delta row produced by this
-     * commit. Forwarded as the wire-level `causedByTaskId` field on the
-     * `{ type: 'commit' }` envelope. Set automatically by the SDK while
-     * `beginTurn(...)` is open.
+     * Dormant agent-task lineage field, forwarded as the wire-level
+     * `causedByTaskId`. Turns/tasks were removed from the SDK; nothing
+     * populates this anymore (write attribution rides on the claim/intent
+     * id). Kept optional for wire-compat; always `null` from the client.
      */
     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;
@@ -75,6 +70,15 @@ export declare class UndoScope<S extends Schema> {
      * observer can never wedge the editor's recording path.
      */
     private readonly recordListeners;
+    /**
+     * Observers notified after ANY stack change — record, undo, redo, or clear.
+     * Distinct from {@link recordListeners} (forward actions only): this fires on
+     * reversals too, so React consumers can keep `canUndo`/`canRedo` live. The
+     * stream-recording path pushes entries WITHOUT a React render, so without this
+     * a freshly-recorded entry leaves `canUndo` stale (snapshot from last render)
+     * and a Cmd+Z handler gated on `canUndo !== false` silently no-ops.
+     */
+    private readonly changeListeners;
     /**
      * Serialization tail. Recording, undo, and redo all chain off this single
      * promise so they run strictly in the order they were *invoked* — never
@@ -112,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}
@@ -122,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;
     /**
@@ -175,6 +210,14 @@ export declare class UndoScope<S extends Schema> {
      */
     onRecord(listener: (entry: UndoEntry) => void): () => void;
     private emitRecord;
+    /**
+     * Subscribe to ANY stack change (record/undo/redo/clear). Used by
+     * `useUndoScope` to re-render so `canUndo`/`canRedo` stay live across every
+     * consumer — not just the component that invoked undo/redo. Returns an
+     * unsubscribe function.
+     */
+    onChange(listener: () => void): () => void;
+    private emitChange;
     canUndo(): boolean;
     canRedo(): boolean;
     /**