snapback4 0.0.5 → 0.0.7

package/README.md

@@ -206,7 +206,11 @@ The horizon `last N by index` bounds what a device acquires per group;
 older rows are online-only, and a device's read past them says
 `complete: false`. Joining a group delivers its rows; leaving it delivers
 one scope tombstone, and the table's `retain` says what the device keeps.
-A table without `sync` is online-only: its queries run on the server.
+What it keeps under `delivered-history` it can still read locally through
+a query without a membership `require` (the server refuses the same query
+once the membership is gone, so a "history" query answers on the device
+and is empty online). A table without `sync` is online-only: its queries
+run on the server.
 
 ## 4. The client
 
@@ -227,10 +231,12 @@ durably and predicts its rows, and follows the server's stream for the
 rest. Its options: `url`; one of `persona` (development), `session` (from
 `snapback4/auth`, kept and restored by the client), or `guest: true`
 (mint one when none is kept); `store`; `sessionStore`; `fetch`;
-`waitSeconds`. It has `query`, `observe`, `mutate`, `link()`, `onLink`,
-`viewer()`, `session()`, `signOut()`, `sync()`, `replica`, `close()`. The
-online client takes `url` with `persona`, `session` or `token`, and has
-the same card without a store.
+`waitSeconds`. It has `query(op, args) → Read`, `observe(op, args) →
+{ getSnapshot(), subscribe(listener) → unsubscribe, close() }` (a live
+read; React's `useSyncExternalStore` shape), `mutate(op, args) → Write`,
+`link()`, `onLink`, `viewer()`, `session()`, `signOut()`, `sync()`,
+`replica`, `close()`. The online client takes `url` with `persona`,
+`session` or `token`, and has the same card without a store.
 
 ### The card
 
@@ -245,10 +251,14 @@ type Write = { state: "pending"; id } | { state: "sent"; id; seq } | { state: "f
 type Refusal = { code: string; family: "input" | "schema" | "auth" | "rule" | "constraint" | "bound" | "op" | "link" | "generation"; message: string; site?: string; rewrite?: string; guide?: string; retryable?: boolean };
 ```
 
-`complete` says the page is whole; `fresh` says the device has everything
-the server had at the last sync (`since` is the last sync's time when it
-does not); `next` is the cursor for the next page (pass it as the query's
-`cursor ?` argument). A row this device wrote and the server has not yet
+`complete` says this is everything the query can answer: false when the
+meter cut the page, when a scan's read rule is not decided by its prefix
+(§2, the meter), or when a page declared without a cursor had more rows
+than it holds (declare `c: cursor ?` and page with `after c`; `check`
+notes it). `fresh` says the device has everything the server had at the
+last sync (`since` is the last sync's time when it does not); `next` is
+the cursor for the next page (pass it as the query's `cursor ?` argument);
+a page with a cursor and more rows is `complete: true` with `next`. A row this device wrote and the server has not yet
 confirmed carries `pending: true`. A write is `pending` while the link is
 down (it lands when it returns), `sent` with the server's sequence, or
 `failed` with the refusal and its predicted rows withdrawn. `isReady`,
@@ -302,8 +312,12 @@ flips the link.
 - **`snapback4 run <op> '<json args>' --as alice [--json]`** runs one
   operation against the local store and prints the result and the meter.
 - **`snapback4 test [--fixture dir] [--as persona]`** loads a fixture
-  (one `<table>.jsonl` per table), runs every query, and prints the
-  meters beside the ceilings.
+  (one `<table>.jsonl` per table) into a fresh store in memory (without a
+  fixture, the project's dev store), runs every query as each persona with
+  arguments derived from the data (a reference is the table's first row,
+  a principal the persona, a text the shortest that fits), prints the
+  meters beside the ceilings and the arguments it used, and names any
+  query it could not run.
 - **`snapback4 check [--cost] [--json]`** compiles, writes
   `snapback/generated/api.ts` (`Rows`, `Ops`, `api`), and prints every
   diagnostic with its site and rewrite; `--cost` adds each site's

package/dist/replica/interpreter.d.ts

@@ -58,6 +58,8 @@ export declare class Interpreter {
     private written;
     private capped;
     private beyondHorizon;
+    /** The program's page had more rows and no cursor to continue on. */
+    private pageOverflow;
     private page;
     private pageDepth;
     private created;
@@ -89,7 +91,12 @@ export declare class Interpreter {
      * counted. */
     private visibility;
     private ruleTrue;
-    /** The read rule for one row, with probes over the replica. */
+    /** Whether the viewer may read a held row. A synced table's rows are
+     * the partition: the server delivered each under the read rule and
+     * withdrew what it revoked, so what the device holds it may read — and
+     * what `retain delivered-history` kept after a leave stays readable here
+     * even though the server now refuses it. Only an online-only table's
+     * rows (none, unless predicted) meet the rule on the device. */
     readable(table: string, row: Row): Promise<boolean>;
     private rule;
     private permitted;

package/dist/replica/interpreter.js

@@ -135,6 +135,8 @@ export class Interpreter {
     written = 0;
     capped = false;
     beyondHorizon = false;
+    /** The program's page had more rows and no cursor to continue on. */
+    pageOverflow = false;
     page = null;
     pageDepth = 0;
     created = new Set();
@@ -176,7 +178,7 @@ export class Interpreter {
         }
         const flow = await this.statements(program.body, program.name);
         const data = flow instanceof Flow && flow.kind === "return" ? flow.value : null;
-        return { data, complete: !this.capped && !this.beyondHorizon, next: this.capped ? null : this.nextCursor(), tables: this.tables };
+        return { data, complete: !this.capped && !this.beyondHorizon && !this.pageOverflow, next: this.capped ? null : this.nextCursor(), tables: this.tables };
     }
     nextCursor() {
         if (!this.page || !this.page.next)
@@ -595,6 +597,8 @@ export class Interpreter {
             if (held >= horizon.last)
                 this.beyondHorizon = true;
         }
+        if (this.pageDepth === 0 && !scan.opaque_cursor && hasMore)
+            this.pageOverflow = true;
         if (this.pageDepth === 0 && scan.opaque_cursor) {
             const columns = definition.indexes[index].components.length;
             this.page = { table, index, order, prefixLen: prefix.length, next: hasMore && lastKey && visible.length ? suffixOf(this.schema, table, index, visible[visible.length - 1], prefix.length).slice(0, columns - prefix.length) : null };
@@ -634,6 +638,8 @@ export class Interpreter {
         candidates.sort((a, b) => { const c = totalCompare(a.key, b.key); return order === "Asc" ? c : -c; });
         const hasMore = candidates.length > take;
         const page = candidates.slice(0, take);
+        if (this.pageDepth === 0 && !first.opaque_cursor && hasMore)
+            this.pageOverflow = true;
         if (this.pageDepth === 0 && first.opaque_cursor)
             this.page = { table, index, order, prefixLen, next: hasMore && page.length ? page[page.length - 1].key : null };
         return page.map((c) => c.row);
@@ -697,9 +703,17 @@ export class Interpreter {
             default: return false;
         }
     }
-    /** The read rule for one row, with probes over the replica. */
+    /** Whether the viewer may read a held row. A synced table's rows are
+     * the partition: the server delivered each under the read rule and
+     * withdrew what it revoked, so what the device holds it may read — and
+     * what `retain delivered-history` kept after a leave stays readable here
+     * even though the server now refuses it. Only an online-only table's
+     * rows (none, unless predicted) meet the rule on the device. */
     async readable(table, row) {
-        const rule = this.schema.tables[table].rules.read;
+        const definition = this.schema.tables[table];
+        if (definition?.sync)
+            return true;
+        const rule = definition.rules.read;
         return this.rule(rule, undefined, row, false);
     }
     async rule(rule, old, next, insert) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapback4",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "type": "module",
   "description": "Snapback 4: the card (contract), the online and local-first clients (IndexedDB, SQLite), React hooks, sign-in, a labelled mock, and the `snapback4` CLI. LLP 3000.",
   "bin": {
@@ -42,7 +42,7 @@
     "README.md"
   ],
   "optionalDependencies": {
-    "snapback4-darwin-arm64": "0.0.5"
+    "snapback4-darwin-arm64": "0.0.7"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",