nervur 0.22.2-3 → 0.22.2-5

package/AUTHORING.md

@@ -144,6 +144,12 @@ and TypeScript reads from it the types of her cells and her needs.
 | `roles` | named tests over the asker and her cells |
 | `state` | a function of the being that names her current state |
 | `asks` | one entry per method she answers |
+| `view` | markup as text over her asks, which a screen renders |
+
+A view is data, at most 64 KiB, carried in her describe to every asker.
+It holds no script, and a renderer loads nothing it names, so a view
+neither acts nor tracks. The library defines no markup: a renderer
+speaks its own.
 
 Every field is optional but `kind` and `asks`. A class with no `state`
 has one state, named `ready`. The kind is how the house finds her code
@@ -195,7 +201,7 @@ nothing lands.
 | `this.house.alarm({ at, ask, args, key })` | one of her asks, at that time |
 | `this.house.cancelAlarm({ key })` | an alarm removed |
 | `this.<need>.<method>({…}, { reply? })` | an awaited call, or an effect |
-| `this.held(id, Need).<ask>({…}, { reply? })` | the same, on a standing |
+| `this.held(id, Need).<ask>({…}, { reply?, after? })` | the same, on a standing, and a watch where `after` is given |
 | `this.standings` | `list()`, `note(id, notes)` and `drop(id)` |
 | `this.handle(ask, { bind?, notes?, once?, expires? })` | a handle to one of her asks |
 | `this.invite(id, { notes?, expires? })` | a new occupant, as a handle |
@@ -239,6 +245,29 @@ one receiver leave one at a time, in the order she called them.
 Asks to one being run one at a time, in the order they arrive. A
 `readOnly` ask runs beside that queue, on the cells last landed.
 
+### Watching an answer
+
+A watch is a `readOnly` ask asked with `after`, the answer you already
+hold. The house answers at once where the answer differs. Where it is
+the same, the house holds the ask and runs it again each time an ask of
+that being lands. It answers the first answer that differs, or the same
+one when the wait runs out. So a chat, an order's status or a dashboard
+is a loop of watches, and nothing polls.
+
+Through the hand, pass `after` beside the method, as the answer you
+hold: `{ result: [...] }`. From a being, pass the result she holds:
+`this.held(room, Messages).messages({}, { after: seen })`, inside a
+`readOnly` ask of her own, so she stays free while she waits. Only a
+`readOnly` ask is watched, and a watch on anything else is refused where
+she makes it.
+
+A watch moves only on what its asker could read, since it runs as that
+asker. One asker holds one watch on one ask with the same args, and a
+second answers the first at once. A watch across a door holds its
+relation until it answers, since Quo moves a relation one ask at a time.
+So watch a far being through a handle to the watched ask alone, a
+relation of its own, and ask everything else on your other standing.
+
 ### Relations
 
 An **occupant** is someone who may ask her. She mints one with
@@ -719,6 +748,50 @@ A user unit stops when its user logs out, unless lingering is enabled
 with `loginctl enable-linger`. On macOS, the agent goes to
 `~/Library/LaunchAgents/` and is started with `launchctl bootstrap`.
 
