@convex-localfirst/core 0.1.0

package/dist/relations.js

@@ -0,0 +1,89 @@
+/** base[foreignKey] === target._id. Returns the single target (or undefined). */
+export function one(table, foreignKey) {
+    return { kind: "one", table, foreignKey };
+}
+/** target[foreignKey] === base._id. Returns the matching targets as an array. */
+export function many(table, foreignKey) {
+    return { kind: "many", table, foreignKey };
+}
+/** base._id -> through[localKey], through[targetKey] -> target._id. Returns targets. */
+export function manyToMany(table, through, localKey, targetKey) {
+    return { kind: "manyToMany", table, through, localKey, targetKey, foreignKey: "" };
+}
+/** Every table a set of relations reads from (targets + join tables). */
+export function relationTables(relations) {
+    const tables = new Set();
+    for (const { spec } of relations) {
+        tables.add(spec.table);
+        if (spec.through) {
+            tables.add(spec.through);
+        }
+    }
+    return [...tables];
+}
+/**
+ * Attach related rows to each base row, in memory. `rowsByTable` must hold every
+ * relation's target (and `through`) table. Each relation is indexed once, so the
+ * whole attach is O(base + targets), not O(base × targets). Pure.
+ */
+export function attachRelations(baseRows, relations, rowsByTable) {
+    if (relations.length === 0) {
+        // No relations: hand back the same rows (and their identities) so the React
+        // hook's stable-reference optimization holds for the common case.
+        return baseRows;
+    }
+    const resolvers = relations.map(({ name, spec }) => {
+        const targets = rowsByTable[spec.table] ?? [];
+        if (spec.kind === "one") {
+            const byId = new Map(targets.map((t) => [t._id, t]));
+            return { name, resolve: (row) => byId.get(row[spec.foreignKey]) };
+        }
+        if (spec.kind === "many") {
+            const byFk = groupBy(targets, (t) => t[spec.foreignKey]);
+            return { name, resolve: (row) => byFk.get(row._id) ?? [] };
+        }
+        // manyToMany
+        const through = rowsByTable[spec.through] ?? [];
+        const targetIdsByLocal = new Map();
+        for (const link of through) {
+            const localId = link[spec.localKey];
+            let set = targetIdsByLocal.get(localId);
+            if (!set) {
+                set = new Set();
+                targetIdsByLocal.set(localId, set);
+            }
+            set.add(link[spec.targetKey]);
+        }
+        const byId = new Map(targets.map((t) => [t._id, t]));
+        return {
+            name,
+            resolve: (row) => {
+                const ids = targetIdsByLocal.get(row._id);
+                if (!ids) {
+                    return [];
+                }
+                return [...ids].map((id) => byId.get(id)).filter((t) => t !== undefined);
+            }
+        };
+    });
+    return baseRows.map((row) => {
+        const out = { ...row };
+        for (const { name, resolve } of resolvers) {
+            out[name] = resolve(row);
+        }
+        return out;
+    });
+}
+function groupBy(rows, key) {
+    const map = new Map();
+    for (const row of rows) {
+        const k = key(row);
+        let bucket = map.get(k);
+        if (!bucket) {
+            bucket = [];
+            map.set(k, bucket);
+        }
+        bucket.push(row);
+    }
+    return map;
+}

