@threadedstack/wmd-web 0.1.16 → 0.1.18

package/src/build/inspect.js

@@ -0,0 +1,78 @@
+// Reading built layers back, for the fast-path parity gate (docs/plans/web-buildkit-impl.md 5.5): the entries of a
+// layer tar (path, type, mode, owner, size, sha256, link target, xattrs, mtime) and the layers of a Docker tar
+// (`docker save` layout or an OCI layout, layers plain or gzip).
+import { scanTarBytes } from './tar.js'
+
+const dec = new TextDecoder()
+const TYPES = { 0: 'file', 7: 'file', 1: 'hardlink', 2: 'symlink', 3: 'char', 4: 'block', 5: 'dir', 6: 'fifo' }
+
+const hex = (buf) => [...new Uint8Array(buf)].map((x) => x.toString(16).padStart(2, '0')).join('')
+const sha256Hex = async (u8) => hex(await crypto.subtle.digest('SHA-256', u8))
+
+/** gunzip when the bytes start with the gzip magic; else the bytes themselves. */
+export async function maybeGunzip(u8) {
+  if (!(u8.length > 2 && u8[0] === 0x1f && u8[1] === 0x8b)) return u8
+  const s = new Blob([u8]).stream().pipeThrough(new DecompressionStream('gzip'))
+  return new Uint8Array(await new Response(s).arrayBuffer())
+}
+
+/** './a/', '/a' and 'a' are the same path: no leading './' or '/', no trailing '/'. */
+export function cleanEntryPath(p) {
+  return p.replace(/^(\.\/|\/)+/, '').replace(/\/+$/, '') || '.'
+}
+
+/**
+ * Every entry of a layer tar (plain or gzip) as {path, type, mode, uid, gid, size, sha256, linkname, xattrs, mtime}
+ * in archive order. `sha256` is the file's content for regular files, else null; `mode` the permission bits (with
+ * setuid/setgid/sticky).
+ */
+export async function layerEntries(bytes) {
+  const u8 = await maybeGunzip(bytes)
+  const out = []
+  for await (const e of scanTarBytes(u8)) {
+    const type = TYPES[e.type] || `type-${e.type}`
+    out.push({
+      path: cleanEntryPath(e.name),
+      type,
+      mode: e.mode & 0o7777,
+      uid: e.uid,
+      gid: e.gid,
+      size: type === 'file' ? e.size : 0,
+      sha256: type === 'file' ? await sha256Hex(u8.subarray(e.offset, e.offset + e.size)) : null,
+      linkname: e.linkname,
+      xattrs: e.xattrs || {},
+      mtime: e.mtime,
+    })
+  }
+  return out
+}
+
+/**
+ * A Docker tar (what BuildKit's type=docker output writes: a `docker save` layout with manifest.json, or an OCI
+ * layout with index.json) as {config, layers}: `config` the image config JSON, `layers` the layer tars' bytes
+ * bottom first, as stored (plain or gzip).
+ */
+export async function dockerTarLayers(bytes) {
+  const files = new Map()
+  for await (const e of scanTarBytes(bytes)) {
+    if (e.type === '0' || e.type === '7') files.set(cleanEntryPath(e.name), bytes.subarray(e.offset, e.offset + e.size))
+  }
+  const get = (p) => {
+    const f = files.get(cleanEntryPath(p))
+    if (!f) throw new Error(`the Docker tar has no ${p}`)
+    return f
+  }
+  const json = (p) => JSON.parse(dec.decode(get(p)))
+  const blob = (digest) => get(`blobs/${digest.replace(':', '/')}`)
+  if (files.has('manifest.json')) {
+    const m = json('manifest.json')[0]
+    return { config: json(m.Config), layers: m.Layers.map((l) => get(l)) }
+  }
+  if (files.has('index.json')) {
+    let m = json('index.json').manifests[0]
+    let man = JSON.parse(dec.decode(blob(m.digest)))
+    if (man.manifests) man = JSON.parse(dec.decode(blob(man.manifests[0].digest)))
+    return { config: JSON.parse(dec.decode(blob(man.config.digest))), layers: man.layers.map((l) => blob(l.digest)) }
+  }
+  throw new Error('the tar has neither manifest.json nor index.json')
+}

package/src/build/pin.js