+### In a page
+
+`BrowserGround.open({ recipe })` from `nervur/browser` runs the same
+houses in a page. Every tab and the service worker of one origin share
+one ground: the one holding the Web Lock runs it, and the others reach
+its hand over a `BroadcastChannel`. When it closes, the next opens the
+ground from the same storage. `hand` answers the same three requests
+the command sends: `describe`, a faculty's method, and an ask of a being
+in a named house.
+
+Its bodies are the browser's. Seeds are sealed under an AES key that
+IndexedDB holds unextractable, and memory is IndexedDB, named
+`indexeddb` in an entry. Classes load from the page's own origin through
+the `origin` body, `{ body: 'origin', at: '/house/index.js' }`, and a
+path off the origin is refused. The recipe is the object you pass: its
+faculties, made by a function, and any custom body.
+
+Any script on the origin can use the ground's keys, so the ground is
+whoever serves the origin's script. Give it an origin of its own, serve
+nothing a stranger wrote there, and set a strict content security
+policy. The page and the house's module must share one copy of
+`nervur/being`, since a house knows a class by a mark that module gives.
+A bundler's shared chunk or an import map gives the one copy.
+
+A service worker opens the ground the same way, on a push, where no tab
+runs it. It may not `import()`, so hand it the modules it imported
+itself: `platform: { load: (href) => modules[new URL(href).pathname] }`.
+
+### In an app
+
+`AppGround.open({ shell })` from `nervur/app` is a BrowserGround in the
+app's web view, on two interfaces the shell fills in native code:
+
+- `NativeSecrets`: `get(name)` and `set(name, value)`, text kept by the
+  iOS Keychain or the Android Keystore on this device alone.
+- `NativeStore`: `get(key)`, `keys(prefix)`, and `swap(writes, expect)`,
+  which lands every write only where each key in `expect` still holds
+  what it names, and answers whether it landed.
+
+The library holds the rest. Each house's seed goes into the secret
+store, and each memory into the native store, which the system never
+evicts as it may a web view's storage. A push token reaches the ground
+through a faculty your recipe makes.
+
 ## What the house guarantees
 
 1. **Every need is covered, or she is absent.** An absent being answers

package/README.md

@@ -107,6 +107,39 @@ the house's seed, its ledger and its record in `state/`, readable by
 you alone. Keep that folder secret: a house opens on no other seed.
 `npx nervur help` lists everything the ground offers.
 
+## A ground in a page
+
+The same house runs in a browser. Bundle the house's module and serve it
+on your origin, beside a page that opens the ground.
+
+```ts
+// page.ts
+import { BrowserGround } from 'nervur/browser';
+
+// Every tab of this origin joins one ground, and the tab holding its lock runs it.
+const ground = await BrowserGround.open();
+
+// The house's code is a module on this origin, and its rows live in IndexedDB.
+await ground.hand({
+  faculty: 'houses',
+  method: 'add',
+  args: { name: 'main', memory: { body: 'indexeddb' }, classes: { body: 'origin', at: '/house/index.js' } },
+});
+
+console.log(await ground.hand({ house: 'main', method: 'hello', args: { name: 'Ada' } }));
+```
+
+Every tab of the origin reaches the one ground, and when the tab running
+it closes, the next opens it from the same storage. Its seeds are sealed
+under a key the browser never hands out. Any script on the origin can
+use them, so give the ground an origin of its own, with a strict content
+security policy. The page and the house's module must share one copy of
+`nervur/being`, as a bundler's shared chunk gives.
+
+An app on a phone opens the same ground with `AppGround` from
+`nervur/app`, on the Keychain or the Keystore and a store the system
+keeps. `AUTHORING.md` shows both.
+
 ## Entries
 
 | Entry | For |
@@ -114,6 +147,9 @@ you alone. Keep that folder secret: a house opens on no other seed.
 | `nervur/being` | writing a being: `Being`, `s`, `need`, `Args`, `Result` |
 | `nervur` | any engine: `Ground`, `House` and the bodies they take |
 | `nervur/node` | a ground on Node: `NodeGround`, the `nervur` command, and its bodies |
+| `nervur/browser` | a ground in a page or its service worker: `BrowserGround` and its bodies |
+| `nervur/app` | a ground in a phone's app: `AppGround`, and the two interfaces its shell fills |
+| `nervur/serve` | a faculty's program in JavaScript: `serve` |
 | `nervur/bench` | tests: `Bench`, `BenchGround`, `FakeNetwork` and the fakes of every body |
 
 ## License

package/dist/browser/browser-ground.js