package/dist/setMerge.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Set-field merge: convergent add/remove for array fields declared as sets (e.g.
+ * `label_ids`). A set-field patch is recorded as an add/remove DELTA (vs the value the
+ * client saw); merge applies `(current ∪ add) \ remove` on both client replay and server,
+ * so concurrent adds/removes to different elements all survive instead of LWW-clobbering.
+ * Delta-based grow/shrink set (not a tagged OR-Set): concurrent add+remove of the SAME
+ * element is a genuine conflict resolved by apply order.
+ */
+/** A patch field carrying a set delta instead of a replacement value. */
+export type SetDelta = {
+    readonly __lfSet: {
+        readonly add: readonly unknown[];
+        readonly remove: readonly unknown[];
+    };
+};
+/**
+ * Counter-field merge: convergent add/subtract for numeric fields declared as counters
+ * (e.g. `vote_count`). A counter-field patch is recorded as a numeric DELTA (vs the value
+ * the client saw); merge ADDS deltas on both client replay and server, so concurrent
+ * increments accumulate instead of LWW-clobbering. Convergent because addition commutes,
+ * so no baseVersion is needed. A counter delta over a non-number field is rejected.
+ */
+export type CounterDelta = {
+    readonly __lfCounter: number;
+};
+export declare function isCounterDelta(value: unknown): value is CounterDelta;
+/** The delta that turns `current` into `next` as a counter: `next - current` (absent/
+ *  non-number current counts as 0). The app patches with the whole intended number; this
+ *  derives the increment so concurrent edits accumulate instead of clobbering. */
+export declare function computeCounterDelta(current: unknown, next: number): number;
+/** Apply a counter delta: `(current ?? 0) + delta`. Absent/non-number current counts as 0.
+ *  Commutative + associative, so applying deltas in any order converges. */
+export declare function applyCounterDelta(current: unknown, delta: number): number;
+/**
+ * Timestamp-ordered last-writer-wins for a scalar field (an LWW-register). A field write
+ * carries the originating op's logical timestamp + a stable tiebreaker (the clientId); the
+ * write with the higher `(ts, tiebreaker)` WINS, deterministically and regardless of the
+ * order writes arrive at the server. This fixes the offline-first hazard that plain
+ * arrival-order LWW has — an OLDER edit that syncs LATER must NOT overwrite a NEWER one.
+ *
+ * Provably convergent: `(ts, tiebreaker)` is a total order, so all replicas pick the same
+ * winner no matter the apply order. The tiebreaker breaks equal-timestamp ties (lexicographic
+ * on the clientId string) so two truly-concurrent writes still resolve deterministically.
+ */
+export type FieldClock = {
+    readonly ts: number;
+    readonly tiebreaker: string;
+};
+/** True if an incoming write `(ts, tiebreaker)` beats the current field clock (absent = wins). */
+export declare function lwwWins(incoming: FieldClock, current: FieldClock | undefined): boolean;
+export declare function isSetDelta(value: unknown): value is SetDelta;
+/** The delta that turns `current` into `next` as a set: elements in next-not-current are
+ *  adds, elements in current-not-next are removes. Order/duplicates in inputs don't matter. */
+export declare function computeSetDelta(current: unknown, next: readonly unknown[]): SetDelta["__lfSet"];
+/** Apply a set delta to a current value: keep current order, drop removed elements, append
+ *  added elements not already present. Deterministic + idempotent (re-applying is a no-op). */
+export declare function applySetDelta(current: unknown, delta: SetDelta["__lfSet"]): unknown[];
+/**
+ * Merge one patch onto a row: for a field whose patch value is a SetDelta, apply the delta
+ * to the current field value (set merge); every other field overwrites (field-level LWW).
+ * This is the single shared apply rule used by the client view/replay AND the server.
+ */
+export declare function mergePatch<T extends Record<string, unknown>>(current: T, patch: Record<string, unknown>): T;

package/dist/setMerge.js

