@makerclay/core 1.0.0

package/src/paths.js

@@ -0,0 +1,302 @@
+import path from 'upath';
+import fs from 'node:fs';
+import { realpath, statIfExists } from './util/fsx.js';
+import { HostError } from './spec/codes.js';
+
+// Every disk path in the core resolves through this module and nowhere else.
+// It is the entire difference between the `clean` layout (makerclay: state in
+// its own data dir) and the future `inline` layout (hyperclay-local: a user
+// folder with state nested inside it), so v2 convergence is a paths change
+// rather than a migration.
+
+// One error vocabulary. This used to be its own class with its own constructor,
+// `PathError(status, message, code)`, sitting beside `HostError(code, message,
+// status)` — the same three values in the opposite order, so passing a status
+// where a code belonged was a silent mistake with a plausible-looking result.
+//
+// It stays a distinct subclass rather than disappearing into HostError because
+// two callers genuinely need to know that path resolution is what refused,
+// rather than something deeper in the same call: `serve.locate` continues to the
+// next candidate on a miss, and `requests.resolveTarget` turns a miss into null
+// while a HostError from the gate must still reach the client.
+export class PathError extends HostError {
+  constructor(code, message) {
+    super(code, message);
+    this.name = 'PathError';
+  }
+}
+
+const notFound = (message = 'File not found') => new PathError('not-found', message);
+const invalidPath = (message = 'Invalid path') => new PathError('bad-request', message);
+
+const OWNER_NAME = /^[a-z0-9_-]{2,32}$/;
+
+// Decode exactly once. Express never decodes req.path, so without this a file
+// with a space or any non-ASCII name is unreachable; decoding twice would let
+// `%252e%252e` walk out of the tree.
+export function decodeOnce(urlPath) {
+  try {
+    return decodeURIComponent(urlPath);
+  } catch {
+    throw invalidPath('Malformed URL encoding');
+  }
+}
+
+// Reject traversal, NUL and backslash outright; hide dotfiles behind a 404 so
+// their existence never leaks. A leading-dot refusal is also what makes an
+// `inline` state directory structurally unservable later.
+export function validateSegments(relPath, { maxDepth = 5 } = {}) {
+  if (typeof relPath !== 'string' || relPath.length === 0) {
+    throw invalidPath();
+  }
+  if (relPath.includes('\0') || relPath.includes('\\')) {
+    throw invalidPath();
+  }
+  if (path.isAbsolute(relPath)) {
+    throw invalidPath();
+  }
+
+  const segments = relPath.split('/').filter((segment) => segment.length > 0);
+  if (segments.length === 0) throw invalidPath();
+  if (segments.length > maxDepth + 1) throw invalidPath('Path too deep');
+
+  for (const segment of segments) {
+    if (segment === '.' || segment === '..') throw invalidPath();
+    if (segment.startsWith('.')) throw notFound();
+    if (segment.length > 255) throw invalidPath();
+  }
+  return segments;
+}
+
+export function isDocumentPath(relPath) {
+  return /\.(html|htmlclay)$/i.test(relPath);
+}
+
+// A node row whose path begins with a dot segment is a metadata anchor, not a
+// file in the served tree (`.records/<slug>/<key>.json` is the only one in v1).
+// validateSegments 404s the path, the scanner's walk skips it, and no listing
+// shows it, so this is the one predicate that keeps those three honest.
+export function isReservedNodePath(relPath) {
+  return String(relPath || '').startsWith('.');
+}
+
+function isContained(base, target) {
+  if (target === base) return true;
+  return target.startsWith(base.endsWith('/') ? base : `${base}/`);
+}
+
+// Walk up until realpath succeeds, then re-append the not-yet-existing tail.
+// This is what makes write resolution work for a file about to be created.
+async function realpathNearestParent(dir) {
+  const missing = [];
+  let current = dir;
+  for (;;) {
+    try {
+      const real = await realpath(current);
+      return missing.length ? path.join(real, ...missing.reverse()) : real;
+    } catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') {
+        throw new PathError('forbidden', 'Access denied');
+      }
+      const parent = path.dirname(current);
+      if (parent === current) throw new PathError('forbidden', 'Access denied');
+      missing.push(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+// Synchronous on purpose: this runs once at boot, before a single request, and
+// keeping it sync is what lets createHost() stay a plain constructor.
+// `create: false` is for inspection, which must not bring an installation into
+// existence just by looking at it. Everything else here is pure path arithmetic;
+// this one mkdir was the only write, and a caller that passes false is promising
+// the directory already exists.
+export function createPaths({ data, layout = 'clean', maxFolderDepth = 5, create = true }) {
+  if (layout !== 'clean') {
+    throw new Error(`Unsupported layout: ${layout}. Only 'clean' ships in v1.`);
+  }
+  if (!data || typeof data !== 'string') {
+    throw new Error('createHost requires a data directory');
+  }
+
+  const root = path.resolve(data);
+  if (create) fs.mkdirSync(path.join(root, 'files'), { recursive: true });
+  const dataReal = path.resolve(fs.realpathSync(root));
+
+  const dirs = {
+    data: dataReal,
+    files: path.join(dataReal, 'files'),
+    tenants: path.join(dataReal, 'tenants'),
+    versions: path.join(dataReal, 'versions'),
+    trash: path.join(dataReal, 'trash'),
+    derived: path.join(dataReal, 'derived'),
+    ui: path.join(dataReal, 'ui'),
+    records: path.join(dataReal, 'records'),
+  };
+
+  const files = {
+    db: path.join(dataReal, 'makerclay.db'),
+    lock: path.join(dataReal, 'makerclay.lock'),
+    config: path.join(dataReal, 'config.json'),
+  };
+
+  function realmRoot(owner = '') {
+    if (!owner) return dirs.files;
+    if (!OWNER_NAME.test(owner)) throw notFound();
+    return path.join(dirs.tenants, owner);
+  }
+
+  // Reject any symlink inside a managed tree. A network server must not follow
+  // a user symlink into versions/, the db, or the host filesystem; the desktop
+  // consent registry hyperclay-local uses does not come along.
+  function assertNoSymlinkTraversal(base, lexical, real) {
+    if (real !== lexical || !isContained(base, real)) {
+      throw notFound();
+    }
+  }
+
+  // Canonical read resolution. Returns the real absolute path of an existing
+  // entry, or throws a PathError when it is absent, a symlink, or outside the
+  // realm.
+  async function resolveRead(owner, relPath) {
+    const base = realmRoot(owner);
+    validateSegments(relPath, { maxDepth: maxFolderDepth });
+    const lexical = path.resolve(path.join(base, relPath));
+    if (!isContained(base, lexical)) throw notFound();
+
+    let real;
+    try {
+      real = await realpath(lexical);
+    } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
+        throw notFound();
+      }
+      throw new PathError('forbidden', 'Access denied');
+    }
+    assertNoSymlinkTraversal(base, lexical, real);
+    return real;
+  }
+
+  // What a reader almost always wants: null instead of a throw. Every caller of
+  // `resolveRead` outside a writer was wrapping it in a try/catch that tested
+  // `instanceof PathError` and returned null, which put the decision about which
+  // failures are ordinary in the caller, where it has to be re-derived and can
+  // silently widen. It belongs here, where "the path does not resolve" is known
+  // precisely.
+  //
+  // Anything that is not a PathError still throws: a permissions failure or a
+  // full disk is not a missing file, and answering 404 to one is how a real
+  // fault gets mistaken for a typo.
+  async function tryResolveRead(owner, relPath) {
+    try {
+      return await resolveRead(owner, relPath);
+    } catch (error) {
+      if (error instanceof PathError) return null;
+      throw error;
+    }
+  }
+
+  // Canonical create/write resolution. The returned path is both the file to
+  // write and the lock key; every writer uses exactly this.
+  async function resolveWrite(owner, relPath) {
+    const base = realmRoot(owner);
+    validateSegments(relPath, { maxDepth: maxFolderDepth });
+    const lexical = path.resolve(path.join(base, relPath));
+    if (!isContained(base, lexical)) throw notFound();
+
+    const existing = await statIfExists(lexical);
+    if (existing) {
+      const real = await realpath(lexical);
+      assertNoSymlinkTraversal(base, lexical, real);
+      return real;
+    }
+    const parentReal = await realpathNearestParent(path.dirname(lexical));
+    const real = path.join(parentReal, path.basename(lexical));
+    assertNoSymlinkTraversal(base, lexical, real);
+    return real;
+  }
+
+  // versions/<slug>--<id8>/ — keyed by identity, named for humans. The slug is
+  // the current basename (display only, renamed in place on file rename); id8
+  // is the real key.
+  //
+  // id8 is the LAST eight characters of the ULID, not the first. The first ten
+  // are the mint TIMESTAMP, so an eight-character prefix has no randomness in it
+  // at all and every pair of documents created in the same second collides. That
+  // is not a rare race: a signup forks a document milliseconds after the one it
+  // copied, and the two then shared a history folder, which let the owner list
+  // and restore a tenant's bytes. The tail is 40 bits of randomness.
+  function idKey(nodeId) {
+    return String(nodeId).slice(-8);
+  }
+
+  function versionsDir(nodeId, slug) {
+    const safeSlug = String(slug || 'document')
+      .replace(/\.(html|htmlclay)$/i, '')
+      .replace(/[^A-Za-z0-9._-]+/g, '-')
+      .replace(/^[.-]+/, '')
+      .slice(0, 64) || 'document';
+    return path.join(dirs.versions, `${safeSlug}--${idKey(nodeId)}`);
+  }
+
+  function versionsDirPrefix(nodeId) {
+    return `--${idKey(nodeId)}`;
+  }
+
+  function trashPath(nodeId, originalName) {
+    const safe = String(originalName).replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 96);
+    return path.join(dirs.trash, `${nodeId}__${safe}`);
+  }
+
+  // Collection records live OUTSIDE files/, and that placement is the whole
+  // privacy model rather than a filing preference. A record is a stranger's
+  // submission; inside the served tree it would be one un-set `private` flag
+  // away from public, and a lost database would set it back to public. Out
+  // here, the collection API is the only door, and it is the only thing that
+  // checks record codes.
+  //
+  // The record's node row (which carries its identity, its record_auth and its
+  // tombstone) uses the reserved `.records/` path prefix. No real file can
+  // collide with it: validateSegments 404s every dot-leading segment.
+  function recordsDir(slug) {
+    return path.join(dirs.records, String(slug).replace(/[^a-z0-9_-]/gi, ''));
+  }
+
+  function recordPath(slug, filename) {
+    return path.join(recordsDir(slug), `${String(filename).replace(/[^a-z0-9._@-]/gi, '')}.json`);
+  }
+
+  function recordNodePath(slug, filename) {
+    return `.records/${String(slug).replace(/[^a-z0-9_-]/gi, '')}/${String(filename).replace(/[^a-z0-9._@-]/gi, '')}.json`;
+  }
+
+  function derivedApiPath(owner, relPath) {
+    const realm = owner ? path.join('tenants', owner) : 'files';
+    return path.join(dirs.derived, 'api', realm, `${relPath}.json`);
+  }
+
+  function derivedTailwindPath(owner, name) {
+    const realm = owner ? path.join('tenants', owner) : 'files';
+    return path.join(dirs.derived, 'tailwind', realm, `${name}.css`);
+  }
+
+  return {
+    layout,
+    maxFolderDepth,
+    dirs,
+    files,
+    realmRoot,
+    resolveRead,
+    tryResolveRead,
+    resolveWrite,
+    versionsDir,
+    versionsDirPrefix,
+    trashPath,
+    recordsDir,
+    recordPath,
+    recordNodePath,
+    derivedApiPath,
+    derivedTailwindPath,
+  };
+}

