@threadedstack/wmd-web 0.1.15 → 0.1.17

package/README.md

@@ -2594,8 +2594,10 @@ engines' memory64 limit), passes `WMD_RAM_FLAT=1` to vm.wasm and hands the memor
   slack (`flatMaxPages`), whatever the guest's RAM. Leave `maxPages` out for such a boot.
 - `flatRam: true|false` forces the layout on or off; unset, it is chosen for `--ram` above 1536 when the engine
   has memory64 and `allowLargeRam` is not set. Safari has no memory64: the old limit and its message stay.
-- No checkpoint yet: `checkpoint: true` is ignored and `restore` / `restoreLazy` are refused with a message
-  (a checkpoint holds memory 0 only).
+- Checkpoints and restores work as for any guest: a checkpoint also holds the RAM memory's written pages (sections
+  `ram-index` and `ram`, header `ramPages`) and restores only into a boot whose RAM memory has the same size.
+- A checkpoint, flat or not, reads only the RAM pages the guest has written (vm.wasm's `vm_touched_map`, a bit per
+  64 KiB set before the first write): a page never written is not read, so the browser never backs it with memory.
 
 Measured in Chromium (page/b7.js, `ram=`): 4096 shows `Mem: 3976`; 8192 with 4 vCPUs held 5366 MB in six
 processes with every byte checked; the same work at 1536 (small) and 4096 (flat) took 35 s and 39 s.

package/RELEASE.json