@@ -0,0 +1,93 @@
+/**
+ * Set-field merge: convergent add/remove for array fields declared as sets (e.g.
+ * `label_ids`). A set-field patch is recorded as an add/remove DELTA (vs the value the
+ * client saw); merge applies `(current ∪ add) \ remove` on both client replay and server,
+ * so concurrent adds/removes to different elements all survive instead of LWW-clobbering.
+ * Delta-based grow/shrink set (not a tagged OR-Set): concurrent add+remove of the SAME
+ * element is a genuine conflict resolved by apply order.
+ */
+export function isCounterDelta(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "__lfCounter" in value &&
+        typeof value.__lfCounter === "number");
+}
+/** The delta that turns `current` into `next` as a counter: `next - current` (absent/
+ *  non-number current counts as 0). The app patches with the whole intended number; this
+ *  derives the increment so concurrent edits accumulate instead of clobbering. */
+export function computeCounterDelta(current, next) {
+    return next - (typeof current === "number" ? current : 0);
+}
+/** Apply a counter delta: `(current ?? 0) + delta`. Absent/non-number current counts as 0.
+ *  Commutative + associative, so applying deltas in any order converges. */
+export function applyCounterDelta(current, delta) {
+    return (typeof current === "number" ? current : 0) + delta;
+}
+/** True if an incoming write `(ts, tiebreaker)` beats the current field clock (absent = wins). */
+export function lwwWins(incoming, current) {
+    if (!current)
+        return true;
+    if (incoming.ts !== current.ts)
+        return incoming.ts > current.ts;
+    return incoming.tiebreaker > current.tiebreaker;
+}
+/** Stable identity key for a set element. Strings (the common case: ids) key as-is;
+ *  anything else by JSON so distinct shapes never collide and types don't alias. */
+function keyOf(element) {
+    return typeof element === "string" ? element : JSON.stringify(element);
+}
+export function isSetDelta(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "__lfSet" in value &&
+        typeof value.__lfSet === "object" &&
+        value.__lfSet !== null);
+}
+/** The delta that turns `current` into `next` as a set: elements in next-not-current are
+ *  adds, elements in current-not-next are removes. Order/duplicates in inputs don't matter. */
+export function computeSetDelta(current, next) {
+    const currentArr = Array.isArray(current) ? current : [];
+    const currentKeys = new Set(currentArr.map(keyOf));
+    const nextKeys = new Set(next.map(keyOf));
+    const add = next.filter((el) => !currentKeys.has(keyOf(el)));
+    const remove = currentArr.filter((el) => !nextKeys.has(keyOf(el)));
+    return { add, remove };
+}
+/** Apply a set delta to a current value: keep current order, drop removed elements, append
+ *  added elements not already present. Deterministic + idempotent (re-applying is a no-op). */
+export function applySetDelta(current, delta) {
+    const removeKeys = new Set(delta.remove.map(keyOf));
+    const result = [];
+    const seen = new Set();
+    for (const el of Array.isArray(current) ? current : []) {
+        const k = keyOf(el);
+        if (removeKeys.has(k) || seen.has(k))
+            continue;
+        seen.add(k);
+        result.push(el);
+    }
+    for (const el of delta.add) {
+        const k = keyOf(el);
+        if (removeKeys.has(k) || seen.has(k))
+            continue;
+        seen.add(k);
+        result.push(el);
+    }
+    return result;
+}
+/**
+ * Merge one patch onto a row: for a field whose patch value is a SetDelta, apply the delta
+ * to the current field value (set merge); every other field overwrites (field-level LWW).
+ * This is the single shared apply rule used by the client view/replay AND the server.
+ */
+export function mergePatch(current, patch) {
+    const next = { ...current };
+    for (const [field, value] of Object.entries(patch)) {
+        next[field] = isSetDelta(value)
+            ? applySetDelta(current[field], value.__lfSet)
+            : isCounterDelta(value)
+                ? applyCounterDelta(current[field], value.__lfCounter)
+                : value;
+    }
+    return next;
+}

package/dist/status.d.ts

@@ -0,0 +1,2 @@
+import type { SyncStatus } from "./types.js";
+export declare const initialSyncStatus: SyncStatus;

package/dist/status.js

@@ -0,0 +1,10 @@
+export const initialSyncStatus = {
+    online: true,
+    syncing: false,
+    pendingMutations: 0,
+    lastPushAt: null,
+    lastPullAt: null,
+    lastError: null,
+    blockedBySchemaMismatch: false,
+    partial: false
+};

package/dist/storage.d.ts

