@super-line/collections-cloudflare 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 Generated from conventional commits by [git-cliff](https://git-cliff.org) —
 run `pnpm changelog` rather than editing by hand.
 
+## [collections-cloudflare-v0.2.0] — 2026-10-20
+
+### Features
+
+- **collections-cloudflare:** A foreign object's SQLite as a live collection ([a9579af])
+
+### Bug Fixes
+
+- **collections-cloudflare:** ReadOnly catches writes in every statement ([e391e8e])
+
 ## [collections-cloudflare-v0.1.0] — 2026-10-15
 
 ### Features

package/README.md

@@ -38,7 +38,67 @@ A new optional field is altered in on the first operation. Any other change —
 
 The backend owns the `col_<name>` and `col_meta` tables in the object's storage.
 
+## Serve another object's tables
+
+`syncedSql` and `remoteRows` serve the tables of *other* Durable Objects — sources whose tables are created at runtime by arbitrary SQL — as one live, read-only collection on the node. Declare it on the contract with `remoteRowsCollection` from the `/contract` subpath, which imports only `zod` and `@super-line/core`:
+
+```ts
+import { remoteRowsCollection } from '@super-line/collections-cloudflare/contract'
+
+export const contract = defineContract({ roles, plugins: [remoteRowsCollection('storeRows')] })
+// rows: { key: `${storeId}:${table}:${id}`, storeId, table, id, data } — each row's columns opaque under `data`
+```
+
+In the source, `syncedSql(ctx, { onChange })` captures every row change with SQLite triggers, and pushes each committed batch to the node. Route every write through its `query`, and expose its reads for the node:
+
+```ts
+import { DurableObject } from 'cloudflare:workers'
+import { syncedSql, type QueryOptions, type Statement } from '@super-line/collections-cloudflare'
+
+export class Store extends DurableObject<Env> {
+  private sync = syncedSql(this.ctx, {
+    onChange: (push) => {
+      const [node, storeId] = this.ctx.id.name!.split(':') as [string, string]
+      return this.env.NODE.getByName(node).storeChanged(storeId, push)
+    },
+  })
+  query(statements: Statement[], opts?: QueryOptions) { return this.sync.query(statements, opts) }
+  snapshot(table: string, limit: number) { return this.sync.snapshot(table, limit) }
+  get(table: string, id: string) { return this.sync.get(table, id) }
+  changesSince(clock: number) { return this.sync.changesSince(clock) }
+}
+```
+
+On the node, `remoteRows` is a `self` backend fed by those pushes, served beside this package's own backend through `composeCollections` from `@super-line/server`:
+
+```ts
+export class Node extends createDurableNode((ctx, env, base) => {
+  const storeRows = remoteRows({
+    collection: 'storeRows',
+    storage: ctx.storage,
+    stub: (storeId) => env.STORE.getByName(`${ctx.id.name}:${storeId}`),
+    onWipe: (storeId) => closeReadersOf(storeId), // conn.raw.close(4409, 'resync') → they resubscribe into a fresh snapshot
+  })
+  const { storeRows: _, ...owned } = contract.collections
+  const server = createSuperLineServer(contract, {
+    ...base,
+    authenticate,
+    policies,
+    collections: composeCollections({ default: cloudflareCollections(ctx.storage, owned), storeRows }),
+  })
+  void server.ready.then(() => storeRows.resume()) // a wake restores subscriptions without reading the source: catch every source up
+  return Object.assign(server, { storeRows })
+}) {
+  storeChanged(storeId: string, push: RemotePush) {
+    return this.server.storeRows.ingest(storeId, push)
+  }
+}
+```
+
+A subscription must pin both `storeId` and `table` with `eq()`, and writes fail with `FORBIDDEN` — they go through the source's `query`. Dropping, renaming or altering a table, pruned deletes, a backlog over `maxPullChanges` or a reset source breaks that source's history: `onWipe` runs, and its subscribers resync. Store ids and table names must be colon-free. The source owns every `_sl_`-prefixed object in its SQLite.
+
 - 📖 Guide: [Host a node on Cloudflare Durable Objects](https://super-line.dogar.biz/how-to/cloudflare-durable-objects)
+- 📖 Guide: [Serve another Durable Object's tables](https://super-line.dogar.biz/how-to/cloudflare-remote-rows)
 - 📚 Reference: [Backends & clustering](https://super-line.dogar.biz/collections/backends)
 - 🧩 Source: <https://github.com/mertdogar/super-line>
 

package/dist/contract.d.ts

@@ -0,0 +1,66 @@
+import * as _super_line_core from '@super-line/core';
+import * as z from 'zod';
+
+/** A cell on the wire: SQLite's own types, with a blob as base64 under `blob`. */
+type Value = string | number | null | {
+    blob: string;
+};
+type Statement = {
+    sql: string;
+    params?: Value[];
+};
+type Result = {
+    columns: string[];
+    rows: Value[][];
+    meta: {
+        rowsRead: number;
+        rowsWritten: number;
+    };
+};
+/** `bytes` is set when the batch's rows passed `maxBytes`; the message then names the cap. */
+type Outcome = {
+    results: Result[];
+} | {
+    error: string;
+    statement: number;
+    bytes?: number;
+};
+/**
+ * `readOnly` rolls the batch back as soon as a statement writes a row or changes the schema; `maxBytes` rolls it
+ * back as soon as the serialized rows of the batch pass the cap.
+ */
+type QueryOptions = {
+    readOnly?: boolean;
+    maxBytes?: number;
+};
+/** One row of a source's table, as the node serves it. `key` is `${storeId}:${table}:${id}`. */
+declare const remoteRowSchema: z.ZodObject<{
+    key: z.ZodString;
+    storeId: z.ZodString;
+    table: z.ZodString;
+    id: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodNull, z.ZodObject<{
+        blob: z.ZodString;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>;
+type RemoteRowsRow = z.infer<typeof remoteRowSchema>;
+type RemoteRowsFragment<N extends string> = {
+    collections: {
+        [K in N]: {
+            schema: typeof remoteRowSchema;
+            key: 'key';
+        };
+    };
+};
+/**
+ * The contract half of `remoteRows`: one read-only collection `name` holding the rows of every source the node
+ * fronts, keyed `${storeId}:${table}:${id}`, with each row's columns opaque under `data`. Its own subpath, so a
+ * contract package doesn't pull in the Durable Object side.
+ *
+ * ```ts
+ * defineContract({ roles, plugins: [remoteRowsCollection('storeRows')] })
+ * ```
+ */
+declare function remoteRowsCollection<const N extends string>(name: N): _super_line_core.ContractPlugin<RemoteRowsFragment<N>>;
+
+export { type Outcome, type QueryOptions, type RemoteRowsRow, type Result, type Statement, type Value, remoteRowSchema, remoteRowsCollection };

package/dist/contract.js

@@ -0,0 +1,19 @@
+// src/contract.ts
+import * as z from "zod";
+import { defineContractPlugin } from "@super-line/core";
+var value = z.union([z.string(), z.number(), z.null(), z.object({ blob: z.string() })]);
+var remoteRowSchema = z.object({
+  key: z.string(),
+  storeId: z.string(),
+  table: z.string(),
+  id: z.string(),
+  data: z.record(z.string(), value)
+});
+function remoteRowsCollection(name) {
+  const fragment = { collections: { [name]: { schema: remoteRowSchema, key: "key" } } };
+  return defineContractPlugin(`remote-rows:${name}`, fragment);
+}
+export {
+  remoteRowSchema,
+  remoteRowsCollection
+};

package/dist/index.d.ts

@@ -1,4 +1,132 @@
-import { CollectionDef, RelayCollectionStore } from '@super-line/core';
+import { SelfCollectionStore, CollectionDef, RelayCollectionStore } from '@super-line/core';
+import { Value, Statement, QueryOptions, Outcome } from './contract.js';
+export { Result } from './contract.js';
+import 'zod';
+
+/** One row of a user table: `id` is its single-column primary key, else its rowid, as a string. */
+type RemoteRow = {
+    table: string;
+    id: string;
+    data: Record<string, Value>;
+};
+type RemoteChange = {
+    table: string;
+    id: string;
+    op: 'put';
+    data: Record<string, Value>;
+} | {
+    table: string;
+    id: string;
+    op: 'delete';
+};
+/**
+ * `wipeAll`: the history since that clock is gone (pruned, a dropped, renamed or altered table, a clock from the
+ * future) or is longer than `maxPullChanges`; `changes` is then empty.
+ */
+type RemoteChanges = {
+    epoch: string;
+    clock: number;
+    changes: RemoteChange[];
+    wipeAll: boolean;
+};
+/** `changes` is `undefined` when the batch was too large to inline or broke the history: pull `changesSince`. */
+type RemotePush = {
+    epoch: string;
+    clock: number;
+    changes: RemoteChange[] | undefined;
+};
+interface SyncedSqlOptions {
+    /** Delete markers kept for `changesSince`; older ones are pruned and the history starts later. Default 1000. */
+    maxTombstones?: number;
+    /** Changes a push carries inline; a larger batch pushes the clock only. Default 500. */
+    maxInlineChanges?: number;
+    /** Changes `changesSince` answers with; a longer backlog answers `wipeAll` instead. Default 5000. */
+    maxPullChanges?: number;
+    /** Called after every batch that changed rows, once it committed. A throw or rejection is logged and dropped. */
+    onChange?: (push: RemotePush) => unknown;
+}
+interface SyncedSql {
+    query(statements: Statement[], opts?: QueryOptions): Outcome;
+    snapshot(table: string, limit: number): RemoteRow[];
+    get(table: string, id: string): RemoteRow | undefined;
+    changesSince(clock: number): RemoteChanges;
+}
+declare const READ_ONLY_MESSAGE = "Read-only: the statement wrote rows or changed the schema and was rolled back";
+/**
+ * Change capture over a Durable Object's own SQLite, for an object whose tables are created at runtime by arbitrary
+ * SQL. `query` is the object's one write funnel: a batch runs in order inside one `transactionSync`, and the first
+ * failure rolls the whole batch back and reports SQLite's message.
+ *
+ * Every user table gets `AFTER INSERT/UPDATE/DELETE` triggers that log into `_sl_changes` at a clock that bumps once
+ * per write batch; a batch that changes the schema re-syncs them, and a table it created is logged whole. A row's id
+ * is its single-column primary key, else its rowid; a `WITHOUT ROWID` table with a composite key is skipped, with a
+ * warning. Dropping, renaming or altering the columns of a table breaks the history, so `changesSince` from before
+ * it says `wipeAll`, as it does past `maxTombstones` pruned deletes and for a backlog over `maxPullChanges`. The `_sl_` prefix is reserved, and the connection runs with
+ * `recursive_triggers` on, so a `REPLACE` that evicts a conflicting row logs its delete.
+ *
+ * ```ts
+ * private sync = syncedSql(this.ctx, { onChange: (push) => this.env.NODE.getByName('node').changed(push) })
+ * query(statements: Statement[], opts?: QueryOptions) { return this.sync.query(statements, opts) }
+ * ```
+ */
+declare function syncedSql(ctx: DurableObjectState, opts?: SyncedSqlOptions): SyncedSql;
+
+type Awaitable<T> = T | Promise<T>;
+/** A source as the node reaches it: `syncedSql`'s reads, over RPC. A Durable Object stub satisfies it. */
+interface RemoteSource {
+    snapshot(table: string, limit: number): Awaitable<RemoteRow[]>;
+    get(table: string, id: string): Awaitable<RemoteRow | undefined>;
+    changesSince(clock: number): Awaitable<RemoteChanges>;
+}
+/** Where the node keeps the last clock it applied per source. `ctx.storage` satisfies it. */
+interface RemoteRowsStorage {
+    get<T>(key: string): Promise<T | undefined>;
+    put<T>(key: string, value: T): Promise<void>;
+    list<T>(options: {
+        prefix: string;
+    }): Promise<Map<string, T>>;
+}
+interface RemoteRowsOptions {
+    /** The contract collection, declared with `remoteRowsCollection(collection)`. */
+    collection: string;
+    storage: RemoteRowsStorage;
+    stub(storeId: string): RemoteSource;
+    /**
+     * The source's history broke (a dropped, renamed or altered table, pruned deletes, a reset source), so rows its
+     * subscribers hold may be stale. Close their connections (`conn.raw.close(4409, 'resync')`): the client reconnects
+     * and resubscribes into a fresh snapshot. Default: nothing.
+     */
+    onWipe?(storeId: string): unknown;
+    /** Rows a snapshot reads from the source table, at most. Default 1000. */
+    snapshotLimit?: number;
+}
+interface RemoteRowsStore extends SelfCollectionStore {
+    /** The forwarder's target: a source's `onChange` push. Applies it inline when it is the next clock, else pulls. */
+    ingest(storeId: string, push: RemotePush): Promise<void>;
+    /**
+     * Pull what these sources changed since their last clock — on wake, for the sources with surviving subscribers.
+     * With no ids, every source the node keeps a clock for.
+     */
+    resume(storeIds?: string[]): Promise<void>;
+}
+/**
+ * The node side of a foreign Durable Object's SQLite: a read-only `self` {@link SelfCollectionStore} serving the rows
+ * of every source the node fronts as one collection. The source pushes each committed batch to {@link
+ * RemoteRowsStore.ingest} (`syncedSql`'s `onChange`); the node keeps the last clock per source in `storage` and pulls
+ * `changesSince` when a push skips a clock, carries no changes or comes from a new epoch. A store's feed starts at
+ * its first subscribe, and every subscribe pulls first.
+ *
+ * A snapshot must pin `storeId` and `table` by equality (`VALIDATION` otherwise); the rest of the query runs on the
+ * rows read. Changes carry no prior row, so the server sends a data-less delete to a subscriber the new row doesn't
+ * match — unless its filter rules out the row's `storeId` or `table`, which never change for a key. Writes throw
+ * `FORBIDDEN`: they go through the source's own path.
+ *
+ * ```ts
+ * const rows = remoteRows({ collection: 'storeRows', storage: ctx.storage, stub: (id) => env.STORE.getByName(id) })
+ * createSuperLineServer(contract, { ...base, collections: composeCollections({ default, storeRows: rows }) })
+ * ```
+ */
+declare function remoteRows(opts: RemoteRowsOptions): RemoteRowsStore;
 
 /**
  * The Durable Object SQLite RelayCollectionStore: every LWW collection on the contract gets its own typed table
@@ -16,4 +144,4 @@ import { CollectionDef, RelayCollectionStore } from '@super-line/core';
  */
 declare function cloudflareCollections(storage: DurableObjectStorage, collections: Record<string, CollectionDef>): RelayCollectionStore;
 
-export { cloudflareCollections };
+export { Outcome, QueryOptions, READ_ONLY_MESSAGE, type RemoteChange, type RemoteChanges, type RemotePush, type RemoteRow, type RemoteRowsOptions, type RemoteRowsStorage, type RemoteRowsStore, type RemoteSource, Statement, type SyncedSql, type SyncedSqlOptions, Value, cloudflareCollections, remoteRows, syncedSql };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import { SuperLineError, applyQuery, isCrdtCollection, matchesFilter } from "@super-line/core";
+import { SuperLineError as SuperLineError2, applyQuery as applyQuery2, isCrdtCollection, matchesFilter } from "@super-line/core";
 
 // ../collections-sqlite/src/sql.ts
 import { DEGENERATE_DATA_COLUMN, planColumns } from "@super-line/core";
@@ -228,6 +228,312 @@ function driftOf(t, stored) {
   return { alter };
 }
 
+// src/synced-sql.ts
+import { getLogger } from "@logtape/logtape";
+var log = getLogger(["super-line", "collections-cloudflare", "synced-sql"]);
+var READ_ONLY_MESSAGE = "Read-only: the statement wrote rows or changed the schema and was rolled back";
+var MAX_BYTES = 16 * 1024 * 1024;
+var INSTALL = [
+  "CREATE TABLE IF NOT EXISTS _sl_meta (epoch TEXT NOT NULL, clock INTEGER NOT NULL, historyStartsAt INTEGER NOT NULL)",
+  "CREATE TABLE IF NOT EXISTS _sl_changes (tbl TEXT NOT NULL, id, clock INTEGER NOT NULL, op TEXT NOT NULL, PRIMARY KEY (tbl, id))",
+  "CREATE INDEX IF NOT EXISTS _sl_changes_clock ON _sl_changes (op, clock)"
+];
+var SIGNATURE_SQL = `SELECT group_concat(type || ' ' || name || ' ' || ifnull(sql, ''), char(10)) AS s FROM sqlite_master
+  WHERE tbl_name NOT GLOB '_sl_*'`;
+var TRIGGERS_SQL = `SELECT name, tbl_name AS tbl FROM sqlite_master WHERE type = 'trigger' AND name GLOB '_sl_*'`;
+var TRACKED_SQL = `SELECT r.name AS name, r.tbl_name AS tbl, t.sql AS sql FROM sqlite_master AS r
+  JOIN sqlite_master AS t ON t.type = 'table' AND t.name = r.tbl_name WHERE r.type = 'trigger' AND r.name GLOB '_sl_i_*'`;
+var TABLES_SQL = `SELECT l.name AS name, l.wr AS wr,
+  (SELECT count(*) FROM pragma_table_info(l.name) WHERE pk > 0) AS pks,
+  (SELECT name FROM pragma_table_info(l.name) WHERE pk = 1) AS pk
+  FROM pragma_table_list() AS l
+  WHERE l.schema = 'main' AND l.type = 'table' AND l.name NOT GLOB 'sqlite_*' AND l.name NOT GLOB '_cf_*' AND l.name NOT GLOB '_sl_*'
+  AND l.name NOT GLOB '__miniflare_*'`;
+var OPS = ["i", "u", "d"];
+var triggerName = (op, table) => `_sl_${op}_${table}`;
+var ident = (name) => `"${name.replaceAll('"', '""')}"`;
+var literal = (text) => `'${text.replaceAll("'", "''")}'`;
+var toBase64 = (buffer) => {
+  let s = "";
+  for (const byte of new Uint8Array(buffer)) s += String.fromCharCode(byte);
+  return btoa(s);
+};
+var fromBase64 = (text) => Uint8Array.from(atob(text), (c) => c.charCodeAt(0)).buffer;
+var decode = (value) => value !== null && typeof value === "object" ? fromBase64(value.blob) : value;
+var encode2 = (value) => value instanceof ArrayBuffer ? { blob: toBase64(value) } : value;
+var idOf = (value) => value instanceof ArrayBuffer ? toBase64(value) : String(value);
+var utf8 = new TextEncoder();
+var ResultTooLarge = class extends Error {
+  constructor(bytes) {
+    super("The result is over the cap");
+    this.bytes = bytes;
+  }
+  bytes;
+};
+var record = (tbl, id, op, when = "") => `DELETE FROM _sl_changes WHERE tbl = ${tbl} AND id = ${id}; INSERT INTO _sl_changes (tbl, id, clock, op) SELECT ${tbl}, ${id}, clock + 1, '${op}' FROM _sl_meta${when};`;
+var triggers = (table, key) => {
+  const tbl = literal(table);
+  const on = ident(table);
+  const [i, u, d] = OPS.map((op) => ident(triggerName(op, table)));
+  return [
+    `CREATE TRIGGER IF NOT EXISTS ${i} AFTER INSERT ON ${on} BEGIN ${record(tbl, `NEW.${key}`, "put")} END`,
+    `CREATE TRIGGER IF NOT EXISTS ${u} AFTER UPDATE ON ${on} BEGIN ${record(tbl, `OLD.${key}`, "delete", ` WHERE OLD.${key} IS NOT NEW.${key}`)} ${record(tbl, `NEW.${key}`, "put")} END`,
+    `CREATE TRIGGER IF NOT EXISTS ${d} AFTER DELETE ON ${on} BEGIN ${record(tbl, `OLD.${key}`, "delete")} END`
+  ];
+};
+function syncedSql(ctx, opts = {}) {
+  const { maxTombstones = 1e3, maxInlineChanges = 500, maxPullChanges = 5e3, onChange } = opts;
+  const storage = ctx.storage;
+  const sql = storage.sql;
+  const rows = (query, ...params) => sql.exec(query, ...params).toArray();
+  const count = (query, ...params) => sql.exec(query, ...params).one().n;
+  const meta = () => sql.exec("SELECT * FROM _sl_meta").one();
+  const signature = () => sql.exec(SIGNATURE_SQL).one().s;
+  const totalChanges = () => count("SELECT total_changes() AS n");
+  const userTables = () => {
+    const tables = /* @__PURE__ */ new Map();
+    for (const t of rows(TABLES_SQL)) {
+      tables.set(t.name, t.pks === 1 && t.pk !== null ? ident(t.pk) : t.wr === 0 ? "rowid" : void 0);
+    }
+    return tables;
+  };
+  const tracked = () => {
+    const tables = /* @__PURE__ */ new Map();
+    for (const { name, tbl, sql: create } of rows(TRACKED_SQL))
+      if (name === triggerName("i", tbl)) tables.set(tbl, create);
+    return tables;
+  };
+  const sync = (before, backfillAt) => {
+    for (const { name, tbl } of rows(TRIGGERS_SQL)) {
+      if (/^_sl_[iud]_/.test(name) && !OPS.some((op) => triggerName(op, tbl) === name)) sql.exec(`DROP TRIGGER ${ident(name)}`);
+    }
+    const now = tracked();
+    const lost = [...before].filter(([t, create]) => now.get(t) !== create).map(([t]) => t);
+    for (const t of lost) sql.exec("DELETE FROM _sl_changes WHERE tbl = ?", t);
+    for (const [table, key] of userTables()) {
+      if (now.has(table)) continue;
+      if (key === void 0) {
+        log.warning("Table {table} has a composite primary key and no rowid; its changes are not synced", { table });
+        continue;
+      }
+      for (const trigger of triggers(table, key)) sql.exec(trigger);
+      if (backfillAt !== void 0 && lost.length === 0)
+        sql.exec(`INSERT INTO _sl_changes (tbl, id, clock, op) SELECT ?, ${key}, ?, 'put' FROM ${ident(table)}`, table, backfillAt);
+    }
+    return lost.length > 0;
+  };
+  const ensure = () => {
+    sql.exec("PRAGMA recursive_triggers = ON");
+    if (rows(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '_sl_meta'`).length > 0) return;
+    storage.transactionSync(() => {
+      for (const ddl of INSTALL) sql.exec(ddl);
+      sql.exec("INSERT INTO _sl_meta (epoch, clock, historyStartsAt) VALUES (?, 0, 0)", crypto.randomUUID());
+      sync(/* @__PURE__ */ new Map());
+    });
+  };
+  const read = (table, query, ...params) => {
+    const cursor = sql.exec(query, ...params);
+    const columns = cursor.columnNames.slice(1);
+    return Array.from(cursor.raw(), ([id, ...values]) => ({
+      table,
+      id: idOf(id),
+      data: Object.fromEntries(columns.map((c, i) => [c, encode2(values[i])]))
+    }));
+  };
+  const changes = (since) => {
+    const out = [];
+    for (const { tbl, id } of rows(`SELECT tbl, id FROM _sl_changes WHERE op = 'delete' AND clock > ?`, since))
+      out.push({ table: tbl, id: idOf(id), op: "delete" });
+    const tables = userTables();
+    for (const { tbl: table } of rows(`SELECT DISTINCT tbl FROM _sl_changes WHERE op = 'put' AND clock > ?`, since)) {
+      const key = tables.get(table);
+      if (key === void 0) continue;
+      const query = `SELECT t.${key}, t.* FROM ${ident(table)} AS t JOIN _sl_changes AS c ON c.id = t.${key}
+        WHERE c.tbl = ? AND c.op = 'put' AND c.clock > ?`;
+      for (const row of read(table, query, table, since)) out.push({ ...row, op: "put" });
+    }
+    return out;
+  };
+  const prune = () => {
+    const over = count(`SELECT count(*) AS n FROM _sl_changes WHERE op = 'delete'`) - maxTombstones;
+    if (over <= 0) return;
+    const cutoff = count(`SELECT clock AS n FROM _sl_changes WHERE op = 'delete' ORDER BY clock LIMIT 1 OFFSET ?`, over - 1);
+    sql.exec(`DELETE FROM _sl_changes WHERE op = 'delete' AND clock <= ?`, cutoff);
+    sql.exec("UPDATE _sl_meta SET historyStartsAt = max(historyStartsAt, ?)", cutoff);
+  };
+  const commit = (before) => {
+    const { epoch, clock } = meta();
+    const next = clock + 1;
+    const broken = signature() !== before.signature && sync(before.tracked, next);
+    const logged = count(`SELECT count(*) AS n FROM _sl_changes WHERE op IN ('put', 'delete') AND clock = ?`, next);
+    if (logged === 0 && !broken) return void 0;
+    sql.exec("UPDATE _sl_meta SET clock = ?", next);
+    if (broken) sql.exec("UPDATE _sl_meta SET historyStartsAt = ?", next);
+    prune();
+    if (!onChange) return void 0;
+    const inline = meta().historyStartsAt < next && logged <= maxInlineChanges;
+    return { epoch, clock: next, changes: inline ? changes(clock) : void 0 };
+  };
+  const notify = (push) => ctx.waitUntil(
+    Promise.resolve().then(() => onChange?.(push)).catch((error) => log.error("onChange failed for clock {clock}: {error}", { clock: push.clock, error }))
+  );
+  const run = ({ sql: query, params = [] }, budget) => {
+    const cursor = sql.exec(query, ...params.map(decode));
+    const out = [];
+    for (const raw of cursor.raw()) {
+      const row = raw.map(encode2);
+      budget.bytes += utf8.encode(JSON.stringify(row)).byteLength + 1;
+      if (budget.bytes > budget.maxBytes) throw new ResultTooLarge(budget.bytes);
+      out.push(row);
+    }
+    return { columns: cursor.columnNames, rows: out, meta: { rowsRead: cursor.rowsRead, rowsWritten: cursor.rowsWritten } };
+  };
+  return {
+    query(statements, { readOnly = false, maxBytes = MAX_BYTES } = {}) {
+      let index = 0;
+      const budget = { bytes: 0, maxBytes };
+      try {
+        ensure();
+        const { results, push } = storage.transactionSync(() => {
+          const before = readOnly ? void 0 : { signature: signature(), tracked: tracked() };
+          const results2 = statements.map((statement, i) => {
+            index = i;
+            if (!readOnly) return run(statement, budget);
+            const schema = signature();
+            const changed = totalChanges();
+            const result = run(statement, budget);
+            if (result.meta.rowsWritten > 0 || totalChanges() !== changed || signature() !== schema) throw new Error(READ_ONLY_MESSAGE);
+            return result;
+          });
+          return { results: results2, push: before && commit(before) };
+        });
+        if (push) notify(push);
+        return { results };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (error instanceof ResultTooLarge) return { error: message, statement: index, bytes: error.bytes };
+        return { error: message, statement: index };
+      }
+    },
+    snapshot(table, limit) {
+      ensure();
+      const key = userTables().get(table);
+      if (key === void 0) return [];
+      return read(table, `SELECT ${key}, * FROM ${ident(table)} LIMIT ?`, limit);
+    },
+    get(table, id) {
+      ensure();
+      const key = userTables().get(table);
+      if (key === void 0) return void 0;
+      return read(table, `SELECT ${key}, * FROM ${ident(table)} WHERE ${key} = ?`, id).find((row) => row.id === id);
+    },
+    changesSince(since) {
+      ensure();
+      const { epoch, clock, historyStartsAt } = meta();
+      const wipeAll = since < historyStartsAt || since > clock || count(`SELECT count(*) AS n FROM _sl_changes WHERE op IN ('put', 'delete') AND clock > ?`, since) > maxPullChanges;
+      return { epoch, clock, changes: wipeAll ? [] : changes(since), wipeAll };
+    }
+  };
+}
+
+// src/remote-rows.ts
+import { SuperLineError, applyQuery } from "@super-line/core";
+var CURRENT = Number.MAX_SAFE_INTEGER;
+var conjuncts = (expr) => expr === void 0 ? [] : expr.op === "and" ? expr.args.flatMap(conjuncts) : [expr];
+var pinOf = (parts, field) => {
+  for (const e of parts) if (e.op === "eq" && e.field === field) return e.value;
+  return void 0;
+};
+var FIXED = ["storeId", "table"];
+var isPin = (e) => e.op === "eq" && (e.field === "storeId" || e.field === "table");
+var splitKey = (key) => {
+  const a = key.indexOf(":");
+  const b = key.indexOf(":", a + 1);
+  return a < 0 || b < 0 ? void 0 : [key.slice(0, a), key.slice(a + 1, b), key.slice(b + 1)];
+};
+function remoteRows(opts) {
+  const { collection, storage, stub, onWipe, snapshotLimit = 1e3 } = opts;
+  const listeners = /* @__PURE__ */ new Set();
+  const queues = /* @__PURE__ */ new Map();
+  const prefix = `remote-rows:${collection}:`;
+  const stateKey = (storeId) => prefix + storeId;
+  const keyOf = (storeId, table, id) => `${storeId}:${table}:${id}`;
+  const rowOf = (storeId, { table, id, data }) => ({ key: keyOf(storeId, table, id), storeId, table, id, data });
+  const changeOf = (storeId, c) => {
+    const id = keyOf(storeId, c.table, c.id);
+    if (c.op === "delete") return { n: collection, k: "delete", id, origin: storeId };
+    return { n: collection, k: "update", id, next: rowOf(storeId, c), origin: storeId };
+  };
+  const emit = (storeId, changes) => {
+    for (const c of changes) {
+      const change = changeOf(storeId, c);
+      for (const cb of listeners) cb(change);
+    }
+  };
+  const serial = (storeId, step) => {
+    const run = (queues.get(storeId) ?? Promise.resolve()).then(step);
+    queues.set(storeId, run.catch(() => {
+    }));
+    return run;
+  };
+  const save = (storeId, { epoch, clock }) => storage.put(stateKey(storeId), { epoch, clock });
+  async function pull(storeId, seen) {
+    const pulled = await stub(storeId).changesSince(seen?.clock ?? CURRENT);
+    await save(storeId, pulled);
+    if (!seen) return;
+    if (pulled.wipeAll || pulled.epoch !== seen.epoch) await onWipe?.(storeId);
+    else emit(storeId, pulled.changes);
+  }
+  async function receive(storeId, push) {
+    const seen = await storage.get(stateKey(storeId));
+    if (!seen) return;
+    const sameEpoch = push.epoch === seen.epoch;
+    if (sameEpoch && push.clock <= seen.clock) return;
+    if (!sameEpoch || push.clock !== seen.clock + 1 || !push.changes) return pull(storeId, seen);
+    await save(storeId, push);
+    emit(storeId, push.changes);
+  }
+  const catchUp = (storeId) => serial(storeId, async () => pull(storeId, await storage.get(stateKey(storeId))));
+  const readOnly = () => {
+    throw new SuperLineError("FORBIDDEN", `Collection ${collection} is read-only: write through its source`);
+  };
+  return {
+    clustering: "self",
+    coordination: "cluster",
+    ingest: (storeId, push) => serial(storeId, () => receive(storeId, push)),
+    async resume(storeIds) {
+      const ids = storeIds ?? [...(await storage.list({ prefix })).keys()].map((key) => key.slice(prefix.length));
+      await Promise.all(ids.map(catchUp));
+    },
+    async snapshot(_n, query) {
+      const parts = conjuncts(query.filter);
+      const storeId = pinOf(parts, "storeId");
+      const table = pinOf(parts, "table");
+      if (typeof storeId !== "string" || typeof table !== "string")
+        throw new SuperLineError("VALIDATION", `A ${collection} subscription must pin storeId and table with eq()`);
+      await catchUp(storeId);
+      const exact = !query.orderBy?.length && parts.every(isPin) && query.limit !== void 0;
+      const limit = exact ? Math.min(snapshotLimit, (query.offset ?? 0) + (query.limit ?? 0)) : snapshotLimit;
+      const rows = await stub(storeId).snapshot(table, limit);
+      return applyQuery(rows.map((row) => rowOf(storeId, row)), query);
+    },
+    async read(_n, key) {
+      const parts = splitKey(key);
+      if (!parts) return void 0;
+      const [storeId, table, id] = parts;
+      const row = await stub(storeId).get(table, id);
+      return row && rowOf(storeId, row);
+    },
+    fixedFields: () => FIXED,
+    onChange(cb) {
+      listeners.add(cb);
+      return () => listeners.delete(cb);
+    },
+    apply: readOnly,
+    conditionalApply: readOnly
+  };
+}
+
 // src/index.ts
 var MAX_PARAMS = 100;
 var MAX_COLUMNS = 98;
@@ -261,14 +567,14 @@ function cloudflareCollections(storage, collections) {
       try {
         tables.set(n, openTable(n, def));
       } catch (err) {
-        tables.set(n, new SuperLineError("INTERNAL", `cloudflareCollections: collection '${n}' is unusable: ${err.message}`));
+        tables.set(n, new SuperLineError2("INTERNAL", `cloudflareCollections: collection '${n}' is unusable: ${err.message}`));
       }
     }
     return tables;
   };
   const table = (n) => {
     const t = open().get(n);
-    if (t instanceof SuperLineError) throw t;
+    if (t instanceof SuperLineError2) throw t;
     return t;
   };
   const readRow = (t, id) => {
@@ -284,14 +590,14 @@ function cloudflareCollections(storage, collections) {
     const ts = Date.now();
     for (const op of ops) {
       const t = table(op.n);
-      if (!t) throw new SuperLineError("NOT_FOUND", `Unknown collection: ${op.n}`);
+      if (!t) throw new SuperLineError2("NOT_FOUND", `Unknown collection: ${op.n}`);
       if (op.op === "insert") {
-        if (rows(t.sql.has, op.id).length > 0) throw new SuperLineError("CONFLICT", `Row already exists: ${op.n}/${op.id}`);
+        if (rows(t.sql.has, op.id).length > 0) throw new SuperLineError2("CONFLICT", `Row already exists: ${op.n}/${op.id}`);
         sql.exec(t.sql.insert, ...rowParams(t, op.id, op.row), ts, ts);
         changes.push({ n: op.n, k: "insert", id: op.id, next: op.row, origin });
       } else if (op.op === "update") {
         const prev = readRow(t, op.id);
-        if (prev === void 0) throw new SuperLineError("NOT_FOUND", `No row: ${op.n}/${op.id}`);
+        if (prev === void 0) throw new SuperLineError2("NOT_FOUND", `No row: ${op.n}/${op.id}`);
         sql.exec(t.sql.update, ...updateParams(t, op.id, op.row, ts));
         changes.push({ n: op.n, k: "update", id: op.id, prev, next: op.row, origin });
       } else {
@@ -329,7 +635,7 @@ function cloudflareCollections(storage, collections) {
       if (!t) return [];
       const q = snapshotSql(t, query, MAX_PARAMS);
       const found = rows(q.sql, ...q.params).map((r) => fromRow(t, r));
-      return q.exact ? found : applyQuery(found, query);
+      return q.exact ? found : applyQuery2(found, query);
     },
     read(n, id) {
       const t = table(n);
@@ -354,5 +660,8 @@ function cloudflareCollections(storage, collections) {
   };
 }
 export {
-  cloudflareCollections
+  READ_ONLY_MESSAGE,
+  cloudflareCollections,
+  remoteRows,
+  syncedSql
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-line/collections-cloudflare",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Durable Object SQLite CollectionStore backend for super-line — typed row collections stored in the object that is the node, with IR→SQL snapshot pushdown.",
   "license": "MIT",
@@ -26,6 +26,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
     }
   },
   "files": [
@@ -36,12 +40,16 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@logtape/logtape": "^2.2.4",
+    "zod": "^4.2.0"
+  },
   "peerDependencies": {
-    "@super-line/core": ">=0.17.0 <1.0.0"
+    "@super-line/core": ">=0.23.0 <1.0.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^5.20261013.1",
-    "@super-line/core": "^0.21.0"
+    "@super-line/core": "^0.23.0"
   },
   "scripts": {
     "build": "tsup"