@abloatai/ablo 0.9.2 → 0.9.4

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;

package/dist/source/adapters/kysely.js

@@ -0,0 +1,210 @@
+/**
+ * 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 { AbloValidationError } from '../../errors.js';
+import { outboxEventSchema } from '../contract.js';
+import { adapterTableMigrations } from '../migrations.js';
+import { toSchemaJSON } from '../../schema/serialize.js';
+import { camelToSnake, snakeToCamel } from '../../schema/ddl.js';
+import { tenancyColumn } from '../../schema/tenancy.js';
+function rowId(op) {
+    const id = op.id ?? op.input?.id;
+    if (typeof id !== 'string' || id.length === 0) {
+        throw new AbloValidationError(`operation on "${op.model}" requires an id`, {
+            code: 'source_operation_id_required',
+        });
+    }
+    return id;
+}
+function buildColumnMaps(schema) {
+    const json = toSchemaJSON(schema);
+    const out = new Map();
+    for (const [key, model] of Object.entries(json.models)) {
+        const fieldToColumn = new Map();
+        const columnToField = new Map();
+        const register = (field, column) => {
+            if (column === camelToSnake(field))
+                return;
+            fieldToColumn.set(field, column);
+            columnToField.set(column, field);
+        };
+        for (const [field, meta] of Object.entries(model.fields)) {
+            if (meta.column)
+                register(field, meta.column);
+        }
+        const orgColumn = tenancyColumn(model.tenancy);
+        if (orgColumn)
+            register('organizationId', orgColumn);
+        out.set(key, { table: model.tableName ?? key, fieldToColumn, columnToField });
+    }
+    return out;
+}
+export function kyselyDataSource(db, schema) {
+    const maps = buildColumnMaps(schema);
+    const modelColumns = (model) => {
+        const mc = maps.get(model);
+        if (!mc) {
+            throw new AbloValidationError(`kyselyDataSource: no model "${model}" in schema`, {
+                code: 'source_adapter_misconfigured',
+            });
+        }
+        return mc;
+    };
+    const columnFor = (mc, field) => mc.fieldToColumn.get(field) ?? camelToSnake(field);
+    const fieldFor = (mc, column) => mc.columnToField.get(column) ?? snakeToCamel(column);
+    /** Field-keyed (SDK shape) → column-keyed (physical), for INSERT/UPDATE. */
+    const toColumns = (mc, row) => {
+        const out = {};
+        for (const k of Object.keys(row))
+            out[columnFor(mc, k)] = row[k];
+        return out;
+    };
+    /** Column-keyed (RETURNING * / SELECT *) → field-keyed (SDK shape). */
+    const toFields = (mc, row) => {
+        const out = {};
+        for (const k of Object.keys(row))
+            out[fieldFor(mc, k)] = row[k];
+        return out;
+    };
+    const applyOperation = async (trx, op) => {
+        const mc = modelColumns(op.model);
+        const id = rowId(op);
+        const input = op.input ?? {};
+        if (op.type === 'DELETE') {
+            const deleted = await trx
+                .deleteFrom(mc.table)
+                .where('id', '=', id)
+                .returningAll()
+                .execute();
+            return deleted[0] ? toFields(mc, deleted[0]) : { id };
+        }
+        if (op.type === 'CREATE') {
+            const inserted = await trx
+                .insertInto(mc.table)
+                .values(toColumns(mc, { id, ...input }))
+                .returningAll()
+                .execute();
+            return inserted[0] ? toFields(mc, inserted[0]) : { id, ...input };
+        }
+        // UPDATE / ARCHIVE / UNARCHIVE — the lifecycle field is `archivedAt`
+        // (camelCase) and goes through `toColumns` like any other, so it lands in
+        // `archived_at` — the same column the provisioner emits.
+        const patch = toColumns(mc, {
+            ...input,
+            ...(op.type === 'ARCHIVE' ? { archivedAt: new Date() } : {}),
+            ...(op.type === 'UNARCHIVE' ? { archivedAt: null } : {}),
+        });
+        const updated = await trx
+            .updateTable(mc.table)
+            .set(patch)
+            .where('id', '=', id)
+            .returningAll()
+            .execute();
+        return updated[0] ? toFields(mc, updated[0]) : { id, ...input };
+    };
+    return {
+        capabilities: { transactions: true, propose: false, schemaIntrospection: true },
+        migrations() {
+            return adapterTableMigrations();
+        },
+        async read(req) {
+            const mc = modelColumns(req.model);
+            if (req.kind === 'load') {
+                const rows = await db
+                    .selectFrom(mc.table)
+                    .selectAll()
+                    .where('id', '=', req.id)
+                    .limit(1)
+                    .execute();
+                return rows.map((r) => toFields(mc, r));
+            }
+            const limit = req.query?.limit ?? 1000;
+            const rows = await db.selectFrom(mc.table).selectAll().limit(limit).execute();
+            return rows.map((r) => toFields(mc, r));
+        },
+        async commit(change) {
+            return db.transaction().execute(async (trx) => {
+                const cached = await trx
+                    .selectFrom('ablo_idempotency')
+                    .selectAll()
+                    .where('client_tx_id', '=', change.clientTxId)
+                    .limit(1)
+                    .execute();
+                if (cached.length > 0) {
+                    const response = cached[0].response;
+                    return {
+                        rows: (typeof response === 'string' ? JSON.parse(response) : response),
+                    };
+                }
+                const rows = [];
+                for (const [index, op] of change.operations.entries()) {
+                    const row = await applyOperation(trx, op);
+                    rows.push(row);
+                    const entityId = String(row.id ?? rowId(op));
+                    await trx
+                        .insertInto('ablo_outbox')
+                        .values({
+                        id: `${change.clientTxId}:${index}`,
+                        model: op.model,
+                        entity_id: entityId,
+                        type: op.type,
+                        data: op.type === 'DELETE' ? null : JSON.stringify(row),
+                        client_tx_id: change.clientTxId,
+                        occurred_at: Date.now(),
+                    })
+                        .execute();
+                }
+                await trx
+                    .insertInto('ablo_idempotency')
+                    .values({ client_tx_id: change.clientTxId, response: JSON.stringify(rows) })
+                    .execute();
+                return { rows };
+            });
+        },
+        async events(cursor, limit) {
+            const after = cursor ?? '0';
+            const rows = await db
+                .selectFrom('ablo_outbox')
+                .selectAll()
+                .where('cursor', '>', after)
+                .orderBy('cursor', 'asc')
+                .limit(limit)
+                .execute();
+            const events = rows.map((r) => outboxEventSchema.parse({
+                id: r.id,
+                model: r.model,
+                entityId: r.entity_id,
+                type: r.type,
+                data: typeof r.data === 'string' ? JSON.parse(r.data) : r.data ?? null,
+                organizationId: r.organization_id ?? null,
+                clientTxId: r.client_tx_id ?? null,
+                occurredAt: r.occurred_at != null ? Number(r.occurred_at) : null,
+                cursor: String(r.cursor),
+            }));
+            return { events, nextCursor: events.length > 0 ? events[events.length - 1].cursor : null };
+        },
+    };
+}

