@abloatai/ablo 0.9.1 → 0.9.3

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;
@@ -46,6 +53,15 @@ export class UndoScope {
      * observer can never wedge the editor's recording path.
      */
     recordListeners = new Set();
+    /**
+     * 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.
+     */
+    changeListeners = new Set();
     /**
      * Serialization tail. Recording, undo, and redo all chain off this single
      * promise so they run strictly in the order they were *invoked* — never
@@ -83,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;
@@ -141,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) ??
@@ -160,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);
@@ -246,6 +360,7 @@ export class UndoScope {
             this.undoStack.shift();
         this.redoStack = [];
         this.emitRecord(entry);
+        this.emitChange();
     }
     /**
      * Subscribe to every recorded mutation. Fires synchronously at the tail of
@@ -275,6 +390,30 @@ export class UndoScope {
             }
         }
     }
+    /**
+     * 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) {
+        this.changeListeners.add(listener);
+        return () => {
+            this.changeListeners.delete(listener);
+        };
+    }
+    emitChange() {
+        for (const listener of this.changeListeners) {
+            try {
+                listener();
+            }
+            catch (err) {
+                if (typeof console !== 'undefined') {
+                    console.error('[UndoScope] onChange listener threw', err);
+                }
+            }
+        }
+    }
     canUndo() {
         return this.undoStack.length > 0;
     }
@@ -297,17 +436,29 @@ 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);
             }
+            catch (err) {
+                // The replay was rejected (e.g. a server 409): the world didn't change,
+                // so restore the entry to the undo stack rather than silently dropping
+                // it (which would also strand it off the redo stack — invisible undo).
+                this.undoStack.push(entry);
+                this.emitChange();
+                throw err;
+            }
             finally {
                 this.replaying = false;
             }
             this.redoStack.push(entry);
             if (this.redoStack.length > this.maxHistory)
                 this.redoStack.shift();
+            this.emitChange();
         });
     }
     /**
@@ -323,16 +474,26 @@ 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);
             }
+            catch (err) {
+                // Symmetric to undo: a rejected re-apply leaves state unchanged, so put
+                // the entry back on the redo stack instead of losing it.
+                this.redoStack.push(entry);
+                this.emitChange();
+                throw err;
+            }
             finally {
                 this.replaying = false;
             }
             this.undoStack.push(entry);
             if (this.undoStack.length > this.maxHistory)
                 this.undoStack.shift();
+            this.emitChange();
         });
     }
     /** Drop all history. Use after bootstrap / sync group change / sync error. */
@@ -340,6 +501,8 @@ export class UndoScope {
         this.undoStack = [];
         this.redoStack = [];
         this.batch = [];
+        this.pendingReplayEchoes.clear();
+        this.emitChange();
     }
     /** Introspection — for debug panels / e2e tests. */
     size() {
@@ -353,7 +516,9 @@ export class UndoScope {
     dispose() {
         this.unsubscribe();
         this.recordListeners.clear();
+        this.changeListeners.clear();
         this.batch = [];
+        this.pendingReplayEchoes.clear();
     }
 }
 /**

package/dist/react/AbloProvider.d.ts

@@ -28,20 +28,30 @@ import { type SyncStoreContract } from './context.js';
 /**
  * Props for `<AbloProvider>`.
  *
- * The default path is one prop:
+ * The one required prop is a prebuilt {@link Ablo} client — the client
+ * owns auth and the credential lifecycle; this provider is the reactive
+ * binding over it (Stripe's `<Elements stripe={...}>` model):
  *
  * ```tsx
- * <AbloProvider schema={schema}>
+ * // Build once at module scope — a new instance per render tears down the socket.
+ * const ablo = Ablo({
+ *   schema,
+ *   getToken: () =>
+ *     fetch('/api/ablo-session', { method: 'POST' })
+ *       .then((r) => r.json())
+ *       .then((d) => d.token),
+ * });
+ *
+ * <AbloProvider client={ablo}>
  *   <App />
  * </AbloProvider>
  * ```
  *
- * That's it for most apps — the provider resolves identity, account
- * scope, and realtime permissions from auth. `userId`/`apiKey`/`url`
- * are situational; the `bootstrapMode`, `persistence`, and `fallback`
- * props are opt-in tuning; and the block tagged "Optional DI (advanced)"
- * below is escape-hatch wiring for tests and platform builders — if you
- * don't recognize a prop there, you don't need it.
+ * That's it for most apps. `userId` is informational; the `fallback`,
+ * `preventUnsavedChanges`, and `on*` props are opt-in app glue; and the
+ * block tagged "Optional DI (advanced)" below is escape-hatch wiring for
+ * tests and platform builders — if you don't recognize a prop there, you
+ * don't need it.
  */
 export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
     /**

package/dist/react/index.d.ts

@@ -27,7 +27,7 @@
  *   useCurrentUserId()        — the provider's userId prop
  *
  * Multiplayer (always available — `<AbloProvider>` always constructs a client):
- *   useAblo((ablo) => ablo.intents.list(...)) — reactive coordination reads
+ *   useAblo((ablo) => ablo.<model>.claim.state(...)) — reactive coordination reads
  *   useParticipant({ scope }) — join multiplayer for a scope, get peers/claims
  *   usePresence()             — typed presence view
  *   useIntent(name)           — typed intent dispatcher

package/dist/react/index.js

@@ -27,7 +27,7 @@
  *   useCurrentUserId()        — the provider's userId prop
  *
  * Multiplayer (always available — `<AbloProvider>` always constructs a client):
- *   useAblo((ablo) => ablo.intents.list(...)) — reactive coordination reads
+ *   useAblo((ablo) => ablo.<model>.claim.state(...)) — reactive coordination reads
  *   useParticipant({ scope }) — join multiplayer for a scope, get peers/claims
  *   usePresence()             — typed presence view
  *   useIntent(name)           — typed intent dispatcher

package/dist/react/useUndoScope.js

@@ -52,6 +52,13 @@ export function useUndoScope(schemaOrName, nameOrOptions, maybeOptions) {
     useEffect(() => {
         setTick(0);
     }, [scope]);
+    // Re-render on ANY stack change — including entries recorded from the local-
+    // mutation stream, which don't otherwise trigger a React update. Without this
+    // `canUndo`/`canRedo` go stale in every consumer that didn't itself call
+    // undo/redo (e.g. a keyboard handler whose Cmd+Z gate then never fires).
+    useEffect(() => {
+        return scope.onChange(() => setTick((t) => t + 1));
+    }, [scope]);
     const size = scope.size();
     return {
         scope,

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/commit.d.ts

@@ -61,11 +61,10 @@ export interface CommitContext {
      */
     confirmationState?: ConfirmationState;
     /**
-     * FK to AgentTurn.id. Pinned at turn open by `SyncAgent.beginTurn`, threaded
-     * through the wire frame's `causedByTaskId`, validated by the commit handler
-     * (turn must belong to the same agent and be open), and written onto every
-     * delta this batch produces. Absent for human-direct commits and SDKs that
-     * predate the turn protocol (→ `caused_by_task_id = NULL`).
+     * Dormant FK to the agent-task id (`agent_tasks.id`). The SDK no longer
+     * sets it (turns/tasks removed; attribution rides on the claim/intent id
+     * + server-stamped actor/capability). Still validated + written onto
+     * `caused_by_task_id` when present, but client writes leave it `null`.
      */
     causedByTaskId?: string | null;
 }

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;