@factoidal/core 0.35.1 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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 = "ccdd8676f40a";
 
 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-2fd7fc4d38f3-web",
+  "releaseRun": "https://github.com/danbri/factoidal-builds/actions/runs/43144347600",
+  "gitSha": "2fd7fc4d38f352c221004f3e407707f69afbb3e8",
+  "builtAt": "2026-11-12T04:22:57Z",
   "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": "ccdd8676f40a0aa78a3a0a997cf561bff59c9af2e544e1231eed5007ecb94250",
+  "wasmBytes": 32729309,
   "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.36.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.36.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": {
     ".": {