package/dist/source/adapters/memory.js

@@ -8,10 +8,11 @@
  * It models the real semantics minimally but faithfully: one canonical row store
  * per model, an idempotency ledger keyed by `clientTxId`, and a monotonic outbox.
  */
+import { AbloValidationError } from '../../errors.js';
 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;
 }

package/dist/source/adapters/prisma.js

@@ -12,6 +12,7 @@
  * (`PrismaLike`), so this compiles in the SDK package and is unit-testable with
  * a fake, while a real `PrismaClient` satisfies it at the call site.
  */
+import { AbloValidationError } from '../../errors.js';
 import { outboxEventSchema } from '../contract.js';
 import { adapterTableMigrations } from '../migrations.js';
 const lowerFirst = (s) => (s ? s[0].toLowerCase() + s.slice(1) : s);
@@ -32,7 +33,7 @@ const lowerFirst = (s) => (s ? s[0].toLowerCase() + s.slice(1) : s);
 function delegateFor(client, name) {
     const delegate = client[name];
     if (!delegate || typeof delegate.findMany !== 'function') {
-        throw new Error(`prismaDataSource: no Prisma delegate "${name}" on the client`);
+        throw new AbloValidationError(`prismaDataSource: no Prisma delegate "${name}" on the client`, { code: 'source_adapter_misconfigured' });
     }
     return delegate;
 }
