npm - @makerclay/core - Versions diffs - 1.0.0 - Mend

@makerclay/core 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (91) hide show

package/LICENSE +221 -0
package/README.md +82 -0
package/package.json +52 -0
package/src/admin/listing.js +149 -0
package/src/admin/routes.js +362 -0
package/src/attic.js +168 -0
package/src/auth/can.js +79 -0
package/src/auth/csrf.js +74 -0
package/src/auth/none.js +24 -0
package/src/auth/password.js +281 -0
package/src/auth/passwords.js +79 -0
package/src/auth/rate-limit.js +66 -0
package/src/auth/sessions.js +86 -0
package/src/auth/token-lanes.js +72 -0
package/src/boot.js +120 -0
package/src/client.js +99 -0
package/src/collections/index.js +397 -0
package/src/collections/routes.js +166 -0
package/src/create-host.js +351 -0
package/src/derived/data-extractor.js +22 -0
package/src/derived/index.js +121 -0
package/src/documents/format-html.js +313 -0
package/src/documents/replace.js +257 -0
package/src/documents/root-attrs.js +171 -0
package/src/documents/serve.js +137 -0
package/src/documents/stale.js +20 -0
package/src/index.js +12 -0
package/src/inspect.js +136 -0
package/src/json-errors.js +59 -0
package/src/livesync.js +75 -0
package/src/nodes/identity.js +14 -0
package/src/nodes/names.js +57 -0
package/src/nodes/ops.js +613 -0
package/src/nodes/scanner.js +321 -0
package/src/nodes/store.js +111 -0
package/src/pages.js +166 -0
package/src/paths.js +302 -0
package/src/recovery/overlay.js +327 -0
package/src/recovery/replay.js +236 -0
package/src/recovery-ui.js +185 -0
package/src/recovery.js +30 -0
package/src/requests.js +73 -0
package/src/routes/meta.js +62 -0
package/src/routes/read.js +105 -0
package/src/routes/save.js +102 -0
package/src/routes/sync.js +118 -0
package/src/routes/upload.js +128 -0
package/src/share/index.js +207 -0
package/src/share/save-tokens.js +65 -0
package/src/spec/codes.js +42 -0
package/src/spec/meta.js +52 -0
package/src/spec/wire.js +115 -0
package/src/store/index.js +29 -0
package/src/store/migrations/001-init.sql +114 -0
package/src/store/sqlite.js +540 -0
package/src/templates.js +50 -0
package/src/tenants/index.js +355 -0
package/src/tenants/isolation.js +91 -0
package/src/tenants/routes.js +131 -0
package/src/ui.js +95 -0
package/src/util/cookies.js +26 -0
package/src/util/express.js +8 -0
package/src/util/fsx.js +205 -0
package/src/util/id.js +37 -0
package/src/util/lockfile.js +52 -0
package/src/util/locks.js +35 -0
package/src/util/multipart.js +33 -0
package/src/versions/files.js +307 -0
package/src/versions/index.js +16 -0
package/src/versions/naming.js +172 -0
package/src/versions/routes.js +91 -0
package/src/wire-compat.js +61 -0
package/ui/app.css +164 -0
package/ui/attic.html +198 -0
package/ui/dashboard.html +456 -0
package/ui/editor.html +156 -0
package/ui/error.html +18 -0
package/ui/login.html +58 -0
package/ui/records.html +173 -0
package/ui/recovery.html +152 -0
package/ui/setup.html +61 -0
package/ui/share-qr.html +44 -0
package/ui/templates/blank.html +16 -0
package/ui/templates/devlog.html +71 -0
package/ui/templates/hackable-dashboard.html +145 -0
package/ui/templates/kanban.html +85 -0
package/ui/templates/landing.html +108 -0
package/ui/templates/writer.html +50 -0
package/ui/tenants.html +172 -0
package/ui/trash.html +134 -0
package/ui/versions.html +114 -0

package/src/documents/format-html.js ADDED Viewed

