@doync/client 0.1.0

package/src/identity.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-(Database name, identity) replica filename (CONTEXT.md Database name;
+ * ADR-0019 addendum / closeio/doync#187 / #321) — a PURE helper shared by every
+ * platform that owns a durable replica file (web OPFS, mobile op-sqlite, …).
+ *
+ * The file key is `(name, userId)`: two Database names in one app never collide
+ * on the same store, and each identity (`doync__<name>__<userId|anon>.db`) owns
+ * its own replica, clientId, cookie, and pending queue so a shared device never
+ * leaks one user's rows into another's session. The id is percent-encoded so an
+ * exotic identity can never escape the filename (a `/` would otherwise mean a
+ * subpath); a numeric/alphanumeric id (the common case, e.g. a GitHub id)
+ * encodes to itself, keeping the file readable. Pre-release: no migration of
+ * pre-#187 / pre-#321 filenames — wipe/redeploy owns the cutover.
+ */
+
+/**
+ * Encode one half of the replica filename so it cannot contain the format's
+ * `__` separator and cannot form a path segment (`/`, etc.).
+ *
+ * `encodeURIComponent` leaves `_` intact; escaping `_` → `%5F` keeps `(name:
+ * 'a__b', user: 'c')` from colliding with `(name: 'a', user: 'b__c')`.
+ * UUID-shaped names (hyphens only) encode to themselves.
+ */
+function encodeHalf(value: string): string {
+  return encodeURIComponent(value).replaceAll('_', '%5F')
+}
+
+/**
+ * Durable replica file for one `(Database name, asserted userId)` pair:
+ * `doync__<name>__anon.db` when `userId` is `null`, else
+ * `doync__<name>__<userId>.db`. Separators are `__` so hyphens (common in UUIDs
+ * and ids) stay unescaped and filenames stay short enough for OPFS. Each half
+ * is percent-encoded; `_` is additionally escaped so halves cannot forge a
+ * separator.
+ */
+export function dbFileForUserId(name: string, userId: string | null): string {
+  const encodedName = encodeHalf(name)
+  return userId === null
+    ? `doync__${encodedName}__anon.db`
+    : `doync__${encodedName}__${encodeHalf(userId)}.db`
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * `@doync/client` public surface (ADR-0033): the app-facing call-surface types
+ * adapters wrap (`DoyncClient`, views, mutation types, connection + schema
+ * status, `LogoutBehavior`). Nothing callable remains on this entry —
+ * construction is `@doync/client/adapter` (`createClient`) or
+ * `@doync/client/internal` (`createClientEngine`). The real consumer packages
+ * are `@doync/web`, `@doync/mobile`, and `@doync/react`.
+ *
+ * Host seams, reconnect, and `createClient` live under `./adapter`. Engine
+ * construction internals and mutation-registry helpers live under
+ * `./internal`.
+ */
+
+export type { LogoutBehavior } from './client'
+export type {
+  ConnectionStatus,
+  DoyncClient,
+  FalsyQuery,
+  MutationOptions,
+  MutationResult,
+  OnceView,
+  PreloadHandle,
+  PreloadOptions,
+  QueryStatus,
+  SchemaEvent,
+  SchemaEventKind,
+  SubscribeOptions,
+  View,
+  ViewStatus,
+} from './engine'
+export type {
+  ClientMutation,
+  ClientMutationHandler,
+  ClientMutationRegistry,
+  ClientMutationTx,
+} from './mutations'

package/src/internal.ts

@@ -0,0 +1,37 @@
+/**
+ * `@doync/client/internal` (ADR-0033): engine construction, replica DDL, meta
+ * keys, mutation flattening, surface-normalize helpers, and mutation-registry
+ * dispatch plumbing. May break in any release. App-facing call-surface types
+ * live on the main entry (`@doync/client`); host seams / reconnect /
+ * `createClient` live on `@doync/client/adapter` — import those from their
+ * entries, not here (no double-listing).
+ */
+
+export { createClientEngine } from './client'
+export { toClientMutationRegistry } from './client-mutation-registry'
+export {
+  ClientEngine,
+  __CONNECTED_CLOCK_META_KEY,
+  __LOGOUT_BEHAVIOR_META_KEY,
+  settledRejection,
+  isFalsyQuery,
+  normalizeQuerySurface,
+  type ClientEngineConfig,
+} from './engine'
+export { dbFileForUserId } from './identity'
+export {
+  bundledSchemaDdl,
+  classifyClientStatement,
+  splitClientStatements,
+  type ClientStatementKind,
+} from './migrate'
+export { asClientMutation, validateMutationArgs } from './mutations'
+export { extractWriteTable } from './port'
+export {
+  applyBundledMigrations,
+  createEngineTables,
+  dropConsumerTables,
+  readMeta,
+  replayMigrations,
+  writeMeta,
+} from './replica'

package/src/migrate.ts

@@ -0,0 +1,156 @@
+import type { DoyncSchema } from '@doync/core'
+
+import {
+  parse,
+  parseAll,
+  SQLiteParserError,
+  unparse,
+  type Statement,
+} from '@doync/sqlite-parser'
+
+/**
+ * Parser-backed SQL classification for client DDL-only bundled-track replay
+ * (ADR-0020 / ADR-0006). Same AST as the server conversation, narrower API: 1.
+ * split migrations keeping trigger BEGIN…END whole; 2. ddl vs trigger (skip —
+ * apply state, never enforce; ADR-0009/0020) vs backfill DML (skip — data via
+ * feed; ADR-0006). Fails closed on unparseable input.
+ */
+
+/** How the client treats one already-split migration statement. */
+export type ClientStatementKind = 'ddl' | 'trigger' | 'dml' | 'pragma' | 'other'
+
+/** Statement kinds recorded as replayable schema DDL (shape, not triggers). */
+const DDL_KINDS = new Set<Statement['kind']>([
+  'STMT_CREATE_TABLE',
+  'STMT_CREATE_INDEX',
+  'STMT_CREATE_VIEW',
+  'STMT_CREATE_VTABLE',
+  'STMT_DROP',
+  'STMT_ALTER',
+])
+
+/**
+ * Statement kinds that read or write rows. Backfill DML is never replayed on
+ * the client — data arrives through the feed (ADR-0006).
+ */
+const DML_KINDS = new Set<Statement['kind']>([
+  'STMT_INSERT',
+  'STMT_UPDATE',
+  'STMT_DELETE',
+  'STMT_SELECT',
+  'COMPOUND_SELECT',
+])
+
+/**
+ * Parse one statement, or `null` when the input is unparseable or empty. Only a
+ * parser error maps to `null`; anything else propagates. `parse` validates the
+ * whole input and returns the FIRST statement (extras are dropped), so a string
+ * that begins with a valid statement classifies by that statement.
+ */
+function parseFirstOrNull(statement: string): Statement | null {
+  try {
+    return parse(statement)
+  } catch (error) {
+    if (error instanceof SQLiteParserError) return null
+    throw error
+  }
+}
+
+/**
+ * Parse a whole script into its statements, or `null` on a parser error (empty
+ * input yields an empty list, never `null`). Only a parser error maps to
+ * `null`; anything else propagates — the one place the parse-failure decision
+ * lives.
+ */
+function parseAllOrNull(sql: string): Statement[] | null {
+  try {
+    return parseAll(sql)
+  } catch (error) {
+    if (error instanceof SQLiteParserError) return null
+    throw error
+  }
+}
+
+/** Map a parsed statement to the client's kind bucket. */
+function classOf(statement: Statement): ClientStatementKind {
+  // Triggers first — clients never install/drop them (ADR-0009/0020).
+  if (statement.kind === 'STMT_CREATE_TRIGGER') return 'trigger'
+  if (statement.kind === 'STMT_DROP' && statement.target === 'TRIGGER') {
+    return 'trigger'
+  }
+  if (statement.kind === 'STMT_PRAGMA') return 'pragma'
+  // Remaining DDL is shape-replayable (CREATE TRIGGER not in DDL_KINDS).
+  if (DDL_KINDS.has(statement.kind)) return 'ddl'
+  if (DML_KINDS.has(statement.kind)) return 'dml'
+  return 'other'
+}
+
+/**
+ * Split a migration's SQL into its top-level statements. The parser understands
+ * statement structure, so a `CREATE TRIGGER … BEGIN … END` body's internal
+ * semicolons stay inside one statement — a migration may mix a trigger with
+ * surrounding DDL without mis-splitting. Each statement is returned as its
+ * canonical unparse (semantically identical to the source); statements that are
+ * empty (whitespace/comments only) yield nothing.
+ *
+ * Fails closed: an unparseable script throws a clear error rather than applying
+ * a partial or mis-read migration. Trusted input only in the sense that the
+ * consumer authored the migrations — the parse itself validates their syntax.
+ */
+export function splitClientStatements(sql: string): string[] {
+  const statements = parseAllOrNull(sql)
+  if (statements === null) {
+    throw new Error(
+      'could not parse the SQL — a statement has a syntax error; fix it and retry',
+    )
+  }
+  return statements.map((statement) => unparse(statement))
+}
+
+/**
+ * Classify ONE already-split statement by its parsed kind. `CREATE TRIGGER` and
+ * `DROP TRIGGER` are `'trigger'` (the client neither creates nor drops triggers
+ * — it runs none, ADR-0009); every other shape-changing DDL is `'ddl'`
+ * (replayed); the row read/write verbs are `'dml'` (backfill, never replayed on
+ * the client); `PRAGMA` and anything unrecognized/unparseable land in their own
+ * buckets.
+ */
+export function classifyClientStatement(
+  statement: string,
+): ClientStatementKind {
+  const parsed = parseFirstOrNull(statement)
+  return parsed === null ? 'other' : classOf(parsed)
+}
+
+/**
+ * The non-trigger DDL statements of the bundled migrations in the half-open
+ * range `(fromVersion, toVersion]` (0-based migration indices `fromVersion …
+ * toVersion − 1`), in order — the replayable shape for the client's DDL-only
+ * bundled-track replay (ADR-0020). Trigger DDL is skipped (ADR-0009) and
+ * backfill DML never runs on the client (ADR-0006). Passing `fromVersion = 0`
+ * yields the full track up to `toVersion` (a fresh replica); a higher
+ * `fromVersion` yields just the newly-appended migrations (a mid-session
+ * catch-up).
+ */
+export function bundledSchemaDdl(
+  schema: DoyncSchema,
+  fromVersion: number,
+  toVersion: number,
+): string[] {
+  const ddl: string[] = []
+  for (let version = fromVersion; version < toVersion; version += 1) {
+    const migration = schema.migrations[version]
+    if (migration === undefined) {
+      // Dense track — hole or past-end means corrupt/truncated; fail loud.
+      throw new Error(
+        `doync: bundled migration track has a hole at version ${version} ` +
+          `(requested range ${fromVersion}..${toVersion}, but the track holds ` +
+          `${schema.migrations.length}) — the schema is corrupt or truncated`,
+      )
+    }
+    for (const statement of splitClientStatements(migration.sql)) {
+      if (classifyClientStatement(statement) === 'ddl') ddl.push(statement)
+    }
+  }
+  return ddl
+}

package/src/mutations.ts

@@ -0,0 +1,96 @@
+import type { SqlValue } from '@doync/core'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
+import {
+  assertWireRepresentable,
+  canonicalizeArgsBinary,
+} from '@doync/core/internal'
+
+import type { LocalRow } from './port'
+
+/**
+ * Write surface a client mutation body runs against: one parameterized
+ * statement at a time inside the mutation's savepoint, returning its rows. Same
+ * shape the Origin uses, so a shared body runs identically on device and
+ * server.
+ */
+export interface ClientMutationTx {
+  exec<T extends LocalRow = LocalRow>(query: string, ...params: SqlValue[]): T[]
+}
+
+/**
+ * Client mutation body `(args, ctx, sql)`. Must be deterministic and DB-only
+ * (may still be async for local work). Generate ids on the client and pass them
+ * in `args` — the body is replayed on rebase. External I/O belongs in a server
+ * override, not the client bundle.
+ */
+export type ClientMutationHandler = (
+  args: unknown,
+  ctx: Record<string, unknown>,
+  sql: ClientMutationTx,
+) => void | Promise<void>
+
+/**
+ * A registered client mutation: body plus optional standard-schema args
+ * validator applied at `mutate()` time. A bare handler is also accepted.
+ */
+export interface ClientMutation {
+  readonly args?: StandardSchemaV1
+  readonly handler: ClientMutationHandler
+}
+
+/**
+ * Name-keyed client mutation registry. Keys match the server's dotted names so
+ * a push reaches the matching authoritative body.
+ */
+export type ClientMutationRegistry = Readonly<
+  Record<string, ClientMutation | ClientMutationHandler>
+>
+
+/**
+ * Normalize a registry entry (bare handler or `{args, handler}`) to the object
+ * form.
+ */
+export function asClientMutation(
+  entry: ClientMutation | ClientMutationHandler,
+): ClientMutation {
+  return typeof entry === 'function' ? { handler: entry } : entry
+}
+
+/**
+ * Validate `args` through a standard-schema synchronously (mirrors
+ * `@doync/core` query-args). Async validators refuse loudly — the body is
+ * deterministic on both ends. Returns validated value or throws.
+ */
+export function validateMutationArgs(
+  schema: StandardSchemaV1,
+  args: unknown,
+): unknown {
+  // Unrepresentable leaves before schema (ADR-0031 / #231/#232). Binary
+  // allowed here; bare handlers skip this path so engine.mutate still guards
+  // every mutation. Double-run of guard+canonicalize on schema paths is
+  // intentional and cheap.
+  assertWireRepresentable(args, 'mutation args', { allowBinary: true })
+  // TypedArray/DataView → ArrayBuffer before standard-schema (ADR-0031 / #231).
+  const canonical = canonicalizeArgsBinary(args)
+  const result = schema['~standard'].validate(canonical)
+  if (result instanceof Promise) {
+    throw new Error(
+      'doync: async standard-schema validation is not supported for mutation args — use a synchronous validator',
+    )
+  }
+  if (result.issues !== undefined) {
+    const detail = result.issues
+      .map((issue) => {
+        const path = (issue.path ?? [])
+          .map((segment) =>
+            typeof segment === 'object' ? String(segment.key) : String(segment),
+          )
+          .join('.')
+        return path === '' ? issue.message : `${path}: ${issue.message}`
+      })
+      .join('; ')
+    throw new Error(`doync: mutation args failed validation — ${detail}`)
+  }
+  return result.value
+}

package/src/port.ts

@@ -0,0 +1,74 @@
+import type { SqlValue } from '@doync/core'
+import type { Statement } from '@doync/sqlite-parser'
+
+import { parse } from '@doync/sqlite-parser'
+
+/** One local-replica row: column name → {@link SqlValue}. */
+export interface LocalRow {
+  [column: string]: SqlValue
+}
+
+// ADR-0019 (synchronous local-DB port; platform adapters supply the impl).
+/**
+ * Synchronous local SQLite port the client engine drives. Platform adapters
+ * (wa-sqlite, node:sqlite, op-sqlite) implement this; app code does not.
+ * Transactions and savepoints are ordinary SQL via {@link LocalDb.exec}.
+ */
+export interface LocalDb {
+  /**
+   * Run one parameterized statement; return its rows (empty for writes/DDL/
+   * transaction control).
+   */
+  exec<T extends LocalRow = LocalRow>(sql: string, ...params: SqlValue[]): T[]
+
+  /**
+   * Run a multi-statement DDL script (no parameters). Used to replay bundled
+   * migrations when creating a fresh replica. Trusted input only.
+   */
+  execBatch(script: string): void
+
+  /**
+   * Consumer tables written since the last call, then clear the set. Used so
+   * only affected subscriptions re-project after a mutation or rebase.
+   */
+  drainWrittenTables(): Set<string>
+}
+
+/**
+ * Extract the target table of one WRITE statement from its SQL text — the
+ * adapter-side stand-in where no synchronous native change feed exists
+ * (ADR-0019): node:sqlite has no update hook, and op-sqlite's hook delivers
+ * callbacks via `invokeAsync` — a later event-loop turn, unusable for the
+ * engine's drain-after-apply contract (closeio/doync#202 device pass).
+ *
+ * A real parse over `@doync/sqlite-parser`, not a keyword recognizer: the AST
+ * attaches a `WITH …` CTE prefix to the DML node itself, so CTE-topped writes
+ * (`WITH src AS (…) INSERT INTO t …`) extract their target with no string
+ * games. Returns the unquoted table name for INSERT / REPLACE / UPDATE /
+ * DELETE, or `null` for a non-write (SELECT, SAVEPOINT, PRAGMA, DDL) or
+ * unparseable input.
+ *
+ * TRIGGER cascades remain invisible to statement text — and stay out of scope
+ * by design: client replicas carry no triggers (the bundled-track replay strips
+ * CREATE TRIGGER; ADR-0009 — clients apply state, never enforce).
+ */
+export function extractWriteTable(sql: string): string | null {
+  let statement: Statement
+  try {
+    statement = parse(sql)
+  } catch (err) {
+    console.warn('extractWriteTable: failed to parse SQL statement', {
+      sql,
+      err,
+    })
+    return null
+  }
+  switch (statement.kind) {
+    case 'STMT_INSERT':
+    case 'STMT_UPDATE':
+    case 'STMT_DELETE':
+      return statement.table ?? null
+    default:
+      return null
+  }
+}

package/src/raw-read.ts

@@ -0,0 +1,135 @@
+import type { SqlValue } from '@doync/core'
+
+import type { ViewStatus } from './engine'
+
+/**
+ * A resolved statement a raw read executes verbatim — the engine's INTERNAL
+ * currency (ADR-0021). Distinct from the wire's `DesiredQuery` (`{name, args}`,
+ * ADR-0016): the statement never leaves the device — the Mirror re-resolves the
+ * registered callback under its own verified ctx (ADR-0018).
+ */
+export interface LocalStatement {
+  readonly sql: string
+  readonly params: readonly SqlValue[]
+}
+
+/**
+ * What a {@link RawRead} needs from its host, injected at construction
+ * (ADR-0023: raw reads receive their narrow needs and know nothing of the
+ * engine). `run` executes the statement over the live replica; `readSet`
+ * answers the subscription's server-confirmed Read-set for targeted
+ * re-projection, or `undefined` before the ack / for a Local read. Both are
+ * plain accessors so a five-line fake makes the read unit-testable.
+ */
+export interface RawReadHost {
+  run(statement: LocalStatement): Record<string, SqlValue>[]
+  readSet(): ReadonlySet<string> | undefined
+}
+
+type AnyRow = Record<string, SqlValue>
+
+/**
+ * One shared reactive read per Query instance (ADR-0023 share-raw): executes
+ * the statement and dedups on RAW rows. No decoder here — identity excludes
+ * decode/one (ADR-0021), so identical SQL flavors share this read and each
+ * handle decodes (Q4). generation ticks on real change.
+ *
+ * Raw rows (scalars / JSON TEXT) equal cheaply; decoded nested objects cannot.
+ * Status (#104) is stable until the visible status moves; pending→acked is
+ * invisible.
+ */
+export class RawRead {
+  #raw: AnyRow[] = []
+  /** Bumped on real change — handles' decode-memo key. */
+  #generation = 0
+  readonly #listeners = new Set<() => void>()
+  #status: ViewStatus
+
+  constructor(
+    private readonly host: RawReadHost,
+    readonly statement: LocalStatement,
+    /** The Query instance identity; `undefined` for a Local read. */
+    readonly identity: string | undefined,
+    /** Seed status: phase, or complete for Local. */
+    initialStatus: ViewStatus,
+  ) {
+    this.#status = initialStatus
+  }
+
+  /** Subscription Read-set for targeted re-projection (via host). */
+  get readSet(): ReadonlySet<string> | undefined {
+    return this.identity === undefined ? undefined : this.host.readSet()
+  }
+
+  status(): ViewStatus {
+    return this.#status
+  }
+
+  updateStatus(next: ViewStatus): boolean {
+    if (
+      this.#status.status === next.status &&
+      this.#status.error === next.error
+    )
+      return false
+    this.#status = next
+    return true
+  }
+
+  /** Re-run statement; true iff raw rows moved. */
+  recompute(): boolean {
+    const rows = this.host.run(this.statement)
+    if (rowsEqual(rows, this.#raw)) return false
+    this.#raw = rows
+    this.#generation += 1
+    return true
+  }
+
+  /** Undecoded rows (handles decode against generation). */
+  rawRows(): readonly AnyRow[] {
+    return this.#raw
+  }
+
+  get generation(): number {
+    return this.#generation
+  }
+
+  onChange(listener: () => void): () => void {
+    this.#listeners.add(listener)
+    return () => this.#listeners.delete(listener)
+  }
+
+  notify(): void {
+    for (const listener of this.#listeners) listener()
+  }
+}
+
+/**
+ * Scalar equality on raw SQL rows — keeps `current()` stable between changes
+ * (useSyncExternalStore).
+ */
+export function rowsEqual(a: readonly AnyRow[], b: readonly AnyRow[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    const ra = a[i] as AnyRow
+    const rb = b[i] as AnyRow
+    const ka = Object.keys(ra)
+    if (ka.length !== Object.keys(rb).length) return false
+    for (const k of ka) {
+      if (!valuesEqual(ra[k] ?? null, rb[k] ?? null)) return false
+    }
+  }
+  return true
+}
+
+/** SqlValue equality: === for scalars, byte-wise BLOBs (ADR-0010). */
+function valuesEqual(a: SqlValue, b: SqlValue): boolean {
+  if (a === b) return true
+  if (a instanceof ArrayBuffer && b instanceof ArrayBuffer) {
+    if (a.byteLength !== b.byteLength) return false
+    const va = new Uint8Array(a)
+    const vb = new Uint8Array(b)
+    for (let i = 0; i < va.length; i++) if (va[i] !== vb[i]) return false
+    return true
+  }
+  return false
+}

package/src/replica/db/0000_replica_engine_v0.sql

@@ -0,0 +1,20 @@
+CREATE TABLE `__doync_membership` (
+	`instance` text NOT NULL,
+	`level` integer NOT NULL,
+	`tbl` text NOT NULL,
+	`pk` text NOT NULL,
+	PRIMARY KEY(`instance`, `level`, `pk`)
+) WITHOUT ROWID;
+--> statement-breakpoint
+CREATE INDEX `__doync_membership_by_row` ON `__doync_membership` (`tbl`,`pk`);--> statement-breakpoint
+CREATE TABLE `__doync_meta` (
+	`k` text PRIMARY KEY NOT NULL,
+	`v` blob
+) WITHOUT ROWID;
+--> statement-breakpoint
+CREATE TABLE `__doync_pending` (
+	`mutation_id` integer PRIMARY KEY NOT NULL,
+	`name` text NOT NULL,
+	`args` text NOT NULL,
+	`idem_key` text
+);

package/src/replica/db/0001_release_stamps.sql

@@ -0,0 +1,6 @@
+CREATE TABLE `__doync_release_stamp` (
+	`instance` text PRIMARY KEY NOT NULL,
+	`cookie` integer NOT NULL,
+	`released_at` integer NOT NULL,
+	`ttl_ms` integer NOT NULL
+) WITHOUT ROWID;