@factoidal/core 0.35.1 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.37.0 (2026-11-14)
+
+- Foafnaut: Web Platform Tests on the Linux engine, full measured runs: 85.06% on the morning of 2026-11-14, 91.76% (2,082,990 of 2,270,129 subtests) at commit 53326e401; 66 crashed tests and 4,876 harness timeouts in that run. Test262 on BubblePopJS: 42,515 of 53,833 (79.0%).
+- Foafnaut: CSS Grid placement, track sizing, alignment and absolutely positioned grid items as pure modules with bound theorems; a page's own web fonts are its fonts when the host holds none, which most grid tests need (css-grid 9,115 to 11,121 subtests).
+- Foafnaut: CSS animations and transitions on the effect stack: replaced animations, `commitStyles()`, animated values in the layout of pages with `::before`/`::after`, one cascade for a layout and an element's matches made once a measure.
+- Foafnaut: the cascade works out structural pseudo-classes and `:has()` once per document: the first layout of a page with 2,000 rules and 3,000 elements went from 845 ms to about 340 ms on the macOS engine.
+- Foafnaut: real pages start sooner: scripts, images and the icon are read while the style sheets are, and the engine's first call is made while the page is fetched (Hacker News load 3.4 s to 1.9 s, measured on an M1).
+- BubblePopJS: the RegExp `Symbol.match`, `replace`, `search`, `split` and `matchAll` protocol, ArraySpeciesCreate and TypedArraySpeciesCreate, typed array `[[DefineOwnProperty]]`, regular expression literals checked at parse time.
+- Foafnaut: reflected IDL attributes such as `el.title` read and write through one host call (5.4 to 3.9 µs a read).
+- Foafnaut: client storage has a budget: 32 MiB per storage key over IndexedDB, the file system and the Cache API, with theorems for the bound; storage buckets, Cookie Store `maxAge` and change events.
+- Foafnaut: networking fixes for workers and service workers (a worker script fetch asked while frames are answered is now answered), the WebSocket close code, ORB for classic scripts, and network theorems for credentials across redirects.
+- Foafnaut: `getComputedStyle(el).paddingLeft` and `.borderRightWidth` answer their values again: two internal operation numbers had collided with the computed-style range; theorems now keep the ranges apart.
+- Build: the engine build refuses a Lean module that imports parts of `Std` the WebAssembly engine does not link.
+
+## 0.36.0 (2026-11-12)
+
+- Foafnaut: dedicated Web Workers on BubblePopJS. `new Worker`, `postMessage` both ways through a structured clone, transfer of ArrayBuffers, `importScripts`; WPT `.any.worker.html` and `.worker.html` variants run (11,749/11,866 subtests on 78 pages). A worker start takes about 1.2 ms and a `postMessage` round trip about 0.2 ms. Each worker seeds `Math.random` from its own entropy.
+- Foafnaut: `XMLHttpRequest` and `fetch()` for page scripts, on both script engines, in the desktop window and on the Hub. The origin policy, CORS with a preflight on each hop, redirects, forbidden fields and methods, and mixed content are decided by the built-in engine; no cookies or credentials are sent. `data:` URLs and `Blob`, `File` and `FormData` bodies; synchronous XHR. WPT xhr/: 1156/1449 subtests on BubblePopJS (was 816/1407), 1022/1433 on QuickJS-NG (was 681/1399). Security: a name is resolved before anything is sent and refused if any address is special-purpose, else one address is pinned for the transfer (no DNS rebinding); a method-override field naming a forbidden method is dropped; `Authorization` is dropped on a cross-origin redirect; a cross-origin redirect to a URL with credentials is refused; on the Hub, a final URL outside the policy is not read.
+- Foafnaut: Shadow DOM and sandboxed iframes. Shadow trees and slots, declarative shadow roots, events through shadow trees (retargeting, `composedPath`), `slotchange`, `:host` and `::slotted`; a page with no shadow host pays nothing for them. `iframe` `sandbox` flags and opaque origins, and `postMessage` between frames. Theorems include `sandboxed_no_access`, `frameFlags_narrows` (flags only narrow), `nested_sandboxed_opaque` and `exchange_data` (only posted message records cross). WPT shadow-dom: 440/690 subtests on BubblePopJS, 547/695 on QuickJS-NG (both were 18/694).
+- Foafnaut: the built-in engine keeps its state as one value passed through each call, not in hidden cells. Starting fib(24) on QuickJS-NG in the Wasm engine went from about 1330 ms to 800 ms; frame times are unchanged.
+- Foafnaut: five bitwise SIMD instructions of the built-in Wasm engine take 4 to 6% less time, with a proof that the fast path gives the same results.
+- Foafnaut: `foafnaut:about` is written by the built-in engine, from facts compiled into it (version, commit, build time, hygiene counts) and the list of specifications it implements. Facts the desktop program reports are in a section of their own, and a line says when the engine and app builds differ. `foafnaut --version` prints the engine's line first. Menu item About Foafnaut (macOS).
+- Foafnaut (macOS): find in page. Cmd-F, Cmd-G and Shift-Cmd-G; matches and marks are made by the built-in engine. The Hub says find is in the desktop app only.
+- Foafnaut (macOS): Open File (Cmd-O), Save Page As and Close Window (Shift-Cmd-W) in the File menu.
+- Foafnaut: a 600 ms splash drawn by the built-in engine at start; `--no-splash` skips it.
+- `foafnaut --dev-help`: developer options, in-browser tools, the developer proxy (`HTTP_PROXY`, `HTTPS_PROXY`, `DENO_CERT`; `tools/devproxy`), and what is not there yet (CDP, WebDriver BiDi, MCP).
+- LWS: no lockout of the root ACL. With authorization on, `lws-serve` refuses with 409 any request that would leave `/.acl` with no agent that has `acl:Control` on the storage root (a PUT or PATCH that drops the last Control agent, a DELETE of `/.acl`, a move, an access grant); the refused request changes nothing. A write that keeps a Control agent, or swaps the owner for another, is accepted as before; `--insecure-no-auth` is not changed. The decision is in Lean (`L4Factoidal/LWS/NoLockout.lean`, `NoLockoutTheorems.lean`; theorems `step_keeps_root_control`, `lockout_iff`, `hasRootControl_iff`, `guard_refused_unchanged`). New command `factoidal lws-acl-reset DIR FILE --operator`: the offline operator recovery of the root ACL of a stopped storage, under the storage directory lock, through the storage library (new op `lwsAclReset`, theorems `reset_has_control`, `reset_other_paths`, `reset_refuses`). Test: `test/lws-no-lockout.test.mjs`.
+
+- LWS: `lws-serve DIR --authz AS --root-acl FILE` (and `--owner`) on an EXISTING storage with no root ACL, for example one made with `--insecure-no-auth`, installs FILE as `/.acl` at start, before any request is answered. Before, the root ACL was written only into a new storage, and such a storage refused every agent (403), its owner too, so the only way out was to serve it with no authorization for a moment. An existing `/.acl` is never replaced; a line on standard error says which happened. No other resource changes, and with `--insecure-no-auth` nothing is installed. The decision is in Lean (`L4Factoidal/LWS/RootAclInstall.lean`; theorems `install_only_when_absent`, `install_keeps_existing`, `install_has_root_acl`, `install_other_paths`, `allowed_without_acl`). `openLwsStorage` and `openInPageLwsStorage` do the same with a snapshot. Test: `test/lws-root-acl-install.test.mjs`.
+
 ## 0.35.1 (2026-11-11)
 
 - Foafnaut (macOS): a heavy page no longer freezes the app. The host keeps one frame of GPU work in flight for heavy frames (three for light ones); after three frames over 250 ms it slows the page's animation and shows "SLOWED: HEAVY PAGE". Quitting or closing the window stops GPU work, so the app quits within seconds (before, up to 209 s on the Spinal Tap page at 2x). `--gpu-frames-in-flight N` sets the limit.

