@syncular/client 0.1.2 → 0.2.0

package/dist/outbox.js

@@ -0,0 +1,140 @@
+/**
+ * The durable outbox (SPEC.md §7.1) with encode-at-send (the §0 binary-push
+ * outbox rule): local mutations are persisted in a schema-agnostic JSON
+ * form and encoded with the *current* generated row codec only when a push
+ * request is built — a commit recorded under schema N replays after an
+ * upgrade to N+1 by re-encoding.
+ */
+import { encodeRow, } from '@syncular/core';
+import { ClientSyncError } from './errors.js';
+import { jsonToRowValue, } from './schema.js';
+export function appendOutboxCommit(db, clientCommitId, operations, nowMs) {
+    if (operations.length === 0) {
+        throw new ClientSyncError('sync.empty_commit', 'a local commit must carry at least one operation (§6.1)');
+    }
+    db.exec(`INSERT INTO _syncular_outbox(client_commit_id, created_at_ms, operations)
+     VALUES (?, ?, ?)`, [clientCommitId, nowMs, JSON.stringify(operations)]);
+}
+/** Pending commits in FIFO creation order (§7.1). */
+export function listOutbox(db) {
+    return db
+        .query(`SELECT seq, client_commit_id, created_at_ms, operations
+       FROM _syncular_outbox ORDER BY seq ASC`)
+        .map((row) => ({
+        seq: row.seq,
+        clientCommitId: row.client_commit_id,
+        createdAtMs: row.created_at_ms,
+        operations: JSON.parse(row.operations),
+    }));
+}
+export function deleteOutboxCommit(db, clientCommitId) {
+    db.exec('DELETE FROM _syncular_outbox WHERE client_commit_id = ?', [
+        clientCommitId,
+    ]);
+}
+/**
+ * §7.4.4: after a schema bump, a persisted upsert may name a column the new
+ * schema no longer has. The value has nowhere to go and there is no
+ * migration — surface it as `sync.outbox_incompatible` (client-local, §10.3)
+ * so the caller can drop the commit through the rejection channel.
+ */
+export class OutboxEncodeError extends ClientSyncError {
+    constructor(message) {
+        super('sync.outbox_incompatible', message, false);
+    }
+}
+function orderedValues(table, values) {
+    // Any persisted key that is not a column of the CURRENT schema means the
+    // bump removed (or renamed) it — the commit cannot be expressed now.
+    for (const key of Object.keys(values)) {
+        if (!table.columnIndex.has(key)) {
+            throw new OutboxEncodeError(`outbox commit references column ${JSON.stringify(key)} on ${JSON.stringify(table.name)}, which the current schema no longer has (§7.4.4)`);
+        }
+    }
+    return table.columns.map((column) => {
+        const value = values[column.name];
+        if (value === undefined)
+            return null;
+        return jsonToRowValue(value);
+    });
+}
+/**
+ * Encode one outbox commit as a `PUSH_COMMIT` frame with the current
+ * schema's row codec (§6.1). When `encryption` is configured, encrypted
+ * columns (§5.11) are encrypted here — the encode-at-send seam — before the
+ * row codec serializes them as ciphertext-envelope `bytes`. Async because
+ * WebCrypto is async.
+ */
+export async function encodeOutboxCommit(schema, commit, encryption) {
+    const operations = [];
+    for (const op of commit.operations) {
+        if (op.op === 'delete') {
+            operations.push({
+                table: op.table,
+                rowId: op.rowId,
+                op: 'delete',
+                ...(op.baseVersion !== undefined
+                    ? { baseVersion: op.baseVersion }
+                    : {}),
+            });
+            continue;
+        }
+        const table = schema.tables.get(op.table);
+        if (table === undefined) {
+            // §7.4.4: the bump removed this table — the commit cannot be encoded.
+            throw new OutboxEncodeError(`outbox commit ${commit.clientCommitId} targets table ${JSON.stringify(op.table)}, which the current schema no longer has (§7.4.4)`);
+        }
+        if (op.values === undefined) {
+            throw new ClientSyncError('sync.invalid_request', `outbox upsert on ${op.table}/${op.rowId} has no values`);
+        }
+        let values = orderedValues(table, op.values);
+        if (encryption !== undefined && table.hasEncryptedColumns) {
+            // Lazy: opt-in E2EE never enters an encryption-free app's bundle.
+            const { encryptRowValues } = await import('./encryption.js');
+            values = await encryptRowValues(encryption, table, op.rowId, values);
+        }
+        operations.push({
+            table: op.table,
+            rowId: op.rowId,
+            op: 'upsert',
+            ...(op.baseVersion !== undefined ? { baseVersion: op.baseVersion } : {}),
+            payload: encodeRow(table.columns, values),
+        });
+    }
+    return {
+        type: 'PUSH_COMMIT',
+        clientCommitId: commit.clientCommitId,
+        operations,
+    };
+}
+/**
+ * §3.3: drop pending commits that write into a revoked scope instead of
+ * replaying them into guaranteed rejections. A whole commit is dropped when
+ * any of its upserts provably lands in the revoked effective scopes —
+ * commits are atomic and their content is pinned by the idempotency key,
+ * so ops are never removed individually. Returns dropped commit ids.
+ */
+export function dropOutboxCommitsInScope(db, table, effective) {
+    const entries = Object.entries(effective);
+    if (entries.length === 0)
+        return [];
+    const dropped = [];
+    for (const commit of listOutbox(db)) {
+        const inScope = commit.operations.some((op) => {
+            if (op.table !== table.name || op.values === undefined)
+                return false;
+            return entries.every(([variable, values]) => {
+                const column = table.scopeColumnByVariable.get(variable);
+                if (column === undefined)
+                    return false;
+                const value = op.values?.[column];
+                return typeof value === 'string' && values.includes(value);
+            });
+        });
+        if (inScope) {
+            deleteOutboxCommit(db, commit.clientCommitId);
+            dropped.push(commit.clientCommitId);
+        }
+    }
+    return dropped;
+}