@@ -0,0 +1,53 @@
+import type { Cursor, LocalId, LocalOperation, OperationStatus, RowValue, ScopeKey, ServerChange, TableName } from "./types.js";
+export type StoreListener = () => void;
+export type StoreUnsubscribe = () => void;
+/**
+ * Canonical-centric local store.
+ *
+ * Invariant I1: the live view returned by getRows/getRow is ALWAYS derived as
+ * `canonical snapshot + replay(pending ops)`. There is no separately-mutated
+ * "live" row map, so a server change physically cannot clobber a pending local
+ * operation. Local mutations only enqueue operations; the canonical snapshot
+ * only changes through applyServerChange.
+ */
+export type LocalStore = {
+    /**
+     * @internal Derived live view for a table (canonical + replayed pending ops);
+     * includes _deleted rows. The store is a persistence PRIMITIVE for the engine —
+     * its reads are UNSCOPED. App code must read through the React hooks
+     * (useQuery/useLiveQuery), which enforce the scoped fail-closed guard; do not
+     * call getRows/getRow directly to display data.
+     */
+    getRows(table: TableName): Promise<readonly RowValue[]>;
+    getRow(table: TableName, id: LocalId): Promise<RowValue | null>;
+    /** Canonical server snapshot, for inspection/tests. */
+    getCanonicalRows(table: TableName): Promise<readonly RowValue[]>;
+    /** Apply one authoritative server change to the canonical snapshot (and prune a confirmed op). */
+    applyServerChange(change: ServerChange): Promise<void>;
+    /**
+     * Apply a batch of server changes with a SINGLE notify (and, for durable stores,
+     * a single transaction). The hot path for sync pulls: applying N changes one at
+     * a time would fire N notifications — each re-deriving + re-cloning every row in
+     * every mounted query — turning a cold pull into O(N×rows). Order is preserved so
+     * repeated changes to the same row resolve correctly.
+     */
+    applyServerChanges(changes: readonly ServerChange[]): Promise<void>;
+    /** Outbox. */
+    enqueueOperation(operation: LocalOperation): Promise<void>;
+    /** Ops still owed to the server (pending|pushing), ordered deterministically. */
+    getPendingOperations(): Promise<readonly LocalOperation[]>;
+    /** Every op still in the log, for conflict inspection. */
+    getAllOperations(): Promise<readonly LocalOperation[]>;
+    getOperation(opId: string): Promise<LocalOperation | null>;
+    updateOperationStatus(opId: string, status: OperationStatus, error?: string): Promise<void>;
+    /** Remove an op from the outbox. Used for an accepted op that produced NO canonical
+     *  change (an idempotent no-op delete): applyServerChanges only prunes ops a change
+     *  references, so without this the op lingers, replayed forever. */
+    dropOperation(opId: string): Promise<void>;
+    getCursor(scopeKey: ScopeKey): Promise<Cursor>;
+    setCursor(scopeKey: ScopeKey, cursor: string): Promise<void>;
+    /** Drop all data for this namespace (logout). */
+    clear(): Promise<void>;
+    subscribe(listener: StoreListener): StoreUnsubscribe;
+    notify(): void;
+};

package/dist/storage.js

@@ -0,0 +1 @@
+export {};

package/dist/transport.d.ts