@@ -1,9 +1,38 @@
 {
   "name": "wmd-web",
   "version": "0.3.2",
-  "commit": "b591b664091fb3105d0cd0f341c56fe04131ff2c",
-  "previous": "wmd-web-v0.1.0",
+  "commit": "fa2b21cfd0fd0bf679498e6feeefc26c33f17372",
+  "previous": null,
   "decisions": [
+    "D-388",
+    "D-395",
+    "D-408",
+    "D-415",
+    "D-416",
+    "D-417",
+    "D-419",
+    "D-423",
+    "D-428",
+    "D-430",
+    "D-432",
+    "D-433",
+    "D-438",
+    "D-442",
+    "D-443",
+    "D-444",
+    "D-445",
+    "D-446",
+    "D-447",
+    "D-448",
+    "D-449",
+    "D-451",
+    "D-453",
+    "D-454",
+    "D-468",
+    "D-476",
+    "D-477",
+    "D-481",
+    "D-482",
     "D-486",
     "D-488",
     "D-494",
@@ -22,13 +51,13 @@
     "D-544",
     "D-545"
   ],
-  "vmSources": "f638fbdada4ccae26c12334b851e12244c1985d8",
+  "vmSources": "c7f2793941170d96db37d9a12a8a5ad072fda7de",
   "guest": {
     "arch": "arm64",
     "files": {
       "vm.wasm": {
-        "sha256": "f7affc474658fdfdc50e96c29a224eed1520ea69b426d6427fbc058eb141091a",
-        "bytes": 1548267
+        "sha256": "2504f4071537e205d78766f2c84219fe49ea4709314becff3a314765733e7fdf",
+        "bytes": 1561314
       },
       "Image": {
         "sha256": "a6b3209cf69d5bc1dacf0f3ed67f92c535dbb4108d67b47091c2aef87c6d7b04",
@@ -45,7 +74,7 @@
     }
   },
   "files": {
-    "README.md": "b9edbf3db9576f7016df93dee8e2b197071655518f90363fe2dafe2a97b03a3d",
+    "README.md": "6873b42beaf44e02eded67fa54aaa2c13d766597048fbc8633909b6d77b049e0",
     "export-page/coi-sw.js": "0300e670b413cb2e0aae35843fc583546bbf6687df971ab6df41cfa3b0d494d7",
     "export-page/index.html": "f5450c89e63601bbbbffef421f03491b231d1f143070012c1c5315d4b0059f43",
     "export-page/run.css": "b57adf1e76553549c1f89ff157b7973409dedc21889cd3932948cd05b51adc6f",
@@ -53,10 +82,10 @@
     "guest/arm64/Image": "a6b3209cf69d5bc1dacf0f3ed67f92c535dbb4108d67b47091c2aef87c6d7b04",
     "guest/arm64/Image-4k": "8ff6e338a0b42d9f774b35423e0e7f9d7f779c635446e8de2a3beb83d3518f8a",
     "guest/arm64/initramfs.cpio.gz": "a2260db90e5d8acdf12a2123f696b4512a1465856d5653e20a85504069a3480c",
-    "guest/arm64/vm.wasm": "f7affc474658fdfdc50e96c29a224eed1520ea69b426d6427fbc058eb141091a",
+    "guest/arm64/vm.wasm": "2504f4071537e205d78766f2c84219fe49ea4709314becff3a314765733e7fdf",
     "package.json": "17aa3a8406e8d2d85b647c426438d3fd75edcb59d83e257882227e7b93cccbc0",
     "src/base.js": "982f8e46dbb727ec542a494ebdb884ccd19a31ff4e091425b2d1fc01b0d4754a",
-    "src/boot.js": "114f9cf0561bca17b042c8db2e72e6984f7a55fd8d19700730895935f226cc77",
+    "src/boot.js": "911a40e01fa4833249743653b7698e8fed217d52a34056a92524562f3f8daacc",
     "src/calib-worker.js": "3d610591a1b3b58f59c3a2ab457f43c90727d95973cd43055b3b73b76180611d",
     "src/fs/9p/codec.js": "69711eb4ebc84eff39256138169fe18f5a5066d6cd9e4ff2daf61c65380d7ef7",
     "src/fs/9p/server.js": "da0ba00ebb5522161bb0ef7cd94bfc9616e342bf865633dfef0ba5bc67627d7a",
@@ -77,9 +106,9 @@
     "src/host/chan.js": "43104dcdd4d17d13f55a71906b398bdb52d9e96c6fca239310f2ee1ccbb4d4ad",
     "src/host/ckpt-file.js": "da7938fa640a062e77bdfb59caad5b3b1fcbf6150e3220de3be23f253f4c4497",
     "src/host/ckpt-io.js": "3fbe74f0254c597f10d088c85e8ba72725502d86ae4dd8c6d2bf0821a93c873f",
-    "src/host/ckpt-point.js": "3cc9ec778f131fbfd17a788709f01f096719f3ef81490a7be36a7fc1a422aef4",
+    "src/host/ckpt-point.js": "42bc16b3f754de3cd4e39f37a0feca2ffd8b4231cd72ec32bd6e1ea734c3c8c7",
     "src/host/ckpt-save.js": "e222571033ae74a4439596c5e90e03b2aa9a5516665dd290f8dd243712294523",
-    "src/host/ckpt.js": "17c3e3f39c7e4ab9b51a4d121d1017d943257f95357330d8f21140011562d0db",
+    "src/host/ckpt.js": "2155b5c8e6f609478805eb8a0b5d5210d47cdf35a80f79e0b9ae42b2c3170923",
     "src/host/clock.js": "aba6af3a8b1a985ae340892222e4b482d33afe20f5c8b3a4c7403ce87d1e247c",
     "src/host/ctl.js": "654c55c64efa3df4df8b7b28024a10bd0e7ed3afb89004f8a583b9e62f17f58f",
     "src/host/errno.js": "26021d85962084be2c43c98fb3accafc2a8f11fbf3c8a5b8d484bd6a088ae4db",
@@ -120,6 +149,6 @@
     "src/registry/pull.js": "66edf4602aca8d41cc68393d01a2da01c4667de7c493af5ae400e8f249d4e3ae",
     "src/registry/ref.js": "24038e0fbcb6ac143cb8e8f7b9fac4dd0803d0891961786dc88dba01a4402e7b",
     "src/registry/wasi-mem.js": "a7f684343010892460db27ee8c1e38e47e797c93dc4ebe4c30185dca6ca56ee2",
-    "src/worker.js": "dda8e216ff774fc6d31ccb55c265f1c560243f872b57bc0affe3075b94bd5b4f"
+    "src/worker.js": "fe23f1b99acedc65e56f92f7246923fdbdbefd085bae427b57cbe1402b4f5161"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadedstack/wmd-web",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "license": "MIT",
   "homepage": "https://github.com/threadedstack/wmd-releases",
   "repository": {
@@ -9,8 +9,8 @@
   },
   "description": "Browser host for wmd's guest vm.wasm (Web Workers + shared memory + WASI preview1)",
   "wmd": {
-    "tag": "v0.1.15",
-    "commit": "b591b664091fb3105d0cd0f341c56fe04131ff2c",
+    "tag": "v0.1.17",
+    "commit": "fa2b21cfd0fd0bf679498e6feeefc26c33f17372",
     "web": "0.3.2"
   },
   "type": "module",

package/src/boot.js

@@ -531,14 +531,12 @@ export async function bootWmd(o) {
   const flatRam = wantsFlatRam(o.args, o)
   if (!flatRam) ramMiB(o.args, o.allowLargeRam) // a bad or too big --ram is a clear error before anything is downloaded
   const maximum = o.maxPages || (flatRam ? flatMaxPages(o.args) : memoryMaxPages(o.args, 1024, o.allowLargeRam))
-  if (flatRam) {
-    if (o.restore || o.restoreLazy) throw new Error(`--ram ${ramMiB(o.args, true)}: a guest with more than ${MAX_BROWSER_RAM_MIB} MiB cannot start from a checkpoint yet`)
-    env.push('WMD_RAM_FLAT=1')
-  }
+  if (flatRam) env.push('WMD_RAM_FLAT=1')
   const ramMem = flatRam ? createRamMemory(ramMiB(o.args, true)) : null
+  /** The RAM memory's pages (0: the RAM is in memory 0). A checkpoint of a flat guest also holds its RAM memory's pages (sections ram-index, ram). */
+  const ramPages = ramMem ? ramMem.buffer.byteLength / CKPT_PAGE : 0
   // P-B9: checkpoints. restoreIn: the checkpoint's parts (parseCheckpoint refuses a malformed one).
-  // A flat guest takes none yet: a checkpoint holds memory 0 only.
-  const ckptOn = !flatRam && (!!o.checkpoint || !!o.restore || !!o.restoreLazy)
+  const ckptOn = !!o.checkpoint || !!o.restore || !!o.restoreLazy
   let restoreIn = o.restore ? parseCheckpoint(o.restore) : null
   // P-B6: a base snapshot that is still downloading ({header: Promise, ckpt: Promise, abort()}, src/base.js openBase()). The
   // boot downloads its own files meanwhile; the snapshot's header is checked against this boot's vm.wasm and boot key as soon
@@ -740,7 +738,7 @@ export async function bootWmd(o) {
           const got = typeof box.take === 'function' ? box.take() : box // a box hands the snapshot over once: the opener keeps no reference to its 0.5 GB
           ckptT.baseWaitMs = absMs() - tw // the time the boot waited for the snapshot after everything else was in
           const parsed = parseCheckpoint(got)
-          checkCheckpointFits(parsed.header, { vmKey, bootKey, bootDesc, maxPages: maximum, hasJit: o.jit !== false, fmaFused: fmaFuses() })
+          checkCheckpointFits(parsed.header, { vmKey, bootKey, bootDesc, maxPages: maximum, ramPages, hasJit: o.jit !== false, fmaFused: fmaFuses() })
           checkPacksFit(parsed.header.packs, packDigests)
           restoreIn = parsed
           lazyIn = null // baseLazy stays: accept() when the restore has succeeded, reject() if it fails
@@ -749,7 +747,7 @@ export async function bootWmd(o) {
           baseRefused(err)
         }
       }
-      if (restoreIn) checkCheckpointFits(restoreIn.header, { vmKey, bootKey, bootDesc, maxPages: maximum, hasJit: o.jit !== false, fmaFused: fmaFuses() })
+      if (restoreIn) checkCheckpointFits(restoreIn.header, { vmKey, bootKey, bootDesc, maxPages: maximum, ramPages, hasJit: o.jit !== false, fmaFused: fmaFuses() })
     }
     if (signal?.aborted) throw abortError()
   } catch (err) {
@@ -812,6 +810,26 @@ export async function bootWmd(o) {
         kept[p] = 1
       }
     }
+    // the flat layout: the guest's RAM, into its own memory (a fresh one: all zero but for these pages)
+    if (restoreIn.ram) {
+      const ram = ramMem.buffer
+      const win = 16384 // pages per view: a RAM memory can be past the length of one typed array view
+      let at = -1
+      let v = null
+      let r = 0
+      for (const c of restoreIn.ram.chunks) {
+        for (let off = 0; off < c.length; off += CKPT_PAGE) {
+          const p = restoreIn.ram.index[r++]
+          const lo = p - (p % win)
+          if (lo !== at) {
+            at = lo
+            v = new Uint8Array(ram, lo * CKPT_PAGE, Math.min(win, ramPages - lo) * CKPT_PAGE)
+          }
+          v.set(c.subarray(off, off + CKPT_PAGE), (p - lo) * CKPT_PAGE)
+        }
+      }
+      ckptT.ramPagesRestored = r
+    }
     // pages the instance's start function wrote that were zero at the checkpoint (the runner's zero_absent): the static region
     let zeroed = 0
     const w = new Int32Array(memory.buffer, 0, Math.min(restoreIn.header.memPages, VM_MIN_PAGES) * (CKPT_PAGE / 4))
@@ -845,6 +863,7 @@ export async function bootWmd(o) {
     be.now('restore', { t: 'boot', stage: 'restore', state: 'done', used: true, bytes: baseBytes, total: baseTotal, source: baseSource, tookMs: Math.round(ckptT.pagesWrittenAt) })
     restoreIn.memChunks = null
     restoreIn.index = null
+    restoreIn.ram = null
     restoreIn.jit = null
     restoreIn.svc = null
     restoreIn.ctl = null
@@ -1854,7 +1873,7 @@ export async function bootWmd(o) {
     try {
       // everything that can fail without harming the running machine comes first: the checkpoint parses and is this boot's
       const parsed = parseCheckpoint(ckpt)
-      checkCheckpointFits(parsed.header, { vmKey, bootKey, bootDesc, maxPages: maximum, hasJit: o.jit !== false, fmaFused: fmaFuses() })
+      checkCheckpointFits(parsed.header, { vmKey, bootKey, bootDesc, maxPages: maximum, ramPages, hasJit: o.jit !== false, fmaFused: fmaFuses() })
       if (!heldAssets) throw new CheckpointError('not-ready', 'this machine was booted without checkpoint support: it has no kept boot files to restore with')
       validateFdTable(parsed.ctl, heldAssets.files.length) // the fd table is checked against this boot's files now, not after the old machine is gone
       // the boot's own bytes (vm.wasm and its compiled Module, the kernel, the packs, the keys) are reused: nothing is

package/src/host/ckpt-point.js

@@ -30,27 +30,44 @@ export const REQ_CKPT = VM_POINT_CKPT
 
 /** Pages per chunk of the memory section (32 MiB). */
 export const CHUNK_PAGES = 512
+/** Pages per view while a memory is scanned (1 GiB). */
+export const WINDOW_PAGES = 16384
 
 /**
  * Non-zero pages of memory: {index: Uint32Array of page numbers, chunks: ArrayBuffer[] (pages
  * back to back, CHUNK_PAGES each), pages (total), nonzero, scanMs, copyMs}. Reads the memory
  * without atomics: the machine is frozen.
  */
-export function scanMemory(memory, { now = () => performance.now(), chunkPages = CHUNK_PAGES, limitBytes = Infinity, verifyAbove = false } = {}) {
+export function scanMemory(memory, { now = () => performance.now(), chunkPages = CHUNK_PAGES, limitBytes = Infinity, verifyAbove = false, skip = null } = {}) {
   const buf = memory.buffer
   // limitBytes: pages from here up are taken to be zero and are not read. Reading an untouched page of a shared
   // memory commits it in WebKit (W34: a full walk of a 3968 MiB memory added about 2.2 GB of footprint), so a caller
   // that knows where the guest's heap ends should say so; the page count of the checkpoint stays the memory's.
   const total = buf.byteLength / PAGE
   const pages = Math.min(total, Math.ceil(limitBytes / PAGE))
-  const w = new Int32Array(buf)
-  const u8 = new Uint8Array(buf)
   const per = PAGE / 4
+  // views of at most WINDOW_PAGES pages: a guest RAM memory64 can be 16 GiB, past the length of one typed array view
+  let wLo = -1
+  let w = null
+  const words = p => {
+    const at = p - (p % WINDOW_PAGES)
+    if (at !== wLo) {
+      wLo = at
+      w = new Int32Array(buf, at * PAGE, Math.min(WINDOW_PAGES, total - at) * per)
+    }
+    return (p - at) * per
+  }
   const t0 = now()
   let idx = new Uint32Array(Math.min(pages, 1 << 14))
   let n = 0
+  let skipped = 0
   for (let p = 0; p < pages; p++) {
-    const lo = p * per
+    // a page the guest never wrote is zero: it is not read (reading it would make the host back it with memory)
+    if (skip && skip(p)) {
+      skipped++
+      continue
+    }
+    const lo = words(p)
     const hi = lo + per
     let nz = false
     for (let i = lo; i < hi; i += 8) {
@@ -72,7 +89,7 @@ export function scanMemory(memory, { now = () => performance.now(), chunkPages =
   let aboveNonzero = 0
   if (verifyAbove) {
     for (let p = pages; p < total; p++) {
-      const lo = p * per
+      const lo = words(p)
       for (let i = lo; i < lo + per; i += 8) {
         if ((w[i] | w[i + 1] | w[i + 2] | w[i + 3] | w[i + 4] | w[i + 5] | w[i + 6] | w[i + 7]) !== 0) {
           aboveNonzero++
@@ -86,10 +103,32 @@ export function scanMemory(memory, { now = () => performance.now(), chunkPages =
   for (let k = 0; k < n; k += chunkPages) {
     const m = Math.min(chunkPages, n - k)
     const c = new Uint8Array(m * PAGE)
-    for (let j = 0; j < m; j++) c.set(u8.subarray(idx[k + j] * PAGE, (idx[k + j] + 1) * PAGE), j * PAGE)
+    for (let j = 0; j < m; j++) c.set(new Uint8Array(buf, idx[k + j] * PAGE, PAGE), j * PAGE)
     chunks.push(c.buffer)
   }
-  return { index: idx.slice(0, n), chunks, pages: total, scannedPages: pages, aboveNonzero, nonzero: n, scanMs: t1 - t0, copyMs: now() - t1 }
+  return { index: idx.slice(0, n), chunks, pages: total, scannedPages: pages - skipped, skippedPages: skipped, aboveNonzero, nonzero: n, scanMs: t1 - t0, copyMs: now() - t1 }
+}
+
+/**
+ * The pages a checkpoint need not read, from vm.wasm's vm_touched_map (guest/vm/include/vm/ram.h): the RAM pages the guest never
+ * wrote. `desc` is the address of its six u64s: [bitmap address, bitmap pages, memory-0 offset of RAM (or of the flat layout's boot
+ * stand-in), its length, RAM bytes, flat]. Returns {mem0(p), ram(p)}: whether page p of memory 0, or of the RAM memory, is skipped.
+ */
+export function touchedSkips(memory, desc) {
+  const d = new BigUint64Array(memory.buffer, desc, 6)
+  const bits = new Uint8Array(memory.buffer, Number(d[0]), Number(d[1]) / 8)
+  const nbits = Number(d[1])
+  const lowOff = Number(d[2])
+  const lowLen = Number(d[3])
+  const flat = d[5] !== 0n
+  const unset = i => i >= nbits || !(bits[i >> 3] & (1 << (i & 7)))
+  const first = Math.ceil(lowOff / PAGE)
+  const end = Math.floor((lowOff + lowLen) / PAGE) // pages wholly inside the range
+  return {
+    // memory 0: a page inside guest RAM that was never written; with the flat layout the boot stand-in is never read again
+    mem0: p => p >= first && p < end && (flat || unset(p - lowOff / PAGE)),
+    ram: p => unset(p),
+  }
 }
 
 /**
@@ -97,7 +136,7 @@ export function scanMemory(memory, { now = () => performance.now(), chunkPages =
  * message to the page; goTimeoutMs: how long vCPU 0 waits for the page (a page that is gone
  * makes the point fail: the guest goes on, as it does for any failed point).
  */
-export function createCkptImports({ memory, ctl, post, scanLimit = null, verifyBound = false, useHeapTop = false, heapTop = () => null, goTimeoutMs = 60_000, now = () => performance.timeOrigin + performance.now() }) {
+export function createCkptImports({ memory, ram = null, touched = () => null, ctl, post, scanLimit = null, verifyBound = false, useHeapTop = false, heapTop = () => null, goTimeoutMs = 60_000, now = () => performance.timeOrigin + performance.now() }) {
   return {
     ctl_attach(wordAddr) {
       Atomics.store(ctl, CTL_CK_HOSTREQ, wordAddr >>> 0)
@@ -124,7 +163,11 @@ export function createCkptImports({ memory, ctl, post, scanLimit = null, verifyB
         // verifyBound found no non-zero page above it
         const top = scanLimit ?? (useHeapTop ? heapTop() : null)
         const limit = typeof top === 'number' && top > 0 ? Math.min(top, memory.buffer.byteLength) : Infinity
-        cap = scanMemory(memory, { now, limitBytes: limit, verifyAbove: verifyBound })
+        const desc = touched()
+        const skips = desc ? touchedSkips(memory, desc) : null
+        // RAM in memory 0 starts at a 64 KiB boundary (memory.grow), so a skipped page is all RAM
+        if (skips && (Number(new BigUint64Array(memory.buffer, desc, 6)[2]) % PAGE) !== 0) throw new Error('guest RAM is not page-aligned in memory 0')
+        cap = scanMemory(memory, { now, limitBytes: limit, verifyAbove: verifyBound, skip: skips ? skips.mem0 : null })
         cap.limitBytes = Number.isFinite(limit) ? limit : null
         // the live g_rsv {brk, end} of vm.wasm 50c6495e / 3aef93fc (linear address 4251160), next to what vm_heap_top() says
         try {
@@ -133,13 +176,15 @@ export function createCkptImports({ memory, ctl, post, scanLimit = null, verifyB
           cap.endLive = Number(g[1])
         } catch {}
         cap.heapTopRet = heapTop()
+        // the flat layout: guest RAM is a memory of its own (host/ram-mem.js), every page of it the guest's
+        if (ram) cap.ram = scanMemory(ram, { now, skip: skips ? skips.ram : null })
       } catch (err) {
         post({ t: 'ckpt-mem-error', message: String(err && err.message ? err.message : err) })
         Atomics.wait(ctl, CTL_CK_GO, 0, goTimeoutMs)
         Atomics.store(ctl, CTL_CK_GO, 0)
         return -12
       }
-      post({ t: 'ckpt-mem', index: cap.index, chunks: cap.chunks, pages: cap.pages, scannedPages: cap.scannedPages, aboveNonzero: cap.aboveNonzero, brkLive: cap.brkLive, endLive: cap.endLive, heapTopRet: cap.heapTopRet, limitBytes: cap.limitBytes, nonzero: cap.nonzero, scanMs: cap.scanMs, copyMs: cap.copyMs, doneAt: now() }, [cap.index.buffer, ...cap.chunks])
+      post({ t: 'ckpt-mem', index: cap.index, chunks: cap.chunks, pages: cap.pages, scannedPages: cap.scannedPages, skippedPages: cap.skippedPages, ramScannedPages: cap.ram?.scannedPages, ramSkippedPages: cap.ram?.skippedPages, aboveNonzero: cap.aboveNonzero, brkLive: cap.brkLive, endLive: cap.endLive, heapTopRet: cap.heapTopRet, limitBytes: cap.limitBytes, nonzero: cap.nonzero, scanMs: cap.scanMs, copyMs: cap.copyMs, ram: cap.ram ? { index: cap.ram.index, chunks: cap.ram.chunks, pages: cap.ram.pages, nonzero: cap.ram.nonzero, scanMs: cap.ram.scanMs, copyMs: cap.ram.copyMs } : null, doneAt: now() }, [cap.index.buffer, ...cap.chunks, ...(cap.ram ? [cap.ram.index.buffer, ...cap.ram.chunks] : [])])
       const r = Atomics.wait(ctl, CTL_CK_GO, 0, goTimeoutMs)
       const go = Atomics.load(ctl, CTL_CK_GO)
       Atomics.store(ctl, CTL_CK_GO, 0)

package/src/host/ckpt.js

@@ -154,6 +154,11 @@ export function assembleCheckpoint(p) {
   const sections = []
   sections.push({ name: 'mem-index', chunks: [new Uint8Array(p.mem.index.buffer, p.mem.index.byteOffset, p.mem.index.byteLength)] })
   sections.push({ name: 'mem', chunks: p.mem.chunks.map(c => new Uint8Array(c)) })
+  // the flat layout: the guest's RAM is a memory of its own, saved as its non-zero pages the same way
+  if (p.mem.ram) {
+    sections.push({ name: 'ram-index', chunks: [new Uint8Array(p.mem.ram.index.buffer, p.mem.ram.index.byteOffset, p.mem.ram.index.byteLength)] })
+    sections.push({ name: 'ram', chunks: p.mem.ram.chunks.map(c => new Uint8Array(c)) })
+  }
   const header = {
     ...p.meta,
     format: FORMAT_VERSION,
@@ -164,6 +169,10 @@ export function assembleCheckpoint(p) {
     guestHdr: b64(p.hdr),
     svcPorts: Object.keys(p.svc).map(Number),
   }
+  if (p.mem.ram) {
+    header.ramPages = p.mem.ram.pages
+    header.ramNonzero = p.mem.ram.nonzero
+  }
   if (p.jit) {
     sections.push({ name: 'jit-recs', chunks: [new Uint8Array(p.jit.snap.recs.buffer, p.jit.snap.recs.byteOffset, p.jit.snap.recs.byteLength)] })
     sections.push({ name: 'jit-log', chunks: concatChunks([p.jit.snap.log], 32 << 20) })
@@ -198,6 +207,7 @@ export function parseCheckpoint(ck) {
     if (index[i] >= h.memPages) throw new CheckpointError('malformed', `page ${index[i]} is past the ${h.memPages} pages of memory`)
     if (i && index[i] <= index[i - 1]) throw new CheckpointError('malformed', `the page list is not strictly increasing at entry ${i} (page ${index[i]} after ${index[i - 1]}): a duplicate or unordered page`)
   }
+  const ram = h.ramPages ? pagesOf(get, 'ram', h.ramPages) : null
   let jit = null
   if (h.jit) {
     const recs = concat(get('jit-recs'))
@@ -213,7 +223,26 @@ export function parseCheckpoint(ck) {
   const svc = {}
   for (const port of h.svcPorts || []) svc[port] = concat(get(`svc-${port}`))
   const ctlBytes = concat(get('ctl'))
-  return { header: h, index, memChunks, jit, svc, ctl: new Uint8Array(ctlBytes), names: parseNames(ck) }
+  return { header: h, index, memChunks, ram, jit, svc, ctl: new Uint8Array(ctlBytes), names: parseNames(ck) }
+}
+
+/** The flat layout's RAM sections (`<name>-index` and `<name>`): {index, chunks}, checked as the memory's are. */
+function pagesOf(get, name, total) {
+  if (!Number.isInteger(total) || total <= 0) throw new CheckpointError('malformed', `${name}Pages is ${total}`)
+  const idxBytes = concat(get(`${name}-index`))
+  if (idxBytes.length % 4) throw new CheckpointError('malformed', `${name}-index is not a list of 32-bit page numbers`)
+  const index = new Uint32Array(idxBytes.buffer.slice(idxBytes.byteOffset, idxBytes.byteOffset + idxBytes.length))
+  const chunks = get(name)
+  const have = chunks.reduce((n, c) => n + c.length, 0)
+  if (have !== index.length * PAGE) throw new CheckpointError('malformed', `the ${name} section holds ${have} bytes for ${index.length} pages`)
+  chunks.forEach((c, i) => {
+    if (c.length % PAGE) throw new CheckpointError('malformed', `${name} chunk ${i} is ${c.length} bytes, not a whole number of ${PAGE}-byte pages`)
+  })
+  for (let i = 0; i < index.length; i++) {
+    if (index[i] >= total) throw new CheckpointError('malformed', `${name} page ${index[i]} is past its ${total} pages`)
+    if (i && index[i] <= index[i - 1]) throw new CheckpointError('malformed', `the ${name} page list is not strictly increasing at entry ${i}`)
+  }
+  return { pages: total, index, chunks }
 }
 
 // no leading zeros: "198.18.07.1" and "198.18.7.1" are one address, and the map keeps each address once
@@ -266,7 +295,7 @@ export function checkVmKeyFits(h, vmKey) {
   }
 }
 
-export function checkCheckpointFits(h, { vmKey, bootKey, bootDesc, maxPages, hasJit, fmaFused = true }) {
+export function checkCheckpointFits(h, { vmKey, bootKey, bootDesc, maxPages, ramPages = 0, hasJit, fmaFused = true }) {
   if (h.format !== FORMAT_VERSION) throw new CheckpointError('version', `checkpoint format ${h.format}; this build restores format ${FORMAT_VERSION}`)
   if (h.vmKey !== vmKey) {
     throw new CheckpointError('stale', `this checkpoint was taken with a different vm.wasm (${String(h.vmKey).slice(0, 12)}, this boot has ${String(vmKey).slice(0, 12)}): its memory image is the old emulator's and cannot be restored; take a new one`)
@@ -276,6 +305,10 @@ export function checkCheckpointFits(h, { vmKey, bootKey, bootDesc, maxPages, has
     throw new CheckpointError('stale', `this checkpoint was taken by a boot with a different kernel, initramfs, command line, environment, image layers or bundle files than this one; restore it only into the same configuration${diff ? ` (differs: ${diff})` : ''}`)
   }
   if (h.memPages > maxPages) throw new CheckpointError('stale', `this checkpoint's memory is ${h.memPages} pages and this boot's maximum is ${maxPages}`)
+  // the flat layout: the guest's RAM is restored into a memory of exactly its size
+  if ((h.ramPages || 0) !== ramPages) {
+    throw new CheckpointError('stale', h.ramPages ? `this checkpoint holds ${h.ramPages / 16} MiB of guest RAM in a memory of its own and this boot ${ramPages ? `has ${ramPages / 16} MiB` : 'keeps its RAM in memory 0'}` : 'this checkpoint keeps the guest\'s RAM in memory 0 and this boot keeps it in a memory of its own')
+  }
   if (h.jit && !hasJit) throw new CheckpointError('stale', 'this checkpoint carries JIT state and this boot has the JIT door off (jit: false)')
   if (!h.jit && hasJit) throw new CheckpointError('stale', 'this checkpoint was taken without the JIT door and this boot has it on')
   // D-539: its JIT blocks may use relaxed_madd, which this engine does not fuse or parse

package/src/worker.js

@@ -166,8 +166,9 @@ async function run(m) {
   // P-B3: channels over the chan block's rings, when the boot has channel services.
   const chan = m.chan ? createChanImports({ sab: m.chan, memory, exiting: () => Atomics.load(ctl, CTL_EXIT) !== 0 }) : {}
   let heapTopFn = null // vm.wasm's vm_heap_top export, once the main thread has instantiated (null: a full scan)
+  let touchedFn = null // vm.wasm's vm_touched_map export: the RAM pages the guest wrote (null: every page is read)
   // P-B9: checkpoint support: wmd.ctl_attach and wmd.point (host/ckpt-point.js)
-  const ckpt = m.ckpt ? createCkptImports({ memory, ctl, scanLimit: m.ckptScanLimit ?? null, verifyBound: !!m.ckptVerifyBound, useHeapTop: !!m.ckptUseHeapTop, heapTop: () => heapTopFn?.() ?? null, post: (msg, transfer) => self.postMessage(msg, transfer || []) }) : null
+  const ckpt = m.ckpt ? createCkptImports({ memory, ram: m.ram || null, ctl, scanLimit: m.ckptScanLimit ?? null, verifyBound: !!m.ckptVerifyBound, useHeapTop: !!m.ckptUseHeapTop, heapTop: () => heapTopFn?.() ?? null, touched: () => touchedFn?.() ?? null, post: (msg, transfer) => self.postMessage(msg, transfer || []) }) : null
   // the flat layout: guest RAM is the page's memory64 (host/ram-mem.js)
   const ramImports = m.ram ? createRamImports({ memory, ram: m.ram }) : null
   const wmd = createWmdImports({
@@ -250,6 +251,7 @@ async function run(m) {
   if (role === 'main') {
     const inst = instantiate()
     if (typeof inst.exports.vm_heap_top === 'function') heapTopFn = () => Number(inst.exports.vm_heap_top())
+    if (typeof inst.exports.vm_touched_map === 'function') touchedFn = () => inst.exports.vm_touched_map() >>> 0
     self.postMessage({ t: 'ready', role, at: performance.timeOrigin + performance.now() })
     try {
       if (m.resume) {