package/dist/schema.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Client schema IR (SPEC.md §2.4, §3.1) — the same shape the server
+ * compiles, hand-written until codegen (B5) emits it. Drives local table
+ * DDL, the generated row codec, mutation helpers, and the §3.3 purge
+ * mapping (scope variable → local column).
+ */
+import type { RowColumn, RowValue } from '@syncular/core';
+import type { ClientDatabase, SqlValue } from './database.js';
+/** `'prefix:{variable}'` shorthand (column name = variable) or explicit. */
+export type ScopePatternSpec = string | {
+    pattern: string;
+    column: string;
+};
+/** One local secondary index (the CREATE INDEX migration subset). */
+export interface ClientIndexSpec {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly unique: boolean;
+}
+export interface ClientTableSchema {
+    readonly name: string;
+    /** Columns in schema-IR declaration order (the row-codec order, §2.4). */
+    readonly columns: readonly RowColumn[];
+    readonly primaryKey: string;
+    /** Scope patterns (§3.1); the variable→column map feeds the §3.3 purge. */
+    readonly scopes: readonly ScopePatternSpec[];
+    /** Local secondary indexes; absent in the generated schema when a table
+     * declares none (typegen omits the key for index-free tables). */
+    readonly indexes?: readonly ClientIndexSpec[];
+}
+export interface ClientSchema {
+    readonly version: number;
+    readonly tables: readonly ClientTableSchema[];
+}
+export interface CompiledClientTable {
+    readonly name: string;
+    readonly columns: readonly RowColumn[];
+    readonly primaryKey: string;
+    readonly primaryKeyIndex: number;
+    readonly columnIndex: ReadonlyMap<string, number>;
+    /** Scope variable → local scope column (§3.3 purge mapping). */
+    readonly scopeColumnByVariable: ReadonlyMap<string, string>;
+    /**
+     * Scope variable → the pattern's literal prefix (§3.1). A stored-scope
+     * value `v` for this variable has scope key `prefix:v` — the invalidation
+     * vocabulary (TODO 3.1 / DESIGN-eviction I2) and the delta-routing key.
+     */
+    readonly scopePrefixByVariable: ReadonlyMap<string, string>;
+    /** Local secondary indexes to create on the mirror table (declaration
+     * order); empty when the table declares none. */
+    readonly indexes: readonly ClientIndexSpec[];
+    /** §5.11: true when any column is `encrypted`. Drives the encrypt/decrypt
+     * seam (skipped entirely when false) and the local-plaintext DDL. */
+    readonly hasEncryptedColumns: boolean;
+}
+export interface CompiledClientSchema {
+    readonly version: number;
+    readonly tables: ReadonlyMap<string, CompiledClientTable>;
+}
+export declare function compileClientSchema(schema: ClientSchema): CompiledClientSchema;
+/**
+ * Hidden per-row column carrying the last known `server_version` (§2.2):
+ * `-1` = local optimistic row never confirmed by the server, `≥ 1` =
+ * version from a `COMMIT` change or a segment row record (§5.2/§5.6 —
+ * segment rows land with their real server version).
+ */
+export declare const SYNC_VERSION_COLUMN = "_sync_version";
+/** `_sync_version` for optimistic rows the server has never confirmed. */
+export declare const OPTIMISTIC_VERSION = -1;
+export declare function quoteIdent(name: string): string;
+/**
+ * §5.11: the app-side type of a column for local (plaintext) storage. For an
+ * encrypted column this is `declaredType` — the local mirror stays plaintext,
+ * so it stores/reads the real value type, not the wire `bytes`.
+ */
+export declare function localColumnType(column: RowColumn): RowColumn['type'];
+/** §7.4.1 persisted local schema-version marker (`_syncular_meta` key). */
+export declare const LOCAL_SCHEMA_VERSION_KEY = "localSchemaVersion";
+/**
+ * Create the synced tables plus client bookkeeping tables (outbox,
+ * subscription state, meta). Idempotent.
+ */
+export declare function ensureLocalSchema(db: ClientDatabase, schema: CompiledClientSchema): void;
+/**
+ * §7.4.3 reset: drop every synced local table (whatever the *previous*
+ * generated schema created — discovered from `sqlite_master`, since a
+ * bump may add/remove tables) and recreate the synced tables from the
+ * NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
+ * subscriptions, blob cache) are preserved. Caller owns the surrounding
+ * transaction and the subscription-state reset (state.ts).
+ */
+export declare function dropAndRecreateSyncedTables(db: ClientDatabase, schema: CompiledClientSchema): void;
+/** RowValue → SQL bind value for the local mirror tables. */
+export declare function toSqlValue(value: RowValue): SqlValue;
+/** SQL cell → RowValue per the column's declared type. */
+export declare 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.
+ */
+export declare function recordToRowValues(table: CompiledClientTable, record: Readonly<Record<string, unknown>>): RowValue[];
+export type JsonRowValue = string | number | boolean | null | {
+    readonly $bytes: string;
+};
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function rowValueToJson(value: RowValue): JsonRowValue;
+export declare function jsonToRowValue(value: JsonRowValue): RowValue;