package/bin/factoidal.mjs

@@ -98,7 +98,7 @@ const REVIEW_WARNING = 'EXPERIMENTAL UNDER-REVIEWED CODE - USE WITH CARE - DO NO
 
 /** The commands that serve, speak a protocol, or handle keys and tokens. */
 const WARNED_COMMANDS = new Set(['serve', 'lws-serve', 'solid-serve', 'solid-client', 'lws-client',
-  'authz-serve', 'authz-keys', 'xmpp-serve', 'webdav-serve', 'webdav-user', 'xmpp-http-proxy', 'lws-keygen'])
+  'authz-serve', 'authz-keys', 'xmpp-serve', 'webdav-serve', 'webdav-user', 'xmpp-http-proxy', 'lws-keygen', 'lws-acl-reset'])
 
 const USAGE = `factoidal - the Factoidal persisted store, from Node or Deno
 
@@ -123,6 +123,9 @@ commands:
   lws-keygen                  print a new storage key for encryption at rest
                               (FACTOIDAL_LWS_KEY of lws-serve, solid-serve and
                               webdav-serve local mounts)
+  lws-acl-reset DIR FILE --operator
+                              offline operator recovery: replace the root ACL
+                              (/.acl) of a stopped LWS storage with FILE
   solid-client OP URL         run one Solid client operation
   lws-client OP URL           run one Linked Web Storage client operation
   authz-serve DIR             serve an OAuth 2.0 authorization server for LWS
@@ -667,7 +670,12 @@ is required):
                         https://github.com/danbri/factoidal/issues/1124
   --owner WEBID         the storage owner: a new storage gets a root ACL
                         that gives this agent Read, Write and Control
-  --root-acl FILE       a Turtle root ACL for a new storage instead
+  --root-acl FILE       a Turtle root ACL for a new storage instead.
+                        An EXISTING storage with no root ACL (/.acl), for
+                        example one made with --insecure-no-auth, gets this
+                        root ACL (or the --owner one) at start, before the
+                        first request is answered; an existing /.acl is
+                        kept and never replaced (a notice says which)
   --audience IRI        the aud value tokens must carry (default: the
                         storage IRI, BASE.well-known/lws-storage, which
                         every lws#storage link names)
@@ -1125,6 +1133,37 @@ The random bytes come from the host (WebCrypto getRandomValues); the engine
 makes the key text and the key id (formal/lean4/L4Factoidal/LWS/DirLock.lean,
 newStorageKey).`,
 
