@syncular/client 0.2.1 → 0.3.0

package/dist/client.d.ts

@@ -194,6 +194,14 @@ export declare class SyncClient {
     get clientId(): string;
     /** The underlying database — raw SQL is the local query API (B3). */
     get database(): ClientDatabase;
+    /**
+     * The raw-SQL read tier. Guarded (query-guard.ts): a single read-only
+     * statement only — writes must go through `mutate()` so they hit the
+     * outbox (SPEC §7.1). Reserved `_sync_*` columns are stripped from the
+     * result, so a `SELECT *` row is safe to feed back into `mutate()`
+     * values; alias explicitly (`_sync_version AS v`) to read one. Engine
+     * internals read `this.#db` directly and skip this method by design.
+     */
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
     /**
      * Subscribe to fine-grained invalidation. The callback fires ONCE per
@@ -309,6 +317,17 @@ export declare class SyncClient {
      * Returns the generated `clientCommitId`.
      */
     mutate(mutations: readonly MutationInput[]): string;
+    /**
+     * Partial-update convenience over the §6.1 full-row wire: read the
+     * current LOCAL row, merge `partial` over it, and record one full-row
+     * upsert through `mutate()`. `partial` keys follow the same two-casing
+     * rule as mutation values (snake_case or camelCase). The row must be
+     * locally present (subscribed/windowed-in); patching an absent row is
+     * an error — there is no base to merge into.
+     */
+    patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
+        readonly baseVersion?: number;
+    }): string;
     /**
      * One combined push+pull round (§1.5, §7.2). The core owns one loop: a
      * concurrent `sync()` while one is already outstanding is rejected loudly

package/dist/client.js

@@ -10,11 +10,13 @@
 import { canonicalScopeJson, decodeMessage, decodeRow, decodeRowsSegment, encodeMessage, encodePresencePublish, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
 import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, upsertLocalRow, } from './apply.js';
 import { clearPendingUpload, computeBlobId, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, reconcileBlobRefcounts, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
+import { registerDevtools } from './devtools.js';
 import { ClientSyncError } from './errors.js';
 import { Invalidation, InvalidationEmitter, } from './invalidation.js';
 import { singleOwnerLock, } from './leader-lock.js';
 import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, OutboxEncodeError, } from './outbox.js';
-import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalSchema, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, } from './schema.js';
+import { assertReadOnlyQuery } from './query-guard.js';
+import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalSchema, fromSqlValue, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
 import { deleteSubscription, getMeta, getSubscription, loadSubscriptions, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
 import { deletePendingEviction, deleteWindowUnit, deriveSubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
 /** True iff `unit` is windowed-in for this snapshot (a registry hit, I3). */
