@makerclay/core 1.0.0

package/src/versions/files.js

@@ -0,0 +1,307 @@
+import path from 'upath';
+import {
+  mkdirp,
+  readdirIfExists,
+  statIfExists,
+  readFileText,
+  unlinkIfExists,
+  rename,
+  rmrf,
+  atomicWrite,
+  readFileTextIfExists,
+} from '../util/fsx.js';
+import { documentEtag } from '../spec/wire.js';
+import {
+  VERSION_NAME, compareNewestFirst, publishInto, sortKey,
+} from './naming.js';
+
+// Version history on disk, lifted from hyperclay-local's backup.js and
+// prune-versions.js, re-keyed by node identity instead of path.
+//
+// The driver half: which directory a node's history lives in, listing and
+// reading it back, pruning it, and holding the lock while any of that happens.
+// What a version is CALLED and how it is committed under that name is
+// naming.js, which knows nothing about nodes, locks or config.
+//
+// One behavioral change from the lift: publish() THROWS. createBackup's
+// swallow-and-return-null does not come along, because a save that cannot
+// publish its version must fail closed rather than silently discard the undo.
+
+export function createFilesVersionDriver({ paths, locks, config = {}, clock = Date, logger = console }) {
+  const maxAgeMs = (config.maxAgeDays ?? 60) * 24 * 60 * 60 * 1000;
+  const keepNewest = config.keepNewest ?? 20;
+  const pruneIntervalMs = 60 * 60 * 1000;
+  const lastPruneAt = new Map();
+
+  function dirFor(node) {
+    return paths.versionsDir(node.id, path.basename(node.path));
+  }
+
+  // The versions directory for a node whose slug has drifted (a rename that
+  // never got to move the directory). Identity is the key, so find by suffix.
+  async function findDirById(nodeId) {
+    const suffix = paths.versionsDirPrefix(nodeId);
+    const names = (await readdirIfExists(paths.dirs.versions)).filter((name) => name.endsWith(suffix));
+    if (names.length <= 1) return names[0] ? path.join(paths.dirs.versions, names[0]) : null;
+    // Eight characters of a ULID, so two documents can share a suffix. One hit is
+    // the normal case and is free to trust; more than one has to be settled by the
+    // record inside, which is the authoritative copy of the id.
+    for (const name of names) {
+      const dir = path.join(paths.dirs.versions, name);
+      if ((await readMetaIn(dir))?.id === nodeId) return dir;
+    }
+    return null;
+  }
+
+  async function resolveDir(node, { create = false } = {}) {
+    const preferred = dirFor(node);
+    if (await statIfExists(preferred)) return preferred;
+    const existing = await findDirById(node.id);
+    if (existing) return existing;
+    if (create) {
+      await mkdirp(preferred);
+      return preferred;
+    }
+    return null;
+  }
+
+  async function readMetaIn(dir) {
+    const raw = await readFileTextIfExists(path.join(dir, 'meta.json'));
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+
+  // Deliberately derived from the content rather than from `node.etag`: the
+  // version is published BEFORE the live file is replaced, so the node still
+  // carries the previous save's digest at this point and a record built from it
+  // would lag one save behind forever.
+  function signatureOfContent(content, encoding) {
+    if (encoding !== 'utf8' || typeof content !== 'string') return null;
+    return { etag: documentEtag(content), bytes: Buffer.byteLength(content, 'utf8') };
+  }
+
+  // The durable half of the overlay. Everything in here is either impossible to
+  // recover from the filesystem (the three flags, the collection slug) or
+  // expensive to work out again (which id owns this history). The directory
+  // name carries only the LAST EIGHT characters of the id, which is 40 bits, so
+  // `id` here is what is authoritative after a database loss, not the folder.
+  //
+  // Spread over `current` rather than replacing it: a publish must not drop a
+  // slug it knows nothing about.
+  function recordFor(node, current, signature = null) {
+    return {
+      ...(current || {}),
+      id: node.id,
+      path: node.path,
+      owner: node.owner ?? '',
+      kind: node.kind,
+      private: !!node.private,
+      isolated: node.isolated === undefined ? (current?.isolated ?? null) : node.isolated,
+      signups: !!node.signups,
+      trashed: !!node.deletedAt,
+      // The only fields here that describe the BYTES rather than the overlay,
+      // and the reason is narrow: a row rebuilt from this record has to be able
+      // to find its file again if the file moved while the host was down.
+      // `byDigest` (nodes/scanner.js) needs both halves, the size to filter
+      // candidates for free out of the stats the walk already has, and the etag
+      // to confirm one. Without them a database loss plus a move strands the
+      // history, which is the one thing the journal this replaced did that these
+      // records otherwise would not.
+      //
+      // They go stale on an external edit, because only a publish refreshes
+      // them. That is the same coverage the journal this replaced had, since its
+      // save lines also only ever recorded host writes.
+      etag: signature?.etag ?? current?.etag ?? null,
+      bytes: signature?.bytes ?? current?.bytes ?? null,
+      rev: (current?.rev ?? 0) + 1,
+      updatedAt: clock.now(),
+    };
+  }
+
+  // Lock-free on purpose: its only caller is `publish`, which already holds the
+  // directory lock. Taking it again here would deadlock.
+  async function writeMeta(dir, node, signature = null) {
+    const current = await readMetaIn(dir);
+    await atomicWrite(path.join(dir, 'meta.json'), `${JSON.stringify(recordFor(node, current, signature), null, 2)}\n`);
+  }
+
+  async function entries(dir) {
+    const names = await readdirIfExists(dir);
+    const found = [];
+    for (const name of names) {
+      if (!VERSION_NAME.test(name)) continue;
+      const stat = await statIfExists(path.join(dir, name));
+      if (!stat || !stat.isFile()) continue;
+      found.push({ name, full: path.join(dir, name), mtimeMs: stat.mtimeMs, size: stat.size });
+    }
+    found.sort(compareNewestFirst);
+    return found;
+  }
+
+  async function pruneDir(dir, now = clock.now()) {
+    const found = await entries(dir);
+    if (!found.length) return { kept: 0, deleted: [] };
+
+    const keep = new Set();
+    found.slice(0, keepNewest).forEach((entry) => keep.add(entry.name));
+    for (const entry of found) {
+      if (now - sortKey(entry) <= maxAgeMs) keep.add(entry.name);
+    }
+
+    const deleted = [];
+    for (const entry of found) {
+      if (keep.has(entry.name)) continue;
+      if (await unlinkIfExists(entry.full)) deleted.push(entry.name);
+    }
+    return { kept: keep.size, deleted };
+  }
+
+  function maybePrune(dir) {
+    const now = clock.now();
+    if (now - (lastPruneAt.get(dir) || 0) < pruneIntervalMs) return;
+    lastPruneAt.set(dir, now);
+    pruneDir(dir, now).catch((error) => {
+      logger.error?.('[versions] prune failed (non-fatal):', error?.message || error);
+    });
+  }
+
+  // The ONE place durable overlay state is written from outside a publish. It
+  // takes the SAME lock as publish, which is already a node-id lock: resolveDir
+  // finds the directory by the identity suffix in its name rather than by path,
+  // so it survives renames. Without sharing that lock, a save racing a flag
+  // change overwrites the flag with a stale snapshot, and the host reports a
+  // durability it did not get.
+  //
+  // `create` is off by default so a best-effort path or trash update never
+  // conjures a history folder for a document that has none.
+  async function patchMeta(node, patch = {}, { create = false } = {}) {
+    const dir = await resolveDir(node, { create });
+    if (!dir) return null;
+    return await locks.withLock(`versions:${dir}`, async () => {
+      const current = await readMetaIn(dir);
+      const next = { ...recordFor(node, current), ...patch };
+      await atomicWrite(path.join(dir, 'meta.json'), `${JSON.stringify(next, null, 2)}\n`);
+      return next;
+    });
+  }
+
+  return {
+    name: 'files',
+
+    findDirById,
+
+    // Throws on any failure. A save that cannot publish its version fails closed.
+    async publish(node, content, { encoding = 'utf8', ext = '.html' } = {}) {
+      const dir = (await resolveDir(node, { create: true }));
+      return await locks.withLock(`versions:${dir}`, async () => {
+        const published = await publishInto(dir, ext, content, encoding, new Date(clock.now()));
+        await writeMeta(dir, node, signatureOfContent(content, encoding));
+        maybePrune(dir);
+        return published;
+      });
+    },
+
+    async list(node) {
+      const dir = await resolveDir(node);
+      if (!dir) return [];
+      const found = await entries(dir);
+      return found.map((entry, index) => ({
+        name: entry.name,
+        time: sortKey(entry),
+        seq: index,
+        size: entry.size,
+      }));
+    },
+
+    async read(node, name) {
+      if (!VERSION_NAME.test(String(name || ''))) return null;
+      const dir = await resolveDir(node);
+      if (!dir) return null;
+      const full = path.join(dir, name);
+      if (!(await statIfExists(full))) return null;
+      return await readFileText(full);
+    },
+
+    async meta(node) {
+      const dir = await resolveDir(node);
+      if (!dir) return null;
+      return await readMetaIn(dir);
+    },
+
+    patchMeta,
+
+    // Move an orphaned history onto a live document. The DIRECTORY is renamed
+    // rather than the node re-identified, and that direction is not arbitrary:
+    // node ids are referenced by shares, save tokens and collections, so
+    // changing a live node's id would silently break all three, while a history
+    // directory is referenced by nothing except its own name.
+    async adopt(fromId, node) {
+      const from = await findDirById(fromId);
+      if (!from) return false;
+      const to = dirFor(node);
+      if (from === to) return true;
+      // findDirById, not statIfExists(dirFor(node)): the question is "does this
+      // node already have a history", and dirFor only answers "is there one filed
+      // under the name its CURRENT path implies". A slug that has drifted makes
+      // those different questions, and the wrong one lets a second directory land
+      // with the same id suffix.
+      if (await findDirById(node.id)) return false;
+      await mkdirp(path.dirname(to));
+      await rename(from, to);
+      // The record's digest describes the file this history used to follow, and
+      // that file may still exist somewhere. Carrying it onto a different
+      // document would let a later scan rebind on it. Clear it and let the next
+      // save write the truth.
+      //
+      // `slug` binds a document to a folder of submissions under records/, and it
+      // belongs to the document this history came FROM, not the one it is landing
+      // on. Carrying it over rebinds a stranger's submissions on the next rebuild.
+      await patchMeta(node, { etag: null, bytes: null, slug: null }, { create: true });
+      return true;
+    },
+
+    // The slug is display only, so a rename moves the directory in place and
+    // never touches the identity half of its name.
+    async renameSlug(node, nextPath) {
+      const current = await resolveDir(node);
+      if (!current) return null;
+      const next = paths.versionsDir(node.id, path.basename(nextPath));
+      if (current === next) return current;
+      if (await statIfExists(next)) return current;
+      await rename(current, next);
+      return next;
+    },
+
+    async prune(node) {
+      const dir = await resolveDir(node);
+      if (!dir) return { kept: 0, deleted: [] };
+      return await locks.withLock(`versions:${dir}`, () => pruneDir(dir));
+    },
+
+    async pruneAll() {
+      const names = await readdirIfExists(paths.dirs.versions);
+      let sites = 0;
+      let deleted = 0;
+      for (const name of names) {
+        const dir = path.join(paths.dirs.versions, name);
+        const stat = await statIfExists(dir);
+        if (!stat?.isDirectory()) continue;
+        const result = await locks.withLock(`versions:${dir}`, () => pruneDir(dir));
+        sites += 1;
+        deleted += result.deleted.length;
+      }
+      return { sites, deleted };
+    },
+
+    async purge(node) {
+      const dir = await resolveDir(node);
+      if (!dir) return false;
+      await rmrf(dir);
+      return true;
+    },
+  };
+}

package/src/versions/index.js

@@ -0,0 +1,16 @@
+import { createFilesVersionDriver } from './files.js';
+
+// The versions driver interface: publish / list / read / meta / patchMeta /
+// adopt / renameSlug / findDirById / prune / pruneAll / purge. `files` is the
+// only driver, and the call is direct: a one-entry lookup table read as though
+// a second driver existed somewhere. The git driver, if it ever arrives, adds
+// the branch back here and touches no caller, which was the only thing the
+// table was buying.
+
+export function createVersions(options) {
+  const name = options?.config?.driver || 'files';
+  if (name !== 'files') throw new Error(`Unknown versions driver: ${name}`);
+  return createFilesVersionDriver(options);
+}
+
+export { createFilesVersionDriver };

package/src/versions/naming.js

@@ -0,0 +1,172 @@
+import path from 'upath';
+import fsp from 'node:fs/promises';
+import crypto from 'node:crypto';
+import {
+  mkdirp,
+  readdirIfExists,
+  statIfExists,
+  unlinkIfExists,
+  fsyncDir,
+  flush,
+  rename,
+} from '../util/fsx.js';
+
+// What a version is CALLED, and how one is committed under that name.
+//
+// Split out of files.js because it is the pure half: given a directory and an
+// instant, it decides a filename that sorts strictly after every version already
+// there, and it puts the bytes under that name atomically. It knows nothing
+// about nodes, locks, pruning or config, and it never reads a version back.
+//
+// The two halves are worth keeping apart because the rules here are subtle in a
+// way the driver's are not, and every one of them exists because of a specific
+// way version history can be silently corrupted: a DST fall-back that makes two
+// versions claim the same instant, a clock that rolls backwards, a crash between
+// writing bytes and naming them.
+
+// `YYYY-MM-DD-HH-MM-SS-mmm`, an optional zone (a signed four-digit UTC offset,
+// or the older bare `Z`), and an optional zero-padded collision suffix. The
+// suffix MUST be matched: an unrecognised name is one the pruner refuses to
+// touch, so without it every collision-suffixed version would accumulate.
+export const VERSION_NAME =
+  /^(\d{4})-(\d{2})-(\d{2})-(\d{2})-(\d{2})-(\d{2})-(\d{3})(Z|[+-]\d{4})?(?:-(\d{3}))?\.[A-Za-z0-9]+$/;
+
+const MAX_COLLISION_ATTEMPTS = 1000;
+const LINK_UNSUPPORTED = new Set(['EPERM', 'ENOTSUP', 'ENOSYS']);
+const pad3 = (n) => String(n).padStart(3, '0');
+
+// Local wall time plus the signed UTC offset in force at that moment, e.g.
+// `2026-11-01-01-30-00-431-0400`. Local time is what the user reads in a file
+// browser; the offset is what makes it orderable, because local wall time
+// repeats for one hour on every DST fall-back and the pruner DELETES.
+//
+// Note the sign: getTimezoneOffset() returns POSITIVE minutes for zones BEHIND
+// UTC, so it is negated here. Getting that backwards inverts every ordering.
+export function generateTimestamp(now = new Date()) {
+  const pad = (value, width = 2) => String(value).padStart(width, '0');
+  const offsetMinutes = -now.getTimezoneOffset();
+  const sign = offsetMinutes < 0 ? '-' : '+';
+  const absMinutes = Math.abs(offsetMinutes);
+  const offset = `${sign}${pad(Math.floor(absMinutes / 60))}${pad(absMinutes % 60)}`;
+
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-` +
+    `${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}-` +
+    `${pad(now.getMilliseconds(), 3)}${offset}`;
+}
+
+export function parseVersionTimestamp(filename) {
+  const match = VERSION_NAME.exec(filename);
+  if (!match) return null;
+  const [, year, month, day, hours, minutes, seconds, ms, zone] = match;
+  if (!zone) return null;
+
+  const wallClock = Date.UTC(+year, +month - 1, +day, +hours, +minutes, +seconds, +ms);
+  if (zone === 'Z') return wallClock;
+  const offsetMinutes = (+zone.slice(1, 3) * 60 + +zone.slice(3, 5)) * (zone[0] === '-' ? -1 : 1);
+  return wallClock - offsetMinutes * 60 * 1000;
+}
+
+export function sortKey(entry) {
+  const parsed = parseVersionTimestamp(entry.name);
+  return parsed === null ? entry.mtimeMs : parsed;
+}
+
+function collisionSuffix(filename) {
+  const match = VERSION_NAME.exec(filename);
+  return match && match[9] ? Number(match[9]) : 0;
+}
+
+function versionStamp(filename) {
+  const m = VERSION_NAME.exec(filename);
+  if (!m) return null;
+  return `${m[1]}-${m[2]}-${m[3]}-${m[4]}-${m[5]}-${m[6]}-${m[7]}${m[8] || ''}`;
+}
+
+export function compareNewestFirst(a, b) {
+  return (sortKey(b) - sortKey(a)) || (collisionSuffix(b.name) - collisionSuffix(a.name));
+}
+
+// Choose a name that sorts strictly AFTER every committed version. Normally the
+// fresh clock instant already does; if the wall clock has rolled backwards to
+// at-or-before the newest committed instant, reuse that instant's stamp and take
+// the next collision suffix so the new file still ranks first.
+async function planVersionName(dir, candidateDate) {
+  let stamp = generateTimestamp(candidateDate);
+  let suffix = 0;
+  let reuseInstant = null;
+
+  const names = await readdirIfExists(dir);
+  const committed = [];
+  for (const name of names) {
+    if (!VERSION_NAME.test(name)) continue;
+    const stat = await statIfExists(path.join(dir, name));
+    if (stat) committed.push({ name, mtimeMs: stat.mtimeMs });
+  }
+
+  if (committed.length) {
+    committed.sort(compareNewestFirst);
+    const newest = committed[0];
+    const newestInstant = sortKey(newest);
+    if (candidateDate.getTime() <= newestInstant) {
+      stamp = versionStamp(newest.name);
+      suffix = collisionSuffix(newest.name) + 1;
+      reuseInstant = newestInstant;
+    }
+  }
+
+  return { stamp, suffix, reuseInstant };
+}
+
+// Publish one version atomically and monotonically.
+//
+// Never a partial file: the content is written to a dot-prefixed temp in the
+// same directory, fsynced, chmod'd and closed FIRST. The dot prefix can never
+// match VERSION_NAME, so the pruner and the listing ignore whatever a crash
+// leaves behind. The final name is then produced by fs.link (atomic, no-replace),
+// or by rename on a filesystem without hard links.
+export async function publishInto(dir, ext, content, encoding, now) {
+  await mkdirp(dir);
+  const tempPath = path.join(dir, `.makerclay-ver-${crypto.randomBytes(8).toString('hex')}.tmp`);
+  try {
+    const handle = await fsp.open(tempPath, 'wx', 0o644);
+    try {
+      await handle.writeFile(content, encoding === null ? undefined : encoding);
+      await flush(handle);
+      await handle.chmod(0o644);
+    } finally {
+      await handle.close();
+    }
+
+    const plan = await planVersionName(dir, now);
+    let { stamp, reuseInstant } = plan;
+    let suffix = plan.suffix;
+
+    for (;;) {
+      if (suffix >= MAX_COLLISION_ATTEMPTS) {
+        if (reuseInstant == null) {
+          throw new Error(`No free version name for ${stamp}${ext} after ${MAX_COLLISION_ATTEMPTS} attempts`);
+        }
+        reuseInstant += 1;
+        stamp = generateTimestamp(new Date(reuseInstant));
+        suffix = 0;
+      }
+
+      const filename = suffix === 0 ? `${stamp}${ext}` : `${stamp}-${pad3(suffix)}${ext}`;
+      const full = path.join(dir, filename);
+      try {
+        await fsp.link(tempPath, full);
+        return { name: filename, full };
+      } catch (error) {
+        if (error.code === 'EEXIST') { suffix += 1; continue; }
+        if (LINK_UNSUPPORTED.has(error.code)) {
+          await rename(tempPath, full);
+          return { name: filename, full };
+        }
+        throw error;
+      }
+    }
+  } finally {
+    await unlinkIfExists(tempPath).catch(() => {});
+    await fsyncDir(dir);
+  }
+}

package/src/versions/routes.js

@@ -0,0 +1,91 @@
+import path from 'upath';
+import { can } from '../auth/can.js';
+import { jsonError } from '../json-errors.js';
+import { documentUrlHeader } from '../spec/wire.js';
+import { VERSION_NAME } from './naming.js';
+import { applySecurityHeaders } from '../tenants/isolation.js';
+import { wrap } from '../util/express.js';
+
+// The versions HTTP surface, in htmlclay's shapes. A document is addressed
+// either by the Document-URL header (cookie-authenticated) or by a save token in
+// the path (isolated documents and share links), which is the same split the
+// save lane uses.
+
+export function mountVersionRoutes({
+  router, versions, replace,
+  resolveTarget, resolveSaveToken, tryResolveRead, gateCtx, track, isolationFor,
+}) {
+  async function targetFromRequest(req, action) {
+    if (req.params.token) {
+      const grant = await resolveSaveToken(req.params.token);
+      if (!grant) return null;
+      const actor = { ...req.actor, grants: { ...req.actor.grants, saveToken: grant } };
+      if (!can(actor, action, grant.node, gateCtx)) return null;
+      const real = await tryResolveRead(grant.node.owner, grant.node.path);
+      if (!real) return null;
+      return { actor, node: grant.node, owner: grant.node.owner, real };
+    }
+    const href = documentUrlHeader(req);
+    if (!href) return null;
+    return await resolveTarget(req.actor, href, action);
+  }
+
+  async function listHandler(req, res) {
+    const found = await targetFromRequest(req, 'version-read');
+    if (!found) return jsonError(res, 'not-found', 'Not found');
+    const list = await versions.list(found.node);
+    return res.json({ ok: true, name: path.basename(found.node.path), versions: list });
+  }
+
+  async function readHandler(req, res) {
+    const name = req.params.name;
+    if (!VERSION_NAME.test(String(name || ''))) return jsonError(res, 'not-found', 'Not found');
+    const found = await targetFromRequest(req, 'version-read');
+    if (!found) return jsonError(res, 'not-found', 'Not found');
+    const body = await versions.read(found.node, name);
+    if (body == null) return jsonError(res, 'not-found', 'Not found');
+    // A version is the same document at an earlier moment, so it gets the same
+    // posture. Without this a tenant saves a version full of script and opens it
+    // through their own save token at the host's real origin.
+    applySecurityHeaders(res, isolationFor ? isolationFor(found.node) : false);
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.setHeader('Cache-Control', 'no-store');
+    return res.send(body);
+  }
+
+  // Backs the current document up FIRST and hard-fails if it cannot: a restore
+  // that loses the state it replaced is worse than a restore that refuses.
+  // The restored bytes have their identity stripped rather than adopted, so a
+  // restore never re-anchors the document onto an older identity.
+  async function restoreHandler(req, res) {
+    const name = req.params.name;
+    if (!VERSION_NAME.test(String(name || ''))) return jsonError(res, 'not-found', 'Not found');
+    const found = await targetFromRequest(req, 'version-write');
+    if (!found) return jsonError(res, 'not-found', 'Not found');
+
+    const body = await versions.read(found.node, name);
+    if (body == null) return jsonError(res, 'not-found', 'Not found');
+
+    const result = await replace({
+      actor: found.actor || req.actor,
+      owner: found.node.owner,
+      relPath: found.node.path,
+      bytes: body,
+      trigger: 'user',
+      source: 'restore',
+      ctx: gateCtx,
+      backupCurrent: true,
+    });
+    res.json({ ok: true, msg: `Restored ${name}`, msgType: 'success', etag: result.etag });
+    track(result.derived());
+    return undefined;
+  }
+
+
+  router.get('/versions', wrap(listHandler));
+  router.get('/versions/:token', wrap(listHandler));
+  router.get('/version/:name', wrap(readHandler));
+  router.get('/version/:token/:name', wrap(readHandler));
+  router.post('/restore/:name', wrap(restoreHandler));
+  router.post('/restore/:token/:name', wrap(restoreHandler));
+}

package/src/wire-compat.js

@@ -0,0 +1,61 @@
+// Every legacy shim in one file, each line naming the deployed client that needs
+// it.
+//
+// This file is documentation, not a module: the leniency it describes lives in
+// spec/wire.js, documents/replace.js and the route table, and it is PERMANENTLY
+// on. There is no shims-off mode and, for the live-sync aliases below, there
+// must never be one.
+//
+// The plan's §11.1 did ask for two CI runs, shims on and shims off, and CI never
+// did that: the flag meant to select it (`wire.legacyRoutes`) was read by
+// nothing, so both "runs" were the same default configuration. That requirement
+// is now obsolete rather than unmet. It was written when this file was a module
+// with a real switch; the shims it describes were folded into the code they
+// belong to, and the live-sync aliases below are permanent by decision, so there
+// is no second configuration left to run.
+//
+// What holds instead, and is enforced by conformance.test.js: none of this is
+// allowed to cost conformance while it is on, which is the only state it has.
+
+// clayjs 0.2.0 sends `Page-URL` and never `Document-URL`. clayjs 0.3.0 sends
+// both, and htmlclay reads `Page-URL` on its live-sync lane.
+// Handled in spec/wire.js documentUrlHeader(): both spellings are read and
+// `Document-URL` wins.
+
+// clayjs 0.2.0 read the save token only from `htmlclaytoken`; 0.3.0 prefers the
+// spec's `savetoken`, which is the one this host injects. `htmlclaytoken` is
+// still STRIPPED on the way in (documents/replace.js), because htmlclay injects
+// that spelling on its own host and a copy of one of its documents must not
+// arrive here carrying a stale credential that clayjs would still read.
+
+// clayjs 0.2.0 reads only `msg` and `msgType` off a save response; the spec adds
+// two OPTIONAL fields, `etag` (the version stamp of what was stored) and `code`
+// (a machine-readable *failure* reason). So a success answers `msg`, `msgType`
+// and `etag`, and `code` appears only on errors, which is what json-errors.js
+// does. htmlclay's own save lane answers with `msg` and `msgType` only.
+//
+// There was a `SAVE_RESPONSE_KEYS` constant here listing all four as though a
+// success carried `code`. Nothing imported it and no response was ever built
+// from it, so it recorded a shape the host does not emit and the spec does not
+// ask for.
+
+// clayjs 0.2.0's live-sync plugin posted to `/_/live-sync/save` and subscribed
+// at `/_/live-sync/stream`, both of which predate the spec's `/_/sync`. Those
+// aliases were removed on 2026-08-21 and RESTORED the same day, permanently.
+// The premise for removing them was that nothing outside our own clients speaks
+// them. That is false in two ways: a saved document is a frozen client, and the
+// Collection dashboard opens `/_/live-sync/stream` from inline page script, so
+// every dashboard ever minted names that path and no library update can reach
+// it; and hyperclayjs, a second shipped client, hardcodes both. This is the one
+// place a deleted route cannot be fixed by shipping a new client, so it is the
+// documented exception to the no-dual-accept rule. The host serves POST and GET
+// on `/_/sync` and on both legacy paths. Leniency also covers the query
+// parameter: the stream reads `document-url` first and still accepts the old
+// `page-url` spelling.
+
+// clayjs 0.2.0 sent a JSON envelope `{content, snapshotHtml, userDriven}` to
+// `/_/save`, and 0.3.0 sent it to any host that declared
+// `clay-save-transport="desktop-json-v1"`. Nothing sends it now: the document is
+// the body, the provenance bit is `Save-Trigger`, and the unstripped snapshot
+// goes to the §10 relay, which is the only route allowed to carry one. Refusing
+// a JSON save with 415 is spec/wire.js readSaveBody(), a rule rather than a shim.