@@ -0,0 +1,313 @@
+// Lifted from hyperclay-local (MIT): src/main/format-html.js.
+// Spec §4 opt-in formatting, with the abuse bounds that keep js-beautify from
+// turning a hostile document into a memory bomb.
+import beautify from 'js-beautify';
+const beautifyOptions = {
+  indent_size: 2,
+  indent_char: ' ',
+  wrap_attributes: 'force-expand-multiline',
+  unformatted: ['svg', 'path', 'rect', 'circle', 'script', 'style', 'link', 'meta']
+};
+// Beautify is superlinear in nesting depth and amplifies output through indentation
+// (force-expand-multiline puts each attribute on its own line), so its cost is bounded in
+// three places, each failing safe to storing the bytes as sent: deepest nesting and
+// projected output size are checked BEFORE formatting (the CPU and the allocation are both
+// spent during beautify and cannot be measured afterwards), actual growth is checked after,
+// and beautify itself is wrapped so even a throw stores the input unchanged. A heuristic
+// miss only ever means "not reformatted", never a wrong document.
+const MAX_FORMAT_DEPTH = 256;
+const MAX_PROJECTED_BYTES = 32 * 1024 * 1024;
+const MAX_GROWTH_RATIO = 3;
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr'
+]);
+const RAW_TEXT_ELEMENTS = new Set(['script', 'style']);
+// Formatting is opt-in per document (spec §4): reformat only when the ROOT <html> element
+// carries formathtml="true", read by value. This is a small linear scan of the document
+// prefix and the root start-tag (never a whole-document regex) so it stays anchored to the
+// real root, matches how a browser parses the tag (quotes only delimit in value position,
+// only ASCII whitespace separates attributes, comments end at --> or --!>), and cannot
+// backtrack on hostile input. Anything but the exact literal value "true" — any other value,
+// no attribute, the attribute on a non-root element, an entity-encoded value, or a root tag
+// that never closes — stores the bytes exactly as sent.
+function isWs(c) {
+  return c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f';
+}
+function commentEnd(str, from) {
+  if (str[from] === '>') return from + 1;                          // <!-->
+  if (str[from] === '-' && str[from + 1] === '>') return from + 2; // <!--->
+  const len = str.length;
+  for (let k = from; k < len; k++) {
+    if (str[k] === '-' && str[k + 1] === '-') {
+      let e = k + 2;
+      if (str[e] === '!') e++;                                     // comment-end-bang: --!>
+      if (str[e] === '>') return e + 1;
+    }
+  }
+  return -1;
+}
+// Scan the document prologue and the root start-tag once, and report what the root is. Returns
+// null when the bytes carry no complete root <html> start-tag: junk before the root, a root that
+// is not <html>, or a start-tag that never closes with '>'. That last case is a truncated
+// document — a real parser would synthesize an implied <html> root, but the bytes on the wire are
+// half a tag, so neither caller should trust it. Two callers ask two questions of this one scan,
+// so they can never disagree about what the document's root is.
+function scanRootHtmlTag(str) {
+  const len = str.length;
+  let i = str.charCodeAt(0) === 0xFEFF ? 1 : 0;
+  // Skip whitespace, comments, doctype, and processing instructions before the root.
+  while (i < len) {
+    const c = str[i];
+    if (isWs(c)) { i++; continue; }
+    if (c !== '<') return null;
+    if (str[i + 1] === '!' && str[i + 2] === '-' && str[i + 3] === '-') {
+      const end = commentEnd(str, i + 4);
+      if (end === -1) return null;
+      i = end;
+      continue;
+    }
+    if (str[i + 1] === '!' || str[i + 1] === '?') {
+      const end = str.indexOf('>', i);
+      if (end === -1) return null;
+      i = end + 1;
+      continue;
+    }
+    break;
+  }
+  // Require the root <html> start-tag.
+  if (str.substr(i, 5).toLowerCase() !== '<html') return null;
+  const boundary = str[i + 5];
+  if (boundary === undefined || !(isWs(boundary) || boundary === '>' || boundary === '/')) return null;
+  i += 5;
+  // Parse attributes, but only trust the result once the tag actually closes with '>'.
+  // An unterminated tag (EOF, or a quoted value with no closing quote) is dropped whole by
+  // an HTML parser, so it carries no root attribute: fail safe to "not opt-in".
+  let optIn = false;
+  let seen = false;
+  while (i < len) {
+    let c = str[i];
+    if (c === '>') return { optIn };
+    if (isWs(c) || c === '/') { i++; continue; }
+    const nameStart = i;
+    while (i < len) {
+      c = str[i];
+      if (isWs(c) || c === '=' || c === '>' || c === '/') break;
+      i++;
+    }
+    if (i === nameStart) {                 // sitting on '=' with no name: it begins the name
+      i++;
+      while (i < len) {
+        c = str[i];
+        if (isWs(c) || c === '=' || c === '>' || c === '/') break;
+        i++;
+      }
+    }
+    const name = str.slice(nameStart, i).toLowerCase();
+    while (i < len && isWs(str[i])) i++;
+    let value = '';
+    if (str[i] === '=') {
+      i++;
+      while (i < len && isWs(str[i])) i++;
+      c = str[i];
+      if (c === '"' || c === "'") {
+        const close = str.indexOf(c, i + 1);
+        if (close === -1) return null;
+        value = str.slice(i + 1, close);
+        i = close + 1;
+      } else {
+        const valueStart = i;
+        while (i < len) {
+          c = str[i];
+          if (isWs(c) || c === '>') break;
+          i++;
+        }
+        value = str.slice(valueStart, i);
+      }
+    }
+    if (name === 'formathtml' && !seen) {  // duplicate attributes: first occurrence wins
+      seen = true;
+      optIn = value === 'true';
+    }
+  }
+  return null;
+}
+function formatOptIn(str) {
+  const root = scanRootHtmlTag(str);
+  return root !== null && root.optIn;
+}
+// Spec §4 obliges a host to refuse a save body that is not a complete HTML document with a
+// top-level <html> element. It reuses the scan above rather than adding a second tokenizer: that
+// one is fuzz-verified against a real parser, and a second one would drift from it.
+function hasHtmlRoot(str) {
+  return typeof str === 'string' && scanRootHtmlTag(str) !== null;
+}
+// Find the '>' that ends a start tag, skipping quoted attribute values, and count the
+// attributes on the way. force-expand-multiline puts each attribute on its own indented
+// line once a tag carries two or more, so attribute count drives the formatted size as much
+// as nesting depth does: a shallow document packed with many-attribute tags can still make
+// beautify allocate hundreds of MB. Returns { end, attrs }; end is -1 for an unterminated tag.
+function scanStartTag(str, from) {
+  const len = str.length;
+  let attrs = 0;
+  let j = from;
+  while (j < len) {
+    while (j < len && (isWs(str[j]) || str[j] === '/')) j++;
+    if (j >= len) return { end: -1, attrs };
+    if (str[j] === '>') return { end: j, attrs };
+    attrs++;
+    while (j < len && !isWs(str[j]) && str[j] !== '=' && str[j] !== '>' && str[j] !== '/') j++;
+    while (j < len && isWs(str[j])) j++;
+    if (str[j] === '=') {
+      j++;
+      while (j < len && isWs(str[j])) j++;
+      const c = str[j];
+      if (c === '"' || c === "'") {
+        const close = str.indexOf(c, j + 1);
+        if (close === -1) return { end: -1, attrs };
+        j = close + 1;
+      } else {
+        while (j < len && !isWs(str[j]) && str[j] !== '>') j++;
+      }
+    }
+  }
+  return { end: -1, attrs };
+}
+function rawTextEnd(str, from, name) {
+  const len = str.length;
+  for (let k = from; k < len; k++) {
+    if (str[k] !== '<' || str[k + 1] !== '/') continue;
+    let m = 0;
+    while (m < name.length && str[k + 2 + m] !== undefined &&
+           str[k + 2 + m].toLowerCase() === name[m]) m++;
+    if (m === name.length) return k;
+  }
+  return -1;
+}
+// One linear pass returning how expensive beautifying this document would be: the deepest
+// element nesting, and an over-estimate of the formatted output size (input plus the
+// indentation and newlines beautify inserts: one line per tag, plus one indented line per
+// attribute once a tag carries two or more). Bails out early the moment the projected size
+// alone is already decisive, so a size bomb is refused in a few ms without finishing the scan.
+function measureFormatCost(str) {
+  const len = str.length;
+  const indent = beautifyOptions.indent_size;
+  let depth = 0;
+  let maxDepth = 0;
+  let added = 0;
+  let i = 0;
+  while (i < len) {
+    if (str[i] !== '<') {
+      // beautify re-indents each line of a formatted text node by depth*indent spaces, so a
+      // newline that costs 1 input byte costs depth*indent output bytes. Charge it, or a deeply
+      // nested newline-heavy text node slips the size gate and makes beautify allocate/crash.
+      if (str[i] === '\n' || (str[i] === '\r' && str[i + 1] !== '\n')) {
+        added += depth * indent;
+        if (len + added > MAX_PROJECTED_BYTES) return { maxDepth, projectedBytes: len + added };
+      }
+      i++;
+      continue;
+    }
+    if (str[i + 1] === '!' && str[i + 2] === '-' && str[i + 3] === '-') {
+      const end = commentEnd(str, i + 4);
+      if (end === -1) break;
+      i = end;
+      continue;
+    }
+    if (str[i + 1] === '!' || str[i + 1] === '?') {
+      const end = str.indexOf('>', i);
+      if (end === -1) break;
+      i = end + 1;
+      continue;
+    }
+    const closing = str[i + 1] === '/';
+    let j = i + (closing ? 2 : 1);
+    const nameStart = j;
+    while (j < len && !isWs(str[j]) && str[j] !== '>' && str[j] !== '/') j++;
+    const name = str.slice(nameStart, j).toLowerCase();
+    if (name === '') { i++; continue; }
+    if (closing) {
+      if (depth > 0) depth--;
+      added += depth * indent + 1;
+      i = str.indexOf('>', j);
+      if (i === -1) break;
+      i++;
+      continue;
+    }
+    const tag = scanStartTag(str, j);
+    if (tag.end === -1) break;
+    const end = tag.end;
+    // the tag's own line, plus force-expand's one indented line per attribute once >= 2
+    added += depth * indent + 1;
+    if (tag.attrs >= 2) {
+      added += tag.attrs * ((depth + 1) * indent + 6) + (depth * indent + 1);
+    }
+    if (len + added > MAX_PROJECTED_BYTES) {
+      return { maxDepth: Math.max(maxDepth, depth), projectedBytes: len + added };
+    }
+    const selfClosed = str[end - 1] === '/';
+    if (!VOID_ELEMENTS.has(name) && !selfClosed) {
+      depth++;
+      if (depth > maxDepth) {
+        maxDepth = depth;
+        if (maxDepth > MAX_FORMAT_DEPTH) return { maxDepth, projectedBytes: len + added };
+      }
+    }
+    if (RAW_TEXT_ELEMENTS.has(name) && !selfClosed) {
+      const raw = rawTextEnd(str, end + 1, name);
+      if (raw === -1) break;
+      i = raw;
+      continue;
+    }
+    i = end + 1;
+  }
+  return { maxDepth, projectedBytes: len + added };
+}
+// Returns { output, declined }. declined is null when the document was reformatted or was
+// never opted in; otherwise it names why a formatted result was refused and the input bytes
+// were stored unchanged: 'depth' / 'size' / 'error' are pathological (would exhaust CPU or
+// memory, or crash the formatter), 'growth' merely grew past the ratio cap. The gates run
+// only after formatOptIn, so a non-null declined always means "opted in but refused".
+function formatHtmlDetailed(str) {
+  if (!formatOptIn(str)) return { output: str, declined: null };
+  const cost = measureFormatCost(str);
+  if (cost.maxDepth > MAX_FORMAT_DEPTH) return { output: str, declined: 'depth' };
+  if (cost.projectedBytes > MAX_PROJECTED_BYTES) return { output: str, declined: 'size' };
+  let formatted;
+  try {
+    formatted = beautify.html(str, beautifyOptions).replace(/(\r\n|\r|\n){3,}/g, '\n\n');
+  } catch {
+    return { output: str, declined: 'error' };
+  }
+  if (formatted.length > str.length * MAX_GROWTH_RATIO) return { output: str, declined: 'growth' };
+  return { output: formatted, declined: null };
+}
+function formatHtml(str) {
+  return formatHtmlDetailed(str).output;
+}
+export { formatHtml, formatHtmlDetailed, hasHtmlRoot, formatOptIn };