@@ -97,7 +98,7 @@ function findManyArgs(query) {
 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;
 }

package/dist/source/index.js

@@ -1,3 +1,4 @@
+import { AbloValidationError } from '../errors.js';
 import { changeSetSchema } from './contract.js';
 /**
  * Build the source-event marker customers should write to their outbox table in
@@ -10,7 +11,7 @@ import { changeSetSchema } from './contract.js';
 export function sourceEventForOperation(options) {
     const entityId = options.entityId ?? options.operation.id;
     if (typeof entityId !== 'string' || entityId.length === 0) {
-        throw new Error('sourceEventForOperation requires operation.id or an explicit entityId');
+        throw new AbloValidationError('sourceEventForOperation requires operation.id or an explicit entityId', { code: 'source_event_invalid' });
     }
     const occurredAt = normalizeEventOccurredAt(options.occurredAt);
     return {

package/dist/sync/syncPosition.d.ts

@@ -0,0 +1,78 @@
+/**
+ * THE sync-position structure — one typed object for "where is this client
+ * in the global delta order", replacing five scattered private counters
+ * (`lastSeenSyncId` on the queue, `highestProcessedSyncId` + `lastAckedId`
+ * on the store, ad-hoc acked watermarks, `max()` calls at snapshot sites).
+ *
+ * Three facts with DIFFERENT advance disciplines — flattening them was the
+ * historical bug source, so the structure models them explicitly:
+ *
+ *   - `persisted` — the resume/ack cursor. Advances ONLY after deltas have
+ *     committed to IndexedDB (the Replicache "lastMutationID read in the
+ *     same transaction as the client view" rule — see SyncWebSocket.sendAck).
+ *     This is what reconnect catch-up sends; it must never run ahead of
+ *     durable state or the server skips deltas that never landed.
+ *
+ *   - `applied` — the in-memory cursor: the last delta APPLIED to the
+ *     object pool. Drives delta dedup/replay guards. May run ahead of
+ *     `persisted` (pool applies before the IDB flush) and behind receipt
+ *     (bootstrap-queued deltas are received but not yet applied).
+ *
+ *   - `acked` — the highest server watermark ACKED to this client's OWN
+ *     commits. An ack at N means the server applied our write at N; the
+ *     optimistic pool already reflects it, so for entities we wrote we have
+ *     logically read through N even before the stream echo arrives.
+ *
+ * One derived read: `readFloor` = max(applied, acked) — the ONLY value
+ * snapshots/claims may stamp as `readAt`. The bare stream cursor made a
+ * claim taken right after an ack-confirmed write stale against that write's
+ * own delta; the bare ack would be wrong for read-only clients. Per-entity
+ * correct: a foreign change to an entity we just wrote necessarily lands
+ * ABOVE our ack and still stale-rejects.
+ *
+ * The Zod schema IS the state shape — the class holds exactly one
+ * `SyncPositionSnapshot` and applies monotonic merges to it, so
+ * snapshot/restore are identity-shaped and the schema is the single gate
+ * for anything loaded from disk (`parseSyncPosition`; a corrupted stored
+ * cursor "ahead of reality" is an existing, known failure mode).
+ */
+import { z } from 'zod';
+export declare const syncPositionSchema: z.ZodObject<{
+    persisted: z.ZodNumber;
+    applied: z.ZodNumber;
+    acked: z.ZodNumber;
+}, z.core.$strip>;
+export type SyncPositionSnapshot = z.infer<typeof syncPositionSchema>;
+/**
+ * PERSISTENCE DESIGN: only the `persisted` cursor is stored durably (as
+ * `WorkspaceMetadata.lastSyncId`, written by Database after each IDB delta
+ * commit and gated on load through `syncPositionSchema.shape.persisted` in
+ * `Database.requiredBootstrap`). Persisting `applied`/`acked` would be
+ * meaningless: on resume the pool is rebuilt FROM the persisted state, so
+ * the correct restore is exactly `advancePersisted(storedCursor)` — which
+ * implies `applied`, while `acked` starts at 0 (a dead session's acks carry
+ * no read authority; the offline queue re-acks its own replays).
+ */
+/** Validate a persisted/foreign value into a position snapshot. */
+export declare function parseSyncPosition(value: unknown): SyncPositionSnapshot | null;
+/** The live position. One instance per client (owned by SyncClient); the
+ *  three producers advance their own fact, consumers read. */
+export declare class SyncPosition {
+    #private;
+    /** Current state — the schema shape, frozen-by-copy. */
+    snapshot(): SyncPositionSnapshot;
+    get persisted(): number;
+    get applied(): number;
+    get acked(): number;
+    /** THE value snapshots/claims stamp as `readAt`. */
+    get readFloor(): number;
+    /** Deltas through `syncId` have COMMITTED to IndexedDB. Persisting
+     *  implies applied — the flush path applies before/with persisting. */
+    advancePersisted(syncId: number): void;
+    /** A delta was APPLIED to the in-memory pool. */
+    advanceApplied(syncId: number): void;
+    /** The server acked one of OUR commits at this watermark. */
+    noteAck(lastSyncId: number | undefined): void;
+    /** Restore from a VALIDATED snapshot (e.g. IDB resume). Monotonic. */
+    restore(snapshot: SyncPositionSnapshot): void;
+}

