@syncular/client 0.2.1 → 0.3.0

package/src/devtools.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 { InvalidationEvent, InvalidationListener } from './invalidation';
+
+/** 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[];
+  };
+}
+
+interface DevtoolsRegistry {
+  readonly clients: DevtoolsEntry[];
+  snapshot(): Promise<Record<string, unknown>[]>;
+}
+
+const KEY = '__SYNCULAR__';
+
+/** The page global to install on, or undefined when gated off. */
+function registryHost(): Record<string, unknown> | undefined {
+  const g = globalThis as Record<string, unknown> & {
+    window?: unknown;
+    process?: { env?: { NODE_ENV?: string } };
+  };
+  if (g.window === undefined) return undefined;
+  if (g.process?.env?.NODE_ENV === 'production') return undefined;
+  return g;
+}
+
+function registryOn(host: Record<string, unknown>): DevtoolsRegistry {
+  const existing = host[KEY];
+  if (existing !== undefined) return existing as DevtoolsRegistry;
+  const registry: DevtoolsRegistry = {
+    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: DevtoolsRegistration,
+): () => void {
+  const host = registryHost();
+  if (host === undefined) return () => {};
+  const registry = registryOn(host);
+  const entry: DevtoolsEntry = { ...registration };
+  const unlisten = registration.onInvalidate((event: InvalidationEvent) => {
+    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/src/index.ts

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

package/src/naming.ts

@@ -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: string): string {
+  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] as string;
+  const rest = segments
+    .slice(1)
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1));
+  return lead + first + rest.join('') + trail;
+}

package/src/query-guard.ts

@@ -0,0 +1,193 @@
+/**
+ * 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 {
+  override readonly 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: string): string[] {
+  const statements: string[] = [];
+  let start = 0;
+  let i = 0;
+  const n = sql.length;
+
+  const pushIfNonEmpty = (end: number) => {
+    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 as "'" | '"' | '`');
+    } 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: string, open: number, quote: "'" | '"' | '`'): number {
+  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: string): string {
+  return sql
+    .replace(/^\s*(?:--[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/|\s)+/, '')
+    .trimStart();
+}
+
+function firstWords(sql: string): string {
+  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: string): string | undefined {
+  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] as string;
+    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 as "'" | '"' | '`');
+    } 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] as string)) 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: string): void {
+  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 = (): never => {
+    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/src/schema.ts

@@ -5,8 +5,9 @@
  * mapping (scope variable → local column).
  */
 import type { RowColumn, RowValue } from '@syncular/core';
-import type { ClientDatabase, SqlValue } from './database';
+import type { ClientDatabase, SqlRow, SqlValue } from './database';
 import { ClientSyncError } from './errors';
+import { snakeToCamel } from './naming';
 
 /** `'prefix:{variable}'` shorthand (column name = variable) or explicit. */
 export type ScopePatternSpec = string | { pattern: string; column: string };
@@ -41,6 +42,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>;
   /**
@@ -119,6 +127,19 @@ export function compileClientSchema(
       scopeColumnByVariable.set(variable, column);
       scopePrefixByVariable.set(variable, prefix);
     }
+    // §5: unambiguous camelCase aliases for mutate key normalization.
+    const columnIndexByCamel = new Map<string, number>();
+    const ambiguous = new Set<string>();
+    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) {
@@ -135,6 +156,7 @@ export function compileClientSchema(
       primaryKey: table.primaryKey,
       primaryKeyIndex,
       columnIndex,
+      columnIndexByCamel,
       scopeColumnByVariable,
       scopePrefixByVariable,
       indexes,
@@ -159,6 +181,26 @@ 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: SqlRow[]): SqlRow[] {
+  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: SqlRow = { ...row };
+    for (const key of reserved) delete copy[key];
+    return copy;
+  });
+}
+
 export function quoteIdent(name: string): string {
   return `"${name.replaceAll('"', '""')}"`;
 }
@@ -329,23 +371,75 @@ export function fromSqlValue(column: RowColumn, value: SqlValue): RowValue {
 }
 
 /**
- * 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(
+export function normalizeRecordKeys(
   table: CompiledClientTable,
   record: Readonly<Record<string, unknown>>,
-): RowValue[] {
-  for (const key of Object.keys(record)) {
-    if (!table.columnIndex.has(key)) {
+): Map<string, unknown> {
+  const normalized = new Map<string, unknown>();
+  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`,
+        `table ${table.name}: unknown column ${JSON.stringify(key)} in mutation values (snake_case and camelCase keys are accepted)`,
       );
     }
+    const sqlName = (table.columns[index] as RowColumn).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: RowColumn, value: unknown): unknown {
+  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: CompiledClientTable,
+  record: Readonly<Record<string, unknown>>,
+): RowValue[] {
+  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(
@@ -355,7 +449,7 @@ export function recordToRowValues(
       }
       return null;
     }
-    return value as RowValue;
+    return coerceSqlRepresentation(column, value) as RowValue;
   });
 }
 

package/src/sql-tag.ts

@@ -0,0 +1,128 @@
+/**
+ * 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';
+
+/** 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;
+}
+
+const SQL_FRAGMENT = Symbol.for('syncular.sqlFragment');
+
+function fragment(text: string, params: readonly SqlValue[]): SqlFragment {
+  return { text, params, [SQL_FRAGMENT]: true };
+}
+
+function isFragment(value: unknown): value is SqlFragment {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as Record<PropertyKey, unknown>)[SQL_FRAGMENT] === true
+  );
+}
+
+function isSqlValue(value: unknown): value is SqlValue {
+  return (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'bigint' ||
+    typeof value === 'boolean' ||
+    value instanceof Uint8Array
+  );
+}
+
+export type SqlInterpolation = SqlValue | SqlFragment | readonly SqlValue[];
+
+/** Compose a raw query. Values bind; only literals/ident/raw become text. */
+export function sql(
+  strings: TemplateStringsArray,
+  ...values: readonly SqlInterpolation[]
+): SqlFragment {
+  let text = '';
+  const params: SqlValue[] = [];
+  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 as readonly SqlValue[]));
+      }
+    } 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: string, allowlist: readonly string[]): SqlFragment => {
+  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: string): SqlFragment => fragment(text, []);

package/src/worker-entry.ts

@@ -332,6 +332,13 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       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());