@@ -0,0 +1,43 @@
+import type { PullRequest, PullResponse, PushRequest, PushResponse } from "./types.js";
+export type SyncTransport = {
+    push(request: PushRequest): Promise<PushResponse>;
+    pull(request: PullRequest): Promise<PullResponse>;
+    /**
+     * Optional reactive change feed: invoke `onChange` whenever the server has new
+     * changes for `request.scopes` after `request.cursors` (true server push — no
+     * polling). Returns an unsubscribe. `onChange` is a content-free doorbell: the
+     * engine pulls on each fire. Transports without a reactive channel omit this and
+     * the client falls back to polling (`useLiveQuery({ pollMs })`).
+     */
+    subscribe?(request: PullRequest, onChange: () => void): () => void;
+};
+/** A subscription handle from `ConvexReactClient.watchQuery`. Internal — implementation
+ *  shape consumed only by createConvexTransport, not part of the public API. */
+type ConvexWatch = {
+    onUpdate(callback: () => void): () => void;
+};
+/** Minimal Convex client shape. `watchQuery` is present on ConvexReactClient (and
+ *  enables reactive pull); ConvexHttpClient omits it (pull falls back to polling).
+ *  Internal — not part of the public API. */
+type ConvexLikeClient = {
+    mutation(reference: unknown, args: Record<string, unknown>): Promise<unknown>;
+    query(reference: unknown, args: Record<string, unknown>): Promise<unknown>;
+    watchQuery?(reference: unknown, args: Record<string, unknown>): ConvexWatch;
+};
+/**
+ * Adapt a Convex client + the generated sync.push/sync.pull references into the
+ * engine's SyncTransport: serializes local operations, calls Convex, and maps
+ * the server change log back into client ServerChange shape.
+ */
+export declare function createConvexTransport(options: {
+    client: ConvexLikeClient;
+    push: unknown;
+    pull: unknown;
+    clientId: string;
+    userId: string;
+}): SyncTransport;
+export declare class OfflineTransportError extends Error {
+    constructor(message?: string);
+}
+export declare function createOfflineTransport(): SyncTransport;
+export {};

package/dist/transport.js

