@abloatai/ablo 0.9.2 → 0.9.3

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':

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/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>;

package/dist/server/storage-mode.js

@@ -7,6 +7,12 @@
  *   - `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 const storageModeSchema = z.enum(['hosted', 'source', 'selfHosted']);

package/dist/source/adapters/drizzle.js

@@ -28,6 +28,7 @@
  * We use `sql` + `db.execute` for ALL writes (not the fluent builder) so the
  * adapter is one small, fully-typed unit with no per-driver builder generics.
  */
+import { AbloValidationError } from '../../errors.js';
 import { sql } from 'drizzle-orm';
 import { outboxEventSchema } from '../contract.js';
 import { adapterTableMigrations } from '../migrations.js';
@@ -40,7 +41,7 @@ function rowsOf(result) {
 function rowId(op) {
     const id = op.id ?? op.input?.id;
     if (typeof id !== 'string' || id.length === 0) {
-        throw new Error(`operation on "${op.model}" requires an id`);
+        throw new AbloValidationError(`operation on "${op.model}" requires an id`, { code: 'source_operation_id_required' });
     }
     return id;
 }
@@ -76,7 +77,7 @@ export function drizzleDataSource(db, schema) {
     const modelColumns = (model) => {
         const mc = maps.get(model);
         if (!mc)
-            throw new Error(`drizzleDataSource: no model "${model}" in schema`);
+            throw new AbloValidationError(`drizzleDataSource: no model "${model}" in schema`, { code: 'source_adapter_misconfigured' });
         return mc;
     };
     const columnFor = (mc, field) => mc.fieldToColumn.get(field) ?? camelToSnake(field);

package/dist/source/adapters/kysely.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Kysely Data Source adapter. Same adapter interface + conformance shape as
+ * `prismaDataSource` / `drizzleDataSource`, built against Kysely's REAL
+ * query-builder API:
+ *   - `db.transaction().execute(async (trx) => …)` — interactive transaction.
+ *   - `insertInto/updateTable/deleteFrom/selectFrom` + `returningAll()` —
+ *     the fluent builder; table/column names are plain strings, so no raw
+ *     SQL tag is needed and this module imports NOTHING from `kysely`
+ *     (structural `KyselyLike`, mirroring the Prisma adapter's zero-dep
+ *     `PrismaLike`).
+ *
+ * SCHEMA-DRIVEN COLUMNS. Kysely is SQL-near: it passes the column names you
+ * give it through verbatim (no Prisma-style `@map`). Like the Drizzle
+ * adapter, every table + column name is derived from the SAME rule the
+ * provisioner uses (`generateProvisionPlan`):
+ *   table  = `model.tableName ?? key`
+ *   column = `fieldMeta.column ?? camelToSnake(field)`  (+ the tenancy column)
+ * so `ablo migrate` (which emits `operator_id`) and this adapter COMPOSE.
+ * The adapter is the translation boundary: rows in/out are field-keyed (the
+ * SDK shape); the physical columns it reads/writes are snake_case.
+ *
+ * JSONB note: the outbox `data` / idempotency `response` values are passed
+ * as JSON strings — Postgres infers the parameter type from the target
+ * `jsonb` column, so the coercion is server-side and driver-agnostic (no
+ * `::jsonb` cast available without raw SQL).
+ */
+import type { DataSourceAdapter, Row } from '../adapter.js';
+import type { Schema, SchemaRecord } from '../../schema/schema.js';
+/**
+ * The subset of a Kysely instance (or transaction handle) the adapter calls.
+ * Structural on purpose — declared with method shorthand so a real
+ * `Kysely<DB>` (whose params are narrowed to `keyof DB`) stays assignable
+ * under TypeScript's method bivariance, exactly like `PrismaLike`.
+ */
+export interface KyselyLike {
+    selectFrom(table: string): KyselySelectBuilder;
+    insertInto(table: string): KyselyInsertBuilder;
+    updateTable(table: string): KyselyUpdateBuilder;
+    deleteFrom(table: string): KyselyDeleteBuilder;
+    transaction(): KyselyTransactionBuilder;
+}
+export interface KyselyTransactionBuilder {
+    execute<T>(fn: (trx: KyselyLike) => Promise<T>): Promise<T>;
+}
+export interface KyselySelectBuilder {
+    selectAll(): KyselySelectBuilder;
+    where(column: string, operator: string, value: unknown): KyselySelectBuilder;
+    orderBy(column: string, direction: 'asc' | 'desc'): KyselySelectBuilder;
+    limit(limit: number): KyselySelectBuilder;
+    execute(): Promise<readonly Row[]>;
+}
+export interface KyselyInsertBuilder {
+    values(row: Row): KyselyInsertBuilder;
+    returningAll(): KyselyInsertBuilder;
+    execute(): Promise<readonly Row[]>;
+}
+export interface KyselyUpdateBuilder {
+    set(patch: Row): KyselyUpdateBuilder;
+    where(column: string, operator: string, value: unknown): KyselyUpdateBuilder;
+    returningAll(): KyselyUpdateBuilder;
+    execute(): Promise<readonly Row[]>;
+}
+export interface KyselyDeleteBuilder {
+    where(column: string, operator: string, value: unknown): KyselyDeleteBuilder;
+    returningAll(): KyselyDeleteBuilder;
+    execute(): Promise<readonly Row[]>;
+}
+export declare function kyselyDataSource<S extends SchemaRecord>(db: KyselyLike, schema: Schema<S>): DataSourceAdapter;