package/dist/schema.js

@@ -0,0 +1,267 @@
+import { ClientSyncError } from './errors.js';
+const PATTERN_RE = /^([^{}]+):\{([^{}:]+)\}$/;
+export function compileClientSchema(schema) {
+    const tables = new Map();
+    for (const table of schema.tables) {
+        if (tables.has(table.name)) {
+            throw new Error(`duplicate table ${JSON.stringify(table.name)}`);
+        }
+        const columnIndex = new Map();
+        table.columns.forEach((column, index) => {
+            if (columnIndex.has(column.name)) {
+                throw new Error(`table ${table.name}: duplicate column ${JSON.stringify(column.name)}`);
+            }
+            columnIndex.set(column.name, index);
+        });
+        const primaryKeyIndex = columnIndex.get(table.primaryKey);
+        if (primaryKeyIndex === undefined) {
+            throw new Error(`table ${table.name}: primary key ${JSON.stringify(table.primaryKey)} is not a column`);
+        }
+        if (table.scopes.length === 0) {
+            throw new Error(`table ${table.name}: every synced table declares at least one scope pattern (§3.1)`);
+        }
+        const scopeColumnByVariable = new Map();
+        const scopePrefixByVariable = new Map();
+        for (const spec of table.scopes) {
+            const pattern = typeof spec === 'string' ? spec : spec.pattern;
+            const match = PATTERN_RE.exec(pattern);
+            if (match === null || match[1] === undefined || match[2] === undefined) {
+                throw new Error(`table ${table.name}: scope pattern ${JSON.stringify(pattern)} must be 'prefix:{variable}'`);
+            }
+            const prefix = match[1];
+            const variable = match[2];
+            const column = typeof spec === 'string' ? variable : spec.column;
+            if (!columnIndex.has(column)) {
+                throw new Error(`table ${table.name}: scope pattern ${JSON.stringify(pattern)} names unknown column ${JSON.stringify(column)}`);
+            }
+            const existing = scopeColumnByVariable.get(variable);
+            if (existing !== undefined && existing !== column) {
+                throw new Error(`table ${table.name}: variable ${JSON.stringify(variable)} maps to two different columns (§3.1)`);
+            }
+            scopeColumnByVariable.set(variable, column);
+            scopePrefixByVariable.set(variable, prefix);
+        }
+        const indexes = table.indexes ?? [];
+        for (const index of indexes) {
+            for (const column of index.columns) {
+                if (!columnIndex.has(column)) {
+                    throw new Error(`table ${table.name}: index ${JSON.stringify(index.name)} names unknown column ${JSON.stringify(column)}`);
+                }
+            }
+        }
+        tables.set(table.name, {
+            name: table.name,
+            columns: table.columns,
+            primaryKey: table.primaryKey,
+            primaryKeyIndex,
+            columnIndex,
+            scopeColumnByVariable,
+            scopePrefixByVariable,
+            indexes,
+            hasEncryptedColumns: table.columns.some((c) => c.encrypted === true),
+        });
+    }
+    return { version: schema.version, tables };
+}
+// ---------------------------------------------------------------------------
+// Local DDL
+// ---------------------------------------------------------------------------
+/**
+ * Hidden per-row column carrying the last known `server_version` (§2.2):
+ * `-1` = local optimistic row never confirmed by the server, `≥ 1` =
+ * version from a `COMMIT` change or a segment row record (§5.2/§5.6 —
+ * segment rows land with their real server version).
+ */
+export const SYNC_VERSION_COLUMN = '_sync_version';
+/** `_sync_version` for optimistic rows the server has never confirmed. */
+export const OPTIMISTIC_VERSION = -1;
+export function quoteIdent(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/**
+ * §5.11: the app-side type of a column for local (plaintext) storage. For an
+ * encrypted column this is `declaredType` — the local mirror stays plaintext,
+ * so it stores/reads the real value type, not the wire `bytes`.
+ */
+export function localColumnType(column) {
+    if (column.encrypted && column.declaredType !== undefined) {
+        return column.declaredType;
+    }
+    return column.type;
+}
+function sqlType(column) {
+    switch (localColumnType(column)) {
+        case 'string':
+        case 'json':
+        case 'blob_ref':
+            return 'TEXT';
+        case 'integer':
+            return 'INTEGER';
+        case 'float':
+            return 'REAL';
+        case 'boolean':
+            return 'INTEGER';
+        case 'bytes':
+        case 'crdt':
+            // §5.10: a crdt column stores its opaque bytes locally, exactly like
+            // a bytes column. The Y.Doc view is an app-level helper (§5.10.4).
+            return 'BLOB';
+    }
+}
+/** §7.4.1 persisted local schema-version marker (`_syncular_meta` key). */
+export const LOCAL_SCHEMA_VERSION_KEY = 'localSchemaVersion';
+function createSyncedTable(db, table) {
+    const columns = table.columns.map((column) => {
+        const notNull = column.nullable ? '' : ' NOT NULL';
+        const pk = column.name === table.primaryKey ? ' PRIMARY KEY' : '';
+        return `${quoteIdent(column.name)} ${sqlType(column)}${notNull}${pk}`;
+    });
+    columns.push(`${quoteIdent(SYNC_VERSION_COLUMN)} INTEGER NOT NULL DEFAULT 0`);
+    db.exec(`CREATE TABLE IF NOT EXISTS ${quoteIdent(table.name)} (${columns.join(', ')})`);
+    // Local secondary indexes (CREATE INDEX subset). Created here so both the
+    // initial ensureLocalSchema and the §7.4.3 drop-and-recreate reset path
+    // materialize them. IF NOT EXISTS keeps it idempotent; the DROP TABLE in the
+    // reset path already removed any stale index alongside its table.
+    for (const index of table.indexes) {
+        const unique = index.unique ? 'UNIQUE ' : '';
+        const cols = index.columns.map((c) => quoteIdent(c)).join(', ');
+        db.exec(`CREATE ${unique}INDEX IF NOT EXISTS ${quoteIdent(index.name)} ON ${quoteIdent(table.name)} (${cols})`);
+    }
+}
+/**
+ * Create the synced tables plus client bookkeeping tables (outbox,
+ * subscription state, meta). Idempotent.
+ */
+export function ensureLocalSchema(db, schema) {
+    db.transaction(() => {
+        for (const table of schema.tables.values()) {
+            createSyncedTable(db, table);
+        }
+        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_meta(
+      key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
+        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_outbox(
+      seq INTEGER PRIMARY KEY AUTOINCREMENT,
+      client_commit_id TEXT NOT NULL UNIQUE,
+      created_at_ms INTEGER NOT NULL,
+      operations TEXT NOT NULL)`);
+        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_subscriptions(
+      id TEXT PRIMARY KEY,
+      tbl TEXT NOT NULL,
+      requested_scopes TEXT NOT NULL,
+      params TEXT,
+      cursor INTEGER NOT NULL DEFAULT -1,
+      bootstrap_state TEXT,
+      effective_scopes TEXT,
+      status TEXT NOT NULL DEFAULT 'active',
+      reason_code TEXT)`);
+        // §4.8 window registry: which units (scope values) of a window base are
+        // live locally — the completeness oracle (I3) and the shrink driver
+        // (a unit's omission from the next pull unregisters it, §4.1).
+        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_windows(
+      base TEXT NOT NULL,
+      unit TEXT NOT NULL,
+      sub_id TEXT NOT NULL,
+      PRIMARY KEY (base, unit))`);
+        // §4.8 E1: units that left the window but still had outbox-pinned rows.
+        // Retried when the outbox drains; cancelled if the unit re-enters.
+        db.exec(`CREATE TABLE IF NOT EXISTS _syncular_window_pending_evict(
+      sub_id TEXT PRIMARY KEY,
+      tbl TEXT NOT NULL,
+      effective_scopes TEXT NOT NULL)`);
+    });
+}
+/** Bookkeeping tables the schema-bump reset (§7.4.3) MUST NOT drop. */
+const RESERVED_TABLE_PREFIX = '_syncular_';
+/**
+ * §7.4.3 reset: drop every synced local table (whatever the *previous*
+ * generated schema created — discovered from `sqlite_master`, since a
+ * bump may add/remove tables) and recreate the synced tables from the
+ * NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
+ * subscriptions, blob cache) are preserved. Caller owns the surrounding
+ * transaction and the subscription-state reset (state.ts).
+ */
+export function dropAndRecreateSyncedTables(db, schema) {
+    const existing = db.query(`SELECT name FROM sqlite_master WHERE type = 'table'
+       AND name NOT LIKE '${RESERVED_TABLE_PREFIX}%'
+       AND name NOT LIKE 'sqlite_%'`);
+    for (const row of existing) {
+        db.exec(`DROP TABLE IF EXISTS ${quoteIdent(String(row.name))}`);
+    }
+    for (const table of schema.tables.values()) {
+        createSyncedTable(db, table);
+    }
+}
+// ---------------------------------------------------------------------------
+// Value conversion
+// ---------------------------------------------------------------------------
+/** RowValue → SQL bind value for the local mirror tables. */
+export function toSqlValue(value) {
+    if (typeof value === 'boolean')
+        return value ? 1 : 0;
+    return value;
+}
+/** SQL cell → RowValue per the column's declared type. */
+export function fromSqlValue(column, value) {
+    if (value === null)
+        return null;
+    switch (localColumnType(column)) {
+        case 'boolean':
+            return value !== 0 && value !== false;
+        case 'integer':
+            return typeof value === 'bigint' ? Number(value) : value;
+        case 'float':
+            return value;
+        case 'bytes':
+        case 'crdt':
+            return value;
+        case 'string':
+        case 'json':
+        case 'blob_ref':
+            return value;
+    }
+}
+/**
+ * App-facing record → schema-ordered row values for the codec and the
+ * local mirror. Missing keys become NULL; unknown keys fail loud.
+ */
+export function recordToRowValues(table, record) {
+    for (const key of Object.keys(record)) {
+        if (!table.columnIndex.has(key)) {
+            throw new ClientSyncError('sync.invalid_request', `table ${table.name}: unknown column ${JSON.stringify(key)} in mutation values`);
+        }
+    }
+    return table.columns.map((column) => {
+        const value = record[column.name];
+        if (value === undefined || value === null) {
+            if (!column.nullable) {
+                throw new ClientSyncError('sync.invalid_request', `table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1 full-row payloads)`);
+            }
+            return null;
+        }
+        return value;
+    });
+}
+function bytesToHex(bytes) {
+    let out = '';
+    for (const byte of bytes)
+        out += byte.toString(16).padStart(2, '0');
+    return out;
+}
+export function hexToBytes(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+export function rowValueToJson(value) {
+    if (value instanceof Uint8Array)
+        return { $bytes: bytesToHex(value) };
+    return value;
+}
+export function jsonToRowValue(value) {
+    if (typeof value === 'object' && value !== null) {
+        return hexToBytes(value.$bytes);
+    }
+    return value;
+}

package/dist/state.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Durable client sync state: per-subscription cursor, bootstrap resume
+ * token (round-tripped opaquely, §4.7), and the last-echoed effective
+ * scopes the §3.3 purge contract is keyed on — persisted per subscription
+ * exactly for that purpose.
+ */
+import type { ScopeMap } from '@syncular/core';
+import type { ClientDatabase } from './database.js';
+export type SubscriptionStatus = 'active' | 'revoked' | 'failed';
+export interface SubscriptionRecord {
+    readonly id: string;
+    readonly table: string;
+    /** Requested scopes (§3.2), chosen by the app. */
+    readonly scopes: ScopeMap;
+    /** Host-opaque JSON params, preserved verbatim. */
+    readonly params?: string;
+    /** Last fully-applied commitSeq; -1 = never synced (§4.3). */
+    readonly cursor: number;
+    /** Opaque resume token from `SUB_END` (§4.7); present mid-bootstrap. */
+    readonly bootstrapState?: string;
+    /** Last effective scopes echoed while active (§3.3 purge key). */
+    readonly effectiveScopes?: ScopeMap;
+    readonly status: SubscriptionStatus;
+    /** §10 code when not active (`sync.scope_revoked`, …). */
+    readonly reasonCode?: string;
+}
+export declare function loadSubscriptions(db: ClientDatabase): SubscriptionRecord[];
+export declare function getSubscription(db: ClientDatabase, id: string): SubscriptionRecord | undefined;
+export declare function saveSubscription(db: ClientDatabase, record: SubscriptionRecord): void;
+export declare function deleteSubscription(db: ClientDatabase, id: string): void;
+/**
+ * §7.4.3 reset: keep every subscription REGISTRATION (id, table,
+ * requested scopes, params — the app's declared intent) but discard all
+ * synced state (cursor → -1, no resume token, no effective-scope map,
+ * status → active), so the next round fresh-bootstraps exactly the
+ * subscriptions the app still wants. Caller owns the transaction.
+ */
+export declare function resetSubscriptionsForBump(db: ClientDatabase): void;
+export declare function getMeta(db: ClientDatabase, key: string): string | undefined;
+export declare function setMeta(db: ClientDatabase, key: string, value: string): void;

package/dist/state.js

@@ -0,0 +1,77 @@
+function rowToRecord(row) {
+    return {
+        id: row.id,
+        table: row.tbl,
+        scopes: JSON.parse(row.requested_scopes),
+        ...(row.params !== null ? { params: row.params } : {}),
+        cursor: row.cursor,
+        ...(row.bootstrap_state !== null
+            ? { bootstrapState: row.bootstrap_state }
+            : {}),
+        ...(row.effective_scopes !== null
+            ? {
+                effectiveScopes: JSON.parse(row.effective_scopes),
+            }
+            : {}),
+        status: row.status,
+        ...(row.reason_code !== null
+            ? { reasonCode: row.reason_code }
+            : {}),
+    };
+}
+export function loadSubscriptions(db) {
+    return db
+        .query('SELECT * FROM _syncular_subscriptions ORDER BY rowid ASC')
+        .map(rowToRecord);
+}
+export function getSubscription(db, id) {
+    const row = db.query('SELECT * FROM _syncular_subscriptions WHERE id = ?', [
+        id,
+    ])[0];
+    return row === undefined ? undefined : rowToRecord(row);
+}
+export function saveSubscription(db, record) {
+    db.exec(`INSERT OR REPLACE INTO _syncular_subscriptions(
+       id, tbl, requested_scopes, params, cursor, bootstrap_state,
+       effective_scopes, status, reason_code)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        record.id,
+        record.table,
+        JSON.stringify(record.scopes),
+        record.params ?? null,
+        record.cursor,
+        record.bootstrapState ?? null,
+        record.effectiveScopes === undefined
+            ? null
+            : JSON.stringify(record.effectiveScopes),
+        record.status,
+        record.reasonCode ?? null,
+    ]);
+}
+export function deleteSubscription(db, id) {
+    db.exec('DELETE FROM _syncular_subscriptions WHERE id = ?', [id]);
+}
+/**
+ * §7.4.3 reset: keep every subscription REGISTRATION (id, table,
+ * requested scopes, params — the app's declared intent) but discard all
+ * synced state (cursor → -1, no resume token, no effective-scope map,
+ * status → active), so the next round fresh-bootstraps exactly the
+ * subscriptions the app still wants. Caller owns the transaction.
+ */
+export function resetSubscriptionsForBump(db) {
+    db.exec(`UPDATE _syncular_subscriptions
+       SET cursor = -1, bootstrap_state = NULL, effective_scopes = NULL,
+           status = 'active', reason_code = NULL`);
+}
+export function getMeta(db, key) {
+    const row = db.query('SELECT value FROM _syncular_meta WHERE key = ?', [
+        key,
+    ])[0];
+    return row === undefined ? undefined : row.value;
+}
+export function setMeta(db, key, value) {
+    db.exec('INSERT OR REPLACE INTO _syncular_meta(key, value) VALUES (?, ?)', [
+        key,
+        value,
+    ]);
+}