@@ -68,6 +70,7 @@ export class SyncClient {
     #started = false;
     #lease;
     #clientId = '';
+    #devtoolsUnregister;
     #schemaFloor;
     #leaseState;
     /** §7.4.5: true while a schema-bump reset + first bootstrap is in flight. */
@@ -144,6 +147,20 @@ export class SyncClient {
         // already at the generated version.
         this.#detectAndResetSchema();
         this.#started = true;
+        // RFC 0002 §3.2: console introspection — a no-op outside a dev page.
+        this.#devtoolsUnregister = registerDevtools({
+            kind: 'client',
+            ref: this,
+            clientId: () => this.#clientId,
+            role: () => 'direct',
+            outbox: async () => this.pendingCommits().length,
+            subscriptions: async () => this.subscriptions(),
+            conflicts: async () => this.conflicts.length,
+            rejections: async () => this.rejections.length,
+            syncNeeded: async () => this.syncNeeded,
+            upgrading: async () => this.upgrading,
+            onInvalidate: (listener) => this.onInvalidate(listener),
+        });
     }
     /**
      * §7.4.1/§7.4.2: compare the generated schema version to the persisted
@@ -194,6 +211,8 @@ export class SyncClient {
         this.#config.onUpgrading?.(upgrading);
     }
     async close() {
+        this.#devtoolsUnregister?.();
+        this.#devtoolsUnregister = undefined;
         this.#socket?.close();
         this.#socket = undefined;
         this.#abortPendingRound('client closed mid-round');
@@ -209,8 +228,17 @@ export class SyncClient {
     get database() {
         return this.#db;
     }
+    /**
+     * The raw-SQL read tier. Guarded (query-guard.ts): a single read-only
+     * statement only — writes must go through `mutate()` so they hit the
+     * outbox (SPEC §7.1). Reserved `_sync_*` columns are stripped from the
+     * result, so a `SELECT *` row is safe to feed back into `mutate()`
+     * values; alias explicitly (`_sync_version AS v`) to read one. Engine
+     * internals read `this.#db` directly and skip this method by design.
+     */
     query(sql, params) {
-        return this.#db.query(sql, params);
+        assertReadOnlyQuery(sql);
+        return stripSyncColumns(this.#db.query(sql, params));
     }
     // -- live-query invalidation (TODO 3.1 / DESIGN-eviction I1–I4) -----------
     /**
@@ -751,6 +779,41 @@ export class SyncClient {
         });
         return clientCommitId;
     }
+    /**
+     * Partial-update convenience over the §6.1 full-row wire: read the
+     * current LOCAL row, merge `partial` over it, and record one full-row
+     * upsert through `mutate()`. `partial` keys follow the same two-casing
+     * rule as mutation values (snake_case or camelCase). The row must be
+     * locally present (subscribed/windowed-in); patching an absent row is
+     * an error — there is no base to merge into.
+     */
+    patch(table, rowId, partial, options) {
+        this.#requireStarted();
+        const compiled = this.#table(table);
+        const pkColumn = compiled.columns[compiled.primaryKeyIndex];
+        const rows = this.#db.query(`SELECT * FROM ${quoteIdent(compiled.name)} WHERE ${quoteIdent(pkColumn.name)} = ?`, [rowId]);
+        const row = rows[0];
+        if (row === undefined) {
+            throw new ClientSyncError('sync.invalid_request', `table ${compiled.name}: no local row with primary key ${JSON.stringify(rowId)} to patch`);
+        }
+        const record = {};
+        for (const column of compiled.columns) {
+            record[column.name] = fromSqlValue(column, row[column.name] ?? null);
+        }
+        for (const [name, value] of normalizeRecordKeys(compiled, partial)) {
+            record[name] = value;
+        }
+        return this.mutate([
+            {
+                table,
+                op: 'upsert',
+                values: record,
+                ...(options?.baseVersion !== undefined
+                    ? { baseVersion: options.baseVersion }
+                    : {}),
+            },
+        ]);
+    }
     // -- lease state (§7.3.5) ---------------------------------------------------
     /** Merge and persist the lease state (opaque, §7.3.5). */
     #setLeaseState(next) {

package/dist/devtools.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The client-side introspection registry (RFC 0002 §3.2): every live
+ * `SyncClient` / `SyncClientHandle` on a page registers itself on
+ * `globalThis.__SYNCULAR__`, so a first integration debugs from the console
+ * instead of hand-exposing the client:
+ *
+ *     __SYNCULAR__.clients            // the live entries
+ *     await __SYNCULAR__.snapshot()   // one plain object per client:
+ *                                     // outbox depth, subscriptions,
+ *                                     // conflicts, syncNeeded, upgrading,
+ *                                     // last invalidation
+ *     __SYNCULAR__.clients[0].ref     // the client itself — full API
+ *
+ * Gated to development: the registry installs only where a `window` exists
+ * (worker cores register through their page-side handle) and NODE_ENV is
+ * anything except `'production'` (bundlers statically replace it, so
+ * production builds skip installation; environments without `process` are
+ * treated as dev). Cost when gated off: one function call per client.
+ */
+import type { InvalidationListener } from './invalidation.js';
+/** What a registrant supplies — plain lambdas over its own surface. */
+export interface DevtoolsRegistration {
+    /** `'direct'` (a `SyncClient`) or the handle's role. */
+    readonly kind: 'client' | 'handle';
+    /** The client/handle itself, for full-API console access. */
+    readonly ref: unknown;
+    readonly clientId: () => string;
+    readonly role: () => string;
+    readonly outbox: () => Promise<number>;
+    readonly subscriptions: () => Promise<readonly unknown[]>;
+    readonly conflicts: () => Promise<number>;
+    readonly rejections: () => Promise<number>;
+    readonly syncNeeded: () => Promise<boolean>;
+    readonly upgrading: () => Promise<boolean>;
+    readonly onInvalidate: (listener: InvalidationListener) => () => void;
+}
+/** One live entry on the registry (a registration plus tracked state). */
+export interface DevtoolsEntry extends DevtoolsRegistration {
+    /** The most recent invalidation event, timestamped (epoch ms). */
+    lastInvalidation?: {
+        readonly atMs: number;
+        readonly tables: readonly string[];
+        readonly scopeKeys: readonly string[];
+    };
+}
+/**
+ * Register a client on the page registry. Returns the unregister function
+ * (a no-op when the registry is gated off) — call it from `close()`.
+ */
+export declare function registerDevtools(registration: DevtoolsRegistration): () => void;

package/dist/devtools.js

@@ -0,0 +1,60 @@
+const KEY = '__SYNCULAR__';
+/** The page global to install on, or undefined when gated off. */
+function registryHost() {
+    const g = globalThis;
+    if (g.window === undefined)
+        return undefined;
+    if (g.process?.env?.NODE_ENV === 'production')
+        return undefined;
+    return g;
+}
+function registryOn(host) {
+    const existing = host[KEY];
+    if (existing !== undefined)
+        return existing;
+    const registry = {
+        clients: [],
+        snapshot: async () => Promise.all(registry.clients.map(async (entry) => ({
+            kind: entry.kind,
+            clientId: entry.clientId(),
+            role: entry.role(),
+            outbox: await entry.outbox().catch(() => 'unavailable'),
+            subscriptions: await entry
+                .subscriptions()
+                .then((subs) => subs.length)
+                .catch(() => 'unavailable'),
+            conflicts: await entry.conflicts().catch(() => 'unavailable'),
+            rejections: await entry.rejections().catch(() => 'unavailable'),
+            syncNeeded: await entry.syncNeeded().catch(() => 'unavailable'),
+            upgrading: await entry.upgrading().catch(() => 'unavailable'),
+            lastInvalidation: entry.lastInvalidation,
+        }))),
+    };
+    host[KEY] = registry;
+    return registry;
+}
+/**
+ * Register a client on the page registry. Returns the unregister function
+ * (a no-op when the registry is gated off) — call it from `close()`.
+ */
+export function registerDevtools(registration) {
+    const host = registryHost();
+    if (host === undefined)
+        return () => { };
+    const registry = registryOn(host);
+    const entry = { ...registration };
+    const unlisten = registration.onInvalidate((event) => {
+        entry.lastInvalidation = {
+            atMs: Date.now(),
+            tables: [...event.tables],
+            scopeKeys: [...event.scopeKeys],
+        };
+    });
+    registry.clients.push(entry);
+    return () => {
+        unlisten();
+        const index = registry.clients.indexOf(entry);
+        if (index !== -1)
+            registry.clients.splice(index, 1);
+    };
+}

package/dist/index.d.ts

@@ -13,14 +13,18 @@ export * from './blob.js';
 export * from './client.js';
 export * from './content-type.js';
 export * from './database.js';
+export * from './devtools.js';
 export * from './encryption.js';
 export * from './errors.js';
 export * from './http.js';
 export * from './invalidation.js';
 export * from './leader-lock.js';
 export * from './multi-tab.js';
+export * from './naming.js';
 export * from './outbox.js';
+export * from './query-guard.js';
 export * from './schema.js';
+export * from './sql-tag.js';
 export * from './state.js';
 export * from './transport.js';
 export * from './window.js';

package/dist/index.js

@@ -13,14 +13,18 @@ export * from './blob.js';
 export * from './client.js';
 export * from './content-type.js';
 export * from './database.js';
+export * from './devtools.js';
 export * from './encryption.js';
 export * from './errors.js';
 export * from './http.js';
 export * from './invalidation.js';
 export * from './leader-lock.js';
 export * from './multi-tab.js';
+export * from './naming.js';
 export * from './outbox.js';
+export * from './query-guard.js';
 export * from './schema.js';
+export * from './sql-tag.js';
 export * from './state.js';
 export * from './transport.js';
 export * from './window.js';

package/dist/naming.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The pinned snake→camel naming map (DESIGN-queries.md §5, §12) — the
+ * client-side copy of the typegen algorithm (kept in lockstep by shared
+ * test vectors; the Rust core carries the same function). Used by `mutate`
+ * to accept BOTH casings for value keys: the canonical camelCase the
+ * generated row types use, and the SQL-truth snake_case. One bijective map
+ * lookup per key; anything else errors (no fuzzy matching).
+ */
+/** The pinned §12 snake→camel conversion (see typegen's naming.ts). */
+export declare function snakeToCamel(name: string): string;

package/dist/naming.js

@@ -0,0 +1,26 @@
+/**
+ * The pinned snake→camel naming map (DESIGN-queries.md §5, §12) — the
+ * client-side copy of the typegen algorithm (kept in lockstep by shared
+ * test vectors; the Rust core carries the same function). Used by `mutate`
+ * to accept BOTH casings for value keys: the canonical camelCase the
+ * generated row types use, and the SQL-truth snake_case. One bijective map
+ * lookup per key; anything else errors (no fuzzy matching).
+ */
+const MAPPABLE_RE = /^_*[A-Za-z][A-Za-z0-9_]*$/;
+/** The pinned §12 snake→camel conversion (see typegen's naming.ts). */
+export function snakeToCamel(name) {
+    if (!MAPPABLE_RE.test(name))
+        return name;
+    const lead = /^_*/.exec(name)?.[0] ?? '';
+    const bare = name.slice(lead.length);
+    const trail = /_*$/.exec(bare)?.[0] ?? '';
+    const middle = bare.slice(0, bare.length - trail.length);
+    const segments = middle.split('_').filter((s) => s.length > 0);
+    if (segments.length === 0)
+        return name;
+    const first = segments[0];
+    const rest = segments
+        .slice(1)
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1));
+    return lead + first + rest.join('') + trail;
+}

