@doync/client 0.1.0

package/src/replica/db/meta/0000_snapshot.json

@@ -0,0 +1,129 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "cc24a082-981e-465f-858f-24aab93bf4d1",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "__doync_membership": {
+      "name": "__doync_membership",
+      "columns": {
+        "instance": {
+          "name": "instance",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "level": {
+          "name": "level",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "tbl": {
+          "name": "tbl",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "pk": {
+          "name": "pk",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "__doync_membership_by_row": {
+          "name": "__doync_membership_by_row",
+          "columns": ["tbl", "pk"],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {
+        "__doync_membership_instance_level_pk_pk": {
+          "columns": ["instance", "level", "pk"],
+          "name": "__doync_membership_instance_level_pk_pk"
+        }
+      },
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "__doync_meta": {
+      "name": "__doync_meta",
+      "columns": {
+        "k": {
+          "name": "k",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "v": {
+          "name": "v",
+          "type": "blob",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "__doync_pending": {
+      "name": "__doync_pending",
+      "columns": {
+        "mutation_id": {
+          "name": "mutation_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "args": {
+          "name": "args",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "idem_key": {
+          "name": "idem_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/src/replica/db/meta/0001_snapshot.json

@@ -0,0 +1,167 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "9b4ee178-f435-4f98-aebf-234ba0657b6d",
+  "prevId": "cc24a082-981e-465f-858f-24aab93bf4d1",
+  "tables": {
+    "__doync_membership": {
+      "name": "__doync_membership",
+      "columns": {
+        "instance": {
+          "name": "instance",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "level": {
+          "name": "level",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "tbl": {
+          "name": "tbl",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "pk": {
+          "name": "pk",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "__doync_membership_by_row": {
+          "name": "__doync_membership_by_row",
+          "columns": ["tbl", "pk"],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {
+        "__doync_membership_instance_level_pk_pk": {
+          "columns": ["instance", "level", "pk"],
+          "name": "__doync_membership_instance_level_pk_pk"
+        }
+      },
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "__doync_meta": {
+      "name": "__doync_meta",
+      "columns": {
+        "k": {
+          "name": "k",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "v": {
+          "name": "v",
+          "type": "blob",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "__doync_pending": {
+      "name": "__doync_pending",
+      "columns": {
+        "mutation_id": {
+          "name": "mutation_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "args": {
+          "name": "args",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "idem_key": {
+          "name": "idem_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "__doync_release_stamp": {
+      "name": "__doync_release_stamp",
+      "columns": {
+        "instance": {
+          "name": "instance",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cookie": {
+          "name": "cookie",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "released_at": {
+          "name": "released_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "ttl_ms": {
+          "name": "ttl_ms",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/src/replica/db/meta/_journal.json

@@ -0,0 +1,20 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1784031358638,
+      "tag": "0000_replica_engine_v0",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1784450022155,
+      "tag": "0001_release_stamps",
+      "breakpoints": true
+    }
+  ]
+}

package/src/replica/db/schema.ts

@@ -0,0 +1,67 @@
+/**
+ * Replica engine tables (ADR-0024) — client-role Drizzle schema, unshared with
+ * Origin/Mirror (similar `__doync_meta` is coincidence).
+ *
+ * - `__doync_meta` — durable clientId, next-mutid, cookie, schema version, logout
+ *   behavior, connected clock (#223) as k/v; `v` blob for store-as-bound.
+ * - `__doync_pending` — optimistic queue outside the overlay savepoint.
+ * - `__doync_membership` — retraction refcount (instance, level, pk); EXISTS
+ *   last-ref delete (ADR-0013); by-row index on (tbl, pk).
+ * - `__doync_release_stamp` — parked releases for heldAt (#225) and GC (#226);
+ *   only while released; wiped with memberships on resync/forget.
+ *
+ * Consumer tables arrive via bundled migrations + patches. Ledger
+ * `__doync_engine` is created unversioned by `runReplicaEngineTrack`.
+ */
+import {
+  blob,
+  index,
+  integer,
+  primaryKey,
+  sqliteTable,
+  text,
+} from 'drizzle-orm/sqlite-core'
+
+/** Client durable kv — see module docblock. without rowid */
+export const doyncMeta = sqliteTable('__doync_meta', {
+  k: text('k').primaryKey(),
+  // blob affinity: store-as-bound for mixed number/string values (ADR-0024)
+  v: blob('v'),
+})
+
+/** Durable optimistic mutation queue. (rowid table — INTEGER PRIMARY KEY) */
+export const doyncPending = sqliteTable('__doync_pending', {
+  mutationId: integer('mutation_id').primaryKey(),
+  name: text('name').notNull(),
+  args: text('args').notNull(),
+  idemKey: text('idem_key'),
+})
+
+/** Client-side membership refcount. without rowid */
+export const doyncMembership = sqliteTable(
+  '__doync_membership',
+  {
+    instance: text('instance').notNull(),
+    level: integer('level').notNull(),
+    tbl: text('tbl').notNull(),
+    pk: text('pk').notNull(),
+  },
+  (t) => [
+    primaryKey({ columns: [t.instance, t.level, t.pk] }),
+    index('__doync_membership_by_row').on(t.tbl, t.pk),
+  ],
+)
+
+/**
+ * Durable release stamp per parked Query instance (ADR-0014 client half /
+ * closeio/doync#224). `cookie` is the Client's scalar cookie at last-release
+ * (the future `heldAt` claim); `released_at` is that moment in connected-clock
+ * units; `ttl_ms` is the resolved grace (declared, else the internal 30m
+ * default matching the server's DEFAULT_QUERY_TTL_MS). without rowid
+ */
+export const doyncReleaseStamp = sqliteTable('__doync_release_stamp', {
+  instance: text('instance').primaryKey(),
+  cookie: integer('cookie').notNull(),
+  releasedAt: integer('released_at').notNull(),
+  ttlMs: integer('ttl_ms').notNull(),
+})

package/src/replica/index.ts

@@ -0,0 +1,185 @@
+import type { DoyncSchema, SqlValue, TableSchema } from '@doync/core'
+
+import {
+  decodeImageValue,
+  decodePkValue,
+  declaredSchemaVersion,
+  isInternalTable,
+  isSqlIdentifier,
+  tablePrimaryKey,
+} from '@doync/core/internal'
+
+import type { LocalDb } from '../port'
+
+import { bundledSchemaDdl } from '../migrate'
+import { readMeta, writeMeta } from './meta'
+import { runReplicaEngineTrack } from './track'
+
+export { readMeta, writeMeta } from './meta'
+export {
+  clearReleaseStamps,
+  DEFAULT_RELEASE_TTL_MS,
+  deleteReleaseStamp,
+  listReleaseStamps,
+  readReleaseStamp,
+  resolveReleaseTtlMs,
+  upsertReleaseStamp,
+  type ReleaseStamp,
+} from './stamps'
+export {
+  REPLICA_ENGINE_TRACK,
+  runReplicaEngineTrack,
+  type EngineTrackResult,
+  type EngineTrackStep,
+} from './track'
+
+/**
+ * The replica-side helpers the engine uses to apply patches to the consumer's
+ * local tables (ADR-0013/0019). The client holds a REAL partial-Mirror replica:
+ * whole rows land in the consumer's own tables so Local reads and subscription
+ * snapshots run ordinary SQL over them. These mirror the server's `sql.ts`
+ * pk/image plumbing, kept minimal and client-local (the server module is not a
+ * shared export).
+ */
+
+/** Quote a validated identifier for interpolation (never user text). */
+export function quoteIdent(name: string): string {
+  if (!isSqlIdentifier(name)) {
+    throw new Error(
+      `doync: refusing to quote non-identifier ${JSON.stringify(name)}`,
+    )
+  }
+  return `"${name}"`
+}
+
+/**
+ * Parse a canonical serialized primary key (ADR-0003: a JSON array of the pk
+ * column values in key order, BLOB parts as hex-tagged objects) into bound
+ * values, in the table's key order. The `pk` on a wire `Patch` is exactly this
+ * form.
+ */
+export function parsePk(pk: string, table: TableSchema): SqlValue[] {
+  const parts: unknown = JSON.parse(pk)
+  const key = tablePrimaryKey(table)
+  if (!Array.isArray(parts) || parts.length !== key.length) {
+    throw new Error(
+      `doync: malformed pk ${pk} for table ${table.name} (expected ${key.length} key part(s))`,
+    )
+  }
+  return parts.map((part) => decodePkValue(part))
+}
+
+/** `pk_a = ? AND pk_b = ?` over a table's primary-key columns, in key order. */
+export function pkWhereClause(table: TableSchema): string {
+  return tablePrimaryKey(table)
+    .map((column) => `${quoteIdent(column)} = ?`)
+    .join(' AND ')
+}
+
+/**
+ * Decode a wire `PutPatch.image` (a codec-tagged row object, ADR-0010) into a
+ * parallel columns/values pair for an INSERT — the same one decode path the
+ * server's apply uses. A tagged blob becomes an `ArrayBuffer`; a scalar passes
+ * through; column names are validated as SQL identifiers before interpolation.
+ */
+export function decodePatchImage(
+  table: TableSchema,
+  image: Record<string, unknown>,
+): { columns: string[]; values: SqlValue[] } {
+  const columns = Object.keys(image)
+  for (const column of columns) {
+    if (!isSqlIdentifier(column)) {
+      throw new Error(
+        `doync: patch image for table ${table.name} has an invalid column name ${JSON.stringify(column)}`,
+      )
+    }
+  }
+  return {
+    columns,
+    values: columns.map((column) => decodeImageValue(image[column])),
+  }
+}
+
+/** Look a synced table up by name; throw if the schema does not declare it. */
+export function requireTable(schema: DoyncSchema, name: string): TableSchema {
+  const table = schema.tables.find((t) => t.name === name)
+  if (table === undefined) {
+    throw new Error(
+      `doync: no synced table named ${JSON.stringify(name)} in the client schema`,
+    )
+  }
+  return table
+}
+
+/**
+ * Apply the Replica engine track via `__doync_engine` ledger (ADR-0024 / #159).
+ * LocalDb twin of server `runEngineTrack`. Returns whether rollback tripwire
+ * fired (caller finishes consumer wipe-and-resync). Named `createEngineTables`
+ * for stable call sites.
+ */
+export function createEngineTables(db: LocalDb): {
+  rolledBack: boolean
+} {
+  return runReplicaEngineTrack(db)
+}
+
+/**
+ * Boot replica shape via DDL-only bundled track (ADR-0020). Fresh client is a
+ * partial Mirror of the same migrations (triggers skipped, FKs off ADR-0009;
+ * backfill skipped ADR-0006).
+ *
+ * - Fresh (no schema_version): full bundle track.
+ * - Persisted: leave recorded shape; new migrations arrive mid-session as
+ *   `schema` directives ({@link applyBundledMigrations}), not at boot.
+ */
+export function replayMigrations(db: LocalDb, schema: DoyncSchema): void {
+  if (readMeta(db, 'schema_version') !== null) return
+  applyBundledMigrations(db, schema, 0, declaredSchemaVersion(schema))
+}
+
+/**
+ * Apply the bundled track's non-trigger DDL for the migrations in
+ * `(fromVersion, toVersion]` to the replica and record `toVersion` as the
+ * applied `schema_version`. The single primitive behind both fresh boot replay
+ * ({@link replayMigrations} with `fromVersion = 0`) and a mid-session catch-up
+ * (`fromVersion =` the currently applied version). The DDL text is the client's
+ * OWN bundle (never wire-carried — ADR-0020); a `CREATE TABLE` from a fresh
+ * base and an `ALTER TABLE … ADD COLUMN` catch-up both keep any rows already
+ * present (SQLite ADD COLUMN preserves rows). Throws if a statement fails — the
+ * caller turns a failed local migration into wipe-and-resync (ADR-0020).
+ */
+export function applyBundledMigrations(
+  db: LocalDb,
+  schema: DoyncSchema,
+  fromVersion: number,
+  toVersion: number,
+): void {
+  for (const ddl of bundledSchemaDdl(schema, fromVersion, toVersion)) {
+    db.execBatch(ddl)
+  }
+  writeMeta(db, 'schema_version', String(toVersion))
+}
+
+/**
+ * Drop every consumer (synced) table (ADR-0020's wipe fallback): the first step
+ * of wipe-replica-and-resync, run with foreign keys already off so no cascade
+ * fires and drop order is irrelevant (ADR-0009). `__doync_`-prefixed engine
+ * tables — the pending queue, clientId, and `__doync_engine` ledger that
+ * SURVIVE the wipe — are left untouched.
+ */
+export function dropConsumerTables(db: LocalDb, schema: DoyncSchema): void {
+  for (const table of schema.tables) {
+    db.exec(`DROP TABLE IF EXISTS ${quoteIdent(table.name)}`)
+  }
+}
+
+/** Assert the schema declares no `__doync_`-prefixed synced table (ADR-0007). */
+export function assertNoReservedTables(schema: DoyncSchema): void {
+  for (const table of schema.tables) {
+    if (isInternalTable(table.name)) {
+      throw new Error(
+        `doync: synced table ${table.name} uses the reserved __doync_ prefix`,
+      )
+    }
+  }
+}

package/src/replica/meta.ts

@@ -0,0 +1,26 @@
+import type { SqlValue } from '@doync/core'
+
+import type { LocalDb } from '../port'
+
+/**
+ * Read one `__doync_meta` value, or `null` if unset. Columns are `k`/`v`
+ * (ADR-0024).
+ */
+export function readMeta(db: LocalDb, key: string): string | null {
+  const row = db.exec<{ v: SqlValue }>(
+    `SELECT v FROM __doync_meta WHERE k = ?`,
+    key,
+  )[0]
+  if (row === undefined || row.v === null) return null
+  return String(row.v)
+}
+
+/** Upsert one `__doync_meta` value. Columns are `k`/`v` (ADR-0024). */
+export function writeMeta(db: LocalDb, key: string, value: string): void {
+  db.exec(
+    `INSERT INTO __doync_meta (k, v) VALUES (?, ?)
+       ON CONFLICT (k) DO UPDATE SET v = excluded.v`,
+    key,
+    value,
+  )
+}

package/src/replica/stamps.ts

@@ -0,0 +1,102 @@
+import type { LocalDb } from '../port'
+
+/**
+ * Durable release stamp for one parked Query instance (ADR-0014 client half /
+ * closeio/doync#224). Shared infrastructure for `heldAt` (#225) and membership
+ * GC (#226) — package-internal, no public consumer surface.
+ *
+ * Lifecycle: written at last-release; deleted on re-desire and on an ADR-0028
+ * warmth-break; wiped with memberships on resync/forget (a stamp must never
+ * outlive the memberships it vouches for).
+ */
+export type ReleaseStamp = {
+  readonly instance: string
+  /** Client scalar cookie at last-release — the future `heldAt` claim. */
+  readonly cookie: number
+  /** Release moment in connected-clock units (ms). */
+  readonly releasedAt: number
+  /**
+   * Resolved grace in ms — the Subscription's declared ttl, or the internal
+   * default (mirrors the server's DEFAULT_QUERY_TTL_MS; no public knob).
+   */
+  readonly ttlMs: number
+}
+
+/**
+ * Fallback when a Subscription declares no ttl — mirrors server
+ * DEFAULT_QUERY_TTL_MS (30m). Not a public knob; duplicated so client does not
+ * depend on server.
+ */
+export const DEFAULT_RELEASE_TTL_MS: number = 30 * 60 * 1000
+
+/** Resolve the stamp's recorded ttl: declared value, else the internal default. */
+export function resolveReleaseTtlMs(declared: number | undefined): number {
+  return declared === undefined ? DEFAULT_RELEASE_TTL_MS : declared
+}
+
+/** Upsert one stamp (at most one per instance; a re-release overwrites). */
+export function upsertReleaseStamp(db: LocalDb, stamp: ReleaseStamp): void {
+  db.exec(
+    `INSERT INTO __doync_release_stamp (instance, cookie, released_at, ttl_ms)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT (instance) DO UPDATE SET
+         cookie = excluded.cookie,
+         released_at = excluded.released_at,
+         ttl_ms = excluded.ttl_ms`,
+    stamp.instance,
+    stamp.cookie,
+    stamp.releasedAt,
+    stamp.ttlMs,
+  )
+}
+
+/** Delete the stamp for one instance (no-op when absent). */
+export function deleteReleaseStamp(db: LocalDb, instance: string): void {
+  db.exec(`DELETE FROM __doync_release_stamp WHERE instance = ?`, instance)
+}
+
+/** Drop every stamp — paired with membership wipe on resync/forget. */
+export function clearReleaseStamps(db: LocalDb): void {
+  db.exec(`DELETE FROM __doync_release_stamp`)
+}
+
+type StampRow = {
+  instance: string | number
+  cookie: number | string
+  released_at: number | string
+  ttl_ms: number | string
+}
+
+function rowToStamp(row: StampRow): ReleaseStamp {
+  return {
+    instance: String(row.instance),
+    cookie: Number(row.cookie),
+    releasedAt: Number(row.released_at),
+    ttlMs: Number(row.ttl_ms),
+  }
+}
+
+/** Read one stamp by instance identity, or `null` when none. */
+export function readReleaseStamp(
+  db: LocalDb,
+  instance: string,
+): ReleaseStamp | null {
+  const row = db.exec<StampRow>(
+    `SELECT instance, cookie, released_at, ttl_ms
+       FROM __doync_release_stamp WHERE instance = ?`,
+    instance,
+  )[0]
+  return row === undefined ? null : rowToStamp(row)
+}
+
+/**
+ * Enumerate every parked stamp (closeio/doync#226 hygiene GC walks this). Order
+ * is unspecified.
+ */
+export function listReleaseStamps(db: LocalDb): ReleaseStamp[] {
+  return db
+    .exec<StampRow>(
+      `SELECT instance, cookie, released_at, ttl_ms FROM __doync_release_stamp`,
+    )
+    .map(rowToStamp)
+}