@@ -0,0 +1,6 @@
+// The wmd-web builder images (scripts/web-builder.sh writes this file): the sha256 and size of each
+// `docker save` tar in web/dist/builder/. createBuilder refuses a tar that does not match.
+export const BUILDER_PINS = {
+  arm64: { file: 'builder-arm64.tar', sha256: '905d0735a2fb7aa12f00bb21f50e82651d1f65db0aa030aa38ab4033047072ee', bytes: 107119104 },
+  amd64: { file: 'builder-amd64.tar', sha256: 'be2199d5eb05d1bcc2814999749de17d4e4ce206726f31fe8a495cf602fd3ccd', bytes: 113018368 },
+}

package/src/build/tar.js

@@ -0,0 +1,304 @@
+// A small deterministic tar writer and header scanner (docs/plans/web-buildkit-impl.md 5.6).
+// Output is ustar; a pax extended header (typeflag 'x') carries what ustar cannot hold: names over the
+// name+prefix limits, non-ASCII names, link targets over 100 bytes, sizes of 8 GiB or more, and uid/gid/mtime
+// that overflow their octal fields. Nothing reads the host clock: mtime is what the caller gives, else 0.
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+const BLOCK = 512
+
+/** TextDecoder.decode that also takes a view on a SharedArrayBuffer (wasm memory), which browsers' decoders refuse. */
+export function decodeText(u8, d = dec) {
+  return typeof SharedArrayBuffer !== 'undefined' && u8.buffer instanceof SharedArrayBuffer ? d.decode(u8.slice()) : d.decode(u8)
+}
+
+/** Throws on a path that must not enter an archive: absolute, '..', NUL, empty components. */
+export function checkTarPath(path) {
+  if (path === './') return // the archive's root folder entry
+  if (typeof path !== 'string' || path === '') throw new Error('tar: empty path')
+  if (path.includes('\0')) throw new Error(`tar: NUL in path ${JSON.stringify(path)}`)
+  if (path.startsWith('/')) throw new Error(`tar: absolute path ${path}`)
+  const parts = path.split('/')
+  if (parts[parts.length - 1] === '') parts.pop() // one trailing '/' is a directory spelling
+  for (const p of parts) {
+    if (p === '' || p === '.' || p === '..') throw new Error(`tar: unsafe path ${path}`)
+  }
+}
+
+function isAscii(s) {
+  for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) > 0x7f) return false
+  return true
+}
+
+function toSeconds(t) {
+  if (t === undefined || t === null) return 0
+  if (t instanceof Date) return Math.floor(t.getTime() / 1000)
+  return Math.max(0, Math.floor(Number(t) || 0))
+}
+
+function octal(buf, off, len, value) {
+  const s = value.toString(8).padStart(len - 1, '0')
+  for (let i = 0; i < len - 1; i++) buf[off + i] = s.charCodeAt(i)
+  buf[off + len - 1] = 0
+}
+const octMax = (len) => 8 ** (len - 1) - 1
+
+function putStr(buf, off, str) {
+  for (let i = 0; i < str.length; i++) buf[off + i] = str.charCodeAt(i)
+}
+
+/** One pax record: "<len> <key>=<value>\n" where len counts itself. */
+function paxRecord(key, value) {
+  const body = enc.encode(` ${key}=${value}\n`)
+  let n = body.length + 1
+  while (String(n).length + body.length !== n) n = String(n).length + body.length
+  const head = enc.encode(String(n))
+  const out = new Uint8Array(n)
+  out.set(head, 0)
+  out.set(body, head.length)
+  return out
+}
+
+function concat(parts, total) {
+  const out = new Uint8Array(total ?? parts.reduce((a, p) => a + p.length, 0))
+  let o = 0
+  for (const p of parts) {
+    out.set(p, o)
+    o += p.length
+  }
+  return out
+}
+
+function rawHeader(name, prefix, typeflag, size, mode, mtime, uid, gid, linkname) {
+  const h = new Uint8Array(BLOCK)
+  putStr(h, 0, name)
+  octal(h, 100, 8, mode)
+  octal(h, 108, 8, uid)
+  octal(h, 116, 8, gid)
+  octal(h, 124, 12, size)
+  octal(h, 136, 12, mtime)
+  h.fill(0x20, 148, 156)
+  h[156] = typeflag.charCodeAt(0)
+  putStr(h, 157, linkname)
+  putStr(h, 257, 'ustar')
+  h[262] = 0
+  h[263] = 0x30
+  h[264] = 0x30
+  putStr(h, 345, prefix)
+  let sum = 0
+  for (let i = 0; i < BLOCK; i++) sum += h[i]
+  const cs = sum.toString(8).padStart(6, '0')
+  putStr(h, 148, cs)
+  h[154] = 0
+  h[155] = 0x20
+  return h
+}
+
+/**
+ * The header block(s) of one entry: a pax header first when needed, then the ustar header.
+ * Exported so the over-8-GiB size path can be tested without 8 GiB of data.
+ * @returns {Uint8Array}
+ */
+export function tarEntryHeader(path, typeflag, size, { mode, mtime, uid = 0, gid = 0, linkname = '' } = {}) {
+  checkTarPath(path)
+  const isDir = typeflag === '5'
+  const full = isDir && !path.endsWith('/') ? `${path}/` : path
+  const pax = []
+  let name = full
+  let prefix = ''
+  const nameBytes = enc.encode(full)
+  if (isAscii(full) && nameBytes.length <= 100) {
+    // plain
+  } else if (isAscii(full) && nameBytes.length <= 255 + 1 + 100) {
+    // ustar prefix/name split at a '/'
+    let at = -1
+    for (let i = full.length - 2; i > 0; i--) {
+      if (full[i] !== '/') continue
+      if (full.length - i - 1 <= 100 && i <= 155) {
+        at = i
+        break
+      }
+    }
+    if (at > 0) {
+      prefix = full.slice(0, at)
+      name = full.slice(at + 1)
+    } else pax.push(['path', full])
+  } else pax.push(['path', full])
+  if (pax.length) {
+    // ustar fallback name: ASCII-only tail, never empty
+    name = full.replace(/[^\x20-\x7e]/g, '_').slice(-100)
+    prefix = ''
+  }
+  let link = linkname
+  if (link && (!isAscii(link) || enc.encode(link).length > 100)) {
+    pax.push(['linkpath', link])
+    link = link.replace(/[^\x20-\x7e]/g, '_').slice(0, 100)
+  }
+  const m = (mode ?? (isDir ? 0o755 : 0o644)) & 0o7777
+  let t = toSeconds(mtime)
+  if (t > octMax(12)) {
+    pax.push(['mtime', String(t)])
+    t = octMax(12)
+  }
+  let u = uid
+  if (u > octMax(8)) {
+    pax.push(['uid', String(u)])
+    u = octMax(8)
+  }
+  let g = gid
+  if (g > octMax(8)) {
+    pax.push(['gid', String(g)])
+    g = octMax(8)
+  }
+  let sz = size
+  if (sz > octMax(12)) {
+    pax.push(['size', String(sz)])
+    sz = octMax(12)
+  }
+  const main = rawHeader(name, prefix, typeflag, sz, m, t, u, g, link)
+  if (!pax.length) return main
+  const recs = pax.map(([k, v]) => paxRecord(k, v))
+  const dataLen = recs.reduce((a, r) => a + r.length, 0)
+  const padded = Math.ceil(dataLen / BLOCK) * BLOCK
+  const tail = (full.replace(/\/$/, '').split('/').pop() || 'x').replace(/[^\x20-\x7e]/g, '_').slice(-60)
+  const ph = rawHeader(`PaxHeaders.0/${tail}`, '', 'x', dataLen, 0o644, 0, 0, 0, '')
+  const body = new Uint8Array(padded)
+  body.set(concat(recs, dataLen), 0)
+  return concat([ph, body, main])
+}
+
+/** A tar writer. Paths are relative, '/'-separated, without '..' or a leading '/'. */
+export function tarWriter() {
+  const chunks = []
+  let total = 0
+  let done = false
+  const push = (c) => {
+    if (done) throw new Error('tar: writer already finished')
+    chunks.push(c)
+    total += c.length
+  }
+  const pad = (n) => (BLOCK - (n % BLOCK)) % BLOCK
+  return {
+    file(path, bytes, { mode, mtime, uid, gid } = {}) {
+      const data = typeof bytes === 'string' ? enc.encode(bytes) : bytes
+      push(tarEntryHeader(path, '0', data.length, { mode, mtime, uid, gid }))
+      if (data.length) {
+        push(data)
+        const p = pad(data.length)
+        if (p) push(new Uint8Array(p))
+      }
+    },
+    dir(path, { mode, mtime, uid, gid } = {}) {
+      push(tarEntryHeader(path, '5', 0, { mode, mtime, uid, gid }))
+    },
+    symlink(path, target, { mtime, uid, gid } = {}) {
+      if (!target) throw new Error('tar: empty symlink target')
+      push(tarEntryHeader(path, '2', 0, { mode: 0o777, mtime, uid, gid, linkname: target }))
+    },
+    /** The archive so far, ended with two zero blocks. */
+    finish() {
+      if (done) throw new Error('tar: writer already finished')
+      push(new Uint8Array(BLOCK * 2))
+      done = true
+      return concat(chunks, total)
+    },
+  }
+}
+
+function parseNum(buf, off, len) {
+  if (buf[off] & 0x80) {
+    // GNU base-256
+    let v = buf[off] & 0x7f
+    for (let i = 1; i < len; i++) v = v * 256 + buf[off + i]
+    return v
+  }
+  let s = ''
+  for (let i = 0; i < len && buf[off + i] !== 0 && buf[off + i] !== 0x20; i++) s += String.fromCharCode(buf[off + i])
+  return s ? parseInt(s, 8) : 0
+}
+
+function cstr(buf, off, len) {
+  let e = off
+  while (e < off + len && buf[e] !== 0) e++
+  return decodeText(buf.subarray(off, e))
+}
+
+function parsePax(data) {
+  const out = {}
+  let p = 0
+  while (p < data.length) {
+    let sp = p
+    while (sp < data.length && data[sp] !== 0x20) sp++
+    const n = parseInt(decodeText(data.subarray(p, sp)), 10)
+    if (!(n > 0) || p + n > data.length) break
+    const rec = decodeText(data.subarray(sp + 1, p + n - 1))
+    const eq = rec.indexOf('=')
+    if (eq > 0) out[rec.slice(0, eq)] = rec.slice(eq + 1)
+    p += n
+  }
+  return out
+}
+
+/**
+ * Walks a tar's headers without reading file data. `read(offset, length)` returns a Uint8Array (sync or
+ * promise) so a Blob can be walked by slices. Yields real entries only (pax 'x'/'g' and GNU 'L'/'K' are folded
+ * into the entry they describe): {name, type, size, mode, mtime, uid, gid, linkname, xattrs, offset} where `offset` is
+ * the start of the entry's data. `type` is the typeflag character ('0' for the old NUL flag).
+ */
+export async function* scanTar(read, totalLength) {
+  let off = 0
+  let pax = null
+  let gnuName = null
+  let gnuLink = null
+  const need = async (o, n) => {
+    const b = await read(o, n)
+    if (b.length < n) throw new Error('tar: truncated archive')
+    return b
+  }
+  while (off + BLOCK <= totalLength) {
+    const h = await need(off, BLOCK)
+    if (h.every((b) => b === 0)) return
+    let sum = 0
+    for (let i = 0; i < BLOCK; i++) sum += i >= 148 && i < 156 ? 0x20 : h[i]
+    if (sum !== parseNum(h, 148, 8)) throw new Error(`tar: bad header checksum at ${off}`)
+    const type = h[156] === 0 ? '0' : String.fromCharCode(h[156])
+    let size = parseNum(h, 124, 12)
+    off += BLOCK
+    if (type === 'x' || type === 'g' || type === 'L' || type === 'K') {
+      const data = await need(off, size)
+      off += Math.ceil(size / BLOCK) * BLOCK
+      if (type === 'x') pax = { ...(pax || {}), ...parsePax(data) }
+      else if (type === 'L') gnuName = cstr(data, 0, data.length)
+      else if (type === 'K') gnuLink = cstr(data, 0, data.length)
+      continue
+    }
+    const prefix = cstr(h, 345, 155)
+    let name = cstr(h, 0, 100)
+    if (prefix) name = `${prefix}/${name}`
+    let linkname = cstr(h, 157, 100)
+    let mtime = parseNum(h, 136, 12)
+    let uid = parseNum(h, 108, 8)
+    let gid = parseNum(h, 116, 8)
+    if (gnuName !== null) name = gnuName
+    if (gnuLink !== null) linkname = gnuLink
+    if (pax) {
+      if (pax.path !== undefined) name = pax.path
+      if (pax.linkpath !== undefined) linkname = pax.linkpath
+      if (pax.size !== undefined) size = Number(pax.size)
+      if (pax.mtime !== undefined) mtime = Math.floor(Number(pax.mtime))
+      if (pax.uid !== undefined) uid = Number(pax.uid)
+      if (pax.gid !== undefined) gid = Number(pax.gid)
+    }
+    const xattrs = {}
+    if (pax) for (const [k, v] of Object.entries(pax)) if (k.startsWith('SCHILY.xattr.')) xattrs[k.slice(13)] = v
+    pax = gnuName = gnuLink = null
+    const hasData = type === '0' || type === '7' || (type !== '1' && type !== '2' && type !== '5' && size > 0)
+    yield { name, type, size, mode: parseNum(h, 100, 8), mtime, uid, gid, linkname, xattrs, offset: off }
+    if (hasData) off += Math.ceil(size / BLOCK) * BLOCK
+  }
+}
+
+/** scanTar over a Uint8Array. */
+export function scanTarBytes(u8) {
+  return scanTar((o, n) => u8.subarray(o, o + n), u8.length)
+}

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/host/ctl.js

