@factoidal/core 0.7.1 → 0.11.0

package/lib/delta-log-hosts.mjs

@@ -0,0 +1,191 @@
+// Host stores for the durable update log (deltaLog* in lib/api.mjs; hub
+// post 18; https://github.com/danbri/factoidal/issues/728).
+//
+// A host store keeps, for each log name, the records in commit order. A
+// record is { seq, epoch, hex }: `hex` is the hexadecimal text of one DLB1
+// record as the engine wrote it (op deltaLogEncode,
+// formal/lean4/Wasm/Ops/DeltaLog.lean). The store does not read the hex.
+// The byte format, the checksums, the torn-record rule and the merge are in
+// Lean (formal/lean4/L4Factoidal/Storage/BrowserLog.lean); a host store
+// only stores and loads text.
+//
+//   open(name)                 create the log if it is absent
+//   append(name, makeRecord)   seq := the number of records; makeRecord(seq)
+//                              (synchronous) gives {hex, epoch}; the record
+//                              is committed with that seq, atomically
+//   readAll(name)              the hex texts, in seq order
+//   destroy(name)              remove the log
+//   corruptLast(name)          TEST HOOK: cut the last 8 hex digits (4
+//                              bytes) of the last record, as a torn write
+//                              would; false when the log is empty
+//
+// No Node built-ins: the browser imports this file as it is.
+
+const DELTA_STORE = 'deltaBatches';
+
+/**
+ * The records in the memory of this process. The default store of the Node
+ * entry: the records live as long as the process. Pass another store to
+ * buildApi() (driver.deltaLogStore) to keep them elsewhere.
+ */
+export function memoryDeltaLogStore() {
+  const logs = new Map();
+  const recordsOf = (name) => {
+    if (!logs.has(name)) logs.set(name, []);
+    return logs.get(name);
+  };
+  return {
+    kind: 'memory',
+    async open(name) {
+      recordsOf(name);
+    },
+    async append(name, makeRecord) {
+      const records = recordsOf(name);
+      const seq = records.length;
+      const rec = makeRecord(seq);
+      records.push({ seq, epoch: rec.epoch, hex: rec.hex });
+      return { seq };
+    },
+    async readAll(name) {
+      return (logs.get(name) || []).map((r) => r.hex);
+    },
+    async destroy(name) {
+      logs.delete(name);
+    },
+    async corruptLast(name) {
+      const records = logs.get(name);
+      if (!records || records.length === 0) return false;
+      const last = records[records.length - 1];
+      last.hex = last.hex.slice(0, Math.max(0, last.hex.length - 8));
+      return true;
+    },
+  };
+}
+
+function indexedDbFactory() {
+  const factory = globalThis.indexedDB;
+  if (!factory) {
+    throw new Error('deltaLog: this runtime has no indexedDB; the browser entry keeps the log in IndexedDB');
+  }
+  return factory;
+}
+
+function idbOpen(dbName) {
+  return new Promise((resolve, reject) => {
+    const req = indexedDbFactory().open(dbName, 1);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(DELTA_STORE)) {
+        db.createObjectStore(DELTA_STORE, { keyPath: 'seq' });
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error || new Error('indexedDB.open failed'));
+    req.onblocked = () => reject(new Error('indexedDB.open blocked (another tab holds an open connection at an older version)'));
+  });
+}
+
+function requestDone(req) {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error || new Error('IndexedDB request failed'));
+  });
+}
+
+function transactionDone(tx) {
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error || new Error('IndexedDB transaction failed'));
+    tx.onabort = () => reject(tx.error || new Error('IndexedDB transaction aborted'));
+  });
+}
+
+/**
+ * The records in IndexedDB: one database for each log name, one object
+ * store 'deltaBatches' keyed by seq, one object { seq, epoch, hex } for each
+ * committed update. The default store of the browser entries.
+ *
+ * append() counts the records, calls makeRecord and adds the record in ONE
+ * readwrite transaction. IndexedDB runs the readwrite transactions of one
+ * object store one after another, so two tabs that append at the same time
+ * get different seq values; `add` (not `put`) refuses a seq that exists. The
+ * transaction asks for `durability: 'strict'`: Chrome 121 and later default
+ * to 'relaxed', where `complete` can fire before the data is on disk.
+ */
+export function indexedDbDeltaLogStore() {
+  return {
+    kind: 'indexedDB',
+    async open(name) {
+      const db = await idbOpen(name);
+      db.close();
+    },
+    async append(name, makeRecord) {
+      const db = await idbOpen(name);
+      try {
+        const tx = db.transaction(DELTA_STORE, 'readwrite', { durability: 'strict' });
+        const done = transactionDone(tx);
+        const store = tx.objectStore(DELTA_STORE);
+        let seq;
+        let failure = null;
+        const countReq = store.count();
+        countReq.onsuccess = () => {
+          seq = countReq.result;
+          try {
+            // Synchronous: the transaction stays active inside this callback.
+            const rec = makeRecord(seq);
+            store.add({ seq, epoch: rec.epoch, hex: rec.hex });
+          } catch (err) {
+            failure = err;
+            tx.abort();
+          }
+        };
+        try {
+          await done;
+        } catch (err) {
+          throw failure || err;
+        }
+        return { seq };
+      } finally {
+        db.close();
+      }
+    },
+    async readAll(name) {
+      const db = await idbOpen(name);
+      try {
+        const all = await requestDone(
+          db.transaction(DELTA_STORE, 'readonly').objectStore(DELTA_STORE).getAll());
+        all.sort((a, b) => a.seq - b.seq);
+        return all.map((r) => r.hex);
+      } finally {
+        db.close();
+      }
+    },
+    async destroy(name) {
+      await new Promise((resolve, reject) => {
+        const req = indexedDbFactory().deleteDatabase(name);
+        req.onsuccess = () => resolve();
+        req.onerror = () => reject(req.error || new Error('indexedDB.deleteDatabase failed'));
+        req.onblocked = () => reject(new Error('indexedDB.deleteDatabase blocked (another open connection)'));
+      });
+    },
+    async corruptLast(name) {
+      const db = await idbOpen(name);
+      try {
+        const all = await requestDone(
+          db.transaction(DELTA_STORE, 'readonly').objectStore(DELTA_STORE).getAll());
+        if (all.length === 0) return false;
+        all.sort((a, b) => a.seq - b.seq);
+        const last = all[all.length - 1];
+        const tx = db.transaction(DELTA_STORE, 'readwrite');
+        const done = transactionDone(tx);
+        tx.objectStore(DELTA_STORE).put({
+          seq: last.seq, epoch: last.epoch, hex: last.hex.slice(0, Math.max(0, last.hex.length - 8)),
+        });
+        await done;
+        return true;
+      } finally {
+        db.close();
+      }
+    },
+  };
+}