package/dist/query-guard.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The raw-query guard (DESIGN-queries.md I3). `client.query()` / the React
+ * `useRawSql` hook are the untrusted raw-SQL tier: an app hands us a SQL
+ * string and we run it against the local database. Two rules make that safe
+ * to expose, enforced HERE in the core (previously they lived in the
+ * now-removed `@syncular/kysely` read-only driver):
+ *
+ *   1. READ-ONLY. Only `select / with / explain / pragma / values` are
+ *      allowed. A write (`insert/update/delete/…`) against the local mirror
+ *      bypasses the outbox (SPEC §7.1) and silently diverges from the
+ *      server — writes MUST go through `client.mutate([...])`.
+ *   2. ONE STATEMENT. `sqlite-wasm`'s `exec` runs every statement in a
+ *      multi-statement string (`SELECT 1; DROP TABLE t`), while bun:sqlite /
+ *      better-sqlite3 prepare only the first. We unify on the strict
+ *      behaviour: exactly one statement per `query()`.
+ *
+ * The guard only fronts the PUBLIC `client.query()` — engine-internal reads
+ * call the `ClientDatabase` directly and are trusted, so they are never
+ * routed through here.
+ */
+/** Raised when `client.query()` is handed SQL it will not run. */
+export declare class RawSqlError extends Error {
+    readonly name = "RawSqlError";
+}
+/**
+ * Assert `sql` is a single read-only statement, or throw `RawSqlError`.
+ * Called by `client.query()` before the string reaches the database.
+ */
+export declare function assertReadOnlyQuery(sql: string): void;