@@ -0,0 +1,93 @@
+function toClientChange(change) {
+    return {
+        changeId: change.changeId,
+        scopeKey: change.scopeKey,
+        table: change.table,
+        id: change.localId, // the client keys rows by localId
+        kind: change.kind,
+        value: change.data,
+        patch: change.patch,
+        version: change.version,
+        serverTime: change.serverTime,
+        opId: change.opId
+    };
+}
+function scopeValue(key) {
+    const idx = key.indexOf(":");
+    return idx >= 0 ? key.slice(idx + 1) : undefined;
+}
+/**
+ * Adapt a Convex client + the generated sync.push/sync.pull references into the
+ * engine's SyncTransport: serializes local operations, calls Convex, and maps
+ * the server change log back into client ServerChange shape.
+ */
+export function createConvexTransport(options) {
+    return {
+        async push(request) {
+            const response = (await options.client.mutation(options.push, {
+                clientId: options.clientId,
+                userId: options.userId,
+                schemaVersion: request.schemaVersion,
+                mutations: request.mutations.map((op) => ({
+                    opId: op.opId,
+                    clientId: op.clientId,
+                    schemaVersion: op.schemaVersion,
+                    functionName: op.functionName,
+                    table: op.table,
+                    kind: op.kind,
+                    localId: op.id,
+                    value: op.value,
+                    patch: op.patch,
+                    // The op's logical timestamp — consumed only by `timestampLww` tables on the server
+                    // to resolve same-field collisions by recency. Harmless extra field otherwise.
+                    timestamp: op.createdAt
+                }))
+            }));
+            return { ...response, changes: response.changes.map(toClientChange) };
+        },
+        async pull(request) {
+            const response = (await options.client.query(options.pull, {
+                clientId: options.clientId,
+                userId: options.userId,
+                schemaVersion: request.schemaVersion,
+                scopes: request.scopes.map((scope) => ({ kind: scope.kind, value: scopeValue(scope.key) })),
+                cursors: request.cursors
+            }));
+            return { ...response, changes: response.changes.map(toClientChange) };
+        },
+        // Reactive pull: watch the SAME `pull` query (Convex queries are reactive) as a
+        // doorbell. It re-fires whenever a new change lands in these scopes after the
+        // given cursors — the engine then drains via the regular `pull` path. Reuses the
+        // already-audited pull endpoint, so it adds no new server surface (no I7 change).
+        // Only wired when the client is reactive (ConvexReactClient.watchQuery); the
+        // HTTP client omits it and the engine falls back to polling.
+        subscribe: options.client.watchQuery
+            ? (request, onChange) => {
+                const watch = options.client.watchQuery(options.pull, {
+                    clientId: options.clientId,
+                    userId: options.userId,
+                    schemaVersion: request.schemaVersion,
+                    scopes: request.scopes.map((scope) => ({ kind: scope.kind, value: scopeValue(scope.key) })),
+                    cursors: request.cursors
+                });
+                return watch.onUpdate(() => onChange());
+            }
+            : undefined
+    };
+}
+export class OfflineTransportError extends Error {
+    constructor(message = "Local-first transport is offline") {
+        super(message);
+        this.name = "OfflineTransportError";
+    }
+}
+export function createOfflineTransport() {
+    return {
+        async push() {
+            throw new OfflineTransportError();
+        },
+        async pull() {
+            throw new OfflineTransportError();
+        }
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,173 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type TableName = string;
+export type FunctionName = string;
+export type LocalId = string;
+export type ClientId = string;
+export type UserId = string;
+export type ScopeKey = string;
+export type Cursor = string | null;
+export type RowValue = Record<string, unknown> & {
+    _id: LocalId;
+    _table?: TableName;
+    _version?: number;
+    _deleted?: boolean;
+    _pending?: boolean;
+    _conflict?: ConflictInfo;
+};
+export type ConflictInfo = {
+    readonly kind: "serverRejected" | "mergeFailed";
+    readonly message: string;
+    readonly opId?: string;
+    readonly serverVersion?: number;
+};
+export type OperationKind = "insert" | "patch" | "delete";
+export type OperationStatus = "pending" | "pushing" | "acked" | "rejected";
+export type OperationPlan = {
+    readonly kind: "insert";
+    readonly table: TableName;
+    readonly id?: LocalId;
+    readonly value: Record<string, unknown>;
+} | {
+    readonly kind: "patch";
+    readonly table: TableName;
+    readonly id: LocalId;
+    readonly patch: Record<string, unknown>;
+} | {
+    readonly kind: "delete";
+    readonly table: TableName;
+    readonly id: LocalId;
+};
+export type LocalOperation = {
+    readonly opId: string;
+    readonly clientId: ClientId;
+    readonly userId: UserId | null;
+    readonly schemaVersion: number;
+    readonly functionName: FunctionName;
+    readonly table: TableName;
+    readonly kind: OperationKind;
+    readonly id: LocalId;
+    readonly args: JsonValue;
+    readonly value?: Record<string, unknown>;
+    readonly patch?: Record<string, unknown>;
+    readonly baseVersion?: number;
+    readonly createdAt: number;
+    readonly status: OperationStatus;
+    readonly error?: string;
+};
+export type ServerChangeKind = "insert" | "patch" | "delete" | "replace";
+export type ServerChange = {
+    readonly changeId: string;
+    readonly scopeKey: ScopeKey;
+    readonly table: TableName;
+    readonly id: LocalId;
+    readonly kind: ServerChangeKind;
+    readonly value?: Record<string, unknown>;
+    readonly patch?: Record<string, unknown>;
+    readonly version: number;
+    readonly serverTime: number;
+    readonly opId?: string;
+};
+export type SyncScope = {
+    readonly kind: "byUser" | "byWorkspace" | "byProject";
+    readonly key: ScopeKey;
+    readonly table?: TableName;
+};
+export type PushRequest = {
+    readonly clientId: ClientId;
+    readonly userId: UserId | null;
+    readonly schemaVersion: number;
+    readonly mutations: readonly LocalOperation[];
+};
+export type AcceptedMutation = {
+    readonly opId: string;
+    readonly serverResult?: unknown;
+};
+export type RejectedMutation = {
+    readonly opId: string;
+    readonly message: string;
+    readonly code?: string;
+    readonly rowId?: LocalId;
+};
+export type IdMapEntry = {
+    readonly table: TableName;
+    readonly localId: LocalId;
+    readonly serverId: string;
+};
+export type PushResponse = {
+    readonly accepted: readonly AcceptedMutation[];
+    readonly rejected: readonly RejectedMutation[];
+    readonly idMaps: readonly IdMapEntry[];
+    readonly changes: readonly ServerChange[];
+    readonly serverTime: number;
+    /** Server signals the client schema version is incompatible; client must not apply. */
+    readonly schemaMismatch?: boolean;
+};
+export type PullRequest = {
+    readonly clientId: ClientId;
+    readonly userId: UserId | null;
+    readonly schemaVersion: number;
+    readonly scopes: readonly SyncScope[];
+    readonly cursors: Record<ScopeKey, Cursor>;
+};
+export type PullResponse = {
+    readonly changes: readonly ServerChange[];
+    readonly cursors: Record<ScopeKey, string>;
+    readonly serverTime: number;
+    /** Server signals the client schema version is incompatible; client must not apply. */
+    readonly schemaMismatch?: boolean;
+    /** Per-scope: true if the server capped this page and more changes remain past the
+     *  returned cursor. Lets the client drain to completion and report partial hydration
+     *  (a large cold start) instead of silently stopping behind. */
+    readonly hasMore?: Record<ScopeKey, boolean>;
+};
+export type SyncStatus = {
+    readonly online: boolean;
+    readonly syncing: boolean;
+    readonly pendingMutations: number;
+    readonly lastPushAt: number | null;
+    readonly lastPullAt: number | null;
+    readonly lastError: string | null;
+    readonly blockedBySchemaMismatch: boolean;
+    /** True while the local cache is still catching up to the server for some scope (a
+     *  large cold start drained past the per-pull cap). False once fully hydrated. */
+    readonly partial: boolean;
+};
+/**
+ * The result of a durable local commit (the `mutate(ref, args).local` promise).
+ * `id` is the CANONICAL row id this mutation targets — the new row's id for an
+ * insert, or the edited/removed row's id otherwise. It equals `row[idField]` and
+ * `row._id` on every subsequent read (the engine stamps the idField on inserts;
+ * the server re-stamps it on sync; the client keys rows by this same id). So a
+ * headless consumer reads it back with no guesswork: `const id = (await
+ * engine.mutate(ref, args).local).id`.
+ */
+export type LocalCommit = {
+    readonly opId: string;
+    readonly table: TableName;
+    readonly id: LocalId;
+    readonly committedAt: number;
+    /**
+     * The resulting row, so a caller can use it directly instead of a readback round-trip:
+     *  - INSERT: the optimistic row just written — `value` with `row[idField] === id`,
+     *    identical to what a read returns immediately after (and what the server re-stamps
+     *    on sync).
+     *  - PATCH: the canonical-plus-pending merge AFTER this patch is applied (same as
+     *    `getRow(table, id)` right after) — `undefined` only if the row isn't local yet.
+     *  - REMOVE: `undefined` — the row is gone.
+     *
+     * Reading it is local-only (no server pull), since the write already flushes via its
+     * background `.server` push.
+     */
+    readonly row?: Record<string, unknown>;
+};
+export type MutationStatus = {
+    readonly opId: string;
+    readonly status: OperationStatus;
+    readonly error?: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/view.d.ts

@@ -0,0 +1,12 @@
+import type { LocalOperation, RowValue, ServerChange, TableName } from "./types.js";
+/**
+ * Derive the live view for one table (Invariant I1): canonical snapshot with the
+ * deterministically-ordered pending operations replayed on top. Shared by every
+ * LocalStore implementation so the rebase logic lives in exactly one place.
+ */
+export declare function deriveView(table: TableName, canonicalRows: readonly RowValue[], operations: readonly LocalOperation[]): RowValue[];
+/**
+ * Compute the next canonical row for a server change, or "stale" if the change
+ * must be ignored because its version does not advance the row (Invariant I5).
+ */
+export declare function nextCanonicalRow(current: RowValue | null, change: ServerChange): RowValue | "stale";