package/lib/lean-entry.mjs

@@ -0,0 +1,213 @@
+// The entry object over a loaded Lean engine handle.
+//
+// A Lean engine handle is what `loadL4()` of l4-assets/l4factoidal.js
+// answers: `call(op, args)`, `callBlob(op, args, bytes)`,
+// `callBlobIO(op, args, bytes)` over the dispatch ABI of
+// formal/lean4/Wasm/Dispatch.lean. Those methods parse the envelope and
+// THROW on {"ok":false,...}. lib/api.mjs wants the other shape: one method
+// per op, string arguments, the envelope as a JSON string, errors as
+// {"ok":false} envelopes. entryFromEngine() builds that object.
+//
+// Which ops exist is the engine's own answer: the `ops` reflection op
+// lists them, and the entry object has a method for each name in that list
+// and for no other. capabilities() in lib/api.mjs probes the methods, so a
+// wasm module older than this package reports what it serves.
+//
+// Four ops need more than strings in and an envelope out, and get their
+// own adapters below:
+//   - queryHdt and storeOpen read a byte region (the dispatch ABI's blob);
+//   - registerExtensionFunction / unregisterExtensionFunction /
+//     clearExtensionFunctions install the JavaScript call-out of SPARQL 1.1
+//     section 17.6 (the ops extRegister, extUnregister, extClear).
+// None of them makes a semantic decision: which IRIs reach the host, what
+// an absent answer means, which artifact a query reads, are decided in Lean.
+
+
+// The two npm entries and the engine each loads (issue 713 stage 4). The
+// core engine's `ops` reflection lists what only the full engine serves
+// (`fullOnlyOps`, `fullOnlyFormats`); a call to one of those names the
+// entry that has it.
+import { appTermToJson, termToJson } from '../rdfjs.mjs';
+export const FULL_ENTRY = '@factoidal/core';
+// The core profile is built for the hub pages only; the package ships the
+// full engine (owner, 2026-10-20).
+export const CORE_ENTRY = 'l4factoidal-core.js (the hub build of the core profile)';
+
+/**
+ * The message of a refusal by the core engine of something only the full
+ * engine serves.
+ * @param {string} what the function, op or format refused
+ */
+export function fullEngineMessage(what) {
+  return `${what} is not in the core engine (${CORE_ENTRY}, ` +
+    `l4factoidal-core.wasm); import '${FULL_ENTRY}', whose full engine ` +
+    '(l4factoidal.wasm) serves it';
+}
+
+// The ops whose second argument is a format tag of a document they read.
+const DOCUMENT_FORMAT_OPS = new Set(['parseToDatasetJson', 'datasetOpen', 'parseDocument']);
+const EXT_PENDING_MARKER = '__FACTOIDAL_EXT_PENDING__';
+
+function okEnvelope(extra) {
+  return JSON.stringify({ ok: true, ...(extra || {}) });
+}
+
+// An engine refusal arrives as an Error whose `.envelope` is the whole
+// {"ok":false,...} document (the loader keeps it, so a parse failure's
+// line, column, offset and format reach lib/api.mjs's ParseError). The
+// message stays the loader's own, "l4factoidal: <error>".
+function failEnvelope(err) {
+  const env = err && err.envelope;
+  if (env && typeof env === 'object' && env.ok === false) {
+    return JSON.stringify({ ...env, error: String(err.message) });
+  }
+  return JSON.stringify({ ok: false, error: String((err && err.message) || err) });
+}
+
+// One answer for Wasm/Ops/ExtFns.lean: the JavaScript value tagged with its
+// JavaScript type ({js, v}; a number as its Number::toString text), or a term
+// object. The engine chooses the datatype and the lexical form
+// (L4Factoidal.XSD.JsValue.jsLiteral, issue 894 item 3). '' means "no
+// value" (the section 17.6 error).
+function encodeExtAnswer(out) {
+  if (out === null || out === undefined || out === EXT_PENDING_MARKER) return '';
+  switch (typeof out) {
+    case 'boolean': return JSON.stringify({ js: 'boolean', v: out });
+    case 'number': return JSON.stringify({ js: 'number', v: Object.is(out, -0) ? '-0' : String(out) });
+    case 'bigint': return JSON.stringify({ js: 'bigint', v: out.toString() });
+    case 'string': return JSON.stringify({ js: 'string', v: out });
+    case 'object':
+      try { return JSON.stringify(appTermToJson(out)); } catch (_error) { return ''; }
+    default: return '';
+  }
+}
+
+// The Lean module asks its host through ONE global,
+// `globalThis.__factoidalExtCall(iri, argsJson)` (Wasm/ExtHost.lean). The
+// bridges lib/api.mjs registers are keyed by IRI here.
+function installExtensionBridge(eng, entry) {
+  const bridges = new Map();
+  const hostCall = (iri, argsJson) => {
+    const bridge = bridges.get(String(iri));
+    if (!bridge) return '';
+    try {
+      return encodeExtAnswer(bridge(String(iri), String(argsJson)));
+    } catch (_err) {
+      return '';
+    }
+  };
+  entry.registerExtensionFunction = (iri, bridge) => {
+    try {
+      eng.call('extRegister', [String(iri)]);
+      bridges.set(String(iri), bridge);
+      globalThis.__factoidalExtCall = hostCall;
+      return okEnvelope();
+    } catch (err) {
+      return failEnvelope(err);
+    }
+  };
+  entry.unregisterExtensionFunction = (iri) => {
+    try {
+      eng.call('extUnregister', [String(iri)]);
+      bridges.delete(String(iri));
+      return okEnvelope();
+    } catch (err) {
+      return failEnvelope(err);
+    }
+  };
+  entry.clearExtensionFunctions = () => {
+    try {
+      eng.call('extClear', []);
+      bridges.clear();
+      return okEnvelope();
+    } catch (err) {
+      return failEnvelope(err);
+    }
+  };
+}
+
+/**
+ * Build the entry object lib/api.mjs drives, from a loaded engine handle.
+ *
+ * @param {{call: Function, callBlob?: Function, callBlobIO?: Function}} eng
+ * @returns {Record<string, Function> & {abiVersion: string, engine: object}}
+ */
+export function entryFromEngine(eng) {
+  if (!eng || typeof eng.call !== 'function') {
+    throw new TypeError(
+      'factoidal: expected a Lean engine handle with a call(op, args) method ' +
+      '(the value loadL4() of l4-assets/l4factoidal.js resolves to)');
+  }
+  const reflection = eng.call('ops', []);
+  // `engine` is "core" for l4factoidal-core.wasm and "full" for
+  // l4factoidal.wasm; a module older than issue 713 stage 4 has no member and
+  // is the full engine.
+  const profile = reflection.engine === 'core' ? 'core' : 'full';
+  const entry = {
+    abiVersion: String(reflection.abiVersion),
+    engine: eng,
+    profile,
+    fullOnlyOps: Array.isArray(reflection.fullOnlyOps) ? reflection.fullOnlyOps.map(String) : [],
+    fullOnlyFormats: Array.isArray(reflection.fullOnlyFormats)
+      ? reflection.fullOnlyFormats.map((f) => String(f).toLowerCase()) : [],
+  };
+  const ops = Array.isArray(reflection.ops) ? reflection.ops : [];
+  for (const op of ops) {
+    if (op === 'ops') continue;
+    const formatChecked = DOCUMENT_FORMAT_OPS.has(op) && entry.fullOnlyFormats.length > 0;
+    entry[op] = (...args) => {
+      if (formatChecked && entry.fullOnlyFormats.includes(String(args[1] ?? '').toLowerCase())) {
+        return JSON.stringify({
+          ok: false, servedBy: 'full',
+          error: fullEngineMessage(`the format '${args[1]}'`),
+        });
+      }
+      try {
+        return JSON.stringify(eng.call(op, args.map(String)));
+      } catch (err) {
+        return failEnvelope(err);
+      }
+    };
+  }
+  if (ops.includes('extRegister')) installExtensionBridge(eng, entry);
+  // The byte-region ops. `bytes` is a Uint8Array; it crosses into the wasm
+  // heap with no encoding.
+  // queryHdt goes through the IO form of the blob entry when the engine has it:
+  // that entry reads the system clock once for the query, so NOW() (SPARQL 1.1
+  // section 17.4.5.1) is bound. The pure `callBlob` has no clock. An engine
+  // without `callBlobIO` serves the op through `callBlob`, as before
+  // (https://github.com/danbri/factoidal/issues/743).
+  if ((typeof eng.callBlobIO === 'function' || typeof eng.callBlob === 'function') &&
+      ops.includes('queryHdt')) {
+    entry.queryHdt = (bytes, sparql) => {
+      try {
+        const args = [String(sparql)];
+        return JSON.stringify(typeof eng.callBlobIO === 'function'
+          ? eng.callBlobIO('queryHdt', args, bytes).envelope
+          : eng.callBlob('queryHdt', args, bytes));
+      } catch (err) {
+        return failEnvelope(err);
+      }
+    };
+  }
+  if (typeof eng.callBlobIO === 'function' && ops.includes('storeOpen')) {
+    entry.storeOpen = (manifestHex, artifactsJson, bytes) => {
+      try {
+        return JSON.stringify(
+          eng.callBlobIO('storeOpen', [String(manifestHex), String(artifactsJson)], bytes).envelope);
+      } catch (err) {
+        return failEnvelope(err);
+      }
+    };
+  }
+  // datasetQuadsBin answers a byte region (formal/lean4/L4Factoidal/RDF/QuadsBin.lean):
+  // this method answers {envelope, bytes} and throws on a refusal.
+  const blobIoOps = Array.isArray(reflection.blobIoOps) ? reflection.blobIoOps : [];
+  if (typeof eng.callBlobIO === 'function' && blobIoOps.includes('datasetQuadsBin')) {
+    entry.datasetQuadsBin = (handle, optsJson) =>
+      eng.callBlobIO('datasetQuadsBin', [String(handle), String(optsJson ?? '')], new Uint8Array(0));
+  } else {
+    delete entry.datasetQuadsBin;
+  }
+  return entry;
+}