@@ -719,6 +719,14 @@ export const DEFAULT_CAPS = [
   'CAP_CHOWN', 'CAP_DAC_OVERRIDE', 'CAP_FSETID', 'CAP_FOWNER', 'CAP_MKNOD', 'CAP_NET_RAW', 'CAP_SETGID',
   'CAP_SETUID', 'CAP_SETFCAP', 'CAP_SETPCAP', 'CAP_NET_BIND_SERVICE', 'CAP_SYS_CHROOT', 'CAP_KILL', 'CAP_AUDIT_WRITE',
 ]
+/** Every capability, as internal/engine/ocispec.go allCaps (Linux 6.1: 0..40); what --privileged grants. */
+export const ALL_CAPS = [
+  'CHOWN', 'DAC_OVERRIDE', 'DAC_READ_SEARCH', 'FOWNER', 'FSETID', 'KILL', 'SETGID', 'SETUID', 'SETPCAP', 'LINUX_IMMUTABLE',
+  'NET_BIND_SERVICE', 'NET_BROADCAST', 'NET_ADMIN', 'NET_RAW', 'IPC_LOCK', 'IPC_OWNER', 'SYS_MODULE', 'SYS_RAWIO', 'SYS_CHROOT',
+  'SYS_PTRACE', 'SYS_PACCT', 'SYS_ADMIN', 'SYS_BOOT', 'SYS_NICE', 'SYS_RESOURCE', 'SYS_TIME', 'SYS_TTY_CONFIG', 'MKNOD', 'LEASE',
+  'AUDIT_WRITE', 'AUDIT_CONTROL', 'SETFCAP', 'MAC_OVERRIDE', 'MAC_ADMIN', 'SYSLOG', 'WAKE_ALARM', 'BLOCK_SUSPEND', 'AUDIT_READ',
+  'PERFMON', 'BPF', 'CHECKPOINT_RESTORE',
+].map(c => `CAP_${c}`)
 const MASKED = ['/proc/acpi', '/proc/asound', '/proc/kcore', '/proc/keys', '/proc/latency_stats', '/proc/timer_list', '/proc/timer_stats', '/proc/sched_debug', '/proc/scsi', '/sys/firmware']
 const READONLY = ['/proc/bus', '/proc/fs', '/proc/irq', '/proc/sys', '/proc/sysrq-trigger']
 const ETC_FILES = ['hosts', 'resolv.conf', 'hostname']