+  'lws-acl-reset': `factoidal lws-acl-reset - offline operator recovery of the root ACL of an LWS storage
+
+usage: factoidal lws-acl-reset DIR FILE --operator [--base IRI] [--storage files|snapshot]
+
+Replaces the root ACL resource (/.acl) of the LWS storage in DIR with the
+Turtle in FILE. It is the last resort when no agent can change /.acl through
+the protocol any more (lws-serve refuses a request that would leave no agent
+with acl:Control on the storage root, with 409; a storage can still lose its
+controller, for example when the only control key is lost). First try the
+recovery agent: an agent with acl:Control on the root can PUT /.acl.
+
+--operator is required: it confirms that you operate this storage and that
+the server is stopped. The command takes the storage directory lock
+(DIR/lws.lock) and refuses while a server holds it; it opens only an existing
+storage, through the same storage library as lws-serve (the engine reads and
+writes every file), answers no request, and changes no resource but /.acl.
+The write goes through the storage journal, and the command prints a notice
+on standard error.
+
+FILE must give some agent acl:Control on the storage root: an Authorization
+with acl:accessTo (or acl:default) the root container, acl:mode acl:Control,
+and an acl:agent, an acl:agentGroup with members, or an acl:agentClass.
+Otherwise the command refuses and nothing is written. Relative IRIs (<./>)
+are read against the root ACL's own IRI; when FILE names the root with an
+absolute IRI, give --base with the storage's base IRI (the one lws-serve
+serves, for example http://127.0.0.1:3000/).
+
+The decision is in Lean (formal/lean4/L4Factoidal/LWS/NoLockout.lean,
+reset; theorems reset_has_control, reset_other_paths, reset_refuses) and the
+lock in L4Factoidal/LWS/DirLock.lean.`,
+
   'webdav-user': `factoidal webdav-user - add or replace a user in a webdav-serve users file
 
 usage: factoidal webdav-user FILE NAME [--iterations N]
@@ -1317,7 +1356,8 @@ const VALUE_OPTIONS = {
   'webdav-user': new Set(['iterations']),
   'xmpp-http-proxy': new Set(['port', 'host', 'xmpp', 'xmpp-password-file', 'target', 'xmpp-host', 'xmpp-port',
     'xmpp-resource', 'xmpp-ca', 'timeout']),
-  'lws-keygen': new Set([])
+  'lws-keygen': new Set([]),
+  'lws-acl-reset': new Set(['base', 'storage'])
 }
 
 // ------------------------------------------------------------- commands
@@ -2529,6 +2569,68 @@ async function commandAuthzServe (positional, options) {
   return untilInterrupted(running, quiet)
 }
 
+// lws-acl-reset: the offline operator recovery of the root ACL of an LWS
+// storage. The storage library opens the storage under the directory lock
+// (`operator: true`: an existing storage only, no request answered), and the
+// engine decides the reset (L4Factoidal/LWS/NoLockout.lean, `reset`). This
+// host reads FILE and prints what the engine says.
+async function commandLwsAclReset (positional, options) {
+  if (positional.length !== 2) throw new UsageError('lws-acl-reset needs DIR and FILE')
+  if (options.operator !== true) {
+    throw new UsageError('lws-acl-reset replaces the root ACL of a storage offline; give --operator ' +
+      'to confirm that you operate this storage and that its server is stopped')
+  }
+  const [dir, file] = positional
+  const { statSync } = await import('node:fs')
+  let isDir = false
+  try { isDir = statSync(dir).isDirectory() } catch (_error) { isDir = false }
+  if (!isDir) {
+    err(`factoidal lws-acl-reset: ${dir} is not a directory; nothing was written`)
+    return EXIT_FAILURE
+  }
+  const acl = new TextDecoder('utf-8', { fatal: true }).decode(readWhole(file))
+  const { openLwsStorage, LwsHostError } = await import('../lws/server.mjs')
+  let storage
+  try {
+    storage = await openLwsStorage({
+      dir,
+      operator: true,
+      lockCommand: 'lws-acl-reset',
+      ...(typeof options.base === 'string' ? { baseIri: options.base } : {}),
+      ...(typeof options.storage === 'string' ? { storage: options.storage } : {})
+    })
+  } catch (error) {
+    if (error instanceof LwsHostError && error.unknownOp) return notWired('lws-acl-reset', error.message)
+    if (error !== null && typeof error === 'object' && (error.envelope !== undefined || error.stateFile === true)) {
+      err(`factoidal lws-acl-reset: ${error.envelope !== undefined ? error.envelope.error : error.message}`)
+      return EXIT_FAILURE
+    }
+    throw error
+  }
+  try {
+    for (const n of storage.notices || []) err(`lws-acl-reset: ${n}`)
+    let notice
+    try {
+      notice = storage.resetRootAcl(acl)
+    } catch (error) {
+      const message = error && error.message ? String(error.message) : String(error)
+      if (message.indexOf('unknown op') >= 0) return notWired('lws-acl-reset', message)
+      if (error !== null && typeof error === 'object' && error.envelope !== undefined && error.envelope !== null) {
+        err(`factoidal ${error.envelope.error}`)
+        if (typeof options.base !== 'string') {
+          err('lws-acl-reset: if FILE names the storage root with an absolute IRI, give --base with the storage\'s base IRI')
+        }
+        return EXIT_FAILURE
+      }
+      throw error
+    }
+    err(notice)
+    return EXIT_OK
+  } finally {
+    storage.close()
+  }
+}
+
 // lws-keygen (https://github.com/danbri/factoidal/issues/1135): 32 random
 // bytes from the host's random source go to the engine (`lwsStorageKeyNew`),
 // which gives the key text and its key id. The key goes to standard output
@@ -3315,7 +3417,8 @@ const COMMANDS = {
   'webdav-serve': commandWebdavServe,
   'webdav-user': commandWebdavUser,
   'xmpp-http-proxy': commandXmppHttpProxy,
-  'lws-keygen': commandLwsKeygen
+  'lws-keygen': commandLwsKeygen,
+  'lws-acl-reset': commandLwsAclReset
 }
 
 // ----------------------------------------------------------------- main

package/bin/foafnaut.mjs

@@ -25,6 +25,7 @@ const HELP = `foafnaut [--latest|--bleeding-edge] [PAGE | --url URL | --html FIL
   --which           print the app that would run
   --version         print the commit and build time of that app (the app answers)
   --help            this text
+  --dev-help        options and tools for developing and testing the browser
 
 App options, passed to the app as they are:
   --perf-summary    print frame and input latency figures when the window closes
@@ -45,6 +46,53 @@ closes; --detach returns at once.
 
 EXPERIMENTAL UNDER-REVIEWED CODE - USE WITH CARE - DO NOT CREATE PUBLIC SERVICES USING THIS WITHOUT CAREFUL INDEPENDENT EXPERT REVIEW.
 `;
+const DEV_HELP = `foafnaut --dev-help: tools for developing and testing the browser
+
+More app options (passed to the app as they are)
+  --offscreen            no window: draw into a GPU texture (for tests and captures)
+  --shot FILE            write a PNG of the page (with --offscreen)
+  --print-pdf FILE       print the page to a PDF file
+  --no-scripts           run no page scripts
+  --strict               refuse pages with features the browser skips (the default)
+  --no-state             no saved state: no history, bookmarks or session
+  --state-dir DIR        keep the saved state in DIR
+  --restore-session      reopen the tabs of the last run
+  --no-splash            no splash at start (off already offscreen and in checks)
+  --single-frame         draw the page as one layer (no partial frames)
+  --gpu-frames-in-flight N  GPU frames queued at most (default: 1 for heavy work, 3 for light)
+  --trace-input          log every input event and edge drag to stderr
+  --check-engine         run the engine on the main thread and check its render plan (CPU)
+  --quickjs-wasm FILE    run page scripts on QuickJS-NG in BubblePopWASM from FILE
+                         (BubblePopJS, the built-in JavaScript engine, is the default)
+  --*-sweep              scripted checks used by the tests (scroll, resize, find, ...);
+                         see labs/demos/foafnaut/sweeps.sh
+
+Inside the browser
+  Option-Command-J       the console: page script output, refusals, skipped features
+  about:foafnaut         version, commit, build time and the specifications implemented,
+                         written by the engine; facts from the desktop program are marked
+  foafnaut:console, foafnaut:sparql, foafnaut:wasm   developer pages
+  Command-F              find in page
+
+Through a proxy (developer proxy: tools/devproxy/README.md, in the source repository)
+  The app uses HTTP_PROXY, HTTPS_PROXY and DENO_CERT from its environment, so it can run
+  through a local proxy with no change. tools/devproxy/devproxy.mjs records real pages once
+  to WARC and replays them offline, and can simplify pages as it serves them:
+    full             no change
+    no-scripts       scripts and on* attributes removed
+    text-css-links   structure, text, links and stylesheets kept; scripts, frames, media,
+                     images, canvas and svg removed
+  Run it with tools/devproxy/foafnaut-through-proxy.sh (--record NAME, --replay NAME, or
+  devproxy.mjs --passthrough --default-service LEVEL). It listens on 127.0.0.1 only, with a
+  private CA for this process only. A test tool, not a sanitiser and not a security
+  boundary. Page scripts' XMLHttpRequest and fetch() may not go through the proxy yet.
+
+Not yet: a debugging protocol (Chrome DevTools Protocol, WebDriver BiDi), an MCP server,
+breakpoints, console input. Plan: https://github.com/danbri/factoidal-core/issues/372
+
+Logs: ~/Library/Logs/foafnaut/trace.jsonl. Source and issues:
+https://github.com/danbri/factoidal-core (labs/demos/foafnaut/).
+`;
 const RELEASES = 'https://api.github.com/repos/danbri/factoidal-builds/releases?per_page=60';
 const APP = 'foafnaut.app';
 const home = () => process.env.FOAFNAUT_HOME || join(homedir(), '.foafnaut');
@@ -139,6 +187,7 @@ export async function main(argv, channel = 'current') {
   for (let i = 0; i < options.length; i++) {
     const arg = options[i];
     if (arg === '--help' || arg === '-h') { process.stdout.write(HELP); return; }
+    if (arg === '--dev-help') { process.stdout.write(DEV_HELP); return; }
     else if (arg === '--latest') channel = 'latest';
     else if (arg === '--bleeding-edge') channel = 'bleeding-edge';
     else if (arg === '--which') which = true;

package/l4-assets/l4factoidal.js

@@ -37,7 +37,7 @@
 // bytes change.
 
 // Stamped by formal/lean4/Wasm/build-wasm.sh step 9 -- do not hand-edit.
-const WASM_VERSION = "2e241365bd79";
+const WASM_VERSION = "f8b5d5ddacbb";
 
 import createModule from './l4factoidal.mjs';
 

package/l4-assets/version.json

@@ -2,17 +2,17 @@
   "engine": "lean4",
   "note": "The Lean 4 (L4Factoidal) engine build provenance and claims: the only engine of @factoidal/core since 0.9.0 (issue 713). This committed file is a placeholder. tools/fetch-builds.sh --set web (through tools/stamp-l4-version.mjs) writes the provenance members from the danbri/factoidal-builds release that built the wasm; formal/lean4/Wasm/build-wasm.sh step 9 writes them for a local build. Do not commit a stamped copy.",
   "stamped": true,
-  "release": "danbri/factoidal-builds build-6f57afba14e0-web",
-  "releaseRun": "https://github.com/danbri/factoidal-builds/actions/runs/42968513371",
-  "gitSha": "6f57afba14e04ed648358e4693790edff69a6cd3",
-  "builtAt": "2026-11-11T07:07:29Z",
+  "release": "danbri/factoidal-builds build-ff075ad5af99-web",
+  "releaseRun": "https://github.com/danbri/factoidal-builds/actions/runs/43633972604",
+  "gitSha": "ff075ad5af998de7918e3ffe5846559fd6d5e6b2",
+  "builtAt": "2026-11-14T22:33:16Z",
   "leanToolchain": "leanprover/lean4:v4.33.1",
   "emscripten": "6.0.8",
   "abiVersion": "1",
   "engineVersion": "l4factoidal-wasm 0.2.0 (dispatch: RDF parse/serialize, SPARQL query+update, RDFS/OWL-RL closures, RDFC-1.0, CL/IKL)",
   "version": "l4factoidal-wasm 0.2.0 (dispatch: RDF parse/serialize, SPARQL query+update, RDFS/OWL-RL closures, RDFC-1.0, CL/IKL)",
-  "wasmSha256": "2e241365bd7906474320610a65af99641474534fa0fe0e744ed3d9edeef4ee41",
-  "wasmBytes": 32703824,
+  "wasmSha256": "f8b5d5ddacbbc195f75a5f32f9ba5027ce559f029c091fe3d16016953e1471d2",
+  "wasmBytes": 32774942,
   "claims": {
     "source": "formal/lean4 (L4Factoidal): no sorry, no user axioms, no native_decide; W3C behaviour pinned by build-time #guard",
     "suitesAtBuildSha": "see docs/test-results and formal/lean4/PORT_NOTES.md at gitSha"

package/lib/version.mjs

@@ -2,4 +2,4 @@
 // needs import attributes, which not every runtime this package targets
 // reads). test/dts-drift.test.js checks that it equals package.json's
 // `version`.
-export const version = '0.35.1';
+export const version = '0.37.0';

package/lws/README.md

@@ -91,6 +91,31 @@ const running = await listen({
   the keys inline instead.
 * `insecureNoAuth: true` serves every request with no authorization. It is
   for development only, and must be asked for.
+* A root ACL (`rootAcl`, or the owner's from `owner`) is written into a
+  NEW storage. An EXISTING storage with no root ACL resource (`/.acl`), for
+  example one made with `insecureNoAuth`, gets it at open, before any
+  request is answered; an existing `/.acl` is kept and never replaced. The
+  start notices say which (`lws-serve` prints them on standard error). So a
+  storage made with no authorization moves to authorization with no moment
+  of open access: `lws-serve DIR --authz AS --root-acl FILE`. The decision
+  and its theorems are in `formal/lean4/L4Factoidal/LWS/RootAclInstall.lean`
+  (listed in `formal/lean4/L4Factoidal/LWS/README.md`); with authorization
+  off nothing is installed.
+* No lockout: with authorization on, a request that would leave the root ACL
+  (`/.acl`) with no agent that has `acl:Control` on the storage root (a PUT
+  or PATCH that drops the last one, a DELETE of `/.acl`, a move, an access
+  grant) is refused with 409 and changes nothing. A write that keeps a
+  Control agent, or swaps one for another, is accepted. Theorems
+  `step_keeps_root_control` and `lockout_iff`
+  (`formal/lean4/L4Factoidal/LWS/NoLockout.lean`, `NoLockoutTheorems.lean`).
+* The offline operator recovery: `factoidal lws-acl-reset DIR FILE --operator`
+  replaces only `/.acl` of a stopped storage with FILE, under the storage
+  directory lock, through this storage library (`openLwsStorage({ dir,
+  operator: true })` and `resetRootAcl(acl)`; the op `lwsAclReset`). It
+  refuses while a server holds the lock, in a directory with no storage, and
+  for a FILE that gives no agent `acl:Control` on the root (theorems
+  `reset_has_control`, `reset_other_paths`, `reset_refuses`). Relative IRIs
+  (`<./>`) need no `--base`.
 
 ## Pagination and client links
 

package/lws/inpage.mjs

@@ -85,6 +85,10 @@ export async function openInPageLwsStorage (options = {}) {
     }
     return answer.snapshot
   }
+  // A snapshot with no root ACL resource, reopened with `rootAcl` (or
+  // `owner`), gets that root ACL at open (L4Factoidal/LWS/RootAclInstall.lean);
+  // the engine says `changed`, and the caller is given the new snapshot.
+  if (opened !== null && typeof opened === 'object' && opened.changed === true && onSnapshot !== null) onSnapshot(snapshot())
 
   /** A fetch to this storage: the same arguments as `fetch`, a real Response back. */
   async function podFetch (input, init) {

package/lws/server.mjs

@@ -98,7 +98,7 @@ import { readSnapshot, persistIfChanged, storageKeyText, storageModeText, loadFi
 
 /** The ops this host needs from the engine. */
 export const LWS_OPS = ['lwsOpen', 'lwsStep', 'lwsClose', 'lwsSnapshot', 'lwsFetched', 'lwsDelivered', 'lwsEgress',
-  'lwsLoad', 'lwsPersist', 'lwsRead', 'lwsDirLock', 'lwsAtRestNotice']
+  'lwsLoad', 'lwsPersist', 'lwsRead', 'lwsDirLock', 'lwsAtRestNotice', 'lwsAclReset']
 
 /** How long this host waits for the answer to one delivery request before
  *  it reports "no answer" (status 0) to the engine. */
@@ -349,6 +349,10 @@ export async function openLwsStorage (options = {}) {
   // HTTP: createLwsServer refuses it.
   if (typeof options.principal === 'string') config.principal = options.principal
   if (typeof options.rootAcl === 'string') config.rootAcl = options.rootAcl
+  // The offline operator recovery (`factoidal lws-acl-reset`): a handle that
+  // opens only an existing storage, answers no request, and accepts
+  // `resetRootAcl` (L4Factoidal/LWS/NoLockout.lean, `reset`).
+  if (options.operator === true) config.operator = true
   // Notifications are on unless the caller turns them off; the engine
   // decides everything else about them.
   if (options.notifications === false) config.notifications = false
@@ -472,9 +476,22 @@ export async function openLwsStorage (options = {}) {
     // files: the engine is told none is present.
     filesMode = opened !== null && typeof opened === 'object' &&
       opened.load !== undefined && opened.load !== null
+    // An existing storage with no root ACL resource, opened with
+    // authorization and a root ACL (`rootAcl`, or the owner's), gets that
+    // root ACL here, before any request is answered: the engine decides
+    // (L4Factoidal/LWS/RootAclInstall.lean) and says `changed`; this host
+    // persists it and prints the engine's `rootAclNotice`. Requests that
+    // reach the socket meanwhile wait for this open (createLwsServer).
+    let started = opened
     if (filesMode) {
       if (dir === null) throw new LwsHostError('a storage kept in files needs a storage directory (dir)')
-      loadFiles(engine, handle, opened, dir)
+      started = loadFiles(engine, handle, opened, dir)
+      persistFilesIfChanged(engine, handle, started, dir)
+    } else if (dir !== null) {
+      persistIfChanged(engine, 'lwsSnapshot', handle, started, dir)
+    }
+    if (started !== null && typeof started === 'object' && typeof started.rootAclNotice === 'string') {
+      notices.push(started.rootAclNotice)
     }
     // What a server prints at start, after the experimental code notice:
     // a take-over of a stale lock, and whether the storage on disk is
@@ -655,6 +672,24 @@ export async function openLwsStorage (options = {}) {
       if (typeof envelope.wake === 'number') scheduleFlush(envelope.wake)
       return answer
     },
+    /**
+     * The offline operator recovery: replace the root ACL resource (/.acl)
+     * with `turtle` (the new ACL text). Only on a storage opened with `operator: true`,
+     * which holds the storage directory lock and answers no request. The
+     * engine decides (`lwsAclReset`, L4Factoidal/LWS/NoLockout.lean `reset`):
+     * only /.acl changes, through the journaled store, and a `turtle` that gives
+     * no agent acl:Control on the storage root is refused (thrown with the
+     * engine's message in `envelope`). Returns the engine's notice.
+     */
+    resetRootAcl (turtle) {
+      const told = engine.call('lwsAclReset', [handle, JSON.stringify({ 'acl': turtle })])
+      if (told === null || typeof told !== 'object' || told.ok === false) {
+        throw Object.assign(new Error(told && told.error ? told.error : 'lwsAclReset: no answer'),
+          { envelope: told })
+      }
+      persist(told)
+      return told.notice
+    },
     /** Resolves when no delivery request is in flight. */
     async settled () {
       await new Promise((resolve) => setTimeout(resolve, 0))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factoidal/core",
-  "version": "0.35.1",
+  "version": "0.37.0",
   "description": "EXPERIMENTAL UNDER-REVIEWED CODE: do not run public services on it without careful independent expert review. RDF parsing and writing (Turtle, TriG, N-Triples, N-Quads, RDF/XML, JSON-LD), SPARQL 1.1 and 1.2, RDFS and OWL reasoning, SHACL and ShEx validation, CSVW and RML mapping, RDFC-1.0, and SPARQL, LWS and Solid servers, for Node, Deno and browsers.",
   "keywords": [
     "sparql",
@@ -28,18 +28,17 @@
   "author": "Dan Brickley <danbri@danbri.org>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/danbri/factoidal.git",
-    "directory": "npm/factoidal"
+    "url": "git+https://github.com/danbri/factoidal-builds.git"
   },
   "main": "./index.js",
   "module": "./index.mjs",
   "browser": "./browser.js",
   "types": "./index.d.ts",
   "bin": {
-    "factoidal": "./bin/factoidal.mjs",
-    "foafnaut": "./bin/foafnaut.mjs",
-    "foafnaut-latest": "./bin/foafnaut-latest.mjs",
-    "foafnaut-bleedingedge": "./bin/foafnaut-bleedingedge.mjs"
+    "factoidal": "bin/factoidal.mjs",
+    "foafnaut": "bin/foafnaut.mjs",
+    "foafnaut-latest": "bin/foafnaut-latest.mjs",
+    "foafnaut-bleedingedge": "bin/foafnaut-bleedingedge.mjs"
   },
   "exports": {
     ".": {