package/lib/pure.mjs

@@ -0,0 +1,98 @@
+// Pure functions over engine ops that had no JavaScript function before
+// 0.10.0. Each one takes values and returns a value: no handle, no hidden
+// state. Every decision is made by the Lean op it calls
+// (formal/lean4/Wasm/Ops/Crypto.lean, Wasm/Ops/Proof.lean,
+// Wasm/CoreDispatch.lean). This file converts bytes to hex and back.
+// No Node built-ins: the browser imports it as it is.
+
+function hexOf(bytes) {
+  if (!(bytes instanceof Uint8Array)) throw new TypeError('expected a Uint8Array');
+  let s = '';
+  for (const b of bytes) s += b.toString(16).padStart(2, '0');
+  return s;
+}
+
+function bytesOf(hex) {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.substr(2 * i, 2), 16);
+  return out;
+}
+
+function optHex(v) {
+  return v === undefined ? undefined : hexOf(v);
+}
+
+function str(name, v) {
+  if (typeof v !== 'string') throw new TypeError(`${name}: argument must be a string`);
+  return v;
+}
+
+/**
+ * @param {() => Promise<object>} loadEngine resolves to an engine handle
+ *   with `call(op, args)` (bin/engine.mjs, lib/browser-engine.mjs).
+ */
+export function buildPure(loadEngine) {
+  const call = async (op, args) => (await loadEngine()).call(op, args);
+
+  /** ChaCha20-Poly1305 seal (RFC 8439). key 32 bytes, nonce 12 bytes. */
+  async function aeadSeal({ key, nonce, plaintext, aad }) {
+    const r = await call('aeadSeal', [JSON.stringify({
+      alg: 'chacha20-poly1305', key: hexOf(key), nonce: hexOf(nonce),
+      aad: optHex(aad), plaintext: optHex(plaintext),
+    })]);
+    return bytesOf(r.ciphertext);
+  }
+
+  /** ChaCha20-Poly1305 open. Rejects when the tag does not authenticate. */
+  async function aeadOpen({ key, nonce, ciphertext, aad }) {
+    const r = await call('aeadOpen', [JSON.stringify({
+      alg: 'chacha20-poly1305', key: hexOf(key), nonce: hexOf(nonce),
+      aad: optHex(aad), ciphertext: hexOf(ciphertext),
+    })]);
+    return bytesOf(r.plaintext);
+  }
+
+  /** HPKE base mode seal, RFC 9180 DHKEM(X25519)/HKDF-SHA256/ChaCha20-Poly1305. */
+  async function hpkeSeal({ skE, pkR, plaintext, info, aad }) {
+    const r = await call('hpkeSeal', [JSON.stringify({
+      skE: hexOf(skE), pkR: hexOf(pkR), info: optHex(info),
+      aad: optHex(aad), plaintext: optHex(plaintext),
+    })]);
+    return { message: bytesOf(r.message), enc: bytesOf(r.enc), ciphertext: bytesOf(r.ciphertext) };
+  }
+
+  /** HPKE base mode open over the `message` that hpkeSeal returned. */
+  async function hpkeOpen({ skR, message, info, aad }) {
+    const r = await call('hpkeOpen', [JSON.stringify({
+      skR: hexOf(skR), info: optHex(info), aad: optHex(aad), message: hexOf(message),
+    })]);
+    return bytesOf(r.plaintext);
+  }
+
+  /** Check an FPP0 proof bundle (JSON text). Returns the engine's report. */
+  async function proofCheck(bundleJson) {
+    const { ok, ...rest } = await call('proofCheck', [str('proofCheck', bundleJson)]);
+    return rest;
+  }
+
+  /** Describe the shape of an FPP0 proof bundle without checking it. */
+  async function proofInspect(bundleJson) {
+    const { ok, ...rest } = await call('proofInspect', [str('proofInspect', bundleJson)]);
+    return rest;
+  }
+
+  /** RDFC-1.0 over N-Quads text, N-Quads text out. */
+  async function canonicalizeNQuads(nquads) {
+    return (await call('canonicalizeToNQuads', [str('canonicalizeNQuads', nquads)])).nquads;
+  }
+
+  /** Parse N-Quads (or N-Triples) text and write it back as N-Quads. */
+  async function normalizeNQuads(nquads) {
+    return (await call('serializeNQuads', [str('normalizeNQuads', nquads)])).nquads;
+  }
+
+  return {
+    aeadSeal, aeadOpen, hpkeSeal, hpkeOpen,
+    proofCheck, proofInspect, canonicalizeNQuads, normalizeNQuads,
+  };
+}

