@threadedstack/wmd-web 0.1.17 → 0.1.19

package/src/build/fast.js

@@ -0,0 +1,1187 @@
+// The no-RUN fast path (docs/plans/web-buildkit-impl.md 5.5): a Dockerfile of only FROM, COPY (from the context),
+// ENV, ARG, LABEL, WORKDIR, USER, EXPOSE, ENTRYPOINT, CMD, STOPSIGNAL, VOLUME and HEALTHCHECK is built in the page:
+// the base is pulled, each COPY (and a WORKDIR that makes a folder) becomes one layer tar written the way BuildKit's
+// file operation writes it, each tar is converted to a pack, and the config and history are written as the
+// dockerfile frontend writes them.
+//
+//   const e = fastEligible(text, { args, target })      // {ok: true, plan} | {ok: false, why}
+//   const r = await fastBuild({ plan, context, pull, converter, platform, args, target, onEvent })
+//   // r: {index, packs, config, history, path: 'fast', ...}; index and packs are what pullImage returns (layers top first)
+//
+// Everything the plan does not list goes to BuildKit, decided before any work (fastEligible) or, for what only the
+// pulled base shows (ONBUILD in its config, the account files /etc/passwd and /etc/group), by fastBuild throwing
+// FastRefused. Any doubt is a refusal: a build that falls back costs time, a build that differs costs correctness.
+//
+// BuildKit sources read for this port (third_party/buildkit, v0.33.0 + tonistiigi/fsutil copy/): dockerfile2llb
+// (dispatchCopy, dispatchWorkdir, dispatch*), solver/llbsolver/file (docopy, mkdir), ops/user_unix.go (readUser),
+// fsutil copy.Copy (prepareTargetDir, copyDirectory, MkdirAll).
+//
+// Context: {list, read} (list(): entries or an async iterable of {path, type: 'file'|'dir'|'symlink', mode, mtime
+// (seconds), target}; read(path): bytes), a tar (Uint8Array), or {[path]: Uint8Array|string}. A source with no modes
+// gives 0644 files and 0755 folders (5.6). All entries are 0:0 on arrival, as BuildKit's local source maps them.
+
+import { Overlay } from '../fs/overlay.js'
+import { Pack, bytesSource } from '../fs/pack.js'
+import { FsError } from '../fs/errno.js'
+import { ImageFiles } from '../image-files.js'
+import { createConverter } from '../registry/converter.js'
+import { sha256 } from '../registry/hub.js'
+import { CONVERTER } from '../registry/pull.js'
+import { IMAGE_SCHEMA, parsePlatform, parseRef, platformString } from '../registry/ref.js'
+import {
+  DockerfileError, Env, FallbackError, expandWord, goDurationString, goQuote, goQuoteList, parseDockerfile,
+} from './dockerfile.js'
+import { matcher, parseDockerignore } from './dockerignore.js'
+import { ContextError, packContext } from './context.js'
+import { decodeText, scanTarBytes, tarWriter } from './tar.js'
+
+/** The base or the build needs BuildKit: fastBuild stopped before returning an image. */
+export class FastRefused extends FallbackError {
+  constructor(why) {
+    super(why)
+    this.name = 'FastRefused'
+  }
+}
+
+const HISTORY_COMMENT = 'buildkit.dockerfile.v0'
+const DEFAULT_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'
+const DEFAULT_SHELL = ['/bin/sh', '-c']
+
+// ---------------------------------------------------------------- paths (Go's path, filepath, system.NormalizePath)
+
+/** path.Clean for a rooted path: '/a//b/../c/' -> '/a/c'. */
+function clean(p) {
+  const out = []
+  for (const s of p.split('/')) {
+    if (s === '' || s === '.') continue
+    if (s === '..') out.pop()
+    else out.push(s)
+  }
+  return `/${out.join('/')}`
+}
+const parts = (abs) => clean(abs).split('/').filter(Boolean)
+const join = (a, b) => clean(`${a}/${b}`)
+const dirname = (abs) => {
+  const c = clean(abs)
+  return c.slice(0, c.lastIndexOf('/')) || '/'
+}
+const basename = (abs) => {
+  const c = clean(abs)
+  return c === '/' ? '/' : c.slice(c.lastIndexOf('/') + 1)
+}
+const tarName = (abs) => clean(abs).slice(1)
+
+/** system.NormalizePath(parent, newPath, 'linux', keepSlash). */
+function normalizePath(parent, newPath, keepSlash) {
+  let par = parent === '' ? '/' : parent
+  if (!par.startsWith('/')) par = clean(`/${par}`)
+  const orig = newPath
+  let p = newPath === '' ? par : newPath
+  if (!p.startsWith('/')) p = clean(`${par}/${p}`)
+  if (keepSlash) {
+    if (orig.endsWith('/') && !p.endsWith('/')) p += '/'
+    else if (orig.endsWith('/.')) {
+      if (p !== '/') p += '/'
+      p += '.'
+    }
+  }
+  return p
+}
+
+/** system.NormalizeWorkdir(current, wd): an absolute workdir is kept as written. */
+export function normalizeWorkdir(current, wd) {
+  return normalizePath(current, wd, false)
+}
+
+/**
+ * Resolves symlinks in every component of an absolute path as fs.RootPath does (the last one too when followLast):
+ * absolute targets restart at the root, '..' stops at the root, a missing component keeps the rest as written.
+ * lstat(abs) -> {type, target}|null.
+ */
+function realPath(path, lstat, followLast = true) {
+  let ps = parts(path)
+  const out = []
+  let hops = 0
+  for (let i = 0; i < ps.length; i++) {
+    const c = ps[i]
+    const cand = `/${[...out, c].join('/')}`
+    const st = lstat(cand)
+    if (!st) {
+      out.push(c, ...ps.slice(i + 1))
+      break
+    }
+    if (st.type === 'symlink' && (i < ps.length - 1 || followLast)) {
+      if (++hops > 255) throw new FastRefused(`too many levels of symbolic links at ${cand}`)
+      const t = st.target
+      const next = t.startsWith('/') ? clean(t) : clean(`/${out.join('/')}/${t}`)
+      ps = [...next.split('/').filter(Boolean), ...ps.slice(i + 1)]
+      out.length = 0
+      i = -1
+      continue
+    }
+    out.push(c)
+  }
+  return `/${out.join('/')}`
+}
+
+// ---------------------------------------------------------------- filepath.Match and wildcard sources
+
+const regexEsc = (c) => c.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')
+
+/** filepath.Match as a RegExp: '*' and '?' stop at '/', '[a-z]' and '[^a-z]' classes, '\\x' escapes. null when malformed. */
+function globRegExp(pat) {
+  const cs = Array.from(pat)
+  let re = '^'
+  for (let i = 0; i < cs.length; i++) {
+    const c = cs[i]
+    if (c === '*') re += '[^/]*'
+    else if (c === '?') re += '[^/]'
+    else if (c === '\\') {
+      if (i + 1 >= cs.length) return null
+      re += regexEsc(cs[++i])
+    } else if (c === '[') {
+      let j = i + 1
+      let cls = '['
+      if (cs[j] === '^') {
+        cls += '^'
+        j++
+      }
+      let n = 0
+      for (; j < cs.length && (cs[j] !== ']' || n === 0); j++, n++) {
+        if (cs[j] === '\\') {
+          if (j + 1 >= cs.length) return null
+          cls += regexEsc(cs[++j])
+        } else if (cs[j] === '-') cls += '-'
+        else cls += regexEsc(cs[j])
+      }
+      if (j >= cs.length) return null
+      re += `${cls}]`
+      i = j
+    } else re += regexEsc(c)
+  }
+  try {
+    return new RegExp(`${re}$`, 'u')
+  } catch {
+    return null
+  }
+}
+
+const hasWildcard = (name) => {
+  for (let i = 0; i < name.length; i++) {
+    const c = name[i]
+    if (c === '\\') i++
+    else if (c === '*' || c === '?' || c === '[') return true
+  }
+  return false
+}
+
+/** fsutil splitWildcards: the folder part before the first component with a wildcard, and the rest. */
+function splitWildcards(p) {
+  const ps = clean(`/${p}`).split('/') // '' first
+  const p1 = []
+  const p2 = []
+  let found = false
+  for (let c of ps) {
+    if (!found && hasWildcard(c)) found = true
+    if (c === '') c = '/'
+    if (!found) p1.push(c)
+    else p2.push(c)
+  }
+  const j = (a) => clean(a.join('/'))
+  return { d1: j(p1), d2: p2.join('/') }
+}
+
+// ---------------------------------------------------------------- the context
+
+/** A folder of the build context, indexed: path ('/a/b', '/' the root) -> {type, mode, mtime, target, read}. */
+class Context {
+  constructor() {
+    this.map = new Map([['/', { type: 'dir', mode: 0o755, mtime: null, implicit: true }]])
+    this.kids = new Map()
+  }
+
+  add(path, e) {
+    const p = clean(path)
+    if (p === '/') {
+      // the root's mtime is not carried into BuildKit's local source (its snapshot root is made at transfer time): the build time
+      if (e.type === 'dir') this.map.set('/', { ...e, mtime: null, implicit: true })
+      return
+    }
+    for (let d = dirname(p); d !== '/'; d = dirname(d)) {
+      if (!this.map.has(d)) this.map.set(d, { type: 'dir', mode: 0o755, mtime: null, implicit: true })
+    }
+    this.map.set(p, e)
+  }
+
+  seal() {
+    this.kids = new Map()
+    for (const p of this.map.keys()) {
+      if (p === '/') continue
+      const d = dirname(p)
+      if (!this.kids.has(d)) this.kids.set(d, [])
+      this.kids.get(d).push(basename(p))
+    }
+    for (const l of this.kids.values()) l.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+    return this
+  }
+
+  lstat(p) {
+    return this.map.get(clean(p)) || null
+  }
+
+  children(p) {
+    return this.kids.get(clean(p)) || []
+  }
+
+  /** A copy without what .dockerignore patterns drop (a folder stays when something under it stays). */
+  filtered(ignoredFn) {
+    const keep = new Set(['/'])
+    for (const p of this.map.keys()) {
+      if (p === '/') continue
+      if (ignoredFn(p.slice(1))) continue
+      for (let d = p; d !== '/'; d = dirname(d)) keep.add(d)
+    }
+    const out = new Context()
+    for (const [p, e] of this.map) if (keep.has(p)) out.map.set(p, e)
+    return out.seal()
+  }
+}
+
+const TYPE_NAMES = { file: 'file', f: 'file', '0': 'file', '7': 'file', dir: 'dir', directory: 'dir', d: 'dir', '5': 'dir', symlink: 'symlink', link: 'symlink', l: 'symlink', '2': 'symlink' }
+
+/**
+ * The context as an indexed Context. Every source kind goes through context.js packContext (file source, plain object,
+ * tar; its limits, path checks and .dockerignore filtering for file sources and objects) and the tar it returns is read
+ * here, so modes and mtimes are the builder's. A tar passes through packContext unfiltered; applyDockerignore filters it.
+ */
+async function loadContext(input, { dockerfileName, limits, omitDockerfile } = {}) {
+  let tar
+  try {
+    ;({ tar } = await packContext(input, { dockerfileName, limits, ...(omitDockerfile ? { dockerfile: '' } : {}) }))
+  } catch (e) {
+    if (e instanceof ContextError) throw new FastRefused(e.message)
+    throw e
+  }
+  const ctx = new Context()
+  const norm = (p) => clean(`/${String(p).replace(/^(\.\/)+/, '')}`)
+  const entry = (raw, readFn) => {
+    const type = TYPE_NAMES[raw.type] || (raw.isDir ? 'dir' : raw.target || raw.linkname ? 'symlink' : 'file')
+    const mode = (raw.mode ?? (type === 'dir' ? 0o755 : 0o644)) & 0o7777
+    let mtime = raw.mtime ?? 0
+    if (mtime instanceof Date) mtime = Math.floor(mtime.getTime() / 1000)
+    const e = { type, mode, mtime: Number(mtime) }
+    if (type === 'symlink') e.target = raw.target ?? raw.linkname
+    if (type === 'file') e.read = readFn
+    return e
+  }
+  const byName = new Map()
+  const hard = []
+  for await (const t of scanTarBytes(tar)) {
+    const p = norm(t.name)
+    // the layer writer reads a file named .wh.* as a whiteout; BuildKit's copy would write it literally and the diff reads it as one
+    if (p.split('/').some(c => c.startsWith('.wh.'))) throw new FastRefused(`the context holds ${JSON.stringify(t.name)}, a name that means a whiteout in a layer`)
+    if (t.type === '1') {
+      hard.push([p, t])
+      continue
+    }
+    if (!(t.type in TYPE_NAMES) && t.type !== '\0') throw new FastRefused(`the context holds a special file (${JSON.stringify(t.name)}, tar type ${JSON.stringify(t.type)})`)
+    const data = tar.subarray(t.offset, t.offset + (t.type === '0' || t.type === '7' ? t.size : 0))
+    const e = entry({ type: t.type === '\0' ? '0' : t.type, mode: t.mode, mtime: t.mtime, target: t.linkname }, () => data)
+    byName.set(p, e)
+    ctx.add(p, e)
+  }
+  for (const [p, t] of hard) {
+    const tgt = byName.get(norm(t.linkname))
+    if (!tgt || tgt.type !== 'file') throw new FastRefused(`the context has a hard link to ${JSON.stringify(t.linkname)} that is not a file in it`)
+    ctx.add(p, { ...entry({ type: '0', mode: t.mode, mtime: t.mtime }, tgt.read), hard: true })
+  }
+  return ctx.seal()
+}
+
+async function applyDockerignore(ctx, dockerfileName) {
+  for (const name of [`${dockerfileName}.dockerignore`, '.dockerignore']) {
+    const e = ctx.lstat(`/${name}`)
+    if (e && e.type === 'file') {
+      const text = decodeText(await e.read())
+      const patterns = parseDockerignore(text)
+      if (patterns.length === 0) return ctx
+      const m = matcher(patterns)
+      return ctx.filtered((p) => m.ignored(p, ctx.lstat(`/${p}`)?.type === 'dir'))
+    }
+  }
+  return ctx
+}
+
+// ---------------------------------------------------------------- accounts (ops/user_unix.go readUser)
+
+// moby/sys/user ParsePasswdFilter / ParseGroupFilter: lines are trimmed, a blank line is skipped (a group file also skips
+// '#' lines), fields missing from a short line stay at their zero value, and a number that does not parse is 0.
+const goAtoi = (x) => (x !== undefined && /^[+-]?\d+$/.test(x) ? Number(x) : 0)
+const goTrim = (x) => x.replace(/^[\t\n\v\f\r \u0085\u00a0]+|[\t\n\v\f\r \u0085\u00a0]+$/g, '')
+function parsePasswd(text) {
+  const out = []
+  for (const raw of text.split('\n')) {
+    const line = goTrim(raw)
+    if (line === '') continue
+    const f = line.split(':')
+    out.push({ name: f[0], uid: goAtoi(f[2]), gid: goAtoi(f[3]) })
+  }
+  return out
+}
+function parseGroup(text) {
+  const out = []
+  for (const raw of text.split('\n')) {
+    const line = goTrim(raw)
+    if (line === '' || line[0] === '#') continue
+    const f = line.split(':')
+    out.push({ name: f[0], gid: goAtoi(f[2]) })
+  }
+  return out
+}
+
+const parseUID = (s) => {
+  if (s === 'root') return 0
+  if (!/^[+-]?\d+$/.test(s)) return null
+  const n = Number(s)
+  return n >= -(2 ** 31) && n < 2 ** 31 ? n : null
+}
+
+/**
+ * llb.WithUser(spec) read against the account files: "name", "uid", "name:group", "uid:gid". A number is the uid AND the
+ * gid (no group); a name takes its passwd uid and gid; a name that is not in the file is 0 (0:0), with no error; a
+ * group name is looked up in /etc/group and left alone when absent.
+ * @returns {{uid: number, gid: number}}
+ */
+export function readUserSpec(spec, { passwd = '', group = '' } = {}) {
+  const [u, g] = spec.includes(':') ? [spec.slice(0, spec.indexOf(':')), spec.slice(spec.indexOf(':') + 1)] : [spec, null]
+  const us = { uid: 0, gid: 0 }
+  const uid = parseUID(u)
+  if (uid !== null) us.uid = us.gid = uid
+  else {
+    const row = parsePasswd(passwd).find((r) => r.name === u)
+    if (row) {
+      us.uid = row.uid
+      us.gid = row.gid
+    }
+  }
+  if (g !== null) {
+    // "app:" and "7:" leave the group empty: WithUser marshals it as ByID 0, so the gid is 0 (client/llb/fileop.go)
+    if (g === '') us.gid = 0
+    else {
+      const gid = parseUID(g)
+      if (gid !== null) us.gid = gid
+      else {
+        const row = parseGroup(group).find((r) => r.name === g)
+        if (row) us.gid = row.gid
+      }
+    }
+  }
+  return us
+}
+
+/** An owner the layer tar can hold (BuildKit marshals ids as uint32): FastRefused otherwise, before any work is done. */
+function checkOwner(o, what) {
+  for (const k of ['uid', 'gid']) {
+    if (!Number.isInteger(o[k]) || o[k] < 0 || o[k] > 0xffffffff) throw new FastRefused(`${what}: ${k} ${o[k]} is not an id a layer can hold`)
+  }
+  return o
+}
+
+const specNeedsAccounts = (spec) => {
+  const [u, g] = spec.includes(':') ? [spec.slice(0, spec.indexOf(':')), spec.slice(spec.indexOf(':') + 1)] : [spec, null]
+  return parseUID(u) === null || (g !== null && parseUID(g) === null)
+}
+
+// ---------------------------------------------------------------- eligibility
+
+const PLATFORM_ARGS = ['BUILDPLATFORM', 'BUILDOS', 'BUILDOSVERSION', 'BUILDARCH', 'BUILDVARIANT', 'TARGETPLATFORM', 'TARGETOS', 'TARGETOSVERSION', 'TARGETARCH', 'TARGETVARIANT', 'TARGETSTAGE']
+const SIGNALS = new Set([
+  'HUP', 'INT', 'QUIT', 'ILL', 'TRAP', 'ABRT', 'BUS', 'FPE', 'KILL', 'USR1', 'SEGV', 'USR2', 'PIPE', 'ALRM', 'TERM', 'STKFLT', 'CHLD', 'CONT', 'STOP',
+  'TSTP', 'TTIN', 'TTOU', 'URG', 'XCPU', 'XFSZ', 'VTALRM', 'PROF', 'WINCH', 'IO', 'PWR', 'SYS',
+])
+const validSignal = (s) => /^\d+$/.test(s) ? Number(s) >= 0 && Number(s) <= 64 : SIGNALS.has(s.replace(/^SIG/, '')) || /^(SIG)?RTM(IN|AX)(\+\d+)?$/.test(s)
+
+/** The predefined global args (defaultArgs): BUILDPLATFORM... for a build and target of the one platform. */
+function globalArgsFor(platform, targetName) {
+  const p = parsePlatform(platform)
+  const s = platformString(p)
+  const env = new Env([
+    ['BUILDPLATFORM', s], ['BUILDOS', p.os], ['BUILDOSVERSION', ''], ['BUILDARCH', p.architecture], ['BUILDVARIANT', p.variant],
+    ['TARGETPLATFORM', s], ['TARGETOS', p.os], ['TARGETOSVERSION', ''], ['TARGETARCH', p.architecture], ['TARGETVARIANT', p.variant],
+    ['TARGETSTAGE', targetName || 'default'],
+  ])
+  return env
+}
+
+/** A word BuildKit expands: checks, without values, that it expands at all (a modifier or a bad quote refuses). */
+function checkWord(word, what) {
+  try {
+    expandWord(word, { get: () => '' })
+  } catch (e) {
+    if (e instanceof FallbackError) throw new FastRefused(`${what}: ${e.why}`)
+    throw new FastRefused(`${what}: ${e.message}`)
+  }
+}
+
+const REMOTE_SRC = /^(https?:\/\/|git@|git:\/\/|ssh:\/\/|ftp:\/\/|github\.com\/)/
+
+/**
+ * Decides before any work. {ok: true, plan} | {ok: false, why}. `args`: build args; `target`: the target stage (default the
+ * last); `platform`: the build's (default linux/arm64).
+ */
+export function fastEligible(text, { args = {}, target = '', platform = 'linux/arm64' } = {}) {
+  const no = (why) => ({ ok: false, why })
+  let df
+  try {
+    df = parseDockerfile(text)
+  } catch (e) {
+    if (e instanceof DockerfileError) return no(`the Dockerfile does not parse (${e.message}); BuildKit reports it`)
+    throw e
+  }
+  try {
+    // directives.go discardShebang: a leading `#!` line is skipped before `# syntax=` is read, so the frontend may be another one
+    if (/^\uFEFF?#!/.test(text)) return no('a #! line before the Dockerfile (BuildKit reads the syntax directive after it)')
+    for (const name of Object.keys(df.directives)) return no(`the parser directive # ${name}= (BuildKit's frontend decides what it means)`)
+    if (df.metaArgs.length) return no('ARG before FROM')
+    for (const k of Object.keys(args)) {
+      if (PLATFORM_ARGS.includes(k)) return no(`the build arg ${k} (it changes the platform BuildKit builds for)`)
+      if (k === 'SOURCE_DATE_EPOCH' || k.startsWith('BUILDKIT_')) return no(`the build arg ${k} (a BuildKit control)`)
+    }
+    let want
+    try {
+      want = parsePlatform(platform)
+    } catch (e) {
+      return no(`the platform: ${e.message}`)
+    }
+    const stage = pickStage(df, target)
+    if (!stage.stage) return no(stage.why)
+    const st = stage.stage
+    const idx = stage.index
+
+    // FROM: BuildKit expands the FROM of every stage, reachable or not (convert.go buildDispatchStates)
+    for (const s2 of df.stages) if (s2.baseName.includes('$')) return no('a variable in FROM')
+    const base = st.baseName
+    if (base.toLowerCase() === 'scratch') return no('FROM scratch')
+    for (let j = 0; j < idx; j++) if (df.stages[j].name && df.stages[j].name === base) return no(`FROM <earlier stage> (${base})`)
+    try {
+      parseRef(base)
+    } catch (e) {
+      return no(`FROM ${base}: ${e.message}`)
+    }
+    if (st.platform) {
+      const g = globalArgsFor(platform, st.name || (df.stages[df.stages.length - 1].name))
+      let v
+      try {
+        v = expandWord(st.platform, g)
+      } catch (e) {
+        return no(`FROM --platform=${st.platform}: ${e.message}`)
+      }
+      let p
+      try {
+        p = parsePlatform(v)
+      } catch {
+        return no(`FROM --platform=${st.platform}: not a platform`)
+      }
+      if (platformString(p) !== platformString(want)) return no(`FROM --platform=${v} is not the build's platform`)
+    }
+
+    const steps = []
+    for (const c of st.commands) {
+      const where = `line ${c.line}`
+      switch (c.type) {
+        case 'run': return no(`RUN (${where})`)
+        case 'add': return no(`ADD (${where})`)
+        case 'shell': return no(`SHELL (${where})`)
+        case 'onbuild': return no(`ONBUILD (${where})`)
+        case 'maintainer': return no(`MAINTAINER (${where})`)
+        case 'copy': {
+          if (c.from) return no(`COPY --from (${where})`)
+          if (c.link) return no(`COPY --link (${where})`)
+          if (c.parents) return no(`COPY --parents (${where})`)
+          if (c.exclude.length) return no(`COPY --exclude (${where})`)
+          if (c.contents.length) return no(`a heredoc in COPY (${where})`)
+          for (const s of c.sources) if (REMOTE_SRC.test(s)) return no(`COPY of a URL or git source (${where})`)
+          for (const w of [...c.sources, c.dest, c.chown, c.chmod]) checkWord(w, `COPY (${where})`)
+          if (c.chmod) {
+            let m
+            try {
+              m = expandWord(c.chmod, { get: () => '' })
+            } catch {
+              m = null
+            }
+            if (m !== null && c.chmod === m && (!/^[0-7]+$/.test(m) || parseInt(m, 8) > 0o7777)) return no(`COPY --chmod=${m} is not an octal mode of 0..07777 (${where})`)
+          }
+          if (c.chown && !c.chown.includes('$')) {
+            // numeric ids go into a layer tar as they are: only 0..4294967295 can be held (BuildKit marshals uint32)
+            const [uu, gg] = c.chown.includes(':') ? [c.chown.slice(0, c.chown.indexOf(':')), c.chown.slice(c.chown.indexOf(':') + 1)] : [c.chown, '']
+            for (const x of [uu, gg]) if (/^[+-]?\d+$/.test(x) && (Number(x) < 0 || Number(x) > 0xffffffff)) return no(`COPY --chown=${c.chown}: an id outside 0..4294967295 (${where})`)
+          }
+          steps.push(c)
+          break
+        }
+        case 'env':
+        case 'label':
+          for (const p of c.pairs) {
+            checkWord(p.key, `${c.type.toUpperCase()} (${where})`)
+            checkWord(p.value, `${c.type.toUpperCase()} (${where})`)
+          }
+          steps.push(c)
+          break
+        case 'arg':
+          for (const a of c.args) if (a.value !== null) checkWord(a.value, `ARG (${where})`)
+          steps.push(c)
+          break
+        case 'workdir':
+          checkWord(c.path, `WORKDIR (${where})`)
+          steps.push(c)
+          break
+        case 'user':
+          checkWord(c.user, `USER (${where})`)
+          steps.push(c)
+          break
+        case 'volume':
+          for (const v of c.volumes) checkWord(v, `VOLUME (${where})`)
+          steps.push(c)
+          break
+        case 'stopsignal':
+          checkWord(c.signal, `STOPSIGNAL (${where})`)
+          steps.push(c)
+          break
+        case 'expose':
+          for (const p of c.ports) checkWord(p, `EXPOSE (${where})`)
+          steps.push(c)
+          break
+        case 'cmd':
+        case 'entrypoint':
+          if (c.cmdline.length === 0) return no(`an empty ${c.type.toUpperCase()} (${where})`)
+          steps.push(c)
+          break
+        case 'healthcheck':
+          steps.push(c)
+          break
+        default:
+          return no(`${c.type.toUpperCase()} (${where})`)
+      }
+    }
+    const lastName = df.stages[df.stages.length - 1].name
+    const plan = {
+      from: { ref: base, platform: platformString(want) },
+      stage: { name: st.name, index: idx },
+      targetName: target || lastName || '',
+      platform: platformString(want),
+      steps,
+      args: { ...args },
+      escape: df.escape,
+    }
+    return { ok: true, plan }
+  } catch (e) {
+    if (e instanceof FallbackError) return no(e.why)
+    throw e
+  }
+}
+
+function pickStage(df, target) {
+  if (!df.stages.length) return { why: 'the Dockerfile has no stages' }
+  if (!target) return { stage: df.stages[df.stages.length - 1], index: df.stages.length - 1 }
+  const t = target.toLowerCase()
+  const i = df.stages.findLastIndex((s) => s.name === t) // addState: with a name given twice the last stage is the one named
+  if (i < 0) return { why: `the target stage ${JSON.stringify(target)} is not in the Dockerfile` }
+  return { stage: df.stages[i], index: i }
+}
+
+// ---------------------------------------------------------------- the image under construction
+
+const packCache = new WeakMap()
+function openPack(bytes, name) {
+  let p = packCache.get(bytes)
+  if (!p) {
+    p = new Pack(bytesSource(bytes), name)
+    packCache.set(bytes, p)
+  }
+  return p
+}
+
+/** The image as the steps so far made it: reads through the packs, top first. */
+class Rootfs {
+  constructor(stack) {
+    this.files = new ImageFiles(new Overlay({ layers: stack.slice().reverse().map((l, i) => openPack(l.bytes, `layer ${i}`)) }))
+  }
+
+  /** {type, mode, uid, gid, mtime, target?} without following the last component, or null. */
+  lstat(path) {
+    try {
+      const s = this.files.stat(path, false)
+      return s && { type: s.type, mode: s.mode, uid: s.uid, gid: s.gid, target: s.target, mtime: Number((s.mtime ?? 0n) / 1000000000n) }
+    } catch (e) {
+      if (e instanceof FsError) return null
+      throw e
+    }
+  }
+
+  text(path) {
+    try {
+      return this.files.readText(path)
+    } catch (e) {
+      if (e instanceof FsError) return null
+      throw e
+    }
+  }
+}
+
+/** The files one instruction writes, over the image: a Map path -> entry in the order they go in the tar. */
+class Pending {
+  constructor(rootfs, now) {
+    this.rootfs = rootfs
+    this.map = new Map()
+    this.now = now
+  }
+
+  lstat(path) {
+    const p = clean(path)
+    if (p === '/') return { type: 'dir', mode: 0o755 }
+    return this.map.get(p) || this.rootfs.lstat(p)
+  }
+
+  /** os.Stat: follows symlinks (through the image) to what they name; null when it is missing. */
+  stat(path) {
+    const real = realPath(path, (p) => this.lstat(p), true)
+    const s = this.lstat(real)
+    return s && s.type === 'symlink' ? null : s
+  }
+
+  /** fsutil MkdirAll: every missing folder is made with perm and the owner; existing ones are left alone. */
+  mkdirAll(path, perm, owner) {
+    const ps = parts(path)
+    let cur = ''
+    for (const c of ps) {
+      cur = `${cur}/${c}`
+      const s = this.lstat(cur)
+      if (s) {
+        if (s.type === 'dir') continue
+        if (s.type === 'symlink') {
+          const t = this.stat(cur)
+          if (t && t.type === 'dir') continue
+        }
+        throw new FastRefused(`${cur} is not a directory`)
+      }
+      // os.Mkdir with a raw int mode keeps the permission bits only: no setuid, setgid or sticky on a folder made here
+      this.map.set(cur, { type: 'dir', mode: perm & 0o777, uid: owner?.uid ?? 0, gid: owner?.gid ?? 0, mtime: this.now, created: true })
+    }
+  }
+}
+
+/** The part of fsutil copy.Copy that decides what a COPY writes, for one resolved source. */
+function copyOne({ ctx, pending, src, dest, owner, mode, now, pathMtimeRoot }) {
+  // dest: cleanPath() of the destination as dispatchCopy built it ('/app/', '/app', '/app/.')
+  const slash = dest.lastIndexOf('/')
+  const d = dest.slice(0, slash + 1)
+  const f = dest.slice(slash + 1)
+  const ensure = f !== '' && f !== '.' ? d : dest
+  const perm = mode ?? 0o755
+  const lst = (p) => pending.lstat(p)
+  pending.mkdirAll(realPath(ensure, lst, true), perm, owner)
+  const dst = realPath(clean(dest), lst, true)
+
+  const srcFollowed = realPath(src, (p) => ctx.lstat(p), true)
+  const fiSrc = ctx.lstat(srcFollowed)
+  if (!fiSrc) throw new FastRefused(`${src}: not found in the build context`)
+  const fiDest = pending.stat(dst)
+  let destPath = dst
+  if (fiSrc.type !== 'dir' && fiDest && fiDest.type === 'dir') destPath = join(dst, basename(src))
+  let target = dirname(destPath)
+  if (fiSrc.type === 'dir' && !fiDest) target = destPath
+  pending.mkdirAll(target, perm, owner)
+
+  const own = (e) => ({ uid: owner?.uid ?? 0, gid: owner?.gid ?? 0, ...e })
+  const copyNode = (sp, tp, overwrite) => {
+    const fi = ctx.lstat(sp)
+    const tfi = pending.lstat(tp)
+    if (fi.type !== 'dir') {
+      if (tfi && tfi.type === 'dir') throw new FastRefused(`cannot replace to directory ${tp} with file`)
+      const common = { mode: (mode ?? fi.mode) & 0o7777, mtime: fi.mtime ?? 0 }
+      if (fi.hard) throw new FastRefused(`${sp} is a hard link in the context; the layer would hold a link, which this path does not write`)
+      if (fi.type === 'file') pending.map.set(tp, own({ type: 'file', from: sp, ...common }))
+      else pending.map.set(tp, own({ type: 'symlink', target: fi.target, mtime: fi.mtime ?? 0 }))
+      return
+    }
+    // a folder
+    let created = false
+    if (!tfi) {
+      created = true
+    } else if (tfi.type !== 'dir') {
+      throw new FastRefused(`cannot copy to non-directory: ${tp}`)
+    }
+    const mt = fi.mtime ?? (fi.implicit ? now : 0)
+    if (created) pending.map.set(tp, own({ type: 'dir', mode: (mode ?? fi.mode) & 0o7777, mtime: mt, created: true }))
+    else if (overwrite) pending.map.set(tp, own({ type: 'dir', mode: (mode ?? fi.mode) & 0o7777, mtime: mt }))
+    else {
+      // the top folder of the source: left as it is, only its time is restored (to the source's) when this COPY made it
+      const mine = pending.map.get(tp)
+      if (mine) mine.mtime = fi.mtime ?? pathMtimeRoot
+      // a folder of the image: copy.go restores its time to the source's (restoreFileTimestamp); mode and owner stay
+      else if (tfi.type === 'dir' && tp !== '/') pending.map.set(tp, { type: 'dir', mode: tfi.mode, uid: tfi.uid, gid: tfi.gid, mtime: fi.mtime ?? pathMtimeRoot })
+    }
+    for (const name of ctx.children(sp)) copyNode(join(sp, name), join(tp, name), true)
+  }
+  copyNode(srcFollowed, destPath, false)
+}
+
+/**
+ * What a layer holds: the entries the instruction wrote, and every existing folder above them (overlayfs copies an ancestor
+ * up when something is written below it): with the base's mode and owner, and the build time when the folder gained a new
+ * direct child, else the base's own mtime. Parents come before children.
+ */
+function layerEntries(pending) {
+  const out = new Map(pending.map)
+  const gains = new Set()
+  for (const [p, e] of pending.map) if (e.created || !pending.rootfs.lstat(p)) gains.add(dirname(p))
+  for (const p of pending.map.keys()) {
+    for (let d = dirname(p); d !== '/'; d = dirname(d)) {
+      if (out.has(d)) continue
+      const st = pending.rootfs.lstat(d)
+      if (st?.type !== 'dir') continue
+      out.set(d, { type: 'dir', mode: st.mode, uid: st.uid, gid: st.gid, mtime: gains.has(d) ? pending.now : st.mtime })
+    }
+  }
+  const key = (p) => p.split('/')
+  return [...out].sort(([a], [b]) => {
+    const x = key(a)
+    const y = key(b)
+    for (let i = 0; i < Math.min(x.length, y.length); i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1
+    return x.length - y.length
+  })
+}
+
+/** The tar of a Pending: parents before children, paths without the leading '/'. */
+async function pendingTar(pending, ctx) {
+  const tw = tarWriter()
+  for (const [path, e] of layerEntries(pending)) {
+    const name = tarName(path)
+    const o = { mode: e.mode, mtime: e.mtime, uid: e.uid, gid: e.gid }
+    if (e.type === 'dir') tw.dir(name, o)
+    else if (e.type === 'symlink') tw.symlink(name, e.target, { mtime: e.mtime, uid: e.uid, gid: e.gid })
+    else tw.file(name, await ctx.lstat(e.from).read(), o)
+  }
+  return tw.finish()
+}
+
+// ---------------------------------------------------------------- history lines (what BuildKit writes in created_by)
+
+const goKV = (p) => `${p.key}=${p.value}`
+function healthString(h) {
+  const dur = (n) => goDurationString(n || 0)
+  return `{Test:[${h.Test.join(' ')}] Interval:${dur(h.Interval)} Timeout:${dur(h.Timeout)} StartPeriod:${dur(h.StartPeriod)} StartInterval:${dur(h.StartInterval)} Retries:${h.Retries || 0}}`
+}
+
+const nowIso = (sec) => new Date(sec * 1000).toISOString().replace('.000Z', 'Z')
+
+// ---------------------------------------------------------------- fastBuild
+
+/**
+ * @param {object} o
+ * @param {object} o.plan from fastEligible
+ * @param {*} o.context what packContext takes: a file source {list, stat, read}, {[path]: bytes|string}, or a tar
+ *   (Uint8Array, ArrayBuffer, Blob); .dockerignore is applied as the builder does
+ * @param {(ref: string) => Promise<{index: object, packs: Uint8Array[], rawConfig: object}>} o.pull the base, as pullImage returns it
+ *   (packs top first); rawConfig (the base's OCI image config JSON: history, rootfs.diff_ids, config.OnBuild...) is required:
+ *   without it the build is refused (FastRefused) rather than guessing ONBUILD triggers or diff ids
+ * @param {object} o.converter a converter from createConverter, or wmdpack.wasm (URL, bytes, Module)
+ * @param {string} [o.platform] must be the plan's (and the base's)
+ * @param {object} [o.args] build args
+ * @param {string} [o.target]
+ * @param {(e: object) => void} [o.onEvent] {t:'pull'|'step'|'convert'|'done', ...}
+ * @param {number} [o.now] seconds (default the clock): the mtime of folders BuildKit makes itself, and `created`
+ * @param {boolean} [o.omitDockerfile] the Dockerfile text was given apart from the context: leave the context's own Dockerfile out, as the builder does
+ * @param {string} [o.dockerfile] the Dockerfile's name in the context, for <name>.dockerignore (default 'Dockerfile')
+ * @param {string} [o.ref] the image's name for index.ref
+ * @param {boolean} [o.baseInConverter] the converter already holds the base's packs
+ * @param {boolean} [o.keepTars] return the layer tars (r.tars) too
+ */
+export async function fastBuild(o) {
+  const t0 = performance.now()
+  const { plan, pull, onEvent = () => {} } = o
+  if (!plan?.steps) throw new TypeError('fastBuild: pass the plan from fastEligible')
+  if (typeof pull !== 'function') throw new TypeError('fastBuild: pass pull(ref)')
+  if (!o.converter) throw new TypeError('fastBuild: pass converter')
+  const platform = platformString(parsePlatform(o.platform || plan.platform))
+  if (platform !== plan.platform) throw new FastRefused(`the plan is for ${plan.platform}, not ${platform}`)
+  const args = o.args ?? plan.args ?? {}
+  const now = Math.floor(o.now ?? Date.now() / 1000)
+  const created = nowIso(now)
+  const escape = plan.escape || '\\'
+
+  onEvent({ t: 'pull', ref: plan.from.ref })
+  const base = await pull(plan.from.ref)
+  if (!base?.index?.layers?.length) throw new FastRefused(`the base ${plan.from.ref} has no layers`)
+  if (base.index.platform && base.index.platform !== platform) throw new FastRefused(`the base is ${base.index.platform}, not ${platform}`)
+
+  const full = base.rawConfig
+  if (!full || typeof full !== 'object' || !Array.isArray(full.rootfs?.diff_ids)) {
+    throw new FastRefused(`the base ${plan.from.ref} has no raw OCI config (rootfs.diff_ids, history, ONBUILD)`)
+  }
+  const cfg = structuredClone(full.config || {})
+  if (cfg.OnBuild && cfg.OnBuild.length) throw new FastRefused('ONBUILD in the base image config')
+  delete cfg.OnBuild
+  if (cfg.WorkingDir && !cfg.WorkingDir.startsWith('/')) cfg.WorkingDir = normalizeWorkdir('/', cfg.WorkingDir)
+  const baseHistory = full.history ? structuredClone(full.history) : []
+  // the base's layers, bottom first
+  const stack = base.index.layers.map((l, i) => ({ pack: l.pack, size: l.size, layer: l.layer, bytes: base.packs[i] })).reverse()
+  const diffIds = [...full.rootfs.diff_ids]
+  if (diffIds.length !== stack.length) throw new FastRefused('the base config lists a different number of layers than its manifest')
+
+  let ctx = await loadContext(o.context, { dockerfileName: o.dockerfile || 'Dockerfile', limits: o.limits, omitDockerfile: !!o.omitDockerfile })
+  ctx = await applyDockerignore(ctx, o.dockerfile || 'Dockerfile')
+
+  const ownConverter = typeof o.converter.convert !== 'function'
+  const conv = ownConverter ? await createConverter(o.converter) : o.converter
+  const newHistory = []
+  const tars = []
+  let built = 0
+  let layerBytes = 0
+  let convertMs = 0
+  try {
+    if (!o.baseInConverter || ownConverter) for (let i = stack.length - 1; i >= 0; i--) await conv.add(stack[i].pack, stack[i].bytes)
+
+    // PATH is always set; the state's env is the config's plus ARGs and ENVs, in order
+    cfg.Env = cfg.Env ? [...cfg.Env] : []
+    if (!cfg.Env.some((e) => e.split('=')[0] === 'PATH')) cfg.Env.push(`PATH=${DEFAULT_PATH}`)
+    const env = new Env(cfg.Env.map((e) => (e.includes('=') ? [e.slice(0, e.indexOf('=')), e.slice(e.indexOf('=') + 1)] : [e, ''])))
+    const globals = globalArgsFor(platform, plan.targetName)
+    let cmdSeen = false
+    let accountsDirty = false
+    let rootfs = new Rootfs(stack)
+    const accounts = () => ({ passwd: rootfs.text('/etc/passwd') || '', group: rootfs.text('/etc/group') || '' })
+    const expand = (w, what) => {
+      try {
+        return expandWord(w, env, { escape })
+      } catch (e) {
+        throw new FastRefused(`${what}: ${e.message}`)
+      }
+    }
+    const history = (createdBy, layer) => newHistory.push({ created: created, created_by: createdBy, comment: HISTORY_COMMENT, ...(layer ? {} : { empty_layer: true }) })
+
+    const total = plan.steps.length
+    for (let i = 0; i < total; i++) {
+      const c = plan.steps[i]
+      onEvent({ t: 'step', i: i + 1, total, text: c.original, state: 'start' })
+      let pendingMap = null
+      let createdBy
+      switch (c.type) {
+        case 'env': {
+          // convert.go dispatch: every pair is expanded against the env from before the instruction, then all are set
+          let msg = 'ENV'
+          const kvs = c.pairs.map((p) => [expand(p.key, 'ENV'), expand(p.value, 'ENV')])
+          for (const [k, v] of kvs) {
+            msg += ` ${k}=${v}`
+            env.set(k, v)
+            const j = cfg.Env.findIndex((e) => e.split('=')[0] === k)
+            if (j >= 0) cfg.Env[j] = `${k}=${v}`
+            else cfg.Env.push(`${k}=${v}`)
+          }
+          createdBy = msg
+          break
+        }
+        case 'label': {
+          cfg.Labels ||= {}
+          let msg = 'LABEL'
+          for (const p of c.pairs) {
+            const k = expand(p.key, 'LABEL')
+            const v = expand(p.value, 'LABEL')
+            cfg.Labels[k] = v
+            msg += ` ${k}=${v}`
+          }
+          createdBy = msg
+          break
+        }
+        case 'arg': {
+          const strs = []
+          for (const a of c.args) {
+            const given = Object.prototype.hasOwnProperty.call(args, a.key)
+            let v = a.value
+            if (v === null && !given && globals.has(a.key)) v = globals.get(a.key)
+            if (given) v = String(args[a.key])
+            else if (a.value !== null) v = expand(a.value, 'ARG')
+            if (v !== null) env.set(a.key, v)
+            strs.push(v !== null ? `${a.key}=${v}` : a.key)
+          }
+          createdBy = `ARG ${strs.join(' ')}`
+          break
+        }
+        case 'workdir': {
+          const wd = normalizeWorkdir(cfg.WorkingDir || '', expand(c.path, 'WORKDIR'))
+          cfg.WorkingDir = wd
+          createdBy = `WORKDIR ${wd}`
+          if (wd !== '/') {
+            const pend = new Pending(rootfs, now)
+            let owner = null
+            if (cfg.User) {
+              if (specNeedsAccounts(cfg.User) && accountsDirty) throw new FastRefused('WORKDIR as a named USER after a COPY that wrote /etc/passwd or /etc/group')
+              owner = checkOwner(readUserSpec(cfg.User, accounts()), `USER ${cfg.User}`)
+            }
+            const real = realPath(clean(wd), (p) => pend.lstat(p), true)
+            pend.mkdirAll(real, 0o755, owner)
+            // the layer is made even when the folder is there already: MkdirAll then changes nothing (no chown either), so it is empty
+            pendingMap = pend
+          }
+          break
+        }
+        case 'user': {
+          cfg.User = expand(c.user, 'USER')
+          createdBy = `USER ${cfg.User}`
+          break
+        }
+        case 'volume': {
+          cfg.Volumes ||= {}
+          const vs = c.volumes.map((v) => expand(v, 'VOLUME'))
+          for (const v of vs) {
+            if (v === '') throw new FastRefused('VOLUME specified can not be an empty string')
+            cfg.Volumes[v] = {}
+          }
+          createdBy = `VOLUME [${vs.join(' ')}]`
+          break
+        }
+        case 'stopsignal': {
+          const sig = expand(c.signal, 'STOPSIGNAL')
+          if (!validSignal(sig)) throw new FastRefused(`STOPSIGNAL ${sig}: not a signal this port knows`)
+          cfg.StopSignal = sig
+          createdBy = `STOPSIGNAL ${sig}`
+          break
+        }
+        case 'expose': {
+          const ports = []
+          for (const p of c.ports) {
+            const ws = []
+            expandWord(p, env, { escape, words: ws })
+            for (const w of ws) ports.push(...parsePorts(w))
+          }
+          cfg.ExposedPorts ||= {}
+          for (const p of ports) cfg.ExposedPorts[p] = {}
+          createdBy = `EXPOSE [${ports.join(' ')}]`
+          break
+        }
+        case 'cmd':
+        case 'entrypoint': {
+          let line = c.cmdline
+          if (c.shell) line = [...(cfg.Shell?.length ? cfg.Shell : DEFAULT_SHELL), c.cmdline.join(' ')]
+          if (c.type === 'cmd') {
+            cfg.Cmd = line
+            cfg.ArgsEscaped = true
+            cmdSeen = true
+          } else {
+            cfg.Entrypoint = line
+            if (!cmdSeen) delete cfg.Cmd
+          }
+          createdBy = `${c.type.toUpperCase()} ${goQuoteList(line)}`
+          break
+        }
+        case 'healthcheck': {
+          cfg.Healthcheck = { ...c.health }
+          createdBy = `HEALTHCHECK ${healthString(c.health)}`
+          break
+        }
+        case 'copy': {
+          const srcs = c.sources.map((s) => expand(s, 'COPY'))
+          const destArg = expand(c.dest, 'COPY')
+          const chown = expand(c.chown, 'COPY')
+          const chmodS = expand(c.chmod, 'COPY')
+          let mode = null
+          if (chmodS !== '') {
+            if (!/^[0-7]+$/.test(chmodS) || parseInt(chmodS, 8) > 0o7777) throw new FastRefused(`COPY --chmod=${chmodS}: not an octal mode (0..07777)`)
+            mode = parseInt(chmodS, 8)
+          }
+          let owner = null
+          if (chown !== '') {
+            if (specNeedsAccounts(chown) && accountsDirty) throw new FastRefused(`COPY --chown=${chown} after a COPY that wrote /etc/passwd or /etc/group`)
+            owner = checkOwner(readUserSpec(chown, accounts()), `COPY --chown=${chown}`)
+          }
+          // pathRelativeToWorkingDir: '.' and '' are './' (a folder), a relative path is under the workdir
+          const wdir = cfg.WorkingDir || '/'
+          const dest = cleanDest(destArg.startsWith('/') ? normalizePath('/', destArg, true) : normalizePath(wdir, destArg === '.' || destArg === '' ? './' : destArg, true))
+          const pend = new Pending(rootfs, now)
+          const cleanSrcs = srcs.map((s) => normalizePath('/', s, false))
+          for (const s of cleanSrcs) {
+            const { d1, d2 } = splitWildcards(s)
+            let list
+            if (d2 === '') list = [d1]
+            else {
+              list = resolveWildcards(ctx, d1, d2)
+              if (list.length === 0) continue // AllowEmptyWildcard
+            }
+            for (const m of list) copyOne({ ctx, pending: pend, src: m, dest, owner, mode, now, pathMtimeRoot: ctx.lstat('/')?.mtime ?? now })
+          }
+          let msg = 'COPY'
+          if (c.chown) msg += ` --chown=${chown}`
+          if (c.chmod) msg += ` --chmod=${chmodS}`
+          for (const s of srcs) msg += ` ${s}`
+          msg += ` ${destArg}`
+          createdBy = `${msg} # buildkit`
+          pendingMap = pend // a COPY that matched nothing still makes its (empty) layer
+          if ([...pend.map.keys()].some((p) => p === '/etc/passwd' || p === '/etc/group')) accountsDirty = true
+          break
+        }
+        default:
+          throw new FastRefused(`${c.type.toUpperCase()} is not part of the fast path`)
+      }
+
+      if (pendingMap) {
+        const tar = await pendingTar(pendingMap, ctx)
+        if (o.keepTars) tars.push(tar.slice())
+        const diff = await sha256(tar)
+        layerBytes += tar.length
+        const below = stack.map((l) => l.pack).reverse()
+        const r = await conv.convert(tar, below)
+        convertMs += r.ms || 0
+        stack.push({ pack: r.sha, size: r.size, layer: diff, bytes: r.bytes })
+        diffIds.push(diff)
+        built++
+        rootfs = new Rootfs(stack)
+        onEvent({ t: 'convert', i: i + 1, pack: r.sha, size: r.size, ms: r.ms })
+        history(createdBy, true)
+      } else history(createdBy, false)
+      onEvent({ t: 'step', i: i + 1, total, text: c.original, state: 'done', layer: !!pendingMap })
+    }
+  } finally {
+    if (ownConverter) conv.close()
+  }
+
+  // the image config, as the dockerfile frontend and the exporter write it
+  const MAP_FIELDS = new Set(['ExposedPorts', 'Volumes', 'Labels'])
+  const cfgOut = {}
+  for (const k of ['User', 'ExposedPorts', 'Env', 'Entrypoint', 'Cmd', 'Volumes', 'WorkingDir', 'Labels', 'StopSignal', 'ArgsEscaped', 'Healthcheck', 'Shell']) {
+    const v = cfg[k]
+    if (v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0)) continue
+    // Go's omitempty leaves out an empty map too (ExposedPorts, Volumes, Labels); Healthcheck is a pointer and stays
+    if (MAP_FIELDS.has(k) && typeof v === 'object' && Object.keys(v).length === 0) continue
+    cfgOut[k] = v
+  }
+  const config = {
+    created,
+    architecture: base.index.architecture || full.architecture || parsePlatform(platform).architecture,
+    os: base.index.os || full.os || 'linux',
+    config: cfgOut,
+    rootfs: { type: 'layers', diff_ids: diffIds },
+    history: [...baseHistory, ...newHistory],
+  }
+  // only what BuildKit's typed image (DockerOCIImage) has fields for: docker_version, container, container_config and the rest are dropped
+  for (const k of ['author', 'variant', 'os.version', 'os.features']) if (full[k] !== undefined) config[k] = full[k]
+  for (const k of Object.keys(config)) if (config[k] === undefined) delete config[k]
+
+  const top = stack.slice().reverse()
+  const index = {
+    schema: IMAGE_SCHEMA,
+    ref: o.ref || '',
+    platform,
+    index: null,
+    manifest: null,
+    os: config.os,
+    architecture: config.architecture,
+    // from the config as written: empty fields are left out there (Go's omitempty), as BuildKit's are
+    config: {
+      Env: cfgOut.Env || null,
+      Cmd: cfgOut.Cmd || null,
+      Entrypoint: cfgOut.Entrypoint || null,
+      WorkingDir: cfgOut.WorkingDir || '',
+      User: cfgOut.User || '',
+      ExposedPorts: cfgOut.ExposedPorts || null,
+      Labels: cfgOut.Labels || null,
+      Volumes: cfgOut.Volumes || null,
+      StopSignal: cfgOut.StopSignal || '',
+      Healthcheck: cfgOut.Healthcheck || null,
+    },
+    layers: top.map((x) => ({ pack: x.pack, size: x.size, layer: x.layer })),
+    converter: CONVERTER,
+    pulled: created,
+    stats: {
+      totalMs: Math.round(performance.now() - t0),
+      layerBytes,
+      downloadBytes: 0,
+      downloadMs: 0,
+      convertMs,
+      fileBytes: 0,
+      wasmBytes: 0,
+      packBytes: top.reduce((a, x) => a + x.size, 0),
+      cachedLayers: stack.length - built,
+      builtLayers: built,
+    },
+  }
+  onEvent({ t: 'done', layers: built })
+  const result = { index, packs: top.map((x) => x.bytes), config, history: config.history, path: 'fast' }
+  if (o.keepTars) result.tars = tars
+  return result
+}
+
+/** filepath-style cleanPath of the backend: Join('/', s), keeping a trailing '/' and a trailing '/.'. */
+function cleanDest(s) {
+  const c = clean(s)
+  if (s.endsWith('/.')) return `${c === '/' ? '' : c}/.`
+  if (s.endsWith('/') && c !== '/') return `${c}/`
+  return c
+}
+
+/** fsutil resolveWildcards: walks base lexically, matching each path relative to it; a matched folder is not entered. */
+function resolveWildcards(ctx, base, comp) {
+  const re = globRegExp(comp)
+  if (!re) throw new FastRefused(`COPY: malformed pattern ${JSON.stringify(comp)}`)
+  const baseReal = realPath(base, (p) => ctx.lstat(p), true)
+  const out = []
+  const walk = (dir, rel) => {
+    for (const name of ctx.children(dir)) {
+      const p = join(dir, name)
+      const r = rel ? `${rel}/${name}` : name
+      const e = ctx.lstat(p)
+      if (re.test(r)) {
+        out.push(p)
+        continue // SkipDir for folders; files have no children
+      }
+      if (e.type === 'dir') walk(p, r)
+    }
+  }
+  if (ctx.lstat(baseReal)?.type === 'dir') walk(baseReal, '')
+  return out
+}
+
+/** fsutil/convert_expose parsePort for one word: "80", "80/udp", "8000-8002", "ip:host:container/proto" -> ["80/tcp", ...]. */
+function parsePorts(raw) {
+  const ps = raw.split(':')
+  let hostPort = ''
+  let containerPort
+  if (ps.length === 1) containerPort = ps[0]
+  else if (ps.length === 2) [hostPort, containerPort] = ps
+  else {
+    containerPort = ps[ps.length - 1]
+    hostPort = ps[ps.length - 2]
+  }
+  const si = containerPort.indexOf('/')
+  const portPart = si < 0 ? containerPort : containerPort.slice(0, si)
+  let proto = si < 0 ? '' : containerPort.slice(si + 1)
+  if (portPart === '') throw new FastRefused(`EXPOSE ${raw}: no port specified`)
+  if (!['', 'tcp', 'udp', 'sctp'].includes(proto.toLowerCase())) throw new FastRefused(`EXPOSE ${raw}: invalid proto ${proto}`)
+  if (proto === '') proto = 'tcp'
+  const range = (s) => {
+    const dash = s.indexOf('-')
+    const num = (x) => {
+      if (!/^[+-]?\d+$/.test(x)) throw new FastRefused(`EXPOSE ${raw}: invalid port ${JSON.stringify(x)}`)
+      const n = Number(x)
+      if (n < 0 || n > 65535) throw new FastRefused(`EXPOSE ${raw}: value out of range (0-65535)`)
+      return n
+    }
+    if (dash < 0) return [num(s), num(s)]
+    const a = s.slice(0, dash)
+    const b = s.slice(dash + 1)
+    if (a === b) return [num(a), num(a)]
+    const [x, y] = [num(a), num(b)]
+    if (y < x) throw new FastRefused(`EXPOSE ${raw}: invalid port range`)
+    return [x, y]
+  }
+  if (ps.length > 2) throw new FastRefused(`EXPOSE ${raw}: an address in EXPOSE`)
+  const [s, e] = range(portPart)
+  if (hostPort) {
+    const [hs, he] = range(hostPort)
+    if (e - s !== he - hs && e !== s) throw new FastRefused(`EXPOSE ${raw}: invalid ranges for container and host ports`)
+  }
+  const out = []
+  for (let p = s; p <= e; p++) out.push(`${p}/${proto.toLowerCase()}`)
+  return out
+}
+
+export const __test = { clean, realPath, globRegExp, splitWildcards, normalizePath, cleanDest, parsePorts, goQuote }