package/dist/sync/syncPosition.js

@@ -0,0 +1,111 @@
+/**
+ * THE sync-position structure — one typed object for "where is this client
+ * in the global delta order", replacing five scattered private counters
+ * (`lastSeenSyncId` on the queue, `highestProcessedSyncId` + `lastAckedId`
+ * on the store, ad-hoc acked watermarks, `max()` calls at snapshot sites).
+ *
+ * Three facts with DIFFERENT advance disciplines — flattening them was the
+ * historical bug source, so the structure models them explicitly:
+ *
+ *   - `persisted` — the resume/ack cursor. Advances ONLY after deltas have
+ *     committed to IndexedDB (the Replicache "lastMutationID read in the
+ *     same transaction as the client view" rule — see SyncWebSocket.sendAck).
+ *     This is what reconnect catch-up sends; it must never run ahead of
+ *     durable state or the server skips deltas that never landed.
+ *
+ *   - `applied` — the in-memory cursor: the last delta APPLIED to the
+ *     object pool. Drives delta dedup/replay guards. May run ahead of
+ *     `persisted` (pool applies before the IDB flush) and behind receipt
+ *     (bootstrap-queued deltas are received but not yet applied).
+ *
+ *   - `acked` — the highest server watermark ACKED to this client's OWN
+ *     commits. An ack at N means the server applied our write at N; the
+ *     optimistic pool already reflects it, so for entities we wrote we have
+ *     logically read through N even before the stream echo arrives.
+ *
+ * One derived read: `readFloor` = max(applied, acked) — the ONLY value
+ * snapshots/claims may stamp as `readAt`. The bare stream cursor made a
+ * claim taken right after an ack-confirmed write stale against that write's
+ * own delta; the bare ack would be wrong for read-only clients. Per-entity
+ * correct: a foreign change to an entity we just wrote necessarily lands
+ * ABOVE our ack and still stale-rejects.
+ *
+ * The Zod schema IS the state shape — the class holds exactly one
+ * `SyncPositionSnapshot` and applies monotonic merges to it, so
+ * snapshot/restore are identity-shaped and the schema is the single gate
+ * for anything loaded from disk (`parseSyncPosition`; a corrupted stored
+ * cursor "ahead of reality" is an existing, known failure mode).
+ */
+import { z } from 'zod';
+export const syncPositionSchema = z.object({
+    /** Resume/ack cursor — advances only after IDB persistence. */
+    persisted: z.number().int().nonnegative(),
+    /** In-memory cursor — last delta applied to the pool. */
+    applied: z.number().int().nonnegative(),
+    /** Highest server watermark acked to this client's own commits. */
+    acked: z.number().int().nonnegative(),
+});
+/**
+ * PERSISTENCE DESIGN: only the `persisted` cursor is stored durably (as
+ * `WorkspaceMetadata.lastSyncId`, written by Database after each IDB delta
+ * commit and gated on load through `syncPositionSchema.shape.persisted` in
+ * `Database.requiredBootstrap`). Persisting `applied`/`acked` would be
+ * meaningless: on resume the pool is rebuilt FROM the persisted state, so
+ * the correct restore is exactly `advancePersisted(storedCursor)` — which
+ * implies `applied`, while `acked` starts at 0 (a dead session's acks carry
+ * no read authority; the offline queue re-acks its own replays).
+ */
+/** Validate a persisted/foreign value into a position snapshot. */
+export function parseSyncPosition(value) {
+    const result = syncPositionSchema.safeParse(value);
+    return result.success ? result.data : null;
+}
+const ZERO = { persisted: 0, applied: 0, acked: 0 };
+/** Monotonic merge: each cursor only ever moves forward. */
+function advance(state, next) {
+    return {
+        persisted: Math.max(state.persisted, next.persisted ?? 0),
+        applied: Math.max(state.applied, next.applied ?? 0),
+        acked: Math.max(state.acked, next.acked ?? 0),
+    };
+}
+/** The live position. One instance per client (owned by SyncClient); the
+ *  three producers advance their own fact, consumers read. */
+export class SyncPosition {
+    #state = ZERO;
+    /** Current state — the schema shape, frozen-by-copy. */
+    snapshot() {
+        return { ...this.#state };
+    }
+    get persisted() {
+        return this.#state.persisted;
+    }
+    get applied() {
+        return this.#state.applied;
+    }
+    get acked() {
+        return this.#state.acked;
+    }
+    /** THE value snapshots/claims stamp as `readAt`. */
+    get readFloor() {
+        return Math.max(this.#state.applied, this.#state.acked);
+    }
+    /** Deltas through `syncId` have COMMITTED to IndexedDB. Persisting
+     *  implies applied — the flush path applies before/with persisting. */
+    advancePersisted(syncId) {
+        this.#state = advance(this.#state, { persisted: syncId, applied: syncId });
+    }
+    /** A delta was APPLIED to the in-memory pool. */
+    advanceApplied(syncId) {
+        this.#state = advance(this.#state, { applied: syncId });
+    }
+    /** The server acked one of OUR commits at this watermark. */
+    noteAck(lastSyncId) {
+        if (lastSyncId !== undefined)
+            this.#state = advance(this.#state, { acked: lastSyncId });
+    }
+    /** Restore from a VALIDATED snapshot (e.g. IDB resume). Monotonic. */
+    restore(snapshot) {
+        this.#state = advance(this.#state, snapshot);
+    }
+}

package/dist/transactions/TransactionQueue.d.ts

@@ -10,7 +10,8 @@
 import { EventEmitter } from 'events';
 import type { Database } from '../Database.js';
 import { Model } from '../Model.js';
-import type { MutationOptions } from '../interfaces/index.js';
+import { SyncPosition } from '../sync/syncPosition.js';
+import type { WriteOptions } from '../interfaces/index.js';
 export interface UserContext {
     userId: string;
     organizationId: string;
@@ -19,7 +20,6 @@ export interface UserContext {
 }
 /** Wire-format mutation payload (post-projection). */
 type MutationInput = Record<string, unknown>;
-type TransactionWriteOptions = Pick<MutationOptions, 'readAt' | 'onStale'>;
 export interface Transaction {
     id: string;
     type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
@@ -34,7 +34,7 @@ export interface Transaction {
     attempts: number;
     priority: 'normal' | 'high';
     priorityScore: number;
-    writeOptions?: TransactionWriteOptions;
+    writeOptions?: WriteOptions;
     batchId?: string;
     /** LINEAR PATTERN: syncId threshold - transaction confirms when delta.id >= this value */
     syncIdNeededForCompletion?: number;
@@ -83,6 +83,8 @@ interface ConflictResolution {
     resolver?: (local: MutationInput | undefined, remote: MutationInput) => MutationInput;
 }
 interface TransactionQueueConfig {
+    /** Shared client position (see sync/syncPosition.ts). One per client. */
+    position?: SyncPosition;
     maxBatchSize: number;
     batchDelay: number;
     maxRetries: number;
@@ -141,7 +143,17 @@ export declare class TransactionQueue extends EventEmitter {
     private deltaConfirmationRetries;
     private isConnectedFn;
     private commitOfflineGraceTimer;
-    private lastSeenSyncId;
+    /**
+     * THE client's place in the global delta order — the SHARED instance
+     * (injected by SyncClient; standalone construction gets its own). The
+     * queue advances `acked` on commit responses; the store advances
+     * `applied`/`persisted`; snapshots/claims read `readFloor`. Contract +
+     * rationale live in `sync/syncPosition.ts`.
+     */
+    readonly position: SyncPosition;
+    /** Applied-cursor alias, kept so the many internal read sites stay legible. */
+    private get lastSeenSyncId();
+    private noteAck;
     private static readonly DELTA_MAX_RETRIES;
     private static readonly DELTA_INITIAL_TIMEOUT_MS;
     private static readonly DELTA_MAX_TIMEOUT_MS;
@@ -237,16 +249,16 @@ export declare class TransactionQueue extends EventEmitter {
     /**
      * Create operation with optimistic update
      */
-    create(model: Model, context: UserContext, writeOptions?: TransactionWriteOptions): Promise<Transaction>;
+    create(model: Model, context: UserContext, writeOptions?: WriteOptions): Promise<Transaction>;
     /**
      * Update operation with conflict detection
      * @param precomputedChanges - Optional pre-captured changes (avoids re-reading from model)
      */
-    update(model: Model, context: UserContext, precomputedChanges?: Record<string, unknown>, writeOptions?: TransactionWriteOptions): Promise<Transaction>;
+    update(model: Model, context: UserContext, precomputedChanges?: Record<string, unknown>, writeOptions?: WriteOptions): Promise<Transaction>;
     /**
      * Delete operation with cascade handling
      */
-    delete(model: Model, context: UserContext, writeOptions?: TransactionWriteOptions): Promise<Transaction>;
+    delete(model: Model, context: UserContext, writeOptions?: WriteOptions): Promise<Transaction>;
     /**
      * Upload attachment — delegates to attachment-uploader.ts
      */
@@ -269,7 +281,7 @@ export declare class TransactionQueue extends EventEmitter {
     /**
      * Archive operation
      */
-    archive(model: Model, context: UserContext, writeOptions?: TransactionWriteOptions): Promise<Transaction>;
+    archive(model: Model, context: UserContext, writeOptions?: WriteOptions): Promise<Transaction>;
     /**
      * Unarchive operation
      */
@@ -415,6 +427,8 @@ export declare class TransactionQueue extends EventEmitter {
         totalTransactions: number;
         batchIndex: number;
         config: {
+            /** Shared client position (see sync/syncPosition.ts). One per client. */
+            position?: SyncPosition;
             maxBatchSize: number;
             batchDelay: number;
             maxRetries: number;