@factoidal/core 0.11.0 → 0.13.0

package/lws/client.mjs

@@ -0,0 +1,319 @@
+// A `fetch` host for the Linked Web Storage 1.0 client.
+// https://github.com/danbri/factoidal/issues/917
+// Design record: docs/designissues/2026-10-22-lws-client.md
+// Drafts: https://w3c.github.io/lws-protocol/lws10-core/ (and lws10-index,
+// lws10-notifications-webhook)
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Call `lwsClientStart` with the caller's operation, then loop: when the
+// engine's action is `fetch`, send exactly that request with the `fetch`
+// it was given and pass the answer to `lwsClientStep`; when it is `done` or
+// `fail`, return or throw. It is a socket and nothing else.
+//
+// Every decision is in formal/lean4/L4Factoidal/LWS/Client/ (iron rule 7
+// of CLAUDE.md, anti-pattern 36): which request comes next, every header
+// field, every URL, every media type, the authorization flow and its
+// discovery checks, preconditions, retries, paging, and whether a
+// notification's signature verifies. This file reads no header, composes no
+// URL and chooses no media type. A reviewer who finds a header name, a
+// status code, a media type or a link relation here has found a rule
+// violation.
+//
+// THE WASM CONTRACT (docs/lws-solid-conformance.md, section "wasm ABI")
+//   lwsClientStart [opJson, sessionJson] -> { ok, state, action }
+//   lwsClientStep  [stateJson, eventJson] -> { ok, state, action }
+//
+//   action  { fetch: { method, url, headers: [[name, value]], bodyBase64? } }
+//         | { done: RESULT, session } | { fail: { code, ... }, session }
+//   event   { status, headers: [[name, value]], bodyBase64 } | { error }
+//
+// `state` is passed back unread. `session` (access tokens, the subject
+// token) is kept here and given to the next operation's start, unread.
+//
+// `fetch` is any function with the WHATWG fetch signature: Node's, a
+// browser's, or one that carries each request as a message over another
+// transport (XMPP, a worker port). The client needs no global fetch.
+
+import { loadEngine } from '../bin/engine.mjs'
+import { FactoidalError } from '../lib/errors.mjs'
+
+/** The ops this host needs from the engine. */
+export const LWS_CLIENT_OPS = ['lwsClientStart', 'lwsClientStep']
+
+/** The operation kinds of the ABI. Listed so a caller can be checked
+ *  against the contract; this host attaches no meaning to any of them. */
+export const LWS_CLIENT_KINDS = [
+  'discover', 'read', 'head', 'create', 'update', 'patch', 'delete', 'readLinkset',
+  'updateLinkset', 'move', 'list', 'typeIndex', 'search', 'subscribe', 'unsubscribe',
+  'requestAccess', 'grantAccess', 'getAccess', 'revokeAccess', 'verifyNotification'
+]
+
+/** The error an operation ends with. `reason` is the engine's code
+ *  (`discoveryValidation`, `preconditionFailed`, ...); `detail` is the
+ *  engine's whole `fail` document. */
+export class LwsClientError extends FactoidalError {
+  constructor (fail, extra = {}) {
+    const reason = fail && typeof fail.code === 'string' ? fail.code : 'unknown'
+    super(`lws client: ${reason}`, { code: 'lws.client' })
+    this.name = 'LwsClientError'
+    this.reason = reason
+    this.detail = fail
+    this.unknownOp = extra.unknownOp === true
+  }
+}
+
+function isUnknownOp (error) {
+  const text = error && error.message ? String(error.message) : String(error)
+  return text.indexOf('unknown op') >= 0
+}
+
+/** Bytes as base64 (RFC 4648 section 4): the transport encoding of the
+ *  string ABI, not a reading of the bytes. */
+function base64OfBytes (bytes) {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64')
+  }
+  let text = ''
+  for (let index = 0; index < bytes.length; index += 1) text += String.fromCharCode(bytes[index])
+  return btoa(text)
+}
+
+function bytesOfBase64 (text) {
+  if (typeof Buffer !== 'undefined') return new Uint8Array(Buffer.from(text, 'base64'))
+  const raw = atob(text)
+  const out = new Uint8Array(raw.length)
+  for (let index = 0; index < raw.length; index += 1) out[index] = raw.charCodeAt(index)
+  return out
+}
+
+/** A caller's body (string, Uint8Array, ArrayBuffer) as bytes. */
+function bytesOf (body) {
+  if (body === undefined || body === null) return null
+  if (typeof body === 'string') return new TextEncoder().encode(body)
+  if (body instanceof Uint8Array) return body
+  if (body instanceof ArrayBuffer) return new Uint8Array(body)
+  throw new TypeError('a body is a string, a Uint8Array or an ArrayBuffer')
+}
+
+/** An operation document: the caller's members, with a body carried as
+ *  base64. */
+function opDocument (op) {
+  const doc = { ...op }
+  if (doc.body !== undefined) {
+    const bytes = bytesOf(doc.body)
+    delete doc.body
+    if (bytes !== null) doc.bodyBase64 = base64OfBytes(bytes)
+  }
+  return doc
+}
+
+/**
+ * Whether the loaded engine carries the client operations.
+ *
+ * @param {object} engine the handle from `loadEngine()`
+ * @returns {Promise<{available: boolean, reason: string}>}
+ */
+export async function lwsClientOpsAvailable (engine) {
+  try {
+    engine.call('lwsClientStart', [JSON.stringify({ kind: 'head', url: 'http://localhost/' }), ''])
+    return { available: true, reason: 'lwsClientStart answered' }
+  } catch (error) {
+    if (isUnknownOp(error)) {
+      return {
+        available: false,
+        reason: 'the loaded l4factoidal WebAssembly module does not carry the LWS client ops ' +
+          '(rebuild formal/lean4/Wasm)'
+      }
+    }
+    return { available: true, reason: 'lwsClientStart answered with an engine error' }
+  }
+}
+
+/**
+ * An LWS client bound to one engine and one `fetch`.
+ *
+ * @param {object} [options]
+ * @param {object} [options.engine] an engine handle to reuse
+ * @param {Function} [options.fetch] the fetch to use (default `globalThis.fetch`)
+ * @param {string} [options.subjectToken] the authentication credential to
+ *   exchange for access tokens (RFC 8693 subject_token)
+ * @param {string} [options.subjectTokenType] its token type URI
+ * @param {object} [options.selfIssued] `{ subject, keyId, jwk }`: a P-256 key
+ *   to sign self-issued credentials with, instead of a subject token
+ * @param {object} [options.session] a session from an earlier client
+ * @param {number} [options.maxSteps] the loop cap of one operation
+ * @returns {Promise<object>} the client
+ */
+export async function createLwsClient (options = {}) {
+  const engine = options.engine !== undefined ? options.engine : await loadEngine()
+  const wire = typeof options.fetch === 'function' ? options.fetch : globalThis.fetch
+  if (typeof wire !== 'function') throw new TypeError('no fetch is available in this runtime')
+  const maxSteps = typeof options.maxSteps === 'number' ? options.maxSteps : 1024
+  let session = options.session !== undefined && options.session !== null
+    ? { ...options.session }
+    : {}
+  if (typeof options.subjectToken === 'string') session.subjectToken = options.subjectToken
+  if (typeof options.subjectTokenType === 'string') session.subjectTokenType = options.subjectTokenType
+  // `{ subject, keyId, jwk }`: a P-256 key the engine signs self-issued
+  // credentials with (lws10-authn-ssi-cid), passed through unread.
+  if (options.selfIssued !== undefined) session.selfIssued = options.selfIssued
+
+  function call (op, args) {
+    try {
+      return engine.call(op, args)
+    } catch (error) {
+      if (isUnknownOp(error)) {
+        throw new LwsClientError({ code: 'unknownOp', op }, { unknownOp: true })
+      }
+      throw error
+    }
+  }
+
+  /** Send one request exactly as the engine wrote it; the answer as an
+   *  event document. */
+  async function exchange (request) {
+    const init = {
+      method: request.method,
+      headers: Array.isArray(request.headers) ? request.headers : [],
+      redirect: 'manual'
+    }
+    if (typeof request.bodyBase64 === 'string') init.body = bytesOfBase64(request.bodyBase64)
+    let reply
+    try {
+      reply = await wire(request.url, init)
+    } catch (error) {
+      return { error: error && error.message ? String(error.message) : String(error) }
+    }
+    const headers = []
+    reply.headers.forEach((value, name) => { headers.push([name, value]) })
+    const bytes = new Uint8Array(await reply.arrayBuffer())
+    // The host's clock and random source, which the engine cannot reach: the
+    // iat, exp, nonce and jti of a self-issued credential.
+    const random = new Uint8Array(48)
+    globalThis.crypto.getRandomValues(random)
+    return {
+      status: reply.status,
+      headers,
+      bodyBase64: base64OfBytes(bytes),
+      now: Math.floor(Date.now() / 1000),
+      randomBase64: base64OfBytes(random)
+    }
+  }
+
+  /**
+   * Run one operation to its end.
+   *
+   * @param {object} op `{ kind, url, ... }`; `body` may be a string or bytes
+   * @returns {Promise<object>} the engine's `done` document
+   */
+  async function run (op) {
+    let envelope = call('lwsClientStart', [JSON.stringify(opDocument(op)), JSON.stringify(session)])
+    for (let step = 0; step < maxSteps; step += 1) {
+      const action = envelope.action || {}
+      if (action.fetch !== undefined) {
+        const event = await exchange(action.fetch)
+        envelope = call('lwsClientStep', [JSON.stringify(envelope.state), JSON.stringify(event)])
+        continue
+      }
+      if (action.session !== undefined) session = action.session
+      if (action.done !== undefined) return action.done
+      throw new LwsClientError(action.fail)
+    }
+    throw new LwsClientError({ code: 'hostStepLimit', steps: maxSteps })
+  }
+
+  const with_ = (kind) => (url, args = {}) => run({ ...args, kind, url })
+
+  return {
+    engine,
+    run,
+    /** The session (access tokens and subject token), for a later client. */
+    session: () => ({ ...session }),
+    discover: with_('discover'),
+    read: with_('read'),
+    head: with_('head'),
+    /** `create(containerUrl, { body, mediaType, slug, container, types, links })` */
+    create: with_('create'),
+    /** `update(url, { body, mediaType, precondition, tag, retry412, links })` */
+    update: with_('update'),
+    patch: with_('patch'),
+    /** `delete(url, { recursive, precondition, tag })` */
+    delete: with_('delete'),
+    readLinkset: with_('readLinkset'),
+    updateLinkset: with_('updateLinkset'),
+    /** `move(url, { destination })` */
+    move: with_('move'),
+    list: with_('list'),
+    typeIndex: with_('typeIndex'),
+    /** `search(anyUrlInTheStorage, { query })` */
+    search: with_('search'),
+    subscribe: with_('subscribe'),
+    unsubscribe: with_('unsubscribe'),
+    requestAccess: with_('requestAccess'),
+    grantAccess: with_('grantAccess'),
+    getAccess: with_('getAccess'),
+    revokeAccess: with_('revokeAccess'),
+    /** `verifyNotification(baseUrl, { requestTarget, method, headers, body })`:
+     *  the engine's verdict `{ accept, status, reason? }`. */
+    verifyNotification: with_('verifyNotification')
+  }
+}
+
+/**
+ * An HTTP receiver for webhook notifications. For each request it asks the
+ * engine (`verifyNotification`) and answers with the status of the
+ * verdict; an accepted notification goes to `onNotification`. The receiver
+ * reads no header and decides nothing.
+ *
+ * @param {object} options
+ * @param {object} options.client a client from `createLwsClient`
+ * @param {Function} [options.onNotification] `(verdict, bodyBytes, request)`
+ * @param {number} [options.port] default 0 (an ephemeral port)
+ * @param {string} [options.host] default 127.0.0.1
+ * @returns {Promise<{ url: string, close: Function, received: Function }>}
+ *   `url` is the receiver's base URL; any path under it receives
+ */
+export async function createNotificationReceiver (options) {
+  const { createServer } = await import('node:http')
+  const client = options.client
+  const host = typeof options.host === 'string' ? options.host : '127.0.0.1'
+  let base = ''
+  const verdicts = []
+  const server = createServer((request, response) => {
+    const chunks = []
+    request.on('data', (chunk) => chunks.push(chunk))
+    request.on('end', async () => {
+      const body = new Uint8Array(Buffer.concat(chunks))
+      const headers = []
+      for (let index = 0; index + 1 < request.rawHeaders.length; index += 2) {
+        headers.push([request.rawHeaders[index], request.rawHeaders[index + 1]])
+      }
+      let verdict
+      try {
+        verdict = await client.verifyNotification(base, {
+          requestTarget: request.url, method: request.method, headers, body
+        })
+      } catch (error) {
+        response.statusCode = 500
+        response.end()
+        return
+      }
+      verdicts.push(verdict)
+      if (verdict.accept === true && typeof options.onNotification === 'function') {
+        try { options.onNotification(verdict, body, { target: request.url, headers }) } catch (_e) { /* the caller's */ }
+      }
+      response.statusCode = verdict.status
+      response.end()
+    })
+  })
+  await new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(typeof options.port === 'number' ? options.port : 0, host, resolve)
+  })
+  base = `http://${host}:${server.address().port}/`
+  return {
+    url: base,
+    received: () => verdicts.slice(),
+    close: () => new Promise((resolve) => server.close(resolve))
+  }
+}