@@ -751,6 +759,8 @@ function defaultMounts() {
  * @param {{destination:string, files:Record<string,{data:Uint8Array|string, mode?:number}|string>, file?:string, readOnly?:boolean}[]} [o.mounts]
  *        each mount is a share vol<i> with these files; `file` binds only that file of the share
  * @param {string} [o.arch]          for imageconfig.json (default arm64)
+ * @param {boolean} [o.privileged]   docker run --privileged as dockerd writes it: all capabilities, no masked or
+ *        read-only paths, /sys read-write, every device allowed (default false; only builder machines use it)
  * @param {boolean} [o.init]         docker run --init: tini at /sbin/docker-init runs the command
  * @param {boolean} [o.keepRunning]  wmd's keep-running init at /sbin/docker-init: the container stays up
  *        after its command ends; args may be [] (nothing runs until ControlClient.startCommand). Send the
@@ -785,6 +795,13 @@ export function containerBundle(o) {
       resources: { devices: [{ allow: false, access: 'rwm' }] },
     },
   }
+  if (o.privileged) {
+    spec.process.capabilities = { bounding: ALL_CAPS, effective: ALL_CAPS, inheritable: ALL_CAPS, permitted: ALL_CAPS }
+    spec.linux.maskedPaths = []
+    spec.linux.readonlyPaths = []
+    spec.linux.resources = { devices: [{ allow: true, access: 'rwm' }] }
+    for (const m of spec.mounts) if (m.destination === '/sys') m.options = m.options.filter(x => x !== 'ro')
+  }
   if (o.init || o.keepRunning) {
     // as dockerd binds its docker-init (internal/engine/ocispec.go): the guest's tini, or its own init for keep-running
     spec.mounts.push({ destination: DOCKER_INIT, type: 'bind', source: o.keepRunning ? '/sbin/init' : '/sbin/tini', options: ['bind', 'ro'] })