@syncular/client 0.30.14 → 0.30.15

package/README.md

@@ -818,3 +818,13 @@ See [windowing](https://syncular.dev/concepts-windowing/) and
 Custom database adapters implementing `withSqliteImage` must return a promise and
 await their callback before detaching the image. The callback can await between
 committed import chunks; no write transaction spans that await.
+
+## Preflight authority reads
+
+Pass `authorityReads: defineAuthorityReads([{ table, columns, scopes }])` at
+creation to enable the zero-argument `authoritySnapshot()`. It reads approved
+plain authority columns and accepted bases with revision and persisted scope
+coverage from one SQLite snapshot, including during security preflight.
+Unaccepted local intent remains separate. The read changes no keys, transport,
+subscriptions or lifecycle. See the [authority contract](../../docs/SPEC.md)
+and [native configuration](../tauri/README.md#authority-evidence-before-activation).

package/dist/authority.d.ts

@@ -0,0 +1,43 @@
+import type { ClientDatabase, SqlRow } from './database.js';
+import type { CompiledClientSchema } from './schema.js';
+/** Frozen at client creation. Scope selectors use the schema's variables. */
+export interface AuthorityReadDeclaration {
+    readonly table: string;
+    readonly columns: readonly string[];
+    readonly scopes: Readonly<Record<string, readonly string[]>>;
+}
+export interface AuthoritySnapshot {
+    readonly revision: bigint;
+    readonly complete: boolean;
+    readonly tables: readonly {
+        readonly table: string;
+        readonly rows: readonly {
+            readonly values: SqlRow;
+            readonly version: number;
+            readonly hasLocalIntent: boolean;
+        }[];
+        /** Includes local-only creations; no intended values are disclosed. */
+        readonly localIntentRowIds: readonly string[];
+        readonly coverage: 'complete' | 'pending' | 'missing';
+        readonly scopes: AuthorityReadDeclaration['scopes'];
+        readonly persisted: readonly {
+            readonly requestedScopes: AuthorityReadDeclaration['scopes'];
+            readonly status: string;
+            readonly cursor: number;
+            readonly effectiveScopes: AuthorityReadDeclaration['scopes'] | null;
+            readonly complete: boolean;
+        }[];
+    }[];
+}
+/** Opt-in policy module; ordinary clients ship no authority reader. */
+export declare class AuthorityReadPolicy {
+    #private;
+    get declarations(): readonly AuthorityReadDeclaration[];
+    constructor(declarations: readonly AuthorityReadDeclaration[]);
+    /** @internal */
+    validate(schema: CompiledClientSchema): void;
+    /** @internal */
+    snapshot(db: ClientDatabase, schema: CompiledClientSchema): AuthoritySnapshot;
+}
+/** Declare authority tables, plain columns and scope selectors at creation. */
+export declare function defineAuthorityReads(declarations: readonly AuthorityReadDeclaration[]): AuthorityReadPolicy;

package/dist/authority.js

@@ -0,0 +1,257 @@
+import { ClientSyncError } from './errors.js';
+import { listOutbox, listOutboxBeforeImages } from './outbox.js';
+import { RETAINED_ROWS } from './failed-overlay.js';
+import { getLocalRevision, getMeta, loadSubscriptions } from './state.js';
+import { fromSqlValue, quoteIdent, SYNC_VERSION_COLUMN } from './schema.js';
+function validateAuthorityReads(schema, declarations) {
+    if (!Array.isArray(declarations))
+        throw new ClientSyncError('client.authority_read_forbidden', 'authorityReads must be a list');
+    const seen = new Set();
+    for (const read of declarations) {
+        if (!read ||
+            typeof read !== 'object' ||
+            !Array.isArray(read.columns) ||
+            !read.scopes ||
+            typeof read.scopes !== 'object' ||
+            Array.isArray(read.scopes))
+            throw new ClientSyncError('client.authority_read_forbidden', 'invalid authority declaration');
+        const table = schema.tables.get(read.table);
+        const plain = (name) => table?.columns.some((c) => c.name === name &&
+            name !== 'authority_version' &&
+            !name.startsWith('_sync') &&
+            !c.encrypted &&
+            ['string', 'integer', 'float', 'boolean', 'json'].includes(c.type));
+        if (Object.keys(read).sort().join() !== 'columns,scopes,table' ||
+            !table ||
+            seen.has(read.table) ||
+            !read.columns.length ||
+            new Set(read.columns).size !== read.columns.length ||
+            !read.columns.includes(table.primaryKey) ||
+            !read.columns.every(plain) ||
+            !Object.keys(read.scopes).length ||
+            !Object.entries(read.scopes).every(([variable, values]) => read.columns.includes(table.scopeColumnByVariable.get(variable) ?? '') &&
+                plain(table.scopeColumnByVariable.get(variable) ?? '') &&
+                Array.isArray(values) &&
+                values.length > 0 &&
+                values.every((v) => typeof v === 'string' && v.length > 0 && v !== '*'))) {
+            throw new ClientSyncError('client.authority_read_forbidden', 'authority reads require declared tables, plain columns, a primary key and nonempty plain scope selectors');
+        }
+        Object.freeze(read.columns);
+        for (const values of Object.values(read.scopes))
+            Object.freeze(values);
+        Object.freeze(read.scopes);
+        Object.freeze(read);
+        seen.add(read.table);
+    }
+}
+/** Read accepted bases without restoring or replaying the visible projection. */
+function readAuthoritySnapshot(db, schema, declarations) {
+    if (!declarations.length)
+        throw new ClientSyncError('client.authority_read_forbidden', 'no authority reads were declared at client creation');
+    return db.transaction(() => {
+        const raw = getMeta(db, 'localRevision');
+        if (raw === undefined ||
+            !/^(0|[1-9][0-9]*)$/.test(raw) ||
+            BigInt(raw) > 18446744073709551615n)
+            throw new ClientSyncError('sync.local_corrupt', 'authority revision is missing or invalid');
+        const revision = getLocalRevision(db);
+        const subscriptions = loadSubscriptions(db);
+        const tables = declarations.map((read) => {
+            const table = schema.tables.get(read.table);
+            const columns = [
+                ...new Set([
+                    ...read.columns,
+                    ...Object.keys(read.scopes).map((v) => table.scopeColumnByVariable.get(v)),
+                ]),
+            ];
+            const scalar = (column, value) => {
+                if (value === null || typeof value === 'object')
+                    throw new ClientSyncError('sync.local_corrupt', 'authority scalar is missing or invalid');
+                return String(fromSqlValue(table.columns[table.columnIndex.get(column)], value));
+            };
+            const matches = (values) => Object.entries(read.scopes).every(([v, held]) => {
+                const column = table.scopeColumnByVariable.get(v);
+                return (values[column] !== null &&
+                    values[column] !== undefined &&
+                    held.includes(scalar(column, values[column])));
+            });
+            const bases = new Map();
+            const intent = new Set();
+            const relevantIntent = new Set();
+            // FIFO before-images precede the earliest still-pending intent.
+            for (const commit of listOutbox(db)) {
+                const images = listOutboxBeforeImages(db, commit.clientCommitId);
+                for (const [idx, op] of commit.operations.entries())
+                    if (op.table === read.table) {
+                        intent.add(op.rowId);
+                        if (op.values && matches(op.values))
+                            relevantIntent.add(op.rowId);
+                        if (bases.has(op.rowId))
+                            continue;
+                        const image = images.find((i) => i.opIndex === idx);
+                        if (!image ||
+                            (image.existed &&
+                                (image.values === undefined || image.syncVersion === undefined)))
+                            throw new ClientSyncError('sync.local_corrupt', 'authority intent before-image is missing');
+                        bases.set(op.rowId, {
+                            values: image.values ?? null,
+                            version: image.syncVersion ?? -1,
+                        });
+                    }
+            }
+            // A retained/ACK base precedes pending edits stacked over that intent.
+            const retained = new Set();
+            for (const row of db.query(`SELECT id,base,version,intent FROM ${RETAINED_ROWS} WHERE tbl=? ORDER BY commit_seq,at,commit_id,idx`, [read.table])) {
+                const id = String(row.id);
+                if (row.base !== null && row.version === null)
+                    throw new ClientSyncError('sync.local_corrupt', 'authority base version is missing');
+                intent.add(id);
+                if (row.intent !== null && matches(JSON.parse(String(row.intent))))
+                    relevantIntent.add(id);
+                if (!retained.has(id))
+                    bases.set(id, {
+                        values: row.base === null ? null : JSON.parse(String(row.base)),
+                        version: Number(row.version ?? -1),
+                    });
+                retained.add(id);
+            }
+            const visible = db.query(`SELECT ${columns.map(quoteIdent).join(',')},${SYNC_VERSION_COLUMN} FROM ${quoteIdent(read.table)}`);
+            for (const row of visible) {
+                const id = scalar(table.primaryKey, row[table.primaryKey]);
+                if (!bases.has(id))
+                    bases.set(id, {
+                        values: row,
+                        version: Number(row[SYNC_VERSION_COLUMN]),
+                    });
+            }
+            const rows = [...bases]
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                .flatMap(([id, base]) => {
+                if (!Number.isSafeInteger(base.version) ||
+                    base.version < -1 ||
+                    (base.values &&
+                        base.version >= 0 &&
+                        !read.columns.every((c) => Object.hasOwn(base.values, c))))
+                    throw new ClientSyncError('sync.local_corrupt', 'authority base evidence is incomplete');
+                if (!base.values || base.version < 0 || !matches(base.values))
+                    return [];
+                return [
+                    {
+                        values: Object.fromEntries(read.columns.map((c) => [
+                            c,
+                            typeof base.values[c] === 'boolean'
+                                ? base.values[c]
+                                    ? 1
+                                    : 0
+                                : (base.values[c] ?? null),
+                        ])),
+                        version: base.version,
+                        hasLocalIntent: intent.has(id),
+                    },
+                ];
+            });
+            const persisted = subscriptions
+                .filter((s) => s.table === read.table)
+                .map((s) => {
+                const effective = s.effectiveScopes;
+                const complete = effective !== undefined &&
+                    Object.keys(effective).length === Object.keys(read.scopes).length &&
+                    s.status === 'active' &&
+                    s.cursor >= 0 &&
+                    s.bootstrapState === undefined &&
+                    s.params === undefined;
+                return {
+                    requestedScopes: Object.fromEntries(Object.keys(read.scopes).map((v) => [v, s.scopes[v] ?? []])),
+                    status: s.status,
+                    cursor: s.cursor,
+                    effectiveScopes: effective === undefined
+                        ? null
+                        : Object.fromEntries(Object.keys(read.scopes).map((v) => [
+                            v,
+                            effective[v] ?? [],
+                        ])),
+                    complete,
+                };
+            });
+            const selectors = Object.entries(read.scopes);
+            const covered = (at, candidates) => at === selectors.length
+                ? candidates.length > 0
+                : selectors[at][1].every((value) => covered(at + 1, candidates.filter((p) => p.effectiveScopes?.[selectors[at][0]]?.some((held) => held === value || held === '*'))));
+            const coverage = covered(0, persisted.filter((p) => p.complete))
+                ? 'complete'
+                : persisted.some((p) => p.status === 'active' &&
+                    selectors.every(([v, values]) => values.some((value) => p.requestedScopes[v]?.includes(value))))
+                    ? 'pending'
+                    : 'missing';
+            return {
+                table: read.table,
+                rows,
+                localIntentRowIds: [...intent]
+                    .filter((id) => relevantIntent.has(id) ||
+                    rows.some((row) => scalar(table.primaryKey, row.values[table.primaryKey]) ===
+                        id) ||
+                    visible.some((row) => scalar(table.primaryKey, row[table.primaryKey]) === id &&
+                        matches(row)))
+                    .sort(),
+                scopes: read.scopes,
+                coverage,
+                persisted,
+            };
+        });
+        return {
+            revision,
+            complete: tables.every((t) => t.coverage === 'complete'),
+            tables,
+        };
+    });
+}
+/** Opt-in policy module; ordinary clients ship no authority reader. */
+export class AuthorityReadPolicy {
+    #declarations;
+    get declarations() {
+        return this.#declarations;
+    }
+    constructor(declarations) {
+        if (!Array.isArray(declarations))
+            throw new ClientSyncError('client.authority_read_forbidden', 'authorityReads must be a list');
+        this.#declarations = structuredClone(declarations);
+        for (const read of this.#declarations) {
+            if (!read ||
+                typeof read !== 'object' ||
+                !Array.isArray(read.columns) ||
+                !read.scopes ||
+                typeof read.scopes !== 'object' ||
+                Array.isArray(read.scopes))
+                throw new ClientSyncError('client.authority_read_forbidden', 'invalid authority declaration');
+            Object.freeze(read.columns);
+            for (const values of Object.values(read.scopes))
+                Object.freeze(values);
+            Object.freeze(read.scopes);
+            Object.freeze(read);
+        }
+        Object.freeze(this.#declarations);
+        Object.freeze(this);
+    }
+    /** @internal */
+    validate(schema) {
+        validateAuthorityReads(schema, this.declarations);
+        Object.freeze(this.declarations);
+        Object.freeze(this);
+    }
+    /** @internal */
+    snapshot(db, schema) {
+        validateAuthorityReads(schema, this.declarations);
+        try {
+            return readAuthoritySnapshot(db, schema, this.declarations);
+        }
+        catch (error) {
+            if (error instanceof SyntaxError)
+                throw new ClientSyncError('sync.local_corrupt', 'authority persisted evidence is invalid');
+            throw error;
+        }
+    }
+}
+/** Declare authority tables, plain columns and scope selectors at creation. */
+export function defineAuthorityReads(declarations) {
+    return new AuthorityReadPolicy(declarations);
+}

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import type { AuthorityReadPolicy, AuthoritySnapshot } from './authority.js';
 import { type SyncProgress, type SyncProgressListener } from './progress.js';
 /**
  * SyncClient implements the client side of SPEC.md §§3–8.
@@ -174,6 +175,7 @@ export interface SyncClientConfig {
      * hosts must not materialize key bytes before their preflight has passed.
      */
     readonly securityPreflight?: boolean;
+    readonly authorityReads?: AuthorityReadPolicy;
     /**
      * RFC 0005 previous-version context. A feature flag, default off: when
      * absent or `enabled: false`, a schema bump behaves exactly as 0.22.0 did
@@ -326,6 +328,8 @@ export declare class SyncClient {
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
     /** Current durable local observer revision (SPEC §7.5). */
     get localRevision(): LocalRevision;
+    /** Read the creation-time plain authority policy, including preflight. */
+    authoritySnapshot(): AuthoritySnapshot;
     /**
      * Read rows, window answerability, and revision from one SQLite snapshot.
      * Reactive integrations use this instead of composing `query()` and

package/dist/client.js

@@ -130,6 +130,7 @@ function realtimeErrorCode(error) {
 }
 export class SyncClient {
     #config;
+    #authorityReads;
     #db;
     #schema;
     /** §5.11 client-side encryption config; undefined ⇒ E2EE off. */
@@ -237,6 +238,8 @@ export class SyncClient {
         this.#retainFailedCommits = config.retainFailedCommits === true;
         this.#db = config.database;
         this.#schema = compileClientSchema(config.schema);
+        this.#authorityReads = config.authorityReads;
+        this.#authorityReads?.validate(this.#schema);
         const realtimePolicy = config.realtimePolicy ?? 'optional';
         if (realtimePolicy !== 'required' &&
             realtimePolicy !== 'optional' &&
@@ -541,6 +544,7 @@ export class SyncClient {
         });
     }
     async close() {
+        this.#started = false;
         this.#emitSyncIntent({ kind: 'none' });
         this.#devtoolsUnregister?.();
         this.#devtoolsUnregister = undefined;
@@ -548,7 +552,6 @@ export class SyncClient {
         this.#abortPendingRound('client closed mid-round');
         await this.#lease?.release();
         this.#lease = undefined;
-        this.#started = false;
         this.#progress.clear();
         this.#syncNeededListeners.clear();
         this.#syncIntentListeners.clear();
@@ -696,6 +699,13 @@ export class SyncClient {
         this.#requireStarted();
         return getLocalRevision(this.#db);
     }
+    /** Read the creation-time plain authority policy, including preflight. */
+    authoritySnapshot() {
+        this.#requireStarted();
+        if (!this.#authorityReads || arguments.length)
+            throw new ClientSyncError('client.authority_read_forbidden', 'authority read denied');
+        return this.#authorityReads.snapshot(this.#db, this.#schema);
+    }
     /**
      * Read rows, window answerability, and revision from one SQLite snapshot.
      * Reactive integrations use this instead of composing `query()` and
@@ -714,24 +724,13 @@ export class SyncClient {
                 const missing = [];
                 for (const requested of spec.coverage ?? []) {
                     const baseKey = windowBaseKey(requested.base);
-                    const live = new Map(loadWindowUnits(this.#db, baseKey).map((entry) => [
-                        entry.unit,
-                        entry.subId,
-                    ]));
+                    const state = this.windowState(requested.base);
                     for (const unit of new Set(requested.units)) {
-                        const subId = live.get(unit);
                         const ref = { baseKey, unit };
-                        if (subId === undefined) {
+                        if (!state.units.includes(unit))
                             missing.push(ref);
-                            continue;
-                        }
-                        const sub = getSubscription(this.#db, subId);
-                        if (sub === undefined ||
-                            sub.status !== 'active' ||
-                            sub.cursor < 0 ||
-                            sub.bootstrapState !== undefined) {
+                        else if (state.pending.includes(unit))
                             pending.push(ref);
-                        }
                     }
                 }
                 return {
@@ -1044,7 +1043,7 @@ export class SyncClient {
                 item.id.length === 0 ||
                 typeof item.table !== 'string' ||
                 item.table.length === 0) {
-                throw invalidRequest('diagnosticsSnapshot expected subscriptions require non-empty id and table strings');
+                throw invalidRequest('diagnosticsSnapshot needs subscription id and table');
             }
             const registeredSubscription = subscriptions.get(item.id);
             if (registeredSubscription !== undefined &&
@@ -2154,7 +2153,7 @@ export class SyncClient {
             };
         }
         if (this.#schemaFloor !== undefined) {
-            throw invalidRequest('local rebootstrap cannot bypass an active schema-floor stop; update the application first');
+            throw invalidRequest('local rebootstrap needs a schema-floor update');
         }
         const pending = listOutbox(this.#db);
         const resetSubscriptions = loadSubscriptions(this.#db).length;
@@ -3843,13 +3842,13 @@ export class SyncClient {
     }
     #requireStarted() {
         if (!this.#started) {
-            throw invalidRequest('call SyncClient.start() first');
+            throw invalidRequest('call start() first');
         }
     }
     #requireActive() {
         this.#requireStarted();
         if (this.#securityLifecycle === 'preflight') {
-            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'security preflight must complete before accessing protected data; call activateSecurity');
+            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'protected reads require activateSecurity');
         }
     }
 }

package/dist/index.d.ts

@@ -8,6 +8,7 @@
  * (`worker-host`) and the RPC protocol types are root exports — they
  * import no SQLite.
  */
+export { defineAuthorityReads, type AuthorityReadPolicy, type AuthorityReadDeclaration, type AuthoritySnapshot, } from './authority.js';
 export * from './apply.js';
 export * from './availability.js';
 export * from './blob.js';

package/dist/index.js

@@ -8,6 +8,7 @@
  * (`worker-host`) and the RPC protocol types are root exports — they
  * import no SQLite.
  */
+export { defineAuthorityReads, } from './authority.js';
 export * from './apply.js';
 export * from './availability.js';
 export * from './blob.js';

package/dist/worker-entry.js

@@ -13,6 +13,7 @@
  * RPC-driven and auto-driven sync rounds serialize on one queue because
  * the core owns exactly one loop.
  */
+import { defineAuthorityReads } from './authority.js';
 import { SyncClient } from './client.js';
 import { withClientDiagnosticsHost, } from './diagnostics.js';
 import { encryptionConfigFromKeyring } from './encryption.js';
@@ -233,6 +234,9 @@ export function startSyncWorker(overrides = {}) {
             ...(config.encryption !== undefined
                 ? { encryption: encryptionConfigFromKeyring(config.encryption) }
                 : {}),
+            ...(config.authorityReads !== undefined
+                ? { authorityReads: defineAuthorityReads(config.authorityReads) }
+                : {}),
             ...(config.securityPreflight !== undefined
                 ? { securityPreflight: config.securityPreflight }
                 : {}),
@@ -342,6 +346,7 @@ export function startSyncWorker(overrides = {}) {
             return serializedSync(() => running.syncUntilIdle(maxRounds));
         },
         query: (sql, params) => requireClient().query(sql, params),
+        authoritySnapshot: () => requireClient().authoritySnapshot(),
         querySnapshot: (spec) => requireClient().querySnapshot(spec),
         localRevision: () => requireClient().localRevision,
         statusSnapshot: () => requireClient().statusSnapshot(),
@@ -420,6 +425,8 @@ export function startSyncWorker(overrides = {}) {
         'previousVersionDiscard',
     ]);
     async function dispatch(message) {
+        if (message.method === 'authoritySnapshot' && message.args.length)
+            throw new ClientSyncError('client.authority_read_forbidden', 'authoritySnapshot accepts no arguments');
         const method = api[message.method];
         const invoke = () => method.apply(api, message.args);
         if (syncChainMethods.has(message.method)) {

package/dist/worker-host.d.ts

@@ -83,6 +83,8 @@ export interface SyncClientHandleConfig {
     readonly headers?: Readonly<Record<string, string>>;
     /** Structured-clone-safe E2EE keyring installed only in the leader worker. */
     readonly encryption?: EncryptionKeyringConfig;
+    /** Fixed plain authority reads permitted before security activation. */
+    readonly authorityReads?: import('./authority.js').AuthorityReadPolicy;
     /** Open the worker-owned replica behind the fail-closed security gate. */
     readonly securityPreflight?: boolean;
     readonly transportEnabled?: boolean;
@@ -244,6 +246,7 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
+    authoritySnapshot(): Promise<import('./authority.js').AuthoritySnapshot>;
     querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
     localRevision(): Promise<LocalRevision>;
     statusSnapshot(): Promise<SyncStatusSnapshot>;

package/dist/worker-host.js

@@ -332,6 +332,11 @@ export class SyncClientHandle {
     query(sql, params) {
         return this.#call('query', [sql, params]);
     }
+    authoritySnapshot() {
+        if (arguments.length)
+            throw new ClientSyncError('client.authority_read_forbidden', 'authoritySnapshot accepts no arguments');
+        return this.#call('authoritySnapshot', []);
+    }
     querySnapshot(spec) {
         return this.#call('querySnapshot', [spec]);
     }
@@ -569,6 +574,9 @@ function buildInitConfig(config, headers = config.headers) {
         ...(config.transportEnabled !== undefined
             ? { transportEnabled: config.transportEnabled }
             : {}),
+        ...(config.authorityReads !== undefined
+            ? { authorityReads: config.authorityReads.declarations }
+            : {}),
         ...(config.securityPreflight !== undefined
             ? { securityPreflight: config.securityPreflight }
             : {}),

package/dist/worker-protocol.d.ts

@@ -77,6 +77,7 @@ export interface WorkerInitConfig {
     /** Portable raw keyring installed inside the worker-owned client core. */
     readonly encryption?: EncryptionKeyringConfig;
     /** Open the worker-owned replica behind the fail-closed security gate. */
+    readonly authorityReads?: readonly import('./authority.js').AuthorityReadDeclaration[];
     readonly securityPreflight?: boolean;
     readonly transportEnabled?: boolean;
     readonly clientId?: string;
@@ -138,6 +139,7 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
+    authoritySnapshot(): import('./authority.js').AuthoritySnapshot;
     querySnapshot(spec: QueryReadSpec): QuerySnapshot;
     localRevision(): LocalRevision;
     pendingCommits(): OutboxCommit[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.30.14",
+  "version": "0.30.15",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,10 +89,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.30.14"
+    "@syncular/core": "0.30.15"
   },
   "devDependencies": {
-    "@syncular/server": "0.30.14",
+    "@syncular/server": "0.30.15",
     "playwright": "1.63.0",
     "@electric-sql/pglite": "^0.5.4"
   }

package/src/authority.ts

@@ -0,0 +1,414 @@
+import type { ClientDatabase, SqlRow, SqlValue } from './database';
+import { ClientSyncError } from './errors';
+import { listOutbox, listOutboxBeforeImages } from './outbox';
+import { RETAINED_ROWS } from './failed-overlay';
+import { getLocalRevision, getMeta, loadSubscriptions } from './state';
+import { fromSqlValue, quoteIdent, SYNC_VERSION_COLUMN } from './schema';
+import type { CompiledClientSchema, JsonRowValue } from './schema';
+
+/** Frozen at client creation. Scope selectors use the schema's variables. */
+export interface AuthorityReadDeclaration {
+  readonly table: string;
+  readonly columns: readonly string[];
+  readonly scopes: Readonly<Record<string, readonly string[]>>;
+}
+export interface AuthoritySnapshot {
+  readonly revision: bigint;
+  readonly complete: boolean;
+  readonly tables: readonly {
+    readonly table: string;
+    readonly rows: readonly {
+      readonly values: SqlRow;
+      readonly version: number;
+      readonly hasLocalIntent: boolean;
+    }[];
+    /** Includes local-only creations; no intended values are disclosed. */
+    readonly localIntentRowIds: readonly string[];
+    readonly coverage: 'complete' | 'pending' | 'missing';
+    readonly scopes: AuthorityReadDeclaration['scopes'];
+    readonly persisted: readonly {
+      readonly requestedScopes: AuthorityReadDeclaration['scopes'];
+      readonly status: string;
+      readonly cursor: number;
+      readonly effectiveScopes: AuthorityReadDeclaration['scopes'] | null;
+      readonly complete: boolean;
+    }[];
+  }[];
+}
+
+function validateAuthorityReads(
+  schema: CompiledClientSchema,
+  declarations: readonly AuthorityReadDeclaration[],
+): void {
+  if (!Array.isArray(declarations))
+    throw new ClientSyncError(
+      'client.authority_read_forbidden',
+      'authorityReads must be a list',
+    );
+  const seen = new Set<string>();
+  for (const read of declarations) {
+    if (
+      !read ||
+      typeof read !== 'object' ||
+      !Array.isArray(read.columns) ||
+      !read.scopes ||
+      typeof read.scopes !== 'object' ||
+      Array.isArray(read.scopes)
+    )
+      throw new ClientSyncError(
+        'client.authority_read_forbidden',
+        'invalid authority declaration',
+      );
+    const table = schema.tables.get(read.table);
+    const plain = (name: string) =>
+      table?.columns.some(
+        (c) =>
+          c.name === name &&
+          name !== 'authority_version' &&
+          !name.startsWith('_sync') &&
+          !c.encrypted &&
+          ['string', 'integer', 'float', 'boolean', 'json'].includes(c.type),
+      );
+    if (
+      Object.keys(read).sort().join() !== 'columns,scopes,table' ||
+      !table ||
+      seen.has(read.table) ||
+      !read.columns.length ||
+      new Set(read.columns).size !== read.columns.length ||
+      !read.columns.includes(table.primaryKey) ||
+      !read.columns.every(plain) ||
+      !Object.keys(read.scopes).length ||
+      !Object.entries(read.scopes).every(
+        ([variable, values]) =>
+          read.columns.includes(
+            table.scopeColumnByVariable.get(variable) ?? '',
+          ) &&
+          plain(table.scopeColumnByVariable.get(variable) ?? '') &&
+          Array.isArray(values) &&
+          values.length > 0 &&
+          values.every(
+            (v) => typeof v === 'string' && v.length > 0 && v !== '*',
+          ),
+      )
+    ) {
+      throw new ClientSyncError(
+        'client.authority_read_forbidden',
+        'authority reads require declared tables, plain columns, a primary key and nonempty plain scope selectors',
+      );
+    }
+    Object.freeze(read.columns);
+    for (const values of Object.values(read.scopes)) Object.freeze(values);
+    Object.freeze(read.scopes);
+    Object.freeze(read);
+    seen.add(read.table);
+  }
+}
+
+/** Read accepted bases without restoring or replaying the visible projection. */
+function readAuthoritySnapshot(
+  db: ClientDatabase,
+  schema: CompiledClientSchema,
+  declarations: readonly AuthorityReadDeclaration[],
+): AuthoritySnapshot {
+  if (!declarations.length)
+    throw new ClientSyncError(
+      'client.authority_read_forbidden',
+      'no authority reads were declared at client creation',
+    );
+  return db.transaction(() => {
+    const raw = getMeta(db, 'localRevision');
+    if (
+      raw === undefined ||
+      !/^(0|[1-9][0-9]*)$/.test(raw) ||
+      BigInt(raw) > 18446744073709551615n
+    )
+      throw new ClientSyncError(
+        'sync.local_corrupt',
+        'authority revision is missing or invalid',
+      );
+    const revision = getLocalRevision(db);
+    const subscriptions = loadSubscriptions(db);
+    const tables = declarations.map((read) => {
+      const table = schema.tables.get(read.table)!;
+      const columns = [
+        ...new Set([
+          ...read.columns,
+          ...Object.keys(read.scopes).map((v) =>
+            table.scopeColumnByVariable.get(v)!,
+          ),
+        ]),
+      ];
+      const scalar = (
+        column: string,
+        value: SqlValue | JsonRowValue,
+      ): string => {
+        if (value === null || typeof value === 'object')
+          throw new ClientSyncError(
+            'sync.local_corrupt',
+            'authority scalar is missing or invalid',
+          );
+        return String(
+          fromSqlValue(table.columns[table.columnIndex.get(column)!]!, value),
+        );
+      };
+      const matches = (values: Record<string, SqlValue | JsonRowValue>) =>
+        Object.entries(read.scopes).every(([v, held]) => {
+          const column = table.scopeColumnByVariable.get(v)!;
+          return (
+            values[column] !== null &&
+            values[column] !== undefined &&
+            held.includes(scalar(column, values[column]!))
+          );
+        });
+      const bases = new Map<
+        string,
+        {
+          values: Record<string, JsonRowValue | SqlValue> | null;
+          version: number;
+        }
+      >();
+      const intent = new Set<string>();
+      const relevantIntent = new Set<string>();
+      // FIFO before-images precede the earliest still-pending intent.
+      for (const commit of listOutbox(db)) {
+        const images = listOutboxBeforeImages(db, commit.clientCommitId);
+        for (const [idx, op] of commit.operations.entries())
+          if (op.table === read.table) {
+            intent.add(op.rowId);
+            if (op.values && matches(op.values)) relevantIntent.add(op.rowId);
+            if (bases.has(op.rowId)) continue;
+            const image = images.find((i) => i.opIndex === idx);
+            if (
+              !image ||
+              (image.existed &&
+                (image.values === undefined || image.syncVersion === undefined))
+            )
+              throw new ClientSyncError(
+                'sync.local_corrupt',
+                'authority intent before-image is missing',
+              );
+            bases.set(op.rowId, {
+              values: image.values ?? null,
+              version: image.syncVersion ?? -1,
+            });
+          }
+      }
+      // A retained/ACK base precedes pending edits stacked over that intent.
+      const retained = new Set<string>();
+      for (const row of db.query(
+        `SELECT id,base,version,intent FROM ${RETAINED_ROWS} WHERE tbl=? ORDER BY commit_seq,at,commit_id,idx`,
+        [read.table],
+      )) {
+        const id = String(row.id);
+        if (row.base !== null && row.version === null)
+          throw new ClientSyncError(
+            'sync.local_corrupt',
+            'authority base version is missing',
+          );
+        intent.add(id);
+        if (row.intent !== null && matches(JSON.parse(String(row.intent))))
+          relevantIntent.add(id);
+        if (!retained.has(id))
+          bases.set(id, {
+            values: row.base === null ? null : JSON.parse(String(row.base)),
+            version: Number(row.version ?? -1),
+          });
+        retained.add(id);
+      }
+      const visible = db.query(
+        `SELECT ${columns.map(quoteIdent).join(',')},${SYNC_VERSION_COLUMN} FROM ${quoteIdent(read.table)}`,
+      );
+      for (const row of visible) {
+        const id = scalar(table.primaryKey, row[table.primaryKey]!);
+        if (!bases.has(id))
+          bases.set(id, {
+            values: row,
+            version: Number(row[SYNC_VERSION_COLUMN]),
+          });
+      }
+      const rows = [...bases]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .flatMap(([id, base]) => {
+          if (
+            !Number.isSafeInteger(base.version) ||
+            base.version < -1 ||
+            (base.values &&
+              base.version >= 0 &&
+              !read.columns.every((c) => Object.hasOwn(base.values!, c)))
+          )
+            throw new ClientSyncError(
+              'sync.local_corrupt',
+              'authority base evidence is incomplete',
+            );
+          if (!base.values || base.version < 0 || !matches(base.values))
+            return [];
+          return [
+            {
+              values: Object.fromEntries(
+                read.columns.map((c) => [
+                  c,
+                  typeof base.values![c] === 'boolean'
+                    ? base.values![c]
+                      ? 1
+                      : 0
+                    : (base.values![c] ?? null),
+                ]),
+              ) as SqlRow,
+              version: base.version,
+              hasLocalIntent: intent.has(id),
+            },
+          ];
+        });
+      const persisted = subscriptions
+        .filter((s) => s.table === read.table)
+        .map((s) => {
+          const effective = s.effectiveScopes;
+          const complete =
+            effective !== undefined &&
+            Object.keys(effective).length === Object.keys(read.scopes).length &&
+            s.status === 'active' &&
+            s.cursor >= 0 &&
+            s.bootstrapState === undefined &&
+            s.params === undefined;
+          return {
+            requestedScopes: Object.fromEntries(
+              Object.keys(read.scopes).map((v) => [v, s.scopes[v] ?? []]),
+            ),
+            status: s.status,
+            cursor: s.cursor,
+            effectiveScopes:
+              effective === undefined
+                ? null
+                : Object.fromEntries(
+                    Object.keys(read.scopes).map((v) => [
+                      v,
+                      effective[v] ?? [],
+                    ]),
+                  ),
+            complete,
+          };
+        });
+      const selectors = Object.entries(read.scopes);
+      const covered = (at: number, candidates: typeof persisted): boolean =>
+        at === selectors.length
+          ? candidates.length > 0
+          : selectors[at]![1].every((value) =>
+              covered(
+                at + 1,
+                candidates.filter((p) =>
+                  p.effectiveScopes?.[selectors[at]![0]]?.some(
+                    (held) => held === value || held === '*',
+                  ),
+                ),
+              ),
+            );
+      const coverage = covered(
+        0,
+        persisted.filter((p) => p.complete),
+      )
+        ? 'complete'
+        : persisted.some(
+              (p) =>
+                p.status === 'active' &&
+                selectors.every(([v, values]) =>
+                  values.some((value) => p.requestedScopes[v]?.includes(value)),
+                ),
+            )
+          ? 'pending'
+          : 'missing';
+      return {
+        table: read.table,
+        rows,
+        localIntentRowIds: [...intent]
+          .filter(
+            (id) =>
+              relevantIntent.has(id) ||
+              rows.some(
+                (row) =>
+                  scalar(table.primaryKey, row.values[table.primaryKey]!) ===
+                  id,
+              ) ||
+              visible.some(
+                (row) =>
+                  scalar(table.primaryKey, row[table.primaryKey]!) === id &&
+                  matches(row),
+              ),
+          )
+          .sort(),
+        scopes: read.scopes,
+        coverage,
+        persisted,
+      } as AuthoritySnapshot['tables'][number];
+    });
+    return {
+      revision,
+      complete: tables.every((t) => t.coverage === 'complete'),
+      tables,
+    };
+  });
+}
+
+/** Opt-in policy module; ordinary clients ship no authority reader. */
+export class AuthorityReadPolicy {
+  readonly #declarations: readonly AuthorityReadDeclaration[];
+  get declarations(): readonly AuthorityReadDeclaration[] {
+    return this.#declarations;
+  }
+  constructor(declarations: readonly AuthorityReadDeclaration[]) {
+    if (!Array.isArray(declarations))
+      throw new ClientSyncError(
+        'client.authority_read_forbidden',
+        'authorityReads must be a list',
+      );
+    this.#declarations = structuredClone(declarations);
+    for (const read of this.#declarations) {
+      if (
+        !read ||
+        typeof read !== 'object' ||
+        !Array.isArray(read.columns) ||
+        !read.scopes ||
+        typeof read.scopes !== 'object' ||
+        Array.isArray(read.scopes)
+      )
+        throw new ClientSyncError(
+          'client.authority_read_forbidden',
+          'invalid authority declaration',
+        );
+      Object.freeze(read.columns);
+      for (const values of Object.values(read.scopes)) Object.freeze(values);
+      Object.freeze(read.scopes);
+      Object.freeze(read);
+    }
+    Object.freeze(this.#declarations);
+    Object.freeze(this);
+  }
+  /** @internal */
+  validate(schema: CompiledClientSchema): void {
+    validateAuthorityReads(schema, this.declarations);
+    Object.freeze(this.declarations);
+    Object.freeze(this);
+  }
+  /** @internal */
+  snapshot(
+    db: ClientDatabase,
+    schema: CompiledClientSchema,
+  ): AuthoritySnapshot {
+    validateAuthorityReads(schema, this.declarations);
+    try {
+      return readAuthoritySnapshot(db, schema, this.declarations);
+    } catch (error) {
+      if (error instanceof SyntaxError)
+        throw new ClientSyncError(
+          'sync.local_corrupt',
+          'authority persisted evidence is invalid',
+        );
+      throw error;
+    }
+  }
+}
+/** Declare authority tables, plain columns and scope selectors at creation. */
+export function defineAuthorityReads(
+  declarations: readonly AuthorityReadDeclaration[],
+): AuthorityReadPolicy {
+  return new AuthorityReadPolicy(declarations);
+}

package/src/client.ts

@@ -1,4 +1,5 @@
 import { BLOB_COMMIT_REFS } from './blob';
+import type { AuthorityReadPolicy, AuthoritySnapshot } from './authority';
 import { hasUniqueIndex } from './schema';
 import { OUTCOMES_TABLE } from './outcomes';
 import { OUTBOX_TABLE } from './outbox';
@@ -424,6 +425,7 @@ export interface SyncClientConfig {
    * hosts must not materialize key bytes before their preflight has passed.
    */
   readonly securityPreflight?: boolean;
+  readonly authorityReads?: AuthorityReadPolicy;
   /**
    * RFC 0005 previous-version context. A feature flag, default off: when
    * absent or `enabled: false`, a schema bump behaves exactly as 0.22.0 did
@@ -746,6 +748,7 @@ export type ClientSnapshotReader = {
 
 export class SyncClient {
   readonly #config: SyncClientConfig;
+  readonly #authorityReads: AuthorityReadPolicy | undefined;
   readonly #db: ClientDatabase;
   readonly #schema: CompiledClientSchema;
   /** §5.11 client-side encryption config; undefined ⇒ E2EE off. */
@@ -860,6 +863,8 @@ export class SyncClient {
     this.#retainFailedCommits = config.retainFailedCommits === true;
     this.#db = config.database;
     this.#schema = compileClientSchema(config.schema);
+    this.#authorityReads = config.authorityReads;
+    this.#authorityReads?.validate(this.#schema);
     const realtimePolicy = config.realtimePolicy ?? 'optional';
     if (
       realtimePolicy !== 'required' &&
@@ -1232,6 +1237,7 @@ export class SyncClient {
   }
 
   async close(): Promise<void> {
+    this.#started = false;
     this.#emitSyncIntent({ kind: 'none' });
     this.#devtoolsUnregister?.();
     this.#devtoolsUnregister = undefined;
@@ -1239,7 +1245,6 @@ export class SyncClient {
     this.#abortPendingRound('client closed mid-round');
     await this.#lease?.release();
     this.#lease = undefined;
-    this.#started = false;
     this.#progress.clear();
     this.#syncNeededListeners.clear();
     this.#syncIntentListeners.clear();
@@ -1398,6 +1403,17 @@ export class SyncClient {
     return getLocalRevision(this.#db);
   }
 
+  /** Read the creation-time plain authority policy, including preflight. */
+  authoritySnapshot(): AuthoritySnapshot {
+    this.#requireStarted();
+    if (!this.#authorityReads || arguments.length)
+      throw new ClientSyncError(
+        'client.authority_read_forbidden',
+        'authority read denied',
+      );
+    return this.#authorityReads.snapshot(this.#db, this.#schema);
+  }
+
   /**
    * Read rows, window answerability, and revision from one SQLite snapshot.
    * Reactive integrations use this instead of composing `query()` and
@@ -1418,28 +1434,11 @@ export class SyncClient {
         const missing: WindowUnitRef[] = [];
         for (const requested of spec.coverage ?? []) {
           const baseKey = windowBaseKey(requested.base);
-          const live = new Map(
-            loadWindowUnits(this.#db, baseKey).map((entry) => [
-              entry.unit,
-              entry.subId,
-            ]),
-          );
+          const state = this.windowState(requested.base);
           for (const unit of new Set(requested.units)) {
-            const subId = live.get(unit);
             const ref = { baseKey, unit };
-            if (subId === undefined) {
-              missing.push(ref);
-              continue;
-            }
-            const sub = getSubscription(this.#db, subId);
-            if (
-              sub === undefined ||
-              sub.status !== 'active' ||
-              sub.cursor < 0 ||
-              sub.bootstrapState !== undefined
-            ) {
-              pending.push(ref);
-            }
+            if (!state.units.includes(unit)) missing.push(ref);
+            else if (state.pending.includes(unit)) pending.push(ref);
           }
         }
         return {
@@ -1817,7 +1816,7 @@ export class SyncClient {
         item.table.length === 0
       ) {
         throw invalidRequest(
-          'diagnosticsSnapshot expected subscriptions require non-empty id and table strings',
+          'diagnosticsSnapshot needs subscription id and table',
         );
       }
       const registeredSubscription = subscriptions.get(item.id);
@@ -3170,9 +3169,7 @@ export class SyncClient {
       };
     }
     if (this.#schemaFloor !== undefined) {
-      throw invalidRequest(
-        'local rebootstrap cannot bypass an active schema-floor stop; update the application first',
-      );
+      throw invalidRequest('local rebootstrap needs a schema-floor update');
     }
 
     const pending = listOutbox(this.#db);
@@ -5331,7 +5328,7 @@ export class SyncClient {
 
   #requireStarted(): void {
     if (!this.#started) {
-      throw invalidRequest('call SyncClient.start() first');
+      throw invalidRequest('call start() first');
     }
   }
 
@@ -5340,7 +5337,7 @@ export class SyncClient {
     if (this.#securityLifecycle === 'preflight') {
       throw new ClientSyncError(
         SECURITY_PREFLIGHT_REQUIRED_CODE,
-        'security preflight must complete before accessing protected data; call activateSecurity',
+        'protected reads require activateSecurity',
       );
     }
   }

package/src/index.ts

@@ -8,6 +8,12 @@
  * (`worker-host`) and the RPC protocol types are root exports — they
  * import no SQLite.
  */
+export {
+  defineAuthorityReads,
+  type AuthorityReadPolicy,
+  type AuthorityReadDeclaration,
+  type AuthoritySnapshot,
+} from './authority';
 export * from './apply';
 export * from './availability';
 export * from './blob';

package/src/worker-entry.ts

@@ -13,6 +13,7 @@
  * RPC-driven and auto-driven sync rounds serialize on one queue because
  * the core owns exactly one loop.
  */
+import { defineAuthorityReads } from './authority';
 import { SyncClient } from './client';
 import type { ClientDatabase } from './database';
 import {
@@ -323,6 +324,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       ...(config.encryption !== undefined
         ? { encryption: encryptionConfigFromKeyring(config.encryption) }
         : {}),
+      ...(config.authorityReads !== undefined
+        ? { authorityReads: defineAuthorityReads(config.authorityReads) }
+        : {}),
       ...(config.securityPreflight !== undefined
         ? { securityPreflight: config.securityPreflight }
         : {}),
@@ -441,6 +445,7 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       return serializedSync(() => running.syncUntilIdle(maxRounds));
     },
     query: (sql, params) => requireClient().query(sql, params),
+    authoritySnapshot: () => requireClient().authoritySnapshot(),
     querySnapshot: (spec) => requireClient().querySnapshot(spec),
     localRevision: () => requireClient().localRevision,
     statusSnapshot: () => requireClient().statusSnapshot(),
@@ -520,6 +525,11 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
   ]);
 
   async function dispatch(message: WorkerCallMessage): Promise<unknown> {
+    if (message.method === 'authoritySnapshot' && message.args.length)
+      throw new ClientSyncError(
+        'client.authority_read_forbidden',
+        'authoritySnapshot accepts no arguments',
+      );
     const method = api[message.method] as (...args: unknown[]) => unknown;
     const invoke = () => method.apply(api, message.args as unknown[]);
     if (syncChainMethods.has(message.method)) {

package/src/worker-host.ts

@@ -192,6 +192,8 @@ export interface SyncClientHandleConfig {
   readonly headers?: Readonly<Record<string, string>>;
   /** Structured-clone-safe E2EE keyring installed only in the leader worker. */
   readonly encryption?: EncryptionKeyringConfig;
+  /** Fixed plain authority reads permitted before security activation. */
+  readonly authorityReads?: import('./authority').AuthorityReadPolicy;
   /** Open the worker-owned replica behind the fail-closed security gate. */
   readonly securityPreflight?: boolean;
   readonly transportEnabled?: boolean;
@@ -656,6 +658,15 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
     return this.#call('query', [sql, params]);
   }
 
+  authoritySnapshot(): Promise<import('./authority').AuthoritySnapshot> {
+    if (arguments.length)
+      throw new ClientSyncError(
+        'client.authority_read_forbidden',
+        'authoritySnapshot accepts no arguments',
+      );
+    return this.#call('authoritySnapshot', []);
+  }
+
   querySnapshot<Row = SqlRow>(
     spec: QueryReadSpec,
   ): Promise<QuerySnapshot<Row>> {
@@ -951,6 +962,9 @@ function buildInitConfig(
     ...(config.transportEnabled !== undefined
       ? { transportEnabled: config.transportEnabled }
       : {}),
+    ...(config.authorityReads !== undefined
+      ? { authorityReads: config.authorityReads.declarations }
+      : {}),
     ...(config.securityPreflight !== undefined
       ? { securityPreflight: config.securityPreflight }
       : {}),

package/src/worker-protocol.ts

@@ -111,6 +111,7 @@ export interface WorkerInitConfig {
   /** Portable raw keyring installed inside the worker-owned client core. */
   readonly encryption?: EncryptionKeyringConfig;
   /** Open the worker-owned replica behind the fail-closed security gate. */
+  readonly authorityReads?: readonly import('./authority').AuthorityReadDeclaration[];
   readonly securityPreflight?: boolean;
   readonly transportEnabled?: boolean;
   readonly clientId?: string;
@@ -186,6 +187,7 @@ export interface WorkerApi extends Omit<
   sync(): Promise<SyncSummary>;
   syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
   query(sql: string, params?: readonly SqlValue[]): SqlRow[];
+  authoritySnapshot(): import('./authority').AuthoritySnapshot;
   querySnapshot(spec: QueryReadSpec): QuerySnapshot;
   localRevision(): LocalRevision;
   pendingCommits(): OutboxCommit[];