EriX Integration Repository

integration is the cross-repository system integration and VM validation repository for EriX.

This repository verifies that independently developed components (bootloader, kernel, root services, and tooling) work together as a complete boot chain in a deterministic VM environment.

---

Scope

This repository is responsible for:

• cloning component repositories from configured branches in CI
• building integration artifacts from configured components
• orchestrating QEMU/OVMF full-system VM scenarios
• asserting deterministic pass/fail outcomes using serial markers and isa-debug-exit
• publishing integration logs, resolved component revisions, and VM appliance artifacts
• building deterministic raw FAT32 disk images from packaged ESP content
• publishing release artifacts on push with branch/tag-aware release routing

This repository is not responsible for:

• implementing kernel, bootloader, or service logic
• defining normative handoff wire-format semantics (owned by docs/handoff)
• replacing component-level unit and local integration tests

---

Deterministic VM Test Contract (Current)

Scenario-driven VM tests are grouped as:

• full-system normal run
• subsystem positive run
• subsystem negative run

All scenario classes execute as full-system VM boots. The default full-system scenario now validates Phase 0 multi-service bootstrap smoke (bootloader -> kernel -> rootd -> {memd,vspaced,pagerd,procd} contract checks).

Scenario schema includes rootd bring-up controls:

• kernel_rootd_test (none|smoke|runtime)
• rootd_test_mode (none|smoke|force-fail|phase0-*|phase1-*|phase2-*|phase3-*)
  • in current implementation this is translated into a generated BootConfig payload (out/fixtures/boot-config.bin) instead of selecting rootd launch arrays at compile-time
• runtime_config_profile (dev|release)
  • selects runtime.<profile>.toml at integration repo root
• runtime_config_path (optional, relative to integration root or absolute)
  • explicit runtime TOML override for scenario/appliance builds
  • if omitted and runtime.local.toml exists, it is used
  • otherwise runtime.<profile>.toml is used
• phase0_missing_service (none|memd|vspaced|pagerd|procd|phase0-probe|named|timed|logd|crashd|irqd|deviced|probed|hotplugd|drv-acpi|drv-serial|seriald|fbcond|console-font|drv-i8042|drv-ps2-keyboard|drv-ps2-mouse|inputd|phase1-lookup|phase1-time|phase2-irq|phase2-driver-hold|phase2-driver-capcheck)
• per-service build modes:
  • memd_test_mode, vspaced_test_mode, pagerd_test_mode, procd_test_mode, named_test_mode, timed_test_mode, logd_test_mode, crashd_test_mode, irqd_test_mode, deviced_test_mode, probed_test_mode, hotplugd_test_mode, drv_acpi_test_mode, drv_serial_test_mode, seriald_test_mode, fbcond_test_mode, drv_i8042_test_mode, drv_ps2_keyboard_test_mode, drv_ps2_mouse_test_mode, inputd_test_mode
  • values: none|runtime|smoke|serial-probe|force-fail (serial-probe currently applies to drv_serial_test_mode)

Runtime policy:

• kernel_rootd_test=runtime is bootstrap-only bring-up driven by generated BootConfig from runtime TOML, with validation_profile=none.
• runtime mode must not rely on synthetic probe/client workflows.
• smoke/negative matrices remain unchanged and continue to use integration smoke features.
• smoke/negative matrices keep mode knobs as fixture-generation inputs and feed rootd through BootConfig payloads.

Current integration checks consume these marker families:

• ERIX_BOOTLOADER:* (bootloader harness markers)
• ERIX_KERNEL:* and ERIX_KERNEL_STUB:* (kernel bring-up/test markers)
• ERIX_KRN:* (kernel library/runtime diagnostics)

Phase0-positive scenarios now assert staged rootd progress markers in order:

• ERIX_KERNEL:ROOTD_STAGE:INTAKE_VALIDATED
• ERIX_KERNEL:ROOTD_STAGE:MODULES_DISCOVERED
• ERIX_KERNEL:ROOTD_STAGE:MEMD_READY
• ERIX_KERNEL:ROOTD_STAGE:VSPACED_READY
• ERIX_KERNEL:ROOTD_STAGE:PAGERD_READY
• ERIX_KERNEL:ROOTD_STAGE:PROCD_READY
• ERIX_KERNEL:ROOTD_STAGE:SERVICES_READY
• ERIX_KERNEL:ROOTD_STAGE:PROBE_SPAWN_REQUESTED
• ERIX_KERNEL:ROOTD_STAGE:PROBE_SPAWNED
• ERIX_KERNEL:PHASE0:FAULT_NOTIFY_SENT
• ERIX_KERNEL:PHASE0:FAULT_RESOLVED
• ERIX_KERNEL:ROOTD_STAGE:PROBE_EVENT_RECEIVED
• ERIX_KERNEL:ROOTD_STAGE:PROBE_COMPLETED

Phase1-time scenarios additionally assert:

• ERIX_KERNEL:ROOTD_STAGE:TIMED_READY
• ERIX_KERNEL:ROOTD_STAGE:TIME_READY

Phase3-framebuffer scenarios additionally assert framebuffer continuity contracts and enforce fail-closed behavior when the console-font blob is missing.

Phase3-input scenarios additionally assert deterministic input stack staging:

• ERIX_DEVICED:READY:DRV_I8042
• ERIX_DEVICED:READY:DRV_PS2_KEYBOARD
• ERIX_DEVICED:READY:DRV_PS2_MOUSE
• ERIX_KERNEL:ROOTD_STAGE:INPUTD_READY
• ERIX_KERNEL:ROOTD_STAGE:INPUT_ROUTING_READY
• ERIX_KERNEL:ROOTD_STAGE:CONSOLE_INPUT_READY

Current exit-code class mapping:

• 0x10: success
• 0x11: bootloader failure
• 0x12: kernel failure
• 0x13: rootd failure
• 0x14: service bootstrap failure

---

Branch-Head Integration Model

By policy, this repository integrates component branch heads (not pinned lockfile SHAs) for fast feedback.

For traceability:

• each CI run emits resolved-revisions.json (repo -> commit SHA)
• test reports and artifacts include that manifest

---

Repository Layout (Current)

integration/
├── components.toml
├── scripts/
│   ├── clone-components.sh
│   ├── build-all.sh
│   ├── build-kernel-fixture.sh
│   ├── generate-boot-config.py
│   ├── parse-runtime-config.py
│   ├── run-scenario.sh
│   ├── run-scenarios.sh
│   ├── run-vm.sh
│   ├── run-kernel-exception-negative-tests.sh
│   ├── package-appliance.sh
│   ├── build-disk-image.sh
│   ├── publish-release-artifacts.sh
│   ├── assert-markers.sh
│   ├── lib/scenario.sh
│   └── lib/components.sh
├── tests/
│   └── scenarios/*.toml
├── runtime.sample.toml
├── runtime.dev.toml
├── runtime.release.toml
├── .github/workflows/ci.yml
├── README.md
├── ARCHITECTURE.md
└── ROADMAP.md

---

Quick Start

From integration/:

./scripts/clone-components.sh
./scripts/build-all.sh
./scripts/run-scenario.sh tests/scenarios/full-system-normal.toml
./scripts/run-scenarios.sh \
  tests/scenarios/subsystem-kernel-scheduler-positive.toml \
  tests/scenarios/subsystem-kernel-exception-ud2-negative.toml
./scripts/package-appliance.sh
./scripts/build-disk-image.sh
APPLIANCE_NAME=erix-release RUNTIME_CONFIG_PROFILE=release ./scripts/package-appliance.sh
./scripts/build-disk-image.sh erix-release
PUBLISH_DRY_RUN=1 ./scripts/publish-release-artifacts.sh

build-kernel-fixture.sh now generates and injects a required boot-config section payload for rootd orchestration.

Runtime appliance defaults:

• KERNEL_ROOTD_TEST=runtime
• RUNTIME_CONFIG_PROFILE=dev
• ROOTD_TEST_MODE=none (runtime image composition is config-driven, not phase-mode-driven)

Runtime config files:

• runtime.dev.toml (default dev profile)
• runtime.release.toml (default release profile)
• runtime.sample.toml (schema + documented behavior)
• runtime.local.toml (local override, gitignored)

Set RUNTIME_CONFIG_PROFILE=release (or RUNTIME_CONFIG_PATH=...) to select runtime image behavior, and APPLIANCE_NAME to select output artifact prefix.

Main outputs:

• out/resolved-revisions.json
• VM serial logs generated by the active harness
• out/appliance/erix-dev.tar.gz
• out/appliance/erix-dev.img
• out/appliance/erix-dev.img.sha256
• out/appliance/erix-dev.img.zst and out/appliance/erix-dev.img.zst.sha256 (when compression is enabled)
• out/appliance/erix-release.tar.gz
• out/appliance/erix-release.img
• out/appliance/erix-release.img.sha256
• out/appliance/erix-release.img.zst and out/appliance/erix-release.img.zst.sha256 (when compression is enabled)

---

Release Publication Policy

Release uploads are run from CI on push, workflow_dispatch, and schedule events. Primary hosting/runtime target is Forgejo (git.erikinkinen.fi) with Forgejo Actions. The publication script remains GitHub-API compatible and can run in either environment. Pull-request validation never mutates tags or releases.

Git ref type	Git ref name	Target tag/release	Behavior
branch	main	nightly	Delete old nightly tag/release (ignore missing), recreate at current SHA, upload fresh artifacts
tag	pushed tag	pushed tag	Keep existing tag, create release if absent, refresh matching assets
branch	any non-main	ci-<sanitized-branch>	Delete old computed tag/release, recreate at current SHA, upload fresh artifacts

All releases created/updated by CI are marked as pre-release. Tag creation/deletion for routed releases is performed through authenticated git push ref updates in CI, so the tag mutation is attributed to the token owner rather than an anonymous API ghost identity.

Artifact upload set:

• compressed disk image (.img.zst) and checksum when compression is enabled, otherwise raw .img and checksum, for both erix-dev and erix-release
• resolved-revisions.json
• appliance tarball (.tar.gz) when present, for each appliance profile

Sanitization rule for non-main branch tags:

• replace / and any non [A-Za-z0-9._-] characters with -
• collapse repeated -

Authentication/token environment:

• Forgejo-first: FORGEJO_TOKEN (recommended in this repository CI)
• compatibility: GITHUB_TOKEN

---

Integration Scope

This repository provides full-system integration validation for EriX, covering bootloader through critical service bootstrap, with test harnesses for various component failure scenarios and boot-time behaviors.

---

License

ISC, consistent with the rest of EriX.