Skip to content
Agent OS
AOS-ADR-0001 Accepted foundation decision

ADR-0001: Fork Fuchsia/Zircon as the Microkernel Base

ADR-0001: Fork Fuchsia/Zircon as the microkernel base: scope, decisions, requirements, evidence, risks, and traceability for the Agent OS programme. Zircon, DFv2, FIDL, Magma, and Starnix are taken from Fuchsia; board drivers and the Rust-first product layer are built on top.

Edit on GitHub →

ADR-0001: Fork Fuchsia/Zircon as the Microkernel Base

This record freezes a high-cost architectural decision, its rationale, consequences, reversal conditions, and required evidence.

Table of Contents

Purpose and Scope

Area: Architecture Decision.

This record freezes a high-cost architectural decision, its rationale, consequences, reversal conditions, and required evidence.

This document owns the semantics implied by ADR-0001: Fork Fuchsia/Zircon as the Microkernel Base. We fork the whole Fuchsia tree; the kernel is Zircon (not a from-scratch implementation), and userspace frameworks (DFv2, FIDL, Magma, Scenic/Flatland, Starnix) come from the same fork; the scope statements below describe the kernel boundary the fork maintains. It does not assert that every described subsystem already exists. It defines the target model, constraints, evidence needed to trust an implementation, and the boundary with adjacent documents.

Normative Position

  1. Keep the kernel limited to address spaces, threads, scheduling mechanisms, capability/object enforcement, IPC, interrupts, clocks, and minimal evidence hooks.
  2. Place drivers, filesystems, networking, graphics, compatibility, package management, product state, and agents in isolated user space.
  3. Implement architecture ports behind explicit trap, MMU, interrupt-controller, timer, atomic, and context-switch interfaces.

Operating Model

The operating model is contract-first and evidence-driven. A component declares its authority, resources, lifecycle, error model, cancellation and timeout behavior, observability, version, and compatibility promise. Backends are replaceable only when the same conformance suite passes and no forbidden platform type leaks into portable layers.

Implementation proceeds through a reference model or mock, deterministic QEMU evidence where relevant, documentation-first physical hardware, and quality-hardware evidence. Pixel 9 adapters remain quarantined according to ADR-0004.

Requirements

  • R01. Keep the kernel limited to address spaces, threads, scheduling mechanisms, capability/object enforcement, IPC, interrupts, clocks, and minimal evidence hooks.
  • R02. Place drivers, filesystems, networking, graphics, compatibility, package management, product state, and agents in isolated user space.
  • R03. Implement architecture ports behind explicit trap, MMU, interrupt-controller, timer, atomic, and context-switch interfaces.
  • R04. Specify normal, partial, denied, timeout, cancellation, restart, upgrade, and permanent-failure behavior.
  • R05. Expose structured diagnostics without leaking secrets or vendor-specific implementation details.
  • R06. Link material unknowns to a claim and, when testable, an experiment with an owner and gate.
  • R07. Update affected documentation and task data when evidence changes the model.

Failure and Degradation

Degradation must be explicit rather than accidental. The system reports capability absence, reduced quality, unavailable provider, stale data, or unsafe condition through typed states. It must not silently fall back to broader authority, unrestricted legacy execution, unverified firmware, lossy data migration, or irreversible agent action.

Recovery defines what state is retained, reconstructed, re-enrolled, compensated, or intentionally discarded. Unsupported hardware or providers are rejected at binding time where possible.

Evidence and Acceptance

  • Deterministic QEMU boot and reproducible build evidence.
  • Fault-containment and capability property tests.
  • A second architecture or SoC port without semantic forks.
  • Evidence records target identity, hardware revision, firmware, source commit, toolchain, configuration, seed, timestamps, artifacts, expected result, actual result, and reviewer.
  • Acceptance requires the referenced tasks to meet their own criteria; prose completion is not implementation completion.

Implementation Obligations

Task Obligation Priority Gate/Milestone Verification
AOS-CORE-001 Freeze executable kernel semantics v0 P0 M1 model review and property tests including invalid transitions

Risks and Open Questions

  • Kernel scope creep expands the trusted computing base and verification cost.
  • Unsafe Rust and assembly can invalidate language-level safety assumptions.
  • Untested revocation, priority propagation, or DMA authority can break isolation.
  • Open-question rule: an unanswered high-impact question becomes a claim/experiment record and cannot be hidden in meeting notes.
  • Stop rule: work stops or changes track when legal rights, recovery, debug access, safety, or the required evidence path is unavailable.

Related Documents

Planning Reference Anchors

Decision

AOS-CORE-001 — Freeze executable kernel semantics v0