package/src/recovery/overlay.js

@@ -0,0 +1,327 @@
+import path from 'upath';
+import { exists, readdirIfExists, readFileTextIfExists, statIfExists } from '../util/fsx.js';
+import { token as mintToken } from '../util/id.js';
+
+// Deciding whether the store can be trusted, and rebuilding it when it cannot.
+//
+// The store is an OVERLAY. The durable records under versions/<slug>--<id8>/
+// are the source of truth, so losing the database must not lose privacy or
+// tenancy (§6.3). With the db gone and the records present, the overlay is
+// rebuilt from them before the first request. With neither, but with evidence
+// of prior state on disk, the host refuses to serve a freshly public tree and
+// asks for recovery mode instead.
+//
+// Never guess. A clear degraded mode beats a half-working dashboard sitting on
+// top of uncertain privacy metadata.
+
+export function createOverlay({ paths, store, nodes, clock, logger = console }) {
+  async function hasAny(dir) {
+    const names = (await readdirIfExists(dir)).filter((name) => !name.startsWith('.'));
+    return names.length > 0;
+  }
+
+  // One pass over versions/, which is the same walk the attic will need. The
+  // directory name carries only the last eight characters of the id, so the
+  // record inside is what is authoritative, never the folder name.
+  async function readAllMeta() {
+    const found = [];
+    for (const name of await readdirIfExists(paths.dirs.versions)) {
+      const raw = await readFileTextIfExists(path.join(paths.dirs.versions, name, 'meta.json'));
+      if (!raw) continue;
+      try {
+        const record = JSON.parse(raw);
+        if (record?.id && typeof record.path === 'string') found.push(record);
+      } catch {
+        logger.warn?.(`[makerclay] unreadable durable record in versions/${name}`);
+      }
+    }
+    return found;
+  }
+
+  // Written once, at the end of the first boot that reaches a normal state. It
+  // is what tells "this database is ours" apart from "this database is new",
+  // and row COUNT cannot: a host whose only document was purged has zero rows
+  // and a perfectly healthy db, which would otherwise read as catastrophic loss.
+  const INSTALLED = 'installed';
+
+  function markInstalled() {
+    if (store && !store.getKv(INSTALLED)) store.setKv(INSTALLED, String(clock.now()));
+  }
+
+  // A database that opens and answers is not the same as a database that is
+  // sound: SQLite will read `kv` happily out of a file whose other pages are
+  // corrupt. §18.3 names a failed integrity check as a recovery trigger, and it
+  // has to be checked BEFORE the installed key, because the installed key is one
+  // of the things a corrupt file can hand back.
+  function integrity() {
+    if (!store.integrityCheck) return 'ok';
+    try {
+      const rows = store.integrityCheck();
+      return rows.length === 1 && rows[0] === 'ok' ? 'ok' : rows.join('; ');
+    } catch (error) {
+      return error?.message || String(error);
+    }
+  }
+
+  // `normal` | `rebuild` | `recover`
+  async function assess() {
+    if (!store) return { state: 'normal', reason: 'no-store' };
+
+    const sound = integrity();
+    if (sound !== 'ok') return { state: 'recover', reason: 'integrity-check-failed', error: sound };
+
+    if (store.getKv(INSTALLED)) return { state: 'normal', reason: 'installed' };
+
+    const rows = store.listAllNodes({ includeDeleted: true });
+    if (rows.length > 0) return { state: 'normal', reason: 'store-populated' };
+
+    // Durable records are consulted FIRST, because they are the evidence. Asking
+    // about versions/ or tenants/ first gets it backwards: a document the owner
+    // marked private but never saved has a record and no versions, so a
+    // versions-first check reads "fresh install" and serves it to the world.
+    const records = await readAllMeta();
+    if (records.length > 0) return { state: 'rebuild', reason: 'records-present', records: records.length };
+
+    // No rows, no records. Anything else on disk means there WAS state here and
+    // nothing left records who could read what; serving now would publish
+    // whatever used to be private.
+    const priorState = (await hasAny(paths.dirs.versions)) || (await hasAny(paths.dirs.tenants));
+    if (priorState) return { state: 'recover', reason: 'state-without-metadata' };
+
+    return { state: 'normal', reason: 'fresh' };
+  }
+
+  // Runs on EVERY boot, not only into an empty database. The likeliest real
+  // disaster is not a lost database, it is a RESTORED one: an old backup dropped
+  // onto today's files passes every health check, has rows, and says a document
+  // is public that was made private after the backup was taken. Neither the
+  // journal nor a rowless-file rule ever covered that. This does.
+  //
+  // Inserting a row for a record that has none is deliberate: it means the serve
+  // lane needs no special case at all, because by the time the first request is
+  // answered every previously-flagged document already has a correct row. The
+  // rows cost nothing new, since a record only exists for a document that was
+  // saved or flagged, which is exactly the set that already had rows.
+  //
+  // Where the two disagree, THE MORE RESTRICTIVE VALUE WINS. Not "the newer one":
+  // there is no reliable way to tell which is newer (a restored versions/ can be
+  // older than the database just as easily as the reverse), and guessing wrong in
+  // the permissive direction publishes something. Guessing wrong in the
+  // restrictive direction costs the owner one click.
+  async function reconcileMeta() {
+    if (!store) return { records: 0, inserted: 0, tightened: 0, skipped: 0 };
+    const records = await readAllMeta();
+    let inserted = 0;
+    let tightened = 0;
+    let skipped = 0;
+
+    for (const record of records) {
+      const row = store.getNodeById(record.id);
+      // Read before the transaction, because a transaction body has to be
+      // synchronous and this is the one question only the disk can answer. Asked
+      // only when a trash marker is actually in play, so an ordinary boot still
+      // costs nothing per record.
+      const fileThere = record.trashed && row && !row.deletedAt
+        ? await exists(path.join(paths.realmRoot(row.owner || ''), row.path))
+        : false;
+
+      if (!row) {
+        // Two records can name the same path: rename a document, create a new
+        // one at the old name, then restore a database from before the rename.
+        // The live row is the one whose file is actually there, so the loser is
+        // not inserted at all. It keeps its history and becomes an attic entry,
+        // which is exactly what the attic is for. Inserting it anyway is the one
+        // option that is neither open nor closed: SQLite refuses on the live
+        // path index, the exception escapes boot(), and the host never serves
+        // again.
+        const holder = store.getNode(record.owner || '', record.path);
+        if (holder && holder.id !== record.id) {
+          skipped += 1;
+          logger.warn?.(
+            `[makerclay] ${record.path} is already held by another document, so the ` +
+            'older record was left for the attic rather than restored.',
+          );
+          continue;
+        }
+      }
+
+      // One transaction per record, never one around the whole loop: a single
+      // unplaceable record must not discard the privacy tightening every other
+      // record just earned.
+      try {
+        const verdict = store.tx(() => {
+          if (!row) {
+            const now = clock.now();
+            store.insertNode({
+              id: record.id,
+              owner: record.owner || '',
+              path: record.path,
+              kind: record.kind || nodes.kindFor(record.path),
+              private: !!record.private,
+              isolated: record.isolated === undefined ? null : record.isolated,
+              signups: !!record.signups,
+              // Restoring the digest is also what restores the TRUST marker:
+              // `isolatedFor` reads `etag == null` to mean "the owner has never
+              // saved these bytes through this host, so sandbox it". A record only
+              // exists for a document that was saved or flagged, so a record with
+              // a digest is proof of a save and the row should say so. A document
+              // that was only ever flagged has no digest in its record either, and
+              // correctly stays untrusted.
+              etag: record.etag ?? null,
+              bytes: record.bytes ?? null,
+              deletedAt: record.trashed ? now : null,
+              seq: store.nextSeq(),
+              createdAt: now,
+              updatedAt: now,
+            });
+            return 'inserted';
+          }
+          const patch = {};
+          // private: true is the restrictive side.
+          if (record.private && !row.private) patch.private = true;
+          // signups: FALSE is the restrictive side. Losing "signups on" costs the
+          // owner a click; losing "signups off" lets strangers open accounts.
+          if (record.signups === false && row.signups) patch.signups = false;
+          // isolated is tri-state, most restrictive first: true, then null
+          // (inherit the host default), then an explicit false.
+          const rank = (value) => (value === true ? 2 : value === false ? 0 : 1);
+          if (rank(record.isolated) > rank(row.isolated)) patch.isolated = record.isolated;
+          // Only when nothing is at the row's path. A trashed document's bytes
+          // live under trash/, so tombstoning a row whose file is sitting right
+          // where it says it is would leave the row saying trashed with the file
+          // outside trash/, and restore would then go looking for bytes that are
+          // not there.
+          if (record.trashed && !row.deletedAt && !fileThere) patch.deletedAt = clock.now();
+          if (!Object.keys(patch).length) return 'unchanged';
+          store.updateNode(row.id, { ...patch, updatedAt: clock.now(), seq: store.nextSeq() });
+          return 'tightened';
+        });
+        if (verdict === 'inserted') inserted += 1;
+        else if (verdict === 'tightened') tightened += 1;
+      } catch (error) {
+        skipped += 1;
+        logger.warn?.(
+          `[makerclay] could not reconcile the record for ${record.path}: ${error?.message || error}`,
+        );
+      }
+    }
+
+    if (inserted || tightened || skipped) {
+      logger.warn?.(
+        `[makerclay] reconciled the overlay against ${records.length} durable record(s): ` +
+        `${inserted} row(s) restored, ${tightened} tightened, ${skipped} skipped.`,
+      );
+    }
+    return { records: records.length, inserted, tightened, skipped };
+  }
+
+  // Deliberately partial, and honest about it. Sessions, share links, tenant
+  // passwords, save tokens and record codes are NOT recoverable and are not
+  // faked. What comes back is the state whose loss would fail open, plus enough
+  // to reach the bytes again.
+  async function rebuild() {
+    if (!store) return { nodes: 0, tenants: 0, collections: 0, trashed: 0 };
+    const reconciled = await reconcileMeta();
+
+    // Trashed bytes live at trash/<nodeId>__<name> and the name is
+    // self-describing, so a document trashed before its record was written is
+    // still reachable. Without this the bytes sit there with no row, the trash
+    // view is empty, and restore cannot be reached.
+    let trashed = 0;
+    const byId = new Map((await readAllMeta()).map((record) => [record.id, record]));
+    for (const name of await readdirIfExists(paths.dirs.trash)) {
+      const split = name.indexOf('__');
+      if (split <= 0) continue;
+      const id = name.slice(0, split);
+      if (store.getNodeById(id)) continue;
+      // trash/ is one flat directory carrying a basename and no realm, so the
+      // name alone puts every tenant's document back in the OWNER's trash,
+      // restorable into the owner's realm. That is the crossing attic.putBack
+      // refuses by hand. The record is the only thing that knows which realm
+      // these bytes came out of.
+      //
+      // Reaching it with a record in hand is rare, and deliberately so:
+      // reconcileMeta ran first and inserted a row for every record it could
+      // place, so an entry that still has none is one whose record it skipped on
+      // a path collision. Rare is not never, and the alternative is a realm
+      // crossing, so the lookup stays.
+      const record = byId.get(id) || null;
+      const owner = (record?.owner ?? '') || '';
+      const relPath = record?.path || name.slice(split + 2);
+      if (!record) {
+        // No record, so the realm is genuinely unknowable. Today's answer is the
+        // owner's trash under a bare name, and saying so beats pretending.
+        logger.warn?.(
+          `[makerclay] trash entry ${name} has no durable record, so it comes back in ` +
+          "the owner's trash under its own name.",
+        );
+      }
+      const now = clock.now();
+      // Ask the filesystem, not the filename. A directory has no history folder,
+      // so trashing one writes no record at all, and typing it by name brings a
+      // folder called `notes` back as a file. `move` then skips rewriting its
+      // descendants, their rows keep the old path, and the bytes at the new path
+      // resolve to a provisional node that reads as public.
+      const entry = await statIfExists(path.join(paths.dirs.trash, name));
+      store.insertNode({
+        id,
+        owner,
+        path: relPath,
+        kind: record?.kind || nodes.kindFor(relPath, !!entry?.isDirectory()),
+        private: true,
+        deletedAt: now,
+        seq: store.nextSeq(),
+        createdAt: now,
+        updatedAt: now,
+      });
+      trashed += 1;
+    }
+
+    // A collection's submissions are a folder of JSON on disk and the binding
+    // from slug to document exists nowhere else, so it comes from the record.
+    // The submit token does NOT: it is a credential, so a fresh one is minted
+    // and every form pointing here needs the new one, the same deal share links
+    // get.
+    let collections = 0;
+    for (const record of await readAllMeta()) {
+      if (!record.slug || !store.getNodeById(record.id)) continue;
+      if (store.getCollection(record.id) || store.getCollectionBySlug(record.slug)) continue;
+      store.insertCollection({
+        nodeId: record.id,
+        slug: record.slug,
+        submitToken: mintToken(18),
+        accepting: true,
+        createdAt: clock.now(),
+      });
+      collections += 1;
+    }
+
+    // A realm directory is proof a tenant existed. The password hash is gone
+    // with the database and is not invented: the tenant comes back DISABLED so
+    // their tree keeps its owner and stays unreadable until the box owner resets
+    // it by hand.
+    let tenants = 0;
+    for (const name of await readdirIfExists(paths.dirs.tenants)) {
+      if (name.startsWith('.') || store.getTenant(name)) continue;
+      const now = clock.now();
+      store.insertTenant({
+        username: name,
+        passwordHash: 'disabled:rebuilt-from-disk',
+        createdAt: now,
+        approvedAt: now,
+      });
+      store.updateTenant(name, { disabledAt: now });
+      tenants += 1;
+    }
+
+    const count = store.listAllNodes({ includeDeleted: true }).length;
+    logger.warn?.(
+      `[makerclay] rebuilt the overlay from disk: ${count} node(s), ${trashed} from trash, ` +
+      `${tenants} tenant(s) restored disabled, ${collections} collection(s) with new submit tokens. ` +
+      'Share links, sessions, tenant passwords and record codes were not recoverable.',
+    );
+    return { nodes: count, tenants, collections, trashed, ...reconciled };
+  }
+
+  return { assess, rebuild, reconcileMeta, readAllMeta, markInstalled };
+}