package/lws/persist.mjs

@@ -11,15 +11,83 @@
 //   DIR/lws-state.json      the snapshot, replaced atomically
 //
 // No request target ever becomes a file name here, so a request cannot
-// address a file outside DIR. The write is: a temporary file in DIR,
+// address a file outside DIR.
+//
+// ENCRYPTION AT REST (https://github.com/danbri/factoidal/issues/921)
+// This file also reads the environment variable FACTOIDAL_LWS_KEY and
+// draws 12 random bytes for every write. Both go to the engine unread: the
+// key text as the open configuration's `storageKey`, the bytes as the
+// `nonce` of the snapshot call. The engine decides everything else
+// (`L4Factoidal/LWS/SnapshotSeal.lean`): whether the key is valid, whether
+// the file in DIR is sealed, whether it authenticates, and the bytes of
+// the sealed document. This file never inspects the document it writes. The write is: a temporary file in DIR,
 // fsync, rename over the state file, fsync of DIR. A crash leaves the old
 // snapshot or the new one, never a torn one.
 
-import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeSync, existsSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, existsSync } from 'node:fs'
+import { dirname, join, resolve, sep } from 'node:path'
 
 export const STATE_FILE = 'lws-state.json'
 
+/** The environment variable that holds the storage key. */
+export const STORAGE_KEY_VARIABLE = 'FACTOIDAL_LWS_KEY'
+
+/**
+ * The text of the storage key: `explicit` when the caller gave a string,
+ * none when the caller gave `null`, and otherwise the environment variable
+ * (Node `process.env`, or `Deno.env` when only Deno's API is present). An
+ * empty value is no key. The engine checks the text.
+ */
+export function storageKeyText (explicit) {
+  if (typeof explicit === 'string') return explicit
+  if (explicit === null) return undefined
+  let value
+  try {
+    if (globalThis.process !== undefined && globalThis.process.env !== undefined) {
+      value = globalThis.process.env[STORAGE_KEY_VARIABLE]
+    } else if (globalThis.Deno !== undefined) {
+      value = globalThis.Deno.env.get(STORAGE_KEY_VARIABLE)
+    }
+  } catch (_error) {
+    value = undefined
+  }
+  return typeof value === 'string' && value !== '' ? value : undefined
+}
+
+/** The environment variable that sets where `lws-serve DIR` keeps the
+ *  storage when the caller names no `storage` (issue 918). */
+export const STORAGE_MODE_VARIABLE = 'FACTOIDAL_LWS_STORAGE'
+
+/**
+ * The text of the storage mode: `explicit` when the caller gave a string,
+ * and otherwise the environment variable, passed unread; the engine checks
+ * it. An empty value is none (the engine's default, the snapshot).
+ */
+export function storageModeText (explicit) {
+  if (typeof explicit === 'string') return explicit
+  let value
+  try {
+    if (globalThis.process !== undefined && globalThis.process.env !== undefined) {
+      value = globalThis.process.env[STORAGE_MODE_VARIABLE]
+    } else if (globalThis.Deno !== undefined) {
+      value = globalThis.Deno.env.get(STORAGE_MODE_VARIABLE)
+    }
+  } catch (_error) {
+    value = undefined
+  }
+  return typeof value === 'string' && value !== '' ? value : undefined
+}
+
+/** 12 bytes from the platform's random source, base64: the nonce of one
+ *  snapshot write. Pure I/O. */
+function nonceBase64 () {
+  const bytes = new Uint8Array(12)
+  globalThis.crypto.getRandomValues(bytes)
+  let text = ''
+  for (const b of bytes) text += String.fromCharCode(b)
+  return btoa(text)
+}
+
 /** The absolute path of the state file of a storage directory. */
 export function stateFileOf (dir) {
   return join(resolve(dir), STATE_FILE)
@@ -37,7 +105,7 @@ export function readSnapshot (dir) {
   try {
     return JSON.parse(text)
   } catch (error) {
-    throw new Error(`${file} is not JSON: ${error.message}`)
+    throw Object.assign(new Error(`${file} is not JSON: ${error.message}`), { stateFile: true })
   }
 }
 
@@ -65,14 +133,193 @@ export function writeSnapshot (dir, snapshot) {
 
 /**
  * After one step: when the engine says the storage changed, ask it for
- * the snapshot (`snapshotOp`) and write it.
+ * the snapshot (`snapshotOp`) and write it. The call carries a fresh random
+ * nonce; the engine uses it when the storage is sealed under a key.
  */
 export function persistIfChanged (engine, snapshotOp, handle, envelope, dir) {
   if (typeof dir !== 'string' || envelope === null || typeof envelope !== 'object') return
   if (envelope.changed !== true) return
-  const answer = engine.call(snapshotOp, [handle])
+  const answer = engine.call(snapshotOp, [handle, JSON.stringify({ nonce: nonceBase64() })])
   if (answer === null || typeof answer !== 'object' || answer.snapshot === undefined) {
     throw new Error(`${snapshotOp} answered with no snapshot`)
   }
   writeSnapshot(dir, answer.snapshot)
 }
+
+// ---------------------------------------------------------------------------
+// A STORAGE KEPT IN FILES (https://github.com/danbri/factoidal/issues/918)
+//
+// With the open configuration `storage: "files"` the engine decides the
+// directory layout and every byte (formal/lean4/L4Factoidal/LWS/FileLayout.lean,
+// design record docs/designissues/2026-10-22-lws-storage-on-disk.md). This
+// part of the file only performs what the engine names:
+//
+//   * reads: the engine names files (paths relative to DIR); each is read
+//     whole, or reported absent. At start (`lwsLoad`) and before a step that
+//     needs the bytes of a resource (a `read` answer of `lwsStep`, given to
+//     `lwsRead`, stage 2 of issue 918);
+//   * a plan of file operations, in order, with their bytes in one region:
+//       write  {path, temp, offset, length}  parent directory, temp file,
+//                                            fsync, rename, fsync directory
+//       append {path, offset, length}        append, fsync
+//       remove {path}                        remove; a missing file is no error
+//       rename {from, to}                    rename, fsync directory; a missing
+//                                            file is no error
+//
+// A name that leaves DIR is refused as a failure of this host; the engine
+// never names one.
+
+/** The absolute path of a name the engine gave, inside DIR. */
+function insideDir (root, name) {
+  if (typeof name !== 'string' || name === '') throw new Error('lws files: the engine named no file')
+  const abs = resolve(root, name)
+  if (!abs.startsWith(root + sep)) throw new Error(`lws files: ${name} is outside the storage directory`)
+  return abs
+}
+
+/** fsync a directory; some platforms cannot, and the rename stands. */
+function fsyncDir (dir) {
+  try {
+    const fd = openSync(dir, 'r')
+    try { fsyncSync(fd) } finally { closeSync(fd) }
+  } catch (_error) {
+    // Some platforms cannot fsync a directory.
+  }
+}
+
+/** `seed` for one engine call: 32 random bytes, base64. Pure I/O. */
+function seedBase64 () {
+  const bytes = new Uint8Array(32)
+  globalThis.crypto.getRandomValues(bytes)
+  let text = ''
+  for (const b of bytes) text += String.fromCharCode(b)
+  return btoa(text)
+}
+
+/**
+ * Read the files the engine named. Returns the `files` member of the load
+ * document and the bytes of the present files, one after the other.
+ */
+export function readNamedFiles (dir, names) {
+  const root = resolve(dir)
+  const files = []
+  const parts = []
+  let total = 0
+  for (const name of names) {
+    const abs = insideDir(root, name)
+    if (!existsSync(abs)) {
+      files.push({ path: name, present: false })
+      continue
+    }
+    const bytes = readFileSync(abs)
+    files.push({ path: name, present: true, length: bytes.length })
+    parts.push(bytes)
+    total += bytes.length
+  }
+  const region = new Uint8Array(total)
+  let at = 0
+  for (const part of parts) { region.set(part, at); at += part.length }
+  return { files, region }
+}
+
+/** Perform a plan of file operations exactly as the engine gave it. */
+export function performPlan (dir, plan, bytes) {
+  const root = resolve(dir)
+  mkdirSync(root, { recursive: true })
+  const slice = (op) => bytes.subarray(op.offset, op.offset + op.length)
+  for (const op of Array.isArray(plan) ? plan : []) {
+    switch (op.op) {
+      case 'write': {
+        const path = insideDir(root, op.path)
+        const temp = insideDir(root, op.temp)
+        mkdirSync(dirname(path), { recursive: true })
+        const fd = openSync(temp, 'w', 0o600)
+        try {
+          writeSync(fd, slice(op))
+          fsyncSync(fd)
+        } finally {
+          closeSync(fd)
+        }
+        renameSync(temp, path)
+        fsyncDir(dirname(path))
+        break
+      }
+      case 'append': {
+        const path = insideDir(root, op.path)
+        mkdirSync(dirname(path), { recursive: true })
+        const fd = openSync(path, 'a', 0o600)
+        try {
+          writeSync(fd, slice(op))
+          fsyncSync(fd)
+        } finally {
+          closeSync(fd)
+        }
+        break
+      }
+      case 'remove': {
+        try { unlinkSync(insideDir(root, op.path)) } catch (error) {
+          if (error.code !== 'ENOENT') throw error
+        }
+        break
+      }
+      case 'rename': {
+        const to = insideDir(root, op.to)
+        try { renameSync(insideDir(root, op.from), to) } catch (error) {
+          if (error.code !== 'ENOENT') throw error
+        }
+        fsyncDir(dirname(to))
+        break
+      }
+      default:
+        throw new Error(`lws files: the engine named an unknown file operation ${String(op.op)}`)
+    }
+  }
+}
+
+/**
+ * Open a storage kept in files: read what `lwsOpen` named, give it to
+ * `lwsLoad`, read what that names, until the engine is ready; then perform
+ * the plan of the start. An engine refusal is thrown as the engine's error.
+ */
+export function loadFiles (engine, handle, opened, dir) {
+  let want = opened.load
+  for (let round = 0; round < 8; round += 1) {
+    const { files, region } = readNamedFiles(dir, Array.isArray(want.read) ? want.read : [])
+    const answered = engine.callBlobIO('lwsLoad', [handle, JSON.stringify({ files, seed: seedBase64() })], region)
+    const envelope = answered.envelope
+    if (envelope.ready === true) {
+      performPlan(dir, envelope.plan, answered.bytes)
+      return envelope
+    }
+    if (envelope.load === undefined || envelope.load === null) {
+      throw new Error('lwsLoad answered neither load nor ready')
+    }
+    want = envelope.load
+  }
+  throw new Error('lwsLoad asked for more reads than one start may make')
+}
+
+/**
+ * Before one step of a storage kept in files (stage 2): read the body files
+ * the engine named in a `read` answer and give them to `lwsRead`. The engine
+ * checks each one (seal, length, digests); a refusal is thrown as its error.
+ */
+export function readStepBodies (engine, handle, names, dir) {
+  const { files, region } = readNamedFiles(dir, Array.isArray(names) ? names : [])
+  const answered = engine.callBlobIO('lwsRead', [handle, JSON.stringify({ files })], region)
+  const envelope = answered.envelope
+  if (envelope === null || typeof envelope !== 'object' || envelope.ok !== true) {
+    throw new Error(`lwsRead: ${envelope !== null && typeof envelope === 'object' ? envelope.error : 'no answer'}`)
+  }
+}
+
+/**
+ * After one step of a storage kept in files: when the engine says the
+ * storage changed, ask it for the write plan (`lwsPersist`) and perform it.
+ */
+export function persistFilesIfChanged (engine, handle, envelope, dir) {
+  if (typeof dir !== 'string' || envelope === null || typeof envelope !== 'object') return
+  if (envelope.changed !== true) return
+  const answered = engine.callBlobIO('lwsPersist', [handle, JSON.stringify({ seed: seedBase64() })], new Uint8Array(0))
+  performPlan(dir, answered.envelope.plan, answered.bytes)
+}