feat: add a principal-scoped Linux Realm capsule

[joshuajbouw]

Closes #76

Depends on astrid-runtime/astrid#1365.

Summary

Adds Linux Realm: a principal-scoped, persistent Linux developer workbench running entirely inside an AOS capsule.

The capsule boots a pinned RISC-V Linux system through Astrid's generic compute-worker boundary, restores from a prewarmed checkpoint, mounts the authenticated invocation workspace at /workspace, persists the principal's Linux home, and exposes a normal foreground realm_shell tool for agents.

This is deliberately a draft. The implementation is functional and has live proof/benchmark records, but it is a substantial new machine, filesystem, lifecycle, and distribution surface that needs architecture, security, licensing, and reproducibility review alongside its core dependency.

Agent experience

• The agent invokes one shell tool with the exact script it wants to run.
• The guest starts in /workspace, corresponding to the host-stamped current workspace.
• The guest has a separate durable home owned by the Astrid principal.
• Multiline scripts, pipelines, Git, C, and Rust builds run inside Linux.
• Foreground commands return ordinary output; persistent/background behavior remains explicit.
• Warm execution restores a resident/prewarmed principal realm rather than cold-booting Linux on every turn.

Changes

• Add a bounded RV64 machine with privileged execution, Sv39 translation, virtual SMP, timers, floating-point support, checkpointing, and deterministic device plumbing.
• Add signed generic vCPU workers with isolated stacks, shared atomic RAM, exact hart binding, and principal compute admission.
• Add host adapters for principal home and invocation workspace, including 9P-style file operations and fail-closed path handling.
• Add a realm actor and runtime pipeline for lazy boot, foreground execution, suspend/resume, stop, restart, and principal-local accounting.
• Package a pinned Linux kernel, rootfs, reproducible Buildroot configuration, source locks, legal information, signed worker, and prewarm checkpoint.
• Include a minimal agent development userland with shell, Git, C build tools, Rust/rustup-compatible tooling, and supporting utilities.
• Expose the agent-native realm_shell surface with multiline streaming and compact text results.
• Derive guest RAM and vCPU topology from Astrid compute admission instead of fixed capsule-local ceilings.
• Add benchmark tooling and versioned M2 Ultra cold/prewarm/vCPU sample records.
• Add the design and threat-model document at docs/principal-linux-realm.md.
• Update CHANGELOG.md under [Unreleased].

Security properties

• The capsule declares no host_process capability.
• Guest-built files are data on the host and cannot execute natively without a separate privileged promotion boundary.
• /workspace comes from an authenticated host attachment, not a model-supplied host path.
• Home, machine state, worker groups, and accounting are principal-bound.
• Physical host paths are not serialized into the guest or IPC contract.
• Traversal, scheme injection, stale handles, symlink metadata, malformed filesystem operations, and cross-principal reuse are covered by fail-closed tests.
• Worker and machine assets are pinned and identity-checked.
• Resource requests remain subordinate to Astrid operator/principal policy.

Validation

• cargo fmt --all -- --check
• Targeted Linux Realm test run on aarch64-apple-darwin
  • resource-policy, workspace traversal, principal isolation, multiline shell, machine, and signed-worker tests passed
  • intentionally stopped at the long full Linux boot/console persistence test so draft PR CI can run the complete matrix
• Existing versioned live-proof and benchmark records are included under benchmarks/linux-realm/.
• The installable capsule and source bundles were built and verified at the published branch checkpoint before submission.

Review focus

• RV64 privileged/trap/MMU correctness and deterministic SMP behavior;
• guest/host filesystem boundary, symlink and stale-handle behavior;
• principal lifecycle, eviction, persistence, and accounting;
• signed worker and packaged asset reproducibility;
• memory/vCPU policy precedence and denial behavior;
• shell/background-process semantics for agent turns;
• Linux/Buildroot redistribution and source-offer completeness;
• whether large implementation files should be split before the PR is made ready.

Deferred by design

• GPU/device passthrough: requires a separate explicit capability and broker boundary.
• General WASI adoption: AOS capsules continue to use audited astrid:* imports.
• Full mutable root filesystem: durable principal home is implemented; root overlay policy remains a separate decision.
• Tensor-algebra scheduling: the generic compute topology can support later work, but no tensor policy is activated here.