@syncular/client 0.2.0 → 0.3.0

package/dist/schema.js

@@ -1,4 +1,5 @@
 import { ClientSyncError } from './errors.js';
+import { snakeToCamel } from './naming.js';
 const PATTERN_RE = /^([^{}]+):\{([^{}:]+)\}$/;
 export function compileClientSchema(schema) {
     const tables = new Map();
@@ -41,6 +42,21 @@ export function compileClientSchema(schema) {
             scopeColumnByVariable.set(variable, column);
             scopePrefixByVariable.set(variable, prefix);
         }
+        // §5: unambiguous camelCase aliases for mutate key normalization.
+        const columnIndexByCamel = new Map();
+        const ambiguous = new Set();
+        table.columns.forEach((column, index) => {
+            const alias = snakeToCamel(column.name);
+            if (alias === column.name || columnIndex.has(alias))
+                return;
+            if (columnIndexByCamel.has(alias)) {
+                ambiguous.add(alias);
+                return;
+            }
+            columnIndexByCamel.set(alias, index);
+        });
+        for (const alias of ambiguous)
+            columnIndexByCamel.delete(alias);
         const indexes = table.indexes ?? [];
         for (const index of indexes) {
             for (const column of index.columns) {
@@ -55,6 +71,7 @@ export function compileClientSchema(schema) {
             primaryKey: table.primaryKey,
             primaryKeyIndex,
             columnIndex,
+            columnIndexByCamel,
             scopeColumnByVariable,
             scopePrefixByVariable,
             indexes,
@@ -75,6 +92,28 @@ export function compileClientSchema(schema) {
 export const SYNC_VERSION_COLUMN = '_sync_version';
 /** `_sync_version` for optimistic rows the server has never confirmed. */
 export 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 function stripSyncColumns(rows) {
+    const first = rows[0];
+    if (first === undefined)
+        return rows;
+    const reserved = Object.keys(first).filter((key) => key.startsWith('_sync_'));
+    if (reserved.length === 0)
+        return rows;
+    return rows.map((row) => {
+        const copy = { ...row };
+        for (const key of reserved)
+            delete copy[key];
+        return copy;
+    });
+}
 export function quoteIdent(name) {
     return `"${name.replaceAll('"', '""')}"`;
 }
@@ -221,24 +260,64 @@ export function fromSqlValue(column, value) {
     }
 }
 /**
- * App-facing record → schema-ordered row values for the codec and the
- * local mirror. Missing keys become NULL; unknown keys fail loud.
+ * 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 function recordToRowValues(table, record) {
-    for (const key of Object.keys(record)) {
-        if (!table.columnIndex.has(key)) {
-            throw new ClientSyncError('sync.invalid_request', `table ${table.name}: unknown column ${JSON.stringify(key)} in mutation values`);
+export function normalizeRecordKeys(table, record) {
+    const normalized = new Map();
+    for (const [key, value] of Object.entries(record)) {
+        const index = table.columnIndex.get(key) ?? table.columnIndexByCamel.get(key);
+        if (index === undefined) {
+            if (key.startsWith('_sync_')) {
+                throw new ClientSyncError('sync.invalid_request', `table ${table.name}: ${JSON.stringify(key)} is an internal sync column and cannot appear in mutation values — did you build this record from a raw SELECT * row? (client.query() strips _sync_* columns; rows read via client.database keep them)`);
+            }
+            throw new ClientSyncError('sync.invalid_request', `table ${table.name}: unknown column ${JSON.stringify(key)} in mutation values (snake_case and camelCase keys are accepted)`);
         }
+        const sqlName = table.columns[index].name;
+        if (normalized.has(sqlName)) {
+            throw new ClientSyncError('sync.invalid_request', `table ${table.name}: column ${JSON.stringify(sqlName)} appears twice in mutation values (as both snake_case and camelCase) — pass it once`);
+        }
+        normalized.set(sqlName, value);
+    }
+    return normalized;
+}
+/**
+ * Accept the local SQL representation of a value alongside the app-facing
+ * one, so a row read straight off the mirror (`SELECT *`) feeds back into
+ * `mutate()` without per-column fixups: SQLite stores booleans as 0/1 and
+ * may surface integers as bigint. Anything else passes through untouched —
+ * the codec still fails loud on genuine type garbage at encode time.
+ */
+function coerceSqlRepresentation(column, value) {
+    switch (localColumnType(column)) {
+        case 'boolean':
+            return value === 0 ? false : value === 1 ? true : value;
+        case 'integer':
+        case 'float':
+            return typeof value === 'bigint' ? Number(value) : value;
+        default:
+            return value;
     }
+}
+/**
+ * App-facing record → schema-ordered row values for the codec and the
+ * local mirror. Missing keys become NULL; unknown keys fail loud (see
+ * {@link normalizeRecordKeys} for the accepted casings).
+ */
+export function recordToRowValues(table, record) {
+    const normalized = normalizeRecordKeys(table, record);
     return table.columns.map((column) => {
-        const value = record[column.name];
+        const value = normalized.get(column.name);
         if (value === undefined || value === null) {
             if (!column.nullable) {
                 throw new ClientSyncError('sync.invalid_request', `table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1 full-row payloads)`);
             }
             return null;
         }
-        return value;
+        return coerceSqlRepresentation(column, value);
     });
 }
 function bytesToHex(bytes) {

package/dist/sql-tag.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The `sql` tagged template — the raw tier's composition helper
+ * (DESIGN-queries.md I4). Structural injection safety: an interpolated
+ * value can only ever become a `?` bind parameter; SQL text can only enter
+ * through the literal template, `sql.ident()` (allowlist-gated) or a loud
+ * `sql.raw()`. This helper is deliberately dumb plumbing and stays that
+ * way — typed/composable queries are the `.syql` codegen tier's job, and
+ * this module must never grow features that overlap it.
+ *
+ *   const q = sql`
+ *     SELECT * FROM todos
+ *     WHERE list_id = ${listId}
+ *       ${status ? sql`AND status = ${status}` : sql.empty}
+ *       AND id IN (${ids})
+ *     ORDER BY ${sql.ident(orderCol, ['created_at', 'title'])} DESC`;
+ *   client.query(q.text, q.params);
+ */
+import type { SqlValue } from './database.js';
+/** A composed raw query: SQL text with `?` placeholders + bound params. */
+export interface SqlFragment {
+    readonly text: string;
+    readonly params: readonly SqlValue[];
+    /** Brand so fragments are distinguishable from user values. */
+    readonly [SQL_FRAGMENT]: true;
+}
+declare const SQL_FRAGMENT: unique symbol;
+export type SqlInterpolation = SqlValue | SqlFragment | readonly SqlValue[];
+/** Compose a raw query. Values bind; only literals/ident/raw become text. */
+export declare function sql(strings: TemplateStringsArray, ...values: readonly SqlInterpolation[]): SqlFragment;
+export declare namespace sql {
+    var empty: SqlFragment;
+    var ident: (value: string, allowlist: readonly string[]) => SqlFragment;
+    var raw: (text: string) => SqlFragment;
+}
+export {};

package/dist/sql-tag.js

@@ -0,0 +1,82 @@
+const SQL_FRAGMENT = Symbol.for('syncular.sqlFragment');
+function fragment(text, params) {
+    return { text, params, [SQL_FRAGMENT]: true };
+}
+function isFragment(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[SQL_FRAGMENT] === true);
+}
+function isSqlValue(value) {
+    return (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'bigint' ||
+        typeof value === 'boolean' ||
+        value instanceof Uint8Array);
+}
+/** Compose a raw query. Values bind; only literals/ident/raw become text. */
+export function sql(strings, ...values) {
+    let text = '';
+    const params = [];
+    for (let i = 0; i < strings.length; i++) {
+        text += strings[i] ?? '';
+        if (i >= values.length)
+            continue;
+        const value = values[i];
+        if (isFragment(value)) {
+            text += value.text;
+            params.push(...value.params);
+        }
+        else if (Array.isArray(value)) {
+            // An array binds as a comma-joined parameter list — `IN (${ids})`.
+            if (value.length === 0) {
+                // `IN ()` is a SQLite syntax error; bind a never-matching list.
+                text += 'SELECT NULL WHERE 0';
+            }
+            else {
+                for (const [j, item] of value.entries()) {
+                    if (!isSqlValue(item)) {
+                        throw new TypeError(`sql\`\` array element ${j} is not a bindable SQL value`);
+                    }
+                }
+                text += value.map(() => '?').join(', ');
+                params.push(...value);
+            }
+        }
+        else if (isSqlValue(value)) {
+            text += '?';
+            params.push(value);
+        }
+        else {
+            // undefined, objects, functions — always a bug at the call site.
+            throw new TypeError(`sql\`\` interpolation ${i} is not a bindable SQL value ` +
+                `(got ${value === undefined ? 'undefined' : typeof value}). ` +
+                'Bind a value, compose a sql`` fragment, or use ' +
+                'sql.ident()/sql.raw() explicitly.');
+        }
+    }
+    return fragment(text, params);
+}
+/** The empty fragment — the neutral element for conditional composition. */
+sql.empty = fragment('', []);
+/**
+ * An identifier (column/table name). The allowlist is MANDATORY —
+ * identifiers cannot be bound, so the only safe source is a closed set the
+ * caller wrote. The value is also shape-checked and quoted defensively.
+ */
+sql.ident = (value, allowlist) => {
+    if (!allowlist.includes(value)) {
+        throw new RangeError(`sql.ident: ${JSON.stringify(value)} is not in the allowlist ` +
+            `[${allowlist.join(', ')}]`);
+    }
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+        throw new RangeError(`sql.ident: ${JSON.stringify(value)} is not a plain identifier`);
+    }
+    return fragment(`"${value}"`, []);
+};
+/**
+ * Verbatim SQL text. The loud escape hatch: never pass request/user/synced
+ * data through here — that is the injection you were protected from.
+ */
+sql.raw = (text) => fragment(text, []);

package/dist/worker-entry.js

@@ -244,6 +244,13 @@ export function startSyncWorker(overrides = {}) {
             scheduleAutoSync();
             return id;
         },
+        patch: (table, rowId, partial, options) => {
+            // Same §8.4 rule as `mutate`: a local write must push without the app
+            // orchestrating sync, so schedule a jittered round to drain the outbox.
+            const id = requireClient().patch(table, rowId, partial, options);
+            scheduleAutoSync();
+            return id;
+        },
         sync: () => {
             const running = requireClient();
             return serializedSync(() => running.sync());

package/dist/worker-host.d.ts

@@ -8,17 +8,18 @@
  * holding the lock). The returned {@link SyncClientHandle} is a thin, fully
  * async proxy over the `worker-protocol` RPC.
  *
- * With `multiTab: true`, a tab that LOSES the election does not resolve to a
- * dead not-leader handle: it becomes a FOLLOWER (`role === 'follower'`) that
- * proxies every call to the leader tab over a BroadcastChannel (see
- * `multi-tab.ts`). When the leader tab closes, its lock releases; the
- * followers contest, the winner PROMOTES in place — spawns the worker over
- * the persisted OPFS database and re-announces — and the handle's `role`
- * flips to `'leader'` with `onRoleChange` firing. The same handle object is
- * kept across the transition so React bindings hold a stable reference.
+ * Multi-tab is the DEFAULT (RFC 0002 §2.4 — the follower path is
+ * conformance-covered): a tab that LOSES the election becomes a FOLLOWER
+ * (`role === 'follower'`) that proxies every call to the leader tab over a
+ * BroadcastChannel (see `multi-tab.ts`). When the leader tab closes, its
+ * lock releases; the followers contest, the winner PROMOTES in place —
+ * spawns the worker over the persisted OPFS database and re-announces — and
+ * the handle's `role` flips to `'leader'` with `onRoleChange` firing. The
+ * same handle object is kept across the transition so React bindings hold a
+ * stable reference.
  *
- * With `multiTab` off (default), behavior is unchanged: the loser is an
- * `isLeader === false` handle whose calls reject with `client.not_leader`.
+ * With `multiTab: false`, the loser is an `isLeader === false` handle whose
+ * calls reject with `client.not_leader` (the single-tab contract).
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
@@ -53,10 +54,11 @@ export interface SyncClientHandleConfig {
     readonly leaderLock?: LeaderLock;
     readonly lockName?: string;
     /**
-     * Multi-tab followers (TODO 3.2). When true, a tab that loses the leader
-     * election becomes a FOLLOWER that proxies to the leader over a
-     * BroadcastChannel, and contests + promotes when the leader closes. When
-     * false (default), the loser is a dead `isLeader === false` handle.
+     * Multi-tab followers (TODO 3.2). On by default: a tab that loses the
+     * leader election becomes a FOLLOWER that proxies to the leader over a
+     * BroadcastChannel, and contests + promotes when the leader closes. Set
+     * false for the single-tab contract — the loser is a dead
+     * `isLeader === false` handle rejecting with `client.not_leader`.
      */
     readonly multiTab?: boolean;
     /** Cross-tab channel factory (default `BroadcastChannel`); injectable for tests. */
@@ -134,6 +136,10 @@ export declare class SyncClientHandle {
     setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
     windowState(base: WindowBase): Promise<WindowState>;
     mutate(mutations: readonly MutationInput[]): Promise<string>;
+    /** Partial-update convenience: read-merge-write one full-row upsert. */
+    patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
+        readonly baseVersion?: number;
+    }): Promise<string>;
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
@@ -166,9 +172,9 @@ export declare class SyncClientHandle {
 /**
  * Acquire leadership, spawn the worker, initialize the core inside it.
  *
- * With `multiTab` off: a losing tab resolves to a dead not-leader handle.
- * With `multiTab` on: a losing tab becomes a FOLLOWER proxying to the leader,
- * and promotes itself if the leader later closes.
+ * With `multiTab` on (the default): a losing tab becomes a FOLLOWER proxying
+ * to the leader, and promotes itself if the leader later closes. With
+ * `multiTab: false`: a losing tab resolves to a dead not-leader handle.
  */
 export declare function createSyncClientHandle(config: SyncClientHandleConfig): Promise<SyncClientHandle>;
 export {};

package/dist/worker-host.js

@@ -1,3 +1,4 @@
+import { registerDevtools } from './devtools.js';
 import { ClientSyncError } from './errors.js';
 import { InvalidationEmitter } from './invalidation.js';
 import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
@@ -33,6 +34,7 @@ export class SyncClientHandle {
     #invalidation;
     #presence;
     #roleListeners;
+    #devtoolsUnregister;
     #closed = false;
     /** @internal — use {@link createSyncClientHandle}. */
     constructor(internals) {
@@ -43,6 +45,20 @@ export class SyncClientHandle {
         this.#invalidation = internals.invalidation;
         this.#presence = internals.presence;
         this.#roleListeners = internals.roleListeners ?? new Set();
+        // RFC 0002 §3.2: console introspection — a no-op outside a dev page.
+        this.#devtoolsUnregister = registerDevtools({
+            kind: 'handle',
+            ref: this,
+            clientId: () => this.#clientId,
+            role: () => this.#role,
+            outbox: async () => (await this.pendingCommits()).length,
+            subscriptions: () => this.subscriptions(),
+            conflicts: async () => (await this.conflicts()).length,
+            rejections: async () => (await this.rejections()).length,
+            syncNeeded: () => this.syncNeeded(),
+            upgrading: () => this.upgrading(),
+            onInvalidate: (listener) => this.onInvalidate(listener),
+        });
     }
     /** @internal — swap this handle from follower to leader (promotion). */
     __becomeLeader(core) {
@@ -109,7 +125,8 @@ export class SyncClientHandle {
         if (this.#role === 'follower') {
             if (this.#follower === undefined) {
                 return Promise.reject(new ClientSyncError(NOT_LEADER_CODE, 'this tab is not the leader — another tab owns the syncular ' +
-                    'core for this origin (enable multiTab for follower proxying)'));
+                    'core for this origin (this handle opted out of follower ' +
+                    'proxying with multiTab: false)'));
             }
             return this.#follower.call(method, args);
         }
@@ -133,6 +150,10 @@ export class SyncClientHandle {
     mutate(mutations) {
         return this.#call('mutate', [mutations]);
     }
+    /** Partial-update convenience: read-merge-write one full-row upsert. */
+    patch(table, rowId, partial, options) {
+        return this.#call('patch', [table, rowId, partial, options]);
+    }
     sync() {
         return this.#call('sync', []);
     }
@@ -199,6 +220,7 @@ export class SyncClientHandle {
         if (this.#closed)
             return;
         this.#closed = true;
+        this.#devtoolsUnregister();
         if (this.#follower !== undefined) {
             this.#follower.close();
             this.#follower = undefined;
@@ -351,9 +373,9 @@ function fireConfigCallbacks(config, event) {
 /**
  * Acquire leadership, spawn the worker, initialize the core inside it.
  *
- * With `multiTab` off: a losing tab resolves to a dead not-leader handle.
- * With `multiTab` on: a losing tab becomes a FOLLOWER proxying to the leader,
- * and promotes itself if the leader later closes.
+ * With `multiTab` on (the default): a losing tab becomes a FOLLOWER proxying
+ * to the leader, and promotes itself if the leader later closes. With
+ * `multiTab: false`: a losing tab resolves to a dead not-leader handle.
  */
 export async function createSyncClientHandle(config) {
     const lock = config.leaderLock ?? defaultLeaderLock();
@@ -381,8 +403,8 @@ export async function createSyncClientHandle(config) {
         });
     }
     // ---- Lost the election. ----
-    if (config.multiTab !== true) {
-        // Legacy single-tab contract: a dead not-leader handle.
+    if (config.multiTab === false) {
+        // Opted-out single-tab contract: a dead not-leader handle.
         return new SyncClientHandle({
             role: 'follower',
             clientId: '',
@@ -407,7 +429,7 @@ async function bootLeader(config, lockName, lease, parts) {
         fireConfigCallbacks(config, event);
         handleRef.handle?.__dispatchEvent(event);
     };
-    const makeBridge = config.multiTab === true
+    const makeBridge = config.multiTab !== false
         ? (clientId, invoke) => {
             const factory = config.channelFactory ?? broadcastChannelFactory();
             const channel = factory(multiTabChannelName(lockName));
@@ -484,7 +506,7 @@ async function bootFollower(config, lockName, lock, parts) {
                     fireConfigCallbacks(config, event);
                     handle.__dispatchEvent(event);
                 },
-                ...(config.multiTab === true
+                ...(config.multiTab !== false
                     ? {
                         makeBridge: (clientId, invoke) => {
                             const promoteChannel = factory(multiTabChannelName(lockName));

package/dist/worker-protocol.d.ts

@@ -82,6 +82,10 @@ export interface WorkerApi {
     /** §4.8 completeness oracle (I3): the windowed-in units for a base. */
     windowState(base: WindowBase): WindowState;
     mutate(mutations: readonly MutationInput[]): string;
+    /** Partial-update convenience: read-merge-write one full-row upsert. */
+    patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
+        readonly baseVersion?: number;
+    }): string;
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -28,7 +28,7 @@
   "exports": {
     ".": {
       "bun": "./src/index.ts",
-      "browser": "./src/index.ts",
+      "browser": "./dist/index.js",
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
@@ -36,7 +36,7 @@
     },
     "./bun": {
       "bun": "./src/bun-database.ts",
-      "browser": "./src/bun-database.ts",
+      "browser": "./dist/bun-database.js",
       "import": {
         "types": "./dist/bun-database.d.ts",
         "default": "./dist/bun-database.js"
@@ -44,7 +44,7 @@
     },
     "./node": {
       "bun": "./src/node-database.ts",
-      "browser": "./src/node-database.ts",
+      "browser": "./dist/node-database.js",
       "import": {
         "types": "./dist/node-database.d.ts",
         "default": "./dist/node-database.js"
@@ -52,7 +52,7 @@
     },
     "./wasm": {
       "bun": "./src/wasm-database.ts",
-      "browser": "./src/wasm-database.ts",
+      "browser": "./dist/wasm-database.js",
       "import": {
         "types": "./dist/wasm-database.d.ts",
         "default": "./dist/wasm-database.js"
@@ -60,7 +60,7 @@
     },
     "./worker": {
       "bun": "./src/worker-entry.ts",
-      "browser": "./src/worker-entry.ts",
+      "browser": "./dist/worker-entry.js",
       "import": {
         "types": "./dist/worker-entry.d.ts",
         "default": "./dist/worker-entry.js"
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.2.0"
+    "@syncular/core": "0.2.1"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.2.0",
+    "@syncular/server": "0.2.1",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -24,6 +24,7 @@ import {
   REALTIME_TAG_ROUND,
   type RequestFrame,
   type ResponseMessage,
+  type RowColumn,
   type RowValue,
   type ScopeMap,
   type SegmentRefFrame,
@@ -57,6 +58,7 @@ import {
   serializeBlobRef,
 } from './blob';
 import type { ClientDatabase, SqlRow, SqlValue } from './database';
+import { registerDevtools } from './devtools';
 import type { EncryptionConfig } from './encryption';
 import { ClientSyncError } from './errors';
 import {
@@ -79,6 +81,7 @@ import {
   OutboxEncodeError,
   type OutboxOperation,
 } from './outbox';
+import { assertReadOnlyQuery } from './query-guard';
 import {
   type ClientSchema,
   type CompiledClientSchema,
@@ -86,13 +89,16 @@ import {
   compileClientSchema,
   dropAndRecreateSyncedTables,
   ensureLocalSchema,
+  fromSqlValue,
   jsonToRowValue,
   LOCAL_SCHEMA_VERSION_KEY,
+  normalizeRecordKeys,
   OPTIMISTIC_VERSION,
   quoteIdent,
   recordToRowValues,
   rowValueToJson,
   SYNC_VERSION_COLUMN,
+  stripSyncColumns,
 } from './schema';
 import {
   deleteSubscription,
@@ -396,6 +402,7 @@ export class SyncClient {
   #started = false;
   #lease: LeaderLease | undefined;
   #clientId = '';
+  #devtoolsUnregister: (() => void) | undefined;
   #schemaFloor: SchemaFloor | undefined;
   #leaseState: LeaseState | undefined;
   /** §7.4.5: true while a schema-bump reset + first bootstrap is in flight. */
@@ -475,6 +482,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),
+    });
   }
 
   /**
@@ -530,6 +551,8 @@ export class SyncClient {
   }
 
   async close(): Promise<void> {
+    this.#devtoolsUnregister?.();
+    this.#devtoolsUnregister = undefined;
     this.#socket?.close();
     this.#socket = undefined;
     this.#abortPendingRound('client closed mid-round');
@@ -549,8 +572,17 @@ export class SyncClient {
     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: string, params?: readonly SqlValue[]): SqlRow[] {
-    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) -----------
@@ -1181,6 +1213,53 @@ 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: string,
+    rowId: string,
+    partial: Readonly<Record<string, unknown>>,
+    options?: { readonly baseVersion?: number },
+  ): string {
+    this.#requireStarted();
+    const compiled = this.#table(table);
+    const pkColumn = compiled.columns[compiled.primaryKeyIndex] as RowColumn;
+    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: Record<string, unknown> = {};
+    for (const column of compiled.columns as readonly RowColumn[]) {
+      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). */