Build Pipeline

The Foundry pipeline turns a recipe into a signed image and publication metadata.

Current implementation status: the CLI has local proof paths for NPK packages, the Micro demo image, and recipe-backed image artifacts. These paths emit BKDL evidence, sign it with Ed25519, verify the artifact, compute a Variant-CID, and support portable bundle export/validation/import. Full dependency closure, real fetch/graft resolution, CAS publication, and remote registry publication are still future Forge work.

Stages

Stage	Output
Resolve	Dependency tree and Variant-CIDs
Build	Image or package artifact
Sign	Detached Ed25519 signature
Attest	BKDL evidence, recipe/manifest digest, and Variant-CID
Validate	Registry trust badge metadata

Dry Run

Use a dry run to inspect the planned build without producing an artifact:

nexus build --edition=mech --arch=aarch64 --dry-run

Recipe Image Proof

Use the recipe image path to turn an edition recipe into a signed local image proof:

nexus build --recipe=recipes/mech.kdl --output=./out
nexus verify ./out/nexus-mech-aarch64.img
nexus forge export-image-bundle ./out/nexus-mech-aarch64.img
nexus forge validate-bundle ~/.nexus/bundles/images/nexus-mech/<variant-cid>/*.image-bundle.tar.gz
nexus forge import-bundle ~/.nexus/bundles/images/nexus-mech/<variant-cid>/*.image-bundle.tar.gz

This path writes:

• ./out/nexus-mech-aarch64.img
• ./out/nexus-mech-aarch64.img.resolution.json
• ./out/nexus-mech-aarch64.img.bkdl.json
• ./out/nexus-mech-aarch64.img.sig
• $NEXUS_HOME/registry/local-images.json
• $NEXUS_HOME/artifacts/images/nexus-mech/<variant-cid>/...

The resolution metadata records the local pipeline stages:

parse -> resolve -> fetch-graft -> build-sanitize -> hash -> sign -> attest -> publish

For non-Micro recipes this is a deterministic recipe-backed raw image artifact, not a bootable OS image claim. It is useful for proving recipe parsing, artifact identity, signing, verification, bundle round-trip, and local registry publication before the full Forge compiler, dependency resolver, and CAS publisher exist.

Local NPK Proof

Use the package proof path to produce one verifiable local Forge artifact:

nexus forge npk-proof hello-npk
nexus verify hello-npk/dist/hello-npk.npk
nexus forge validate-bkdl hello-npk/dist/hello-npk.npk.bkdl.json
nexus forge validate-sig hello-npk/dist/hello-npk.npk.sig hello-npk/dist/hello-npk.npk hello-npk/dist/hello-npk.npk.bkdl.json
nexus bazaar validate --local
nexus bazaar verify-cids --local
nexus forge export-bundle hello-npk
nexus forge validate-bundle ~/.nexus/bundles/npk/hello-npk/<variant-cid>/*.npk-bundle.tar.gz
nexus forge validate-bundle-manifest ./bundle-manifest.json
nexus forge import-bundle ~/.nexus/bundles/npk/hello-npk/<variant-cid>/*.npk-bundle.tar.gz
nexus bazaar install --local hello-npk

For a full regression proof, including deterministic rebuild and tamper rejection, run:

nexus forge selftest

This path writes:

• hello-npk/dist/hello-npk.npk
• hello-npk/dist/hello-npk.npk.bkdl.json
• hello-npk/dist/hello-npk.npk.sig
• $NEXUS_HOME/artifacts/npk/hello-npk/<variant-cid>/hello-npk.npk
• $NEXUS_HOME/artifacts/npk/hello-npk/<variant-cid>/hello-npk.npk.bkdl.json
• $NEXUS_HOME/artifacts/npk/hello-npk/<variant-cid>/hello-npk.npk.sig
• $NEXUS_HOME/registry/local-packages.json
• $NEXUS_HOME/bundles/npk/hello-npk/<variant-cid>/*.npk-bundle.tar.gz

nexus verify checks the artifact digest, canonical BKDL evidence, Ed25519 signature, and Variant-CID. The .sig sidecar embeds the public key PEM, so the published artifact can be verified even when the original local key path is not available. nexus forge validate-bkdl checks the BKDL evidence contract against the repository schema. nexus forge validate-sig checks the signature sidecar schema and, when given artifact/BKDL paths, confirms the sidecar is bound to those filenames. The local Bazaar commands validate the trust badge metadata and recompute the CID from the BKDL evidence inputs. Local registry entries include an artifacts block with explicit npk, bkdl, and signature paths; the legacy install_cmd is kept in sync for display and compatibility. Installs use the stored artifact under $NEXUS_HOME/artifacts/npk, not the temporary build workspace. nexus forge export-bundle writes a portable bundle containing the stored NPK, BKDL evidence, signature sidecar, and a manifest with relative paths and BLAKE3 digests. nexus forge validate-bundle verifies the archive checksum, manifest digests, BKDL evidence, signature sidecar, bundled NPK, bundle provenance, publisher identity, local trust roots, and local revocation policy. nexus forge validate-bundle-manifest checks the extracted manifest against the checked-in schema. nexus forge import-bundle validates the same policy gate, copies accepted artifacts into the local Forge store, and writes a local Bazaar entry with the accepted bundle provenance for the receiving machine. nexus bazaar install --local validates local trust, verifies the stored artifact, and delegates installation to nip.

Bundle import is intentionally local/offline-capable. The default policy lives at $NEXUS_HOME/registry/bundle-trust-policy.json and is seeded from the checked-in nexus-forge/registry/bundle-trust-policy.json when missing. It allows local self-published Forge bundles only through an explicit trust root, and it rejects revoked publisher IDs, signing key IDs, Variant-CIDs, or bundle archive hashes. Pass a policy explicitly when needed:

nexus forge validate-bundle ./bundle.tar.gz ./bundle-trust-policy.json
nexus forge import-bundle ./bundle.tar.gz ./bundle-trust-policy.json

Initial external identity acceptance is not generic DID acceptance. Forge should accept only Libertaria SKH (did:skh:*), Libertaria DID/VC (did:nexus:* plus Nexus VC profiles), and Mosaic IOP DID from /home/markus/zWork/_Dlabs/mosaic-trust-network/iop-rs, iop-ts, and iop-dart. Other DID methods require a resolver spec, trust-root policy, revocation semantics, and regression evidence before they become trusted inputs.

Micro Image Development Proof

Use the Micro local-proof path to produce one verifiable development artifact:

nexus build --edition=micro --arch=x86_64 --local-proof
nexus verify ~/.nexus/artifacts/nexus-micro-x86_64.img
nexus forge export-image-bundle ~/.nexus/artifacts/nexus-micro-x86_64.img
nexus forge validate-bundle ~/.nexus/bundles/images/nexus-micro/<variant-cid>/*.image-bundle.tar.gz
nexus forge import-bundle ~/.nexus/bundles/images/nexus-micro/<variant-cid>/*.image-bundle.tar.gz

This path uses the checked-in demo image builder and writes a bootable image plus .bkdl.json and .sig sidecars. nexus verify checks the image digest, BKDL evidence, Ed25519 signature, and Variant-CID. nexus forge export-image-bundle writes a portable image bundle, and nexus forge import-bundle copies the proven image into the receiving machine's local image store.

The Micro image path is bootable in QEMU. The general recipe image path proves recipe-backed artifact production and publication, but non-Micro recipe images are still deterministic development artifacts. Neither path yet performs full dependency closure, CAS publication, or remote image registry publication.

Runtime Package Proof

Use the runtime proof path after building a local NPK proof and a Micro image:

nexus forge npk-proof hello-npk
nexus build --edition=micro --arch=x86_64 --local-proof
nexus runtime install-proof \
  --local hello-npk \
  --image ~/.nexus/artifacts/nexus-micro-x86_64.img \
  --output ./nexus-micro-runtime-hello.img
nexus verify ./nexus-micro-runtime-hello.img

This writes:

• ./nexus-micro-runtime-hello.img
• ./nexus-micro-runtime-hello.img.runtime.json
• ./nexus-micro-runtime-hello.img.bkdl.json
• ./nexus-micro-runtime-hello.img.sig
• $NEXUS_HOME/registry/runtime-packages.json

The runtime manifest uses nexus-runtime-package-proof/v1 and records the package Variant-CID, an NRP installed-package path, a read-only NexFS /sysro projection, and the initial capability policy. The generated image carries a null-terminated runtime ledger in sector LBA 1; the boot sector reads that ledger from the image and prints compact nxs, NRP, NexFS, and capability markers over serial.

The ledger includes the full package Variant-CID, not only a display prefix:

[nxs] package=hello-npk accepted
[pkg] cid=cid:v1:blake3:<package-cid>
[nrp] installed=/nrp/packages/installed/hello-npk
[nexfs] sysro=/sysro/generations/runtime-proof/packages/hello-npk ro=true
[cap] grants=package.read,package.exec denies=network,host.write,truthdb.write pledges=no-network,read-only-package,exec-entrypoint

This is a development runtime bridge. It proves package evidence can be carried from the local Forge path into a boot-visible Nexus image with embedded runtime metadata. It is not the final nxs generation composer, real kernel-side NRP mutation, or production Cell-loader enforcement.

Run the full QEMU regression with:

nexus-forge/tests/test-runtime-package-proof.sh

Trust Metadata

When an artifact is published to the Bazaar, the pipeline must write badge evidence into the package entry. Run:

nexus bazaar validate

before publishing the registry update.