package/src/documents/replace.js ADDED Viewed

@@ -0,0 +1,257 @@
+import { can } from '../auth/can.js';
+import { documentEtag, ifMatchSatisfied } from '../spec/wire.js';
+import { formatHtmlDetailed, hasHtmlRoot } from './format-html.js';
+import { stripRootAttrs } from './root-attrs.js';
+import { detectDrift, DRIFT_MESSAGE } from './stale.js';
+import { HostError } from '../spec/codes.js';
+import { atomicWrite, readFileTextIfExists, statInfo } from '../util/fsx.js';
+// THE MUTATION KERNEL.
+//
+// Every write lane calls this one function: browser save, editor save, restore,
+// template application, data-loss revert, tenant instance creation, future sync.
+// No route, CLI command or internal feature writes a managed file directly.
+//
+// The step order below is load-bearing, not stylistic:
+//   - the etag is computed from the bytes on DISK, never from the store, so a
+//     file edited in a terminal cannot be silently overwritten on a stale column;
+//   - If-Match is answered before anything is written, and drift detection only
+//     runs when the client sent no If-Match, so the two protections layer rather
+//     than duplicate;
+//   - the version is published BEFORE the live file is replaced, so a crash
+//     between them costs the newest save and never the previous document;
+//   - the rename in step 11 is the durable commit point: everything after it is
+//     bookkeeping, and everything after step 12 is best-effort, because a false
+//     error reported after the file landed provokes a retry against the caller's
+//     own successful write.
+// Serve-time machinery, never a document's own bytes. `savetoken` is the one this
+// host injects; `htmlclaytoken` arrives only on a document that came from
+// htmlclay, and clayjs reads both, so a stale one left in a file would hand out a
+// dead credential.
+export const EPHEMERAL_ATTRS = ['savetoken', 'htmlclaytoken'];
+export function createReplace({
+  paths, nodes, versions, locks, events, config, clock, logger = console, derived = null,
+}) {
+  const capabilities = config.capabilities || {};
+  const limits = config.limits || {};
+  async function replace({
+    actor,
+    owner = '',
+    relPath,
+    bytes,
+    ifMatch = null,
+    trigger = 'auto',
+    snapshot = null,
+    senderId = null,
+    source = 'save',
+    ctx = {},
+    backupCurrent = false,
+  }) {
+    // 1. Authorize write for that exact node.
+    const node = nodes.resolve(owner, relPath);
+    if (!can(actor, 'write', node, ctx)) {
+      throw new HostError('forbidden', 'You do not have permission to save this document.');
+    }
+    // These two run 3-then-2 on purpose, and the numbers are the sequence's, not
+    // this file's: the lock in step 2 is keyed on the resolved path, so step 3
+    // has to produce that path before step 2 can take it. Renumbering them to
+    // code order would hide the one thing worth knowing here.
+    // 3. Open the current file through paths.js. Never rebuild a raw path from
+    //    the Document-URL header.
+    const filePath = await paths.resolveWrite(owner, relPath);
+    // 2. Acquire the node's canonical path lock, wrapping the ENTIRE
+    //    read-modify-write region. Serializing only the write would still let two
+    //    saves read the same stale base.
+    return await locks.withLock(filePath, async () => {
+      // Everything above ran outside this lock, so a move can have landed in
+      // between: the file is somewhere else now and the row went with it. Writing
+      // here anyway lands bytes at a path this save no longer owns, and because
+      // the row moved, the new file has no row at all, which means it is public.
+      //
+      // Checked against the row that was authorized, not against the path. A
+      // first save to a path with no row authorizes a provisional node and is the
+      // common case, so "a row appeared here" is a concurrent first save to the
+      // same new path: materialize resolves it onto that same row at this same
+      // path, nothing is left rowless, and last-write-wins still applies.
+      const holder = nodes.get(owner, relPath);
+      if (!node.provisional && holder?.id !== node.id) {
+        throw new HostError('conflict', 'That document moved while this save was in flight. Reload and try again.');
+      }
+      // 4. Read stored bytes; compute the etag from THOSE bytes.
+      const storedBytes = await readFileTextIfExists(filePath);
+      const storedEtag = storedBytes == null ? null : documentEtag(storedBytes);
+      // 5. Apply If-Match. Mismatch: 412, nothing written.
+      let driftWarning = false;
+      if (ifMatch != null && capabilities.conditional !== false) {
+        if (!ifMatchSatisfied(ifMatch, storedBytes)) {
+          throw new HostError('conflict', 'This document changed since you loaded it.');
+        }
+      } else {
+        // 6. No If-Match: whole-file drift detection.
+        //
+        // Drift means "the bytes on disk are not bytes this host wrote", so the
+        // baseline is the kernel's own last write. It used to be `served_etag`,
+        // which is a single node-wide value overwritten by every reader, so any
+        // second tab merely LOADING a terminal edit erased the first tab's
+        // protection against clobbering it.
+        //
+        // This deliberately does not try to catch tab-versus-tab staleness. That is
+        // what `If-Match` is for, and losing it costs nothing permanent: whoever
+        // saves second publishes the first one's bytes as a version on the way
+        // past. An external edit clobbered with no rescue version is the only case
+        // where bytes exist nowhere afterwards, and it is the case this now covers
+        // for every tab regardless of who loaded when.
+        driftWarning = detectDrift({ storedBytes, lastKnownEtag: holder?.etag ?? null }) === 'drift';
+      }
+      // 7. Validate.
+      if (typeof bytes !== 'string') {
+        throw new HostError('invalid-document', 'Expected the document as text.');
+      }
+      const size = Buffer.byteLength(bytes, 'utf8');
+      if (limits.saveBytes && size > limits.saveBytes) {
+        throw new HostError('too-large', `Document is larger than the ${limits.saveBytes}-byte limit.`);
+      }
+      if (!hasHtmlRoot(bytes)) {
+        throw new HostError('invalid-document', 'Not a complete HTML document with a top-level <html> element.');
+      }
+      let next = stripRootAttrs(bytes, EPHEMERAL_ATTRS);
+      // 8. Format only when the host advertises `format` AND the root carries
+      //    exactly formathtml="true".
+      if (capabilities.format !== false) {
+        const formatted = formatHtmlDetailed(next);
+        if (formatted.declined) {
+          logger.warn?.(`[makerclay] declined to format ${relPath}: ${formatted.declined}`);
+        }
+        next = formatted.output;
+      }
+      const versionNode = await ensureNodeRow({ owner, relPath, node });
+      const nextEtag = documentEtag(next);
+      // The size of what LANDS, not of what was sent. `size` above is the
+      // client's bytes, which is the right number to check a limit against and
+      // the wrong one to store: the ephemeral attributes, the edit-mode shim and
+      // formatting all change the length before the write. Storing the submitted
+      // number leaves the row's size disagreeing with its own file, and byDigest
+      // filters candidates on size before it computes a digest, so the right file
+      // is discarded before it is ever read.
+      const storedSize = Buffer.byteLength(next, 'utf8');
+      // 9. Dedupe: identical bytes return the current etag, no version, no event.
+      if (storedBytes != null && nextEtag === storedEtag) {
+        // Nothing was written, but this may be the row's first sight of the
+        // file, and a row with no signature cannot follow a later rename.
+        const settled = await nodes.update(versionNode, {
+          ...(versionNode.ino == null ? await signatureOf(filePath) : {}),
+          // The dedupe branch is the one place the host is looking directly at
+          // ground truth: these bytes and the bytes on disk are the same bytes. A
+          // row that walks away from here still describing an earlier kernel write
+          // is describing a document that exists nowhere, and byDigest is built on
+          // that pair.
+          observedEtag: nextEtag,
+          bytes: storedSize,
+        });
+        return {
+          node: settled,
+          etag: nextEtag,
+          changed: false,
+          msg: 'Saved',
+          msgType: 'success',
+          derived: async () => {},
+        };
+      }
+      // 10. Publish the version. publishVersion throws: a save that cannot
+      //     publish its undo fails closed. Seed the pre-host state when history
+      //     is empty, and rescue drifted bytes before they are clobbered.
+      if (storedBytes != null) {
+        const history = await versions.list(versionNode);
+        if (history.length === 0 || driftWarning || backupCurrent) {
+          await versions.publish(versionNode, storedBytes);
+        }
+      }
+      await versions.publish(versionNode, next);
+      // 11. Atomic replace of the live file + fsync of its directory. This
+      //     rename is the durable commit point.
+      await atomicWrite(filePath, next);
+      // 12. One store transaction: refresh etag/bytes/mtime, bump seq.
+      const saved = await touchNode({
+        owner, relPath, node: versionNode, etag: nextEtag, size: storedSize, filePath,
+      });
+      const result = {
+        node: saved,
+        etag: nextEtag,
+        changed: true,
+        msg: driftWarning ? DRIFT_MESSAGE : 'Saved',
+        msgType: driftWarning ? 'warning' : 'success',
+      };
+      // 14. After the response: derived work, best-effort, never converted into
+      //     an HTTP failure.
+      result.derived = async () => {
+        events.emit('node-saved', { node: saved, etag: nextEtag, trigger, source, senderId });
+        if (!derived) return;
+        try {
+          await derived.onSaved({
+            node: saved, html: next, previousHtml: storedBytes, snapshot, senderId, trigger,
+            sourcePath: filePath,
+          });
+        } catch (error) {
+          logger.error?.('[makerclay] derived work failed (non-fatal):', error?.message || error);
+        }
+      };
+      return result;
+    });
+  }
+  async function ensureNodeRow({ owner, relPath, node }) {
+    return nodes.materialize({ ...node, owner, path: relPath, kind: nodes.kindFor(relPath) });
+  }
+  // atomicWrite is temp-file-plus-rename, so the host changes a file's inode on
+  // EVERY save. A row that does not re-record it here stops matching its own
+  // file the next time anything moves.
+  async function signatureOf(filePath) {
+    const info = await statInfo(filePath);
+    if (!info) return {};
+    return { dev: info.dev, ino: info.ino, mtimeMs: info.mtimeMs };
+  }
+  async function touchNode({ owner, relPath, node, etag, size, filePath }) {
+    const patch = {
+      // Also the drift baseline: the bytes this host wrote are the bytes a later
+      // save compares the file against, so a second save from the same tab
+      // measures itself against its own write rather than reporting drift that
+      // never happened.
+      etag,
+      // A statement of fact rather than the scanner's column being borrowed:
+      // once this write lands, the bytes on disk ARE this digest. `bytes` has
+      // always had two writers and `observedEtag` only had one, so after an
+      // external edit the row carried the scanner's old digest beside the
+      // kernel's new size and byDigest looked for a pair no file has. It also
+      // restores the own-write dedupe in refreshRow, which never fired after a
+      // browser save.
+      observedEtag: etag,
+      bytes: size,
+      ...(await signatureOf(filePath)),
+      updatedAt: clock.now(),
+    };
+    return nodes.materialize({ ...node, owner, path: relPath, kind: nodes.kindFor(relPath) }, patch);
+  }
+  return { replace };
+}