package/dist/transport.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Transport seams (REVISE B3): request/response bytes, segment download,
+ * and the realtime attach surface matching §8's client side. Tests use
+ * loopback implementations that call the server library directly — the
+ * loopback doctrine; HTTP/WebSocket bindings live in `./http`.
+ */
+/** One combined push+pull round trip: SSP2 request bytes → response bytes. */
+export type SyncTransport = (request: Uint8Array) => Promise<Uint8Array>;
+export interface SegmentFetchRequest {
+    readonly segmentId: string;
+    readonly table: string;
+    /** Canonical JSON (§11.2) of the requested scope map (§5.5 header). */
+    readonly requestedScopesJson: string;
+}
+/**
+ * Fetch segment bytes from the direct endpoint (§5.5). `fetchUrl`, when
+ * present, is the §5.4 direct-URL capability: its presence makes the
+ * client advertise accept bit 3, and the client core then routes
+ * url-carrying descriptors through it — capability negotiation, never a
+ * fallback pair. A `fetchUrl` implementation MUST NOT attach host
+ * authentication (the URL is the entire grant, §5.4).
+ */
+export interface SegmentDownloader {
+    (request: SegmentFetchRequest): Promise<Uint8Array>;
+    readonly fetchUrl?: (url: string) => Promise<Uint8Array>;
+}
+export interface RealtimeHandlers {
+    /** JSON control frame (§8.1): hello / sync / heartbeat / unknown. */
+    onText(text: string): void;
+    /** Binary frame: channel tag byte + payload (§8.7) — a `0x00`-tagged
+     * standalone SSP2 response (delta) or a `0x01`-tagged round chunk. */
+    onBinary(bytes: Uint8Array): void;
+    onClose?(): void;
+}
+export interface RealtimeSocket {
+    /** Send a JSON control message (acks, §8.2). */
+    send(text: string): void;
+    /** Send one binary message (tagged round chunk, §8.7). The socket is
+     * the sync-round transport whenever it is connected — Direction
+     * decision 1: one loop, no fallback pair. */
+    sendBytes(bytes: Uint8Array): void;
+    close(): void;
+}
+export type RealtimeConnector = (handlers: RealtimeHandlers) => Promise<RealtimeSocket> | RealtimeSocket;

package/dist/transport.js

@@ -0,0 +1,7 @@
+/**
+ * Transport seams (REVISE B3): request/response bytes, segment download,
+ * and the realtime attach surface matching §8's client side. Tests use
+ * loopback implementations that call the server library directly — the
+ * loopback doctrine; HTTP/WebSocket bindings live in `./http`.
+ */
+export {};