package/lib/store.mjs

@@ -0,0 +1,115 @@
+// Host plumbing for the Lean persisted store (Shardborough IBK3/IBK4/IBK5
+// generations), shared by Node and the browser.
+//
+// A store is read through a READER: a function from a path relative to the
+// collection root ('CURRENT', 'gen-1/manifest.sbm2',
+// 'gen-1/predicate-0.ibk3', ...) to the bytes of that file (a Uint8Array or
+// an ArrayBuffer, or a Promise of either). index.mjs builds one over the
+// file system; a browser page builds one over fetch().
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Read CURRENT, read a manifest by name, read the artifact files the
+// engine named, concatenate their bytes and say where each one starts.
+// It never parses a manifest, verifies a digest, decodes a block or
+// chooses an artifact: the ops storeManifestInspect, storeQueryPlan and
+// storeOpen (formal/lean4/Wasm/Ops/Store.lean, StoreHandles.lean) decide
+// all of that. bin/store.mjs is the same plumbing over store-host/ for the
+// `factoidal` command.
+
+import { requireChildName } from '../store-host/paths.mjs';
+
+/** The manifest file names a generation directory can carry, in the order
+ *  the native tools try them. */
+export const MANIFEST_NAMES = ['manifest.sbm2', 'manifest.sbm1'];
+
+async function readBytes(reader, path) {
+  const out = await reader(path);
+  if (out instanceof Uint8Array) return out;
+  if (out instanceof ArrayBuffer) return new Uint8Array(out);
+  if (ArrayBuffer.isView(out)) return new Uint8Array(out.buffer, out.byteOffset, out.byteLength);
+  throw new TypeError(
+    `store reader: '${path}' answered ${out === null ? 'null' : typeof out}, ` +
+    'expected a Uint8Array or an ArrayBuffer');
+}
+
+/**
+ * The generation to open and its manifest bytes. With no `generation`,
+ * CURRENT names it (an activated collection); with one, that generation is
+ * opened directly, activated or not.
+ */
+export async function openGeneration(reader, generation) {
+  let name = generation;
+  if (name == null) {
+    let pointer;
+    try {
+      pointer = await readBytes(reader, 'CURRENT');
+    } catch (cause) {
+      const err = new Error(
+        `openStore: the collection root has no readable CURRENT pointer (${cause && cause.message})`);
+      err.cause = cause;
+      throw err;
+    }
+    // CURRENT holds a UTF-8 generation name (docs/shardborough-storage-spec.md
+    // section 6.4); trailing ASCII whitespace is tolerated, as in
+    // store-host/index.mjs.
+    name = new TextDecoder('utf-8', { fatal: true }).decode(pointer).replace(/[\r\n\t ]+$/, '');
+    requireChildName(name, 'CURRENT');
+  } else {
+    requireChildName(String(name), 'generation');
+    name = String(name);
+  }
+  for (const manifestName of MANIFEST_NAMES) {
+    let manifest;
+    try {
+      manifest = await readBytes(reader, `${name}/${manifestName}`);
+    } catch (_err) {
+      continue;
+    }
+    return { generation: name, manifestName, manifest, activated: generation == null };
+  }
+  throw new Error(`openStore: generation '${name}' has none of ${MANIFEST_NAMES.join(', ')}`);
+}
+
+/** Read the named artifacts of one generation into one region, with a
+ *  {key, offset, len} window per artifact. */
+export async function readRegion(reader, generation, keys) {
+  const chunks = [];
+  for (const key of keys) chunks.push(await readBytes(reader, `${generation}/${key}`));
+  let total = 0;
+  for (const c of chunks) total += c.length;
+  const blob = new Uint8Array(total);
+  const artifacts = [];
+  let offset = 0;
+  for (let i = 0; i < chunks.length; i += 1) {
+    blob.set(chunks[i], offset);
+    artifacts.push({ key: keys[i], offset, len: chunks[i].length });
+    offset += chunks[i].length;
+  }
+  return { blob, artifacts, total };
+}
+
+/** The artifact keys a manifest declares, as storeManifestInspect lists
+ *  them: every block, every index sidecar, every out-of-line literal. */
+export function manifestKeys(inspectEnvelope) {
+  const keys = [];
+  for (const entry of inspectEnvelope.entries || []) {
+    keys.push(entry.key);
+    for (const key of Object.values(entry.sidecars || {})) keys.push(key);
+  }
+  for (const blob of inspectEnvelope.blobs || []) keys.push(blob.key);
+  return keys;
+}
+
+const HEX = (() => {
+  const t = new Array(256);
+  for (let b = 0; b < 256; b += 1) t[b] = b.toString(16).padStart(2, '0');
+  return t;
+})();
+
+/** Lowercase hexadecimal: the transport the manifest argument of the store
+ *  ops takes. Artifact bytes never take this path. */
+export function hexOfBytes(bytes) {
+  const parts = new Array(bytes.length);
+  for (let i = 0; i < bytes.length; i += 1) parts[i] = HEX[bytes[i]];
+  return parts.join('');
+}

package/lib/version.mjs

@@ -0,0 +1,5 @@
+// The package version, as a module the browser can import (a JSON import
+// 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.11.0';