buildNamespace

buildNamespace(ctx, caps, opts?): Promise<InterpretedNamespace>

Defined in: packages/runtime/src/platform/boot.ts:281

Interpret a BootContext into a kernel-ready InterpretedNamespace.

Parameters

ctx

BootContext

BootContext produced by UnixImage.createBootContext.

caps

PlatformCapabilities

PlatformCapabilities — used for caps.fetch (httpFS) and caps.importEsm (pkg bin factory).

opts?

NamespaceBuildOpts

Optional container-specific overrides. See NamespaceBuildOpts.

Returns

Promise<InterpretedNamespace>

An InterpretedNamespace ready to pass to createContainerKernel.

Remarks

Canonical namespace builder shared by the top-level boot path and the container runtime. Runs five sequential phases, each consuming and extending a NamespaceBuildState record:

mountRootAndImageFs — overlay root, image mounts, spec mount dispatch, legacy volumes (steps 1–4).
mountKernelFs — synthetic device fileservers (/dev, /dev/user, /etc/motd, /srv) with srv-callback gating (steps 5, 8, 8b, 9).
applyExtensions — catalog metadata, env merge, catalogInstall closure, common-dir creation, pkg bin override, registerExec callback (steps 10–15).
attachDevices — optional container / factotum / net devices loaded via lazy dynamic import (steps 15b–15d).
applyBinds — union binds that alias already-mounted servers (step 16, load-bearing LAST).

Mount order is load-bearing: union binds MUST run last so they can alias already-mounted servers. The four-phase decomposition preserves the narrative numbering of the original 17 steps — every observable output (mount order, overlay stack, permission bits, env keys, exec registry) is pinned by the golden trace in test/platform/build-namespace-golden.test.ts.

The function does NOT create a kernel; call createContainerKernel with the result. Splitting namespace construction from kernel creation lets callers (notably the init system) inject registerService at kernel-construction time.

Example

import { Unix, stdSystem } from '@fishnet/core'
import { buildNamespace, createContainerKernel, createNodeCapabilities } from '@fishnet/runtime'

const image = await Unix().use(stdSystem()).build()
const ns = await buildNamespace(image.createBootContext(), createNodeCapabilities())
const kernel = createContainerKernel(ns)

Caveat

Phase order is intentional. Each phase can read values the previous phase wrote (e.g. Phase 4 reads registerExec from Phase 3); reordering breaks the forward-reference chain.