package/dist/query-guard.js

@@ -0,0 +1,200 @@
+/**
+ * The raw-query guard (DESIGN-queries.md I3). `client.query()` / the React
+ * `useRawSql` hook are the untrusted raw-SQL tier: an app hands us a SQL
+ * string and we run it against the local database. Two rules make that safe
+ * to expose, enforced HERE in the core (previously they lived in the
+ * now-removed `@syncular/kysely` read-only driver):
+ *
+ *   1. READ-ONLY. Only `select / with / explain / pragma / values` are
+ *      allowed. A write (`insert/update/delete/…`) against the local mirror
+ *      bypasses the outbox (SPEC §7.1) and silently diverges from the
+ *      server — writes MUST go through `client.mutate([...])`.
+ *   2. ONE STATEMENT. `sqlite-wasm`'s `exec` runs every statement in a
+ *      multi-statement string (`SELECT 1; DROP TABLE t`), while bun:sqlite /
+ *      better-sqlite3 prepare only the first. We unify on the strict
+ *      behaviour: exactly one statement per `query()`.
+ *
+ * The guard only fronts the PUBLIC `client.query()` — engine-internal reads
+ * call the `ClientDatabase` directly and are trusted, so they are never
+ * routed through here.
+ */
+/** Verbs a read-only query may begin with (lowercased). */
+const READ_ONLY_VERBS = new Set([
+    'select',
+    'with',
+    'explain',
+    'pragma',
+    'values',
+]);
+/** Raised when `client.query()` is handed SQL it will not run. */
+export class RawSqlError extends Error {
+    name = 'RawSqlError';
+}
+/**
+ * Split `sql` into top-level statements at unquoted `;`, skipping over
+ * string literals ('…'), quoted/bracketed identifiers ("…", `…`, […]) and
+ * comments (-- …, /* … *​/) so a `;` inside any of them is not a boundary.
+ * Returns the non-empty statements (comment/whitespace-only trailers drop).
+ */
+function splitStatements(sql) {
+    const statements = [];
+    let start = 0;
+    let i = 0;
+    const n = sql.length;
+    const pushIfNonEmpty = (end) => {
+        const stripped = stripLeading(sql.slice(start, end));
+        if (stripped.length > 0)
+            statements.push(sql.slice(start, end));
+        start = end + 1;
+    };
+    while (i < n) {
+        const c = sql[i];
+        if (c === '-' && sql[i + 1] === '-') {
+            const nl = sql.indexOf('\n', i + 2);
+            i = nl === -1 ? n : nl + 1;
+        }
+        else if (c === '/' && sql[i + 1] === '*') {
+            const close = sql.indexOf('*/', i + 2);
+            i = close === -1 ? n : close + 2;
+        }
+        else if (c === "'" || c === '"' || c === '`') {
+            i = skipQuoted(sql, i, c);
+        }
+        else if (c === '[') {
+            const close = sql.indexOf(']', i + 1);
+            i = close === -1 ? n : close + 1;
+        }
+        else if (c === ';') {
+            pushIfNonEmpty(i);
+            i += 1;
+        }
+        else {
+            i += 1;
+        }
+    }
+    pushIfNonEmpty(n);
+    return statements;
+}
+/** Advance past a quoted run opened at `open`; SQL doubles the quote to escape it. */
+function skipQuoted(sql, open, quote) {
+    let i = open + 1;
+    const n = sql.length;
+    while (i < n) {
+        if (sql[i] === quote) {
+            if (sql[i + 1] === quote)
+                i += 2;
+            else
+                return i + 1;
+        }
+        else {
+            i += 1;
+        }
+    }
+    return n;
+}
+/** Strip leading whitespace and comments, returning the remainder. */
+function stripLeading(sql) {
+    return sql
+        .replace(/^\s*(?:--[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/|\s)+/, '')
+        .trimStart();
+}
+function firstWords(sql) {
+    const trimmed = sql.trim().replace(/\s+/g, ' ');
+    return trimmed.length > 72 ? `${trimmed.slice(0, 72)}…` : trimmed;
+}
+/**
+ * The main verb of a `WITH …` statement: SQLite allows a with-clause before
+ * SELECT **and before INSERT/UPDATE/DELETE**, so `WITH t AS (…) DELETE …`
+ * must not slip through the verb allowlist. CTE bodies live inside
+ * parentheses, and a bare keyword cannot be a CTE name, so the first
+ * paren-depth-0 keyword after the clause IS the main verb.
+ */
+function mainVerbAfterWith(sql) {
+    const MAIN_VERBS = new Set([
+        'select',
+        'values',
+        'insert',
+        'update',
+        'delete',
+        'replace',
+    ]);
+    let depth = 0;
+    let i = 0;
+    const n = sql.length;
+    let sawWith = false;
+    while (i < n) {
+        const c = sql[i];
+        if (c === '-' && sql[i + 1] === '-') {
+            const nl = sql.indexOf('\n', i + 2);
+            i = nl === -1 ? n : nl + 1;
+        }
+        else if (c === '/' && sql[i + 1] === '*') {
+            const close = sql.indexOf('*/', i + 2);
+            i = close === -1 ? n : close + 2;
+        }
+        else if (c === "'" || c === '"' || c === '`') {
+            i = skipQuoted(sql, i, c);
+        }
+        else if (c === '[') {
+            const close = sql.indexOf(']', i + 1);
+            i = close === -1 ? n : close + 1;
+        }
+        else if (c === '(') {
+            depth += 1;
+            i += 1;
+        }
+        else if (c === ')') {
+            depth -= 1;
+            i += 1;
+        }
+        else if (/[A-Za-z_]/.test(c)) {
+            let j = i + 1;
+            while (j < n && /[A-Za-z0-9_]/.test(sql[j]))
+                j += 1;
+            const word = sql.slice(i, j).toLowerCase();
+            if (depth === 0) {
+                if (!sawWith && word === 'with')
+                    sawWith = true;
+                else if (sawWith && MAIN_VERBS.has(word))
+                    return word;
+            }
+            i = j;
+        }
+        else {
+            i += 1;
+        }
+    }
+    return undefined;
+}
+/**
+ * Assert `sql` is a single read-only statement, or throw `RawSqlError`.
+ * Called by `client.query()` before the string reaches the database.
+ */
+export function assertReadOnlyQuery(sql) {
+    const statements = splitStatements(sql);
+    if (statements.length === 0) {
+        throw new RawSqlError('client.query() was given an empty statement.');
+    }
+    if (statements.length > 1) {
+        throw new RawSqlError(`client.query() runs a single statement, but ${statements.length} were ` +
+            'given. Split them into separate query() calls. ' +
+            `First: ${firstWords(statements[0] ?? '')}`);
+    }
+    const statement = stripLeading(statements[0] ?? '');
+    const verb = statement.match(/^([a-zA-Z]+)/)?.[1]?.toLowerCase();
+    const rejectWrite = () => {
+        throw new RawSqlError('client.query() is read-only — this statement writes the local ' +
+            'database directly, which bypasses the sync outbox (SPEC §7.1). Use ' +
+            '`client.mutate([...])` for inserts/updates/deletes. ' +
+            `Rejected: ${firstWords(sql)}`);
+    };
+    if (verb === undefined || !READ_ONLY_VERBS.has(verb))
+        rejectWrite();
+    if (verb === 'with') {
+        // SQLite allows `WITH … DELETE/INSERT/UPDATE`; only a SELECT/VALUES
+        // main statement is a read.
+        const main = mainVerbAfterWith(statement);
+        if (main !== 'select' && main !== 'values')
+            rejectWrite();
+    }
+}

package/dist/schema.d.ts

@@ -5,7 +5,7 @@
  * mapping (scope variable → local column).
  */
 import type { RowColumn, RowValue } from '@syncular/core';
-import type { ClientDatabase, SqlValue } from './database.js';
+import type { ClientDatabase, SqlRow, SqlValue } from './database.js';
 /** `'prefix:{variable}'` shorthand (column name = variable) or explicit. */
 export type ScopePatternSpec = string | {
     pattern: string;
@@ -38,6 +38,13 @@ export interface CompiledClientTable {
     readonly primaryKey: string;
     readonly primaryKeyIndex: number;
     readonly columnIndex: ReadonlyMap<string, number>;
+    /**
+     * §5 mutate key normalization: unambiguous camelCase alias → column
+     * index. An alias is dropped when it equals another column's exact name
+     * or when two columns map to the same alias (exact names always win; the
+     * generator errors on such schemas under camel naming anyway).
+     */
+    readonly columnIndexByCamel: ReadonlyMap<string, number>;
     /** Scope variable → local scope column (§3.3 purge mapping). */
     readonly scopeColumnByVariable: ReadonlyMap<string, string>;
     /**
@@ -67,6 +74,15 @@ export declare function compileClientSchema(schema: ClientSchema): CompiledClien
 export declare const SYNC_VERSION_COLUMN = "_sync_version";
 /** `_sync_version` for optimistic rows the server has never confirmed. */
 export declare const OPTIMISTIC_VERSION = -1;
+/**
+ * Strip the reserved `_sync_*` columns from app-facing query rows, so a
+ * `SELECT *` row round-trips straight into `mutate()` values. Result
+ * columns are per-statement, so the first row decides for all rows; an
+ * explicit alias (`SELECT _sync_version AS v`) passes through untouched.
+ * Engine internals read `_sync_version` via `client.database` and never
+ * pass through this filter.
+ */
+export declare function stripSyncColumns(rows: SqlRow[]): SqlRow[];
 export declare function quoteIdent(name: string): string;
 /**
  * §5.11: the app-side type of a column for local (plaintext) storage. For an
@@ -94,9 +110,18 @@ export declare function dropAndRecreateSyncedTables(db: ClientDatabase, schema:
 export declare function toSqlValue(value: RowValue): SqlValue;
 /** SQL cell → RowValue per the column's declared type. */
 export declare function fromSqlValue(column: RowColumn, value: SqlValue): RowValue;
+/**
+ * Normalize an app-facing record's keys to the SQL-truth snake_case column
+ * names. Keys are accepted in exactly two casings (§5/§12): snake_case and
+ * the generated row types' camelCase — one bijective-map lookup per key,
+ * no fuzzy matching. Unknown keys fail loud (with a dedicated hint for the
+ * reserved `_sync_*` names); giving one column in both casings is an error.
+ */
+export declare function normalizeRecordKeys(table: CompiledClientTable, record: Readonly<Record<string, unknown>>): Map<string, unknown>;
 /**
  * App-facing record → schema-ordered row values for the codec and the
- * local mirror. Missing keys become NULL; unknown keys fail loud.
+ * local mirror. Missing keys become NULL; unknown keys fail loud (see
+ * {@link normalizeRecordKeys} for the accepted casings).
  */
 export declare function recordToRowValues(table: CompiledClientTable, record: Readonly<Record<string, unknown>>): RowValue[];
 export type JsonRowValue = string | number | boolean | null | {