@@ -40,6 +40,8 @@ export class BrowserGround {
     // Asks sent to another page's ground, by id, with the page they went to.
     #pending = new Map();
     #ground;
+    // The custody and the memories its boot opened, each closed when it closes.
+    #opened = [];
     #persisted = false;
     #leader;
     #waiting = [];
@@ -178,8 +180,13 @@ export class BrowserGround {
         const name = this.#name;
         const platform = this.#platform;
         const recipe = this.#options.recipe ?? {};
-        const custody = await platform.custody(`${name}-custody`);
-        const memory = await platform.memory(`${name}-ground`);
+        // Every store it opens is kept, so its close lets each go before the lock passes.
+        const kept = (opened) => {
+            this.#opened.push(opened);
+            return opened;
+        };
+        const custody = kept(await platform.custody(`${name}-custody`));
+        const memory = kept(await platform.memory(`${name}-ground`));
         this.#persisted = await platform.persist().catch(() => false);
         // It only dials, so it writes no address into an invitation.
         const web = new WebCarry({ allowPrivate: this.#options.allowPrivate === true });
@@ -188,7 +195,7 @@ export class BrowserGround {
         for (const [faculty, made] of Object.entries(recipe.faculties?.() ?? {}))
             faculties[faculty] = await made;
         const bodies = {
-            memory: joined({ indexeddb: ({ house }) => platform.memory(`${name}-house-${house}`) }, recipe.bodies?.memory),
+            memory: joined({ indexeddb: async ({ house }) => kept(await platform.memory(`${name}-house-${house}`)) }, recipe.bodies?.memory),
             classes: joined({
                 origin: ({ args }) => {
                     if (typeof args.at !== 'string')
@@ -209,6 +216,9 @@ export class BrowserGround {
         const ground = this.#ground;
         this.#ground = undefined;
         await ground?.close();
+        // Its IndexedDB connections go with it, so the next ground in this page opens on none of its.
+        for (const opened of this.#opened.splice(0))
+            opened.close?.();
         this.#release?.();
         this.#orphan(() => true);
         for (const resolve of this.#waiting)

package/dist/browser/locked-custody.d.ts

@@ -19,6 +19,8 @@ export declare class LockedCustody implements Custody {
     constructor(shelf: Shelf, subtle?: SubtleCrypto);
     /** The custody of the origin, on a shelf in IndexedDB named `name`. */
     static open(name?: string, factory?: IDBFactory): Promise<LockedCustody>;
+    /** Its shelf let go, where the shelf holds a connection. */
+    close(): void;
     keys({ house }: {
         house: string;
     }): Promise<Keys>;

package/dist/browser/locked-custody.js

@@ -54,6 +54,10 @@ export class LockedCustody {
     static async open(name = 'nervur-custody', factory = indexedDB) {
         return new LockedCustody(await IndexedDbShelf.open(name, factory));
     }
+    /** Its shelf let go, where the shelf holds a connection. */
+    close() {
+        this.#shelf.close?.();
+    }
     keys({ house }) {
         if (!NAME.test(house))
             return Promise.reject(new TypeError(`no house is named ${house}`));

package/dist/house/rows.js

@@ -12,6 +12,8 @@ export class Rows {
     #placeNames = new Map();
     /** The last write holding each row, which the next one to hold it waits for. */
     #holds = new Map();
+    // How many times each row's cache has moved, so a read overtaken by a write never lands behind it.
+    #moves = new Map();
     #landed;
     constructor(memory, crypto, tools, names, key) {
         this.#memory = memory;
@@ -33,22 +35,36 @@ export class Rows {
         }
         return place;
     }
+    // A row's cache moved, by a write that landed or one refused: a read in flight across it is behind.
+    #moved(place) {
+        this.#moves.set(place, (this.#moves.get(place) ?? 0) + 1);
+    }
+    #forget(place) {
+        this.#moved(place);
+        this.#held.delete(place);
+    }
     async #read(place) {
-        const cached = this.#held.get(place);
-        if (cached !== undefined)
-            return cached;
-        const { entries, version } = await this.#memory.read({ place });
-        const sealed = entries[ENTRY];
-        let held = { row: null, text: null, version };
-        if (sealed !== undefined) {
-            const opened = await this.#crypto.open(this.#key, sealed.subarray(0, 12), sealed.subarray(12), this.#tools.utf8(place));
-            const text = opened === null ? null : this.#tools.text(opened);
-            if (text === null)
-                throw new Error('a row does not open under these keys');
-            held = { row: JSON.parse(text), text, version };
+        for (;;) {
+            const cached = this.#held.get(place);
+            if (cached !== undefined)
+                return cached;
+            const move = this.#moves.get(place) ?? 0;
+            const { entries, version } = await this.#memory.read({ place });
+            const sealed = entries[ENTRY];
+            let held = { row: null, text: null, version };
+            if (sealed !== undefined) {
+                const opened = await this.#crypto.open(this.#key, sealed.subarray(0, 12), sealed.subarray(12), this.#tools.utf8(place));
+                const text = opened === null ? null : this.#tools.text(opened);
+                if (text === null)
+                    throw new Error('a row does not open under these keys');
+                held = { row: JSON.parse(text), text, version };
+            }
+            // A write that moved the row while this read was in flight wins, and this read looks again.
+            if ((this.#moves.get(place) ?? 0) !== move)
+                continue;
+            this.#held.set(place, held);
+            return held;
         }
-        this.#held.set(place, held);
-        return held;
     }
     /** A row as it stands, or `null`. */
     async get(place) {
@@ -152,10 +168,11 @@ export class Rows {
             }
             if (versions === null) {
                 for (const place of Object.keys(expect))
-                    this.#held.delete(place);
+                    this.#forget(place);
                 return false;
             }
             for (const [place, held] of landed) {
+                this.#moved(place);
                 this.#held.set(place, { ...held, version: versions[place] ?? null });
                 this.#landed?.(place, held.row);
             }

package/dist/node/cli.js

@@ -20,6 +20,7 @@ import { connect } from 'node:net';
 import { basename, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
+import { handAt } from './hand.js';
 import { NodeGround } from './node-ground.js';
 import { notifyReady } from './notify.js';
 const USAGE = 'nervur up <folder> | service <folder> | [--at <socket>] help | ask <house> [--id <being>] [<method> [args]] | <faculty> [<method> [args]]';
@@ -127,7 +128,7 @@ const service = (folder) => {
 };
 const words = process.argv.slice(2);
 // The hand: named, or the one a ground in this folder serves.
-let at = process.env.NERVUR_HAND ?? (existsSync(join('state', 'hand')) ? join('state', 'hand') : undefined);
+let at = process.env.NERVUR_HAND ?? (existsSync(process.platform === 'win32' ? 'state' : join('state', 'hand')) ? handAt('state') : undefined);
 if (words[0] === '--at') {
     at = words[1] ?? fail('--at names no socket');
     words.splice(0, 2);

package/dist/node/file-memory.js

@@ -5,6 +5,7 @@
 import { mkdir, open, readFile, rename } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { syncFolder } from './sync-folder.js';
 const hex = (bytes) => Buffer.from(bytes).toString('hex');
 const unhex = (text) => new Uint8Array(Buffer.from(text, 'hex'));
 export class FileMemory {
@@ -80,12 +81,6 @@ export class FileMemory {
             await file.close();
         }
         await rename(temporary, this.#path);
-        const directory = await open(folder, 'r');
-        try {
-            await directory.sync();
-        }
-        finally {
-            await directory.close();
-        }
+        await syncFolder(folder);
     }
 }

package/dist/node/hand.d.ts

@@ -21,9 +21,16 @@ export interface HandRequest {
     /** The answer the owner holds, which makes a `readOnly` ask a watch. */
     readonly after?: Answer;
 }
+/**
+ * Where a ground's hand stands for its state folder: a socket inside it,
+ * or on Windows a named pipe, which has no place in a folder, named for
+ * the folder's path.
+ */
+export declare const handAt: (state: string, platform?: NodeJS.Platform) => string;
 /**
  * Serves `ask` at `path`: a house's own hand, or a ground's, which also
  * reads `house` and changes its record. A socket left there by a process
- * that is gone is replaced.
+ * that is gone is replaced. A named pipe on Windows is open to its user
+ * alone, as the operating system makes it, and leaves nothing behind.
  */
 export declare const serveHand: (ask: (request: HandRequest) => Promise<unknown>, path: string) => Promise<Hand>;

package/dist/node/hand.js

@@ -1,8 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
-// The hand on a local socket: one JSON object a line in, one answer a
-// line out, in order. The socket is readable by the ground's user alone.
+// The hand on a local socket, or on Windows a named pipe: one JSON object
+// a line in, one answer a line out, in order. It is open to the ground's
+// user alone.
+import { createHash } from 'node:crypto';
 import { chmod } from 'node:fs/promises';
 import { createServer } from 'node:net';
+import { join, resolve as absolute } from 'node:path';
 import { createInterface } from 'node:readline';
 import { gone } from './gone.js';
 const object = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -46,16 +49,29 @@ const serve = (ask, socket) => {
 // A local socket's path fits the kernel's address: 103 bytes on macOS and
 // the BSDs, 107 on Linux, with the closing zero beyond.
 const LONGEST = process.platform === 'linux' ? 107 : 103;
+const PIPE = /^\\\\[.?]\\pipe\\/;
+/**
+ * Where a ground's hand stands for its state folder: a socket inside it,
+ * or on Windows a named pipe, which has no place in a folder, named for
+ * the folder's path.
+ */
+export const handAt = (state, platform = process.platform) => platform === 'win32' ? `\\\\.\\pipe\\nervur-${createHash('sha256').update(absolute(state).toLowerCase()).digest('hex').slice(0, 16)}` : join(state, 'hand');
 /**
  * Serves `ask` at `path`: a house's own hand, or a ground's, which also
  * reads `house` and changes its record. A socket left there by a process
- * that is gone is replaced.
+ * that is gone is replaced. A named pipe on Windows is open to its user
+ * alone, as the operating system makes it, and leaves nothing behind.
  */
 export const serveHand = async (ask, path) => {
+    if (PIPE.test(path))
+        return listen(ask, path, false);
     const length = Buffer.byteLength(path);
     if (length > LONGEST)
         throw new Error(`a socket's path is at most ${LONGEST} bytes here, and ${path} is ${length}: serve the hand from a shorter folder`);
     await gone(path);
+    return listen(ask, path, true);
+};
+const listen = async (ask, path, file) => {
     const server = createServer((socket) => serve(ask, socket));
     const sockets = new Set();
     server.on('connection', (socket) => {
@@ -64,6 +80,8 @@ export const serveHand = async (ask, path) => {
     });
     await new Promise((resolve, reject) => {
         server.once('error', reject);
+        if (!file)
+            return void server.listen(path, () => resolve());
         // Closed to everyone from the first moment, then opened to the user.
         const mask = process.umask(0o177);
         try {
@@ -73,13 +91,15 @@ export const serveHand = async (ask, path) => {
             process.umask(mask);
         }
     });
-    await chmod(path, 0o600);
+    if (file)
+        await chmod(path, 0o600);
     return {
         close: async () => {
             for (const socket of sockets)
                 socket.destroy();
             await new Promise((resolve) => server.close(() => resolve()));
-            await gone(path);
+            if (file)
+                await gone(path);
         },
     };
 };

package/dist/node/ledger-memory.js

@@ -9,6 +9,7 @@ import { createHash } from 'node:crypto';
 import { mkdir, open, readFile, rename, truncate } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { syncFolder } from './sync-folder.js';
 const GENESIS = { n: 0, hash: '0'.repeat(64) };
 const hash = (text) => createHash('sha256').update(text).digest('hex');
 const unhex = (text) => new Uint8Array(Buffer.from(text, 'hex'));
@@ -103,7 +104,7 @@ export class LedgerMemory {
         const temporary = `${this.#witness}.${process.pid}.tmp`;
         await synced(temporary, 'w', (handle) => handle.writeFile(JSON.stringify(head)));
         await rename(temporary, this.#witness);
-        await synced(dirname(this.#witness), 'r', async () => undefined);
+        await syncFolder(dirname(this.#witness));
     }
     async read({ place }) {
         const held = (await this.#open()).places.get(place);
@@ -135,7 +136,7 @@ export class LedgerMemory {
         try {
             await synced(this.#path, 'a', (handle) => handle.appendFile(`${raw}\n`));
             if (line.n === 1)
-                await synced(dirname(this.#path), 'r', async () => undefined);
+                await syncFolder(dirname(this.#path));
             if (this.#witness !== undefined)
                 await this.#attest(head);
         }

package/dist/node/node-ground.js

@@ -20,7 +20,7 @@ import { WebCarry } from '../bodies/web-carry.js';
 import { Ground } from '../ground/ground.js';
 import { FolderCustody, KeychainCustody } from './custody.js';
 import { FolderClasses } from './folder-classes.js';
-import { serveHand } from './hand.js';
+import { handAt, serveHand } from './hand.js';
 import { serveHttp } from './http.js';
 import { LedgerMemory } from './ledger-memory.js';
 import { takeLock } from './lock.js';
@@ -127,7 +127,7 @@ export class NodeGround {
             // 6. Hook: HTTP chains the web carry and every faculty's handler, and the hand takes its socket.
             if (httpPort !== undefined)
                 http = await serveHttp({ port: httpPort, host: bind }, [web, ...ground.handlers]);
-            const hand = env.NERVUR_HAND ?? join(state, 'hand');
+            const hand = env.NERVUR_HAND ?? handAt(state);
             const served = await serveHand((request) => ground.hand(request), hand);
             return new NodeGround({ ground, hand, tcp, lock, served, http });
         }

package/dist/node/sync-folder.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Makes a file's creation or renaming in `folder` durable. On POSIX the
+ * folder is synced. Windows opens no folder for syncing, and NTFS journals
+ * a creation and a rename itself, so there it does nothing.
+ */
+export declare const syncFolder: (folder: string, platform?: NodeJS.Platform) => Promise<void>;

package/dist/node/sync-folder.js

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: Apache-2.0
+import { open } from 'node:fs/promises';
+/**
+ * Makes a file's creation or renaming in `folder` durable. On POSIX the
+ * folder is synced. Windows opens no folder for syncing, and NTFS journals
+ * a creation and a rename itself, so there it does nothing.
+ */
+export const syncFolder = async (folder, platform = process.platform) => {
+    if (platform === 'win32')
+        return;
+    const handle = await open(folder, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nervur",
-  "version": "0.22.2-3",
+  "version": "0.22.2-5",
   "description": "Nervur's kit of Quo: write beings and faculties, and open the house that holds them on any ground.",
   "keywords": [
     "quo",
@@ -69,7 +69,7 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "prepack": "npm run build",
     "check": "tsc -p tsconfig.json && tsc -p tsconfig.pure.json && node test.mjs \"test/**/*.test.ts\"",
-    "deep": "tsc -p tsconfig.deep.json && NERVUR_TEST_CAP=900000 node test.mjs \"deep/**/*.test.ts\"",
+    "deep": "tsc -p deep && NERVUR_TEST_CAP=900000 node test.mjs \"deep/**/*.test.ts\"",
     "prepublishOnly": "test \"$NERVUR_GATED\" = 1 || { echo 'a publish is /release, from the root, on the human'\"'\"'s word' >&2; exit 1; }"
   },
   "engines": {