Cohesix Build Plan (ARM64, Pure Rust Userspace)
The current roadmap is contained in this file: milestones 0–27g, the narrow Release A video index and Python index publication, Release B and milestones 28–28g, then deferred whole-numbered milestones 29–43. The ownership map resolves historical references without changing evidence or generated identifiers. Only the new 28x release scope is committed next; later design inventories are not additional release gates. Milestone 27i separately authorizes the owner-requested Python publication path without reopening Release A acceptance.
This build plan records what Cohesix has implemented, what remains to be built, and the conditions for completing each milestone. It defines scope, dependencies, deliverables, acceptance criteria, and known limitations so users and contributors can distinguish delivered capabilities from planned work.
Completed milestones summarize the as-built result and its qualification limits. Active and planned milestones define the remaining work. Detailed implementation history and test-run records belong in linked audit, benchmark, or release evidence; each milestone retains the decisions and exceptions that affect its scope or acceptance. Update task descriptions to describe the resulting behavior and obligations rather than appending a sequence of changes or test attempts.
This plan governs milestone scope and status under the build charter.
Selected manifests, resolved outputs, and coh-rtc artifacts define as-built
configuration. Architecture and interface
references own runtime contracts; the test plan and
benchmark methodology govern qualification evidence.
- Host: macOS 26 on Apple Silicon.
- Targets: QEMU
aarch64/virtwith GICv3; Raspberry Pi 4 via firmware → U-Boot → seL4 binary image. - Userspace: pure Rust; Queen/Worker control uses bounded namespaces and console operations, with no ad-hoc host RPC authority.
- Reference AI host: NVIDIA Jetson Orin Nano. AI runtimes and GPU tools run host-side, using configurable NVMe paths for models, data, caches and evidence.
A shard is a manifest-derived Worker namespace bucket. Telemetry uses
/shard/<label>/worker/<id>/telemetry; the legacy /worker/<id>/telemetry
alias requires sharding.legacy_worker_alias = true.
seL4 Reference Manual Alignment (v16.0.0)
The seL4 v16.0.0 manual governs kernel semantics. The selected external seL4 build, headers and metadata define enabled options, object layouts and APIs. Check each kernel interaction against both. Manual availability, configured support, implementation and target proof are distinct; Cohesix protocols, device behavior and build rules remain owned by their specific contracts.
Milestones
| Milestone | Description | Status |
|---|---|---|
| 0 | Repository Skeleton & Toolchain | Complete |
| 1 | Boot Banner, Timer, & First IPC | Complete |
| 2 | NineDoor Minimal 9P | Complete |
| 3 | Queen/Worker MVP with Roles | Complete |
| 4 | Bind & Mount Namespaces | Complete |
| 5 | Hardening & Test Automation (ongoing) | Complete |
| 6 | GPU Worker Integration | Complete |
| 6a | GPU Model Lifecycle & Telemetry Semantics (LoRA-ready) | Complete |
| 7a | Root-Task Event Pump & Authenticated Kernel Entry | Complete |
| 7b | Standalone Console & Networking (QEMU-first) | Complete |
| 7c | TCP transport parity while retaining existing flows | Complete |
| 7d | ACK/ERR broadcast is implemented across serial and TCP | Complete |
| 7e | TraceFS (JSONL Synthetic Filesystem) | Complete |
| 8a | Lightweight Hardware Abstraction Layer | Complete |
| 8b | Root-Task Compiler & Deterministic Profiles | Complete |
| 8c | Cache-Safe DMA via AArch64 VSpace Calls | Complete |
| 8d | In-Session test Command + Preinstalled .coh Regression Scripts |
Complete |
| 9 | Secure9P Pipelining & Batching | Complete |
| 10 | Telemetry Rings & Cursor Resumption | Complete |
| 11 | Host Sidecar Bridge & /host Namespace (Ecosystem Coexistence) | Complete |
| 12 | PolicyFS & Approval Gates | Complete |
| 13 | AuditFS & ReplayFS | Complete |
| 14 | Sharded Namespaces & Provider Split | Complete |
| 15 | Client Concurrency & Session Pooling | Complete |
| 16 | Observability via Files (No New Protocols) | Complete |
| 17 | Content-Addressed Updates (CAS) — 9P-first | Complete |
| 18 | Field Bus & Low-Bandwidth Sidecars (Host/Worker Pattern) | Complete |
| 19 | cohsh-core Extraction (Shared Grammar & Transport) |
Complete |
| 20a | cohsh as 9P Client Library |
Complete |
| 20b | NineDoor UI Providers | Complete |
| 20c | SwarmUI Desktop (Tauri, Pure 9P/TCP) | Complete |
| 20d | SwarmUI Live Hive Rendering (PixiJS, GPU-First) | Complete |
| 20e | CLI/UI Convergence Tests | Complete |
| 20f | UI Security Hardening (Tickets & Quotas) | Complete |
| 20f1 | SwarmUI Host Tool Packaging + Tauri API Fix | Complete |
| 20g | Deterministic Snapshot & Replay (UI Testing) | Complete |
| 20h | Alpha Release Gate: As-Built Verification, Live Hive Demo, SwarmUI Replay, & Release Bundle | Complete |
| 21a | Telemetry Ingest with OS-Named Segments (Severely Limited Create) | Complete |
| 21b | Host Bridges (coh mount, coh gpu, coh telemetry pull) | Complete |
| 21c | SwarmUI Interactive cohsh Terminal (Full Prompt UX) | Complete |
| 21d | Deterministic Node Lifecycle & Operator Control | Complete |
| 21e | Rooted Authority, Cut Detection, Explicit Session Semantics, and Live Hive Visibility | Complete |
| 22 | Runtime Convenience (coh run) + GPU Job Breadcrumbs | Complete |
| 23 | PEFT/LoRA Lifecycle Glue (coh peft) | Complete |
| 24 | Python Client + Examples (cohesix) + Doctor + Release Cut | Complete |
| 24b | Live GPU Bridge Wiring + PEFT Live Flow + Live Hive Telemetry Text | Complete |
| 24b1 | Live Hive UX Patch: Performance, Labels, Clickability, Telemetry Harness | Complete |
| 24c | Authoritative Scheduling Grammar + REST Gateway + Scheduler/Lease Observability | Complete |
| 24d | Jetson CUDA Host Support (NVML Fallback + Doctor) | Complete |
| 24e | REST Multiplexer Transports + SwarmUI Gateway Mode | Reopened — M27g REST mount path-bound restoration |
| 25 | SMP Utilization via Task Isolation (Multicore without Multithreading) | Complete |
| 25a | REST Live Hive Performance (Parallel Polling + Batching) | Complete |
| 25b | Secure Scale Gateway (1k Worker Readiness + Due Diligence Closure) | Complete |
| 25c | Python Orchestration SDK (1k Fleet Playbooks + Host Integrations) | Complete |
| 25d | REST Request-Auth Parity Across Host Tools (Gateway Capability Max) | Complete |
| 25e | Evidence Packs + Integration Kits (Audit-First Adoption) | Complete |
| 25f | Gateway Broker Refactor + Large Telemetry Reference Manifests (No-Retry Reliability Gate) | Complete |
| 25g | Host Control Tickets via FUSE (GPU/PEFT + systemd/docker + K8s Coexistence) | Complete |
| 25h | Multi-Hive Federation via Ticket Relay (Single-Writer Preserved, 10x1k Fleet Pattern) | Complete |
| 26 | Official Pi 4 Bring-up (U-Boot + Binary Image) | Complete |
| 26a | Pi 4 Driver-Task Substrate + GENET/Serial/Display Isolation | Complete |
| 26b | Pi 4 USB/Wi-Fi Driver Tasks + DHCP/Benchmark Concurrency | Complete |
| 26c | Regression-Gated Refactor + Surface Audit (Zero-Regression) | Complete |
| 26d | seL4 16 Baseline Refresh + Reference/Performance Realignment | Complete |
| 26e | Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation | Reopened (bounded lease-history view) |
| 27 | Operator Utilities: Inspect, Trace, Bundle, Diff, Attest | Complete — owner-approved evidence; 1.1.0-beta (Release A) |
| 27a | Authority Hardening: Delegated REST Identity, Fenced Failover, Idempotent Queen Intents | Complete — 1.1.0-beta (Release A) authority floor |
| 27b | Executable Host Foundation | Complete — selected foundation |
| 27c | Recoverable CUDA Recipes | Complete |
| 27d | Verified Private LoRA Release | Complete |
| 27e | Installation, Adoption and CI | Complete |
| 27f | SwarmUI Community Showcase: Spectrum Workbench + Live AI Hive | Planned — next release |
| 27g | Integrated Qualification and Next Release | Complete — owner-approved limited Release A qualification |
| 27h | Release A Community Video Index | Complete — documentation only |
| 27i | Release A Python Index Publication | Complete — PyPI 1.1.0b1 page correction published |
| 28 | Shared Governed Jobs and Bounded Unattended Authority | Complete — selected foundation |
| 28a | Useful CUDA Workloads and Reliable GPU Operations | Complete — selected Orin systemd and Docker lanes |
| 28b | Deeper PEFT Lifecycle and Verified Serving | Complete |
| 28c | macOS Developer Actions and Local Metal Workbench | Complete — selected Mac developer journey |
| 28c1 | Governed Mac MLX Release and vMLX Rollout | Complete — selected Mac component |
| 28d | MCP Access to Complete Selected Workflows | Complete — selected MCP-only Jetson Orin component |
| 28e | A2A Delegation of Durable Selected Jobs | Complete — selected A2A Jetson Orin component |
| 28f | NeMo Agent Toolkit Adoption Kit and Live Integration | Complete — selected Jetson/KVM component |
| 28g | Installation, Integrated User Qualification and Release B | In Progress |
| 29 | Extended Formal Assurance and NIST Evidence | Deferred — explicit activation |
| 30 | Broader Providers, Federation, Deployment and Domain Workflows | Deferred — explicit activation |
| 31 | Semantic Object Fabric and Context Capsules | Deferred — explicit activation |
| 32 | General Machine-Checked Admission and Proof Artefacts | Deferred — explicit activation |
| 33 | Production Worker Binding, Driver Inventory and Quarantine | Deferred — explicit activation |
| 34 | Advanced Agents, Context Optimisation and Broader NeMo Families | Deferred — explicit activation |
| 35 | General Inference Gateway, Compatibility and Routing | Deferred — explicit activation |
| 36 | Extended MCP/A2A Coverage and Resource Mounts | Deferred — explicit activation |
| 37 | VM-Local Persistence and Reboot Recovery | Deferred — explicit activation |
| 38 | Core-Local Service-Turn Scheduling | Deferred — explicit activation |
| 39 | Operator-Lane Scheduling and Multi-Surface Responsiveness | Deferred — explicit activation |
| 40 | Read-Only Edge Status and Attestation Tool | Deferred — explicit activation |
| 41 | Pi 4 Root-Shell Hardware Status | Deferred — explicit activation |
| 42 | Additional AI-Native Namespace Projections | Deferred — explicit activation |
| 43 | AWS Native Deployment and ENA | Deferred — explicit activation |
Post-26e Delivery Sequence
The 19 September 2026 owner instruction makes numerical order implementation order. Preserve completed 0–27a and their evidence/exception decisions. The next release is exactly 27b -> 27c -> 27d -> 27e -> 27f -> 27g. Each milestone closes against its own focused contracts using only earlier completed owners; 27g qualifies the assembled release. A prompt to implement a milestone means its complete body/tasks/checks, with no unstated conversation requirement. Under the charter, a Planned milestone is activated by the owner’s implementation request after its listed prerequisites are complete; record In Progress before implementation. This planning edit itself activates no runtime work.
The new release boundary supersedes older full-catalogue, fixed-ID and out-of-order delivery instructions for prospective work, including the earlier 14 September broad 27b activation. Working implementation, local changes, qualified evidence and exceptions are preserved, never downgraded or relabeled. Inspect the actual checkout and existing evidence before implementing any task. Security boundaries and acceptance standards remain unchanged.
Release actions use completed 27a operator approval, scoped tickets, current state checks, fencing and durable execution, extended only where 27b owns a necessary selected-path repair. Full formal proofs and general machine-checked admission are deferred; release outputs cannot claim those guarantees. No deferred milestone gates 27b–27g. Accepted 26e isolation remains valid; production Worker binding and Queen reboot persistence are separate later claims.
Release packaging
Retain A = 1.1.0-beta, B = 1.2.0, C = 1.3.0-beta and
Cohesix-<release-version>-<platform> bundle naming. A delivers recoverable
CUDA, Verified Private LoRA Release, adoption/CI and the substantial native
SwarmUI showcase. B is the qualified 28–28g ecosystem release below; C remains
reserved. No version is
published or reassigned by this planning change.
Historical releases and evidence keep original names, IDs and proof classes.
Superseded 0.9.0-beta distribution retirement
Status: Complete — owner-directed repository maintenance on 28 September 2026.
Title/ID: repo-release-090-tree-retirement
Milestone: Release packaging / repo-release-090-tree-retirement
Goal: Remove the superseded 0.9.0-beta distribution from the current release tree without changing later bundles or historical Git evidence.
Inputs: releases/Cohesix-0.9.0-beta-{MacOS,linux}, their tarballs and release notes; compiler-owned implementation and host-integration inventories.
Changes:
- releases/ — remove the two unpacked bundles, two archives and version-bound notes.
- configs/generated/, crates/cohesix-authority/src/provider_generated.rs and tools/cohesix-py/cohesix/provider_generated.py — regenerate the inventory and dependent catalogue/hash projections.
Commands:
- scripts/check-generated.sh
- git diff --cached --check
Checks: No 0.9.0-beta distribution file remains under releases/; generated contracts match the selected source and tracked paths.
Deliverables: Scoped release-tree deletion and generated metadata, with AI-assisted inventory and verification; no runtime, target or release-acceptance claim.
Milestone ownership and historical references
The 23 September 2026 revision keeps 0–27g scope, evidence, status and qualification requirements unchanged. Prospective owner references in those sections use the current numbering; historical task/evidence identifiers remain unchanged. New 28–28g are the bounded Release B implementation scopes in this file. No deferred milestone gates that release. The old blanket assurance/provider/semantic/agent dependency chain is removed.
| Former scope (before this consolidation) | Current owner |
|---|---|
| 0–27g, including selected CUDA/HF foundations and narrow reopenings | Unchanged 0–27g; extend, do not repeat their accepted work. |
| 28 verification/NIST | Focused release-safety checks in 28; broader assurance in 29. |
| 28a provider catalogue | Selected CUDA in 28a, PEFT in 28b, Apple in 28c; remaining catalogue in 30. |
| 28b semantic objects/capsules | 31. |
| 28c general admission | Narrow shared admission/standing authority in 28; general proof programme in 32. |
| 28d complete production bundle/driver binding | Selected-path safety in 28; stronger full binding/inventory claim in 33. |
| 28e AI/PEFT/NeMo | Concrete PEFT in 28b, Apple compute in 28c, NeMo Agent Toolkit kit in 28f; advanced agent/context/framework/NeMo families in 34. |
| 28f inference gateway | Native serving/canary in 28b; general compatibility/routing/cache gateway in 35. |
| 28g broad MCP/A2A | Shared authority in 28, MCP in 28d, A2A in 28e, NeMo clients in 28f, release qualification in 28g; extra protocol breadth in 36. |
| 29 persistence | 37. |
| 29a service-turn scheduling | 38. |
| 29b operator-lane scheduling | 39. |
| 30 field status | 40. |
| 30a hardware diagnostics | 41. |
| 30b AI namespace projections | 42. |
| 31 AWS | 43. |
Historical task IDs and generated identifiers retain their bytes and meaning; a reused numeric prefix cannot activate scope or upgrade evidence. The older pre-19 September task mappings remain resolved as follows:
| Stable task or original scope | Current ownership |
|---|---|
| m27b provider-action/evidence/identity/integration foundation | 27b unchanged; selected extensions in 28–28c; wider catalogue in 30. |
| m27b live-reference-workflows and packaging | Accepted recipes/LoRA/install remain 27c/27d/27e; unselected domain/deployment breadth is 30. |
| m27b federation/exporters/industry-sidecars | 30; retain their existing implementation and evidence. |
| m27b-operator-manuals-and-reference-maintenance | 27b unchanged; 27e adoption remains unchanged. |
| m27c-semantic-ir-and-object-contract and former semantic workbench inspector | 31. |
| m27d-live-peft-reference-paths | 27d unchanged. |
| m27d-framework-adapters and m27d-nemo-provider-family | 34; the distinct minimal NeMo Agent Toolkit integration is 28f. |
| m27e-inference-ir-and-compatibility-contract and m27e-inference-receipts-otel-and-evidence | 35. |
| m28c-mcp-policy-ir and m28c-a2a-policy-ir | Retained full-catalogue designs in 36; selected protocol implementation is 28d/28e over 28 authority. |
| m28b-production-worker-ticket-driver-inventory and m28b_production_bundle | 33; no persisted identifier is renamed. |
| m28a-native-provider-discovery-and-actions | 30 inventory; its existing narrow launchd restoration for M27g remains valid at its original scope. |
Each deferred milestone has a current scope/activation boundary and an expandable retained design inventory. Only inside those labelled inventories, numeric milestone references use the former numbering in the first table. Those design records preserve task ideas, detailed constraints, commands and rationale; their former Planned/Reopened or complete-catalogue wording is not new implementation authority or a Release B gate. At activation, reconcile the selected remaining tasks with current code and this mapping before execution. Do not reimplement work accepted by 28x. Current task/claim references elsewhere must use the current heading and exact task ID, not an old number alone.
Compatibility and validation ownership
Every implementation milestone reviews the complete host-tool suite (coh,
cohsh, gateway, ticket agent, GPU and sidecar bridges, CAS/evidence tools,
SwarmUI), tools/cohesix-py, compiler/generated consumers and benchmark scripts.
27b owns selected action/verifier/authority conformance; 27c owns lifecycle,
identity/cache/accounting; 27d owns PEFT/evaluation/deployment generations; 27e
owns install/doctor/CLI/Python/CI; 27f owns native UI/replay/accessibility; 27g
owns assembled compatibility and native-stack comparison. Each owner updates
affected code, generated contracts, fixtures, help/manuals and benchmarks
atomically and records surfaces needing no change. Deferred owners do the same
for their extensions. No hand-edited generated output or threshold relaxation.
This planning change modifies documentation only. Applicable checks are
scripts/check-generated.sh, scripts/ci/check_test_plan.sh, documentation
links/unique anchors/task ownership/dependency review, and git diff --check.
No runtime suite, GPU workload or hardware run is part of planning validation.
Implementation commands in task records are future execution instructions, not
claims that every named helper already exists. Use existing catalogued entrypoints
where available; add missing owner gates with their implementation and docs.
Milestone 0 — Repository Skeleton & Toolchain
Status: Complete — the repository/workspace scaffolding, build scripts, size
guard, bounded m0-rust-1-97-1-security-refresh task, bounded
m0-rust-current-stable-dependency-refresh task, and bounded
m0-toml-1-1-4-maintenance closure are complete. The exact Rust 1.97.1 host
gate remains green; target-qualified later stages remain separately gated.
Deliverables
- Cargo workspace initialised with crates for
root-task,nine-door, andworker-heartplus shared utility crates. toolchain/setup_macos_arm64.shscript checking for Homebrew dependencies, rustup, and QEMU - and installing if absent.scripts/qemu-run.shthat boots seL4 with externally builtelfloader,kernel.elf, also creates and usesrootfs.cpio.- QEMU launchers auto-select host acceleration (
hvfon macOS,kvmon Linux when/dev/kvmis accessible), withCOHESIX_QEMU_ACCEL/QEMU_ACCELoverrides and fallback totcg. scripts/ci/size_guard.shenforcing < 4 MiB CPIO payload.- Repository tree matches
docs/REPO_LAYOUT.md, and architecture notes fromdocs/ARCHITECTURE.md §1-§3are captured in crate READMEs or module docs to prevent drift.
Checks
cargo checksucceeds for the workspace.qemu-system-aarch64 --versionreports the expected binary.- QEMU launchers log the selected accelerator and pass
-accelwith host-appropriate defaults or explicit overrides. scripts/ci/size_guard.sh out/rootfs.cpiorejects oversized archives.
Title/ID: m0-rust-1-97-1-security-refresh
Milestone: Milestone 0 — Repository Skeleton & Toolchain / Rust 1.97.1 security refresh
Goal: Replace the superseded Rust 1.93.1 baseline with exact stable Rust 1.97.1 while preserving the existing host and `aarch64-unknown-none` build contracts.
Inputs: rust-toolchain.toml, Cargo.toml, Cargo.lock, .github/workflows/ci.yml, toolchain/setup_macos_arm64.sh, toolchain/setup_linux_arm64.sh, scripts/ci/rust_risk_gate.sh, scripts/ci/test_rust_risk_gate.py, docs/TOOLCHAIN_MAC_ARM64.md, staged Test Plan gates.
Changes:
- rust-toolchain.toml + setup scripts + CI — select exact Rust 1.97.1 with deterministic minimal-profile installation plus the declared rustfmt, clippy, and aarch64-unknown-none closure.
- scripts/ci/rust_risk_gate.sh + focused tests — bind risk scanning to the exact named Rust 1.97.1 toolchain and refreshed bootstrap-file digest.
- docs/TOOLCHAIN_MAC_ARM64.md — describe the refreshed as-built Rust contract.
Commands:
- cargo fmt --all -- --check
- cargo clippy --workspace --all-targets -- -D warnings
- cargo check --workspace
- cargo test --workspace -- --test-threads=1
- cargo test -p rust-risk-audit
- python3 scripts/ci/test_rust_risk_gate.py
- scripts/ci/rust_risk_gate.sh --baseline docs/audit/rust_risk_baseline.toml
- cargo audit
- cargo deny check advisories
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m0-rust-1-97-1-qemu
- scripts/ci/test_plan_run.sh --target pi4 --stage 1 --state-dir out/test-plan/m0-rust-1-97-1-pi4
- scripts/ci/test_plan_run.sh --target pi4 --stage 2 --state-dir out/test-plan/m0-rust-1-97-1-pi4
Checks: the exact compiler, Cargo, rustfmt, Clippy, host standard library, and aarch64-unknown-none standard library resolve from Rust 1.97.1; all mandatory repository gates pass without product, protocol, authority, generated-artifact, or evidence-tier drift.
Deliverables: synchronized exact toolchain pins and documentation plus host and bare-metal compile, lint, test, dependency, generated-artifact, risk-ratchet, and staged Test Plan evidence.
Title/ID: m0-rust-current-stable-dependency-refresh
Milestone: Milestone 0 — Repository Skeleton & Toolchain / Current stable Rust dependency refresh
Goal: Move every crates.io dependency to its current stable, maintained release while preserving Cohesix protocol, authority, no_std, target, and evidence contracts.
Inputs: Cargo.toml, Cargo.lock, all workspace Cargo.toml files, host and no_std Rust sources/tests, RustSec advisories, crates.io release metadata, and staged Test Plan gates.
Changes:
- Cargo manifests + Cargo.lock — refresh compatible dependencies, migrate direct breaking releases, and remove or replace unmaintained dependency lanes.
- host and no_std Rust sources/tests — adapt only the APIs required by the dependency migrations without changing Cohesix behavior, protocol, authority, or generated interfaces.
- docs/BUILD_PLAN.md + dependency-policy evidence — record exact scope, validation, intentional retained exceptions if any, and the final dependency frontier.
Commands:
- cargo update
- cargo fmt --all -- --check
- cargo clippy --workspace --all-targets -- -D warnings
- cargo check --workspace
- cargo check -p pi4-driver-runtime --target aarch64-unknown-none
- cargo test --workspace -- --test-threads=1
- cargo audit
- cargo deny check advisories
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m0-rust-current-stable-dependencies-qemu
Checks: every direct crates.io dependency resolves to its current stable maintained release or has a documented target/contract blocker; the resolved graph has no unaddressed advisory regression; all mandatory repository gates pass without product, protocol, authority, no_std, generated-artifact, or evidence-tier drift.
Deliverables: synchronized manifests and lockfile, required API migrations and tests, dependency/advisory evidence, generated-artifact verification, and staged Test Plan evidence.
Title/ID: m0-toml-1-1-4-maintenance
Milestone: Reopened Milestone 0 — Repository Skeleton & Toolchain / Current stable Rust dependency refresh
Goal: Qualify the TOML 1.1.4 patch refresh and close the generated-policy hash embedding drift exposed by its focused regression run without changing Cohesix behavior.
Inputs: Cargo.lock, the six direct TOML consumer manifests, exact Rust 1.97.1, coh-rtc generated policy/default artifacts, docs/USERLAND_AND_CLI.md, and dependency-policy checks.
Changes:
- Cargo manifests + Cargo.lock — advance the six direct TOML consumers from 1.1.3 to 1.1.4 and retain the resolver-selected compatible transitive graph.
- docs/USERLAND_AND_CLI.md — restore the two embedded generated hashes to the authoritative coh-rtc snippets; do not change policy/default semantics.
- docs/BUILD_PLAN.md — record the bounded maintenance scope, exact resolved graph, and validation evidence.
Commands:
- rustup show active-toolchain
- cargo metadata --locked --no-deps --format-version 1
- cargo fmt --all -- --check
- cargo check --locked -p coh -p cohsh -p swarmui -p coh-rtc -p rust-risk-audit -p security-nist
- cargo test --locked -p coh -p cohsh -p swarmui -p coh-rtc -p rust-risk-audit -p security-nist
- cargo clippy --locked -p coh -p cohsh -p swarmui -p coh-rtc -p rust-risk-audit -p security-nist --all-targets -- -D warnings
- python3 scripts/ci/check_swarmui_dependencies.py
- cargo audit
- cargo deny check advisories
- scripts/check-generated.sh
Checks: all six affected packages compile and test under exact Rust 1.97.1; dependency/advisory policy remains green; generated artifacts and their embedded documentation blocks agree byte-for-byte.
Deliverables: synchronized manifests, lockfile, generated-doc embedding, and bounded validation evidence with Milestone 0 returned to Complete.
Title/ID: m0-host-setup-parity-repair
Milestone: Reopened Milestone 0 — Repository Skeleton & Toolchain / macOS and Ubuntu ARM64 host setup parity repair
Goal: Make one canonical setup command provision each supported host-build lane and a shared repository Python environment without overstating Linux target acceptance.
Inputs: toolchain/setup_macos_arm64.sh, toolchain/setup_linux_arm64.sh, scripts/setup_environment.sh, configs/test-plan-python-requirements.lock, tools/cohesix-py/pyproject.toml, README.md, docs/QUICKSTART.md, docs/TOOLCHAIN_MAC_ARM64.md, docs/PYTHON_SUPPORT.md, release inventory, and host setup tests.
Changes:
- toolchain/setup_macos_arm64.sh — enforce macOS 26+, Apple Silicon, Xcode Command Line Tools, ripgrep, and HVF prerequisites before completing the existing pinned seL4 host setup.
- toolchain/setup_linux_arm64.sh — enforce Ubuntu 22.04/24.04/26.04 ARM64, install the correct QEMU ARM system package and complete host-tool build dependencies, select Python 3.11+ per LTS, and verify diagnostic TCG.
- toolchain/setup_repo_venv.sh — create the non-symlinked repository `.venv` from the hash-locked host-test closure and install `tools/cohesix-py` editable without optional integration or ML dependencies.
- scripts/setup_environment.sh — keep the release-bundle path runtime-only, correct Ubuntu QEMU/GTK package selection, support the three ARM64 LTS releases, enable Universe only when installation is needed, fail closed on incompatible hosts, verify HVF or TCG, and install the exact bundled Python wheel into a protected `.venv` without conflating runtime readiness with target acceptance.
- README.md + docs/QUICKSTART.md + docs/TOOLCHAIN_MAC_ARM64.md + docs/PYTHON_SUPPORT.md — project one-command setup for each OS and retain the distinct macOS construction, Linux diagnostic-QEMU, and target-acceptance boundaries.
- tests/test_toolchain_setup.py + scripts/ci/check_test_plan.sh — guard platform, package, Python, documentation, and shell-syntax contracts. The complete host-tool suite, `tools/cohesix-py`, and performance benchmark scripts were reviewed; only Python environment installation is affected, with no protocol, benchmark workload, or report-schema change.
Commands:
- bash -n toolchain/setup_macos_arm64.sh toolchain/setup_linux_arm64.sh toolchain/setup_repo_venv.sh
- scripts/setup_environment.sh --check
- .venv/bin/python -m pytest -q tests/test_toolchain_setup.py
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
Checks: both installers reject hosts outside their exact support envelope before mutation, expose help without platform preflight, install the shared locked `.venv` by default, and preserve separate full-construction, diagnostic-QEMU, and acceptance claims; focused tests and repository consistency gates pass.
Deliverables: corrected canonical host installers, a shared repository Python bootstrap, simplified macOS/Linux quickstart documentation, and deterministic regression coverage with Milestone 0 returned to Complete.
M0 dependency-refresh evidence (2026-07-28)
- All 47 direct crates.io dependencies resolve to their current stable releases. Required breaking migrations cover AES, Axum, Base64, CBOR, Ed25519/signature, FUSE, libloading, NVML, Rand, SHA-2, smoltcp, spin, syn, Tauri, TOML, and ureq.
cargo update --dry-run -vreports no further resolvable updates. Five transitive packages remain intentionally constrained by the current direct parents:generic-array 0.14.7through Tauri’s SHA-2 0.10 graph,matchit 0.8.4through Axum 0.8.9, andtoml 0.8.2,toml_datetime 0.6.3, andtoml_edit 0.20.2through Tauri’s GTK3 build graph. Forcing the advertised newer versions fails the upstream exact-version requirements; no local patch or duplicate authority lane is introduced.cargo auditreports no vulnerability failure. Its 17 allowed warnings are the existing unmaintained/unsound GTK3 andurlpatterntransitive graph retained by current Tauri;cargo deny check advisoriespasses. The obsolete serde_cbor and FUSE advisory exceptions are removed.- Formatting, workspace Clippy with warnings denied, workspace/all-target
compilation, FUSE/NVML/Tauri optional compilation, QEMU root-task
compilation, the
aarch64-unknown-nonePi runtime compilation, generated artifact checks, 706 Pi runtime tests, and every dependency-migration test pass. cargo test --workspace --no-fail-fastpasses under exact Rust 1.97.1. The stale serial-flood fairness assertion now matches the already-established independent serial/local-seat partial-line contract; no runtime behavior or operator grammar changed.- The QEMU release-feature library matrix also passes under Rust 1.97.1 after its fixtures were aligned with the single-attempt supervisor, bounded diagnostic output, independent physical-input scheduling, and current diagnostic-precedence contracts. These are test-harness corrections only; target runtime behavior and operator grammar are unchanged.
M0 TOML maintenance evidence (2026-07-29)
- The six direct host consumers now resolve TOML
1.1.4. The lockfile also advancesdisplaydocto0.2.7andtao-macrosto0.1.4; Tauri utilities retain their independently compatible existing TOML0.9.12edge. Acargo update --dry-run -vreports zero additional compatible updates and preserves the five already documented parent-constrained exceptions. - The patch refresh changes no source API, protocol, authority, manifest, or
target behavior.
coh-rtcoutput remains byte-identical. The focused test run exposed two stale generated-policy hashes embedded indocs/USERLAND_AND_CLI.mdby the earlier5e50c5c62manifest regeneration; those two embedded values now match the authoritative standalone snippets without changing policy/default semantics. - Exact Rust/Cargo
1.97.1, locked metadata, formatting, strict Clippy for all affected targets, affected-package compilation and tests, SwarmUI dependency policy, generated-artifact/test-plan/NIST guards, and diff checks pass.cargo auditretains the same 17 allowed Tauri GTK3/urlpattern warnings with no vulnerability failure, andcargo deny check advisoriespasses.
Milestone 1 — Boot Banner, Timer, & First IPC
Status: Complete — boot banner, timer tick, and initial IPC appear in current boot logs; retain existing log ordering. Deliverables
- Root task prints a banner and configures a periodic timer tick.
- Root task spawns a secondary user component via seL4 endpoints.
- Demonstrate one ping/pong IPC exchange and timer-driven logging.
- Added runtime CSpace-path assert for all retypes.
- Scaffold
cohshCLI prototype (command parsing + mocked transport) perdocs/USERLAND_AND_CLI.md §2-§4so operators can observe logs viatailand exercise attach/login flows defined indocs/INTERFACES.md §7.
Checks
- QEMU serial shows boot banner and periodic
tickline. - QEMU serial logs
PING 1/PONG 1sequence exactly once per boot. - No panics; QEMU terminates cleanly via monitor command.
M1 → M2 Transition Note
- Retype now targets the init root CNode using the canonical tuple
(root=seL4_CapInitThreadCNode, node_index=0, node_depth=bootinfo.initThreadCNodeSizeBits, slot)and validates capacity viainitThreadCNodeSizeBits.
Milestone 2 — NineDoor Minimal 9P
Status: Complete — Secure9P codec, fid/session handling, and the synthetic namespace are active; follow-up limited to ongoing fuzz coverage. Deliverables
- Secure9P codec + fid/session table implementing
version,attach,walk,open,read,write,clunk. - Synthetic namespace publishing:
/proc/boot(read-only text)/log/queen.log(append-only)/queen/ctl(append-only command sink)/worker/<id>/telemetry(append-only, created on spawn)
- In-VM transport (shared ring or seL4 endpoint wrapper). No TCP inside the VM.
cohshCLI upgraded to speak the live NineDoor transport (mock removed) while preserving operator workflows.- Implementation satisfies the defences and layering requirements from
docs/SECURE9P.md §2-§5and strictly adheres todocs/INTERFACES.md §1-§6for operation coverage, ticket validation, and error semantics. - These flows are defined for one Queen orchestrating many workers within a hive; host tools (CLI or GUI) drive them via
cohsh.
Checks
- Integration test attaches, walks, reads
/proc/boot, and appends to/queen/ctl. - Attempting to write to
/proc/bootfails withPermission. - Decoder corpus covers malformed frames (length mismatch, fid reuse).
Milestone 3 — Queen/Worker MVP with Roles
Status: Complete for the Queen/Worker session model — roles, budgets, and
/queen/ctl JSON handling are live in root/host model state; this milestone did
not prove a separate Worker target task.
Deliverables
- Role-aware access policy implementing
QueenandWorkerHeartbeatroles. /queen/ctlaccepts JSON commands:{"spawn":"heartbeat","ticks":100}{"kill":"<id>"}{"budget":{"ttl_s":120,"ops":1000}}(optional fields)
- The root/host Worker-heart model appends
"heartbeat <tick>"lines to the selected Worker telemetry path. - Budget enforcement (ttl/ticks/ops) with automatic revocation.
- Access policy follows
docs/ROLES_AND_SCHEDULING.md §1-§5and the queen control schema indocs/INTERFACES.md §3-§4; all JSON handling must reject unknown formats as defined in the error table (docs/INTERFACES.md §8). - These queen/worker flows assume one Queen orchestrating many workers within a hive, exercised through
cohshor clients speaking its protocol.
Checks
- Writing spawn command creates bounded Worker model state and its telemetry stream.
- Writing kill removes worker directory and closes telemetry file.
- Role isolation tests deny cross-role reads/writes.
Milestone 4 — Bind & Mount Namespaces
Status: Complete — Per-session mount tables are implemented; future changes must preserve established bind/mount semantics from SECURE9P.md.
Deliverables
- Per-session mount table with
bind(from, to)andmount(service, at)operations scoped to a single path. - Queen-only commands for namespace manipulation exposed via
/queen/ctl. - Namespace operations mirror the behaviour defined in
docs/INTERFACES.md §3and respect mount expectations indocs/ARCHITECTURE.md §4. - Mount and namespace flows remain scoped to one Queen orchestrating many workers inside a hive, driven by
cohsh(and future GUI clients that speak its protocol).
Checks
- Queen remaps
/queento a subdirectory without affecting other sessions. - Attempted bind by a worker fails with
Permission.
Milestone 5 — Hardening & Test Automation (ongoing)
Status: Complete — Unit/fuzz/integration coverage exists; maintain regression packs as features evolve. Deliverables
- Unit tests for codec, fid lifecycle, and access policy negative paths.
- Fuzz harness covering length-prefix mutations and random tail bytes for the decoder.
- Integration test: spawn heartbeat → emit telemetry → kill → verify revocation logs.
- Cohsh regression scripts (per
docs/USERLAND_AND_CLI.md §6-§7) execute against mock and QEMU targets, ensuring CLI and Secure9P behaviours stay aligned.
Checks
cargo testpasses in CI.- Fuzz harness runs N iterations (configurable) without panic.
Milestone 6 — GPU Worker Integration
Status: Complete for the host-side bridge, simulation, schema, and Worker-role model. No executable VM Worker task was completed here; that remains conditional on a later profile with target-created task objects and matching capability, lifecycle, scheduling, fault, and revocation evidence. Deliverables
- Define
WorkerGpurole and extend/queen/ctlschema with GPU lease requests. - Host-side
gpu-bridge-hosttool implementing NVML-based discovery (feature-gated) and--mocknamespace mirroring for/gpu/<id>/*. - Job submission protocol (JSON) supporting vector add and matrix multiply kernels with SHA-256 payload validation, optional inline payloads, and status fan-out to
/gpu/<id>/statusand/worker/<id>/telemetry. - Implementation must align with
docs/GPU_NODES.md §2-§7, uphold the command schemas indocs/INTERFACES.md §3-§5, and keep VM-side responsibilities within the boundaries indocs/ARCHITECTURE.md §7-§8. - The shipped host bridge and simulation paths are production-grade within their documented bounds. Host simulation and a Worker-role model do not establish an executable target Worker or a fully implemented GPU stack.
Checks
- Queen creates a bounded GPU Worker model record and receives logical Worker telemetry; host simulation does not launch a target Worker task.
- Lease expiry revokes Worker-model/session access and closes the host-simulation
/gpu/<id>/jobhandle. - Host integration tests run in
--mockmode when GPUs are absent.
Rule of Engagement: Advance milestones sequentially, treat documentation as canonical, and keep code/tests aligned after every milestone increment.
Future Note: A host-side WASM GUI is expected as a hive dashboard layered on the
cohshprotocol; it does not alter kernel/userspace boundaries or introduce new in-VM services.
Milestone 6a — GPU Model Lifecycle & Telemetry Semantics (LoRA-ready)
Status: Complete — host bridge and documentation now define model lifecycle surfaces, schema-tagged telemetry, and export guarantees without altering in-VM capabilities.
Why this exists (context)
Milestone 6 proved the GPU lease boundary and host bridge mechanics using kernel-style job submission. That validated the architecture, but it does not yet express model lifecycle state or learning-oriented telemetry semantics, which are required for PEFT / LoRA feedback loops at scale.
Milestone 6a adds no new execution capabilities and no new control channels. It introduces only file-level conventions and minimal host-bridge extensions so Cohesix can orchestrate model state and learning telemetry without becoming an ML runtime.
This milestone is intentionally boring.
Goal
Extend the existing gpu-bridge-host and GPU namespace with:
- Model lifecycle surfaces (selection + activation, not execution)
- Well-defined telemetry semantics suitable for LoRA / PEFT pipelines
while preserving:
- CUDA/NVML strictly outside the VM
- Secure9P as the only control plane
- WorkerGpu as a namespace-only role
- Deterministic memory and rate bounds
Deliverables
1. GPU Model Lifecycle Namespace (Host-side only)
Extend the mirrored GPU namespace with a model lifecycle view:
/gpu/models/
available/
<model_id>/
manifest.toml
active -> <model_id>
Properties:
available/is read-only to VM rolesactiveis a writable symlink-like pointer (atomic swap)- Model artifacts live on the host filesystem; Cohesix sees references only
- Activation semantics are host-defined (reload / restart / hot-swap)
Non-goals
- No model uploads via 9P
- No artifact streaming
- No training or conversion logic
2. Telemetry Schema for Learning Loops
Define and document a versioned telemetry schema for GPU learning feedback.
Required fields (minimum):
schema_versiondevice_idmodel_idlora_id(optional)time_windowtoken_countlatency_histogram
Optional fields:
- confidence / entropy
- drift indicators
- operator feedback flags
Telemetry continues to flow through existing paths:
/gpu/telemetry/*
/worker/<id>/telemetry
Constraints:
- Size-bounded records
- Append-only semantics
- Explicit windowing (no unbounded streams)
3. Worker Behavior (No New Roles)
WorkerGpu behavior remains minimal:
- Observe
/gpu/models/active - Include
model_id/lora_idin forwarded telemetry - Enforce existing rate and size limits
No new worker types or privileges are introduced.
4. Queen Export Compatibility (No Training Logic)
Ensure telemetry emitted under the new schema can be exported unchanged via:
/queen/telemetry/* /queen/export/lora_jobs/*
Milestone 6a does not implement training, scheduling, or PEFT tooling. It only guarantees that exported telemetry is:
- Structured
- Bounded
- Policy-checkable
- ML-pipeline friendly
Files & Components Touched
gpu-bridge-host- Add model lifecycle surfaces
- Implement atomic model activation
- Emit telemetry records with schema tags
docs/GPU_NODES.md- Document
/gpu/models/* - Clarify separation between job execution vs model state
- Document
docs/INTERFACES.md- Telemetry schema definition
- Explicit size and rate limits
docs/USE_CASES.md- Reference LoRA / PEFT edge feedback loop (informational)
No changes to:
- seL4 kernel usage
- Secure9P protocol
- NineDoor access policy logic
- Worker role definitions
Checks (Definition of Done)
- Existing Milestone 6 GPU kernel tests still pass unchanged
- Switching
/gpu/models/activecauses host-side model reload - Telemetry records include valid schema headers
- Oversized or malformed telemetry is rejected
- Worker cannot upload models or bypass leases
- No new in-VM dependencies introduced
Outcome
After Milestone 6a:
- Cohesix can safely coordinate model evolution at the edge
- PEFT / LoRA pipelines can consume telemetry without bespoke glue
- GPU execution remains host-owned
- The control plane remains deterministic, auditable, and small
Milestone 6 stays about capability.
Milestone 6a is about intent.
Milestone 7a — Root-Task Event Pump & Authenticated Kernel Entry
Status: Complete — Event pump replaces the spin loop; authenticated console flow and serial integration are live. Preserve PL011 logging and audit ordering during follow-up changes. Deliverables
- Deprecate legacy spin loop
- Replace the placeholder busy loop in
kernel_startwith a cooperative event pump that cycles serial RX/TX, timer ticks, networking polls, and IPC dispatch without relying onstdprimitives. - Capture wake ordering and preemption notes in module docs so subsequent milestones can extend the pump without regressing determinism.
- Instrument the transition with structured audit logs showing when the pump initialises each subsystem.
- Replace the placeholder busy loop in
- Serial event integration (no-std)
- Introduce a
root-taskserialmodule built atop OSS crates such asembedded-ioandnbfor trait scaffolding while maintaining zero-allocation semantics usingheaplessbuffers. - Provide interrupt-safe reader/writer abstractions that feed the event pump, expose per-source back-pressure counters via
portable-atomic, and enforce UTF-8 sanitisation before lines reach the command parser. - Add conformance tests that replay captured QEMU traces to guarantee debounced input (backspace, control sequences) behaves identically across boots.
- Introduce a
- Networking substrate bootstrapping
- Integrate the virtio-net PHY and
smoltcpdevice glue behind a feature gate, seeding deterministic RX/TX queues usingheapless::{Vec, spsc::Queue}and documenting memory bounds indocs/SECURITY.md. - Ensure the event pump owns the poll cadence for
smoltcp, handles link up/down notifications, and publishes metrics to/proc/bootfor observability. - Provide fault-injection tests that exhaust descriptors, validate checksum handling, and assert the pump survives transient PHY resets.
- Integrate the virtio-net PHY and
- Authenticated command loop
- Embed a shared command parser (serial + TCP) constructed with
heapless::Stringand finite-state validation to enforce maximum line length, reject unsupported control characters, and throttle repeated failures with exponential back-off. - Hook authentication into the root-task capability validator so privileged verbs (
attach,spawn,kill,log) require valid tickets, emitting audit lines to/log/queen.logon denial. - Add integration tests that execute scripted login attempts, verify rate limiting, and confirm the event pump resumes servicing timers and networking during authentication stress.
- Embed a shared command parser (serial + TCP) constructed with
- Documentation updates
- Update
docs/ARCHITECTURE.mdanddocs/SECURITY.mdwith the new event pump topology, serial/network memory budgets, and authenticated console flow diagrams. - Document migration steps for developers moving from the spin loop to the event pump, including feature flags and testing guidance in
docs/REPO_LAYOUT.mdor relevant READMEs.
- Update
Checks
- Root task boots under QEMU, initialises the event pump, and logs subsystem activation without reintroducing the legacy busy loop.
- Serial RX/TX, networking polls, and command handling execute deterministically without heap allocations; fuzz/property tests cover parser and queue saturation paths.
- Authenticated sessions enforce capability checks, rate limit failures, and keep timer/NineDoor services responsive during sustained input.
Task Breakdown
Title/ID: m7a-event-pump-core
Goal: Replace the kernel_start spin loop with a cooperative no-std event pump.
Inputs: docs/ARCHITECTURE.md §§2,4; docs/SECURITY.md §§3-4; existing root-task entrypoint.
Changes:
- crates/root-task/src/kernel.rs — remove spin loop, initialise serial/net/timer pollers, and document scheduling guarantees.
- crates/root-task/src/event/mod.rs — new event pump coordinator orchestrating serial, timer, IPC, and networking tasks with explicit tick budgeting.
- crates/root-task/tests/event_pump.rs — unit tests covering scheduling fairness, back-pressure propagation, and panic-free shutdown paths.
Commands: cd crates/root-task && cargo test event_pump && cargo check --features net && cargo clippy --features net --tests
Checks: Event pump drives serial, timer, and networking tasks deterministically; tests cover starvation and shutdown.
Deliverables: Root-task event pump replacing legacy loop with documented guarantees and regression tests.
Title/ID: m7a-serial-auth
Goal: Provide authenticated serial command handling with rate limiting and audit trails.
Inputs: docs/INTERFACES.md §§3,7-8; docs/SECURITY.md §5; embedded-io 0.4; heapless 0.8.
Changes:
- crates/root-task/src/console/mod.rs — integrate heapless line editor, authentication state machine, and audit logging.
- crates/root-task/src/console/serial.rs — implement no-std serial driver traits, UTF-8 sanitisation, and per-byte throttling metrics.
- crates/root-task/tests/console_auth.rs — tests for login success/failure, rate limiting, control sequence rejection, and audit log outputs.
Commands: cd crates/root-task && cargo test console_auth && cargo check --features net && cargo clippy --features net --tests
Checks: Serial console authenticates commands, enforces throttling, and keeps event pump responsive under stress.
Deliverables: Hardened serial console with authentication, audit coverage, and passing tests.
Title/ID: m7a-net-loop
Goal: Embed the smoltcp-backed networking poller into the event pump with deterministic buffers.
Inputs: docs/ARCHITECTURE.md §§4,7; docs/SECURITY.md §4; smoltcp 0.11; heapless 0.8; portable-atomic 1.6.
Changes:
- crates/root-task/src/net/mod.rs — finalise virtio-net PHY, smoltcp integration, and bounded queues with instrumentation.
- crates/root-task/src/event/net.rs — event pump adapter scheduling smoltcp polls, handling link state, and surfacing metrics.
- crates/root-task/tests/net_pump.rs — property tests for descriptor exhaustion, checksum validation, and PHY reset recovery.
Commands: cd crates/root-task && cargo test --features net net_pump && cargo check --features net && cargo clippy --features net --tests
Checks: Networking poller integrates with event pump, survives fault injection, and maintains deterministic buffer usage.
Deliverables: Networking subsystem integrated with event pump, documented, and guarded by targeted tests.
Title/ID: m7a-docs-migration
Goal: Update documentation for the event pump, authenticated console, and networking integration.
Inputs: docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/SECURITY.md, existing milestone notes.
Changes:
- docs/ARCHITECTURE.md — describe event pump topology, serial/net modules, and removal of spin loop.
- docs/SECURITY.md — record authenticated console threat model, rate limiting strategy, and memory quotas.
- docs/REPO_LAYOUT.md & crate READMEs — outline developer workflows, feature flags, and testing commands for the new pump.
Commands: cargo doc -p root-task --document-private-items && mdbook build docs (if configured)
Checks: Documentation builds cleanly, reflects new architecture, and guides developers through migration.
Deliverables: Synchronized documentation explaining event pump adoption, security posture, and developer workflows.
Milestone 7b — Standalone Console & Networking (QEMU-first)
Status: Complete — PL011 root console and TCP console co-exist; networking stack is feature-gated and non-blocking. Virtio-console is not used; PL011 remains the root console (see ARCHITECTURE.md for dual-console expectations).
Deliverables
- Serial console integration
- Implement a bidirectional serial driver for QEMU (
virtio-consolepreferred, PL011 fallback) that supports blocking RX/TX (no heap, nostd) and exposes an interrupt-safe API so the event pump can integrate timer and network wake-ups. - Replace the
kernel_startspin loop with an event pump that polls serial input, dispatches parsed commands, services outgoing buffers, and yields to networking/timer tasks without starving the scheduler. - Enforce ticket and role checks before privileged verbs execute; log denied attempts to
/log/queen.log, apply exponential back-off when credentials are wrong, and drop connections that exceed retry quotas.
- Implement a bidirectional serial driver for QEMU (
- Networking substrate
- Add
smoltcp(Rust, BSD-2) to the root-task crate under a newnetmodule with explicit feature gating so baseline builds stay minimal. - Implement a virtio-net MMIO PHY for QEMU, encapsulate the device behind a trait that abstracts descriptor management, and document the register layout alongside reset/feature negotiation flows.
- Use
heapless::{Vec, spsc::Queue}for RX/TX buffers to keep allocations deterministic; document memory envelopes indocs/SECURITY.mdand prove queue saturation behaviour with tests.
- Add
- Command loop
- Build a minimal serial + TCP line editor using
heapless::Stringand a finite-state parser for commands (help,attach,tail,log,quit, plusspawn/killstubs that forward JSON to NineDoor) with shared code paths so behaviours remain identical across transports. - Integrate the loop into the root-task main event pump alongside timer ticks, networking polls, and IPC dispatch while enforcing capability checks before invoking root-task RPCs.
- Rate-limit failed logins, enforce maximum line length, reject control characters outside the supported set, and record audit events whenever a session hits throttling.
- Build a minimal serial + TCP line editor using
Checks
- QEMU boot brings up the root task, configures smoltcp, accepts serial commands, and listens for TCP attachments on the configured port.
cohsh --transport tcpcan attach, tail logs, and quit cleanly; regression scripts cover serial-only mode.- Fuzz or property-based tests exercise the new parser and networking queues without panics.
Task Breakdown
Title/ID: m7b-serial-rx
Goal: Provide bidirectional serial I/O for the root-task console in QEMU.
Inputs: docs/ARCHITECTURE.md §2; docs/INTERFACES.md §7; seL4 virtio-console/PL011 specs; `embedded-io` 0.4 (optional traits).
Changes:
- crates/root-task/src/console/serial.rs — MMIO-backed RX/TX driver exposing `read_byte`/`write_byte` without heap allocation, plus interrupt acknowledgement helpers and a shared rate-limiter primitive for reuse by the console loop.
- crates/root-task/src/kernel.rs — initialise the serial driver, hook it into the event pump, remove the legacy busy loop, and document the wake-up ordering for timer/net/serial sources.
- crates/root-task/tests/serial_stub.rs — host-side stub verifying backspace/line termination handling, throttle escalation, and the audit log entries emitted by repeated authentication failures.
Commands: cd crates/root-task && cargo test serial_stub && cargo check --features net && cargo clippy --features net --tests
Checks: Serial RX consumes interactive input without panics; console loop handles backspace/newline, rate limiting, and audit logging in QEMU.
Deliverables: Root-task serial driver initialised during boot with regression tests for RX edge cases and throttling safeguards.
Title/ID: m7b-net-substrate
Goal: Wire up a deterministic networking stack for the root task.
Inputs: docs/ARCHITECTURE.md §§4,7; docs/INTERFACES.md §§1,3,6; docs/SECURITY.md §4; smoltcp 0.11; heapless 0.8; portable-atomic 1.6.
Changes:
- crates/root-task/Cargo.toml — add `smoltcp`, `heapless`, and `portable-atomic` dependencies behind a `net` feature along with feature docs explaining footprint impact.
- crates/root-task/src/net/mod.rs — introduce PHY trait, virtio-net implementation (descriptor rings, IRQ handler), smoltcp device glue, bounded queues, and defensive checks for descriptor exhaustion.
- crates/root-task/src/main.rs — initialise networking, register poller within the root-task event loop, and expose metrics hooks so audit logs can capture link bring-up status.
- docs/SECURITY.md — document memory envelopes, networking threat considerations, and mitigations for RX flooding or malformed descriptors.
Commands: cd crates/root-task && cargo check --features net && cargo test --features net net::tests && cargo clippy --features net --tests
Checks: Smoltcp interface boots in QEMU with deterministic heap usage; unit tests cover RX/TX queue saturation, link bring-up, error paths, and descriptor validation.
Deliverables: Root-task networking module with virtio-net backend, updated security documentation, and passing feature-gated tests reinforced by lint coverage.
Title/ID: m7b-console-loop
Goal: Provide an authenticated serial/TCP command shell bound to capability checks.
Inputs: docs/INTERFACES.md §§3-5,8; docs/SECURITY.md §5; existing root-task timer/IPC code; heapless 0.8.
Changes:
- crates/root-task/src/console/mod.rs — add finite-state parser, rate limiter, shared line editor for serial/TCP sources, and an authentication/session manager that reuses ticket validation helpers.
- crates/root-task/src/main.rs — integrate console loop with networking poller and ticket validator while ensuring timer/NineDoor tasks retain service guarantees.
- crates/root-task/tests/console_parser.rs — unit tests for verbs, overlong lines, login throttling, Unicode/control character handling, and audit log integration.
Commands: cd crates/root-task && cargo test --features net console_parser && cargo clippy --features net --tests
Checks: Parser rejects invalid verbs, enforces max length, rate limits failed logins, normalises newline sequences, and verifies capability enforcement via mocks.
Deliverables: Hardened console loop with comprehensive parser tests integrated into root-task and lint-clean CI coverage.
Milestone 7c — TCP transport parity while retaining existing flows
Status: Complete — TCP transport, documentation updates, and integration tests are in tree; keep host build scripts and console fixtures in sync when toggling transport flags. Deliverables
- Remote transport
- Extend
cohshwith a TCP transport that speaks to the new in-VM listener while keeping the existing mock/QEMU flows; expose reconnect/back-off behaviour and certificate-less ticket validation for the prototype environment. - Reuse the current NineDoor command surface so scripting and tests stay aligned, document the new
--transport tcpflag with examples, and ensure help text highlights transport fallbacks when networking is unavailable.
- Extend
- Documentation & tests
- Update
docs/ARCHITECTURE.md,docs/INTERFACES.md, anddocs/SECURITY.mdwith the networking/console design, threat model, and TCB impact including memory budgeting tables for serial/net buffers. - Provide QEMU integration instructions (
docs/USERLAND_AND_CLI.md) showing serial console usage, remotecohshattachment, and recommended port-forwarding commands for macOS host tooling. - Add unit tests for the command parser (invalid verbs, overlong lines), virtio queue wrappers, and integration tests that boot QEMU, connect via TCP, run scripted sessions, and verify audit log outputs.
- Record the TCP console toggle in
configs/root_task.tomlonce the manifest compiler lands (Milestone 8b) so docs and fixtures remain in sync.
- Update
Task Breakdown
Title/ID: m7c-cohsh-tcp
Goal: Extend cohsh CLI with TCP transport parity while retaining existing flows.
Inputs: docs/USERLAND_AND_CLI.md §§2,6; docs/INTERFACES.md §§3,7; existing cohsh mock/QEMU transport code.
Changes:
- apps/cohsh/Cargo.toml — gate TCP transport feature and dependencies, annotate default-off status, and document cross-compilation requirements for macOS hosts.
- apps/cohsh/src/transport/tcp.rs — implement TCP client with ticket authentication, reconnect handling, heartbeats, and telemetry logging for CLI operators.
- apps/cohsh/src/main.rs — add `--transport tcp` flag and configuration plumbing, including environment overrides and validation for mutually exclusive serial parameters.
- docs/USERLAND_AND_CLI.md — document CLI usage, examples, regression scripts covering serial and TCP paths, and troubleshooting steps for QEMU port forwarding.
Commands: cd apps/cohsh && cargo test --features tcp && cargo clippy --features tcp --tests && cargo fmt --check
Checks: CLI attaches via TCP to QEMU instance, tails logs, forwards NineDoor commands, retains existing regression flow for serial transport, and recovers gracefully from simulated disconnects.
Deliverables: Feature-complete TCP transport with documentation, tests validating CLI behaviour, and formatting/lint coverage.
Title/ID: m7c-docs-integration-tests
Goal: Finalise documentation updates and cross-stack integration tests for networking milestone.
Inputs: docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/SECURITY.md, docs/USERLAND_AND_CLI.md; existing integration harness scripts.
Changes:
- docs/ARCHITECTURE.md — describe networking module, console loop, PHY abstraction, and update diagrams to illustrate serial/net event pump interactions.
- docs/INTERFACES.md — specify TCP listener protocol, authentication handshake, console commands, and error codes for throttling or malformed frames.
- docs/SECURITY.md — extend threat model with networking attack surfaces, mitigations, audit expectations, and documented memory bounds.
- tests/integration/qemu_tcp_console.rs — scripted boot + TCP session exercising help/attach/tail/log/quit verbs, plus negative tests for failed logins and overlong lines.
- scripts/qemu-run.sh — accept networking flags, expose forwarded TCP port, document usage, and emit helpful diagnostics when host prerequisites (tap/tuntap) are missing.
Commands: ./scripts/qemu-run.sh --net tap --console tcp --exit-after 120 && cargo test -p tests --test qemu_tcp_console && cargo clippy -p tests --tests
Checks: Automated QEMU run brings up TCP console reachable from host; integration test passes end-to-end; documentation reviewed for consistency and security sign-off.
Deliverables: Updated documentation set, automation scripts, and passing QEMU TCP console integration test with lint coverage.
Milestone 7d — ACK/ERR broadcast is implemented across serial and TCP
Status: Complete — ACK/ERR broadcast is implemented across serial and TCP with shared fixtures, reconnection semantics, and documentation in place. Deliverables
- Ensure the PL011 root console remains active alongside the TCP listener; TCP handling must stay non-blocking so serial recovery remains deterministic (see
ARCHITECTURE.md). - Attachments must respect the current NineDoor handshake and ticket validation; acknowledgements should reuse the parser grammar from
USERLAND_AND_CLI.md. - Console acknowledgements
- Enable the root-task TCP listener to emit
OK/ERRresponses forATTACH, heartbeat probes, and command verbs so remote operators receive immediate feedback. - Surface execution outcomes (success, denial, or validation failure) through the shared serial/TCP output path with structured debug strings suitable for regression tests.
- Enable the root-task TCP listener to emit
- Client alignment
- Ensure
cohshreuses the acknowledgement surface for telemetry, surfacing attach/session state changes and command failures consistently across transports.
- Ensure
- Documentation & tests
- Update protocol documentation to describe the acknowledgement lifecycle, including reconnection semantics and error payloads.
- Extend automated coverage so both serial and TCP transports assert the presence of acknowledgements during scripted sessions.
Checks (DoD)
- Adding ACK/ERR output MUST NOT change line prefixes, newline behaviour, or attach handshake timing established in Milestone 7c. The Regression Pack must pass without modifying any fixture.
Task Breakdown
Title/ID: m7d-console-ack
Goal: Implement bidirectional console responses covering attach handshakes and command execution outcomes.
Inputs: docs/INTERFACES.md §7; docs/USERLAND_AND_CLI.md §6; apps/root-task/src/event/mod.rs; apps/root-task/src/net/virtio.rs; apps/cohsh/src/transport/tcp.rs.
Changes:
- apps/root-task/src/event/mod.rs — introduce an acknowledgement dispatcher that emits success/error lines for each validated command, wiring into both serial and TCP paths.
- apps/root-task/src/net/virtio.rs & apps/root-task/src/net/queue.rs — plumb outbound console buffers so TCP clients receive the acknowledgement lines generated by the event pump without blocking polling guarantees.
- apps/cohsh/src/transport/tcp.rs — consume acknowledgement lines for attach/command verbs, surfacing them in CLI output and telemetry, and hardening reconnect flows when acknowledgements are missing.
- docs/INTERFACES.md & docs/USERLAND_AND_CLI.md — document the acknowledgement grammar, heartbeat expectations, and troubleshooting guidance for mismatched responses.
Commands: (cd apps/root-task && cargo test --features net && cargo clippy --features net --tests && cargo fmt --check) && (cd apps/cohsh && cargo test --features tcp && cargo clippy --features tcp --tests && cargo fmt --check)
Checks: TCP console responds with acknowledgements for attach/log/tail commands; serial harness mirrors the same output; regression suite covers success and failure cases with deterministic logs.
Deliverables: Bidirectional console acknowledgements spanning serial and TCP transports, updated protocol documentation, and passing unit/integration tests with lint/format coverage.
Foundation Allowlist (for dependency reviews / Web Codex fetches)
https://crates.io/crates/smoltcphttps://crates.io/crates/heaplesshttps://crates.io/crates/portable-atomic(for lock-free counters)https://crates.io/crates/embassy-executorandhttps://crates.io/crates/embassy-net(future async extension, optional)https://crates.io/crates/log/defmt(optional structured logging while developing the stack)https://crates.io/crates/embedded-io(serial/TCP trait adapters)https://crates.io/crates/nb(non-blocking IO helpers)https://crates.io/crates/spin(lock primitives for bounded queues)
Milestone 7e — TraceFS (JSONL Synthetic Filesystem)
Status: Complete — TraceFS provider backs /trace/* and worker traces; control-plane filters and CLI coverage are wired without regressing existing mounts (see SECURE9P.md).
Purpose
Add a minimal synthetic 9P provider (tracefs) exposing JSONL-based tracing and diagnostic streams.
Enable root-task and userspace components to log, filter, and stream events via append-only 9P files, following the Plan 9 “everything is a file” model.
Deliverables
- New
nine-doorprovider/trace/ctl,/trace/events,/kmesg, and per-task/proc/<tid>/trace. - Root-task
Tracefacade with zero-allocation ring buffer andtrace!()macro. - Category/level filters controllable by writing JSON commands to
/trace/ctl. - Persistent, append-only JSONL event format shared across roles.
- CLI (
cohsh) integration fortail/echocommands against/trace/*. - Optional host-side mirroring via a bridge mount.
Commands (Mac ARM64)
SEL4_BUILD_DIR=$HOME/seL4/build \
./scripts/cohesix-build-run.sh \
--sel4-build "$HOME/seL4/build" \
--out-dir out/cohesix \
--profile release \
--root-task-features kernel,bootstrap-trace,serial-console \
--cargo-target aarch64-unknown-none \
--transport qemu \
--raw-qemu
cohsh> echo '{"set":{"level":"debug","cats":["boot","ninep"]}}' > /trace/ctl
cohsh> tail /trace/events
Checks
/trace/eventsstreams JSONL trace lines after boot./trace/ctlaccepts JSON control messages without panic.- Per-task
/proc/<tid>/tracereturns filtered events. - Host build passes
cargo test -p nine-doorand integration testtests/cli/tracefs_script.sh.
Definition of Done
- Boot completes and serial console shows
[Cohesix] Root console ready. - Writing to
/trace/ctldynamically changes categories/levels. - Reading
/trace/eventsshows bounded ring output with sequence continuity. - No TCP or external logging inside the VM.
- Code aligned with
secure9p-*layering; passescargo clippy -- -D warnings. - TCP console must remain non-blocking and PL011 stays active as the fallback root console (see
ARCHITECTURE.md).
Milestone 8a — Lightweight Hardware Abstraction Layer
Why now (context): Kernel bring-up now relies on multiple MMIO peripherals (PL011 UART, virtio-net). Tight coupling to KernelEnv
spread driver responsibilities across modules, making future platform work and compiler integration harder to reason about.
Goal Carve out a lightweight Hardware Abstraction Layer so early boot and drivers consume a focused interface for mapping device pages and provisioning DMA buffers.
Deliverables
apps/root-task/src/hal/mod.rsintroducingKernelHaland theHardwaretrait that wrap device/DMA allocation, coverage queries, and allocator snapshots.apps/root-task/src/kernel.rsswitched to the HAL for PL011 bring-up and diagnostics, keeping boot logging unchanged.apps/root-task/src/drivers/{rtl8139.rs,virtio/net.rs}andapps/root-task/src/net/stack.rsupdated to rely on the HAL rather than touchingKernelEnvdirectly, simplifying future platform support and keeping NICs behind a sharedNetDevicetrait.- Documentation updates in this build plan describing the milestone and entry criteria.
Status: Complete — Kernel HAL now owns device mapping, diagnostics, and NIC bring-up (RTL8139 by default on dev-virt, virtio-net behind
the feature gate) while keeping console output stable.
Commands
cargo check -p root-task --features "kernel,net-console"
Checks (DoD)
- Root task still boots with PL011 logging and default RTL8139 initialisation via the HAL, with virtio-net available behind the feature gate for experiments.
- HAL error propagation surfaces seL4 error codes for diagnostics (no regression in boot failure logs).
- Workspace
cargo checksucceeds with the kernel and net-console features enabled. - Run the Regression Pack (see “Docs-as-Built Alignment”) to confirm console behaviour, networking event pump cadence, and NineDoor flows are unchanged despite the new HAL. Any change in ACK/ERR or
/proc/bootoutput must be documented and justified. - HAL introduction MUST NOT alter device MMIO layout, IRQ numbering, or virtio feature-negotiation visible in QEMU logs. Any change requires a manifest schema bump and doc update.
- Milestone 8a scope exception (authorized): A narrow TCP/virtio-net stability effort is permitted to unblock console bring-up, limited to:
- Minimal, feature-gated debug instrumentation in
apps/root-task/src/drivers/virtio/net.rsand queue helpers. - TX/RX publish ordering + cache visibility fixes, without protocol or console grammar changes.
- A host repro harness that drives the existing QEMU TCP console and cohsh
smoke flow. The original standalone helper was later retired when
scripts/cohsh/run_regression_batch.shandscripts/qemu_tcp_response_matrix.pybecame the canonical bounded paths. - No refactors, no new in-VM services, and no manifest/schema changes.
- Scope note (authorized): Feature-flag consolidation for root-task bring-up (
cleanup-1-feature-flags-consolidation) is permitted, limited to adding a single publiccohesix-devumbrella, removing dead flags, and updating scripts/docs without changing default behavior or console grammar. - Scope note (authorized): Instrumentation noise reduction (
cleanup-2-instrumentation-noise-reduction) is permitted, limited to heapless rate-limited counters and demoting/rate-limiting net/event pump spam without changing console protocol lines, ordering, or CLI/ACK semantics.
- Minimal, feature-gated debug instrumentation in
Milestone 8b — Root-Task Compiler & Deterministic Profiles
Why now (context): The event pump, HAL, and authenticated console now run end-to-end, but the configuration that wires tickets, namespaces, and capability budgets together still lives in hand-written Rust. A manifest-driven compiler lets us regenerate bootstrap code, docs, and CLI fixtures from one artefact so deployments stay auditable and reproducible.
Goal
Introduce the coh-rtc compiler that ingests configs/root_task.toml and emits deterministic artefacts consumed by the root task, docs, and regression suites.
Deliverables
configs/root_task.tomlcapturing schema version, platform profile, event-pump cadence, ticket inventory, namespace mounts, Secure9P limits, and feature toggles (e.g.,net-console).- Workspace binary crate
tools/coh-rtc/with modules:src/ir.rsdefining IR v1.0 with serde validation, red-line enforcement (walk depth ≤ 8,msize ≤ 8192, no..components), and feature gating that refusesstd-only options whenprofile.kernel = true.src/codegen/emitting#![no_std]Rust forapps/root-task/src/generated/{mod.rs,bootstrap.rs}plus JSON/CLI artefacts.- Integration tests under
tools/coh-rtc/tests/that round-trip sample manifests and assert deterministic hashes.
apps/root-task/src/lib.rsandapps/root-task/src/kernel.rsupdated to include the generated module (behind#[path = "generated/mod.rs"]) and to use manifest-derived tables for ticket registration, namespace wiring, and initial audit lines.apps/root-task/build.rsgains a check that fails the build if generated files are missing or stale relative toconfigs/root_task.toml.- Generated artefacts:
apps/root-task/src/generated/bootstrap.rs— init graph, ticket table, namespace descriptors with compile-time hashes.configs/generated/root_task_resolved.json— serialised IR with SHA-256 fingerprint stored alongside.scripts/cohsh/boot_v0.coh— baseline CLI script derived from the manifest to exercise attach/log/quit flows.
- Manifest IR gains optional
ecosystem.*section (schema-validated, defaults to noop):ecosystem.host.enable(bool)ecosystem.host.providers[](enum:systemd,k8s,nvidia,jetson,net)ecosystem.host.mount_at(default/host)ecosystem.audit.enable(bool)ecosystem.policy.enable(bool)ecosystem.models.enable(bool; future CAS hook)- Generated doc snippets call out that these nodes appear only when enabled.
- Documentation updates:
docs/ARCHITECTURE.md §11expanded with the manifest schema and regeneration workflow.docs/BUILD_PLAN.md(this file) references the manifest in earlier milestones.docs/REPO_LAYOUT.mdlists the newconfigs/andtools/coh-rtc/trees with regeneration commands.
Status: Complete — local aarch64/QEMU validation and regression pack confirm the DoD checks.
Commands
cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json --cli-script scripts/cohsh/boot_v0.cohcargo check -p root-task --no-default-features --features kernel,net-consolecargo test -p root-taskcargo test -p tools/coh-rtccargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/boot_v0.coh
Checks (DoD)
- Regeneration is deterministic: two consecutive runs of
cargo run -p coh-rtc …produce identical Rust, JSON, and CLI artefacts (verified via hash comparison recorded inconfigs/generated/root_task_resolved.json.sha256). - Root task boots under QEMU using generated bootstrap tables; serial log shows manifest fingerprint and ticket registration sourced from generated code.
- Compiler validation rejects manifests that violate red lines (e.g., invalid walk depth, enabling
gpuwhileprofile.kernelomits the feature gate) and exits with non-zero status. - Run the Regression Pack and reject any drift in
scripts/cohsh/boot_v0.cohoutput or manifest fingerprints unless the docs and schema version are updated in the same change. - Generated modules MUST NOT introduce new global state or reorder initialisation in a way that changes serial boot ordering or
/proc/bootoutput. - Compiler rejects manifests that set
ecosystem.host.enable = truewhen memory budgets or Secure9P red lines (msize, walk depth, role isolation) would be exceeded; enabling the ecosystem section MUST NOT relax prior limits. - Docs-as-built guard extends to the new schema nodes so generated snippets and rendered docs agree on the resolved manifest.
Compiler touchpoints
- Introduces
root_task.schema = "1.0"; schema mismatches abort generation and instruct operators to upgrade docs. - Adds
cargo xtaskstyle CI guard (or Makefile target) invoked byscripts/check-generated.shthat runs the compiler, compares hashes, and fails CI when committed artefacts drift. - Exports doc snippets (e.g., namespace tables) as Markdown fragments consumed by
docs/ARCHITECTURE.mdto guarantee docs stay in lockstep with the manifest.
Milestone 8c — Cache-Safe DMA via AArch64 VSpace Calls
Why now (context): DMA regions shared with host-side GPUs, telemetry rings, and future sidecars cross NineDoor and HAL boundaries, but our cache maintenance is still implicit. Section 10.9.2 of the seL4 manual exposes the AArch64-only seL4_ARM_VSpace_{Clean, CleanInvalidate, Invalidate, Unify}_Data invocations; wrapping them in Rust lets us publish deterministic cache semantics instead of trusting ad-hoc CPU flushes.
Goal Wrap the AArch64-specific VSpace cache operations in the HAL, wire them into manifest-driven DMA contracts, and call them whenever pages are pinned for host DMA so shared buffers remain coherent and auditable.
Deliverables
apps/root-task/src/hal/cache.rs(new module) definingCacheMaintenancehelpers aroundseL4_ARM_VSpace_Clean_Data,CleanInvalidate_Data,Invalidate_Data, andUnify_Instructionplus error/trace plumbing so callers can treat range, alignment, and domain failures deterministically.- HAL integration updates (telemetry rings, GPU windows, future sidecar buffers) that execute the helpers immediately before handing memory to host-side actors and right after reclaiming pins, ensuring caches flush/invalidates happen in lockstep with page sharing.
tools/coh-rtcschema additions (cache.dma_clean,cache.dma_invalidate,cache.unify_instructions) plus generated bootstrap tables and docs (docs/ARCHITECTURE.md §11,docs/SECURE9P.md) describing why AArch64 cache ops are necessary for deterministic DMA. The manifest rejects configurations that omitcache.kernel_ops = truewhile requesting DMA cache maintenance, preventing bizarreness.apps/root-task/tests/cache_maintenance.rs(QEMU/host shim) covering success/error paths of the helpers and asserting audit logs for flushed ranges before the shared region becomes available to NineDoor clients.
Status: Complete — cache maintenance helpers and DMA audit traces verified; coh-rtc rejects missing cache.kernel_ops; tests pass.
Commands
cd apps/root-task && cargo test cache_maintenance --features cache-maintenancecargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json --cli-script scripts/cohsh/boot_v0.cohcargo test -p coh-rtc
Checks (DoD)
- Cache helpers succeed for valid, aligned ranges and surface
seL4_RangeError/seL4_InvalidArgumentin logs when misaligned. - Serial logs around NineDoor/DMA transitions mention cache flush/invalidate audit lines, proving the helpers run before sharing buffers.
coh-rtcrefuses to emit bootstrap tables for DMA cache maintenance whencache.kernel_opsis disabled, keeping docs/code aligned with the manual’s capability requirements.
Milestone 8d — In-Session test Command + Preinstalled .coh Regression Scripts
Why now (context): The TCP console is now viable, but operators and CI need a deterministic, single-command proof that cohsh protocol semantics and server-side Secure9P/NineDoor behaviours remain intact. An in-session coh> test that exercises client↔server flows via preinstalled scripts ensures regressions surface immediately, including namespace side effects and negative paths.
Goal
Provide coh> test that runs a bounded suite validating the cohsh control-plane contract end-to-end (client + server), returning deterministic PASS/FAIL plus optional machine-readable JSON suitable for CI.
Following the .coh script format as documented in docs/USERLAND_AND_CLI.md “## coh scripts” section.
Deliverables
- Interactive command surface
coh> testdefaults to a bounded “quick” suite;--mode quick|fullswitches coverage depth.- Flags:
--json(stable output schema),--timeout <s>(hard upper bound to prevent hangs), and optional safety--no-mutate(skips spawn/kill when operators prohibit mutation). Mutation is otherwise permitted for “full” coverage. - Assumes session is already AUTH’d and ATTACH’d but revalidates both up front and fails fast if either is missing.
- Preinstalled
.cohregression scripts on the server filesystem (rootfs-installed by the build script, never fetched at runtime)- Canonical path:
/proc/tests/within the mounted namespace; scripts are installed into the CPIO rootfs during packaging. - Versioned artefacts (names fixed):
selftest_quick.coh— validates session state (AUTH/ATTACH), ping/ack grammar, bounded request/response round-trips.selftest_full.coh— validates Secure9P/NineDoor semantics and performs one disposable Worker-model lifecycle (spawn → observe namespace/telemetry evidence → kill) to prove mutation paths.selftest_negative.coh— validates deterministic ERR paths (forbidden role action,..traversal rejection, bounded walk depth, oversized request vsmsize, and no unintended mutation).
- Canonical path:
- Script execution model
coh> testexecutes the server-hosted.cohscripts (e.g., internally equivalent tocoh> run /proc/tests/selftest_full.cohif the verb exists) so real client↔server control flow and namespace semantics are exercised; no client-embedded shortcuts.
- Output contract
- Human output: checklist-style PASS/FAIL with the first failing step and a concise reason.
- JSON (
--json):{ ok, mode, elapsed_ms, checks:[{name, ok, detail, transcript_excerpt?}], version }(versioned for compatibility).
Status: Complete — coh> test runs against preinstalled /proc/tests scripts, emits PASS/FAIL plus JSON, and rerun guidance is documented for operators.
Test coverage (what “full” must prove)
- AUTH/ATTACH validation with deterministic failure when missing.
- Protocol grammar: deterministic OK/ERR acknowledgements, bounded retries, no silent failures.
- Role enforcement: queen-only actions rejected when attached as a non-queen role (or simulated negative in the script when role switching is unavailable).
- Secure9P correctness: walk/open/read/write/clunk flows, rejection of
.., bounded walk depth,msize/frame bounds, read-only vs append-only semantics. - Disposable Worker-model lifecycle: create a short-lived model record, observe namespace/telemetry evidence, remove the record, and verify cleanup.
Commands
coh> testcoh> test --mode fullcoh> test --mode full --jsoncoh> test --mode full --timeout 10coh> test --mode full --no-mutate- Example referencing the installed scripts:
coh> run /proc/tests/selftest_full.coh(only if the existing verb is available; otherwise thetestcommand drives the same execution path internally).
Checks (DoD)
- From an active interactive session,
coh> test --mode quickcompletes within the default timeout and reports PASS on a healthy system. coh> test --mode fullcompletes within the default timeout and exercises: AUTH/ATTACH validation, at least one read-only read from/proc/*, at least one permitted control write (append-only where applicable), disposable Worker-model spawn → observe → kill, and at least one negative test producing deterministic ERR output.--jsonoutput matches the documented schema and remains stable for CI consumption (includeversion)..cohscripts exist at/proc/tests/, are installed into the rootfs by the build process, and remain the single source of truth for the suite (rerun whenever console, Secure9P, namespace layout, or access policy changes).- Regression command reruns are documented: operators must execute this suite whenever console handling, Secure9P transport, namespace structure, or access policies change.
Milestone 9 — Secure9P Pipelining & Batching
(Clarification) Milestones 9–15 intentionally build on the full 7d acknowledgement grammar. Do NOT attempt to pull 9P batching/pipelining earlier than 7d; doing so breaks test surfaces.
Why now (compiler): Host NineDoor already handles baseline 9P flows, but upcoming use cases demand concurrent telemetry and command streams. Enabling multiple in-flight tags and batched writes requires new core structures and manifest knobs so deployments tune throughput without compromising determinism and Regression Pack guarantees.
Goal Refactor Secure9P into codec/core crates with bounded pipelining and manifest-controlled batching.
Deliverables
- Split
crates/secure9p-codec/secure9p-core/secure9p-transportinto:crates/secure9p-codec— frame encode/decode, batch iterators, fuzz corpus harnesses (stillstdfor now).crates/secure9p-core— session manager, fid table, tag window enforcement, andno_std + alloccompatibility. Existing consumers (apps/nine-door,apps/cohsh) migrate to the new crates.
apps/nine-door/src/host/updated to process batched frames and expose back-pressure metrics; new modulepipeline.rsencapsulates short-write handling and queue depth accounting surfaced via/proc/9p/*later.apps/nine-door/tests/pipelining.rsintegration test spinning four concurrent sessions, verifying out-of-order responses and bounded retries when queues fill.- CLI regression
scripts/cohsh/9p_batch.cohexecuting scripted batched writes and verifying acknowledgement ordering. scripts/cohsh/9p_batch.cohincludes batching/overflow assertions and participates in the regression pack DoD.configs/root_task.tomlgains IR v1.1 fields:secure9p.tags_per_session,secure9p.batch_frames,secure9p.short_write.policy. Validation ensurestags_per_session >= 1and total batched payload stays ≤ negotiatedmsize.- Docs:
docs/SECURE9P.mdupdated to describe the new layering and concurrency knobs;docs/INTERFACES.mddocuments acknowledgement semantics for batched operations. - Explicit queue depth limits and retry back-off parameters documented; negative path covers tag overflow and back-pressure refusal.
Status: Complete — pipelining tests cover synthetic load, batching toggles, and back-pressure; 9p_batch.coh regression (including overflow) passes with the full regression pack.
Commands
cargo test -p secure9p-codeccargo test -p secure9p-corecargo test -p nine-doorcargo test -p coh-rtc(regenerates manifest snippets with new fields)cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/9p_batch.coh
Checks (DoD)
- Synthetic load (10k interleaved operations across four sessions) completes without tag reuse violations or starvation; metrics expose queue depth and retry counts.
- Batched frames round-trip within negotiated
msize; when the manifest disables batching the same tests pass with single-frame semantics. - Short-write retry policies (e.g., exponential back-off) are enforced according to manifest configuration and verified by CLI regression output.
- Abuse case: exceeding configured
tags_per_sessionor queue depth yields deterministicERRand audit lines without panics; regression script asserts failure ordering. - Re-run the Regression Pack to ensure pipelining and batching do not alter existing single-request semantics (tags, errors, or short-write handling) as exercised by earlier CLI scripts.
- Tag scheduling MUST remain deterministic: single-request scripts from milestones ≤7 MUST still produce byte-identical ACK/ERR sequences.
Compiler touchpoints
coh-rtcemits concurrency defaults into generated Rust tables and CLI fixtures; docs snippets pull from the manifest rather than hard-coded prose.- CI regeneration guard ensures manifest-driven tests fail if concurrency knobs drift between docs and code.
Task Breakdown
Title/ID: m09-codec-core-split
Goal: Extract codec/core crates with bounded tag windows and batch iterators.
Inputs: crates/secure9p-codec, crates/secure9p-core, crates/secure9p-transport, configs/root_task.toml (new IR fields), docs/SECURE9P.md excerpts.
Changes:
- crates/secure9p-codec/lib.rs — move frame encode/decode + batch iterators; add fuzz corpus harness.
- crates/secure9p-core/lib.rs — session manager with tag window enforcement and queue depth accounting.
- apps/nine-door/src/host/pipeline.rs — enforce queue limits and short-write retry back-off.
Commands:
- cargo test -p secure9p-codec
- cargo test -p secure9p-core
Checks:
- Tag overflow attempt (tags_per_session + 1) returns deterministic ERR and audit line.
Deliverables:
- Updated crate split, manifest IR additions, and queue depth limits documented in docs/SECURE9P.md.
Title/ID: m09-batched-io-regression
Goal: Prove batched write ordering and back-pressure across CLI + Regression Pack.
Inputs: scripts/cohsh/9p_batch.coh, apps/nine-door/tests/pipelining.rs.
Changes:
- apps/nine-door/tests/pipelining.rs — four-session interleave with induced short writes.
- scripts/cohsh/9p_batch.coh — add overflow case asserting ERR on batch > msize.
Commands:
- cargo test -p nine-door --test pipelining
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/9p_batch.coh
Checks:
- Out-of-order responses preserved; batch larger than msize is rejected with logged ERR.
Deliverables:
- Regression outputs archived; docs/INTERFACES.md snippet refreshed from manifest.
Milestone 10 — Telemetry Rings & Cursor Resumption
Why now (compiler): Persistent telemetry is currently mock-only. Operators need bounded append-only logs with resumable cursors, generated from the manifest so memory ceilings and schemas stay auditable.
Goal Implement ring-backed telemetry providers with manifest-governed sizes and CBOR frame schemas.
Deliverables
apps/nine-door/src/host/telemetry/(new module) housing ring buffer implementation (ring.rs) and cursor state machine (cursor.rs), integrated intonamespace.rsandcontrol.rsso workers emit telemetry via append-only files.crates/secure9p-coregains append-only helpers enforcing offset semantics and short-write signalling consumed by the ring provider.- CBOR Frame v1 schema defined in
tools/coh-rtc/src/codegen/cbor.rs, exported as Markdown todocs/INTERFACES.mdand validated by serde-derived tests. - CLI regression
scripts/cohsh/telemetry_ring.cohexercising wraparound, cursor resume, and offline replay viacohsh --features tcp. - Manifest IR v1.2 fields:
telemetry.ring_bytes_per_worker,telemetry.frame_schema,telemetry.cursor.retain_on_boot. Validation ensures aggregate ring usage fits within the event-pump budget declared indocs/ARCHITECTURE.md. apps/root-task/src/generated/bootstrap.rsextended to publish ring quotas and file descriptors consumed by the event pump.
Status: Complete — ring-backed telemetry and cursor retention are validated by tests and the regression pack, with latency metrics recorded in docs/SECURITY.md.
Commands
cargo test -p nine-doorcargo test -p secure9p-corecargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsoncargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/telemetry_ring.coh
Checks (DoD)
- Rings wrap without data loss; on reboot the cursor manifest regenerates identical ring state and CLI replay resumes exactly where it left off.
- Latency metrics (P50/P95) captured during tests and recorded in
docs/SECURITY.md, sourced from automated output instead of manual measurements. - Attempts to exceed manifest-declared ring quotas are rejected and logged; CI asserts the rejection path.
- Abuse case: late reader requesting stale cursor receives deterministic ERR and bounded rewind log; overflow write attempts drop frames with explicit audit.
- Re-run the Regression Pack to confirm that adding ring-backed telemetry does not change console grammar or existing
/worker/<id>/telemetrysemantics outside the new CBOR frames. - Introduction of CBOR telemetry MUST NOT alter legacy plain-text worker telemetry unless explicitly gated by manifest field
telemetry.frame_schema.
Compiler touchpoints
- Codegen emits ring metadata for
/proc/bootso operators can inspect per-worker quotas; docs pull from the generated JSON to avoid drift. - Regeneration guard verifies that CBOR schema excerpts in docs match compiler output.
Task Breakdown
Title/ID: m10-ring-impl
Goal: Implement bounded append-only rings with cursor state machine.
Inputs: apps/nine-door/src/host/telemetry/, configs/root_task.toml telemetry fields.
Changes:
- apps/nine-door/src/host/telemetry/{ring.rs,cursor.rs} — ring write/read, cursor resume, wraparound handling.
- crates/secure9p-core/lib.rs — append-only helpers for offsets and short-write signalling.
Commands:
- cargo test -p nine-door --test telemetry_ring
- cargo test -p secure9p-core
Checks:
- Write past ring_bytes_per_worker rejects with ERR and audit entry; cursor resume returns deterministic frame ordering.
Deliverables:
- Ring implementation and manifest-aligned quotas documented in docs/INTERFACES.md.
Title/ID: m10-cbor-schema-regen
Goal: Define CBOR frame schema and regenerate bootstrap/fixtures.
Inputs: tools/coh-rtc/src/codegen/cbor.rs, apps/root-task/src/generated/bootstrap.rs.
Changes:
- tools/coh-rtc/src/codegen/cbor.rs — schema + Markdown export.
- apps/root-task/src/generated/bootstrap.rs — emit ring quotas and cursor retention flags.
Commands:
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/telemetry_ring.coh
Checks:
- CLI script proves wraparound and stale cursor rejection; regenerated schema matches docs snippet.
Deliverables:
- Updated manifest IR, CBOR schema excerpts in docs/INTERFACES.md.
Milestone 11 — Host Sidecar Bridge & /host Namespace (Ecosystem Coexistence)
Why now (compiler): Cohesix needs to govern existing fleets (systemd units, Kubernetes nodes, GPUs) without moving those systems into the VM. Mirroring host controls into /host via Secure9P keeps determinism and the tiny TCB while exposing file-driven levers.
Flagship narrative: Cohesix acts as a governance layer over existing ecosystems: external orchestrators, device managers, and schedulers are surfaced as files and policies so queens and workers can coordinate without new protocols or in-VM servers.
Goal
Provide a host-only sidecar bridge that projects external ecosystem controls into a manifest-scoped /host namespace with strict policy/audit boundaries and no new in-VM transports.
Deliverables
- New host tool crate
apps/host-sidecar-bridge/(name can adjust) that connects to NineDoor from the host using existing transports, publishes a provider-driven synthetic tree under/host, and supports--mockmode for CI. - Namespace layout (v1, minimal, file-only and append-only for controls):
/host/systemd/<unit>/{status,restart}(mocked)/host/k8s/node/<name>/{cordon,drain}(mocked)/host/nvidia/gpu/<id>/{status,power_cap,thermal}(mocked; honours GPU-outside-VM stance)
- Access policy:
- Queen role can write control nodes; workers are read-only or denied based on manifest policy.
- Control writes are append-only command files (no random writes); audit lines are appended for every write using existing logging/telemetry mechanisms (no new logging protocol).
- Host-only transport enforcement: no new in-VM TCP listeners; the sidecar uses the existing authenticated console/NineDoor boundaries from the host side only.
- CLI harness and commands (documented):
cargo test -p host-sidecar-bridgecargo run -p host-sidecar-bridge -- --mock --mount /hostcargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/host_absent.cohcargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/host_sidecar_mock.coh- Manifest/IR alignment:
/hosttree appears only whenecosystem.host.enable = truewith providers declared underecosystem.host.providers[]and mount point defaulting to/host. - Docs include policy and TCB notes emphasising that the bridge mirrors host controls without expanding the in-VM attack surface.
Status: Complete — host-sidecar bridge and manifest-gated /host namespace are verified via host tool tests, host_sidecar_policy, and regression scripts covering /host role enforcement.
Checks (DoD)
/host/*tree mounts only when enabled by the manifest; omitted otherwise.- Writes to control nodes are rejected for non-queen roles and result in append-only audit lines; mock mode exercises this path in CI.
- No new in-VM TCP services are introduced; all transports remain host-side per Secure9P.
- Abuse case: denied write to
/host/systemd/*/restartreturns deterministic ERR and logged audit; disablement removes namespace entirely and unit/integration tests assert absence.
Compiler touchpoints
coh-rtcvalidation ensures enablingecosystem.hostrespects existing Secure9P red lines (msize, walk depth, role isolation) and memory budgets.- Codegen emits doc/CLI snippets advertising
/hostonly when enabled; docs-as-built guard pulls from the resolved manifest.
Task Breakdown
Title/ID: m11-sidecar-skeleton
Goal: Create host sidecar bridge and manifest-gated /host namespace.
Inputs: apps/host-sidecar-bridge/, configs/root_task.toml (ecosystem.host.*).
Changes:
- apps/host-sidecar-bridge/src/main.rs — provider mounts, append-only control writers, mock mode.
- apps/nine-door/src/host/namespace.rs — conditional mount for /host based on manifest.
Commands:
- cargo test -p host-sidecar-bridge
- cargo run -p host-sidecar-bridge -- --mock --mount /host
Checks:
- Disabled manifest omits /host entirely; enabling exposes mocked controls without TCP listeners inside VM.
Deliverables:
- Host bridge crate and manifest toggles documented in docs/ARCHITECTURE.md.
Title/ID: m11-policy-roles
Goal: Enforce role-based append-only controls with audit.
Inputs: docs/INTERFACES.md control grammar, scripts/cohsh/host_sidecar_mock.coh.
Changes:
- apps/nine-door/src/host/control.rs — queen-only write enforcement and append-only audit logging.
- scripts/cohsh/host_sidecar_mock.coh — denied-write then approved-write flow.
Commands:
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/host_sidecar_mock.coh
- cargo test -p nine-door --test host_sidecar_policy
Checks:
- Non-queen write returns ERR EPERM; audit line includes ticket and path; approved write succeeds deterministically.
Deliverables:
- CLI regression outputs captured; docs/SECURITY.md mentions audit expectations.
Milestone 12 — PolicyFS & Approval Gates
Why now (compiler): Host mirroring introduces higher-risk controls. Converting approvals into manifest-driven files keeps operations human-auditable without new protocols.
Flagship narrative: Governance is file-native: risky actions become append-only requests, policy gates decide via files, and the hive stays deterministic across transports.
Goal
Add a PolicyFS surface that captures human-legible approvals for sensitive operations before they reach /queen/ctl or /host controls.
Deliverables
- Namespace nodes (provider may live in NineDoor or host; keep consistent with existing architecture):
/policy/ctl(append-only JSONL commands for policy changes)/policy/rules(read-only snapshot emitted from manifest)/actions/queue(append-only requests)/actions/<id>/status(read-only)
- Enforcement: selected control writes (e.g.,
/queen/ctl,/host/*/restart) require a policy gate when enabled; denials/approvals append to the audit log using existing telemetry logging. - CLI regression demonstrating a denied action followed by an approved action under policy gating.
scripts/cohsh/policy_gate.cohis part of the regression pack and must remain deterministic. Its live target lane gates a session-local/queen/ctlbind; seeded/hostnodes remain fixture-only.- Manifest flag (e.g.,
ecosystem.policy.enable) toggles the gate and publishes rules; the current default manifest enables the gate and disabling it reverts to prior control semantics.
Status: Complete — PolicyFS surfaces and gating are manifest-driven, approval consumption is enforced, and the policy gate regression passes deterministically.
Commands
cargo test -p nine-doorcargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsoncargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/policy_gate.coh
Checks (DoD)
- Policy gate enablement is manifest-driven; disabling it reverts to prior control semantics without hidden defaults.
- Deterministic results: identical scripts produce identical ACK/ERR sequences and audit lines for denied vs. approved actions.
- Sensitive control writes are refused when gates are active and no approval exists; acceptance path appends deterministic audit lines.
- Abuse case: replaying an already-consumed approval yields ERR and does not double-apply actions; CLI script asserts refusal.
Compiler touchpoints
coh-rtcemits policy/rule snapshots into generated docs and CLI fixtures; validation enforces append-only semantics and bounded queue sizes consistent with Secure9P limits.- Docs-as-built guard ensures policy nodes and examples match the resolved manifest.
Task Breakdown
Title/ID: m12-policyfs-provider
Goal: Implement PolicyFS nodes and append-only gating for risky controls.
Inputs: apps/nine-door/src/host/{policy.rs,namespace.rs}, configs/root_task.toml (ecosystem.policy.*).
Changes:
- apps/nine-door/src/host/policy.rs — providers for /policy/ctl, /policy/rules, /actions/*.
- apps/nine-door/src/host/control.rs — enforcement hook requiring approvals before queen/host writes.
Commands:
- cargo test -p nine-door --test policyfs
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
Checks:
- Missing approval produces ERR EPERM with audit; enabling flag publishes /policy tree; disabling removes it.
Deliverables:
- PolicyFS provider code and manifest schema updates referenced in docs/INTERFACES.md.
Title/ID: m12-approval-regression
Goal: Demonstrate denied→approved flow and replay refusal.
Inputs: scripts/cohsh/policy_gate.coh.
Changes:
- scripts/cohsh/policy_gate.coh — stepwise denied action, approval append, approved retry, replay attempt.
- docs/SECURITY.md appendix note on approval replay limits (snippet refreshed from manifest).
Commands:
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/policy_gate.coh
Checks:
- Replay attempt after approval consumption returns ERR and no duplicate action; ACK/ERR sequence deterministic.
Deliverables:
- CLI transcript stored; manifest hash recorded for regression comparison.
Milestone 13 — AuditFS & ReplayFS
Why now (compiler): With host mirroring and policy gates, operators need deterministic replay for investigations without expanding the TCB. Bounded audit/replay surfaces make Cohesix operations repeatable and inspectable.
Flagship narrative: Cohesix treats control as data: every action and decision is recorded as append-only files that can be replayed deterministically to prove governance over external ecosystems.
Goal Provide append-only audit logs and a bounded replay surface that re-applies Cohesix-issued control actions deterministically.
Deliverables
/audit/subtree:/audit/journal(append-only CBOR or JSONL aligned with existing telemetry choices)/audit/decisions(policy approvals/denials)/audit/export(read-only snapshot trigger)
/replay/subtree:/replay/ctl(append-only commands like “start replay from cursor X”)/replay/status(read-only)
- Replay semantics:
- Only replays Cohesix-issued control-plane actions (no arbitrary host scans) and respects bounded log windows.
- Deterministic execution: same inputs → same ACK/ERR + audit lines regardless of transport (serial/TCP).
- CLI regression exercising record then replay of a scripted sequence with byte-identical acknowledgements.
scripts/cohsh/replay_journal.cohis part of the regression pack. Its live target actions are approved session-local/queen/ctlbinds, so replay coverage does not invent host-provider state.- Audit logging integrates with telemetry rings without adding new protocols; storage remains bounded per manifest budget.
Status: Complete — AuditFS/ReplayFS surfaces, manifest gating, tests, and regression scripts are in place and pass deterministically.
Commands
cargo test -p nine-doorcargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsoncargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/replay_journal.coh
Checks (DoD)
- Scripted actions can be replayed to yield byte-identical ACK/ERR sequences for Cohesix control operations.
- Audit entries are emitted for all transports; replay refuses to exceed bounded windows or to replay non-Cohesix host state.
- Append-only semantics enforced for journal/control files; attempts at random-write are rejected and audited.
- Abuse case: request to replay beyond bounded window or disabled replay flag returns ERR and leaves system unchanged; CLI script asserts refusal.
Compiler touchpoints
- Manifest fields (e.g.,
ecosystem.audit.enable) gate audit/replay surfaces; validation enforces bounded storage and adherence to Secure9P limits. - Generated docs reference audit/replay schemas derived from the resolved manifest; CI guard ensures snippets stay in sync.
Task Breakdown
Title/ID: m13-auditfs-journal
Goal: Add append-only audit journal and decision logs with bounded storage.
Inputs: apps/nine-door/src/host/audit.rs, configs/root_task.toml (ecosystem.audit.*).
Changes:
- apps/nine-door/src/host/audit.rs — /audit/journal and /audit/decisions providers, append-only enforcement.
- apps/nine-door/src/host/telemetry/mod.rs — hook to emit audit lines into telemetry ring.
Commands:
- cargo test -p nine-door --test auditfs
Checks:
- Random-write attempts to journal rejected with ERR; storage cap enforced with deterministic truncation policy.
Deliverables:
- Audit schema documented in docs/INTERFACES.md via compiler snippet.
Title/ID: m13-replayfs-determinism
Goal: Implement bounded replay control with deterministic ACK/ERR.
Inputs: apps/nine-door/src/host/replay.rs, scripts/cohsh/replay_journal.coh.
Changes:
- apps/nine-door/src/host/replay.rs — /replay/ctl, /replay/status, cursor handling within bounded window.
- scripts/cohsh/replay_journal.coh — record then replay sequence plus over-window abuse case.
Commands:
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/replay_journal.coh
- cargo test -p nine-door --test replayfs
Checks:
- Replay beyond window or when disabled returns ERR; successful replay reproduces byte-identical ACK/ERR.
Deliverables:
- Replay semantics and bounds captured in docs/SECURITY.md and docs/INTERFACES.md.
Milestone 14 — Sharded Namespaces & Provider Split
Why now (compiler): Scaling beyond hundreds of workers will otherwise bottleneck on single-directory namespaces. Deterministic sharding keeps walk depth bounded and aligns provider routing with manifest entries.
Goal Introduce manifest-driven namespace sharding with optional legacy aliases.
Deliverables
- Namespace layout
/shard/<00..ff>/worker/<id>/…generated from manifest fields.apps/nine-door/src/host/namespace.rsgrows aShardLayouthelper that maps worker IDs to providers using manifest-supplied shard count and alias flags. apps/nine-door/tests/shard_scale.rsspins 1k worker directories, measuring attach latency and ensuring aliasing (when enabled) doesn’t exceed walk depth (≤ 8 components).crates/secure9p-coreexposes a sharded fid table ensuring per-shard locking and eliminating global mutex contention.- Manifest IR v1.2 additions:
sharding.enabled,sharding.shard_bits,sharding.legacy_worker_alias. Validation enforcesshard_bits ≤ 8and forbids aliases when depth would exceed limits. - Docs updates in
docs/ROLES_AND_SCHEDULING.mddescribing shard hashing (sha256(worker_id)[0..=shard_bits)), alias behaviour, and operational guidance. scripts/cohsh/shard_1k.cohadded to the regression pack DoD.
Status: Complete — sharded layouts, fid tables, manifest validation, CLI/regression coverage, and docs are aligned; regression pack is green.
Commands
cargo test -p nine-doorcargo test -p secure9p-corecargo test -p tests --test shard_1kcargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
Checks (DoD)
- 1k worker sessions attach concurrently without starvation; metrics exported via
/proc/9p/sessionsdemonstrate shard distribution. - Enabling legacy aliases preserves
/worker/<id>paths for backwards compatibility; disabling them causes the compiler to reject manifests that still reference legacy paths. - Re-run the Regression Pack and compare paths: legacy
/worker/<id>scripts must either continue to pass when aliases are enabled or fail deterministically when aliasing is disabled, with matching docs and manifest examples. - Walk-depth MUST remain ≤8 at all times; CI must emit a hard error if shard/alias combinations ever generate deeper paths.
- Abuse case: deliberate alias + shard over-depth request fails manifest validation and produces deterministic compiler error recorded in docs.
Compiler touchpoints
- Generated bootstrap code publishes shard tables for the event pump and NineDoor bridge; docs consume the same tables.
- Manifest regeneration updates CLI fixtures so scripted tests reference shard-aware paths automatically.
Task Breakdown
Title/ID: m14-shard-mapping
Goal: Implement shard layout helper and sharded fid table.
Inputs: apps/nine-door/src/host/namespace.rs, crates/secure9p-core fid table.
Changes:
- apps/nine-door/src/host/namespace.rs — ShardLayout mapping with alias toggle.
- crates/secure9p-core/lib.rs — per-shard fid tables and lock partitioning.
Commands:
- cargo test -p nine-door --test shard_scale
- cargo test -p secure9p-core
Checks:
- Over-depth shard+alias combination rejected by manifest validation; 1k worker attach latency within documented bounds.
Deliverables:
- Shard tables emitted to generated bootstrap and referenced in docs/ROLES_AND_SCHEDULING.md.
Title/ID: m14-shard-regression
Goal: Validate legacy alias compatibility and sharded CLI flows.
Inputs: scripts/cohsh/shard_1k.coh (new), tests/integration shard_1k harness.
Changes:
- scripts/cohsh/shard_1k.coh — attaches to shard and legacy alias paths; includes disabled-alias negative case.
- docs/INTERFACES.md snippet showing shard path grammar generated from manifest.
Commands:
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/shard_1k.coh
Checks:
- Legacy path fails deterministically when alias disabled; succeeds when enabled with identical ACK ordering.
Deliverables:
- Regression transcript captured; manifest hash recorded for docs.
Milestone 15 — Client Concurrency & Session Pooling
Why now (compiler): Server-side pipelining is useless unless the CLI and automation harness can take advantage of it safely. Manifest-driven client policy keeps retries and pooling deterministic across deployments.
Goal
Add pooled sessions and retry policies to cohsh, governed by compiler-exported policy files.
Deliverables
apps/cohsh/src/lib.rsextendsShellwith a session pool (default manifest value: two control, twenty-four telemetry) and batched Twrite helper.apps/cohsh/src/transport/tcp.rsgains retry scheduling based on manifest policy.apps/cohsh/tests/pooling.rsverifies pooled throughput and idempotent retry behaviour.- Manifest IR v1.3:
client_policies.cohsh.pool,client_policies.retry,client_policies.heartbeat. Compiler emitsconfigs/generated/cohsh_policy.tomlconsumed at runtime (CLI loads it on start, failing if missing/out-of-sync). - CLI regression
scripts/cohsh/session_pool.cohdemonstrating increased throughput under load and safe recovery from injected failures. - Docs (
docs/USERLAND_AND_CLI.md) describe new CLI flags/env overrides, referencing manifest-derived defaults.
Status: Complete — session pooling, retry policies, policy hashing, CLI regression coverage, and docs updates are in place; regression pack is green.
Commands
cargo test -p cohshcargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/session_pool.cohcargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
Checks (DoD)
- Throughput benchmark (documented in test output) demonstrates improvement relative to single-session baseline without exceeding
msizeor server tag limits. - Retry logic proves idempotent: injected short-write failures eventually succeed without duplicating telemetry or exhausting tickets.
- CLI refuses to start when the manifest policy hash mismatches the compiled defaults.
- Re-run the Regression Pack and assert that pooled sessions preserve ACK/ERR ordering and idempotent retries for all existing CLI scripts.
- Pooled sessions MUST NOT reorder ACKs across operations that were previously strictly ordered (attach/log/tail/quit baseline).
- Abuse case: pool exhaustion and forced retry after connection drop yields bounded retries and no duplicate commands; script asserts final counts.
Compiler touchpoints
coh-rtcemits policy TOML plus hash recorded in docs/tests; regeneration guard compares CLI-consumed hash with manifest fingerprint.- Docs embed CLI defaults via compiler-generated snippets to avoid drift.
Task Breakdown
Title/ID: m15-session-pool
Goal: Add pooled sessions and retry policies to cohsh.
Inputs: apps/cohsh/src/lib.rs, configs/root_task.toml client_policies.*.
Changes:
- apps/cohsh/src/lib.rs — session pool, batched Twrite helper, policy hash enforcement.
- apps/cohsh/src/transport/tcp.rs — retry scheduling and reconnect handling.
Commands:
- cargo test -p cohsh --tests
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/session_pool.coh
Checks:
- Connection drop triggers retries without duplicate telemetry; pool exhaustion returns deterministic ERR and audit.
Deliverables:
- Updated client policy TOML emitted by compiler and referenced in docs/USERLAND_AND_CLI.md.
Title/ID: m15-throughput-benchmark
Goal: Measure throughput improvements and ensure ordering stability.
Inputs: apps/cohsh/tests/pooling.rs, scripts/cohsh/session_pool.coh outputs.
Changes:
- apps/cohsh/tests/pooling.rs — throughput benchmark comparing single vs pooled sessions with injected short writes.
- docs/SECURITY.md — note on ordering/idempotency with snippet from manifest.
Commands:
- cargo test -p cohsh --test pooling
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/session_pool.coh
Checks:
- ACK/ERR ordering unchanged from baseline; retries logged once per failure; benchmark shows expected throughput gain.
Deliverables:
- Benchmark data archived; manifest hash updated in docs.
Milestone 16 — Observability via Files (No New Protocols)
Why now (compiler): Operators need structured observability without adding new protocols inside the VM. Manifest-defined /proc endpoints ensure metrics stay aligned with runtime behaviour.
Goal
Expose audit-friendly observability nodes under /proc generated from the manifest.
Deliverables
apps/nine-door/src/host/observe.rs(new module) providing read-only providers for/proc/9p/{sessions,outstanding,short_writes}and/proc/ingest/{p50_ms,p95_ms,backpressure,dropped,queued}plus append-only/proc/ingest/watchsnapshots.- Event pump updates (
apps/root-task/src/event/mod.rs) to update ingest metrics without heap allocation; telemetry forwarded through generated providers. - Unit tests covering metric counters and ensuring no allocations on hot paths; CLI regression
scripts/cohsh/observe_watch.cohtails/proc/ingest/watchverifying stable grammar. - Manifest IR v1.3 fields:
observability.proc_9pandobservability.proc_ingestenabling individual nodes and documenting retention policies. Validation enforces bounded buffer sizes. - Docs:
docs/SECURITY.mdgains monitoring appendix sourced from manifest snippets;docs/INTERFACES.mddocuments output grammar.
Status: Complete — /proc observability providers, ingest metrics hooks, CLI regressions, doc snippets, and regression pack coverage are aligned and green.
Commands
cargo test -p nine-doorcargo test -p root-taskcargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsoncargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/observe_watch.coh
Checks (DoD)
- Stress harness records accurate counters; metrics exported via
/procmatch expected values within tolerance. - CLI tail output remains parseable and line-oriented; regression test asserts exact output grammar.
- Compiler rejects manifests that attempt to enable observability nodes without allocating sufficient buffers.
- Re-run the Regression Pack to ensure
/procadditions are strictly additive and do not change existing node sizes, EOF behaviour, or latency characteristics beyond documented tolerances. /procnodes MUST NOT change default units, JSON keys, or column spacing without a manifest schema revision and updated golden outputs.- Abuse case: rapid poll of
/proc/ingest/watchunder back-pressure does not allocate or drop counters; deterministic throttling logged.
Compiler touchpoints
- Generated code provides
/procdescriptors; docs embed them via compiler output. - As-built guard compares manifest-declared observability nodes with committed docs and fails CI if mismatched.
Task Breakdown
Title/ID: m16-proc-providers
Goal: Implement observability providers without new protocols.
Inputs: apps/nine-door/src/host/observe.rs, apps/root-task/src/event/mod.rs.
Changes:
- apps/nine-door/src/host/observe.rs — providers for /proc/9p/* and /proc/ingest/* with bounded buffers.
- apps/root-task/src/event/mod.rs — metrics update hooks without heap allocation.
Commands:
- cargo test -p nine-door --test observe
- cargo test -p root-task
Checks:
- Under stress, metrics remain accurate; abuse case polling watch node throttles without allocations.
Deliverables:
- Observability nodes documented in docs/INTERFACES.md and docs/SECURITY.md via compiler snippets.
Title/ID: m16-cli-regressions
Goal: Validate CLI grammar and negative cases for observability nodes.
Inputs: scripts/cohsh/observe_watch.coh.
Changes:
- scripts/cohsh/observe_watch.coh — tail watch node, induce back-pressure, request unsupported node to assert ERR.
- docs/SECURITY.md — capture latency/metric tolerances.
Commands:
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/observe_watch.coh
Checks:
- Unsupported node returns deterministic ERR; watch grammar matches golden; back-pressure logs recorded.
Deliverables:
- Regression transcript stored; manifest hash noted in docs.
Milestone 17 — Content-Addressed Updates (CAS) — 9P-first
Why now (compiler): Upcoming edge deployments need resumable, verifiable updates without bloating the VM with new protocols. Manifest-governed CAS ensures integrity rules and storage budgets remain enforceable.
Goal Provide CAS-backed update distribution via NineDoor with compiler-enforced integrity policies.
Deliverables
apps/nine-door/src/host/cas.rsimplementing a CAS provider exposing/updates/<epoch>/{manifest.cbor,chunks/<hash>}with optional delta packs. Provider enforces SHA-256 chunk integrity and optional Ed25519 signatures when manifest enablescas.signing.- Host tooling
apps/cas-tool/(new crate) packaging update bundles, generating manifests, and uploading via Secure9P. - CLI regression
scripts/cohsh/cas_roundtrip.cohverifying download resume, signature enforcement, and delta replay. - Models as CAS (registry semantics via files, no new service): expose
/models/<sha256>/{weights,schema,signature}backed by the same CAS provider; include doc example binding a model into a worker namespace via mount/bind. - CLI regression
scripts/cohsh/model_cas_bind.cohuploads a dummy model bundle, verifies hash, and binds it into a worker namespace. - Manifest CAS fields are
cas.enable,cas.store.chunk_bytes,cas.delta.enable, andcas.signing.verification_key_path. Validation ensures chunk size ≤ negotiatedmsizeand a valid public Ed25519 verification key is present when signatures are required; target code never embeds the private signing key. - Docs:
docs/INTERFACES.mddescribes CAS grammar, delta rules, and operational runbooks sourced from compiler output;docs/SECURITY.mdrecords threat model.
Status: Complete — CAS provider, cas-tool, model bindings, compiler v1.4 CAS fields, doc snippets, and regression coverage are aligned and green.
Commands
cargo test -p nine-doorcargo test -p cas-toolcargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsoncargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/cas_roundtrip.cohcargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/model_cas_bind.coh
Checks (DoD)
- Resume logic validated via regression script; delta application is idempotent and verified by hashing installed payloads before/after.
- Signing path tested with fixture keys; unsigned mode explicitly documented and requires manifest acknowledgement (e.g.,
cas.signing.required = false). - Compiler rejects manifests where CAS storage exceeds event-pump memory budgets or chunk sizes exceed
msize. - Re-run the Regression Pack and verify that enabling CAS does not change baseline NineDoor error codes or 9P limits (e.g.,
msize, walk depth) enforced by earlier milestones. - CAS fetch paths MUST NOT alter 9P latency or error codes for non-CAS workloads; regression pack MUST prove no change in baseline attach/log/tail flows.
- Model binding test proves
/models/<sha256>mounts remain read-only and integrate with worker namespaces without introducing new services; manifest gating (e.g.,ecosystem.models.enable) controls exposure. - Abuse case: hash mismatch or signature verification failure rejects chunk and leaves partial downloads quarantined with deterministic audit.
Compiler touchpoints
- Codegen emits CAS provider tables and host-tool manifest templates; docs ingest the same JSON to prevent drift.
- Regeneration guard checks CAS manifest fingerprints against committed artefacts.
- Manifest validation ties CAS model exposure to
ecosystem.models.enableand ensures model artefact sizes respect existing Secure9Pmsizeand walk-depth limits.
Task Breakdown
Title/ID: m17-cas-provider
Goal: Implement CAS provider and manifest validation for updates/models.
Inputs: apps/nine-door/src/host/cas.rs, configs/root_task.toml cas.* fields.
Changes:
- apps/nine-door/src/host/cas.rs — chunk integrity checks, delta packs, signature enforcement.
- tools/coh-rtc/src/codegen/cas.rs — emit IR v1.4 fields and templates.
Commands:
- cargo test -p nine-door --test cas_provider
- cargo test -p tools/coh-rtc
Checks:
- Hash mismatch causes ERR and quarantine; chunk_size > msize rejected at compile time.
Deliverables:
- CAS grammar documented in docs/INTERFACES.md with compiler snippets.
Title/ID: m17-cas-regressions
Goal: Validate end-to-end CAS roundtrip and model binding.
Inputs: scripts/cohsh/cas_roundtrip.coh, scripts/cohsh/model_cas_bind.coh, apps/cas-tool/.
Changes:
- apps/cas-tool/src/main.rs — bundle creation, manifest generation, upload helper.
- scripts/cohsh/cas_roundtrip.coh — resume + signature paths including negative signature case.
- scripts/cohsh/model_cas_bind.coh — bind model into worker namespace and assert read-only.
Commands:
- cargo test -p cas-tool
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/cas_roundtrip.coh
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/model_cas_bind.coh
Checks:
- Replay after interruption resumes without duplication; signature failure returns deterministic ERR and audit.
Deliverables:
- Regression outputs stored; docs/SECURITY.md updated with CAS threat model references.
Milestone 18 — Field Bus & Low-Bandwidth Sidecars (Host/Worker Pattern)
Status: Reopened — the bounded m18-remove-hallucinated-lora-radio defect
correction, discovered during the Milestone 26c documentation audit, closed on
2026-07-15, but the later production-surface audit found that the claimed live
MODBUS/DNP3 delivery path is still only an in-memory model. BusAdapter returns
Delivered while online without performing protocol I/O, and the MODBUS and
DNP3 types are aliases over that queue. The compiler-declared namespace and
bounded-spool model remain useful, but they are not live protocol integration
evidence. This reopened scope is limited to completing the original host-side
MODBUS/DNP3 promise; worker-bus remains the one intentionally model/session-
only Worker role.
Historical references that attached a radio subsystem to lowercase lora
identifiers are invalid: Cohesix does not implement or target that subsystem.
LoRA, worker-lora, and lowercase lora identifiers refer only to the AI
adapter/model lifecycle.
Title/ID: m18-remove-hallucinated-lora-radio
Milestone: Milestone 18 — Field Bus & Low-Bandwidth Sidecars / reopened defect discovered by Milestone 26c README-linked documentation remediation
Goal: Remove the fabricated radio subsystem attached to lora identifiers while preserving the declared bounded MODBUS/DNP3 sidecar model for the separately reopened live-delivery task and the root-owned AI LoRA receipt model.
Inputs: tools/coh-rtc/src/{ir.rs,codegen}, configs/root_task*.toml, apps/{sidecar-bus,worker-lora,nine-door,root-task}, scripts/cohsh/sidecar_integration.coh, README.md, docs/{GLOSSARY,INTERFACES,SECURITY,ROLES_AND_SCHEDULING,USE_CASES}.md, generated artifacts, current tests, immutable release snapshots.
Changes:
- tools/coh-rtc, source manifests, and generated artifacts — remove sidecars.lora, the /lora radio namespace, regional-band, transmit, duty-cycle, payload, and radio-tamper schema and outputs; retain AI LoRA worker-role and PEFT schema.
- apps/sidecar-bus, apps/worker-lora, apps/nine-door, and apps/root-task — remove radio-only APIs and namespace handlers; keep WorkerLora as a bounded AI lifecycle-receipt Worker with no training, inference, model loading, or GPU access in the VM.
- scripts/cohsh and tests — remove radio assertions and add regressions that reject the retired manifest surface and preserve AI LoRA receipt behavior.
- README.md and canonical docs — define LoRA once as low-rank adaptation, remove all current radio claims, and cross-reference the Queen export and host PEFT lifecycle contracts.
- releases/ — leave published snapshots immutable; record the false historical radio claims as superseded current-documentation errata and exclude them from current as-built truth.
Commands:
- cargo fmt --all -- --check
- cargo test -p coh-rtc
- cargo test -p worker-lora
- cargo test -p sidecar-bus --features modbus,dnp3
- cargo test -p nine-door
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib ninedoor::tests
- cargo test -p cohsh --test script_catalog
- cargo check -p worker-lora --target aarch64-unknown-none
- cargo clippy --workspace --all-targets -- -D warnings
- cargo check --workspace
- cargo test --workspace -- --test-threads=1
- SEL4_BUILD_DIR=seL4/SMP_build cargo check -p root-task --target aarch64-unknown-none --no-default-features --features release-qemu
- SEL4_BUILD_DIR=seL4/build_UBOOT cargo check -p root-task --target aarch64-unknown-none --no-default-features --features release-pi4
- scripts/cohesix-build-run.sh --no-run --cargo-target aarch64-unknown-none
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml --sel4-kernel-source-dir "$HOME/seL4_16"
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
- scripts/ci/test_plan_run.sh --list
- cargo audit
- cargo deny check advisories
Checks:
- Current source, manifests, generated artifacts, tests, scripts, and canonical docs contain no radio-specific region, transmission, duty-cycle, or radio-tamper behavior or claim under lora identifiers.
- sidecars.lora is rejected as an unknown manifest field; the MODBUS/DNP3 model still passes its bounded-spool and authority tests without those tests being labelled live protocol evidence.
- The root-owned WorkerLora receipt model remains available without claiming an executable target role, and /queen/export/lora_jobs plus host PEFT policy remain unchanged.
- Generated-artifact drift, focused tests, workspace checks, local links, Markdown structure, and GitHub Mermaid validation pass.
Deliverables: Corrected compiler/runtime/docs suite, regenerated default-profile artifacts, regression evidence, and a release erratum without mutating historical release bundles.
Closure evidence (2026-07-15): The task commands pass. Compiler schema v1.6
rejects sidecars.lora; the canonical resolved-manifest SHA-256 is
376f09a49cdb37c07ae8ef007d4d4c715df4b4f949d4d6c1546002108d495599.
The QEMU package and stage-only Pi build regenerated their rootservers and
elfloader images; the retired radio paths and identifiers are absent from those
artifacts. Current source and canonical documentation scans contain only the AI
LoRA meaning, intentional negative tests, and this correction record.
Historical release snapshots remain unchanged and are explicitly superseded by
historical drift ledger entry M26C-DOC-019.
Separate repository gate at that checkpoint: On 2026-07-15, the regenerated
seL4/build_UBOOT/elfloader/archive.archive.o.cpio was 5,001,728 bytes against
the mandatory 4 MiB limit; the preceding checked-in artifact was 5,005,824
bytes. The correction therefore reduced the archive by 4 KiB and did not
introduce the breach. Later Milestone 26d repository-gate work restored the
invariant; the current tracked seL4 16 archive is 3,237,888 bytes. The historical
figures remain evidence for that checkpoint, not a current blocker or capacity
available for in-place rootserver replacement.
Why now (context): Remaining edge use cases depend on deterministic
adapters for industrial buses. Implementing them as sidecars preserves the
lean no_std core while meeting operational demands.
Goal Deliver host-side adapters that bridge MODBUS and DNP3 into NineDoor namespaces, driven by compiler-declared mounts and capability policies.
Deliverables
- Host-side sidecar framework (
apps/sidecar-bus) offering async runtimes on macOS/Linux with feature gates to keep VM artefactsno_std. Sidecars communicate via Secure9P transports or serial overlays without embedding TCP servers in the VM. - A recognized
worker-bustemplate and generated/bus/*control/telemetry contract. Current selected profiles still mark the target Worker role as not implemented; the host-side provider remains the as-built integration path. - Compiler schema v1.6 fields
sidecars.modbusandsidecars.dnp3describing mounts, baud/link settings, and capability scopes; validation keeps resources within the event-pump budget. - Documentation updates (
docs/ARCHITECTURE.md §12,docs/INTERFACES.md) illustrating the sidecar pattern, security boundaries, and testing strategy. scripts/cohsh/sidecar_integration.cohintegrated into the regression pack DoD.
Historical completion boundary: The MODBUS/DNP3 host-side framework,
compiler-declared /bus contract, CLI regression coverage, and documentation
remain accepted only as a contract/model baseline. They do not prove serial or
TCP protocol delivery, remote acknowledgement, restart-safe replay, or live
interoperability. Milestone 17 boundary remains
3e6faa33410af58ed8d1942ce58ab701a276b882. The invalid radio-specific lora
surface described above has been removed; that radio-only defect is closed,
while the live MODBUS/DNP3 delivery defect remains reopened as scoped above.
Title/ID: m18-live-modbus-dnp3-sidecars
Milestone: Milestone 18 — Field Bus & Low-Bandwidth Sidecars / reopened live-delivery defect discovered by the Milestone 28b1 production-surface audit
Goal: Replace the in-memory online-delivery model with real bounded host-side MODBUS RTU/TCP and DNP3 client adapters while keeping WorkerBus model/session-only.
Inputs: apps/sidecar-bus/**, apps/host-sidecar-bridge/**, tools/coh-rtc/src/**, configs/root_task*.toml, scripts/cohsh/sidecar_integration.coh, docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/SECURITY.md, docs/TEST_PLAN.md, and the 28b1 provider/integration registry contract.
Changes:
- tools/coh-rtc/src/** + configs/root_task*.toml — generate exact MODBUS unit/register/coil maps and DNP3 outstation/object/variation maps, serial/TCP endpoint bounds, polling/deadline/reconnect policy, read actions, separately approved write/control allowlists, capability scopes, spool durability, and evidence requirements; reject free-form addresses, functions, objects, or control payloads.
- apps/sidecar-bus/** — add a host executable and real bounded MODBUS RTU/TCP and DNP3 client codecs/transports. `Delivered` is emitted only after the remote protocol acknowledgement; exception/status codes, timeout, disconnect, partial frame, duplicate, and reconnect map to typed Cohesix outcomes. No protocol stack or TCP listener enters the VM.
- apps/sidecar-bus/** — replace drain-before-ack with a crash-safe bounded WAL/spool carrying sequence, target, operation fingerprint, attempt state, acknowledgement, and deadletter status. Restart resumes unacknowledged entries without silently dropping or duplicating a write.
- apps/host-sidecar-bridge/** + NineDoor host projection — publish authenticated, versioned, TTL-bound read snapshots and approved terminal action receipts over the existing Secure9P/host-ticket surfaces; stale or absent links withdraw state instead of returning success.
- interoperability and packaging — add deterministic protocol simulators plus at least one live RTU/TCP and DNP3 interoperability transcript per supported host profile, negative safety/refusal cases, exact package manifests, hardened service definitions, and evidence-pack reconstruction.
- canonical docs and historical errata — describe the contract/model baseline separately from live provider acceptance and correct prior claims without mutating historical release snapshots.
Commands:
- cargo test -p sidecar-bus --features modbus,dnp3
- cargo test -p host-sidecar-bridge
- cargo test -p coh-rtc
- scripts/ci/provider_conformance_run.sh --provider modbus --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m18-modbus
- scripts/ci/provider_conformance_run.sh --provider dnp3 --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m18-dnp3
- scripts/cohsh/run_regression_batch.sh
- scripts/check-generated.sh
Checks: online delivery performs real protocol I/O and requires the matching remote acknowledgement; serial/TCP framing, exception/status mapping, reconnect, duplicate suppression, WAL recovery, bounds, authorization, read-only defaults, separately approved controls, namespace publication, and package manifests pass; absent or stale providers are typed unavailable; no mock, simulator, queue-only result, or WorkerBus model state can satisfy live provider or production use-case evidence.
Deliverables: Real host-only MODBUS/DNP3 integrations, durable acknowledgement-aware delivery, exact live conformance evidence, and an explicitly model-only WorkerBus boundary.
Use-case alignment
- Industrial IoT gateways (Edge §1) gain MODBUS integration without bloating the VM.
- Energy substations (Edge §2) receive DNP3 scheduling and signed config updates.
Commands
cargo test -p worker-buscargo test -p sidecar-bus --features modbus,dnp3cohsh --script scripts/cohsh/sidecar_integration.coh
Checks (DoD)
- Sidecars operate within declared capability scopes; attempts to access undeclared mounts are rejected and logged.
- Offline telemetry spooling validated for MODBUS/DNP3 adapters with manifest-driven limits.
- For this milestone, run the full Regression Pack both under QEMU and (where applicable) on the target hardware profile, and treat any divergence between the two as a bug unless explicitly documented.
- Sidecar mounts MUST NOT introduce new
/busnames that collide with legacy namespaces; compiler must hash-prefix automatically if conflicts appear. - Abuse case: unauthorized write into a sidecar mount returns
ERRand an audit record.
Compiler touchpoints
- IR v1.6 ensures mounts, roles, and quotas for sidecars, generating documentation tables and manifest fragments consumed by host tooling.
- Validation prevents enabling sidecars without corresponding host dependencies or event-pump capacity.
Task Breakdown
Title/ID: m19-sidecar-framework
Goal: Build the host sidecar framework and bounded bus template.
Inputs: apps/sidecar-bus/, apps/worker-bus/, configs/root_task.toml sidecars.modbus and sidecars.dnp3.
Changes:
- apps/sidecar-bus/src/lib.rs — capability-scoped adapters with feature gates for modbus/dnp3.
Commands:
- cargo test -p sidecar-bus --features modbus,dnp3
- cargo test -p worker-bus
Checks:
- Unauthorized mount access returns ERR; bounded spool behavior is verified in tests.
Deliverables:
- Sidecar patterns documented in docs/ARCHITECTURE.md and docs/INTERFACES.md.
Title/ID: m19-cli-regressions
Goal: Validate manifest-gated mounts and offline spooling behaviour.
Inputs: scripts/cohsh/sidecar_integration.coh, Regression Pack.
Changes:
- scripts/cohsh/sidecar_integration.coh — mount enable/disable checks, offline spool replay, unauthorized write attempt.
- docs/SECURITY.md — note on namespace collision avoidance via hash-prefix.
Commands:
- cohsh --script scripts/cohsh/sidecar_integration.coh
Checks:
- Disabled manifest hides mounts; offline spool flushes deterministically; unauthorized write produces ERR and audit.
Deliverables:
- CLI transcript stored; manifest hash updated in docs.
Milestone 19 — cohsh-core Extraction (Shared Grammar & Transport)
Why now (compiler): UI and automation consumers need a shared grammar without duplicating console logic. Extracting a core library keeps ACK/ERR stability while enabling multiple frontends.
Goal
Publish a reusable cohsh-core crate with shared verb grammar and transports that mirror console semantics. cohsh-core is a grammar + transport library only; it adds no new verbs or semantics.
Deliverables
- New crate
crates/cohsh-core/encapsulating verb grammar (attach,tail,spawn,kill,quit), ACK/ERR/END model, login throttling, and ticket checks. Supportsno_std + allocwith optional smoltcp TCP transport feature. - Golden transcript fixtures covering serial, TCP, and in-process transports to prove byte-identical ACK/ERR sequences.
- CLI harness using
cohsh-coreto ensure parity with existingcohshcommands; docs reference the shared grammar.
Status: Complete — cohsh-core grammar/ACK models are shared by console and CLI, transcript parity is enforced across transports, and coh-rtc emits guarded grammar/policy snippets.
Commands
cargo test -p cohsh-corecargo test -p cohsh --testscargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/boot_v0.coh
Checks (DoD)
- Console serial/TCP and
cohsh-coretransport fixtures remain byte-identical; focusedcohshtests bind the CLI projection to the shared grammar. - Heapless build passes; no unbounded allocations and no POSIX dependencies.
- Abuse case: invalid ticket or throttled login returns deterministic ERR without advancing state; fixture captures denial.
- UI/CLI/console equivalence MUST be preserved: ACK/ERR/END sequences must remain byte-stable relative to the 7c baseline.
Compiler touchpoints
coh-rtcemits grammar snippets and ticket policies into docs/USERLAND_AND_CLI.md; regeneration guard ensures hash alignment withcohsh-corefixtures.
Task Breakdown
Title/ID: m19-core-crate
Goal: Extract shared verb grammar and transports into cohsh-core.
Inputs: apps/cohsh/src/lib.rs existing grammar, scripts/cohsh/boot_v0.coh fixtures.
Changes:
- crates/cohsh-core/lib.rs — verb parser, ACK/ERR model, smoltcp TCP transport feature.
- apps/cohsh/src/lib.rs — refactor to consume cohsh-core.
Commands:
- cargo test -p cohsh-core
- cargo test -p cohsh --tests
Checks:
- Invalid ticket returns deterministic ERR; heapless build passes without allocations beyond bounded buffers.
Deliverables:
- Shared crate and regenerated grammar snippets in docs/USERLAND_AND_CLI.md.
Title/ID: m19-transcript-harness
Goal: Ensure transcript parity across console/TCP/core transports.
Inputs: scripts/cohsh/boot_v0.coh, new tests in crates/cohsh-core/tests/transcripts.rs.
Changes:
- crates/cohsh-core/tests/transcripts.rs — compare serial vs TCP vs in-process transcripts.
Commands:
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/boot_v0.coh
- cargo test -p cohsh-core --test transcripts
Checks:
- Transcript diff produces zero-byte delta; abuse case with throttled login emits ERR and matches across transports.
Deliverables:
- Stored golden fixtures owned by the focused transcript test.
Milestone 20a — cohsh as 9P Client Library
Why now (compiler): Automation and UI need a library-level 9P client that reuses grammar without console coupling. A first-class client library keeps ordering/idempotency intact.
Goal
Refactor cohsh into a reusable 9P client library with helpers for control verbs and streaming tails.
Deliverables
CohClientexposingopen/read/write/clunkplustail()streaming helper built atopcohsh-core9P transport.- Convenience helpers for
/queen/ctlJSON (spawn,kill,budget) with manifest-derived defaults. - Script harness replaying sessions via 9P (not console) to validate identical semantics; golden fixtures maintained.
Commands
cargo test -p cohsh --test client_libcargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/session_pool.cohcargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/boot_v0.coh
Checks (DoD)
tail()stream over 9P matches console stream identically; diff harness reports zero variance.spawn/killvia file writes produce identical ACK/ERR semantics; clients may retry explicitly; operations are designed to be idempotent where applicable.- Abuse case: attempt to walk
..or access disabled namespace returns deterministic ERR without affecting state. - UI/CLI/console equivalence MUST be preserved: ACK/ERR/END sequences must remain byte-stable relative to the 7c baseline.
Compiler touchpoints
- Manifest-derived paths and defaults emitted by
coh-rtcinto client templates; docs updated via snippets.
Task Breakdown
Title/ID: m20a-client-api
Goal: Build CohClient library with tail and control helpers.
Inputs: apps/cohsh/src/lib.rs, crates/cohsh-core transport.
Changes:
- apps/cohsh/src/client.rs — CohClient struct with open/read/write/clunk and tail helper.
- apps/cohsh/src/queen.rs — spawn/kill/budget helpers wrapping JSON writes.
Commands:
- cargo test -p cohsh --test client_lib
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/boot_v0.coh
Checks:
- Walking `..` or disabled namespace returns ERR; tail stream matches console transcript.
Deliverables:
- Client API docs in docs/USERLAND_AND_CLI.md via compiler snippet.
Title/ID: m20a-replay-harness
Goal: Replay sessions over 9P and compare to console baselines.
Inputs: scripts/cohsh/session_pool.coh, new regression harness for 9P replay.
Changes:
- scripts/cohsh/session_pool.coh — add 9P-only replay path and abuse case for forbidden walk.
- apps/cohsh/tests/client_lib.rs — compares ACK/ERR across transports without
a one-line repository wrapper.
Commands:
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/session_pool.coh
Checks:
- Replay harness shows zero diff between 9P and console outputs; abuse case logs ERR without side effects.
Deliverables:
- Updated regression pack metadata and manifest hashes.
Status: Complete — CohClient API and queen helpers are in tree, client defaults are compiler-emitted, and the 9P replay harness matches console transcripts with regression coverage.
Milestone 20b — NineDoor UI Providers
Why now (compiler): UI surfaces need read-only summaries without adding protocols. Providers must reuse existing /proc mechanics and stay bounded.
Goal Expose UI-friendly read-only providers under NineDoor with cursor-resume semantics and CBOR/text variants.
Deliverables
- Providers for
/proc/9p/{sessions,outstanding,short_writes},/proc/ingest/{p50_ms,p95_ms,backpressure},/policy/preflight/{req,diff},/updates/<epoch>/{manifest.cbor,status}with deterministic EOF and 32 KiB read bounds. - CBOR and text outputs aligned with manifest schemas; cursor resume for long reads.
- UI fixtures documenting provider outputs for SwarmUI and CLI parity.
Commands
cargo test -p nine-door --test ui_providerscargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/observe_watch.cohcargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/cas_roundtrip.coh
Checks (DoD)
- Each provider ≤ 8192 bytes per 9P read; larger outputs must be cursor-resumed over multiple reads with deterministic EOF; fuzzed frames don’t panic or allocate unboundedly.
- Abuse case: request for disabled provider or oversized read returns deterministic ERR and audit line.
- UI/CLI/console equivalence MUST be preserved: ACK/ERR/END sequences must remain byte-stable relative to the 7c baseline.
Compiler touchpoints
- Manifest toggles for UI providers emitted via
coh-rtcand referenced in docs/INTERFACES.md and docs/ARCHITECTURE.md.
Task Breakdown
Title/ID: m20b-provider-impl
Goal: Implement bounded UI providers with CBOR/text outputs.
Inputs: apps/nine-door/src/host/{observe.rs,policy.rs,updates.rs}, manifest toggles.
Changes:
- apps/nine-door/src/host/observe.rs — add text + CBOR variants with cursor resume.
- apps/nine-door/src/host/policy.rs — /policy/preflight providers with diff output.
Commands:
- cargo test -p nine-door --test ui_providers
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/observe_watch.coh
Checks:
- Disabled provider returns ERR; read beyond 32 KiB rejected; fuzz harness passes without panics.
Deliverables:
- Provider docs and CBOR schemas refreshed in docs/INTERFACES.md.
Title/ID: m20b-updates-status
Goal: Surface update status for UI consumption via NineDoor.
Inputs: apps/nine-door/src/host/cas.rs status hooks, scripts/cohsh/cas_roundtrip.coh.
Changes:
- apps/nine-door/src/host/cas.rs — expose /updates/<epoch>/{manifest.cbor,status} read-only nodes.
- scripts/cohsh/cas_roundtrip.coh — add status fetch and disabled-provider abuse case.
Commands:
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/cas_roundtrip.coh
Checks:
- Status node respects cursor resume; disabled updates return ERR without touching CAS store.
Deliverables:
- UI fixture outputs stored; docs reference status grammar.
Status: Complete — UI providers are manifest-gated with bounded cursor-resume semantics, CBOR/text parity, and audit-deny paths; tests and regression pack are green.
Milestone 20c — SwarmUI Desktop (Tauri, Pure 9P/TCP)
Why now (compiler): Desktop operators need a UI that reflects the namespace and reuses the existing 9P grammar without introducing new transports or control semantics. SwarmUI must prove strict parity with CLI behavior and respect ticket-scoped authority.
Goal
Deliver a SwarmUI desktop (Tauri) that speaks 9P via cohsh-core, renders namespace-derived telemetry and fleet views, and supports deterministic offline inspection via cached CBOR snapshots. SwarmUI adds no new verbs and no in-VM services.
SwarmUI is a thin presentation layer only: all protocol semantics, state machines, parsing, and policy live in Rust (cohsh-core); any WASM or frontend code is rendering-only and must not implement verbs, retries, background polling, caching policy, or independent state.
Deliverables
apps/swarmui/Tauri app with Rust backend linked tocohsh-core; host-only, no HTTP/REST dependencies.- Namespace-driven panels:
- Telemetry Rings (tail
/worker/*/telemetry). - Fleet Map (read
/proc/ingest/*+ worker directories). - Optional Namespace Browser (read-only tree over
/proc,/queen,/worker,/log,/gpu, indicating read/append-only paths).
- Telemetry Rings (tail
- Offline inspection via bounded CBOR cache under
$DATA_DIR/snapshots/(opt-in; read-only when offline). - Ticket/lease auth identical to CLI; per-ticket session views supported; role-scoped interactions enforced client-side.
Commands
cargo test -p cohsh-corecargo test -p swarmuicargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/telemetry_ring.coh
Checks (DoD)
- UI renders telemetry with exact
OK …then stream and terminates withEND; transcript matches CLI byte-for-byte. - Build proves no HTTP/REST dependencies (static link audit or cargo deny).
- Abuse case: expired or unauthorized ticket returns
ERRsurfaced verbatim in UI and logs audit; offline mode uses cached CBOR without network or retries. - UI/CLI/console equivalence MUST be preserved: ACK/ERR/END sequences remain byte-stable relative to the 7c baseline.
- SwarmUI performs no background polling outside an active user view/session; no hidden watchers when idle.
Compiler touchpoints
- UI defaults (paths, cache size, ticket scope) emitted by
coh-rtcfor SwarmUI config;docs/USERLAND_AND_CLI.mdreferences the same sources of truth.
Task Breakdown
Title/ID: m20c-ui-backend
Goal: Wire SwarmUI backend to cohsh-core with 9P-only transport and per-ticket sessions.
Inputs: apps/swarmui/src-tauri/, crates/cohsh-core, scripts/cohsh/telemetry_ring.coh.
Changes:
- apps/swarmui/src-tauri/main.rs — session management (per ticket), ticket auth, telemetry tail via cohsh-core.
- apps/swarmui/Cargo.toml — ensure no HTTP/REST deps; enable bounded offline cache feature.
Commands:
- cargo test -p swarmui
- cargo run -p cohsh –-features tcp – –transport tcp –script scripts/cohsh/telemetry_ring.coh
Checks:
- Unauthorized ticket returns ERR surfaced verbatim in UI; offline mode reads CBOR snapshot only.
Deliverables:
- UI backend notes and cache path documented in docs/USERLAND_AND_CLI.md.
Title/ID: m20c-ui-fixtures
Goal: Capture UI/CLI transcript parity and namespace-derived fleet rendering.
Inputs: UI snapshot fixtures, /proc/ingest providers.
Changes:
- apps/swarmui/tests/transcript.rs — compare UI-captured ACK/ERR/END to CLI golden.
- apps/swarmui/src/cache.rs — snapshot write/read with strict size bounds and expiry handling.
Commands:
- cargo test -p swarmui –test transcript
- cargo test -p cohsh-core
Checks:
- Transcript diff zero; cache bounded to documented size; expired cache rejected gracefully.
Deliverables:
- Updated docs/INTERFACES.md with SwarmUI consumption guidance and non-goals.
Status: Complete — SwarmUI desktop is wired to cohsh-core with ticket-scoped sessions, transcript parity tests, bounded offline cache, and no-HTTP dependency enforcement; regression pack remains green.
Milestone 20d — SwarmUI Live Hive Rendering (PixiJS, GPU-First)
Why now (SwarmUI):
Milestone 20d proves SwarmUI can act as a strict, ticket-scoped presentation layer over the 9P namespace with byte-stable CLI parity. The remaining risk is visual overload or architectural drift (SVG/D3 DOM graphs, UI-invented state, per-event rendering). This extension locks in a single, elegant, GPU-first “Live Hive” renderer that is visually compelling while remaining protocol-faithful, deterministic, and bounded.
Goal
Extend SwarmUI with a PixiJS-backed “Live Hive” view that renders agents, work, and flow as a continuous simulation derived solely from existing telemetry and event streams. The renderer introduces no new verbs, no new transports, and no UI-owned control logic. All authority, parsing, and semantics remain in Rust (cohsh-core).
SwarmUI remains a thin presentation layer: frontend code renders only. All protocol behavior, retries, caching policy, and state machines live in Rust. Any frontend logic must be strictly lossy, bounded, and discardable.
Deliverables
- Live Hive Canvas
- PixiJS (WebGL) scene embedded in SwarmUI.
- Visual primitives:
- Agents (“bees”) — sprites with subtle motion and state-based glow.
- Work/messages (“pollen”) — short-lived particles flowing between agents.
- Load/health — aura intensity or soft heat field derived from telemetry.
- Errors — transient pulse/shockwave effects surfaced from
ERRevents. - Namespaces/groups — faint, collapsible cluster hulls mapped from namespace paths.
- SVG permitted only for labels and selection overlays; never for core rendering.
- Simulation Model (Frontend)
- Lightweight, ephemeral world model decoupled from the render loop:
- agent positions/velocities/state flags
- ephemeral flows/messages
- optional low-resolution heat grid
- Fixed or semi-fixed update step; render capped (30–60fps).
- Explicit level-of-detail rules:
- Zoomed out → clusters + aggregate flow intensity.
- Zoomed in → individual agents + per-message particles.
- Under load → degrade to edge intensity; never drop frames.
- Lightweight, ephemeral world model decoupled from the render loop:
- Event Ingestion Contract
- Consume the same event streams used by telemetry panels (
tailover namespace paths). - Event → simulation diff mapping only; no per-event draw guarantees.
- No UI-specific protocol extensions.
- Consume the same event streams used by telemetry panels (
- Replay & Demo Mode
- Live Hive can be driven entirely from:
- recorded transcripts
- cached CBOR snapshots
- Deterministic playback for demos, regression tests, and offline inspection.
- Live Hive can be driven entirely from:
Non-Goals
- No SVG/D3 graph as the primary renderer.
- No Web-only (WASM-only) SwarmUI target yet.
- No UI-invented orchestration, scheduling, or heuristics.
- No attempt to visualise every raw event individually.
Commands
cargo test -p cohsh-corecargo test -p swarmuicargo run -p swarmui -- --replay $DATA_DIR/snapshots/demo.cbor
Checks (DoD)
- Live Hive renders identically when driven by: 1) a live Cohesix node 2) a recorded transcript
- UI actions emit byte-identical
ACK/ERR/ENDsequences to CLI for equivalent verbs. - Sustained high event rates do not reduce UI responsiveness or violate frame caps.
- No HTTP/REST dependencies introduced; no background polling outside active views.
- Renderer remains discardable: restarting the UI reconstructs state solely from streams/snapshots.
Compiler Touchpoints
- UI defaults (hive LOD thresholds, frame caps, snapshot limits) emitted by
coh-rtc. docs/INTERFACES.mdupdated to describe Live Hive as a rendering view only, not a control surface.
Task Breakdown
Title/ID: m20d-hive-renderer
Goal: Add GPU-first Live Hive renderer without altering protocol semantics.
Inputs: apps/swarmui/, crates/cohsh-core, telemetry streams, CBOR snapshots.
Changes:
- apps/swarmui/frontend/hive/ — PixiJS scene, simulation model, LOD rules.
- apps/swarmui/frontend/events.js — event → simulation diff mapping.
- apps/swarmui/src-tauri/ — replay mode wiring (no new verbs).
Commands:
- cargo test -p swarmui
- cargo run -p swarmui – –replay demo.cbor
Checks:
- Frame rate bounded; transcript parity preserved; no new deps.
Deliverables:
- Live Hive view documented as non-authoritative renderer in docs/INTERFACES.md.
Title/ID: m20d-hive-fixtures
Goal: Prove deterministic rendering and replay stability.
Inputs: golden transcripts, CBOR snapshots.
Changes:
- apps/swarmui/tests/replay.rs — snapshot-driven render smoke tests.
- docs/INTERFACES.md — Live Hive non-goals and degradation rules.
Commands:
- cargo test -p swarmui –test replay
Checks:
- Replay produces stable visual state; expired snapshots rejected cleanly.
Deliverables:
- Golden demo snapshots committed for CI and demos.
Title/ID: m20d-design-fonts
Goal: Establish a cross-platform, UI-safe font system aligned with Tauri and PixiJS best practices.
Inputs: apps/swarmui/, design guidelines, Tauri asset bundling.
Changes:
- apps/swarmui/frontend/assets/fonts/ — bundle Inter and JetBrains Mono font files (limited weights only).
- apps/swarmui/frontend/styles/fonts.css — define canonical font stacks and defaults.
- apps/swarmui/frontend/styles/tokens.css — expose font tokens (`--font-ui`, `--font-mono`, sizes, line-heights).
- Disable ligatures by default for monospace; expose opt-in toggle.
Commands:
- cargo test -p swarmui
Checks:
- Fonts load from local assets only (no system or network dependency).
- Text renders consistently across macOS, Windows, and Linux.
Deliverables:
- Documented font policy and usage rules in docs/INTERFACES.md.
Title/ID: m20d-design-colors
Goal: Define a minimal, dark-first color system shared by HTML UI and PixiJS hive renderer.
Inputs: SwarmUI frontend, PixiJS renderer.
Changes:
- apps/swarmui/frontend/styles/colors.css — base palette, semantic colors, opacity rules.
- apps/swarmui/frontend/styles/tokens.css — color tokens shared by UI and canvas overlays.
- apps/swarmui/frontend/hive/palette.js — PixiJS color constants derived from tokens.
Commands:
- cargo test -p swarmui
Checks:
- No hard-coded colors outside token files.
- Semantic colors (ACK/ERR/flow/load) map consistently between UI and hive.
Deliverables:
- Color token table and usage notes added to docs/INTERFACES.md.
Title/ID: m20d-design-layout
Goal: Lock down layout, spacing, and panel rules for a dense operator UI.
Inputs: SwarmUI frontend panels.
Changes:
- apps/swarmui/frontend/styles/layout.css — spacing scale (4/8/12/16/24/32), panel rules.
- Remove shadows; enforce separation via tone and spacing only.
- Standardise panel chrome (headers, dividers, empty states).
Commands:
- cargo test -p swarmui
Checks:
- No arbitrary spacing values outside the defined scale.
- Panels render consistently across platforms and DPI settings.
Deliverables:
- Layout and spacing rules documented for contributors.
Title/ID: m20d-design-icons
Goal: Standardise iconography for SwarmUI controls and panels.
Inputs: SwarmUI frontend.
Changes:
- apps/swarmui/frontend/assets/icons/ — bundle Phosphor Icons SVG subset.
- apps/swarmui/frontend/components/icon.js — single icon wrapper enforcing size/weight.
- Replace mixed or ad-hoc icons with Phosphor set.
Commands:
- cargo test -p swarmui
Checks:
- Single icon set used everywhere.
- Icon weights consistent for default vs active states.
Deliverables:
- Icon usage guidelines added to docs/INTERFACES.md.
Title/ID: m20d-hive-visual-language
Goal: Define and enforce the visual language for the Live Hive renderer.
Inputs: PixiJS hive renderer.
Changes:
- apps/swarmui/frontend/hive/style.js — shape, motion, glow, and blending constants.
- Enforce circle/soft-blob primitives only; no sharp geometry.
- Define motion easing and pulse rules for normal vs error states.
Commands:
- cargo test -p swarmui
Checks:
- Hive visuals conform to documented motion and shape rules.
- Error pulses are single-shot and bounded.
Deliverables:
- Live Hive visual language documented as non-authoritative rendering rules.
Title/ID: m20d-design-tokens
Goal: Centralise all design constants into a single token system.
Inputs: SwarmUI frontend, PixiJS renderer.
Changes:
- apps/swarmui/frontend/styles/tokens.css — fonts, colors, spacing, motion.
- apps/swarmui/frontend/hive/tokens.js — generated or mirrored constants for PixiJS.
- Remove duplicated constants across UI and renderer.
Commands:
- cargo test -p swarmui
Checks:
- No duplicated magic numbers in UI or hive renderer.
- Token changes propagate consistently.
Deliverables:
- Single source-of-truth design tokens referenced in docs/INTERFACES.md.
Status: Complete — Live Hive PixiJS rendering is wired with deterministic replay fixtures, compiler-emitted hive defaults, and documented design tokens; regression pack is green.
Milestone 20e — CLI/UI Convergence Tests
Status: Complete — the original convergence work established shared grammar
and per-frontend transcript fixtures. After the canonical worker namespace
became shard-qualified, SwarmUI and coh-status intentionally stopped sharing a
zero-byte worker-path fixture with the legacy-alias console/cohsh lane;
docs/TEST_PLAN.md records their distinct hashes. The obsolete aggregate shell
harness was retired in the 2026-08-24 script audit. Current protection is the
four focused tests below, not a cross-frontend zero-byte or timing claim.
Why now (compiler): After UI/CLI/library convergence, each frontend needs deterministic fixture ownership against the shared grammar.
Goal
Establish deterministic transcript-fixture coverage for console, cohsh,
cohsh-core, SwarmUI, and coh-status while keeping each frontend bound to the
shared grammar and its current canonical namespace projection.
Deliverables
- Focused golden transcript tests for console,
cohsh,cohsh-core, SwarmUI, and coh-status. - Deterministic failure on unreviewed byte-level fixture drift within each frontend contract.
- Frontend-specific transcript fixtures stored in
tests/fixtures/transcripts/with hashes recorded by TEST_PLAN.
Commands
cargo test -p cohsh-core --test transcriptscargo test -p cohsh --test transcriptscargo test -p swarmui --test transcriptcargo test -p coh-status --test transcript
Checks (DoD)
- Each frontend matches its own bound fixture and shared ACK/ERR/END grammar.
- Abuse case: an intentionally corrupted fixture triggers a deterministic failure.
- Namespace-path differences are limited to the canonical shard path versus an explicitly enabled legacy alias; they are not normalized into a false zero-byte cross-frontend claim.
Compiler touchpoints
- Manifest fingerprints and transcript hashes recorded in docs/TEST_PLAN.md; regeneration guard verifies alignment.
Task Breakdown
Title/ID: m20e-transcript-suite
Goal: Build shared transcript fixtures and comparison harness.
Inputs: tests/fixtures/transcripts/, console + TCP outputs.
Changes:
- crates/cohsh-core/tests/transcripts.rs — own serial, TCP, and core fixture
parity.
- apps/cohsh/tests/transcripts.rs + apps/swarmui/tests/transcript.rs +
apps/coh-status/tests/transcript.rs — own each frontend's current namespace
projection and fixture.
Commands:
- cargo test -p cohsh-core --test transcripts
- cargo test -p cohsh --test transcripts
Checks:
- Corrupted fixtures fail deterministically; each focused frontend transcript
matches its TEST_PLAN-bound fixture.
Deliverables:
- Transcript fixtures stored; docs/TEST_PLAN.md references their distinct
hashes.
Title/ID: m20e-ui-cli-sync
Goal: Integrate SwarmUI/coh-status into convergence CI.
Inputs: apps/swarmui/tests/transcript.rs, apps/coh-status/tests/transcript.rs.
Changes:
- apps/swarmui/tests/transcript.rs — capture UI transcript and feed into shared fixtures.
- apps/coh-status/tests/transcript.rs — same for status tool.
Commands:
- cargo test -p swarmui --test transcript
- cargo test -p coh-status --test transcript
Checks:
- UI/CLI/console retain shared ACK/ERR/END grammar while each current
namespace projection matches its bound fixture.
Deliverables:
- CI job definition referencing convergence tests; docs updated with expected tolerances.
Milestone 20f — UI Security Hardening (Tickets & Quotas)
Status: Complete — Ticket scopes/quotas are enforced; multi-worker cohsh parity, command surface checks, and deterministic regression batching validated; host ticket mint one-shots shipped.
Why now (compiler): With UI parity established, enforce least privilege and quotas to protect interactive sessions.
Goal Lock UI/CLI security quotas and console grammar parity while proving cohsh works cleanly with multiple workers and a deterministic regression batch.
Deliverables
- Ticket scopes
{path, verb, rate}with per-ticket bandwidth and cursor quotas enforced in NineDoor and consumed by UI/CLI. PumpMetricsaddsui_reads,ui_denies; audit lines emitted for denials with manifest-driven limits.- CLI/UI regression scripts prove permission denials and quota breaches across transports.
- Cohsh multi-worker regression coverage exercises spawn/tail/kill across multiple worker telemetry paths without ID drift.
scripts/cohsh/run_regression_batch.shis a reliable manual compliance pack for this milestone (base + gated, deterministic worker-id scripts).- SwarmUI/CLI transcripts retain the shared ACK/ERR/END grammar; each namespace projection remains byte-stable against its own TEST_PLAN-bound fixture.
- Cohsh and SwarmUI add host-only ticket mint one-shots that do not alter console grammar.
Commands
cargo test -p nine-door --test ui_securitycargo test -p cohsh-corecargo test -p cohsh --test transcriptscargo test -p cohsh --test script_catalogcargo test -p swarmui --test securitycargo test -p coh-status --test transcriptcargo test -p cohsh --test client_libcargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/telemetry_ring.cohscripts/cohsh/run_regression_batch.sh
Checks (DoD)
- Write with read-only ticket →
ERR EPERMacross all transports; denial audited. - Quota breach →
ERR ELIMIT; audit lines consistent and deterministic; no duplicate frames. - Abuse case: replayed ticket beyond expiry refuses access with deterministic ERR without consuming additional quota.
- Multi-worker regression: spawn two workers, tail each telemetry path, kill both, and observe no path errors.
- Cohsh command surface checklist passes for queen + worker sessions without console disconnects.
- SwarmUI console transport passes transcript/security tests with no grammar drift.
- Regression batch passes base + gated with deterministic worker-id scripts and archived logs.
- UI/CLI/console equivalence preserved: ACK/ERR/END sequences remain byte-stable relative to the 7c baseline.
- Cohsh
--mint-ticketprints a worker/queen token; SwarmUI “Mint Ticket” button and--mint-ticketreturn the same token format and enforce worker subject requirements.
Compiler touchpoints
coh-rtcemits ticket quota tables and hashes referenced by docs/SECURITY.md and docs/USERLAND_AND_CLI.md; regeneration guard enforces consistency.
Task Breakdown
Title/ID: m20f-ticket-quotas
Goal: Enforce per-ticket path/verb/rate quotas with audit metrics.
Inputs: apps/nine-door/src/host/security.rs, PumpMetrics.
Changes:
- apps/nine-door/src/host/security.rs — quota checks, ui_denies/ui_reads metrics.
- apps/nine-door/src/host/telemetry/mod.rs — audit lines for denials.
Commands:
- cargo test -p nine-door --test ui_security
Checks:
- Quota breach triggers ERR ELIMIT and increments metrics; replayed ticket denied deterministically.
Deliverables:
- Quota tables documented via compiler output in docs/SECURITY.md.
Title/ID: m20f-cli-ui-regressions
Goal: Validate quota enforcement and multi-worker parity across CLI and UI clients.
Inputs: scripts/cohsh/telemetry_ring.coh, scripts/cohsh/shard_1k.coh, apps/cohsh/tests/script_catalog.rs, apps/swarmui/tests/security.rs.
Changes:
- scripts/cohsh/telemetry_ring.coh — ensure read-only ticket write attempt and quota exhaustion loop remain deterministic.
- scripts/cohsh/shard_1k.coh — add multi-worker coverage (second distinct-role spawn + telemetry checks).
- apps/cohsh/tests/script_catalog.rs — refresh script hashes to include updated regression scripts.
- apps/swarmui/tests/security.rs — mirror quota abuse from UI.
Commands:
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/telemetry_ring.coh
- cargo test -p cohsh --test script_catalog
- cargo test -p swarmui --test security
Checks:
- ERR EPERM/ELIMIT identical across transports; metrics observed in /proc/ingest/watch.
- Multi-worker telemetry paths pass `tail` without invalid path errors.
Deliverables:
- Regression outputs captured; manifest hash noted in docs/USERLAND_AND_CLI.md.
Title/ID: m20f-regression-batch-determinism
Goal: Make the regression batch deterministic for worker-id dependent scripts and document it in the test plan.
Inputs: scripts/cohsh/run_regression_batch.sh, docs/TEST_PLAN.md, resources/proc_tests/selftest_full.coh.
Changes:
- scripts/cohsh/run_regression_batch.sh — isolate worker-id scripts into dedicated boots and archive logs per script.
- resources/proc_tests/selftest_full.coh — align worker ids with deterministic spawn ordering.
- docs/TEST_PLAN.md — add regression batch requirements and ordering.
Commands:
- scripts/cohsh/run_regression_batch.sh
Checks:
- Regression batch passes with no worker-id drift across scripts.
Deliverables:
- Updated test plan documenting the manual regression pack.
Title/ID: m20f-cohsh-tcp-pool-safety
Goal: Stabilize cohsh TCP pooling against the single-console connection while preserving pool bench semantics.
Inputs: apps/cohsh/src/transport/tcp.rs, apps/cohsh/src/main.rs, scripts/cohsh/session_pool.coh.
Changes:
- apps/cohsh/src/transport/tcp.rs — add pooled TCP wrapper that avoids extra ATTACH/QUIT on shared connections.
- apps/cohsh/src/main.rs — use pooled TCP wrapper for session pool factory.
- apps/cohsh/src/lib.rs — adjust pool bench TCP expectations, payload limits, and skip CAT readback on console transports.
- docs/USERLAND_AND_CLI.md — document TCP console pool bench expectations.
Commands:
- cargo run -p cohsh --features tcp -- --transport tcp --script scripts/cohsh/session_pool.coh
Checks:
- cohsh interactive commands do not drop the console connection; pool bench reports OK.
Deliverables:
- Regression logs covering session_pool.coh.
Title/ID: m20f-swarmui-console-alignment
Goal: Align SwarmUI with the TCP console transport and add telemetry tail support without changing ACK/ERR grammar.
Inputs: apps/swarmui/src-tauri/main.rs, apps/swarmui/src/lib.rs, apps/root-task/src/event/mod.rs, apps/root-task/src/ninedoor.rs, docs/USERLAND_AND_CLI.md, docs/INTERFACES.md.
Changes:
- apps/root-task/src/event/mod.rs — stream telemetry ring contents for tail requests with cursor tracking.
- apps/root-task/src/ninedoor.rs — expose worker telemetry reads for console tail.
- apps/swarmui/src/lib.rs — add console backend using cohsh transport and server-managed telemetry tails.
- apps/swarmui/src-tauri/main.rs — select console vs 9P transport via env settings.
- docs/USERLAND_AND_CLI.md — document SwarmUI transport selection and console telemetry tail behavior.
- docs/INTERFACES.md — record SwarmUI console transport alignment and non-goals.
Commands:
- cargo check -p cohsh -p swarmui -p root-task
- SEL4_BUILD_DIR=$HOME/seL4/build ./scripts/cohesix-build-run.sh --sel4-build "$HOME/seL4/build" --out-dir out/cohesix --profile release --root-task-features cohesix-dev --cargo-target aarch64-unknown-none --raw-qemu --transport tcp
Checks:
- SwarmUI connects via console transport and renders live hive updates.
- Interactive cohsh command set succeeds against TCP console.
Deliverables:
- Updated docs and telemetry tail audit logs.
Title/ID: m20f-console-frame-integrity
Goal: Prevent partial TCP console sends from corrupting frame boundaries for cohsh and SwarmUI sessions.
Inputs: apps/root-task/src/net/stack.rs, apps/root-task/src/drivers/virtio/net.rs, logs/qemu-run.log, logs/cohsh-queen-interactive.log.
Changes:
- apps/root-task/src/net/stack.rs — gate TCP sends on available TX capacity; abort on partial send.
- apps/root-task/src/drivers/virtio/net.rs — fix TX written_len accounting to avoid payload truncation on repeated bytes.
Commands:
- cargo check -p root-task -p cohsh -p swarmui
- SEL4_BUILD_DIR=$HOME/seL4/build ./scripts/cohesix-build-run.sh --sel4-build "$HOME/seL4/build" --out-dir out/cohesix --profile release --root-task-features cohesix-dev --cargo-target aarch64-unknown-none --raw-qemu --transport tcp
- ./out/cohesix/host-tools/cohsh --transport tcp --tcp-host 127.0.0.1 --tcp-port 31337 --role queen
- scripts/cohsh/run_regression_batch.sh
Checks:
- Interactive cohsh commands (tail, ping, ls, cat, echo, spawn, kill, bind, mount) remain attached without reconnect loops.
- SwarmUI console session stays connected and updates hive telemetry.
- Applicable regression pack passes with existing contract outputs unchanged.
- virtio-net TX logs show written_len == payload_len for console frames; no invalid UTF-8 in console stream.
Deliverables:
- Updated qemu + cohsh logs showing stable tail output.
Title/ID: m20f-console-utf8-safe-truncation
Goal: Prevent log truncation from emitting invalid UTF-8 that drops console sessions.
Inputs: apps/root-task/src/net/outbound.rs, logs/cohsh-queen-*.log.
Changes:
- apps/root-task/src/net/outbound.rs — truncate log lines on UTF-8 boundaries; add regression test.
Commands:
- cargo test -p root-task
Checks:
- LineBuf truncation preserves valid UTF-8; cohsh no longer drops on bind/mount sequence.
Deliverables:
- Updated root-task test output; cohsh interactive logs for bind/mount.
Title/ID: m20f-console-parity-plan
Goal: Capture a reproducible trace of TCP console frame integrity issues and validate cohsh/SwarmUI parity before fixes.
Inputs: logs/tcpdump-new-*.log, logs/qemu-run-*.log, apps/root-task/src/net/stack.rs, apps/root-task/src/net/outbound.rs, apps/cohsh/src/transport/tcp.rs, apps/cohsh/src/lib.rs.
Changes:
- docs/BUILD_PLAN.md — record the console parity debug/validation plan and required logs.
- docs/BUILD_PLAN.md — capture interactive vs script-mode differences (auto-log, REPL keepalive, console lock) and trace-correlation checklist.
Commands:
- SEL4_BUILD_DIR=$HOME/seL4/build ./scripts/cohesix-build-run.sh --sel4-build "$HOME/seL4/build" --out-dir out/cohesix --profile release --root-task-features cohesix-dev --cargo-target aarch64-unknown-none --raw-qemu --transport tcp
- COHSH_TCP_DEBUG=1 ./out/cohesix/host-tools/cohsh --transport tcp --tcp-host 127.0.0.1 --tcp-port 31337 --role queen
- COHSH_TCP_DEBUG=1 ./out/cohesix/host-tools/cohsh --transport tcp --tcp-host 127.0.0.1 --tcp-port 31337 --role worker
- scripts/cohsh/run_regression_batch.sh
- rg "Flags \\[R\\]" logs/tcpdump-new-*.log
Checks:
- Console frames remain valid (no invalid UTF-8 payloads, no send.partial aborts) during the full interactive command surface.
- Interactive vs script traces show consistent ACK/ERR/END ordering for log/tail/cat without server-side RST.
- Console lock semantics preserved; concurrent attachments require explicit COHSH_CONSOLE_LOCK=0 (debug only).
Deliverables:
- Updated cohsh/QEMU/tcpdump logs documenting frame integrity and interactive parity.
- Trace-correlation notes mapping cohsh commands to tcpdump RST/FIN events.
Title/ID: m20f-cohsh-interactive-parity
Goal: Ensure interactive cohsh commands and SwarmUI console sessions match script-mode behavior without connection churn.
Inputs: apps/root-task/src/event/mod.rs, apps/root-task/src/net/stack.rs, apps/root-task/src/net/console_srv.rs, apps/cohsh/src/transport/tcp.rs, apps/swarmui/src/lib.rs, logs/cohsh-*.log.
Changes:
- apps/root-task/src/event/mod.rs — align CAT/TAIL streaming with pending stream handling and consistent END emission.
- apps/root-task/src/net/stack.rs — tune console send pacing/backpressure handling for stream output; rate-limit `tcp.flush.blocked` audit spam.
- apps/root-task/src/net/console_srv.rs — preserve END delivery without reordering stream data lines.
- apps/cohsh/src/transport/tcp.rs — harden console stream reads/reconnect logic and enforce exclusive console locking.
- apps/swarmui/src/lib.rs — match SwarmUI console error handling to cohsh transport semantics.
Commands:
- cargo check -p root-task -p cohsh -p swarmui
- SEL4_BUILD_DIR=$HOME/seL4/build ./scripts/cohesix-build-run.sh --sel4-build "$HOME/seL4/build" --out-dir out/cohesix --profile release --root-task-features cohesix-dev --cargo-target aarch64-unknown-none --raw-qemu --transport tcp
- ./out/cohesix/host-tools/cohsh --transport tcp --tcp-host 127.0.0.1 --tcp-port 31337 --role queen
- ./out/cohesix/host-tools/cohsh --transport tcp --tcp-host 127.0.0.1 --tcp-port 31337 --role worker
- scripts/cohsh/run_regression_batch.sh
Checks:
- All interactive cohsh commands succeed without reconnect loops for both queen and worker roles.
- SwarmUI console transport remains attached and renders hive updates.
- Applicable regression pack passes with existing contract outputs unchanged.
Deliverables:
- Updated QEMU + cohsh logs validating interactive parity and SwarmUI stability.
Title/ID: m20f-ticket-mint-oneshots
Goal: Add host-only ticket mint one-shots to cohsh and SwarmUI without changing console grammar.
Inputs: configs/root_task.toml, docs/WORKER_TICKETS.md, docs/HOST_TOOLS.md, docs/USERLAND_AND_CLI.md.
Changes:
- apps/cohsh/src/main.rs — add `--mint-ticket` CLI path with config-backed secrets.
- apps/cohsh/src/ticket_mint.rs — shared ticket mint helper (config parsing, defaults, subject validation).
- apps/cohsh/tests/ticket_mint.rs — verify minted tickets decode with defaults and subject rules.
- apps/cohsh/Cargo.toml — add test dependency for ticket mint fixtures.
- apps/swarmui/src-tauri/main.rs — add `--mint-ticket` CLI path and Tauri command for UI button.
- apps/swarmui/frontend/index.html — add Mint Ticket controls.
- apps/swarmui/frontend/app.js — wire Mint Ticket button to backend.
- docs/WORKER_TICKETS.md — document cohsh/SwarmUI one-shot minting.
- docs/HOST_TOOLS.md — add CLI usage examples.
- docs/USERLAND_AND_CLI.md — document flags and env vars.
- docs/TEST_PLAN.md — add the ticket mint test step.
Commands:
- cargo test -p cohsh --test ticket_mint
- cargo test -p swarmui --test security
Checks:
- Worker roles require subject; queen subject optional.
- Minted ticket decodes with the role secret and includes default budgets.
Deliverables:
- Cohsh/SwarmUI minting examples and updated docs.
Milestone 20f1 — SwarmUI Host Tool Packaging + Tauri API Fix
Status: Complete — SwarmUI is packaged in cohesix-dev host tools, the Tauri invoke bridge is resilient, and a clean build is warning-free.
Why now (host tools): SwarmUI must be buildable and runnable from the standard cohesix-dev profile, and its frontend must reliably bind to the Tauri backend without changing protocol semantics.
Goal
Ensure SwarmUI is packaged with the cohesix-dev host tool set and fix the Tauri invoke bridge so the UI connects without altering 9P/console grammar.
Deliverables
cohesix-devhost tool build includes SwarmUI inout/*/host-tools.- SwarmUI frontend uses the supported Tauri invoke bridge (no “Tauri API unavailable”).
- SwarmUI defaults to the console TCP port (
31337) unless overridden bySWARMUI_9P_PORT. - Clean
cohesix-devbuild emits no root-task warnings. - Build from a clean
out/andtarget/completes successfully.
Commands (Mac ARM64)
rm -rf out target
SEL4_BUILD_DIR=$HOME/seL4/build \
./scripts/cohesix-build-run.sh \
--sel4-build "$HOME/seL4/build" \
--out-dir out/cohesix \
--profile release \
--root-task-features cohesix-dev \
--cargo-target aarch64-unknown-none \
--raw-qemu \
--transport tcp
Checks (DoD)
- SwarmUI binary is present in
out/cohesix/host-tools. - SwarmUI connects without
ERR CONNECT Tauri API unavailable. - No changes to ACK/ERR/END grammar or ordering.
Task Breakdown
Title/ID: m20f1-swarmui-packaging
Goal: Package SwarmUI with the cohesix-dev host tool set.
Inputs: scripts/cohesix-build-run.sh, apps/swarmui/Cargo.toml.
Changes:
- scripts/cohesix-build-run.sh — include swarmui when cohesix-dev is enabled.
Commands:
- rm -rf out target
- ./scripts/cohesix-build-run.sh --root-task-features cohesix-dev ...
Checks:
- out/cohesix/host-tools/swarmui exists.
Deliverables:
- Updated build script; clean build output.
Title/ID: m20f1-tauri-invoke-bridge
Goal: Fix SwarmUI invoke bridge detection for Tauri.
Inputs: apps/swarmui/frontend/app.js.
Changes:
- apps/swarmui/frontend/app.js — use supported invoke bridge.
Commands:
- cargo run -p swarmui
Checks:
- UI connects without "Tauri API unavailable".
Deliverables:
- Updated frontend invoke path.
Title/ID: m20f1-default-port
Goal: Align SwarmUI default TCP port with the console listener.
Inputs: apps/swarmui/src-tauri/main.rs, crates/net-constants.
Changes:
- apps/swarmui/src-tauri/main.rs — default to `COHSH_TCP_PORT` when `SWARMUI_9P_PORT` unset.
Commands:
- cargo run -p swarmui
Checks:
- SwarmUI connects with no `SWARMUI_9P_PORT` set when QEMU forwards port 31337.
Deliverables:
- Default port matches console transport.
Title/ID: m20f1-clean-build-warnings
Goal: Eliminate root-task build warnings during cohesix-dev builds.
Inputs: apps/root-task/src/event/mod.rs.
Changes:
- apps/root-task/src/event/mod.rs — remove unused assignments in log streaming path.
Commands:
- ./scripts/cohesix-build-run.sh --root-task-features cohesix-dev ...
Checks:
- No warnings emitted during root-task build.
Deliverables:
- Clean build with zero root-task warnings.
Milestone 20g — Deterministic Snapshot & Replay (UI Testing)
Status: Complete — Trace record/replay fixtures and parity tests land across cohsh, SwarmUI, and coh-status; trace policy snippet and hashes align; SwarmUI header branding is live; release bundle replay verified on macOS 26.x and Ubuntu 24 (cohsh + SwarmUI).
Why now (compiler): To stabilize UI regressions without live targets, we need deterministic trace capture and replay consistent with CLI/console semantics.
Goal
Add trace record/replay across cohsh-core, cohsh, SwarmUI, and coh-status to enable deterministic UI testing.
Deliverables
cohsh-coretrace recorder/replayer for 9P frames + ACKs (.tracefiles) with size targets ≤ 1 MiB per 10 s of tail traffic.cohshCLI supports--record-trace <FILE>and--replay-trace <FILE>viacohsh-core; CLI usage is documented indocs/USERLAND_AND_CLI.mdand referenced indocs/TEST_PLAN.md.- SwarmUI “offline replay” mode consuming trace files; docs in
docs/TEST_PLAN.md. - coh-status offline replay hook for field diagnostics.
- SwarmUI frontend header includes the Cohesix SVG branding at the top of the shell.
Commands
cargo test -p cohsh-core --test tracecargo test -p cohsh --test tracecargo test -p swarmui --test tracecargo test -p coh-status --test trace
Checks (DoD)
- Replay reproduces identical telemetry curves and ACK sequences across
cohsh, SwarmUI, and coh-status; diff harness reports zero delta. - Abuse case: tampered trace (truncated or modified hash) is rejected with deterministic error and no UI state change.
- UI/CLI/console equivalence MUST be preserved: ACK/ERR/END sequences must remain byte-stable relative to the 7c baseline. All testing and verification for this milestone is governed by:
docs/TEST_PLAN.md— the sole authority on test phases, execution order, and acceptance criteria.
Compiler touchpoints
coh-rtcemits trace metadata schema and default size limits into docs/TEST_PLAN.md; regeneration guard verifies hash alignment.
Task Breakdown
Title/ID: m20g-trace-core
Goal: Implement trace recorder/replayer in cohsh-core with bounds.
Inputs: crates/cohsh-core, tests/fixtures/traces/, docs/TEST_PLAN.md.
Changes:
- crates/cohsh-core/src/trace.rs — bounded recorder/replayer with hash validation.
- crates/cohsh-core/tests/trace.rs — tampered trace negative case.
Commands:
- cargo test -p cohsh-core --test trace
Checks:
- Truncated or tampered trace rejected; valid trace replays byte-identical ACK/ERR.
Deliverables:
- Trace schema referenced in docs/TEST_PLAN.md via compiler snippet.
Title/ID: m20g-cohsh-replay
Goal: Wire cohsh CLI record/replay to cohsh-core trace format.
Inputs: apps/cohsh/src/main.rs, apps/cohsh/src/lib.rs, apps/cohsh/src/trace.rs, tests/fixtures/traces/, tests/fixtures/transcripts/trace_v0/, docs/USERLAND_AND_CLI.md, docs/TEST_PLAN.md.
Changes:
- apps/cohsh/src/main.rs — add `--record-trace` and `--replay-trace` CLI entry points using cohsh-core.
- apps/cohsh/src/lib.rs — expose trace driver for CLI use.
- apps/cohsh/tests/trace.rs — record/replay parity + tamper rejection.
Commands:
- cargo test -p cohsh --test trace
Checks:
- cohsh record/replay matches cohsh-core fixtures; tampered trace rejected deterministically.
Deliverables:
- cohsh trace CLI documented; canonical trace capture path referenced in docs/TEST_PLAN.md.
Title/ID: m20g-ui-replay
Goal: Add offline replay to SwarmUI and coh-status for deterministic UI tests.
Inputs: apps/swarmui/src/transport.rs, apps/swarmui/src-tauri/main.rs, apps/swarmui/tests/trace.rs, apps/coh-status/src/lib.rs, apps/coh-status/tests/trace.rs, docs/TEST_PLAN.md.
Changes:
- apps/swarmui/src/transport.rs — trace transport factory for replay.
- apps/swarmui/src-tauri/main.rs — `--replay-trace` entry point and decoding.
- apps/swarmui/tests/trace.rs — trace replay transcript parity.
- apps/coh-status/src/lib.rs — trace replay client wrapper + policy.
- apps/coh-status/tests/trace.rs — trace replay transcript parity.
Commands:
- cargo test -p swarmui --test trace
- cargo test -p coh-status --test trace
Checks:
- Replay matches stored trace_v0 transcripts; tampered trace rejected deterministically.
Deliverables:
- Offline replay documentation; trace fixture in tests/fixtures/traces/trace_v0.trace and transcripts in tests/fixtures/transcripts/trace_v0/.
Title/ID: m20g-swarmui-header
Goal: Add Cohesix header branding to the SwarmUI shell.
Inputs: apps/swarmui/frontend/index.html, docs/COHESIX_LOGO.png, apps/swarmui/frontend/styles/.
Changes:
- apps/swarmui/frontend/index.html — add Cohesix header at the top of the SwarmUI shell.
- apps/swarmui/frontend/styles/ — define header layout and spacing rules.
Commands:
- cargo test -p swarmui
Checks:
- Cohesix header renders at the top without disrupting layout or live hive rendering.
Deliverables:
- SwarmUI displays the Cohesix header consistently across desktop and mobile sizes.
Milestone 20h — Alpha Release Gate: As-Built Verification, Live Hive Demo, SwarmUI Replay, & Release Bundle
Status: Complete — Test Plan gates executed (clean build + CLI + regression + packaging), Live Hive + replay demos validated, and macOS/Ubuntu release bundles verified end-to-end.
Why now (compiler):
Milestone 20g defines the point at which Cohesix becomes control-plane complete and deterministic. An alpha release is only valid if the as-built system passes the full Test Plan, from a clean checkout, with no hidden assumptions.
This milestone is a release gate, not a feature milestone.
It adds no new architecture, protocols, or semantics.
It exists to prove correctness, operability, and legibility.
Goal
- Complete Milestone 20g exactly as specified in
docs/BUILD_PLAN.md. - Verify the as-built system against all applicable phases in
docs/TEST_PLAN.md. - Deliver both:
- a Deterministic Replay Demo (trust, auditability), and
- a Live Hive Demo (real-time, exciting, but controlled).
- Produce a self-contained alpha release bundle that a third party can run using only:
- the bundle
- the QEMU runner
docs/QUICKSTART.md
Hard Preconditions
A) Milestone 20g completion (blocking)
- All deliverables for Milestone 20g implemented.
- All Milestone 20g checks satisfied.
- Documentation reflects as-built behavior.
Rule: Milestone 20h MUST NOT be marked Complete unless Milestone 20g is already complete.
Testing & Verification (Canonical)
All testing and verification for this milestone is governed by:
docs/TEST_PLAN.md— the sole authority on test phases, execution order, and acceptance criteria.
Ad-hoc commands, manual test lists, or one-off scripts must not be used as acceptance criteria.
They may be inputs to the Test Plan, but DoD is defined only by Test Plan gates.
B) Clean Build & Reproducibility Gate
(Per TEST_PLAN: Build Integrity + Reproducibility phases)
Requirements
- Remove all build artifacts (
target/,out/, and equivalents). - Rebuild Cohesix from a clean workspace using the canonical build flow.
- Re-run
coh-rtcand verify generated artifacts match committed expectations.
Acceptance
- Clean build succeeds.
- No new build warnings remain unaddressed.
- No features are disabled or bypassed to achieve a clean build.
- Generated artifacts, manifests, and doc snippets are consistent.
C) CLI & Control-Plane Surface Gate
(Per TEST_PLAN: CLI Semantics, Role Enforcement, Concurrency)
The full cohsh command surface MUST be validated via the CLI test phases defined in docs/TEST_PLAN.md, including:
- Queen role coverage
- Worker role coverage
- Concurrent session behavior
- Deterministic ACK/ERR semantics
- Negative/denial cases
Key properties verified (via TEST_PLAN)
- Every documented
cohshcommand is exercised. - Role-scoped authority is enforced (queen vs worker).
- Concurrent sessions do not corrupt state or reorder acknowledgements.
- All failures are explicit, deterministic, and auditable.
Evidence
- Test Plan artifacts (logs, transcripts, or summaries) are collected and referenced.
- No manual “it looked right” validation is acceptable.
D) Regression & Stability Gate
(Per TEST_PLAN: Regression, Long-Run, Non-Regression)
- Execute the full regression batch as defined by
docs/TEST_PLAN.md. - Long-running tests must complete within declared time bounds.
- Output drift fails the gate unless explicitly approved and documented.
Acceptance
- All regression phases PASS.
- No existing regression tests are weakened.
- New tests (if any) are additive and documented.
Demo Deliverables (Post-Gate)
Only after all TEST_PLAN gates pass may the following demo artifacts be finalized.
1) Deterministic Replay Demo
- Canonical snapshot / trace generated under Milestone 20g.
- Canonical trace is shipped in the alpha bundle under
traces/with its hash for tamper checks. - Used by:
- CLI replay demo (
cohsh --replay-trace <FILE>) - SwarmUI Replay Mode
- CLI replay demo (
- Replay produces byte-identical behavior across runs.
This demo proves:
- determinism
- auditability
- UI correctness without live risk
2) Live Hive Demo (Controlled)
Purpose: demonstrate Cohesix alive — Worker model entries being created and telemetry flowing — without implying that a target Worker task was launched.
Rules (strict)
- Live mutation occurs only via:
cohsh- scripted flows covered by TEST_PLAN
- SwarmUI is observational only in live mode.
- No UI-initiated control.
Validated via
- TEST_PLAN live-operation phase
- Role enforcement + audit verification
- Deterministic logging under live load
3) SwarmUI — Dual-Mode Alpha
Replay Mode (default)
- Loads canonical snapshot from
traces/ - Full timeline scrub (pause / rewind / step)
- Deterministic visualization
Live Hive Mode
- Read-only view of live state
- Mirrors CLI-driven actions in real time
- No write capability
SwarmUI behavior is validated under TEST_PLAN UI/CLI convergence criteria.
Alpha Release Bundle
Produced only after all TEST_PLAN gates pass.
cohesix-alpha-/
├── bin/
├── image/
├── qemu/
├── scripts/
├── traces/
│ └── (canonical .trace + hash)
├── ui/
│ └── swarmui/
├── docs/
│ ├── QUICKSTART.md
│ └── (as-built snapshots)
├── VERSION.txt
└── LICENSE.txt
Bundle contents, integrity, and runnability are validated under TEST_PLAN Packaging phase.
Release bundles are emitted per host OS; the macOS tarball appends -MacOS, and the Linux aarch64
bundle appends -linux to the release name and carries Linux host tools in bin/.
QUICKSTART.md
The Quickstart MUST reference:
- TEST_PLAN phases at a high level
- What has already been verified
- What the user is expected to run vs observe
- Where the canonical trace lives in the bundle and the replay commands already defined in the Test Plan
It must not introduce new testing procedures outside the Test Plan.
Definition of Done (Authoritative)
Milestone 20h is Complete if and only if:
- Milestone 20g is complete per
docs/BUILD_PLAN.md. - All applicable phases in
docs/TEST_PLAN.mdPASS:- Build Integrity
- CLI Semantics
- Role Enforcement
- Concurrency
- Regression
- Packaging
- Clean rebuild from scratch succeeds.
- Replay demo and Live Hive demo are both validated outcomes of the Test Plan.
- SwarmUI behavior (replay + live read-only) is consistent with CLI behavior.
- A third party can run the alpha using only:
- the release bundle
qemu/run.shdocs/QUICKSTART.md
If any Test Plan gate fails, this milestone remains Incomplete.
Outcome
After Milestone 20h:
- Cohesix has a test-plan-validated alpha.
- Demos are exciting and trustworthy.
- There is one source of truth for correctness:
docs/TEST_PLAN.md. - The system is ready for external evaluation without hand-holding.
Release 0.1.0 alpha —-
Next, Alpha Release 2 targets a plug-and-play operator experience immediately after Milestone 20.x. Milestones 21-24 define the Alpha track; Pi 4 bare-metal (U-Boot + binary image) and AWS AMI work follows starting at Milestone 26.
Milestone 21a — Telemetry Ingest with OS-Named Segments (Severely Limited Create)
Why now (compiler):
Operators, demos, and UI testing need a safe way to inject telemetry from host tools without turning Cohesix into a general file transfer system. This milestone introduces a Plan-9-style telemetry ingest path that supports severely constrained create: the OS controls naming, retention, and quotas; clients can only append bounded records. This increases utility while preserving Cohesix’s control-plane boundary and minimal TCB.
Goal
Provide a deterministic, bounded telemetry ingest surface where host tools can:
- Request a new telemetry segment with OS-assigned naming, and
- Append bounded telemetry records into that segment using existing Secure9P primitives.
Non-Goals (Explicit)
- No arbitrary file upload or “scp-like” behaviour
- No client-chosen filenames or paths
- No delete / remove / rename semantics
- No random writes or truncation
- No new in-VM TCP listeners beyond the existing console
- No schema-aware parsing of CSV / XML / JSON payloads
Deliverables
- Fixed telemetry namespace under
/queen/telemetry/<device_id>/with:ctl(append-only control)seg/(OS-named, append-only segments)latest(read-only pointer to the most recent segment)
- OS-assigned segment creation via control file (no path-based create)
- Hard quotas on segment count and bytes with deterministic refuse/evict behaviour
- Bounded, versioned telemetry envelope (opaque payload)
cohsh telemetry pushhost command- CLI regression coverage added to the Regression Pack
- Documentation updated to reflect as-built semantics
Task Breakdown
Title/ID: m21a-telemetry-namespace
Goal: Introduce a fixed telemetry namespace with OS-named segments.
Inputs: docs/ARCHITECTURE.md, docs/INTERFACES.md, existing NineDoor providers.
Changes:
• apps/nine-door/src/host/telemetry.rs — add provider for:
/queen/telemetry/<device_id>/ctl
/queen/telemetry/<device_id>/seg/<seg_id>
/queen/telemetry/<device_id>/latest
• apps/nine-door/src/host/namespace.rs — mount telemetry provider under /queen.
Commands:
• cargo test -p nine-door
Checks:
• Telemetry paths appear only when enabled.
• Segment files are append-only and OS-named.
Deliverables:
• Telemetry namespace live with no client-controlled naming.
Title/ID: m21a-telemetry-create-ctl
Goal: Implement severely limited “create” via control file.
Inputs: docs/INTERFACES.md (new schema), existing append-only control patterns.
Changes:
• apps/nine-door/src/host/telemetry.rs — handle ctl command:
{“new”:“segment”,“mime”:””}
• Emit deterministic ACK with assigned seg_id.
• Update /latest pointer on successful creation.
Commands:
• cargo test -p nine-door –test telemetry_create
Checks:
• Client cannot create files by path.
• Only ctl-based segment allocation is accepted.
Deliverables:
• OS-controlled segment allocation with deterministic responses.
Title/ID: m21a-telemetry-quotas
Goal: Enforce deterministic quotas and retention for telemetry segments.
Inputs: configs/root_task.toml (new fields), coh-rtc validation rules.
Changes:
• tools/coh-rtc/src/ir.rs — add telemetry_ingest.* fields:
max_segments_per_device
max_bytes_per_segment
max_total_bytes_per_device
eviction_policy (refuse | evict-oldest)
• apps/nine-door/src/host/telemetry.rs — enforce quotas and eviction.
Commands:
• cargo run -p coh-rtc – configs/root_task.toml
• cargo test -p nine-door –test telemetry_quotas
Checks:
• Quota exhaustion yields deterministic ERR or deterministic eviction.
Deliverables:
• Manifest-driven, bounded telemetry retention.
Title/ID: m21a-telemetry-envelope
Goal: Define and document the telemetry envelope format.
Inputs: docs/INTERFACES.md.
Changes:
• docs/INTERFACES.md — add schema cohsh-telemetry-push/v1.
• Enforce max_record_bytes (≤ 4096) server-side.
Commands:
• cargo test -p nine-door –test telemetry_envelope
Checks:
• Oversized records rejected deterministically.
Deliverables:
• Versioned, opaque telemetry envelope documented and enforced.
Title/ID: m21a-cohsh-telemetry-push
Goal: Add host-side telemetry push command to cohsh.
Inputs: docs/USERLAND_AND_CLI.md, existing cohsh 9P write helpers.
Changes:
• apps/cohsh/src/lib.rs — add command:
telemetry push <src_file> –device
• Enforce file size limits, extension allowlist, chunking, and fixed destination.
• Resolve seg_id via ACK detail or /latest before appending.
Commands:
• cargo test -p cohsh
Checks:
• cohsh cannot write outside telemetry allowlist.
• Oversized files fail locally with deterministic ERR.
Deliverables:
• Safe host-side telemetry injection command.
Title/ID: m21a-telemetry-regression
Goal: Lock behaviour with deterministic CLI regression.
Inputs: scripts/cohsh/telemetry_push_create.coh.
Changes:
• scripts/cohsh/telemetry_push_create.coh — cover:
create success
push success
oversize failure
quota exhaustion behaviour
• Add script to the Regression Pack.
Commands:
• cargo run -p cohsh –features tcp – –transport tcp –script scripts/cohsh/telemetry_push_create.coh
Checks:
• Script passes unchanged across runs.
Deliverables:
• Regression coverage preventing scope
Title/ID: m21a-docs-sync
Goal: Update documentation to reflect as-built telemetry ingest.
Inputs: docs/ARCHITECTURE.md, docs/USERLAND_AND_CLI.md, docs/INTERFACES.md.
Changes:
• Document telemetry namespace, quotas, and create semantics.
Commands:
• mdbook build docs (if configured)
Checks:
• Docs match code behaviour exactly.
Deliverables:
• Docs-as-built alignment.
Checks (Definition of Done)
- Telemetry segments are OS-named and append-only.
- Clients cannot choose names or paths.
- Quotas and eviction/refusal behaviour are deterministic.
- No new in-VM network services are introduced.
- Applicable regression pack passes with existing contract outputs unchanged.
- Documentation reflects actual behaviour.
Outcome
After Milestone 21a, Cohesix supports safe, Plan-9-style telemetry creation with strict bounds and OS-owned lifecycle—improving utility for demos, UI testing, and early deployments without compromising the control-plane boundary.
Milestone 21b — Host Bridges (coh mount, coh gpu, coh telemetry pull)
Why now (adoption): After Milestone 20.x, we need plug-and-play host UX that integrates with existing CUDA/MIG workflows without new protocols or VM expansion.
Goal Deliver host-only mount views for Secure9P namespaces, GPU lease UX, and pull-based telemetry export while preserving Secure9P and console semantics (no new server-side filesystem behavior).
Deliverables
cohhost tool (single binary) with subcommandsmount,gpu, andtelemetry pull, built oncohsh-coretransports and policy tables without introducing new verbs.coh mountFUSE mount of Secure9P namespaces (for example/mnt/coh) with strict path validation, append-only enforcement, and fid lifecycle checks; never bypasses policy. The mount is a client convenience view only and does not add POSIX semantics to the system.coh gpudiscovery/status/lease UX with--mockbackend for CI and non-NVIDIA hosts, plus NVML backend on Linux; MIG visibility only when defined indocs/GPU_NODES.md.coh telemetry pullpulls bundles from/queen/telemetry/*into host storage; resumable and idempotent (no streaming).- Invariant envelope:
msize <= 8192, walk depth <= 8, no.., ACK-before-side-effects, bounded work per command.
Commands
cargo test -p coh --features mockcargo run -p coh --features mock -- mount --mock --at /tmp/coh-mountcargo run -p coh --features mock -- gpu list --mockcargo run -p coh --features mock -- telemetry pull --mock --out out/telemetry
Checks (DoD)
coh mountworks in--mockand against a dev instance; invalid paths return deterministic ERR with audit line.coh gpulease grant/deny is deterministic and logged; mock and NVML backends produce identical lease semantics.coh telemetry pullresumes without duplicates and is idempotent across restarts; no streaming or background polling.- Golden transcript markers or fixtures prove stable ACK/ERR ordering for
cohsubcommands. - Deterministic denial semantics for invalid tickets/paths/quotas are verified in tests.
- Bounded memory and bounded work per operation (no unbounded queues, no infinite retries) are enforced by limits and tests.
- Secure9P invariants preserved (msize <= 8192, path validation, fid lifecycle).
- Console semantics preserved (ACK-before-side-effects) for console-backed flows.
- Applicable regressions pass; canonical output fixtures remain authoritative,
while tests evolve only under
AGENTS.mdTest Discipline. - CI runs mock-mode tests on x86_64.
Compiler touchpoints
coh-rtcemitscohdefaults (mount root, allowlisted paths, telemetry export bounds, retry ceilings) into a manifest snippet consumed bycohand documented indocs/USERLAND_AND_CLI.md.- Manifest gates enforce host-tool-only features (FUSE, NVML) with explicit fallbacks to
--mock.
Task Breakdown
Title/ID: m21b-coh-cli-skeleton
Goal: Introduce coh host CLI with strict subcommand parsing and policy loading.
Inputs: crates/cohsh-core, docs/USERLAND_AND_CLI.md, docs/INTERFACES.md.
Changes:
- apps/coh/src/main.rs — CLI entrypoint with mount/gpu/telemetry pull subcommands.
- apps/coh/src/policy.rs — manifest-backed limits and allowlist loader.
Commands:
- cargo test -p coh --features mock
Checks:
- Unknown subcommand or invalid args returns deterministic ERR without side effects.
Deliverables:
- coh CLI skeleton and policy loader documented in docs/USERLAND_AND_CLI.md.
Title/ID: m21b-coh-mount
Goal: Implement Secure9P-backed FUSE mount with bounded operations.
Inputs: secure9p-core, docs/SECURE9P.md.
Changes:
- apps/coh/src/mount.rs — FUSE adapter enforcing path validation, append-only, and fid lifecycle.
- apps/coh/tests/mount.rs — invalid path and offset denial tests.
Commands:
- cargo test -p coh --features mock --test mount
Checks:
- `..` walk attempts and oversized reads return deterministic ERR; mount never bypasses policy.
Deliverables:
- FUSE mount docs and regression fixtures.
Title/ID: m21b-coh-gpu-telemetry
Goal: Add coh gpu UX and telemetry pull with mock backend.
Inputs: docs/GPU_NODES.md, docs/INTERFACES.md.
Changes:
- apps/coh/src/gpu.rs — list/status/lease UX with mock and NVML backends.
- apps/coh/src/telemetry.rs — resumable pull from /queen/telemetry/*.
Commands:
- cargo run -p coh --features mock -- gpu list --mock
- cargo run -p coh --features mock -- telemetry pull --mock --out out/telemetry
Checks:
- Lease grant/deny is deterministic; telemetry pull resumes without duplicates.
Deliverables:
- coh gpu + telemetry pull behavior documented with transcript fixtures.
Milestone 21c — SwarmUI Interactive cohsh Terminal (Full Prompt UX)
Why now (operator UX): SwarmUI already embeds cohsh-core and speaks the TCP console. A full terminal prompt improves operator ergonomics without adding new verbs or protocols.
Goal
Add a cohesive, terminal‑grade command prompt inside SwarmUI that reuses existing console semantics and cohsh-core parsing.
Deliverables
- SwarmUI “Console” panel with command input, scrollback, and clear/stop controls.
- Prompt supports multiline output,
OK/ERR/ENDframing, and tail streams. - Single‑session multiplexing: the prompt reuses SwarmUI’s existing console session (no second client).
- No new verbs, no new transports, and no VM changes.
- SwarmUI help output lists only console commands and points to
cohshfor additional CLI features.
Commands
cargo check -p swarmuicargo test -p cohsh-core --test transcripts
Checks (DoD)
- Prompt output matches
cohshtranscript ordering (ACK/ERR/END) forhelp → attach → log → spawn → tail → quit. - Tail streams can be stopped without breaking the shared session.
- Reconnect logic mirrors
cohsh(connection loss surfaces clearly and resumes cleanly). - Console lock is enforced (SwarmUI prompt does not allow a second TCP client).
- No new console verbs or transport semantics introduced.
Task Breakdown
Title/ID: m21c-swarmui-console-ui
Goal: Add a console panel with input, scrollback, and tail controls.
Inputs: apps/swarmui/frontend, docs/USERLAND_AND_CLI.md.
Changes:
- apps/swarmui/frontend/components/console.js — input + scrollback UI.
- apps/swarmui/frontend/styles/console.css — terminal styling.
Commands:
- npm run lint (if configured) or cargo check -p swarmui
Checks:
- Console renders without layout regressions; input accepts commands and displays output.
Deliverables:
- SwarmUI console panel wired to the UI.
Title/ID: m21c-swarmui-console-bridge
Goal: Bridge console input/output through the existing SwarmUI session.
Inputs: apps/swarmui/src-tauri/main.rs, crates/cohsh-core.
Changes:
- apps/swarmui/src-tauri/main.rs — expose send-line + stream events for prompt output.
- apps/swarmui/src/lib.rs — reuse existing session; no new transport.
Commands:
- cargo check -p swarmui
Checks:
- Prompt uses the same TCP session; no parallel client sockets.
Deliverables:
- Prompt input/output routed through existing console session.
Title/ID: m21c-swarmui-console-parity
Goal: Ensure prompt output ordering matches cohsh transcripts.
Inputs: crates/cohsh-core/tests/transcripts.rs, docs/TEST_PLAN.md.
Changes:
- apps/swarmui/tests/console_parity.rs — compare prompt output framing to cohsh transcripts.
Commands:
- cargo test -p swarmui --test console_parity
Checks:
- ACK/ERR/END sequences match cohsh fixtures for baseline verbs.
Deliverables:
- Parity test ensuring terminal output consistency.
Milestone 21d — Deterministic Node Lifecycle & Operator Control
Why now (operator): Cohesix nodes must behave predictably across power loss, network partitions, maintenance windows, and redeployments. Lifecycle semantics must be explicit, inspectable, and controllable — not inferred from side effects.
Goal Define and enforce a finite lifecycle state machine for Cohesix nodes, exposed entirely via file-shaped control surfaces, with deterministic transitions and regression coverage.
Status: Reopened for m21d-maintenance-outstanding-work-restoration,
discovered during the Milestone 26e release burn-in. Restore maintenance after
complete Worker containment and enforce the existing active-lease prerequisite;
retain terminal evidence and all lifecycle, policy, and admission contracts.
Lifecycle states (normative)
BOOTINGDEGRADEDONLINEDRAININGQUIESCEDOFFLINE
State definitions
| State | Meaning |
|---|---|
BOOTING |
Root-task started, manifest loaded, identity pending. |
DEGRADED |
Identity ok, but one or more required dependencies are missing (network, storage, sidecar, or policy gates). |
ONLINE |
Full control-plane available; workers and telemetry allowed within policy bounds. |
DRAINING |
No new work accepted; telemetry ingestion remains enabled. |
QUIESCED |
All work drained; safe to reboot or power off. |
OFFLINE |
Explicitly disabled or unrecoverable failure; control-plane actions denied. |
Control & observation (NineDoor)
Observability (read-only)
/proc/lifecycle/state/proc/lifecycle/reason/proc/lifecycle/since
Control (append-only, queen-only)
/queen/lifecycle/ctl
Supported control commands (append-only, single line)
cordon, drain, resume, quiesce, reset
Hard rules
- Transitions are explicit and must occur only via
/queen/lifecycle/ctlor deterministic system events enumerated in docs; no heuristic or hidden state changes. - Invalid transitions return deterministic
ERRand emit audit entries. - Every transition emits an audit record in
/log/queen.logwith old/new state and reason. - Tickets, telemetry ingest, worker authority, and host sidecar publishes are gated by lifecycle state.
Telemetry Spool Policy (Addendum to Milestones 21a & 37)
Rationale: Telemetry storage must be predictable under pressure. Operators must know when, why, and how data is retained or dropped. This addendum aligns policy terminology between 21a telemetry ingest quotas and the 37 persistent spool store; it does not retroactively change 21a’s completed behavior.
Policy surface (alignment)
-
Telemetry ingest (21a): keep telemetry_ingest.eviction_policy(refuseevict-oldest) as the source of truth for per-device segment limits. -
Persistent spool (37): use persistence.spool.mode(refuseoverwrite_acked) andpersistence.spool.max_record_bytesto mirror 21a’s refusal/eviction semantics while remaining crash-safe.
Manifest example (bytes only)
[telemetry_ingest]
max_segments_per_device = 64
max_bytes_per_segment = 262144
max_total_bytes_per_device = 16777216
eviction_policy = "refuse" # or "evict-oldest"
[persistence.spool]
max_bytes = 67108864
max_record_bytes = 32768
mode = "refuse" # or "overwrite_acked"
Operator visibility
/proc/spool/statusMUST expose policy and pressure fields (used_bytes, max_bytes, records, dropped, pressure, mode, ack_cursor).- If additional nodes are required for UI providers, add
/proc/spool/policyand/proc/spool/pressureonly with corresponding updates toARCHITECTURE.mdandINTERFACES.md.
CLI surface (host-only, target milestone 37 or later)
cohsh telemetry status— read spool/ingest status and render policy + pressure.cohsh telemetry explain— summarize current policy and refusal/eviction outcomes.
Mandatory regression cases
- Quota exhaustion:
refusevsevict-oldest(21a) andoverwrite_acked(37). - Ack cursor behind overwrite window (37).
- Record-too-large rejection (37).
- Offline accumulation → online drain (21a + 37).
Invariants
- All drops are auditable.
- Backpressure is observable.
- No data loss occurs without an explicit policy allowing it.
Regression coverage
scripts/cohsh/lifecycle_basic.cohscripts/cohsh/lifecycle_drain_spool.cohscripts/cohsh/lifecycle_reboot_resume.coh
Checks (DoD)
- Lifecycle transitions are byte-stable across serial/TCP.
- Telemetry is not lost during
DRAINING(spool or queue behavior is deterministic). QUIESCEDguarantees zero outstanding leases.- Replay reproduces identical state transitions and audit lines.
Task Breakdown
Title/ID: m21d-maintenance-outstanding-work-restoration
Milestone: Reopened Milestone 21d — Deterministic Node Lifecycle & Operator Control; discovered in Milestone 26e / m26e-host-integration-dependency-contract and restored with m26e-worker-supervisor-child-isolation
Goal: Refuse maintenance while work retains authority and allow it after exact Worker containment, even while terminal evidence remains visible.
Inputs: The 2026-09-13 Pi GENET release burn-in reached 43 completed CUDA/PEFT jobs in 86 minutes, then drain reported 48 outstanding leases from retained Worker entries while the lease table was empty; current Worker projections and registered lease state.
Changes:
- apps/root-task/src/{ninedoor.rs,worker_supervisor.rs,hal/worker_task.rs} — count queued, starting, ready, closing and faulted slots under the existing projection lock without copying the population; count registered active leases; preserve terminal identity and telemetry.
- apps/nine-door/src/host/{core.rs,schedule.rs} — enforce registered lease obligations alongside active host-model Workers.
- apps/root-task/tests/worker_supervisor.rs + apps/nine-door/tests/lifecycle.rs — independent state classification and lease refusal/preemption contracts.
- docs/INTERFACES.md + docs/OPERATOR_RECIPES.md — distinguish Worker containment from the active lease table and retained evidence.
Compatibility review: cohsh, coh, Hive Gateway/REST, host-ticket-agent, gpu-bridge-host, host-sidecar-bridge, cas-tool, SwarmUI, cohesix-py and raw/REST performance scripts keep their existing grammar, schemas, finite budgets, error mappings, workloads and thresholds. Only the NineDoor host model and maintenance documentation require changes; generated contracts and other host implementations require none. This restores existing maintenance prerequisites without adding an admission path or changing Worker teardown.
Commands:
- cargo test -p root-task --test worker_supervisor --test worker_fault_lifecycle
- cargo test -p nine-door --test lifecycle
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
Checks: Queued/starting/ready/closing/faulted states block maintenance; absent/terminal states do not; registered leases refuse drain/quiesce/reset until preemption; fresh exact-image Pi work remains live, retires, permits drain with retained terminal evidence, and resumes new work after both host FUSE remounts. Preserve the original failed timed run and perform only the focused revalidation requested by the operator.
Deliverables: Scoped repair, host checks, exact Pi build/first-raw and focused maintenance evidence; no new full burn-in or release acceptance claim.
Title/ID: m21d-lifecycle-state-machine
Goal: Implement the node lifecycle state machine in root-task.
Inputs: docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/ROLES_AND_SCHEDULING.md.
Changes:
- apps/root-task/src/lifecycle.rs — state machine + transition validation.
- apps/root-task/src/lib.rs — hook lifecycle into boot + worker/ticket gating.
Commands:
- cargo test -p root-task
Checks:
- Invalid transitions return deterministic ERR with audit lines.
Deliverables:
- Root-task lifecycle state machine with deterministic transitions.
Title/ID: m21d-lifecycle-ir
Goal: Add lifecycle policy fields to compiler IR and regenerate artifacts.
Inputs: configs/root_task.toml, tools/coh-rtc, docs/ARCHITECTURE.md.
Changes:
- tools/coh-rtc/src/ir.rs — lifecycle policy fields (initial state, allowed auto transitions).
- configs/root_task.toml — lifecycle policy configuration.
Commands:
- cargo run -p coh-rtc
- scripts/check-generated.sh
Checks:
- Generated snippets update; invalid lifecycle policy is rejected.
Deliverables:
- Manifest-backed lifecycle policy with validated defaults.
Title/ID: m21d-lifecycle-namespace
Goal: Expose lifecycle nodes via NineDoor and enforce permissions.
Inputs: apps/nine-door, docs/INTERFACES.md.
Changes:
- apps/nine-door/src/host/lifecycle.rs — /proc/lifecycle/* + /queen/lifecycle/ctl.
- apps/nine-door/src/host/namespace.rs — mount lifecycle provider.
Commands:
- cargo test -p nine-door --test lifecycle
Checks:
- `/proc/lifecycle/*` is read-only; `/queen/lifecycle/ctl` is queen-only append.
Deliverables:
- Lifecycle nodes live with deterministic error semantics.
Title/ID: m21d-cohsh-lifecycle
Goal: Add cohsh lifecycle commands and update CLI docs.
Inputs: docs/USERLAND_AND_CLI.md, docs/INTERFACES.md.
Changes:
- apps/cohsh/src/lib.rs — add `lifecycle` commands (cordon/drain/resume/quiesce/reset).
- docs/USERLAND_AND_CLI.md — document lifecycle CLI surface and examples.
Commands:
- cargo test -p cohsh
Checks:
- CLI rejects invalid transitions locally with deterministic ERR.
Deliverables:
- cohsh lifecycle commands with documented grammar.
Title/ID: m21d-lifecycle-regressions
Goal: Lock lifecycle behavior with deterministic regression scripts.
Inputs: scripts/cohsh/.
Changes:
- scripts/cohsh/lifecycle_basic.coh
- scripts/cohsh/lifecycle_drain_spool.coh
- scripts/cohsh/lifecycle_reboot_resume.coh
Commands:
- cohsh --script scripts/cohsh/lifecycle_basic.coh
Checks:
- Scripts pass unchanged; transcript ordering stable.
Deliverables:
- Regression coverage for lifecycle transitions and gating.
Title/ID: m21d-docs-failure-modes
Goal: Add operator-facing failure semantics and walkthroughs.
Inputs: docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/USERLAND_AND_CLI.md.
Changes:
- docs/FAILURE_MODES.md — explicit failure behavior and recovery actions.
- docs/OPERATOR_WALKTHROUGH.md — end-to-end lifecycle narrative with artifacts.
Commands:
- mdbook build docs (if configured)
Checks:
- Docs describe as-built behavior and reference canonical interfaces.
Deliverables:
- Failure modes and operator walkthrough docs committed and referenced.
Milestone 21e — Rooted Authority, Cut Detection, Explicit Session Semantics, and Live Hive Visibility
Why now (operator and systems): Cohesix enforces strict Queen/Worker authority and bounded control, but operators need those guarantees to be visible and interpretable during live operation. This milestone strengthens control-plane semantics using rooted-network ideas and extends SwarmUI Live Hive to reflect these states explicitly. The goal is less ambiguity, not more intelligence.
No new protocols, no consensus, no background convergence - only explicit state, refusal, and audit.
Goal
- Make root reachability and network cuts explicit and inspectable.
- Formalize session setup, drain, and teardown semantics.
- Surface back-pressure (busy, quota, cut, policy) as first-class signals.
- Ensure SwarmUI Live Hive visualizes these states so operators do not infer health incorrectly.
Non-Goals (Explicit)
- No leader election or consensus protocols
- No automatic failover or self-promotion
- No hidden retries or background loops
- No new transports or networking paths
- No relaxation of Secure9P / NineDoor invariants
- No changes to ACK/ERR grammar beyond reason tags
Deliverables
1) Root Reachability and Cut Detection
New read-only nodes (IR-gated, bounded):
/proc/root/reachable (ro: reachable=yes|no)
/proc/root/last_seen_ms (ro: last_seen_ms=<u64>)
/proc/root/cut_reason (ro: cut_reason=<none|network_unreachable|session_revoked|policy_denied|lifecycle_offline>)
Rules
- Workers MUST NOT exercise authority when
/proc/root/reachable=no. - Queen authority is never inferred or mirrored.
last_seen_msupdates on authenticated Queen activity.cut_reason=nonewhenreachable=yes; otherwise use deterministic priority:lifecycle_offline>session_revoked>policy_denied>network_unreachable.- Cut detection feeds lifecycle state transitions per Milestone 21d (explicit events only, no heuristics).
2) Explicit Session Semantics (Telephone-Exchange Model)
Expose session lifecycle explicitly:
/proc/9p/session/active
/proc/9p/session/<id>/state
/proc/9p/session/<id>/since_ms
/proc/9p/session/<id>/owner
Session states:
SETUPACTIVEDRAININGCLOSED
Rules
- No implicit resurrection of sessions.
- Revocation immediately transitions to
CLOSED. DRAININGforbids new control actions but allows telemetry completion./proc/9p/sessionsremains unchanged; new per-session nodes are additive only.
3) Busy / Back-Pressure as First-Class Signals
Standard refusal reason tags (console):
ERR <verb> reason=busyERR <verb> reason=quotaERR <verb> reason=cutERR <verb> reason=policy
NineDoor error codes remain within the existing error surface; no new error names are introduced.
Pressure counters (IR-gated, bounded):
/proc/pressure/busy
/proc/pressure/quota
/proc/pressure/cut
/proc/pressure/policy
Rules
- No automatic retries inside Cohesix.
- All refusals are deterministic and audited.
- Callers decide retry behavior.
4) SwarmUI Live Hive — Visualizing Authority and Pressure
Rationale: Without visualization, correct behavior looks like failure. Live Hive must reflect authority, reachability, and contention so operators do not infer false health or blame the wrong layer.
Constraints
- No new protocols
- No new data collection
- Purely renders existing file-shaped state
- Live Hive reads text nodes (no CBOR requirement)
4a) Root / Cut Status Badge
Live Hive reads:
/proc/root/reachable/proc/root/cut_reason
UI:
- Prominent
ROOT OKorCUTbadge per node - Cut reason displayed inline
- Nodes in CUT state are visually distinct (no “healthy” styling)
4b) Session Indicator
Live Hive reads:
/proc/9p/session/active/proc/9p/session/<id>/state
UI:
- Session count per node
- Highlight when sessions enter
DRAINING - Summary only (no per-session deep UI)
4c) Back-Pressure Strip
Live Hive reads:
/proc/pressure/busy/proc/pressure/quota/proc/pressure/cut/proc/pressure/policy
UI:
- Small pressure indicators or counters
- Makes contention visible instead of mysterious slowdown
4d) Error Classification
Live Hive classifies ACK/ERR events:
- Distinguish
reason=busy,reason=quota,reason=cut,reason=policy - Display as categorized events, not generic failures
5) Audit and Replay Integration
All new semantics:
- Emit audit lines via existing AuditFS
- Are replayable via ReplayFS
- Produce byte-identical ACK/ERR sequences on replay
Files and Components Touched
apps/root-task/— root reachability state and refusal taggingapps/nine-door/— session lifecycle tracking and/proc/9p/session/*apps/swarmui/— Live Hive rendering of root, sessions, and pressuretools/coh-rtc/— observability gates and boundsconfigs/root_task.tomldocs/ARCHITECTURE.mddocs/INTERFACES.mddocs/SECURITY.mddocs/USERLAND_AND_CLI.md
Regression Coverage (Required)
New scripts:
scripts/cohsh/root_cut_basic.cohscripts/cohsh/session_lifecycle.cohscripts/cohsh/busy_backpressure.coh
Live Hive validation:
- Visual state matches
/proc/*values - Replay shows identical transitions and UI markers
Checks (Definition of Done)
- Root cuts are explicit, auditable, and visible in Live Hive.
- No worker acts under partition.
- Session teardown is immediate and deterministic.
- Back-pressure is visible and never silent.
- Replay reproduces identical control outcomes.
- No new transports or background logic introduced.
- Regression Pack passes with additive coverage only.
Compiler touchpoints
coh-rtcemits observability gates and bounds for/proc/root/*,/proc/9p/session/*, and/proc/pressure/*.- Generated snippets update
docs/ARCHITECTURE.mdanddocs/INTERFACES.md; drift fails CI.
Task Breakdown
Title/ID: m21e-root-reachability-ir
Goal: Add root reachability and pressure nodes to IR and regenerate artifacts.
Inputs: configs/root_task.toml, tools/coh-rtc, docs/ARCHITECTURE.md, docs/INTERFACES.md.
Changes:
- tools/coh-rtc/src/ir.rs — add /proc/root/* and /proc/pressure/* gates + bounds.
- configs/root_task.toml — manifest toggles and size limits.
Commands:
- cargo run -p coh-rtc
- scripts/check-generated.sh
Checks:
- Generated snippets list the new nodes with correct bounds.
Deliverables:
- Regenerated snippets and manifest artifacts.
Title/ID: m21e-root-reachability-runtime
Goal: Track and expose root reachability and cut reason deterministically.
Inputs: apps/root-task, docs/ROLES_AND_SCHEDULING.md.
Changes:
- apps/root-task/src/lifecycle.rs — integrate cut reason updates.
- apps/root-task/src/observability.rs — emit /proc/root/* values.
Commands:
- cargo test -p root-task
Checks:
- reachable/cut_reason updates are deterministic and audited.
Deliverables:
- Root reachability state wired to observability.
Title/ID: m21e-session-semantics
Goal: Expose per-session state for NineDoor sessions.
Inputs: apps/nine-door, docs/INTERFACES.md.
Changes:
- apps/nine-door/src/host/session.rs — state tracking + /proc/9p/session/*.
- apps/nine-door/src/host/namespace.rs — mount session provider.
Commands:
- cargo test -p nine-door --test session_state
Checks:
- Session transitions match SETUP/ACTIVE/DRAINING/CLOSED with stable output.
Deliverables:
- Per-session observability nodes with deterministic state.
Title/ID: m21e-pressure-refusal
Goal: Standardize refusal reason tags and pressure counters.
Inputs: apps/root-task, apps/nine-door, docs/SECURITY.md.
Changes:
- apps/root-task/src/event/mod.rs — emit ERR reason tags (busy/quota/cut/policy).
- apps/nine-door/src/host/security.rs — increment /proc/pressure/* counters.
Commands:
- cargo test -p root-task
- cargo test -p nine-door --test pressure_counters
Checks:
- Refusals increment counters and emit reason tags without new error names.
Deliverables:
- Deterministic refusal tagging and pressure counters.
Title/ID: m21e-swarmui-livehive
Goal: Render root, session, and pressure state in Live Hive.
Inputs: apps/swarmui/frontend, apps/swarmui/src-tauri, docs/INTERFACES.md.
Changes:
- apps/swarmui/frontend/hive/ — badges, counters, and session summary.
- apps/swarmui/src-tauri/ — read new /proc text nodes.
Commands:
- cargo check -p swarmui
Checks:
- Live Hive displays root/cut, sessions, and pressure when view is active.
Deliverables:
- Live Hive visuals wired to text-based /proc nodes.
Title/ID: m21e-regressions
Goal: Lock behavior with deterministic regression scripts and UI replay.
Inputs: scripts/cohsh/, docs/TEST_PLAN.md.
Changes:
- scripts/cohsh/root_cut_basic.coh
- scripts/cohsh/session_lifecycle.coh
- scripts/cohsh/busy_backpressure.coh
Commands:
- cohsh --script scripts/cohsh/root_cut_basic.coh
Checks:
- Scripts pass unchanged; ACK/ERR ordering stable.
Deliverables:
- Regression scripts for reachability, session lifecycle, and pressure.
Milestone 22 — Runtime Convenience (coh run) + GPU Job Breadcrumbs
Status: Complete — coh run + breadcrumb schema, docs, and tests are in place; regression pack and full test plan (source + macOS/Ubuntu bundles) completed.
Why now (adoption): Operators need a two-minute “lease -> run -> observe -> release” loop without introducing a runtime orchestrator.
Goal
Provide a coh run wrapper that validates leases, runs a user command, and records bounded lifecycle breadcrumbs.
Deliverables
coh runsubcommand that verifies an active lease via/gpu/<id>/leasebefore execution and refuses to run without one.- Wrapper executes a user-specified command (Docker or local binary) and appends bounded lifecycle breadcrumbs to
/gpu/<id>/status(perdocs/GPU_NODES.md) through the host bridge interface. - Denial path emits deterministic ERR with no side effects; wrapper remains non-orchestrating.
Commands
cargo test -p coh --features mock --test runcargo test -p coh --features mock --test transcriptcargo run -p cohsh -- --transport mock --mock-seed-gpu --script scripts/cohsh/run_demo.coh
Checks (DoD)
- Demo script proves “lease -> run -> observe -> release” in under two minutes using
--mock. coh rundenies when no valid lease exists and logs deterministic ERR without side effects.- Breadcrumbs in
/gpu/<id>/statusare bounded, ordered, and schema-tagged; regressions enforce ordering and denial semantics. - Deterministic denial semantics for invalid tickets/paths/quotas are verified in tests.
- Bounded memory and bounded work per operation (no unbounded queues, no infinite retries) are enforced by limits and tests.
- Secure9P invariants preserved (msize <= 8192, path validation, fid lifecycle).
- Console semantics preserved (ACK-before-side-effects) for console-backed flows.
- Applicable regressions pass; canonical output fixtures remain authoritative,
while tests evolve only under
AGENTS.mdTest Discipline. - CI runs mock-mode tests on x86_64.
Compiler touchpoints
coh-rtcemits breadcrumb schema, max line bytes, and lease validation defaults into a manifest snippet consumed bycoh.- Manifest gates ensure breadcrumb fields match documented
/gpu/<id>/statussemantics.
Task Breakdown
Title/ID: m22-coh-run
Goal: Implement coh run wrapper with lease validation and bounded lifecycle logging.
Inputs: docs/GPU_NODES.md, docs/INTERFACES.md, cohsh-core transport.
Changes:
- apps/coh/src/run.rs — lease check, command spawn, breadcrumb emission.
- apps/coh/tests/run.rs — denial path and ordered breadcrumb tests.
Commands:
- cargo test -p coh --features mock --test run
Checks:
- No-lease path returns deterministic ERR; breadcrumbs are ordered and bounded.
Deliverables:
- coh run behavior documented with transcript fixtures.
Title/ID: m22-breadcrumb-schema
Goal: Define and lock breadcrumb schema for /gpu/<id>/status entries.
Inputs: docs/GPU_NODES.md, manifest IR.
Changes:
- tools/coh-rtc/ — emit breadcrumb schema and limits for host tooling.
- docs/INTERFACES.md — update status schema snippet via codegen.
Commands:
- cargo run -p coh-rtc
Checks:
- Generated schema hash matches committed docs; invalid fields rejected by coh.
Deliverables:
- Breadcrumb schema published and referenced by host tools.
Title/ID: m22-run-regressions
Goal: Add regression coverage for run wrapper ordering and denial semantics.
Inputs: scripts/cohsh/*.coh, tests/fixtures/transcripts/.
Changes:
- scripts/cohsh/run_demo.coh — lease, run, observe, release sequence.
- apps/coh/tests/transcript.rs — compare coh run transcript to cohsh baseline.
Commands:
- cargo test -p coh --features mock --test transcript
Checks:
- Transcript diff is zero; denial case emits deterministic ERR.
Deliverables:
- Regression fixtures stored; CI hook updated.
Milestone 23 — PEFT/LoRA Lifecycle Glue (coh peft)
Status: Complete — PEFT lifecycle flows, dev-virt GPU mock entries, SwarmUI replay/path/layout fixes, regression pack, and full test plan (source + macOS/Ubuntu bundles) validated.
Why now (adoption): PEFT users need a file-native loop to export jobs, import adapters, and activate or rollback safely without a new control plane.
Goal
Provide coh peft commands that export LoRA jobs, import adapters, and atomically activate or rollback models.
Deliverables
coh peft exportpulls/queen/export/lora_jobs/<job_id>/(telemetry.cbor, base_model.ref, policy.toml) into a host directory; any new manifest/provenance file must be introduced viacoh-rtcand documented indocs/GPU_NODES.mdanddocs/INTERFACES.mdin the same change.coh peft importstages adapters into host storage and exposes them as/gpu/models/available/<model_id>/manifest.tomlwith hash/size/provenance checks.coh peft activateswaps/gpu/models/activeatomically;coh peft rollbackreverts to the previous pointer with a documented recovery path.- No training in VM and no registry service; file-native only.
- New namespaces (
/queen/export/*,/gpu/models/*) have explicit NineDoor provider ownership and manifest gating; docs are updated before code depends on them. dev-virtQEMU runs without a host GPU bridge expose mock/gpu/<id>/{info,ctl,lease,status}entries for CLI demos (GPU-0/GPU-1);/gpu/modelsremains host-mirrored only.- SwarmUI replay flags (
--replay-trace,--replay) accept absolute or relative paths so release bundles can replay fixtures without path assumptions. - SwarmUI pressure/error labels break to their own line and chips render slightly smaller for readability.
Commands
cargo test -p coh --features mock --test peftcargo run -p coh --features mock -- peft export --job job_8932 --out out/lora_jobscargo run -p coh --features mock -- peft import --model llama3-edge-v7 --from out/adaptercargo run -p coh --features mock -- peft activate --model llama3-edge-v7
Checks (DoD)
- End-to-end demo covers export -> import -> activate -> rollback with deterministic outputs.
- Adapter hash/size/provenance checks reject invalid input with deterministic ERR and no side effects.
- Rollback procedure is documented and tested.
- Deterministic denial semantics for invalid tickets/paths/quotas are verified in tests.
- Bounded memory and bounded work per operation (no unbounded queues, no infinite retries) are enforced by limits and tests.
- Secure9P invariants preserved (msize <= 8192, path validation, fid lifecycle).
- Console semantics preserved (ACK-before-side-effects) for console-backed flows.
- Applicable regressions pass; canonical output fixtures remain authoritative,
while tests evolve only under
AGENTS.mdTest Discipline. - CI runs mock-mode tests on x86_64.
Compiler touchpoints
coh-rtcemits any LoRA job schema/provenance fields (if/when added) and pointer-swap limits forcoh peft.- Generated snippets refresh
docs/INTERFACES.mdanddocs/GPU_NODES.mdto keep schema alignment. - Manifest gating enumerates the new export/model namespaces and their provider ownership.
Task Breakdown
Title/ID: m23-peft-export
Goal: Implement coh peft export from /queen/export/lora_jobs/* with bounded pulls.
Inputs: docs/GPU_NODES.md, docs/INTERFACES.md.
Changes:
- apps/coh/src/peft/export.rs — pull job directory with manifest validation.
- apps/coh/tests/peft_export.rs — resumable pull and idempotency tests.
Commands:
- cargo test -p coh --features mock --test peft_export
Checks:
- Export resumes without duplicates; missing job returns deterministic ERR.
Deliverables:
- Export workflow documented with fixtures.
Title/ID: m23-peft-import-activate
Goal: Import adapters and atomically activate model pointers.
Inputs: host model registry, docs/GPU_NODES.md.
Changes:
- apps/coh/src/peft/import.rs — hash/size/provenance checks for adapters.
- apps/coh/src/peft/activate.rs — atomic pointer swap with rollback metadata.
Commands:
- cargo test -p coh --features mock --test peft_import
Checks:
- Invalid hashes rejected; pointer swap is atomic and rollback restores previous model.
Deliverables:
- Activation/rollback behavior documented with transcript fixtures.
Title/ID: m23-peft-regressions
Goal: Validate end-to-end PEFT lifecycle flows.
Inputs: scripts/cohsh/*.coh, tests/fixtures/transcripts/.
Changes:
- scripts/cohsh/peft_roundtrip.coh — export/import/activate/rollback sequence.
- apps/coh/tests/transcript.rs — parity check with cohsh output.
Commands:
- cargo test -p coh --features mock --test transcript
Checks:
- Transcript diff zero; rollback emits deterministic ACK/ERR ordering.
Deliverables:
- Regression fixtures stored and referenced in docs.
Title/ID: m23-dev-virt-gpu-mock
Goal: Provide mock `/gpu` entries for CLI demos in dev-virt.
Inputs: docs/GPU_NODES.md, docs/INTERFACES.md.
Changes:
- apps/root-task/src/ninedoor.rs — seed mock `/gpu/<id>` entries and bounded logs when no host GPU bridge is present.
Commands:
- cargo run -p cohsh --features mock -- --transport tcp --host 127.0.0.1 --port 31337 --script resources/proc_tests/selftest_quick.coh
Checks:
- `coh gpu list` returns mock GPU-0/GPU-1 and reads `/gpu/<id>/info` without errors.
Deliverables:
- Mock `/gpu` entries documented in GPU/NineDoor interface docs.
Title/ID: m23-swarmui-replay-path
Goal: Normalize SwarmUI replay paths for release bundle replay.
Inputs: docs/TEST_PLAN.md, release bundle layout.
Changes:
- apps/swarmui/src-tauri/main.rs — resolve replay paths as absolute when provided relative inputs.
Commands:
- cargo test -p swarmui --test trace
Checks:
- `swarmui --replay-trace <relative path>` and `swarmui --replay <relative path>` work from bundle root.
Deliverables:
- Replay instructions remain consistent in docs/TEST_PLAN.md.
Title/ID: m23-swarmui-pressure-layout
Goal: Improve SwarmUI pressure/error strip readability.
Inputs: apps/swarmui/frontend/index.html, apps/swarmui/frontend/styles/layout.css.
Changes:
- apps/swarmui/frontend/styles/layout.css — line-break pressure/error labels and shrink status chips slightly.
Commands:
- cargo test -p swarmui --test console_parity
Checks:
- Pressure and error labels render above chips; chip text remains legible.
Deliverables:
- UI layout changes tracked in the milestone.
Milestone 24 — Python Client + Examples (cohesix) + Doctor + Release Cut
Status: Complete — cohesix Python client + examples, coh doctor, and alpha2 release bundles validated; regression pack and full test plan (source + macOS/Ubuntu bundles) completed.
Why now (adoption): A thin, non-authoritative Python layer and a setup doctor reduce friction for CUDA, PEFT, and edge users without altering the control plane.
Goal
Deliver the cohesix Python client, runnable examples, coh doctor, and Alpha packaging/quickstart.
Deliverables
cohesixPython library with filesystem backend (viacoh mount) and TCP backend (viacohsh-coregrammar); parity tests prove no new semantics.- Examples (fast, inspectable artifacts): CUDA lease+run, MIG lease+run (when available), PEFT export/import/activate/rollback, edge telemetry write +
coh telemetry pull. coh doctorsubcommand for deterministic environment checks (tickets, mount capability, NVML or--mock, runtime prerequisites).- Alpha packaging and minimal quickstart docs for
coh+cohesix. - Release bundle updated to include
coh,cohesix, and the doctor/quickstart artifacts in the shipped tarballs.
Commands
cargo run -p coh --features mock -- doctor --mockpython -m pytest -k cohesix_paritypython tools/cohesix-py/examples/lease_run.py --mock
Checks (DoD)
- Fresh host can run
coh doctorthen a demo in < 15 minutes using--mock. - Python parity tests match
cohshor namespace behavior byte-for-byte where applicable; no new semantics introduced. - Examples leave inspectable artifacts and exit deterministically.
- Deterministic denial semantics for invalid tickets/paths/quotas are verified in tests.
- Bounded memory and bounded work per operation (no unbounded queues, no infinite retries) are enforced by limits and tests.
- Secure9P invariants preserved (msize <= 8192, path validation, fid lifecycle).
- Console semantics preserved (ACK-before-side-effects) for console-backed flows.
- Applicable regressions pass; canonical output fixtures remain authoritative,
while tests evolve only under
AGENTS.mdTest Discipline. - CI runs mock-mode tests on x86_64.
Compiler touchpoints
coh-rtcemits Python client defaults (paths, size limits, example fixtures) andcoh doctorchecks into manifest-backed snippets for docs.- Parity fixtures are hashed and referenced in docs/TEST_PLAN.md.
Task Breakdown
Title/ID: m24-python-client
Goal: Build cohesix Python client with filesystem + TCP backends and parity tests.
Inputs: crates/cohsh-core, docs/USERLAND_AND_CLI.md, docs/INTERFACES.md.
Changes:
- tools/cohesix-py/ — Python package with fs and TCP backends.
- tools/cohesix-py/tests/parity.py — parity tests against cohsh transcripts.
Commands:
- python -m pytest -k cohesix_parity
Checks:
- Parity tests match cohsh transcripts; invalid ticket yields deterministic ERR.
Deliverables:
- Python client package and parity fixtures.
Title/ID: m24-examples
Goal: Provide quick examples that leave inspectable artifacts.
Inputs: tools/cohesix-py/examples/, docs/GPU_NODES.md.
Changes:
- tools/cohesix-py/examples/lease_run.py — lease -> run -> release example.
- tools/cohesix-py/examples/peft_roundtrip.py — export/import/activate/rollback.
Commands:
- python tools/cohesix-py/examples/lease_run.py --mock
Checks:
- Example outputs are deterministic and bounded; artifacts stored under out/examples/.
Deliverables:
- Example artifacts and docs/USERLAND_AND_CLI.md updates.
Title/ID: m24-doctor-release
Goal: Implement coh doctor and Alpha packaging/quickstart.
Inputs: apps/coh/, docs/USERLAND_AND_CLI.md, README.md.
Changes:
- apps/coh/src/doctor.rs — deterministic checks for tickets, mounts, NVML/mock, runtime prerequisites.
- docs/QUICKSTART_ALPHA.md — minimal Alpha quickstart for coh + cohesix.
Commands:
- cargo run -p coh --features mock -- doctor --mock
Checks:
- Doctor emits deterministic actionable output; packaging contains coh + cohesix.
Deliverables:
- Alpha quickstart docs and packaging notes.
Title/ID: m24-swarmui-header-unify
Goal: Unify SwarmUI header alignment and scale so the banner reads as a single product surface.
Inputs: apps/swarmui/frontend/index.html, apps/swarmui/frontend/styles/layout.css.
Changes:
- apps/swarmui/frontend/styles/layout.css — align banner grid, status rows, and header badge/chip sizing.
Commands:
- npm run lint (if configured) or cargo check -p swarmui
Checks:
- Header elements align cleanly at desktop and stack without overflow at 980px/720px breakpoints.
Deliverables:
- Updated SwarmUI header styling.
Milestone 24b — Live GPU Bridge Wiring + PEFT Live Flow + Live Hive Telemetry Text
Status: Complete — live /gpu/models publish verified, non-mock PEFT flow unblocked, Live Hive telemetry text overlays validated.
Why now (adoption): Operators can’t complete a non-mock PEFT flow because the live VM still does not expose /gpu/models/*. The Queen currently returns ERR LS reason=policy detail=invalid-path on /gpu/models, so coh peft import --host ... has nowhere to publish the registry. This milestone wires the host GPU bridge into the live namespace and adds bounded telemetry text in Live Hive without introducing new protocols.
Goal
Enable a non-mock PEFT flow by publishing live /gpu/models and /gpu/telemetry into the VM, extend Live Hive with bounded telemetry text overlays + details panel, and enforce per-path polling defaults for cohsh/SwarmUI.
Deliverables
- Live GPU bridge publish path that installs
/gpu/<id>,/gpu/models/*, and/gpu/telemetry/schema.jsoninside the live VM using existing Secure9P file semantics (no new RPC services). gpu-bridge-hostgains live publish mode (--publish,--interval-ms, TCP config flags) that pushes boundedGpuNamespaceSnapshotpayloads to the Queen.coh peft importsupports a live refresh step (--publish/--refresh-gpu-models) so the host registry is mirrored into/gpu/models/available/*and/gpu/models/active.- Live host telemetry adapters for
systemd,k8s,docker, andnvidia(NVML) publish read-only snapshots under/host/*(no new control semantics). - Live Hive renders per-worker text overlays (last N lines) plus a selectable details panel; truncation/polling logic lives in
cohsh-coreonly. - Real-world telemetry defaults (manifest-backed):
- Tail poll default: 1000 ms; min 250 ms; max 10_000 ms.
- NVML status poll: 1000 ms; systemd: 2000 ms; docker: 2000 ms; k8s: 5000 ms.
- Live Hive overlay: N=3 lines, details panel M=50 lines, line cap 160 bytes, per-worker text budget 2 KiB.
- PEFT/LoRA telemetry window: 1s (
time_windowlabelms:<start>-<end>);lora_idrequired for LoRA records.
- Documentation updates (as-built):
docs/TEST_PLAN.md,docs/HOST_TOOLS.md,docs/GPU_NODES.md,docs/INTERFACES.md,docs/USERLAND_AND_CLI.md,docs/ARCHITECTURE.md, andREADME.mdwhere behavior is surfaced.
Commands
cargo run -p coh-rtcscripts/check-generated.shcargo test -p gpu-bridge-hostcargo test -p host-sidecar-bridgecargo test -p cohsh-corecargo test -p swarmui --test console_parityscripts/cohsh/run_regression_batch.shscripts/release_bundle.sh --name Cohesix-0.3.0-alpha2 --version 0.3.0-alpha2 --force
Checks (DoD)
- Live Queen returns a non-error for
ls /gpu/modelsafter the GPU bridge publish step;/gpu/telemetry/schema.jsonis readable. - Non-mock PEFT flow succeeds end-to-end:
coh peft import --host ... --publishinstallsmanifest.tomlunder/gpu/models/available/<model_id>/.coh peft activate --host ...updates/gpu/models/active.coh peft export --host ...reads/queen/export/lora_jobs/<job_id>/telemetry.cborwithin configured bounds.
- Live Hive text overlays and details panel render bounded telemetry lines without UI-owned polling logic.
- Per-path polling respects min/max bounds; defaults match the values above.
docs/TEST_PLAN.mdincludes a non-mock PEFT flow section and live telemetry checks; new steps pass on macOS 26 and Ubuntu 24 bundles.docs/HOST_TOOLS.mdanddocs/GPU_NODES.mddocument the live publish flow and required commands.- Applicable regression pack passes; existing contract-output drift fails.
- After Test Plan gates pass, release bundle minor version increments (e.g.,
Cohesix-0.2.0-alpha2→Cohesix-0.3.0-alpha2), with directory and tarball names updated.
Compiler touchpoints
coh-rtcemits telemetry polling defaults and Live Hive text budgets into manifest-backed snippets.- Any new
/gpu/bridge/*nodes and provider ownership are represented in IR and docs snippets.
Task Breakdown
Title/ID: m24b-gpu-bridge-publish
Goal: Enable live GPU bridge publishing of `/gpu/models` and telemetry schema into a running Queen.
Inputs: apps/gpu-bridge-host, apps/nine-door, docs/GPU_NODES.md.
Changes:
- apps/gpu-bridge-host/src/main.rs — add `--publish`, `--interval-ms`, TCP config flags; serialize bounded snapshots.
- apps/nine-door/src/host/core.rs — accept snapshot payloads and update `/gpu` namespace deterministically.
- docs/GPU_NODES.md — document live publish flow and error semantics.
Commands:
- cargo test -p gpu-bridge-host
- cargo test -p nine-door --test integration
Checks:
- Live `ls /gpu/models` succeeds after publish; invalid payloads return deterministic ERR.
Deliverables:
- Live GPU bridge publish path + updated GPU docs.
Title/ID: m24b-peft-live-flow
Goal: Unblock non-mock PEFT import/activate by refreshing `/gpu/models` after registry updates.
Inputs: apps/coh/, docs/USERLAND_AND_CLI.md, docs/HOST_TOOLS.md.
Changes:
- apps/coh/src/main.rs — add `--publish`/`--refresh-gpu-models` option for `peft import`.
- docs/USERLAND_AND_CLI.md — document live PEFT flow and required commands.
- docs/HOST_TOOLS.md — update PEFT examples to include live publish.
Commands:
- cargo test -p coh --features nvml
Checks:
- `coh peft import --host ... --publish` yields `/gpu/models/available/<model_id>/manifest.toml` in the VM.
Deliverables:
- Live PEFT flow documented and validated.
Title/ID: m24b-host-telemetry-live
Goal: Provide live host telemetry providers for systemd/k8s/docker/NVML.
Inputs: apps/host-sidecar-bridge, docs/INTERFACES.md, docs/ARCHITECTURE.md.
Changes:
- apps/host-sidecar-bridge/ — add live adapters and bounded snapshot formatting.
- docs/INTERFACES.md — document `/host/*/status` line formats.
- docs/ARCHITECTURE.md — record telemetry polling defaults.
Commands:
- cargo test -p host-sidecar-bridge
Checks:
- Live publish works over TCP; mock path remains deterministic.
Deliverables:
- Live host telemetry adapters + updated docs.
Title/ID: m24b-live-hive-text
Goal: Render bounded telemetry text overlays and a details panel in Live Hive using cohsh-core tails.
Inputs: crates/cohsh-core, apps/swarmui, docs/INTERFACES.md.
Changes:
- crates/cohsh-core/ — add tail polling policy and line budget enforcement.
- apps/swarmui/ — render overlays + details panel; no UI polling logic.
- docs/INTERFACES.md — Live Hive text overlay rules.
Commands:
- cargo test -p cohsh-core
- cargo test -p swarmui --test console_parity
Checks:
- Overlay shows last N lines; details panel shows last M; line truncation enforced.
Deliverables:
- Live Hive text overlay + deterministic bounds.
Title/ID: m24b-test-plan-release
Goal: Update Test Plan and cut a new release bundle after gates pass.
Inputs: docs/TEST_PLAN.md, scripts/release_bundle.sh, releases/.
Changes:
- docs/TEST_PLAN.md — add non-mock PEFT flow + live telemetry checks.
- releases/ — bump minor version bundle and tarball names.
Commands:
- scripts/cohsh/run_regression_batch.sh
- scripts/release_bundle.sh --name Cohesix-0.3.0-alpha2 --version 0.3.0-alpha2 --force
Checks:
- Test Plan additions pass on macOS 26 and Ubuntu 24 bundles.
Deliverables:
- Updated Test Plan and new release bundle.
Release 0.2.0 alpha —-
Milestone 24b1 — Live Hive UX Patch: Performance, Labels, Clickability, Telemetry Harness
Status: Complete — Live Hive responsiveness, labeling, clickability, and telemetry harness are in place and verified.
Why now (adoption): Operators cannot trust Live Hive when it is slow and ambiguous. The UI must remain responsive, worker dots must be identifiable at a glance, and clicking a worker must deterministically reveal telemetry. This patch is a focused UX + telemetry correctness fix, not a new protocol or capability change.
Goal Diagnose and fix Live Hive slowness, add worker labels and type color-coding, guarantee clickability with tests, and add a deterministic performance + telemetry harness.
Deliverables
- Root-cause analysis of Live Hive slowness (profiling notes + findings captured in docs).
- Worker dots show a short numeric label (stable per worker id) in the Hive view.
- Worker dots are color-coded by role/type (worker-heartbeat, worker-gpu, worker-lora, worker-bus).
- Click selection is reliable and verified by an automated UI test.
- A performance + telemetry harness that validates:
- UI remains responsive under N workers and M telemetry lines.
- Telemetry lines appear when a worker is selected.
- Documentation updates:
docs/TEST_PLAN.mdanddocs/INTERFACES.mdupdated with the new UI and test expectations.
Commands
cargo test -p swarmui --test console_paritycd tools/swarmui-ui-tests && npm testscripts/cohsh/run_regression_batch.sh
Checks (DoD)
- Live Hive remains responsive at N=8 workers and 2 KiB per-worker telemetry text budget.
- Each worker dot renders a numeric label and role-specific color.
- Clicking a worker reliably selects it and reveals telemetry in the details panel.
- Playwright test asserts that clicking a worker changes the selected worker and loads telemetry text.
- Performance harness reports within thresholds: 60 FPS target with < 16 ms avg frame time (or explicit measured threshold captured in test output).
- No new protocols or console grammar changes.
Task Breakdown
Title/ID: m24b1-hive-perf-diagnose
Goal: Identify and fix the root cause of Live Hive slowness without changing protocols.
Inputs: apps/swarmui, crates/cohsh-core, docs/INTERFACES.md.
Changes:
- apps/swarmui/ — profiling instrumentation + performance fixes (render loop, data diffs, throttling).
- docs/INTERFACES.md — record any clarified UI constraints or telemetry rendering rules.
Commands:
- cargo test -p swarmui --test console_parity
Checks:
- UI remains responsive with 8 workers and active telemetry tails.
Deliverables:
- Performance fix + recorded diagnosis summary.
Title/ID: m24b1-hive-labels-colors
Goal: Add worker labels and role-based color-coding to Live Hive.
Inputs: apps/swarmui, docs/INTERFACES.md.
Changes:
- apps/swarmui/ — render numeric labels near worker dots; add role palette mapping.
- docs/INTERFACES.md — document label format + role color scheme.
Commands:
- cargo test -p swarmui --test console_parity
Checks:
- Each worker dot has a stable numeric label; colors reflect worker role.
Deliverables:
- Labeled and color-coded Live Hive nodes.
Title/ID: m24b1-hive-clickability
Goal: Guarantee worker dots are clickable and selection is deterministic.
Inputs: tools/swarmui-ui-tests, apps/swarmui.
Changes:
- tools/swarmui-ui-tests/ — add Playwright test for worker selection.
- apps/swarmui/ — ensure click targets map to selection state.
Commands:
- cd tools/swarmui-ui-tests
- npm test
Checks:
- Playwright validates click selection updates the details panel.
Deliverables:
- UI clickability test and stable selection behavior.
Title/ID: m24b1-hive-perf-telemetry-harness
Goal: Add a deterministic harness that checks performance and telemetry visibility.
Inputs: tools/swarmui-ui-tests, docs/TEST_PLAN.md.
Changes:
- tools/swarmui-ui-tests/ — add perf + telemetry fixtures + thresholds.
- docs/TEST_PLAN.md — add the harness run steps and expected thresholds.
Commands:
- cd tools/swarmui-ui-tests
- npm test
Checks:
- Telemetry lines appear after selection; perf thresholds met.
Deliverables:
- Performance + telemetry harness and Test Plan update.
Release 0.3.0 alpha —-
Milestone 24c — Authoritative Scheduling Grammar + REST Gateway + Scheduler/Lease Observability
Status: Complete.
Why now (adoption): Operators want frictionless API access without weakening Cohesix’s authority model. This milestone adds VM‑authoritative scheduling/lease/policy/export control grammar, a host‑only REST gateway that is a strict projection of file/console semantics, and read‑only /proc observability surfaced in Live Hive.
Goal Add additive, non‑breaking control grammar for:
- Lease renewal/preemption + quotas
- Declarative VM scheduling queue
- Policy apply/rollback enforcement
- Export scheduling / data‑diode controls
Expose the new control surfaces through a host‑only REST gateway (OpenAPI 3.1), add Python REST backend parity, render read‑only scheduler + lease panels in SwarmUI using new /proc nodes, and support running the REST gateway as a systemd service on Linux with automatic reconnect to the Cohesix TCP console.
Deliverables
- New append‑only control files (strict JSONL schemas, bounded):
/queen/lease/ctl— lease quotas/renew/preempt/queen/schedule/ctl— scheduling queue/queen/export/ctl— export windows/policy/ctl— apply/rollback schema
- Manifest‑gated bounds for new control files and
/procnodes (IR‑driven viacoh-rtc). - New
/procnodes (read‑only, bounded):/proc/schedule/summary+/proc/schedule/queue/proc/lease/summary+/proc/lease/active+/proc/lease/preemptions
- Host‑only REST gateway + OpenAPI 3.1 spec + Swagger UI.
- Linux systemd service unit for the REST gateway with restart/reconnect behavior.
- Python REST backend with parity tests.
- SwarmUI read‑only panels: Scheduler Queue and Lease/Preemption Timeline.
- Docs updates:
docs/INTERFACES.md,docs/ARCHITECTURE.md,docs/USERLAND_AND_CLI.md,docs/HOST_TOOLS.md,docs/QUICKSTART.md,docs/PYTHON_SUPPORT.md,docs/TEST_PLAN.md.
Commands
cargo run -p coh-rtcscripts/check-generated.shcargo test -p nine-door --test schedule_createcargo test -p nine-door --test schedule_boundscargo test -p nine-door --test lease_boundscargo test -p nine-door --test policy_ctlcargo test -p nine-door --test export_ctlcargo test -p cohsh-corecargo test -p cohsh --test transcriptscargo test -p swarmui --test console_paritycd tools/swarmui-ui-tests && npm testcargo test -p hive-gatewaypython -m pytest -k cohesix_parityscripts/cohsh/run_regression_batch.sh
Checks (DoD)
- New control files accept valid JSONL and reject invalid fields with deterministic
ERR. - New
/procnodes respect manifest bounds and render deterministic, line‑oriented output. - REST gateway returns OK/ERR/END‑equivalent responses and enforces manifest bounds.
- Python REST backend matches cohsh semantics in parity tests.
- SwarmUI panels render queue + lease state from
/procwithout adding any control verbs. - REST gateway can be run under systemd on Linux, and auto‑reconnects to the Cohesix console after a QEMU restart.
docs/TEST_PLAN.mdis updated and its new steps are completed as part of DoD for this milestone.- Regression pack passes with updated fixtures; no ACK/ERR/END drift outside new fixtures.
Task Breakdown
Title/ID: m24c-grammar-manifest
Goal: Add manifest gates + bounds for new control files and `/proc` nodes.
Inputs: configs/root_task.toml, tools/coh-rtc, docs/INTERFACES.md.
Changes:
- configs/root_task.toml — add scheduler/lease/export/policy gates + size bounds.
- tools/coh-rtc — emit generated bounds for new control and `/proc` nodes.
Commands:
- cargo run -p coh-rtc
- scripts/check-generated.sh
Checks:
- Generated outputs hash-match; bounds appear in snippets.
Deliverables:
- IR-driven gates and bounds for new control files and `/proc` nodes.
Title/ID: m24c-grammar-runtime
Goal: Implement VM/NineDoor handling of new control files with strict JSONL validation + audit lines.
Inputs: apps/root-task/src/ninedoor.rs, apps/nine-door, docs/INTERFACES.md.
Changes:
- apps/root-task/src/ninedoor.rs — handlers for `/queen/lease/ctl`, `/queen/schedule/ctl`,
`/queen/export/ctl`, `/policy/ctl`.
- apps/nine-door/ — host-mode providers for the same paths.
- docs/INTERFACES.md — document schemas + error semantics.
- docs/ARCHITECTURE.md — update control surfaces/data flows.
Commands:
- cargo test -p nine-door --test schedule_create
- cargo test -p nine-door --test schedule_bounds
- cargo test -p nine-door --test lease_bounds
- cargo test -p nine-door --test policy_ctl
- cargo test -p nine-door --test export_ctl
Checks:
- Valid lines accepted; invalid lines rejected deterministically; audit lines emitted.
Deliverables:
- Authoritative scheduling/lease/policy/export grammar in VM and host NineDoor.
Title/ID: m24c-proc-observability
Goal: Add read-only `/proc` nodes for schedule + lease observability (bounded).
Inputs: apps/root-task, docs/INTERFACES.md.
Changes:
- apps/root-task — `/proc/schedule/*` and `/proc/lease/*` providers.
- docs/INTERFACES.md — new `/proc` node formats.
Commands:
- cargo test -p nine-door --test schedule_bounds
- cargo test -p nine-door --test lease_bounds
Checks:
- `/proc` nodes respect manifest byte/line limits and stable formatting.
Deliverables:
- Read-only schedule/lease observability nodes.
Title/ID: m24c-swarmui-scheduler-lease-panels
Goal: Add read-only Live Hive panels for scheduler queue and lease/preemption timeline.
Inputs: apps/swarmui, tools/swarmui-ui-tests, docs/INTERFACES.md.
Changes:
- apps/swarmui/ — panels that read `/proc/schedule/*` and `/proc/lease/*`.
- tools/swarmui-ui-tests/ — replay fixtures + Playwright checks for panel wiring.
- docs/INTERFACES.md — UI expectations (read-only).
Commands:
- cargo test -p swarmui --test console_parity
- cd tools/swarmui-ui-tests
- npm test
Checks:
- Panels render bounded content and update on replay fixtures.
Deliverables:
- Read-only SwarmUI panels for schedule and lease state.
Title/ID: m24c-host-rest-gateway
Goal: Provide host-only REST gateway mapping 1:1 to file/console semantics with systemd service support and reconnect behavior.
Inputs: crates/cohsh-core, docs/HOST_TOOLS.md.
Changes:
- apps/hive-gateway/ — new host tool (REST server + OpenAPI 3.1 + Swagger UI).
- docs/HOST_TOOLS.md — add gateway usage + auth/ticket guidance.
- docs/HOST_API.md — OpenAPI spec + examples.
- systemd unit file (Linux) — run gateway as a service with restart policy and env overrides.
Commands:
- cargo test -p hive-gateway
Checks:
- REST responses mirror OK/ERR/END; no new semantics.
- Systemd unit reconnects to QEMU after console disconnect.
Deliverables:
- REST gateway + OpenAPI spec + systemd service unit.
Title/ID: m24c-python-rest-backend
Goal: Add REST backend to cohesix-py with parity coverage.
Inputs: tools/cohesix-py, docs/PYTHON_SUPPORT.md.
Changes:
- tools/cohesix-py/cohesix/backends.py — RestBackend.
- tools/cohesix-py/tests/test_parity.py — REST parity fixtures.
- docs/PYTHON_SUPPORT.md — REST usage docs.
Commands:
- python -m pytest -k cohesix_parity
Checks:
- REST backend matches cohsh semantics.
Deliverables:
- REST backend + parity tests.
Title/ID: m24c-docs-quickstart-testplan
Goal: Update Quickstart and Test Plan for REST gateway + new control grammar.
Inputs: docs/QUICKSTART.md, docs/TEST_PLAN.md, docs/USERLAND_AND_CLI.md.
Changes:
- docs/QUICKSTART.md — REST gateway quickstart (mock + live QEMU).
- docs/TEST_PLAN.md — add schedule/lease/export/policy checks + REST gateway tests (including systemd service + reconnect).
- docs/USERLAND_AND_CLI.md — document new control files (`echo` JSONL).
Commands:
- scripts/ci/check_test_plan.sh
Checks:
- Quickstart steps run on macOS 26 + QEMU.
- New Test Plan steps executed and recorded as part of DoD.
Deliverables:
- Updated docs for frictionless adoption.
Title/ID: m24c-regression-pack
Goal: Add fixtures and run the regression pack unchanged.
Inputs: scripts/cohsh/run_regression_batch.sh, tests/fixtures/*.
Changes:
- tests/fixtures/ — add schedule/lease/export/policy fixtures.
Commands:
- scripts/cohsh/run_regression_batch.sh
Checks:
- No ACK/ERR/END drift outside updated fixtures.
Deliverables:
- Updated fixtures and regression evidence.
Release 0.4.0 alpha —-
Milestone 24d — Jetson CUDA Host Support (NVML Fallback + Doctor)
Status: Complete.
Why now (adoption): Jetson Orin hosts ship NVML with feature gaps. Host tools must still publish /gpu/* and pass coh doctor without weakening lease semantics or requiring mock mode.
Goal
Enable CUDA-based GPU discovery by default in host tools, with a deterministic NVML→CUDA fallback for Jetson-class NVML limitations. coh doctor must always succeed on Jetson by falling back to CUDA APIs when NVML is feature-limited.
Deliverables
- CUDA inventory backend for
gpu-bridge-host(driver/runtime APIs) with deterministic NVML→CUDA fallback. - CUDA support enabled by default in affected host tools (
gpu-bridge-host,coh), while preserving NVML support for dGPU hosts. coh doctortreats NVML “not supported/feature-limited” as non-fatal and falls back to CUDA; emits an explicit degraded status line.- Docs updates:
docs/HOST_TOOLS.md,docs/GPU_NODES.md,docs/USERLAND_AND_CLI.md(Jetson guidance + backend behavior). - Host setup supports Ubuntu 22.04 and documents Python 3.11 venv usage in Quickstart (for Jetson-class hosts).
Commands
cargo test -p host-cudacargo test -p gpu-bridge-hostcargo test -p coh --test transcriptcargo test -p coh --test run
Checks (DoD)
- On Jetson Orin (JP 6.2.1),
./bin/gpu-bridge-host --listreportsmemory_mb > 0,sm_count > 0, and non-empty driver/runtime versions via CUDA. - On Jetson Orin,
./bin/coh doctorsucceeds without--mockand emits a CUDA fallback status line. - On dGPU hosts with NVML,
gpu-bridge-hoststill uses NVML and returns unchanged inventory fields. /gpu/<id>/infoschema remains unchanged and leases continue to enforcemem_mbbounds.
Task Breakdown
Title/ID: m24d-gpu-bridge-cuda
Goal: Add CUDA inventory backend and deterministic NVML→CUDA fallback for GPU discovery.
Inputs: apps/gpu-bridge-host/src/lib.rs, apps/gpu-bridge-host/Cargo.toml, docs/INTERFACES.md.
Changes:
- crates/host-cuda/ — CUDA driver/runtime probe (host-only, unsafe isolated).
- apps/gpu-bridge-host/src/lib.rs — add CUDA inventory implementation and fallback logic.
- apps/gpu-bridge-host/Cargo.toml — enable CUDA support by default.
- docs/INTERFACES.md — document backend selection and Jetson behavior.
- docs/REPO_LAYOUT.md — document the new host CUDA crate.
Commands:
- cargo test -p host-cuda
- cargo test -p gpu-bridge-host
Checks:
- CUDA discovery succeeds on Jetson; NVML remains active on dGPU.
Deliverables:
- CUDA-backed GPU discovery with deterministic fallback.
Title/ID: m24d-coh-doctor-cuda
Goal: Ensure `coh doctor` passes on Jetson by falling back to CUDA when NVML is feature-limited.
Inputs: apps/coh/src/doctor.rs, apps/coh/Cargo.toml, docs/USERLAND_AND_CLI.md.
Changes:
- apps/coh/src/doctor.rs — detect NVML limitations and fallback to CUDA APIs.
- apps/coh/Cargo.toml — enable CUDA support by default alongside NVML.
- docs/USERLAND_AND_CLI.md — document NVML fallback behavior.
Commands:
- cargo test -p coh --test transcript
Checks:
- `coh doctor` succeeds on Jetson without `--mock` and emits a degraded CUDA fallback line.
Deliverables:
- Deterministic Jetson-friendly doctor checks.
Title/ID: m24d-docs-host-tools
Goal: Update host tool docs for Jetson CUDA discovery and fallback semantics.
Inputs: docs/HOST_TOOLS.md, docs/GPU_NODES.md.
Changes:
- docs/HOST_TOOLS.md — clarify CUDA-by-default behavior and NVML fallback.
- docs/GPU_NODES.md — describe Jetson inventory via CUDA APIs and limits.
Commands:
- scripts/ci/check_test_plan.sh
Checks:
- Docs accurately describe as-built host discovery behavior.
Deliverables:
- Jetson-ready host tool documentation.
Title/ID: m24d-host-setup-ubuntu
Goal: Support Ubuntu 22.04 host setup and document Python 3.11 venv usage for Quickstart.
Inputs: scripts/setup_environment.sh, docs/QUICKSTART.md.
Changes:
- scripts/setup_environment.sh — allow Ubuntu 22.04; add explicit override for unsupported versions with best-effort package selection.
- docs/QUICKSTART.md — add non-mock `coh doctor` expectations (NVML vs Jetson) and document Python 3.11 venv path for cohesix-py.
Commands:
- scripts/ci/check_test_plan.sh
Checks:
- Quickstart steps are clear for Ubuntu 22.04 + Python 3.11 venv users.
Deliverables:
- Jetson-friendly host setup and Quickstart guidance.
Title/ID: m24d-coh-fuse-default
Goal: Enable FUSE support by default for Linux `coh` builds while keeping macOS opt-in.
Inputs: apps/coh/Cargo.toml, docs/HOST_TOOLS.md, docs/QUICKSTART.md, docs/PYTHON_SUPPORT.md, docs/USERLAND_AND_CLI.md, docs/TEST_PLAN.md.
Changes:
- apps/coh/Cargo.toml — default FUSE on Linux, macOS opt-in via feature.
- docs/HOST_TOOLS.md — update OS-specific FUSE defaults.
- docs/QUICKSTART.md — document macOS opt-in behavior.
- docs/PYTHON_SUPPORT.md — align FUSE notes with OS defaults.
- docs/USERLAND_AND_CLI.md — clarify live mount prerequisites.
- docs/TEST_PLAN.md — note macOS default FUSE disabled.
Commands:
- cargo check -p coh
- cargo test -p coh --test transcript
- cargo test -p coh --test run
Checks:
- `coh doctor` passes the mount check when Linux `/dev/fuse` (or macOS `/dev/macfuse0`) is available.
- Docs reflect OS-specific FUSE defaults.
Deliverables:
- Linux-default FUSE-enabled `coh` builds with aligned documentation.
Title/ID: m24d-toolchain-linux
Goal: Provide a Linux toolchain bootstrap script aligned with Cohesix host tool requirements.
Inputs: toolchain/setup_macos_arm64.sh, toolchain/setup_linux_arm64.sh.
Changes:
- toolchain/setup_linux_arm64.sh — install build/runtime prerequisites, rustup, and QEMU checks for Ubuntu hosts.
Commands:
- toolchain/setup_linux_arm64.sh
Checks:
- Script installs required packages and reports tool versions.
Deliverables:
- Linux toolchain setup script for host builds.
Milestone 24e — REST Multiplexer Transports + SwarmUI Gateway Mode
Status: Reopened — only m24e-coh-rest-mount path-bound restoration discovered during M27g burn-in preflight; prior transport completion evidence remains retained.
Why now (adoption): Live multi-host publishing requires a single console client. We need host tools and SwarmUI to speak to the hive-gateway REST projection so multiple external workers can publish and observe without breaking the single-client console constraint.
Goal
Add REST-backed transports for host publishers (gpu-bridge-host, host-sidecar-bridge, cas-tool), coh (including a REST-backed mount mode), and SwarmUI so they can multiplex through hive-gateway while retaining all existing console and Secure9P features.
Deliverables
- REST client crate for hive-gateway (
/v1/fs/ls,/v1/fs/cat,/v1/fs/echo). cohshREST transport implementing the existing transport trait (no new semantics).cohshCLI supports--transport restwith--rest-url(env:COHSH_REST_URL,COH_REST_URL,HIVE_GATEWAY_URL).gpu-bridge-hostpublish via REST (/gpu/bridge/ctl) with--rest-url.host-sidecar-bridgepublish via REST (/host/*) with--rest-url.cas-toolupload via REST (/updates/*) with--rest-url.cohREST mode formount,gpu,telemetry pull,peft, andrunvia--rest-url(REST mount is exclusive: one active mount per gateway URL).- REST transport clamps
/procreads to manifest bounds so SwarmUI shows schedule/lease data in REST mode. - SwarmUI transport option (
SWARMUI_TRANSPORT=rest|gateway) that routes through hive-gateway and preserves all existing features in console/9p modes (REST transport is enabled by default; disable with--no-default-featuresif needed). - SwarmUI live hive PixiJS renderer remains responsive under load (particle containers + capped sim steps).
- Docs updated for REST multiplexer usage and SwarmUI transport selection.
- REST multiplexer is queen-role only; worker-role attach remains console/9P-only.
Commands
cargo check -p cohesix-restcargo test -p cohshcargo test -p gpu-bridge-hostcargo test -p host-sidecar-bridgecargo test -p swarmui
Checks (DoD)
- REST transport maps
LS/CAT/ECHOto gateway responses with deterministic errors. cohsh --transport rest --rest-urlattaches and reads/proc/schedule/*+/proc/lease/*without max_bytes bound errors.- REST publish paths populate
/gpu/*and/host/*without console attachment. cas-tool --rest-urluploads CAS bundles via/updates/*without console attachment.coh mount --rest-urlmounts via gateway (queen-role only, append-only semantics preserved, single REST mount per gateway URL).- SwarmUI REST mode connects through hive-gateway and renders the same panels/features as console/9p modes (REST transport enabled by default).
- SwarmUI live hive view remains responsive (no PixiJS stalls) with live multi-worker telemetry.
- Multiplexer smoke coverage:
cohshREST attach/ping;gpu-bridge-host --rest-url --publish;host-sidecar-bridge --rest-url --watch;cas-tool upload --rest-url;coh mount|gpu|telemetry|peft|run --rest-url;SWARMUI_TRANSPORT=restwith live hive view and console commands. - Docs describe REST multiplexer usage and transport selection clearly.
Task Breakdown
Title/ID: m24e-rest-client
Goal: Provide a shared hive-gateway REST client for host tools.
Inputs: docs/HOST_API.md.
Changes:
- crates/cohesix-rest/ — add GatewayClient + response models.
- Cargo.toml — add cohesix-rest to workspace.
Commands:
- cargo check -p cohesix-rest
Checks:
- REST client validates OK/ERR and preserves gateway error details.
Deliverables:
- Shared REST client crate for host tools.
Title/ID: m24e-cohsh-rest-transport
Goal: Add a REST-backed transport that implements the cohsh Transport trait.
Inputs: apps/cohsh/src/lib.rs, apps/cohsh/src/transport.
Changes:
- apps/cohsh/src/transport/rest.rs — implement Transport over hive-gateway.
- apps/cohsh/src/transport/mod.rs — export rest transport.
- apps/cohsh/Cargo.toml — add cohesix-rest dependency/feature.
Commands:
- cargo test -p cohsh
Checks:
- Transport methods (`list`, `read`, `write`, `tail`) map to REST without changing semantics.
Deliverables:
- REST transport available to host tools and SwarmUI.
Title/ID: m24e-cohsh-rest-cli
Goal: Expose REST transport selection in the cohsh CLI.
Inputs: apps/cohsh/src/main.rs, docs/USERLAND_AND_CLI.md, docs/HOST_TOOLS.md.
Changes:
- apps/cohsh/src/main.rs — add `--transport rest` + `--rest-url` resolution.
- docs/USERLAND_AND_CLI.md — document REST transport option for cohsh.
- docs/HOST_TOOLS.md — add cohsh REST example.
Commands:
- cargo test -p cohsh
Checks:
- `cohsh --transport rest --rest-url` connects to hive-gateway and supports core verbs.
Deliverables:
- CLI access to REST multiplexer transport.
Title/ID: m24e-rest-proc-bounds
Goal: Clamp REST `/proc` reads to manifest bounds so SwarmUI shows schedule/lease data.
Inputs: apps/cohsh/src/transport/rest.rs, docs/HOST_API.md.
Changes:
- apps/cohsh/src/transport/rest.rs — enforce `/proc` read bounds via gateway metadata.
Commands:
- cargo test -p cohsh
Checks:
- REST reads for `/proc/schedule/*` and `/proc/lease/*` succeed with bounded `max_bytes`.
Deliverables:
- SwarmUI REST schedule/lease visibility retained.
Title/ID: m24e-bridge-rest-publish
Goal: Allow host bridge publishers to use hive-gateway as a multiplexer.
Inputs: apps/gpu-bridge-host/src/main.rs, apps/host-sidecar-bridge/src/main.rs.
Changes:
- apps/gpu-bridge-host/src/main.rs — add `--rest-url` publish mode.
- apps/host-sidecar-bridge/src/main.rs — add `--rest-url` publish mode.
- apps/gpu-bridge-host/Cargo.toml — add cohesix-rest dependency.
- apps/host-sidecar-bridge/Cargo.toml — enable cohsh REST transport feature.
Commands:
- cargo test -p gpu-bridge-host
- cargo test -p host-sidecar-bridge
Checks:
- REST publish mode writes valid snapshot lines and respects bounds.
Deliverables:
- REST-capable host publishers.
Title/ID: m24e-cas-tool-rest
Goal: Allow cas-tool to upload bundles through hive-gateway.
Inputs: apps/cas-tool/src/main.rs, docs/HOST_API.md.
Changes:
- apps/cas-tool/src/main.rs — add `--rest-url` upload mode.
- apps/cas-tool/Cargo.toml — add cohesix-rest dependency.
Commands:
- cargo test -p cas-tool
Checks:
- REST upload writes base64 chunks to `/updates/*` without console attachment.
Deliverables:
- REST-capable cas-tool upload.
Title/ID: m24e-coh-rest-mount
Status: Reopened — M27g / m27g-two-hour-pi4-operator-burn-in found that REST FUSE reads exceeded advertised schedule and lease path bounds.
Milestone: Reopened 24e / coh-rest-mount; discovery Milestone 27g / two-hour-pi4-operator-burn-in.
Restoration: Share the existing bounded-path mapping with cohsh; cap coh read/tail requests and response checks at the advertised path bound, preserving caller limits and all gateway enablement/authority checks. Validate exact Mac and Linux mounts against the same current Pi; do not change target bounds or quotas.
Compatibility: coh/coh-status and cohsh share the corrected REST mapping. Review Hive Gateway, SwarmUI, host-ticket-agent, host-sidecar-bridge, gpu-bridge-host, cas-tool, sidecar-bus, Python SDK and benchmark paths; wire formats and target policy remain unchanged.
Goal: Add REST-backed CohAccess for `coh` and support `coh mount --rest-url`.
Inputs: apps/coh/src/main.rs, apps/coh/src/mount.rs, apps/coh/src/rest.rs.
Changes:
- apps/coh/src/rest.rs — implement REST CohAccess.
- apps/coh/src/mount.rs — add REST-backed mount path.
- apps/coh/src/main.rs — add `--rest-url` handling for live operations.
- apps/coh/Cargo.toml — add cohesix-rest dependency.
Commands:
- cargo test -p coh
Checks:
- REST mount uses queen-role gateway, preserves append-only semantics, and enforces a single mount per gateway URL.
Deliverables:
- `coh` REST mode including mount support.
Title/ID: m24e-swarmui-rest-transport
Goal: Add SwarmUI transport option that connects through hive-gateway.
Inputs: apps/swarmui/src-tauri/main.rs, apps/swarmui/src/lib.rs.
Changes:
- apps/swarmui/src-tauri/main.rs — support `SWARMUI_TRANSPORT=rest|gateway`.
- apps/swarmui/Cargo.toml — enable cohsh REST transport feature.
Commands:
- cargo test -p swarmui
Checks:
- SwarmUI REST mode renders existing panels and console commands without regressions (REST transport enabled by default).
Deliverables:
- SwarmUI gateway mode for REST multiplexing.
Title/ID: m24e-swarmui-pixi-perf
Goal: Keep SwarmUI Live Hive responsive under multi-worker telemetry load.
Inputs: apps/swarmui/frontend/hive/renderer.js, apps/swarmui/frontend/hive/index.js.
Changes:
- apps/swarmui/frontend/hive/renderer.js — shift to particle containers + sprite-based clusters.
- apps/swarmui/frontend/hive/index.js — cap sim steps per frame + throttle render rate under pressure.
Commands:
- cargo test -p swarmui
Checks:
- Live Hive view remains responsive (no UI stalls) with active telemetry and multiple workers.
Deliverables:
- PixiJS rendering optimizations for live mode.
Title/ID: m24e-docs-rest-multiplexer
Goal: Document REST multiplexer usage and SwarmUI transport selection.
Inputs: docs/HOST_TOOLS.md, docs/API_GUIDELINES.md, docs/HOST_API.md, docs/USERLAND_AND_CLI.md.
Changes:
- docs/HOST_TOOLS.md — add REST publish examples for host bridges and SwarmUI.
- docs/API_GUIDELINES.md — add transport guidance for REST multiplexer deployments.
- docs/HOST_API.md — add `/gpu/bridge/ctl` and `/host/*` REST examples.
- docs/USERLAND_AND_CLI.md — document SwarmUI transport options.
Commands:
- scripts/ci/check_test_plan.sh
Checks:
- Docs reflect as-built REST multiplexer behavior.
Deliverables:
- Updated operator-facing documentation.
Milestone 25 — SMP Utilization via Task Isolation (Multicore without Multithreading)
Why now (platform and performance): Cohesix targets modern aarch64 hardware where multicore CPUs are the norm. To scale throughput without sacrificing determinism, auditability, or TCB size, Cohesix must exploit seL4 SMP scheduling rather than introducing shared-memory multithreading. This milestone formalizes multicore usage through task isolation, sharding, and explicit authority boundaries.
This is a performance and clarity milestone, not a feature expansion.
Status: Complete.
Goal
Enable Cohesix to take advantage of multicore aarch64 CPUs by:
- Running multiple isolated seL4 tasks in parallel,
- Keeping authoritative state single-threaded and serial, and
- Scaling throughput through replication and partitioning, not threads.
The result must preserve:
- deterministic ACK/ERR ordering,
- replayability,
- bounded work per tick,
- and a minimal trusted computing base.
Non-Goals (Explicit)
- No POSIX threads or shared-memory multithreading
- No async runtimes with implicit scheduling
- No background work queues with unbounded growth
- No relaxation of replay or audit guarantees
- No changes to Secure9P / NineDoor semantics
- No new protocols or transports
Design Principles (Normative)
These are target-state acceptance requirements, not claims that every named service is already a child task. The as-built profile currently applies them to manifest-declared physical-driver runtimes; root-task still owns NineDoor, console/network, provider, policy, and Worker model/session paths.
- Concurrency via isolation, not sharing
All parallelism is achieved by running separate seL4 tasks. - Single-threaded authority
All authoritative decisions (tickets, lifecycle, policy, replay) are serialized through a single authority task. - Parallelism at the edges
Parsing, IO, and provider logic may scale horizontally, but must request decisions from the authority task. - Explicit back-pressure
When the authority or a shard is saturated, callers receive deterministicERR <verb> reason=busy, not hidden queuing.
Task-Level Parallelism Model
Core Roles (Illustrative)
| Task | Responsibility | Parallelism Strategy |
|---|---|---|
root-task |
Authority, lifecycle, policy | Single instance, serialized |
nine-door |
Secure9P parsing and routing | Sharded per session or subtree |
console-transport |
TCP/serial framing, auth | One task per transport |
Providers (/log, /proc, /gpu, /host) |
Namespace backends | One task per provider |
| Workers (future executable profile) | Role-specific execution | One task per Worker only after the reopened execution gate closes |
In a future profile that closes the reopened task-isolation gate, each listed service task runs a single-threaded event loop and seL4 schedules those tasks across available cores. Today root-owned service paths share the root-task event loop; only manifest-declared physical-driver runtimes are separate child tasks.
SMP Affinity and Partitioning
Affinity Guidelines
- Authority task MAY be pinned to a single core for stability.
- IO-heavy tasks MAY be pinned near device IRQ affinity.
- Provider tasks MAY be distributed across remaining cores.
Affinity is optional and platform-specific but must be:
- declarative,
- bounded,
- and documented.
Authority Interaction Contract
All non-authority tasks:
- Submit requests to the authority task via IPC,
- Receive explicit
OK/ERRresponses, - MUST NOT mutate authoritative state directly.
If the authority task cannot accept work:
- It responds with
ERR <verb> reason=busy, - The refusal is audited and observable,
- No retries occur inside the VM.
Determinism and Replay Guarantees
- Authoritative decisions are totally ordered.
- Parallel tasks must not reorder or speculate on outcomes.
- Replay executes the same authority decisions in the same order, regardless of task scheduling or core count.
- SMP must not introduce nondeterministic ACK/ERR sequences.
Implementation Touchpoints
apps/root-task/- Explicit authority IPC surface
- Busy/back-pressure signaling
apps/nine-door/- Optional sharding of protocol handling
apps/root-task/src/net/console_srv.rsandapps/root-task/src/serial/- Transport isolation from authority logic
docs/ARCHITECTURE.md- SMP model and invariants
docs/SECURITY.md- Rationale for rejecting multithreading
Testing and Validation
Functional
- All existing regression scripts must pass unchanged.
- New SMP runs must produce byte-identical ACK/ERR sequences to single-core runs.
Stress
- Saturate protocol handlers while authority remains correct.
- Verify
ERR <verb> reason=busyemission under load. - Confirm no state corruption or reordering.
- Run concurrent cohsh regression scripts over the REST multiplexer (
hive-gatewayas the sole console client) usingscripts/cohsh/REST_regression_batch.sh.
Replay
- Capture traces on multicore.
- Replay on single-core QEMU and assert identical outcomes.
Checks (Definition of Done)
- Cohesix runs correctly on multicore aarch64 under QEMU and hardware.
- Parallel tasks execute on multiple cores without shared-memory races.
- Authority logic remains single-threaded and replayable.
- Back-pressure is explicit and observable.
- No new threads, runtimes, or hidden queues introduced.
scripts/cohsh/REST_regression_batch.shpasses unchanged withhive-gatewayas the sole console client (concurrent REST runs).cohsh test --mode smpcompletes without unexpected errors while the root consolesmpcommand reports bounded userspace activity.- Root console
smp dumpemits the raw scheduler snapshot only in a compatible debug context, or returns a deterministic unsupported result. - Documentation clearly explains the SMP model and its constraints.
Task Breakdown
Title/ID: m25c-smp-kernel-enable
Goal: Enable seL4 SMP in the external kernel build and document requirements.
Inputs: ~/seL4/SMP_build, docs/ARCHITECTURE.md, docs/BUILD_PLAN.md.
Changes:
- ~/seL4/SMP_build/ — regenerate kernel artifacts with SMP enabled (do not touch ~/seL4/build).
- docs/ARCHITECTURE.md — record SMP kernel requirements and QEMU CPU count.
Commands:
- cmake --build ~/seL4/SMP_build
Checks:
- SMP-enabled kernel boots under QEMU with >1 core.
Deliverables:
- SMP kernel artifacts and documented build requirements.
Title/ID: m25c-smp-build-mirror
Goal: Mirror SMP build outputs into the repo and make SMP the default build path.
Inputs: ~/seL4/SMP_build, seL4/SMP_build, scripts/cohesix-build-run.sh.
Changes:
- seL4/SMP_build/ — copy SMP build outputs from ~/seL4/SMP_build (leave seL4/build untouched).
- scripts/cohesix-build-run.sh — default SEL4_BUILD_DIR to seL4/SMP_build; allow override to seL4/build.
Commands:
- rsync -a ~/seL4/SMP_build/ seL4/SMP_build/
Checks:
- `scripts/cohesix-build-run.sh` uses seL4/SMP_build by default; `--sel4-build seL4/build` overrides correctly.
Deliverables:
- Repo-local SMP build outputs and updated build defaults.
Title/ID: m25c-smp-qemu-defaults
Goal: Default QEMU SMP topology to four single-threaded cores while keeping overrides explicit.
Inputs: scripts/qemu-run.sh, scripts/cohesix-build-run.sh, scripts/release_bundle.sh, releases/*/qemu/run.sh, docs/QUICKSTART.md, docs/TEST_PLAN.md.
Changes:
- scripts/qemu-run.sh — default to `-smp 4,cores=4,threads=1,sockets=1`; allow overrides via `COHESIX_QEMU_SMP` / `QEMU_SMP` (count) and `COHESIX_QEMU_SMP_TOPO` / `QEMU_SMP_TOPO` (full topology string).
- scripts/cohesix-build-run.sh — same default and override handling as `scripts/qemu-run.sh`.
- scripts/release_bundle.sh — bake the SMP defaults and env overrides into generated `qemu/run.sh`.
- releases/<next minor>-* — bump minor version per policy; update bundled `qemu/run.sh` defaults and rename tarballs accordingly.
- docs/QUICKSTART.md, docs/TEST_PLAN.md — document the SMP default and override variables.
Commands:
- COHESIX_QEMU_SMP=1 scripts/cohesix-build-run.sh --no-run --cargo-target aarch64-unknown-none
- COHESIX_QEMU_SMP=4 scripts/cohesix-build-run.sh --no-run --cargo-target aarch64-unknown-none
Checks:
- Default QEMU launches use `-smp 4,cores=4,threads=1,sockets=1`.
- SMP overrides apply deterministically with no validation regressions.
- Release bundle minor version increments and tarball names match directory names.
Deliverables:
- SMP-aware QEMU launch defaults with documented override behavior.
Title/ID: m25c-authority-ipc
Goal: Serialize authoritative decisions behind a single IPC surface.
Inputs: apps/root-task, docs/ROLES_AND_SCHEDULING.md.
Changes:
- apps/root-task/src/authority.rs — authority IPC entrypoint and queueing.
- apps/root-task/src/lib.rs — route all authority mutations through IPC.
Commands:
- cargo test -p root-task
Checks:
- Authority decisions are serialized and replay-stable.
Deliverables:
- Single-threaded authority IPC with deterministic ordering.
Title/ID: m25c-sharded-tasks
Goal: Run IO, parsing, and providers in separate single-threaded seL4 tasks.
Inputs: apps/nine-door, apps/console, apps/root-task.
Changes:
- apps/root-task/src/spawn.rs — spawn NineDoor shards and provider tasks.
- apps/nine-door/src/lib.rs — shard-aware request handling.
Commands:
- cargo check -p root-task
- cargo test -p nine-door --test sharding
Checks:
- Shards execute in parallel without shared-memory coupling.
Deliverables:
- Task-isolated protocol handling.
Title/ID: m25c-affinity-ir
Goal: Add optional affinity hints to IR and enforce bounds.
Inputs: configs/root_task.toml, tools/coh-rtc, docs/ARCHITECTURE.md.
Changes:
- tools/coh-rtc/src/ir.rs — affinity hints and validation.
- configs/root_task.toml — optional affinity policy.
Commands:
- cargo run -p coh-rtc
- scripts/check-generated.sh
Checks:
- Invalid affinity configurations are rejected deterministically.
Deliverables:
- Manifest-driven affinity policy (optional).
Title/ID: m25c-smp-replay-regressions
Goal: Prove SMP determinism vs single-core runs.
Inputs: docs/TEST_PLAN.md, scripts/cohsh/.
Changes:
- scripts/cohsh/smp_parity.coh — compare ACK/ERR sequences across core counts.
Commands:
- cohsh --script scripts/cohsh/smp_parity.coh
Checks:
- Multicore and single-core transcripts match byte-for-byte.
Deliverables:
- SMP parity regression coverage.
Title/ID: m25c-smp-cohsh-selftest
Goal: Add `cohsh test --mode smp` to pressure SMP and surface activity for the `smp` console command.
Inputs: apps/cohsh, apps/nine-door, resources/proc_tests, docs/USERLAND_AND_CLI.md, docs/TEST_PLAN.md.
Changes:
- resources/proc_tests/selftest_smp.coh — SMP-oriented regression script.
- apps/nine-door/src/host/namespace.rs — expose `/proc/tests/selftest_smp.coh`.
- apps/cohsh/src/lib.rs — accept `test --mode smp` and map to the new script.
- docs/USERLAND_AND_CLI.md — document the new selftest script and mode.
- docs/TEST_PLAN.md — add `test --mode smp` to QEMU regression steps.
Commands:
- cargo test -p cohsh
Checks:
- `cohsh test --mode smp` completes without unexpected errors.
- Root console `smp` shows bounded userspace activity.
Deliverables:
- SMP selftest script and cohsh mode support.
Title/ID: m25-smp-console-metrics
Goal: Add a root console path to emit the raw seL4 scheduler snapshot.
Inputs: root console parser, seL4 debug syscall docs, docs/USERLAND_AND_CLI.md.
Changes:
- apps/root-task/src/console.rs — invoke seL4 debug scheduler/CPU dump APIs (`seL4_DebugDumpScheduler`, `seL4_DebugDumpCPUInfo`) when enabled; bounded output, no shared-memory access. The later `m26d-smp-command-post-cutover-usability` correction makes this explicit as `smp dump`.
- docs/USERLAND_AND_CLI.md — document the raw scheduler output and debug-build gating.
Commands:
- QEMU diagnostic serial console: `smp dump`
Checks:
- Debug builds emit per-core scheduler/CPU metrics (core id, runnable/idle summary) with bounded output.
- Non-debug builds return deterministic `ERR reason=unsupported` with no side effects.
Deliverables:
- Explicit raw SMP scheduler diagnostic with seL4-aligned semantics.
Title/ID: m25-smp-rest-regression-batch
Goal: Stress SMP using concurrent cohsh regression scripts via the REST multiplexer.
Inputs: scripts/cohsh/*.coh, apps/hive-gateway, docs/TEST_PLAN.md.
Changes:
- scripts/cohsh/REST_regression_batch.sh — run multiple `cohsh --transport rest` scripts concurrently against `hive-gateway` using `COHESIX_GATEWAY_URL` (or `HIVE_GATEWAY_URL`/`COHSH_REST_URL`/`COH_REST_URL`); bounded concurrency, no script changes.
- docs/TEST_PLAN.md — add a REST SMP stress run using the batch script.
Commands:
- `COHESIX_GATEWAY_URL=http://<gateway-host>:<port> scripts/cohsh/REST_regression_batch.sh`
Checks:
- All regression scripts pass unchanged under concurrent REST load.
- `ERR ... reason=busy` appears only under saturation and is audited; ACK/ERR ordering remains deterministic.
Deliverables:
- REST multiplexer SMP stress harness and documented runbook.
Title/ID: m25h-live-hive-turbo
Goal: Deliver ≥100x Live Hive responsiveness by prioritizing fresh telemetry visibility, bounded aggregation, and adaptive rendering without changing protocol semantics.
Inputs: apps/swarmui/src, apps/swarmui/frontend, tools/coh-rtc, docs/INTERFACES.md, docs/TEST_PLAN.md.
Changes:
- apps/swarmui/src/hive.rs — O(1) telemetry line parsing, per-worker pending caps, fresh-only coalescing, round-robin worker sampling, overlay/detail caching.
- apps/swarmui/src/lib.rs — Live Hive polling uses freshness-first policy; status snapshots rate-limited behind IR-driven bounds.
- apps/swarmui/frontend/hive/index.js — ring-buffer ingestion, drop-oldest under pressure, index-range event application (no per-step slicing).
- apps/swarmui/frontend/app.js + apps/swarmui/frontend/hive/index.js — keep Live Hive rendering active during scroll (no pause) while degrading cadence/quality; pause rendering only when the canvas is offscreen; throttle cadence, cap detail LOD, and drop render resolution when the canvas is idle to keep page interactions smooth.
- apps/swarmui/frontend/hive/world.js — cache per-tick positions; in-place compaction for pollen/pulse particles.
- apps/swarmui/frontend/hive/renderer.js — adaptive resolution/AA/particle budgets under degraded mode.
- tools/coh-rtc/src/ir.rs + generated configs — manifest-backed Live Hive performance knobs (sample size, pending caps, degrade thresholds).
- docs/INTERFACES.md — document freshness-first Live Hive guarantees and aggregation bounds.
- docs/TEST_PLAN.md — add Live Hive performance regression harness (target freshness + frame budget).
Commands:
- cargo run -p coh-rtc
- cargo test -p swarmui
- (SwarmUI UI regression) cd tools/swarmui-ui-tests && npm test
Checks:
- Live Hive shows current telemetry within one poll under 3–100 workers with bounded backlog.
- Aggregation/caching preserves latest state while historical detail remains bounded and replay-safe.
- Renderer meets frame budget targets under load; degraded mode engages deterministically.
Deliverables:
- Freshness-first Live Hive with documented bounds and ≥100x reduction in worst-case UI/ingest latency.
Release 0.6.0 alpha —-
Milestone 25a — REST Live Hive Performance (Parallel Polling + Batching)
Why now (demo readiness): REST is the only transport that supports the demo multiplexer, but Live Hive poll latency is dominated by serial REST reads. This milestone reduces REST wall-clock latency without changing protocols or semantics, while preserving Secure9P bounds and auditability.
Status: Complete — REST status polling is parallelized, REST cache behavior honors status_poll_ms, pool sizing supports bounded concurrency, telemetry fan-out is pool-capped, and deterministic REST performance harness coverage is in place.
Goal
Reduce Live Hive REST status poll wall-clock time with minimal risk by:
- Parallelizing REST status reads in SwarmUI, and
- Honoring
status_poll_mscaching in REST mode, - Increasing REST session pool sizing to support concurrency,
- Parallelizing REST telemetry tails after pool sizing, with concurrency capped to pool limits, and
- Adding a deterministic REST performance harness, and
- Applying manifest-driven CPU affinity to the root-task authority thread during bootstrap.
Non-Goals (Explicit)
- No new protocols or transports.
- No changes to ACK/ERR/END grammar.
- No changes to Secure9P semantics or bounds.
- No release bundle updates under
releases/. - No UI feature expansion beyond performance.
Design Principles (Normative)
- Protocol stability — REST remains a thin wrapper over existing NineDoor semantics.
- Bounded concurrency — parallelism must respect pool sizing and manifest limits.
- Deterministic behavior — parallel reads must not reorder or coalesce event semantics.
- Opt-in batching — new batch endpoints must be additive and backward compatible.
Implementation Touchpoints
apps/swarmui/src/lib.rs— REST status polling: cache + parallel reads.configs/root_task.toml— REST pool sizing adjustments (manifest-driven).configs/generated/cohsh_policy.toml+ generated policy artifacts (viacoh-rtc).apps/swarmui/src/hive.rs— REST telemetry tails: parallel with pool-capped concurrency.scripts/rest_perf_harness.py— deterministic REST performance harness.apps/root-task/src/affinity.rs,apps/root-task/src/sel4.rs,apps/root-task/src/kernel.rs— apply manifest-driven affinity during bootstrap.
Testing and Validation
Functional
- SwarmUI REST mode must continue to render Live Hive without regressions.
Performance
- Run the REST performance harness to quantify sequential vs parallel status latency.
- Verify pool sizing eliminates “session pool exhausted” under parallel polling.
Checks (Definition of Done)
- SwarmUI REST mode reduces status polling wall-clock latency by at least 2x on the same host.
scripts/rest_perf_harness.py --suite status --assert-min-ratio 2.0passes.scripts/rest_perf_harness.py --suite telemetry --assert-min-ratio 1.3passes when workers are present.cargo test -p swarmuipasses.cargo run -p coh-rtc+scripts/check-generated.shpass after manifest changes.
Task Breakdown
Title/ID: m25a-rest-perf-harness
Goal: Add a deterministic REST performance harness for Live Hive polling.
Inputs: scripts/rest_perf_harness.py.
Changes:
- scripts/rest_perf_harness.py — sequential vs parallel REST timing for status + telemetry.
Commands:
- python3 scripts/rest_perf_harness.py --help
Checks:
- Harness reports averages and enforces optional min speedup ratio.
Deliverables:
- REST performance harness script.
Title/ID: m25a-swarmui-rest-status
Goal: Parallelize and cache REST status polling in Live Hive.
Inputs: apps/swarmui/src/lib.rs.
Changes:
- apps/swarmui/src/lib.rs — parallel `/proc` reads and honor `status_poll_ms` in REST mode.
Commands:
- cargo test -p swarmui
Checks:
- Live Hive status remains correct; poll latency drops.
Deliverables:
- SwarmUI REST status polling improvements.
Title/ID: m25a-rest-pool-sizing
Goal: Increase REST session pool sizing to support parallel polling.
Inputs: configs/root_task.toml.
Changes:
- configs/root_task.toml — adjust `client_policies.cohsh.pool` sizes.
- configs/generated/cohsh_policy.toml — regenerated.
- apps/cohsh/src/generated/policy.rs — regenerated.
- docs/snippets/cohsh_policy.md — regenerated.
Commands:
- cargo run -p coh-rtc
- scripts/check-generated.sh
Checks:
- Generated policy artifacts match manifest.
Deliverables:
- Updated REST pool sizing and generated artifacts.
Title/ID: m25a-swarmui-rest-telemetry
Goal: Parallelize REST telemetry tails per worker after pool sizing.
Inputs: apps/swarmui/src/hive.rs, configs/root_task.toml, configs/generated/cohsh_policy.toml.
Changes:
- apps/swarmui/src/hive.rs — parallel `tail` calls within pool-sized bounds.
Commands:
- cargo test -p swarmui
Checks:
- No changes to telemetry semantics; poll latency improves with multiple workers.
- Parallelism never exceeds configured REST telemetry pool size.
Deliverables:
- SwarmUI REST telemetry polling improvements with pool-capped concurrency.
Title/ID: m25a-root-affinity-wire
Goal: Apply manifest-driven CPU affinity to the root-task authority thread and role-specific operations (NineDoor attach and worker spawns) and extend SMP debug output to iterate configured cores.
Inputs: apps/root-task/src/affinity.rs, apps/root-task/src/sel4.rs, apps/root-task/src/kernel.rs, tools/coh-rtc, configs/root_task.toml, docs/ARCHITECTURE.md.
Changes:
- apps/root-task/src/affinity.rs — policy validation and role-based core selection helpers.
- apps/root-task/src/sel4.rs — guarded TCB affinity syscall wrapper.
- apps/root-task/src/kernel.rs — validate policy and pin the init TCB to `authority_core`.
- apps/root-task/src/userland/mod.rs — apply NineDoor affinity during bridge attach.
- apps/root-task/src/ninedoor.rs — apply worker affinity during worker spawns.
- apps/root-task/src/console/mod.rs — per-core SMP debug dumps using configured affinity cores.
- apps/root-task/src/event/mod.rs — per-core SMP debug dumps using configured affinity cores.
- tools/coh-rtc/src/codegen/rust.rs — emit affinity policy tables.
- tools/coh-rtc/src/codegen/docs.rs — include affinity fields in manifest snippet.
- docs/ARCHITECTURE.md — document root-task affinity application.
Commands:
- cargo test -p root-task
- cargo run -p coh-rtc
- scripts/check-generated.sh
Checks:
- Root-task bootstrap logs authority core pinning when affinity is enabled.
- NineDoor attach and worker spawns log role-core affinity applications.
- `smp` debug output cycles through configured role cores.
- Generated manifest snippet includes affinity fields and matches configs.
Deliverables:
- Manifest-driven root-task affinity wiring for the init TCB.
Release 0.7.0 alpha —-
Milestone 25b — Secure Scale Gateway (1k Worker Readiness + Due Diligence Closure)
Why now (release integrity + scale): The live benchmark demonstrates 100 workers sustained with timeout onset under heavier activity before 100 in ramp mode, while due-diligence still contains open P1 blockers in gateway auth, token handling, regression coverage, and platform gates. This milestone addresses both concerns in one bounded track so scale gains are security-valid and release-valid.
Status: Complete - due-diligence gate baseline passed at out/audit/gate/20260214T044955Z, P0/P1 blockers are closed in docs/audit/findings.csv, and Milestone 25b closure evidence is published in docs/audit/AUDIT_REPORT_2026-02-14.md.
Goal
Deliver a single-console-compliant gateway path that can be validated toward 1,000-worker operation while closing release-blocking due-diligence findings by:
- Hardening gateway edge authentication and secret handling.
- Preserving the one-console-client design while improving multiplexed throughput and fairness.
- Expanding benchmark methodology to deterministic 8..1000 worker ramps with reproducible evidence.
- Restoring failing regression/workspace gates so performance evidence is trustworthy.
- Publishing closure evidence in audit artifacts and benchmark docs.
Non-Goals (Explicit)
- No new in-VM TCP listeners or alternate control-plane transports.
- No changes to ACK/ERR/END grammar or Secure9P protocol semantics.
- No bypass of role/ticket authorization inside the VM.
- No broad UI feature work unrelated to scale or due-diligence closure.
- No release bundle changes under
releases/in this milestone.
Design Principles (Normative)
- Single-console authority -
hive-gatewayremains the sole TCP console client; all concurrent operators route through REST. - Edge auth plus VM auth - add caller authentication at REST ingress without changing VM attach semantics.
- Bounded fairness - queueing, caching, and concurrency must be explicit, bounded, and manifest/policy constrained.
- Evidence-first closure - every P1/P2 closure includes deterministic repro, command logs, commit SHA, and independent verification.
- No hidden drift - docs, generated artifacts, and gate scripts must converge on one canonical command set.
Implementation Touchpoints
apps/hive-gateway/src/main.rs- request-auth middleware, bind/exposure guardrails, bounded broker queueing and metrics.apps/cohsh/src/transport/tcp.rs,apps/cohsh/src/session_pool.rs- transport/pool behavior required for gateway throughput under single console.apps/root-task/src/net/mod.rs,apps/root-task/src/net/console_srv.rs- default token removal and auth-log redaction.scripts/rest_perf_harness.py- deterministic ramp/seed support, resilient summaries, graph/CSV export.tests/tests/shard_1k.rs,scripts/cohsh/shard_1k.coh,crates/sel4-runtime/src/lib.rs,crates/sel4-sys/src/lib.rs- regression/workspace gate repairs.docs/BENCHMARKS.md,docs/HOST_API.md,docs/USERLAND_AND_CLI.md,docs/TEST_PLAN.md,docs/audit/*- as-built benchmark + assurance evidence alignment.
Testing and Validation
Security and Auth
- Verify unauthenticated REST writes are rejected deterministically.
- Verify startup fails fast when required auth token inputs are missing in non-test mode.
- Verify auth rejection logs never include raw token bytes or token-adjacent material.
Scale and Performance
- Run fixed-seed worker ramps (
8..1000) with preflight-gated VM boot/TCP/auth validation. - Compare baseline vs aggressive profiles with identical topology and bounds.
- Confirm summary emission even on timeout-heavy runs to preserve evidence quality.
Regression and Release Gates
- Re-run
cargo test -p testsandcargo test --workspaceafter fixture/platform fixes. - Re-run generated-artifact and test-plan guards with updated docs snippets.
- Re-run
scripts/ci/due_diligence_gate.shand attach logs in audit evidence.
Checks (Definition of Done)
- Single-console design remains intact (no additional in-VM listener; gateway is sole console client in multiplexer mode).
DD-2026-0001,DD-2026-0002,DD-2026-0003, andDD-2026-0010move toCLOSED_VERIFIEDwith reproducible evidence.DD-2026-0004,DD-2026-0005, andDD-2026-0009move toCLOSED_VERIFIEDwith passing gate commands.scripts/rest_perf_harness.pysupports deterministic 8..1000 worker runs and always emits machine-readable summary output.docs/BENCHMARKS.mdincludes comparative 8..1000 results and graphs sourced from committed evidence logs.scripts/ci/due_diligence_gate.shpasses without skipped/incomplete steps on milestone closure runs.
Task Breakdown
Title/ID: m25b-gateway-edge-auth
Goal: Close gateway-facing auth blockers while preserving VM authority semantics.
Inputs: apps/hive-gateway/src/main.rs, docs/HOST_API.md, docs/OPERATOR_WALKTHROUGH.md, docs/audit/findings.csv.
Changes:
- apps/hive-gateway/src/main.rs - add required request authentication middleware for mutating routes and fail-fast startup when auth secrets are unset in non-test mode.
- apps/hive-gateway/src/main.rs - enforce safe default exposure (loopback-only unless explicitly overridden with documented risk flags).
- apps/hive-gateway/tests/* - add integration tests for unauthenticated/incorrect-token/authorized request paths.
- docs/HOST_API.md - document request-auth contract, headers, and deployment hardening defaults.
Commands:
- cargo test -p hive-gateway
Checks:
- Unauthenticated POST `/v1/fs/echo` and equivalent write paths return deterministic authorization errors.
- Gateway refuses insecure startup configuration in non-test mode.
Deliverables:
- Closure evidence for DD-2026-0002 and DD-2026-0010 with logs and commit SHA.
Title/ID: m25b-console-token-hygiene
Goal: Remove insecure token defaults and prevent auth token leakage in logs.
Inputs: apps/root-task/src/net/mod.rs, apps/root-task/src/net/console_srv.rs, tools/coh-rtc, configs/root_task.toml, docs/audit/findings.csv.
Changes:
- apps/root-task/src/net/mod.rs - remove production default auth token path and require explicit configured token source.
- apps/root-task/src/net/console_srv.rs - replace raw auth-byte logging with structured redacted diagnostics.
- apps/root-task/tests/* - add negative assertions proving token material is not logged on auth rejection.
- tools/coh-rtc + generated outputs - wire token requirements through generated policy/config where applicable.
Commands:
- cargo test -p root-task
- cargo run -p coh-rtc
- scripts/check-generated.sh
Checks:
- Missing token config fails fast outside test profiles.
- Auth failure logs do not expose token contents or byte-equivalent payload.
Deliverables:
- Closure evidence for DD-2026-0001 and DD-2026-0003 with regenerated artifacts.
Title/ID: m25b-single-console-broker
Goal: Increase gateway multiplexing throughput under one attached console session.
Inputs: apps/hive-gateway/src/main.rs, apps/cohsh/src/session_pool.rs, apps/cohsh/src/transport/tcp.rs, docs/USERLAND_AND_CLI.md.
Changes:
- apps/hive-gateway/src/main.rs - introduce bounded broker queueing with priority classes (control before telemetry), fairness scheduling, and explicit backpressure signals.
- apps/hive-gateway/src/main.rs - add bounded read-through caches for hot `/proc` reads with deterministic TTL and invalidation.
- apps/hive-gateway/src/main.rs - expose queue depth, saturation, timeout, and retry counters through gateway metrics/status paths.
- docs/USERLAND_AND_CLI.md - clarify single-console behavior and REST multiplexer operational limits.
Commands:
- cargo test -p hive-gateway
- python3 scripts/rest_perf_harness.py --suite status --assert-min-ratio 2.0
Checks:
- Parallel REST load no longer collapses into avoidable "session pool exhausted" behavior at configured policy limits.
- No change to console grammar or in-VM listener topology.
Deliverables:
- Single-console broker implementation with bounded throughput/fairness instrumentation.
Title/ID: m25b-rest-harness-1k
Goal: Extend the benchmark harness and report pipeline for deterministic 1k-worker readiness evidence.
Inputs: scripts/rest_perf_harness.py, docs/BENCHMARKS.md.
Changes:
- scripts/rest_perf_harness.py - add deterministic seed handling for ramp profiles and worker bands up to 1000.
- scripts/rest_perf_harness.py - require preflight boot/TCP/auth/LS checks before load execution.
- scripts/rest_perf_harness.py - harden timeout/error handling so run summaries and per-op stats are always emitted.
- scripts/rest_perf_harness.py - emit CSV/JSON artifacts consumable by benchmark graphs.
- docs/BENCHMARKS.md - publish baseline vs aggressive 8..1000 runs, degradation thresholds, and graph-backed interpretation.
Commands:
- python3 scripts/rest_perf_harness.py --mode simulate --workers-min 8 --workers-max 1000 --duration-mins 5 --seed 2501
- python3 scripts/rest_perf_harness.py --mode simulate --workers-min 8 --workers-max 1000 --duration-mins 5 --seed 2501 --intensity-min 6 --intensity-max 6
Checks:
- Both runs emit reproducible summaries and evidence files.
- Report includes graphs and explicit onset points for buffer pressure and timeout behavior.
Deliverables:
- 1k-worker readiness benchmark evidence pack and updated benchmark report.
Title/ID: m25b-regression-and-gate-closure
Goal: Repair failing release gates so scale evidence is release-grade.
Inputs: tests/tests/shard_1k.rs, scripts/cohsh/shard_1k.coh, crates/sel4-runtime/src/lib.rs, crates/sel4-sys/src/lib.rs, docs/TEST_PLAN.md, scripts/ci/due_diligence_gate.sh, docs/audit/*.
Changes:
- tests/tests/shard_1k.rs + scripts/cohsh/shard_1k.coh - align policy queue and shard fixture expectations with current namespace semantics.
- crates/sel4-runtime/src/lib.rs - add target-aware section annotation handling for macOS Mach-O compatibility.
- crates/sel4-sys/src/lib.rs - cfg-gate affinity invocation wrapper for kernels lacking affinity labels.
- docs/TEST_PLAN.md - normalize commands to `python3` and include `cargo test -p tests` plus `cargo test --workspace` gate coverage.
- docs/audit/findings.csv + docs/audit/BLOCKERS.md + docs/audit/checklists/RELEASE_EVIDENCE_CHECKLIST.md - update dispositions, closure evidence, and independent verification records.
Commands:
- cargo test -p tests --test shard_1k
- cargo test --workspace
- scripts/ci/check_test_plan.sh
- scripts/ci/due_diligence_gate.sh
Checks:
- DD-2026-0004, DD-2026-0005, DD-2026-0009, DD-2026-0006, DD-2026-0007, DD-2026-0011, and DD-2026-0012 have closure evidence and pass relevant gates.
- Due-diligence gate completes with no `P0/P1` blockers open.
Deliverables:
- Clean gate run logs and updated audit registers proving release-ready closure.
Milestone 25c — Python Orchestration SDK (1k Fleet Playbooks + Host Integrations)
Why now (adoption + operator scale): 1k-worker readiness is not only transport and gateway throughput; operators also need low-friction automation that plugs into existing Python tooling while preserving Cohesix control semantics and auditability.
Status: Complete - Python orchestration APIs, host integration adapters, playbook CLI, documentation updates, and local/G5g validation are complete.
Goal
Deliver a world-class Python SDK surface that:
- Keeps Cohesix non-authoritative protocol boundaries intact.
- Makes 1k-fleet operations simple to integrate from existing Python tooling and CI.
- Covers high-impact Mac, Jetson, and mixed-fleet use cases with auditable playbooks.
- Runs deterministically in local
.venvand Linux (G5g) environments.
Non-Goals (Explicit)
- No new in-VM listeners, transports, or protocol verbs.
- No bypass of role/ticket/policy gates.
- No behavior drift from
/queen/*/ctland/proc/*schemas documented indocs/INTERFACES.md. - No changes under
releases/in this milestone.
Deliverables
- Python orchestration core with typed schedule/lease/export/approval APIs mapped to existing control files.
- Environment-driven backend selection (
mock, mounted filesystem, REST gateway, TCP console) with deterministic precedence. - Host integration adapters for:
systemdservice state,- Docker container inventory,
- Kubernetes pod phase snapshots,
- NVML/NVIDIA GPU telemetry,
- PEFT/LoRA runtime package probes.
- Built-in high-impact playbooks covering:
- 1000 Mac: release factory, private PEFT grid, endpoint compliance.
- 1000 Jetson: traffic safety mesh, manufacturing safety + QA, critical infrastructure sensing.
- Mixed fleets: closed-loop AI factory, medical edge AI, logistics digital twin.
- Frictionless CLI entrypoint (
cohesix-playbook) plus example wrapper script. - Updated documentation in
tools/cohesix-py/README.mdanddocs/PYTHON_SUPPORT.md. - Added Python tests for orchestration APIs, integration adapters, and playbook flows.
Commands
source .venv/bin/activatepython -m pip install -e 'tools/cohesix-py[integrations,ml,dev]'python -m pytest tools/cohesix-py/tests -qpython -m cohesix.playbook_cli --listpython -m cohesix.playbook_cli --playbook mixed-closed-loop-ai-factory --dry-run --mockpython tools/cohesix-py/examples/use_case_playbook.py --playbook jetson-traffic-safety --dry-run --mock- Linux validation (G5g): run the same install/tests/playbook dry-run over SSH on the G5g host defined in
~/cohesix_dev.txt.
Checks (DoD)
- Python package installs cleanly into repo
.venv. - New tests pass with deterministic output in mock mode.
- Playbook CLI lists all built-in playbooks and executes dry-run reports without control writes.
- Live-compatible control writes remain bounded and map only to canonical control files.
- Host adapters degrade gracefully when optional host dependencies are unavailable.
- Linux validation on G5g passes with the same test suite and playbook dry-run commands.
Task Breakdown
Title/ID: m25c-python-orchestration-core
Goal: Add typed, bounded orchestration APIs for schedule/lease/export/approval workflows.
Inputs: tools/cohesix-py/cohesix/client.py, docs/INTERFACES.md.
Changes:
- tools/cohesix-py/cohesix/orchestration.py - typed request models, env backend discovery, /proc snapshot reads.
Commands:
- python -m pytest tools/cohesix-py/tests/test_orchestration.py -q
Checks:
- Control payloads are validated, bounded, and written only to canonical paths.
Deliverables:
- Orchestration API module with deterministic tests.
Title/ID: m25c-python-host-integrations
Goal: Integrate systemd, docker, k8s, NVML, and PEFT probes with graceful fallback behavior.
Inputs: docs/HOST_TOOLS.md, docs/PYTHON_SUPPORT.md.
Changes:
- tools/cohesix-py/cohesix/integrations.py - provider probes + NDJSON rendering for telemetry shipping.
- tools/cohesix-py/tests/test_integrations.py - probe fallback/parse tests.
Commands:
- python -m pytest tools/cohesix-py/tests/test_integrations.py -q
Checks:
- Missing dependencies are reported as skipped/degraded, not hard failures.
Deliverables:
- Provider adapter module and test coverage.
Title/ID: m25c-python-playbooks
Goal: Ship high-impact built-in playbooks for Mac, Jetson, and mixed 1k-fleet workflows.
Inputs: docs/USE_CASES.md, docs/PYTHON_SUPPORT.md.
Changes:
- tools/cohesix-py/cohesix/playbooks.py - playbook catalog + execution helpers.
- tools/cohesix-py/cohesix/playbook_cli.py - frictionless playbook CLI.
- tools/cohesix-py/examples/use_case_playbook.py - example wrapper.
- tools/cohesix-py/tests/test_playbooks.py - playbook catalog and execution tests.
Commands:
- python -m pytest tools/cohesix-py/tests/test_playbooks.py -q
- python -m cohesix.playbook_cli --list
Checks:
- All nine use-case playbooks are discoverable and dry-run capable.
Deliverables:
- Playbook SDK + CLI + tests.
Title/ID: m25c-python-docs-and-linux-validation
Goal: Document world-class Python UX and validate on local + G5g Linux.
Inputs: tools/cohesix-py/README.md, docs/PYTHON_SUPPORT.md, ~/cohesix_dev.txt.
Changes:
- tools/cohesix-py/README.md - install/CLI/playbook UX updates.
- docs/PYTHON_SUPPORT.md - orchestration + integration + playbook docs.
Commands:
- source .venv/bin/activate
- python -m pip install -e 'tools/cohesix-py[integrations,ml,dev]'
- python -m pytest tools/cohesix-py/tests -q
- ssh -i ~/.ssh/cohesix-cuda-builder.pem ubuntu@34.221.49.64 '<linux test commands>'
Checks:
- Local and G5g test runs both pass; docs match as-built behavior.
Deliverables:
- Updated docs + Linux validation evidence.
Milestone 25d — REST Request-Auth Parity Across Host Tools (Gateway Capability Max)
Why now (gateway readiness at 1k scale): hive-gateway now enforces request-auth at the REST edge for mutating paths. Any host tool that can route through REST must attach request-auth consistently or it becomes a brittle outlier in multi-tool, high-concurrency deployments.
Status: Reopened for m25d-fuse-owner-mount-restoration, discovered during the Milestone 26e release burn-in. Existing request-auth, namespace, and TCP authentication contracts remain in force; restoration is limited to the incompatible FUSE startup options, macFUSE mount API selection, and their native host validation.
Goal
Deliver request-auth parity across all REST-capable host tools so gateway mode is predictable, secure, and low-friction:
- Standardize token resolution order (CLI override + canonical env fallbacks).
- Attach request-auth headers from every REST-capable host client path (including parallel fan-out paths).
- Preserve single-console architecture (
hive-gatewayremains the only TCP console client in multiplexed mode). - Keep docs aligned with as-built CLI/env behavior.
Non-Goals (Explicit)
- No new REST routes, RPC semantics, or control-plane verbs.
- No changes to in-VM console grammar (
ACK/ERR/END) or NineDoor behavior. - No changes to ticket authorization semantics.
- No changes under
releases/in this milestone.
Implementation Touchpoints
apps/coh/src/main.rs,apps/coh/src/rest.rs- add REST request-auth token CLI/env resolution and attach headers for all REST access paths.apps/coh/src/mount.rs- ensure FUSE mount is a faithful projection ofLS/CAT/ECHOsemantics (non-zero file sizes, append-only offset discipline, and limited dynamic telemetry roots aligned with Milestone 21a).apps/root-task/src/net/mod.rs,apps/root-task/src/net/console_srv.rs- adjust TCP console unauthenticated auth deadlines to support remote tunnel usage without changing console grammar.apps/cas-tool/src/main.rs- add REST request-auth support for CAS uploads through gateway.apps/gpu-bridge-host/src/main.rs- add REST request-auth support for/gpu/bridge/ctlpublish mode.apps/swarmui/src-tauri/main.rs,apps/swarmui/src/lib.rs,apps/swarmui/src/hive.rs- propagate request-auth token through REST transport bootstrap and parallel telemetry/status polling paths.docs/HOST_TOOLS.md,docs/USERLAND_AND_CLI.md- document canonical REST request-auth flags/env fallbacks for host operators.
Commands
cargo test -p cohcargo test -p cas-toolcargo test -p gpu-bridge-hostcargo test -p swarmuicargo check -p swarmui
Checks (DoD)
- All REST-capable host tools attach request-auth when provided via CLI/env.
- No REST-capable host tool requires ad-hoc or undocumented env variables.
- SwarmUI REST parallel fan-out paths (status + telemetry) preserve request-auth headers.
- Gateway-mode docs list the exact token flags/env keys operators must set.
- Existing TCP/mock flows remain unchanged.
Task Breakdown
Title/ID: m25d-fuse-owner-mount-restoration
Milestone: Reopened Milestone 25d — REST Request-Auth Parity Across Host Tools / owner-only FUSE startup restoration; discovered under Milestone 26e / m26e-host-integration-dependency-contract
Goal: Restore native Mac and Linux FUSE startup without broadening host access or changing Cohesix namespace authority.
Inputs: apps/coh/src/mount.rs, fuser 0.18.0 owner-access contract, the exact Pi GENET burn-in image, MacFUSE 5.3.3, Linux FUSE, and retained failed mount evidence.
Changes:
- apps/coh/src/mount.rs — retain explicit Owner access and ordinary session cleanup, remove the incompatible AutoUnmount option, preserve the private-mount invariant in a focused regression, and use uncached reads so a zero-length metadata fallback cannot conceal live content or a backend refusal.
- Cargo.toml, apps/coh/Cargo.toml, Cargo.lock, third_party/fuser — pin the unchanged fuser 0.18.0 runtime with a documented build-script patch selecting its existing libfuse3 adapter on macOS; preserve the macFUSE protocol ABI and default Linux mount implementation.
- tools/rust-risk-audit/src/main.rs and docs/audit/rust_risk_baseline.toml — seal the exact vendored dependency tree, reject drift and path redirection, and preserve every first-party risk ceiling.
- docs/HOST_TOOLS.md — document host-user privacy, the macFUSE 5 library requirement, and normal/disconnected-mount cleanup.
- Compatibility review: all coh mount backends share the corrected configuration. cohsh, hive-gateway, gpu-bridge-host, host-sidecar-bridge, host-ticket-agent, cas-tool, SwarmUI, tools/cohesix-py, and performance benchmark scripts keep their existing wire, policy, namespace, request-auth, and evidence contracts; no changes are required on those surfaces.
Commands:
- cargo test --locked -p coh --features fuse
- cargo clippy --locked -p coh --features fuse --all-targets -- -D warnings
- cargo build --locked --release -p coh --features fuse,nvml
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
Checks: focused host tests and exact native builds pass; both real host mounts read the Pi-backed namespace and unmount cleanly while owner-only access is retained. Failed pre-repair evidence remains distinct from the repaired diagnostic candidate and timed run.
Deliverables: bounded FUSE repair, native Mac/Linux command and mount evidence, and compatibility review. Broader release qualification is unchanged.
Title/ID: m25d-rest-auth-parity-host-tools
Goal: Ensure every REST-capable host tool resolves and attaches gateway request-auth headers.
Inputs: apps/coh/src/main.rs, apps/coh/src/rest.rs, apps/cas-tool/src/main.rs, apps/gpu-bridge-host/src/main.rs.
Changes:
- apps/coh/src/main.rs, apps/coh/src/rest.rs - add `--rest-auth-token` support and env fallback resolution for REST mode.
- apps/cas-tool/src/main.rs - add `--rest-auth-token` and env fallbacks for REST upload mode.
- apps/gpu-bridge-host/src/main.rs - add `--rest-auth-token` and env fallbacks for REST publish mode.
Commands:
- cargo test -p coh
- cargo test -p cas-tool
- cargo test -p gpu-bridge-host
Checks:
- REST clients instantiate `GatewayClient` with request-auth when configured.
Deliverables:
- Host-tool REST request-auth parity with deterministic fallback order.
Title/ID: m25d-swarmui-rest-auth-fanout
Goal: Propagate request-auth through SwarmUI REST boot and parallel fan-out reads/tails.
Inputs: apps/swarmui/src-tauri/main.rs, apps/swarmui/src/lib.rs, apps/swarmui/src/hive.rs.
Changes:
- apps/swarmui/src-tauri/main.rs - resolve `SWARMUI_REST_AUTH_TOKEN` + canonical gateway env fallbacks.
- apps/swarmui/src/lib.rs - carry request-auth token in REST parallel config and pass to all spawned transports.
- apps/swarmui/src/hive.rs - attach request-auth token in parallel telemetry tail workers.
Commands:
- cargo test -p swarmui
- cargo check -p swarmui
Checks:
- No SwarmUI REST code path creates `CohshRestTransport` without request-auth propagation.
Deliverables:
- SwarmUI REST transport parity with gateway auth policy.
Title/ID: m25d-docs-as-built-rest-auth
Goal: Keep operator docs fully aligned with REST auth semantics after parity fixes.
Inputs: docs/HOST_TOOLS.md, docs/USERLAND_AND_CLI.md.
Changes:
- docs/HOST_TOOLS.md - document per-tool `--rest-auth-token` and env fallback behavior.
- docs/USERLAND_AND_CLI.md - reflect gateway request-auth requirements for `coh` and `swarmui` REST mode.
Commands:
- scripts/ci/check_test_plan.sh
Checks:
- Docs match shipped tool flags and env keys exactly.
Deliverables:
- Updated host-tool operator guidance with no auth ambiguity.
Title/ID: m25d-coh-mount-rest-writable-and-bidir
Goal: Make `coh mount --rest-url` reliably readable/writable and suitable for safe bidirectional telemetry transfer (Milestone 21a semantics).
Inputs: apps/coh/src/mount.rs, apps/coh/src/main.rs, apps/coh/src/rest.rs, docs/OPERATOR_WALKTHROUGH.md, docs/TEST_PLAN.md.
Changes:
- apps/coh/src/mount.rs - fix FUSE file attrs (non-zero file sizes), ensure `readdir` reports accurate directory vs file types (macOS uses the type eagerly), eliminate write-only “ghost” entries, allow host-side appends by avoiding POSIX-perm EPERM (kernel-level checks), and support limited dynamic telemetry roots under `coh.telemetry.root` without introducing generic POSIX create semantics.
- apps/coh/src/main.rs, apps/coh/src/rest.rs - ensure REST request-auth token is accepted and attached for mount-backed `ECHO` paths so gateway mode stays writable when request-auth is enforced.
- docs/OPERATOR_WALKTHROUGH.md - document FUSE mount prerequisites and a bidirectional telemetry transfer smoke using supported MIME types.
- docs/TEST_PLAN.md - add a gateway-mode mount regression: REST mount can `cat` `/proc/*` and append to `/queen/telemetry/<device>/ctl` with request-auth enabled.
Commands:
- cargo test -p coh
Checks:
- REST mount `cat` shows non-empty content for bounded files like `/proc/lifecycle/state` and `/log/queen.log`.
- REST mount can create a new telemetry device root by addressing `${coh.telemetry.root}/<device>/ctl`, then append records into the OS-named segment, and another host can read them via mount.
- macOS REST mounts can append to `/queen/telemetry/<device>/ctl` without local EPERM/permission denials (errors must come from Cohesix bounds/policy, not host file mode bits).
- No new generic create/mkdir/unlink/rename semantics are introduced; dynamic behavior is strictly scoped to telemetry ingest roots and remains OS-owned.
Deliverables:
- Writable, bounded REST mount suitable for multi-host gateway ops with deterministic, policy-aligned behavior.
Title/ID: m25d-console-auth-timeout-remote-tcp-mount
Goal: Make remote TCP console attachments (and `coh mount --host/--port`) reliable over SSH tunnels/high-latency links without changing console grammar.
Inputs: apps/root-task/src/net/mod.rs, apps/root-task/src/net/console_srv.rs, apps/cohsh/src/transport/tcp.rs, docs/HOST_TOOLS.md, docs/OPERATOR_WALKTHROUGH.md.
Changes:
- apps/root-task/src/net/mod.rs, apps/root-task/src/net/console_srv.rs - increase unauthenticated auth deadline (or implement a bounded auth window) so a client can deliver its token over WAN latency.
- apps/cohsh/src/transport/tcp.rs - keep client-side retry/backoff bounded and emit a crisp error that points operators at gateway mode when auth times out.
- docs/HOST_TOOLS.md, docs/OPERATOR_WALKTHROUGH.md - document that REST via `hive-gateway` is the default for remote multi-host ops; TCP console is best-effort over WAN until this is fixed.
Commands:
- scripts/cohesix-build-run.sh --transport tcp --tcp-port 31337
- (remote) cohsh/coh attach or mount over an SSH reverse tunnel
Checks:
- g5g (AWS) can attach/mount over a reverse tunnel without `authentication timed out waiting for server response`.
Deliverables:
- Remote-safe TCP auth window with unchanged console wire grammar and updated operator guidance.
Title/ID: m25d-macos-coh-fuse-default
Goal: Ship macOS `coh` builds with FUSE enabled so operators can use `coh mount` once MacFUSE is installed/approved.
Inputs: scripts/cohesix-build-run.sh, docs/HOST_TOOLS.md, docs/OPERATOR_WALKTHROUGH.md, docs/TEST_PLAN.md.
Changes:
- scripts/cohesix-build-run.sh - build `coh` with `--features fuse` on macOS hosts.
- docs/HOST_TOOLS.md, docs/OPERATOR_WALKTHROUGH.md, docs/TEST_PLAN.md - document MacFUSE prerequisites (`/dev/macfuse0`) and keep examples as-built.
Commands:
- cargo build -p coh --release --features fuse
Checks:
- macOS `coh mount` no longer reports “fuse support disabled”.
Deliverables:
- macOS-ready `coh mount` binary and aligned operator docs.
Release 0.8.0 alpha —-
Milestone 25e — Evidence Packs + Integration Kits (Audit-First Adoption)
Why now (buyability + integration): Cohesix has a scale-capable, request-authenticated gateway path (25b–25d) and Python orchestration (25c). The highest leverage remaining adoption blocker is not new VM semantics; it is the absence of deterministic, auditor-friendly evidence artifacts and turnkey integration patterns that reuse existing control surfaces without introducing new protocols.
Status: Reopened for m25e-evidence-timeline-error-records, m25e-evidence-export-failure-retention and the separately user-authorized m25e-session-evidence-byte-budget, discovered during the Milestone 26e release burn-in. Timeline restoration accepts emitted structured errors while retaining the existing output schema. Export restoration restores partial-summary retention, nonzero capture failures and existing bounded CAT framing for long AuditFS JSON. The budget task raises the finite default session allowance to 8 MiB for full evidence capture and shared operator traffic. Per-read bounds, retained-log coverage, redaction, rate/cursor limits and transport contracts remain unchanged.
Goal
Deliver high-impact, low-risk adoption accelerators that remain host-side and strictly protocol-faithful:
- Deterministic evidence packs for audits, due diligence, and incident review, sourced only from existing
/proc,/log,/audit,/replay, and telemetry surfaces. - A correlated timeline view derived from evidence pack contents (no new runtime behavior).
- Turnkey integration kits (CI + SIEM) that consume the REST/OpenAPI gateway and/or
coh/Python tooling without introducing new control-plane semantics. - GPU lease receipts and chargeback-friendly exports derived from
/proc/lease/*,/audit/journal, and/gpu/*status files (no changes to lease enforcement).
Non-Goals (Explicit)
- No new in-VM listeners, protocols, transports, or control verbs.
- No changes to ACK/ERR/END grammar, NineDoor error semantics, or Secure9P bounds.
- No device identity enrollment or attestation work (covered by Milestone 26 and Milestone 27
coh attest). - No changes under
releases/in this milestone.
Implementation Touchpoints
apps/coh/src/main.rs+apps/coh/src/lib.rs— add evidence subcommands and shared helpers.apps/coh/src/telemetry.rs— reuse bounded telemetry pull implementation inside evidence packs.crates/cohesix-rest/src/lib.rs+apps/hive-gateway— consumeGET /v1/meta/boundsand REST file projections for evidence reads.apps/nine-door/src/host/audit.rs+apps/root-task/src/ninedoor.rs— ensure evidence pack includes/audit/exportand correlatable audit journal entries (read-only).docs/HOST_TOOLS.md,docs/HOST_API.md,docs/OPERATOR_WALKTHROUGH.md— document evidence pack CLI and integration recipes.
Commands
cargo test -p cohcargo test -p hive-gatewaypython -m pytest tools/cohesix-py/tests -q
Checks (Definition of Done)
coh evidence packsucceeds in--mockmode and in REST gateway mode with request-auth enabled, emitting a deterministic directory structure underout/evidence/<id>/.- Evidence packs contain: manifest/policy fingerprint, bounds snapshot,
/procsnapshots,/replay/status, a bounded/log/queen.logcapture, and (optionally) downloaded telemetry segments. When/audit/exportis present, packs include/audit/exportplus redacted/audit/journaland/audit/decisions. coh evidence timelineproduces stable, correlated output from an evidence pack without network access.- GPU lease receipts can be emitted from
coh gpu lease/coh runwithout changing VM control semantics, and include correlatable identifiers (lease id,subject,resource,seq) captured from/proc/lease/*. - Integration kits run in mock mode end-to-end and contain no hardcoded secrets; all tokens/URLs are supplied via env vars.
Task Breakdown
Title/ID: m25e-session-evidence-byte-budget
Milestone: Milestone 25e — Evidence Packs + Integration Kits; discovered in Milestone 26e release burn-in
Goal: Make a full retained-log evidence capture usable with ordinary shared operator traffic under a finite default session allowance.
Inputs: Fresh-session Queen-log ELIMIT from exact Pi image c07fdd9c7ba3; explicit user instruction to increase the default byte budget.
Changes:
- configs/root_task*.toml and tools/coh-rtc/src/ir.rs — set the default and manifest ceiling to 8388608 bytes (8 MiB); retain explicit smaller ticket quotas.
- coh-rtc outputs, selected native host profiles and installed Python wheel — regenerate all affected fingerprints and projected defaults.
- docs/SECURITY.md, docs/HOST_TOOLS.md and docs/OPERATOR_RECIPES.md — explain sizing, cumulative shared-session accounting and unchanged per-request/resource limits.
Commands: cargo test -p coh-rtc; scripts/check-generated.sh; scripts/ci/check_test_plan.sh; native host builds; fresh exact-image Pi raw entry and full evidence export.
Checks: 8 MiB is finite and exceeds three worst-case retained logs plus 2 MiB operator traffic; smaller explicit ticket values survive parsing and existing quota refusal tests still pass. No rate, cursor, payload, role or namespace limit increases.
Deliverables: regenerated contracts, configuration regression, native build identities, new frozen burn-in profile and live export evidence. No UEFI activation or release acceptance claim.
Title/ID: m25e-evidence-timeline-error-records
Milestone: Reopened Milestone 25e — Evidence Packs + Integration Kits; discovered during Milestone 26e release burn-in maintenance revalidation
Goal: Export a usable incident timeline when AuditFS includes correctly refused operations.
Inputs: The captured Pi maintenance case contains error={code:Permission,message:EPERM}; the existing timeline reader only accepted string errors and rejected the pack.
Changes:
- apps/coh/src/evidence_timeline.rs — accept canonical structured errors and legacy strings; normalize objects to the unchanged timeline-v1 error string while retaining the original pack.
- apps/coh/tests/evidence_timeline.rs — verify structured, legacy and null errors, retained refusal outcomes, and deterministic rejection of malformed objects.
- docs/HOST_TOOLS.md — document input compatibility and unchanged timeline output.
Commands:
- cargo test -p coh --test evidence_timeline
- cargo build --release -p coh --features fuse,nvml
- coh evidence timeline --input <captured-maintenance-case>
Checks: Native Mac and Linux readers consume the unchanged captured case, preserve all refusal events, and keep malformed input failing. The installed Python CI/SIEM consumers validate that same case without another target workload. All required repository checks pass before merge.
Compatibility review: Reviewed cohsh, coh, Hive Gateway/REST, gpu-bridge-host, host-ticket-agent, host-sidecar-bridge, cas-tool, SwarmUI, cohesix-py, and raw/REST benchmark scripts. Only coh timeline and its documentation need changes; Python SIEM already preserves object-valued errors, and the library/CI consumer parse JSON generically. Target producers, generated contracts, timeline schema, other binaries, SDK wheel, benchmark inputs and report schemas remain unchanged. No Pi rebuild or full burn-in rerun is needed for this host-only reader repair.
Deliverables: Bounded compatibility repair, focused tests, two native readers and offline validation of the original captured failure evidence.
Title/ID: m25e-evidence-export-failure-retention
Milestone: Milestone 25e — Evidence Packs + Integration Kits; discovered in Milestone 26e release burn-in
Goal: Preserve failed exports truthfully and restore bounded reads of legitimate long AuditFS records.
Inputs: Pi GENET image from commit 15923ebbfe8f, timed-01 Queen-log ELIMIT refusal, fresh-session audit-journal buffer-full result with prior exit code zero.
Changes:
- apps/coh/src/evidence.rs — seal partial summaries on capture failure; return an error for retained capture errors; use a positive REST read bound to verify empty audit streams.
- apps/root-task/src/ninedoor.rs — serialize AuditFS journal/decision records with the existing C1 framing, preserving line and stream bounds.
- apps/coh/tests/evidence_pack.rs — assert required-read stop and optional-read error retention independently of target scheduling.
- docs/OPERATOR_RECIPES.md and docs/HOST_TOOLS.md — describe nonzero failure, partial case inspection and unchanged quota boundaries.
Commands: cargo test --locked --release -p coh --features fuse --test evidence_pack; cargo build --locked --release -p coh --features fuse,nvml
Checks: both native builds preserve refusal detail and partial summary, return nonzero on capture errors, and retain exact successful-export contents and redaction.
Deliverables: native host evidence, focused AuditFS serialization regression, fresh exact-image Pi export and first-failure cases; no manifest, ticket quota, public framing or release acceptance changes.
Title/ID: m25e-coh-evidence-pack
Goal: Add a deterministic evidence pack exporter that captures bounded, auditor-friendly system state without new semantics.
Inputs: apps/coh/src/main.rs, apps/coh/src/lib.rs, apps/coh/src/telemetry.rs, crates/cohesix-rest/src/lib.rs, docs/INTERFACES.md.
Changes:
- apps/coh/src/main.rs - add `coh evidence pack` subcommand (supports `--mock`, `--rest-url`, and TCP console flows).
- apps/coh/src/lib.rs + apps/coh/src/evidence.rs - implement bounded evidence reads for canonical nodes (`/proc/*`, `/log/queen.log`, `/audit/*`, `/replay/*`, `/proc/lease/*`, `/proc/schedule/*`).
- apps/coh/src/evidence.rs - include manifest fingerprint + gateway bounds snapshot (`GET /v1/meta/bounds`) to bind evidence packs to a concrete as-built contract.
- apps/coh/src/evidence.rs - optionally reuse `telemetry::pull` to download telemetry segments into the pack under manifest bounds.
- docs/HOST_TOOLS.md + docs/OPERATOR_WALKTHROUGH.md - document evidence pack usage and output layout.
Commands:
- cargo test -p coh
- cargo run -p coh -- --mock evidence pack --out out/evidence/mock
Checks:
- Pack includes all required nodes and never reads past manifest-bounded byte caps.
- Pack output is stable for identical inputs (deterministic file names + ordering).
Deliverables:
- `coh evidence pack` implementation + docs.
Title/ID: m25e-coh-evidence-timeline
Goal: Produce a correlated timeline view from evidence packs for incident review and audit traceability.
Inputs: apps/coh/src/evidence.rs (from m25e-coh-evidence-pack), apps/nine-door/src/host/audit.rs (journal format reference), docs/audit/CONTROL_TRACEABILITY.md.
Changes:
- apps/coh/src/main.rs - add `coh evidence timeline --in <pack-dir>` that emits `timeline.ndjson` and `timeline.md`.
- apps/coh/src/evidence_timeline.rs - parse `/audit/journal` JSONL + `/audit/decisions`, correlate with `/proc/lease/*` snapshots and `seq` fields, and emit stable, bounded output.
- apps/coh/tests/evidence_timeline.rs - add fixture-driven tests ensuring stable ordering and robust handling of partial packs.
Commands:
- cargo test -p coh
Checks:
- Timeline output is deterministic for a fixed evidence pack and does not require network access.
Deliverables:
- Timeline generator suitable for postmortems and due diligence artifacts.
Title/ID: m25e-integration-kits-ci-siem
Goal: Ship turnkey, protocol-faithful integration kits that reduce adoption friction in CI and SIEM pipelines.
Inputs: docs/HOST_API.md (OpenAPI), docs/HOST_TOOLS.md, tools/cohesix-py.
Changes:
- docs/HOST_TOOLS.md - add a dedicated section: CI usage (generate evidence pack, upload artifacts) and SIEM export patterns (audit journal + decisions + lease snapshots).
- tools/cohesix-py/examples/ci_evidence_pack.py - run `coh evidence pack` (or REST equivalents) in mock/dry-run, validate output layout, emit a machine-readable summary JSON.
- tools/cohesix-py/examples/siem_export_ndjson.py - read an evidence pack and emit normalized NDJSON suitable for Splunk/Elastic ingestion (no network by default; optional `--post` with env-configured URL/token).
- tools/cohesix-py/tests/test_examples_ci_siem.py - ensure examples run deterministically in mock mode and never require external connectivity.
Commands:
- python -m pytest tools/cohesix-py/tests -q
Checks:
- Examples run in mock mode on macOS and produce stable outputs with no secrets in logs.
Deliverables:
- Integration kits that demonstrate “buyable” workflows without new control semantics.
Title/ID: m25e-gpu-lease-receipts
Goal: Add receipt-backed GPU leasing outputs for audit and chargeback without changing lease enforcement.
Inputs: apps/coh/src/gpu.rs, apps/coh/src/run.rs, docs/INTERFACES.md.
Changes:
- apps/coh/src/gpu.rs - add optional `--receipt-out` that writes a JSON receipt including request parameters, ACK line, and a bounded `/proc/lease/*` snapshot captured immediately after the lease request.
- apps/coh/src/run.rs - extend host command wrapper to emit receipts for lease-validated runs (breadcrumb correlation).
- apps/coh/tests/receipts.rs - validate receipt schema, bounds, and determinism.
Commands:
- cargo test -p coh
Checks:
- Receipts never include secrets (tokens, raw tickets) and are stable for fixed inputs.
Deliverables:
- Receipt artifacts suitable for audit and internal billing pipelines.
Milestone 25f — Gateway Broker Refactor + Large Telemetry Reference Manifests (No-Retry Reliability Gate)
Why now (beta reliability + telemetry realism): Strict no-retry gateway runs still surface backpressure and timeout failures under accelerated mixed control/telemetry load. The gateway currently multiplexes logical pool sessions over one locked TCP transport, and current harness coverage does not explicitly pressure MB/GB telemetry scenarios. This milestone addresses the root cause while preserving Cohesix red lines and single-console architecture.
Goal
Deliver a Cohesix-aligned reliability and scale step that:
- Replaces lock-contention request handling in
hive-gatewaywith a bounded broker model (single wire owner, concurrent REST callers). - Allows many chunk references per telemetry manifest so MB/GB-class host artifacts can be represented without turning telemetry ingest into generic file transfer.
- Expands the performance harness to explicit
1 MB,10 MB,100 MB, and1 GBgateway scenarios with--no-retries, fast ramp, and strict error-budget gating.
Non-Goals (Explicit)
- No new in-VM TCP listeners, RPC channels, or ad-hoc host/VM protocols.
- No change to ACK/ERR/END grammar, NineDoor error semantics, or Secure9P red lines (
msize <= 8192, walk depth <= 8). - No generic POSIX create/upload semantics under telemetry paths; segment naming/retention remains OS-owned and bounded.
- No hidden retry paths in benchmark mode; failures must remain visible and count against pass/fail.
Implementation Touchpoints
apps/hive-gateway/src/main.rs- brokerized request scheduler/dispatcher, bounded queueing, fairness between control and telemetry classes, and queue/backpressure observability.apps/cohsh/src/transport/tcp.rs,apps/cohsh/src/session_pool.rs- align transport/session abstractions with gateway broker ownership (single wire writer, no concurrent socket mutation).tools/coh-rtc/src/ir.rs,configs/root_task.toml, generated policy artifacts - introduce bounded telemetry reference-manifest limits (count/bytes) as manifest-driven controls.apps/nine-door/src/host/telemetry.rs,apps/root-task/src/ninedoor.rs- validate and enforce reference-manifest envelopes and quotas deterministically.apps/cohsh/src/lib.rs,apps/coh/src/telemetry.rs,tools/cohesix-py- support telemetry push/pull workflows that emit and consume chunk-reference manifests under manifest limits.scripts/rest_perf_harness.py,tests/test_rest_perf_harness.py- add explicit large-size scenario matrix, no-retry mode, fast-ramp presets, and strict error-budget exit behavior.docs/INTERFACES.md,docs/HOST_TOOLS.md,docs/TEST_PLAN.md- document as-built manifest-reference envelope semantics and benchmark gates.
Commands
cargo test -p hive-gatewaycargo test -p cohshcargo test -p nine-doorcargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json.venv/bin/python -m pytest -q tests/test_rest_perf_harness.pypython scripts/rest_perf_harness.py --mode simulate --rest-url http://127.0.0.1:8080 --no-retries --fast-ramp --scenario telemetry-1mb --error-budget-rate 0.01python scripts/rest_perf_harness.py --mode simulate --rest-url http://127.0.0.1:8080 --no-retries --fast-ramp --scenario telemetry-10mb --error-budget-rate 0.01python scripts/rest_perf_harness.py --mode simulate --rest-url http://127.0.0.1:8080 --no-retries --fast-ramp --scenario telemetry-100mb --error-budget-rate 0.01python scripts/rest_perf_harness.py --mode simulate --rest-url http://127.0.0.1:8080 --no-retries --fast-ramp --scenario telemetry-1gb --error-budget-rate 0.01
Checks (Definition of Done)
- Gateway REST handlers use a bounded broker queue/dispatcher instead of per-request lock contention on shared transport state; control-path latency remains protected under telemetry pressure.
- Backpressure is explicit and deterministic (
429/ gateway backpressure path), with queue depth and timeout counters exposed in status telemetry. - Telemetry reference manifests accept many bounded chunk references per segment (manifest-driven limits), reject malformed/oversized entries deterministically, and never relax existing per-record Secure9P bounds.
- Large-file scenarios (
1 MB,10 MB,100 MB,1 GB) run through gateway mode with--no-retriesand fast ramp; heavy-ish beta gate iserror_rate <= 1.0%(--error-budget-rate 0.01) and harness exits non-zero on violation. docs/TEST_PLAN.mdincludes mandatory commands and pass criteria for all four scenarios (no skip path).
Task Breakdown
Title/ID: m25f-gateway-broker-refactor
Goal: Replace lock-contention transport access with a bounded broker model while preserving single-console wire ownership.
Inputs: apps/hive-gateway/src/main.rs, apps/cohsh/src/session_pool.rs, apps/cohsh/src/transport/tcp.rs, docs/HOST_TOOLS.md.
Changes:
- apps/hive-gateway/src/main.rs - add broker request queues (control + telemetry), deterministic scheduling/fairness, and queue-aware backpressure responses.
- apps/hive-gateway/src/main.rs - keep `hive-gateway` as sole console client; remove direct per-request competition on shared transport mutex.
- apps/cohsh/src/session_pool.rs, apps/cohsh/src/transport/tcp.rs - align lease/session lifecycle with broker ownership and bounded shutdown/reconnect behavior.
Commands:
- cargo test -p hive-gateway
- cargo test -p cohsh
Checks:
- Under concurrent REST load, checkout timeout/backpressure rates fall materially from baseline and control-plane operations remain serviceable.
Deliverables:
- Brokerized gateway transport path with deterministic backpressure telemetry.
Title/ID: m25f-telemetry-manifest-chunk-references
Goal: Support MB/GB telemetry artifacts via many bounded chunk references rather than bulk inline payload transfer.
Inputs: tools/coh-rtc/src/ir.rs, configs/root_task.toml, apps/nine-door/src/host/telemetry.rs, apps/root-task/src/ninedoor.rs, docs/INTERFACES.md.
Changes:
- tools/coh-rtc/src/ir.rs + configs/root_task.toml - add manifest-driven limits for telemetry reference manifests (max refs, max manifest bytes, max referenced bytes scope as required).
- apps/nine-door/src/host/telemetry.rs + apps/root-task/src/ninedoor.rs - enforce deterministic validation for reference-manifest envelopes and bounded append semantics.
- apps/cohsh/src/lib.rs + apps/coh/src/telemetry.rs - add/extend host tooling for emitting reference manifests and resolving latest segment IDs without new control verbs.
- docs/INTERFACES.md - document reference-manifest schema and limits as-built.
Commands:
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- cargo test -p nine-door
- cargo test -p cohsh
Checks:
- Valid manifests append successfully; malformed and over-limit manifests fail with deterministic ERR details.
Deliverables:
- Manifest-reference telemetry ingest path suitable for real-world artifact sizes while preserving Cohesix control-plane boundaries.
Title/ID: m25f-harness-large-scenarios-no-retry
Goal: Make gateway reliability regressions visible with explicit no-retry large-size scenario gates.
Inputs: scripts/rest_perf_harness.py, tests/test_rest_perf_harness.py, docs/TEST_PLAN.md.
Changes:
- scripts/rest_perf_harness.py - add explicit scenario presets (`telemetry-1mb`, `telemetry-10mb`, `telemetry-100mb`, `telemetry-1gb`) routed through gateway paths.
- scripts/rest_perf_harness.py - enforce `--no-retries` mode, fast-ramp controls, and strict `--error-budget-rate` pass/fail behavior.
- tests/test_rest_perf_harness.py - cover scenario wiring, no-retry semantics, and error-budget failure behavior.
- docs/TEST_PLAN.md - add canonical commands and required outputs for all four scenarios.
Commands:
- .venv/bin/python -m pytest -q tests/test_rest_perf_harness.py
- python scripts/rest_perf_harness.py --mode simulate --rest-url http://127.0.0.1:8080 --no-retries --fast-ramp --scenario telemetry-1mb --error-budget-rate 0.01
- python scripts/rest_perf_harness.py --mode simulate --rest-url http://127.0.0.1:8080 --no-retries --fast-ramp --scenario telemetry-10mb --error-budget-rate 0.01
- python scripts/rest_perf_harness.py --mode simulate --rest-url http://127.0.0.1:8080 --no-retries --fast-ramp --scenario telemetry-100mb --error-budget-rate 0.01
- python scripts/rest_perf_harness.py --mode simulate --rest-url http://127.0.0.1:8080 --no-retries --fast-ramp --scenario telemetry-1gb --error-budget-rate 0.01
Checks:
- Each scenario emits deterministic summary artifacts and fails hard (exit code non-zero) when error rate exceeds budget.
Deliverables:
- A repeatable large-object gateway reliability gate with no hidden retries.
Title/ID: m25f-docs-sync-and-operator-guidance
Goal: Keep docs-as-built alignment for broker behavior, large telemetry references, and no-retry gates.
Inputs: docs/INTERFACES.md, docs/HOST_TOOLS.md, docs/TEST_PLAN.md, docs/ARCHITECTURE.md.
Changes:
- docs/INTERFACES.md - describe telemetry reference-manifest envelopes and manifest-driven limits.
- docs/HOST_TOOLS.md - document gateway broker behavior, expected backpressure signals, and operator tuning knobs.
- docs/TEST_PLAN.md - codify the mandatory 1MB/10MB/100MB/1GB no-retry fast-ramp matrix and pass/fail policy.
- docs/ARCHITECTURE.md - update transport implementation notes to reflect brokerized gateway path while preserving single-console architecture.
Commands:
- scripts/ci/check_test_plan.sh
Checks:
- Documentation matches implemented flags, limits, and failure semantics exactly.
Deliverables:
- Canonical operator and test documentation for Milestone 25f.
Milestone 25g — Host Control Tickets via FUSE (GPU/PEFT + systemd/docker + K8s Coexistence)
Why now (high-value orchestration): Cohesix already has bounded control surfaces for /gpu/*, /host/*, policy gates, and evidence packs, but host actions still require tool-specific flows. The highest-leverage next step is a unified, auditable host execution queue where Queen emits bounded JSON control tickets and host executors consume them through mounted file views without adding new protocols.
Goal
Deliver a deterministic, policy-gated host control-ticket plane that:
- Defines a manifest-driven ticket contract with idempotency and lifecycle states.
- Adds a host ticket agent that watches mounted ticket files and executes bounded adapters.
- Prioritizes high-value adapters: GPU lease/PEFT lifecycle, systemd remediation, Docker remediation, and Kubernetes coexistence translation.
- Extends evidence/replay so every ticket decision is traceable and reproducible.
Non-Goals (Explicit)
- No new in-VM TCP listeners, RPC channels, or host/VM sideband protocols.
- No change to ACK/ERR/END grammar, NineDoor error semantics, or Secure9P bounds.
- No in-VM CUDA/NVML, no in-VM container runtime, and no bypass of role/ticket authorization.
- No unbounded queueing, retries, or background mutation loops.
Design Principles (Normative)
- Spec/status split - ticket requests and ticket outcomes are append-only, separate streams.
- At-least-once + idempotency - executors may re-read; outcomes are deduplicated by
id+idempotency_key. - Policy-first execution - Queen gating and ticket scopes remain authoritative before host side effects.
- Replayability - ticket state transitions are deterministic and captured by existing audit/evidence paths.
Implementation Touchpoints
tools/coh-rtc/src/ir.rs,configs/root_task.toml, generated artifacts - emit ticket schema/bounds (host-ticket/v1) and allowlisted action kinds.apps/nine-door/src/host/*,apps/root-task/src/ninedoor.rs- expose bounded ticket files under/host/tickets/*with append-only semantics.apps/host-ticket-agent/*(new host tool) - watch mounted ticket streams, claim work, execute adapters, and append status receipts.apps/gpu-bridge-host/*,apps/coh/src/peft/*- GPU/PEFT ticket executors.apps/host-sidecar-bridge/*- systemd/docker/K8s adapter execution and status projection.tools/cohesix-py/*- optional RBAC-to-ticket translation helpers for Kubernetes coexistence workflows.docs/INTERFACES.md,docs/HOST_TOOLS.md,docs/USERLAND_AND_CLI.md,docs/USE_CASES.md,docs/TEST_PLAN.md,docs/ARCHITECTURE.md- docs-as-built and operator/test alignment.
Commands
cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsonscripts/check-generated.shcargo test -p nine-doorcargo test -p host-sidecar-bridgecargo test -p gpu-bridge-hostcargo test -p coh --features mockcargo test -p tests --test shard_1kpython3 -m pytest tools/cohesix-py/tests -qscripts/ci/check_test_plan.sh
Checks (Definition of Done)
- Ticket namespace is manifest-gated and bounded, with deterministic state transitions:
queued->claimed->running->succeeded|failed|expired.
- Host ticket agent executes only allowlisted actions and writes bounded status receipts without leaking auth tokens or raw signing secrets.
- GPU/PEFT tickets drive
lease,import,activate, androllbackflows using existing/gpu/*and/queen/export/*semantics. - systemd/docker tickets perform bounded remediation (restart/stop/status verify) through host adapters and emit correlatable outcomes.
- Kubernetes coexistence flow translates RBAC-scoped intents into Cohesix tickets without introducing alternative control-plane semantics.
- Evidence packs and timeline tooling include ticket request/outcome correlation so incident replay and chargeback are deterministic.
docs/TEST_PLAN.mdincludes mandatory ticket-flow runs (GPU/PEFT, systemd, docker, K8s coexistence, replay/evidence) with no skip path.
Task Breakdown
Title/ID: m25g-ticket-ir-and-namespace
Goal: Define host control-ticket schema/bounds and expose append-only ticket streams in the namespace.
Inputs: tools/coh-rtc/src/ir.rs, configs/root_task.toml, apps/nine-door/src/host, apps/root-task/src/ninedoor.rs, docs/INTERFACES.md.
Changes:
- tools/coh-rtc/src/ir.rs + configs/root_task.toml - add `host-ticket/v1` schema, action allowlist, byte caps, and lifecycle enums.
- apps/nine-door/src/host/tickets.rs + apps/root-task/src/ninedoor.rs - add `/host/tickets/spec`, `/host/tickets/status`, `/host/tickets/deadletter`, and bounded snapshot nodes.
- docs/INTERFACES.md - document ticket file paths, schema, and deterministic failure semantics.
Commands:
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- scripts/check-generated.sh
- cargo test -p nine-door
Checks:
- Valid ticket lines append successfully; malformed/over-limit lines fail deterministically.
Deliverables:
- Manifest-driven host ticket contract with generated artifacts and interface docs.
Title/ID: m25g-host-ticket-agent-core
Goal: Add a host-only ticket agent that watches mounted ticket streams and executes bounded work with idempotent claims.
Inputs: apps/coh/src/mount.rs, apps/host-ticket-agent (new), docs/HOST_TOOLS.md, docs/ARCHITECTURE.md.
Changes:
- apps/host-ticket-agent/src/main.rs - tail/watch loop for `/host/tickets/spec` with deterministic cursor resume.
- apps/host-ticket-agent/src/claim.rs - claim/idempotency handling keyed by `id` + `idempotency_key`.
- apps/host-ticket-agent/src/status.rs - append bounded `host-ticket-result/v1` receipts to `/host/tickets/status`.
- docs/HOST_TOOLS.md + docs/ARCHITECTURE.md - document runtime model, failure handling, and single-console constraints.
Commands:
- cargo test -p host-ticket-agent
Checks:
- Agent survives watcher interruptions, resumes from cursor, and avoids duplicate side effects for repeated tickets.
Deliverables:
- Host ticket execution agent with deterministic claim/execute/report lifecycle.
Title/ID: m25g-gpu-peft-ticket-executors
Goal: Implement high-value GPU lease and PEFT lifecycle ticket actions.
Inputs: apps/gpu-bridge-host, apps/coh/src/peft, docs/GPU_NODES.md, docs/USE_CASES.md.
Changes:
- apps/host-ticket-agent/src/executors/gpu.rs - execute `gpu.lease.grant|renew|release` and verify via `/gpu/<id>/lease`.
- apps/host-ticket-agent/src/executors/peft.rs - execute `peft.import|activate|rollback` using existing host registry and `/gpu/models/*` flows.
- docs/GPU_NODES.md + docs/USE_CASES.md - document ticket-driven GPU/PEFT orchestration for multi-tenant edge and model governance use cases.
Commands:
- cargo test -p gpu-bridge-host
- cargo test -p coh --features mock
Checks:
- Ticketed GPU/PEFT flows are auditable, bounded, and preserve existing lease/model semantics.
Deliverables:
- Ticket executors for the highest-value GPU/PEFT control loops.
Title/ID: m25g-systemd-docker-remediation
Goal: Add deterministic systemd/docker remediation ticket actions through host-side adapters.
Inputs: apps/host-sidecar-bridge, apps/host-ticket-agent, docs/HOST_TOOLS.md, docs/INTERFACES.md.
Changes:
- apps/host-ticket-agent/src/executors/systemd.rs - support allowlisted `start|stop|restart|status-check` unit actions.
- apps/host-ticket-agent/src/executors/docker.rs - support allowlisted container restart/stop/status actions with bounded output capture.
- apps/host-sidecar-bridge/src/providers/* - normalize status verification for post-action receipts.
- docs/HOST_TOOLS.md + docs/INTERFACES.md - document remediation action schemas and safeguards.
Commands:
- cargo test -p host-sidecar-bridge
- cargo test -p host-ticket-agent
Checks:
- Remediation actions emit deterministic success/failure receipts and never execute non-allowlisted commands.
Deliverables:
- Policy-bounded systemd/docker ticket remediation path.
Title/ID: m25g-k8s-rbac-ticket-translation
Goal: Preserve Kubernetes coexistence by translating RBAC-scoped intents into Cohesix host tickets.
Inputs: tools/cohesix-py, apps/host-ticket-agent, docs/USE_CASES.md, docs/PYTHON_SUPPORT.md.
Changes:
- tools/cohesix-py/cohesix/orchestrator.py - add optional RBAC-to-ticket translation helpers for cordon/drain/lease workflows.
- apps/host-ticket-agent/src/executors/k8s.rs - execute allowlisted K8s actions and emit bounded receipts.
- docs/USE_CASES.md + docs/PYTHON_SUPPORT.md - document coexistence constraints, identity mapping, and ticket translation flow.
Commands:
- python3 -m pytest tools/cohesix-py/tests -q
- cargo test -p host-ticket-agent
Checks:
- K8s coexistence remains out-of-band governance (no scheduler replacement) with deterministic ticket/audit linkage.
Deliverables:
- RBAC-scoped K8s coexistence adapter over ticketed control semantics.
Title/ID: m25g-evidence-replay-and-testplan
Goal: Extend audit/evidence/replay and codify mandatory ticket-flow validation in the Test Plan.
Inputs: apps/coh/src/evidence.rs, apps/coh/src/evidence_timeline.rs, docs/TEST_PLAN.md, docs/SECURITY.md, docs/USERLAND_AND_CLI.md.
Changes:
- apps/coh/src/evidence.rs + apps/coh/src/evidence_timeline.rs - correlate ticket `id`/`idempotency_key` across spec/status/audit/lease artifacts.
- docs/TEST_PLAN.md - add mandatory control-ticket matrix: GPU/PEFT, systemd remediation, docker remediation, K8s coexistence translation, and replay/timeline validation.
- docs/SECURITY.md + docs/USERLAND_AND_CLI.md - document token redaction, idempotency semantics, and operator procedures.
Commands:
- cargo test -p coh
- scripts/ci/check_test_plan.sh
Checks:
- Evidence packs and timelines are deterministic and include ticket correlation for all mandatory ticket classes.
Deliverables:
- Canonical docs and regression requirements for Milestone 25g ticketed orchestration.
Milestone 25h — Multi-Hive Federation via Ticket Relay (Single-Writer Preserved, 10x1k Fleet Pattern)
Why now (historical planning context): At Milestone 25h planning time, an earlier local benchmark snapshot was interpreted as a 1500-worker hard cap, with gateway pressure observed around 1000-1200 workers per hive. That snapshot is not a current qualified capacity claim; BENCHMARKS.md owns the active evidence and acceptance rules. The architectural conclusion remains: scale across independently bounded hives instead of introducing active/active writes to one logical hive. FAILOVER.md defines the single-writer active/standby and host-orchestrated cutover model extended by this milestone.
Goal
Deliver a deterministic multi-hive interoperability layer that:
- Scales operational control across many independent hives using host-side ticket relay.
- Preserves single-writer semantics per hive and explicit split-brain fencing.
- Enables pragmatic “10 queens -> 10,000 workers” orchestration patterns without adding new in-VM protocols.
- Produces replayable, correlated evidence for cross-hive intents and outcomes.
Non-Goals (Explicit)
- No active/active multi-queen writes to one logical hive namespace.
- No built-in cross-queen state replication or consensus protocol.
- No new in-VM TCP listeners, RPC channels, or shared-memory authority paths.
- No relaxation of Secure9P limits, ACK/ERR/END grammar, or existing policy gates.
- No dependence on REST-backed FUSE appends for mutation paths in federated mode; control writes remain REST
/v1/fs/echo-driven.
Design Principles (Normative)
- Hive as authority island - each hive remains independently authoritative and bounded.
- Forward intents, not mutable state - relay append-only tickets and receipts, never raw state replication.
- Idempotent by construction - cross-hive actions correlate by
id + idempotency_key + source_hive + target_hive. - Host-owned federation logic - keep routing, WAL, and retry policy host-side to preserve tiny VM TCB.
- Read-many, write-disciplined - broad fleet reads are allowed; writes are fenced per-hive and explicit.
Implementation Touchpoints
tools/coh-rtc/src/ir.rs,configs/root_task.toml, generated artifacts - add manifest-gated federation config:- peer inventory, per-peer auth references, relay queue bounds, allowed cross-hive actions, and WAL bounds.
apps/host-ticket-agent/*and/or newapps/hive-federation-relay/*- implement bounded cross-hive relay worker over existing REST gateway paths.apps/hive-gateway/*- expose relay-safe status counters (queue, dedupe, remote write failures) without adding control semantics.apps/coh/src/evidence.rs,apps/coh/src/evidence_timeline.rs- include cross-hive correlation fields in evidence/timeline exports.scripts/failover_watchdog.py- integrate federation-aware fencing hooks (pause relay during cutover, resume after health checks).tools/cohesix-py/*- optional fleet orchestrator helpers for fan-out by shard/hive policy while preserving ticket semantics.docs/FAILOVER.md,docs/HOST_TOOLS.md,docs/INTERFACES.md,docs/ARCHITECTURE.md,docs/TEST_PLAN.md,docs/USE_CASES.md- canonical as-built behavior and operator runbooks.
Commands
cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsonscripts/check-generated.shcargo test -p host-ticket-agentcargo test -p hive-gatewaycargo test -p cohpython3 -m pytest tools/cohesix-py/tests -qpython3 scripts/failover_watchdog.py --helpscripts/ci/check_test_plan.sh
Checks (Definition of Done)
- Per-hive single-writer invariant is preserved during normal operations, relay fan-out, planned failover, and unplanned cutover.
- Cross-hive relay is deterministic and idempotent: duplicate spec lines or relay restarts do not produce duplicate side effects.
- Federated writes use authenticated REST mutation paths; read-only FUSE mounts may be used for observability.
- Relay queueing is bounded with explicit backpressure/timeout counters and deterministic failure receipts.
- Evidence/timeline output correlates source hive intent -> target hive execution -> terminal receipt with stable IDs.
- A multi-hive validation matrix (minimum 3 hives; stretch 10 hives) passes with no split-brain writes and no grammar drift.
docs/TEST_PLAN.mdincludes mandatory federation runs (relay success, relay failure, dedupe, failover pause/resume, evidence correlation) with no skip path.
Task Breakdown
Title/ID: m25h-federation-ir-and-policy
Goal: Add manifest-driven federation config and bounds for cross-hive relay behavior.
Inputs: tools/coh-rtc/src/ir.rs, configs/root_task.toml, docs/INTERFACES.md, docs/ARCHITECTURE.md.
Changes:
- tools/coh-rtc/src/ir.rs + configs/root_task.toml - add `federation` section (peers, allowlisted actions, queue/WAL bounds, auth references).
- Generated artifacts/snippets - emit federation bounds for docs and host tooling.
- docs/INTERFACES.md + docs/ARCHITECTURE.md - document federation envelope and invariants.
Commands:
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- scripts/check-generated.sh
Checks:
- Invalid peer config or over-limit bounds fail generation deterministically.
Deliverables:
- Manifest-backed federation policy with generated docs snippets and hash-checked artifacts.
Title/ID: m25h-relay-agent-core
Goal: Implement bounded cross-hive ticket relay with WAL and deterministic cursor resume.
Inputs: apps/host-ticket-agent, apps/hive-gateway, docs/HOST_TOOLS.md, docs/FAILOVER.md.
Changes:
- apps/host-ticket-agent/src/relay.rs (or new apps/hive-federation-relay) - watch source `/host/tickets/spec`, forward allowlisted intents to target `/host/tickets/spec`.
- apps/host-ticket-agent/src/wal.rs - persist pending relay intents and replay unapplied entries after restart.
- apps/hive-gateway - expose relay observability counters under existing status surfaces.
Commands:
- cargo test -p host-ticket-agent
- cargo test -p hive-gateway
Checks:
- Relay restarts resume from cursor/WAL without duplicate side effects.
Deliverables:
- Host-side relay engine with bounded queueing and restart-safe behavior.
Title/ID: m25h-federated-ticket-envelope
Goal: Define cross-hive ticket envelope and status correlation rules.
Inputs: apps/nine-door/src/host/tickets.rs, apps/root-task/src/ninedoor.rs, docs/INTERFACES.md.
Changes:
- Ticket schema evolution (`host-ticket/v1` additive fields or `host-ticket-federated/v1`) including `source_hive`, `target_hive`, `relay_hop`, and correlation IDs.
- Deterministic mapping from target status receipts back to source status/deadletter.
- docs/INTERFACES.md - normative schema and lifecycle transitions for federated flow.
Commands:
- cargo test -p nine-door
- cargo test -p host-ticket-agent
Checks:
- Malformed or unauthorized federated envelopes are rejected with deterministic ERR/receipts.
Deliverables:
- Stable cross-hive envelope contract and receipt-correlation semantics.
Title/ID: m25h-fleet-read-model
Goal: Add operator-grade fleet read model without introducing global write semantics.
Inputs: apps/coh, apps/hive-gateway, docs/HOST_TOOLS.md.
Changes:
- apps/coh/src/fleet.rs - read-only fan-in helpers (`coh fleet status`, `coh fleet lease-summary`, `coh fleet pressure`).
- docs/HOST_TOOLS.md - document read-only fleet commands and write-fencing guidance.
- Optional REST/FUSE examples for multi-hive observability trees.
Commands:
- cargo test -p coh
Checks:
- Fleet read commands produce deterministic merged output and never mutate hive state.
Deliverables:
- Read-only fleet observability surface aligned with single-writer control semantics.
Title/ID: m25h-failover-fencing-integration
Goal: Integrate relay behavior with failover fencing and cutover runbooks.
Inputs: scripts/failover_watchdog.py, docs/FAILOVER.md, docs/TEST_PLAN.md.
Changes:
- scripts/failover_watchdog.py - add relay pause/resume hooks tied to hold-down and health thresholds.
- docs/FAILOVER.md - federation-aware runbook: freeze relay, cut over, replay WAL, resume relay.
- docs/TEST_PLAN.md - mandatory failover + relay consistency checks.
Commands:
- python3 scripts/failover_watchdog.py --help
- scripts/ci/check_test_plan.sh
Checks:
- Planned/unplanned cutovers do not create split-brain relay writes or duplicate downstream actions.
Deliverables:
- Federation-aware failover automation and validated operator procedure.
Title/ID: m25h-federation-scale-gate
Goal: Validate pragmatic multi-hive scale targets with deterministic pass/fail criteria.
Inputs: scripts/rest_perf_harness.py, docs/BENCHMARKS.md, docs/TEST_PLAN.md, docs/USE_CASES.md.
Changes:
- scripts/rest_perf_harness.py - add multi-hive scenario mode (N gateways, per-hive worker caps, relay load profile).
- docs/BENCHMARKS.md - publish 3-hive baseline and optional 10-hive stretch results with first-failure mode analysis.
- docs/USE_CASES.md + docs/TEST_PLAN.md - map federated scale to concrete use-case flows and mandatory gate commands.
Commands:
- python scripts/rest_perf_harness.py --mode simulate --multi-hive --hives 3 --workers-per-hive 1000 --no-retries --error-budget-rate 0.01
Checks:
- Multi-hive scenarios hit target worker totals via federation without breaching per-hive invariants.
Deliverables:
- Federation scale gate evidence and use-case-aligned capacity guidance.
Title/ID: m25h-evidence-and-timeline-correlation
Goal: Make cross-hive relay flows first-class in evidence packs and timelines.
Inputs: apps/coh/src/evidence.rs, apps/coh/src/evidence_timeline.rs, docs/HOST_TOOLS.md.
Changes:
- apps/coh/src/evidence.rs - export source/target relay correlation fields and redacted auth metadata.
- apps/coh/src/evidence_timeline.rs - stitch multi-hive ticket lifecycle into deterministic timeline ordering.
- docs/HOST_TOOLS.md - operator guidance for multi-hive postmortems and chargeback.
Commands:
- cargo test -p coh
Checks:
- Evidence/timeline output is deterministic and sufficient to reconstruct federated control flow.
Deliverables:
- Cross-hive evidence correlation integrated into existing audit-first tooling.
Release 0.9.0 alpha —-
The next planned releases target official Raspberry Pi 4 bare-metal boot (U-Boot + binary image) and AWS native boot via AMI.
Milestone 26 — Official Pi 4 Bring-up (U-Boot + Binary Image)
Status: Complete.
As-built attestation correction (2026-09-14): Schema 1.20 replaces the
public policy-hash TPM/DICE labels with explicit implementation modes. Root
reports measurement_only and development ticket keys; required signed modes
without a device provider fail before ticket registration. The shared host
TPM2 quote/certificate verifier and versioned challenge/evidence/trust contract
are implemented in ATTESTATION.md. Device issuance and sealed
or derived production ticket material remain the reopened task below.
Stock Pi 4 exception (Lukas Bower, 2026-09-14): The current Pi has no onboard TPM or provisioned device-bound DICE chain. It is excluded from positive signed-device acceptance and explicitly selects optional measurement-only mode. This exception does not enable secure boot, attest static keys, waive ordinary Pi operator/trace validation, or qualify an added TPM module. The hardware-independent host verifier and its negative/cryptographic conformance gates remain required. No CYW43 behavior or historical proof is relabelled.
Why now (context):
Upstream seL4 Pi 4 bring-up documentation originally used direct U-Boot image loading examples on bcm2711, not a UEFI handoff chain. Cohesix now follows the active staged U-Boot path: scripts/pi4-image-build.sh validates and consumes immutable seL4/build_UBOOT artifacts, composes the new rootserver and wrapper only in disposable output, stages the seL4 binary image, driver-runtime CPIO, and padded DTB, then hands off with bootm <image> <runtime-cpio> <dtb>. This preserves deterministic control at the U-Boot prompt while matching the isolated runtime layout used by Milestone 26a/26b.
Non-negotiable constraints:
- Boot chain for Pi 4 Milestone 26 is:
Pi firmware (start4/fixup) -> U-Boot -> seL4 image -> root-task. - Milestone 26 acceptance no longer depends on UEFI firmware settings or
BOOTAA64.EFI. - Backward compatibility remains mandatory: Pi 4 changes must not break existing QEMU workflows on macOS (
hvf/tcg) or Linux (kvm/tcg) foraarch64/virt. - Local diagnostics on Pi 4 must reuse the existing root-console parser and command semantics; no new shell grammar or in-VM protocol is permitted.
- Local diagnostics seat remains primitive: USB keyboard input + HDMI text output only; no compositor/windowing stack.
- Milestone 26 remains a strict no-NIC runtime baseline on Pi 4; root-task network bring-up and TCP console reachability on Pi 4 start in Milestone 26a.
- Milestone 26 has no Pi 4 NIC throughput or latency acceptance target; QEMU U-Boot harness timing is script/debug feedback only and cannot be used as Pi hardware latency or network-performance proof.
- U-Boot may be used for pre-kernel network setup and diagnostics, but no new Cohesix protocol semantics may be introduced there.
- All post-seL4 hardware access (UART, NET, USB input, HDMI text output, TPM, RTC) must go through HAL-owned traits/drivers.
Prerequisites (must be completed before Milestone 26 DoD)
Upstream seL4 Pi 4 binary image support
- Confirm and use upstream seL4 image output for
KernelPlatform=bcm2711(for examplesel4test-driver-image-arm-bcm2711). - The generated image must preserve existing VM boot semantics once seL4 is entered.
Upstream U-Boot Pi 4 support
- Build Pi 4 U-Boot using
rpi_4_defconfig. - Ensure SD card firmware handoff is configured to load
u-boot.binas kernel payload.
Goal
Deliver a Pi firmware -> U-Boot -> seL4 image -> root-task boot path on Raspberry Pi 4 that reaches the cohesix> prompt with primitive local diagnostics (USB keyboard input + HDMI text output) and deterministic no-NIC runtime evidence.
Deliverables
- Pi 4 U-Boot boot chain
- Standard FAT boot partition contains:
- Raspberry Pi firmware assets (
start4.elf,fixup4.dat, board DTBs/overlays as needed), u-boot.bin,- seL4 generated image (
sel4test-driver-image-arm-bcm2711), - Cohesix manifest artifacts used by root-task.
- Raspberry Pi firmware assets (
- Root-task remains the first user process post-kernel boot.
- Standard FAT boot partition contains:
- U-Boot command path (authoritative for boot control)
- Document and standardize operator commands:
fatlsto verify media,fatloadto load the staged image, runtime CPIO, and DTB into RAM,bootmto transfer execution through the staged U-Boot image contract.
- Define the environment conventions that 26a/26b will extend (
loadaddr,ipaddr,serverip,ethact,autoload,bootcmd).
- Document and standardize operator commands:
- macOS debug harness for U-Boot scripts
- Add a reproducible QEMU U-Boot harness on macOS using
qemu_arm64_defconfigandqemu-system-aarch64 -machine virt. - Use this harness to debug U-Boot env scripts and pre-boot network setup logic quickly.
- Explicitly document that QEMU harness does not prove Pi 4 USB keyboard, HDMI, or GENET hardware behavior.
- Add a reproducible QEMU U-Boot harness on macOS using
- Identity & attestation
- Root retains attestation policy and ticket-authority admission, while any physical TPM transport follows the mandatory isolated-driver/HAL boundary. A DICE mode is valid only when a device-bound CDI and signed certificate chain are established before root-task; hashing public configuration in root is not a DICE fallback.
- Capability ticket seeds are TPM-sealed or DICE-derived and become usable only after the selected measured-boot policy and signed evidence validate. Raw production seeds are never emitted into generated Rust, manifests, images, logs, or release bundles.
- Versioned, nonce-bound evidence is bound to the exact boot, kernel, root,
resolved manifest, and image identities and projected through bounded
/proc/attest/*nodes over existing Secure9P/console transport semantics. Measurement-only and unavailable states remain explicit and fail closed when attestation is required.
- Schema & validation
- Introduce profile naming aligned to boot reality (
pi4-uboot-aarch64), with a compatibility alias fromuefi-aarch64permitted only during migration. - Validate bounded hardware declarations (
uart,rtc, local-seat, attestation policy/device requirements). - Enforce no-NIC runtime gate for Milestone 26 profile(s).
- Introduce profile naming aligned to boot reality (
- Local diagnostics seat (Pi 4, essential-only)
- Profile-gated local-seat path consumes USB keyboard input and routes bytes into the existing root console parser.
- Primitive HDMI text sink mirrors root-console output lines with bounded memory and deterministic truncation.
- If
hw.local_seat.required=trueand the local-seat declaration or schema cannot be admitted, boot fails deterministically before ticket publication. Linked USB/HDMI runtime backend attach failures keep the serial shell alive with red local-seat acceptance evidence so Pi 4 recovery remains possible.
- No-NIC baseline validation (Milestone 26 only)
- Root-task completes boot/attestation/local-seat bring-up without NIC initialisation.
/proc/bootemits deterministic evidence that networking is intentionally disabled in Milestone 26 runtime.
Commands
- Build seL4 Pi 4 image:
scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
- Build U-Boot for Pi 4:
make -C third_party/u-boot rpi_4_defconfigmake -C third_party/u-boot CROSS_COMPILE=aarch64-linux-gnu- -j$(sysctl -n hw.ncpu)
- U-Boot boot commands on Pi 4:
fatls mmc 0:1fatload mmc 0:1 ${loadaddr} cohesix-image-arm-bcm2711fatload mmc 0:1 0x15000000 cohesix-driver-runtimes.cpio.uimgfatload mmc 0:1 0x14000000 bcm2711-rpi-4-b.dtbbootm ${loadaddr} 0x15000000 0x14000000
- U-Boot pre-boot networking setup commands (for 26a/26b preparation and diagnostics):
setenv autoload nosetenv ipaddr <board-ip>setenv serverip <host-ip>dhcpping ${serverip}saveenv
- macOS QEMU U-Boot harness:
make -C third_party/u-boot qemu_arm64_defconfigmake -C third_party/u-boot CROSS_COMPILE=aarch64-linux-gnu- -j$(sysctl -n hw.ncpu)qemu-system-aarch64 -machine virt -cpu cortex-a57 -m 2048 -nographic -bios third_party/u-boot/u-boot.bin
- Runtime checks:
cargo check -p root-taskcargo test -p root-task --features "kernel serial-console" local_seat
Checks (DoD)
- Pi 4 boots through U-Boot using the staged
bootmimage + runtime CPIO + DTB handoff into seL4/root-task with deterministic log ordering. cohesix>prompt appears on HDMI text output and accepts USB keyboard commands (help,bi,caps,ping) with unchanged parser semantics.- Command responses typed on USB keyboard are visible on HDMI and match serial transcript semantics.
- Manifest fingerprint is printed and matches packaged hash.
- If
hw.attestation.required=true, a real nonce-bound TPM2 Quote or device-bound DICE signature chain validates against the configured trust policy before ticket authority is published; measurement-only, replayed, stale, unsigned, wrong-boot, or unavailable evidence aborts deterministically. Merely matching a manifest hash is not attestation. - Milestone 26 runtime on Pi 4 emits deterministic no-NIC evidence and does not require TCP console reachability.
- Root-task post-seL4 paths use HAL-only device access; no direct firmware-service assumptions in runtime code.
- macOS QEMU U-Boot harness can execute U-Boot env/network commands for script validation; Pi 4 hardware remains authoritative for USB/HDMI/NIC proof and QEMU timing is not accepted as Pi hardware latency evidence.
- Existing macOS/Linux QEMU regression scripts continue to pass unchanged unless explicitly profile-gated and documented.
Compiler touchpoints
coh-rtcemits hardware tables for selected profile(s) and docs import them intodocs/HARDWARE_BRINGUP.mdanddocs/ARCHITECTURE.md.coh-rtcextends Pi 4 profile schema with bounded local-seat declarations (enabled,required, declared keyboard/display devices) and validates that required local-seat profiles name matchingrequired=truekeyboard/display device entries.coh-rtcenforces Milestone 26 no-NIC runtime gates while allowing U-Boot pre-boot network env declarations for future milestones.- Migration guard: accept legacy
uefi-aarch64manifests only through an explicit compatibility path and emit deterministic deprecation diagnostics.
Task Breakdown
Title/ID: m26-uboot-bootchain
Goal: Boot Pi 4 via the staged U-Boot `bootm` handoff into seL4/root-task with stable manifest fingerprint output.
Inputs: `seL4/build_UBOOT/images/sel4test-driver-image-arm-bcm2711`, `third_party/u-boot`, Pi firmware boot partition files, profile manifest, staged driver-runtime CPIO, padded Pi 4 DTB.
Changes:
- `scripts/pi4-image-build.sh` — build deterministic Pi 4 FAT payload (`u-boot.bin` + seL4 image + manifest artifacts).
- `docs/HARDWARE_BRINGUP.md` — document canonical Pi 4 U-Boot command flow and SD layout.
- `apps/root-task` — preserve boot fingerprint line ordering relative to serial/local seat.
Commands:
- `scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml`
- `make -C third_party/u-boot rpi_4_defconfig`
- `make -C third_party/u-boot CROSS_COMPILE=aarch64-linux-gnu- -j$(sysctl -n hw.ncpu)`
Checks:
- Pi 4 reaches root-task via staged `bootm <image> <runtime-cpio> <dtb>`; missing/invalid manifest or DTB policy aborts before ticket publication.
Deliverables:
- Reproducible Pi 4 U-Boot boot artifacts with documented hashes and commands.
---
Title/ID: m26-uboot-mac-debug-harness
Goal: Provide a fast macOS U-Boot/QEMU harness for debugging boot scripts and future network env setup.
Inputs: `third_party/u-boot` (`qemu_arm64_defconfig`), `qemu-system-aarch64`, docs updates.
Changes:
- `scripts/uboot/qemu-uboot-smoke.sh` — launch U-Boot on QEMU `virt` with deterministic serial logging.
- `docs/HARDWARE_BRINGUP.md` — list supported harness use cases and explicit non-goals (no Pi4 USB/HDMI/GENET fidelity).
Commands:
- `make -C third_party/u-boot qemu_arm64_defconfig`
- `make -C third_party/u-boot CROSS_COMPILE=aarch64-linux-gnu- -j$(sysctl -n hw.ncpu)`
- `qemu-system-aarch64 -machine virt -cpu cortex-a57 -m 2048 -nographic -bios third_party/u-boot/u-boot.bin`
Checks:
- Harness reaches U-Boot prompt and can execute env and network setup commands deterministically.
Deliverables:
- Faster pre-hardware debug loop for U-Boot setup logic.
---
Title/ID: m26-local-seat-minimal
Goal: Provide primitive local post-boot diagnostics on Pi 4 by wiring USB keyboard input and HDMI text output into existing root-console path.
Inputs: `apps/root-task/src/console/*`, `apps/root-task/src/userland/mod.rs`, `apps/root-task/src/event/*`, HAL mapping, `tools/coh-rtc`, profile manifest.
Changes:
- HAL-bound USB keyboard input path feeding existing parser/dispatcher.
- Primitive HDMI text sink mirroring root-console output lines with bounded memory and deterministic truncation.
- `coh-rtc` schema/codegen for `hw.local_seat` (`enabled`, `required`, declared devices).
- Pi 4 VL805 local-seat remains cold-boot-only: Linux/U-Boot captures may provide layout diagnostics, but root-port power readback, connected/enabled/speed state, and reset must be proven in the current Cohesix boot after command/event-ring proof.
Commands:
- `cargo check -p root-task`
- `cargo test -p root-task --features "kernel serial-console" local_seat`
- `cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json`
Checks:
- USB keyboard commands yield identical parser semantics to serial.
- Pi 4 USB enumeration does not synthesize root-port state from Linux/U-Boot captures after command-ring proof.
- HDMI output mirrors root-console lines deterministically.
- `hw.local_seat.required=true` fails fast when dependencies are unsatisfied.
Deliverables:
- Pi 4 local-seat evidence proving `cohesix>` command loop on USB keyboard + HDMI.
---
Title/ID: m26-device-identity-attestation-closure
Milestone: Milestone 26 — Official Pi 4 Bring-up / reopened device-identity, attestation, and ticket-secret defect
Goal: Replace configuration hashing presented as TPM/DICE evidence with real device-bound, freshness-protected attestation and prevent authority publication when no accepted trust root exists.
Inputs: apps/root-task/src/{attest.rs,kernel.rs,ninedoor.rs}, apps/pi4-driver-runtime/**, tools/coh-rtc/src/**, configs/root_task*.toml, selected seL4/U-Boot/QEMU/Pi images, host secret and trust-anchor tooling, docs/ARCHITECTURE.md, docs/HARDWARE_BRINGUP.md, docs/INTERFACES.md, docs/SECURITY.md, docs/TEST_PLAN.md, and the frozen CYW43 image identity when implementation begins.
Changes:
- tools/coh-rtc/src/** + configs/root_task*.toml — replace ambiguous `tpm-or-dice` selection with explicit `disabled|measurement_only|tpm2_quote|dice_evidence` implementation modes plus `required`, algorithms, bounded measurement/PCR policy, trust-anchor references, evidence/challenge limits, freshness window, ticket-key policy, and exact device/boot-chain prerequisites. Production generation rejects an attestation claim without a declared usable trust root, rejects DICE with no device-bound CDI chain, rejects TPM mode with no isolated TPM device contract, and rejects literal/static production ticket keys.
- apps/pi4-driver-runtime/** + HAL manifests — when TPM mode is selected, add the least-authority isolated TPM transport/runtime required for bounded TPM2 startup, PCR read/extend policy, quote, and sealed-object unseal. Root receives typed evidence/results only; it receives no direct physical bus/MMIO shortcut and no raw endorsement or storage key.
- boot/U-Boot handoff + apps/root-task/src/attest.rs — for DICE mode, consume a read-once, versioned, signed evidence descriptor rooted in a device-bound CDI/attestation key established before root-task. For TPM mode, request a TPM2 Quote over the generated PCR selection. Both evidence forms bind verifier nonce, boot/session id, monotonic/replay data, firmware/U-Boot/seL4 kernel/root/runtime archives/resolved-manifest/image hashes, algorithms, public-key/certificate chain, and signature.
- apps/root-task/src/ninedoor.rs + generated interface — add bounded `/proc/attest/{capabilities,status,challenge,evidence}` semantics. `challenge` accepts only an authenticated, rate-limited, fixed-schema nonce request; `evidence` returns the uniquely correlated signed result. This is an ephemeral evidence operation over existing transport/authority, not a general RPC or configuration mutation.
- ticket authority — replace generated static production role keys with TPM-sealed role material or DICE-domain-separated key derivation. Ticket publication occurs only after the selected measurement policy and signed chain validate; failure leaves ticket/network write authority unavailable while preserving the emergency serial failure report required by the profile.
- QEMU/Pi evidence — use a vTPM only as explicit QEMU virtual-device evidence and require real Pi hardware TPM or a genuine Pi device-bound DICE/secure-boot chain for Pi attestation acceptance. If neither exists, the Pi profile reports `measurement_only` or `unavailable`; it may boot only when attestation is not required and cannot make an attested-production claim.
- docs/tests/release — add enrollment/trust-anchor, rotation, nonce freshness, replay, wrong-PCR, wrong-image, wrong-key, expired-chain, TPM reset, DICE-chain, unavailable-device, secret-scan, and power-loss cases; historical deterministic hashes remain measurement fixtures and are never promoted.
Commands:
- cargo test -p coh-rtc attestation
- cargo test -p root-task --tests attest
- cargo test -p pi4-driver-runtime --features tpm2
- scripts/check-generated.sh
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26-attestation-qemu
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26-attestation-pi4
Checks: a fresh verifier nonce produces a valid TPM2 Quote or DICE signature chain bound to the exact accepted image and manifest; replay, public-data hash synthesis, missing CDI/TPM, wrong measurement, stale nonce, signature/chain failure, static key material, and fixture substitution fail before ticket publication; QEMU virtual evidence and Pi hardware/device-root evidence remain distinct; no CYW43 behavior or proof classification is edited.
Deliverables: Honest measurement-versus-attestation states, real device-bound signed evidence, sealed/derived ticket authority, host-verifiable freshness, and separate QEMU/Pi acceptance records.
---
Title/ID: m26-hal-boundary
Goal: Keep all post-seL4 runtime device access HAL-owned while allowing U-Boot-only pre-boot control.
Inputs: `apps/root-task/src/hal/*`, `apps/root-task/src/drivers/*`, `apps/root-task/src/kernel.rs`, `tools/coh-rtc/src/*`, docs.
Changes:
- Ensure all Milestone 26 runtime paths (serial, local seat, attestation, future network handoff points) are represented through HAL interfaces.
- Add deterministic checks and documentation language for bootloader-owned vs Cohesix-owned responsibilities.
Commands:
- `cargo check -p root-task`
- `cargo test -p root-task hal:: -- --nocapture`
- `rg -n "EFI_|boot_services|runtime_services|uefi::" apps/root-task/src apps/nine-door/src tools/coh-rtc/src`
Checks:
- No direct firmware-service assumptions in runtime code.
- HAL remains sole runtime device access surface.
Deliverables:
- Auditable bootloader/runtime boundary with CI-friendly guard commands and docs-as-built updates.
Milestone 26a — Pi 4 Driver-Task Substrate + GENET/Serial/Display Isolation
Status: Complete — the Pi 4 driver-task substrate, serial/display isolation, GENET linked-runtime migration, preserved GENET compatibility behavior, and physical wired TCP proof are accepted as meeting the 26a definition of done. Fresh Genet runs retain clean TCP/cohsh reachability, bounded driver-task service evidence, and no root-owned steady-state physical-driver service path.
Why now (platform continuity):
Milestone 25 established Cohesix’s performance model: parallelism comes from isolated seL4 tasks, while root-task authority stays serialized. The first 26a implementation proved Pi 4 GENET reachability, but later Wi-Fi tuning exposed a system-level flaw: hardware drivers still share the cooperative root-task turn. The completed 26a closure converts HAL from a broad in-root provider into a driver admission layer with explicit scheduling contracts, then migrates low-risk hardware paths before CYW43.
Non-negotiable constraints:
- No new in-VM listeners or protocols; the authenticated root-task TCP console remains the only in-VM TCP listener.
- Milestone 26a is the first milestone where Pi 4 TCP console reachability is expected; Milestone 26 must remain valid without NIC/TCP on Pi 4.
- DHCP is intentionally out of scope for 26a and is delivered in Milestone 26b; 26a uses static IPv4 only.
- Any VM vs Pi 4 networking differences must be profile-gated, manifest-defined, and documented.
- Driver implementation must remain HAL-bound with bounded queues and deterministic memory budgets.
- Root-task remains the single authority for tickets, console grammar, namespace, policy, and replay; driver tasks own only device progress.
- Every hardware-facing service path must declare a HAL driver-task scheduling contract before it can be serviced. Missing, unbounded, or non-preemptible contracts fail closed.
- Driver tasks receive only their declared MMIO, DMA, IRQ notification, endpoint, fault, and ring capabilities. No driver task may receive Secure9P authority, ticket material, broad namespace state, or a catch-all
KernelHal. - Serial RX and USB/local-seat input are the highest-priority service class; HDMI/log flushing and network data are preemptible.
- Direct root-task driver paths are not a steady-state Pi 4 driver model. They may remain only for early/emergency serial output before the driver-task substrate exists and for QEMU/host compatibility profiles; physical Pi 4 steady-state driver service must fail closed until the corresponding independent ring-backed driver task owns the hardware state.
- Backward compatibility is mandatory: 26a network changes must preserve existing macOS/Linux QEMU console and networking workflows unless explicitly profile-gated for Pi 4
pi4-uboot-aarch64(with transitional alias support for legacyuefi-aarch64manifests). - QEMU remains compatibility and transport-substrate evidence for 26a, not a Pi 4 wired-NIC latency baseline. Any 26a GENET latency reporting is diagnostic boundedness evidence for the physical static-IPv4 path; Milestone 26b owns same-harness benchmark comparison and the physical-network latency SLO.
Prerequisite
- Milestone 26 completed (U-Boot boot chain + device identity attestation + local diagnostics seat + bootloader/HAL boundary enforcement).
- Milestone 26 hardware evidence includes deterministic no-NIC boot transcripts for Pi 4 (
pi4-uboot-aarch64).
Goal
Add the HAL-enforced driver-task substrate, migrate serial/display and GENET behind explicit scheduling contracts, and preserve the original Pi 4 GENET static IPv4 behavior as the compatibility target.
Deliverables
- HAL driver-task admission substrate
- Add a HAL-owned driver scheduling contract surface for serial, USB/local-seat, HDMI text, GENET, CYW43, SDIO host, PCIe root, and QEMU compatibility NICs.
- Each contract declares role, service class, authority, isolation target, per-turn operation/byte/frame budget, queue depth, and blocking policy.
- Runtime driver construction and polling fail closed when a hardware-facing path does not declare a valid, preemptible contract.
- The initial compatibility implementation may still run selected drivers in-process, but the same contract is the admission record for the dedicated seL4 task that replaces it.
- seL4 driver-task substrate
- Add root-owned wrappers for driver TCB creation, CSpace/VSpace setup, IPC-buffer installation, badged endpoints, notifications, IRQ binding, fault endpoints, scheduling-context parameters where available, and revocation.
-
As-built substrate work now includes non-MCS TCB priority/scheduling/resume/notification wrappers, CNode revoke, a remote-safe IPC-buffer bind helper, AArch64 VSpace root and boot-ASID-pool assignment wrappers, explicit page/page-table map wrappers for non-root VSpaces, bounded HAL driver-task command/completion rings, Pi 4 bootstrap-created driver TCB attempts for the manifest-selected subset of the seven acceptance-eligible Pi hardware runtime contracts, restricted child CSpaces, command endpoints, notifications, fault endpoint slots, stacks, and tolerant handling for boot-seeded intermediate page tables while mapping driver IPC/stack frames. The completed M26a classic-SMP profile used manifest-selected per-driver affinity through child-TCB
seL4_TCB_SetAffinity; M26e supersedes that mechanism atomically with the selected core’s generated SchedControl/SC bind and prohibits directTCB.SetAffinityin an MCS transcript. The role-affinity wrapper used around legacy in-process operations changes the init TCB temporarily; it is not isolated-child evidence. Physical Pi 4 MCS owner-state boots must showDRIVER_TASK_MCS_ACTIVE ... core=<manifest-core>,DRIVER_TASK_AFFINITY_MCS ... source=sched-control-sc-bind direct-set-affinity=no status=configured, andDRIVER_TASK_BOOT ... affinity_core=<manifest-core>for the active selected contracts plus aggregate applied affinity before placement proof closes; anyTCB.SetAffinity, affinity-failure marker, orDRIVER_TASK_AFFINITY_DEFERRED ... reason=pi4-child-tcb-affinity-boot-stall-guardline keeps affinity proof red. Physical Pi 4 owner-state boots bind the generated CYW43 and SDIO peer notifications during bootstrap and must emitDRIVER_TASK_NOTIFICATION_BOUND ... source=generated-cyw43-sdio-topology; other runtimes may still defer the optional early TCB-bound notification syscall and continue endpoint-backed command-ring startup with notification lifecycle proof red. QEMU compatibility smoke may still create all nine declared contracts, including RTL8139 and virtio-net, after virtio networking is ready. QEMU virtio compatibility builds keep the same contract set but publish an inactiveqemu-virtio-pre-net-resource-guardreport before network init so failed live-task bootstrap cannot exhaust resources needed by the virtio TCP regression path; with the explicitqemu-driver-task-smokefeature, they create all nine declared driver-task TCBs after virtio networking is ready, allocate per-driver VSpaces, assign ASIDs, map only a one-page driver trampoline plus stack/IPC/ring frames, complete a fixed-layout ring command without callback/context pointers, unmap root aliases for code/IPC/stack after the isolated task starts, and emit console-visibleDRIVER_TASK_BOOT_SMOKE phase=post-net-qemu status=summary ... vspace=isolated ipc_abi=shared-ring-command pointer_free_ipc=yes owner_state=not-provenas QEMU transport-substrate proof. Physical Pi 4 builds now require the isolated VSpace constructor for normal driver bootstrap and reject virtual NIC trampoline work from the physical bootstrap set. For generated Pi 4 hot paths, root loads isolatedpi4-driver-*runtime artifacts only from the raw driver-runtime CPIO embedded into the root-task image byscripts/pi4-image-build.sh; when an artifact is found by generated path, HAL maps every boundedPT_LOADpage from the runtime ELF plus stack/IPC/ring and declared MMIO/DMA/shared-buffer regions, stages a pointer-freepi4-driver-abiruntime-init descriptor containing physical page metadata, semantic resource ranges, bus-alias policy, optional IRQ descriptors, USB/PCIe and CYW43/SDIO bus-link descriptors, and framebuffer metadata, then starts the isolated fixed-ring runtime entry. Physical Pi pre-root bootstrap turns do not sample timer registers; later steady ring latency telemetry uses the EL0 virtual counter. Physical Pi ring turns useseL4_Calland isolated runtimes reply after publishing the primitive completion record, so lower-priority driver TCBs do not depend onYieldfor service time. Runtime-init commands deliver topology and must be followed by hardware service turns before board proof can close. Per-driver runtime-image specs are compiler IR underroot_task.driver_images, generated into the root-task manifest tables, and backed by separately isolatedpi4-driver-*runtime image artifacts staged by bothscripts/cohesix-build-run.shandscripts/pi4-image-build.sh;scripts/pi4-image-build.shpackages the raw CPIO before the root-task build so the physical Pi image carries the required embedded runtime source. The staged U-Boot CPIO remains audit/packaging evidence and is not a runtime fallback for physical Pi owner-state boots. Generatedcode-pages=320covers the current 257-page multi-segment runtime ELF spans with a bounded 63-page growth margin, and the USB xHCI manifest aperture is 16 pages instead of the earlier 2-page stub. Runtime DMA/shared budgets are descriptor-backed and sized to current runtime use: serial shared=4 pages, USB DMA/shared=128/32 pages, HDMI DMA/shared=0/16 pages plus framebuffer, GENET DMA/shared=64/32 pages for a 32-RX/32-TX ring shape, CYW43 DMA/shared=0/64 pages, SDIO DMA/shared=10/32 pages, and PCIe shared=16 pages. SDIO’s ten low, uncached pages are one private Pi firmware-mailbox request page, one control-block page, and eight CMD53 bounce pages spanning the exact 32-KiB reciprocal aperture. The child VSpace layout keeps MMIO at0x70200000, DMA at0x70800000, and shared control at0x70c00000; semantic resource ranges carry aggregate page counts while per-page DMA descriptors cover every runtime-owned DMA page. Those artifacts implement fixed-ring production service engines rather than smoke-only stubs: serial handles bounded mini-UART init/RX/TX; HDMI renders into the mapped framebuffer; PCIe services primitive mapped-aperture read/write/flush operations; USB owns the direct-root-port xHCI boot-keyboard path; GENET owns MDIO/MAC plus bounded RX/TX rings; and CYW43 owns the shared-control SDPCM surface without direct SDHCI authority or fallback. SDIO owns one HAL-declared SDHCI page, one noncontiguous firmware-mailbox page, one channel-4 BCM2835 DMA-controller page, and ten private low DMA pages. Its sole retained owner seals a Linux/Raspberry Pimmc-bcm2835engine choice into each immutable CMD53 identity from normalized host-block geometry: at most two blocks use retained PIO, while more than two use the DREQ-11 external-DMA engine. One linked-runtime call may batch the finite Linux-ordered preissue setup and exactly one issue under the shared 256-operation service contract. Each fresh direction-owned PIO ready edge moves one complete normalized host block of at most 512 bytes and 128SDHCI_BUFFERaccesses without crossing into another block; external DMA advances through one immutable SDHCI/DMA snapshot per owner continuation and requires terminalCS.INTplusCONBLK_AD == 0. Both shapes join exact response/payload, authoritativeDATA_END, and host quiescence. A full retained 32-KiB backplane window is partitioned as Linux MMC-shaped511 * 64external-DMA plus1 * 64retained-PIO children. Missing external-DMA authority fails its selected request closed; no engine switching, second lane, root-owned data path, legacy fallback, or post-issue replay exists. PMUCONTROL uses one incrementing four-byte Function 1 CMD53 read and one matching write at0x8600, never a partial bytewise CMD52 update.All seven generated runtime specs remain acceptance-eligible (
root_context_required=false,hardware_state_migrated=true), while a fresh Pi boot activates only the selected network role: Wi-Fi selects SDIO plus CYW43 and wired selects GENET. Root hands firmware-mailbox authority to SDIO once after PCIe/VL805 readiness proof, and every later root mailbox call fails closed. A preseeded mailbox page is transferred by copying its cached HAL-admitted frame capability into the child rather than requesting fresh device-untyped coverage. SDIO retains the Linux-shaped GPIO129 GET-config/polarity, output-low, host power-off, 2 ms off, power-up-while-low, 10 ms settle, WL_ON high, startup-clock, and final 10 ms settle sequence as one-action phases with virtual-counter deadlines. Firmware property acceptance requires global transaction success plus the firmware-overwritten zero GPIO token; per-tag returned-length, tag, and end-marker metadata are not GPIO-consumer predicates. Each operation posts the proven Pi 4 VC address once, retains the same DMA page, and services one reply sample per turn under a 500 ms deadline. No synchronous mailbox spin, alias replay, GPIO state-only path, confirm-read path, or root fallback remains. Pending phases retain the exact ring intake and publish no premature completion. Missing exact SDIO IRQ/DPC proof fails closed, old-generation CCCR responses cannot prevent physical reset, and fresh Pi proof must still show useful USB, HDMI, selected-network DHCP, SDIO owner state for Wi-Fi, and PCIe/VL805 behavior. - QEMU/host compatibility profiles may still dispatch bounded service callbacks through live driver TCBs or root compatibility paths so existing virtual-device tests keep running. Those paths now enter through a single HAL callback-compatibility gate and a single HAL root-compatibility admission gate; physical Pi 4 builds compile out the callback slot state and both gates fail closed for steady-state hardware service. If the independent ring-backed path is unavailable, the service turn fails closed and acceptance remains red. The May 20 Pi 4 proof is not closure because every driver-task bootstrap failed with
seL4_DeleteFirstand hot paths stayed root-task compatibility. CYW43, SDIO, and PCIe now have owner-ring service queues: SDIO records CMD52/CMD53/POLL_IRQ completion through the isolated runtime before owner-state can creditsdio-host, CYW43 firmware/NVRAM/SDPCM command records return from isolated runtime completions before root hardware execution, and PCIe port read/write/flush helpers return from isolated runtime completions before root hardware execution. Their current acceptance specs still need fresh Pi hardware proof to show the complete SDIO, CYW43, USB, and PCIe hardware state machines are live in the isolated runtimes. - The normal physical Pi 4 service path now uses linked-image command/completion rings where implemented and fails closed otherwise. Serial still keeps emergency boot logging alive, but normal UART runtime initialization now runs through the profile-selected
pi4-driver-serialimage and the event pump receives only adriver-task-serial-clientafter that command succeeds. Physical Pi network init selects ring-backedGenetDriverTaskDevice/Cyw43DriverTaskDeviceclients; the isolated GENET image now owns MDIO/MAC plus bounded RX/TX descriptor-ring turns when wired is selected, and the isolated CYW43 image owns shared-control SDPCM command records while SDIO transport authority sits with the profile-selectedsdio-hostimage when Wi-Fi is selected. Local-seat init has the same boundary: root has USB/HDMI ring-client shells, the isolated HDMI runtime can render with framebuffer metadata, and the isolated USB runtime owns the xHCI boot-keyboard path. The olderPi4LocalSeatroot-resident selector handler and root-owned USB support crate have been removed and are not acceptance evidence. The physical PiKernelHalno longer carries a directPi4WifiStateslot and direct Wi-Fi HAL construction returnspi4-wifi-driver-task-runtime-required. The HAL still splits root-context diagnostic ring registration from pointer-free selector ring registration; QEMU/host compatibility can keep root-context diagnostic services, while physical Pi linked-image hardware service uses the fixed ring or fails closed. Shared-ring completions are tracked asshared_ring_rolesand do not satisfyhot_path=dedicatedor full acceptance; idle completions and zero-result progress completions cannot credit hot-path ownership. The proof layer also requiresDRIVER_TASK_OWNER_STATE_PROOF=yesbacked by per-active-hot-pathDRIVER_TASK_OWNER_STATE ... descriptor=present root_pointer=nolines for the selected boot set, acceptance-eligible runtime-image specs, and the runtime transport mapping mask complete;sdio-hostmust prove the isolated SDIO runtime completed non-root-context hardware progress before it can credit Wi-Fi owner-state. Owner-state descriptor registration is rejected if the corresponding runtime-image spec is not acceptance-eligible. The QEMU smoke path proves the isolated trampoline, per-driver VSpace/ASID allocation, restricted mapping set, runtime-image declaration accounting, actual transport-region mapping, and pointer-free ring transport, but that is transport-substrate proof rather than Pi hardware hot-path ownership. Any callback-pointer, root-task compatibility, or root-resident selector service turn remains QEMU/host or migration evidence only and fails reopened Pi closure. - Root keeps authority and revocation; driver tasks receive only compiler-declared caps and bounded shared rings.
- seL4 scheduling fields are profile-qualified. Current accepted profiles use non-MCS TCB priority/domain plus bounded IPC/poll budgets. A future MCS profile may claim explicit scheduling-context binding only after the Milestone 26e ABI, admission, timeout, reply/donation, and target-evidence gates pass for that exact profile.
- The substrate must not introduce POSIX threads, implicit async runtimes, unbounded queues, or a second listener/protocol.
- Serial/display driver-task migration
- Move normal UART service behind a
driver-serialcontract and preserve emergency early-boot debug UART fallback only until handoff. - Move HDMI/text flushing behind a
driver-displaycontract so display refresh cannot block serial input, USB keyboard input, or network control progress. - Prove serial command echo and HDMI mirror behavior under synthetic GENET traffic.
- Move normal UART service behind a
- GENETv5 NIC backend (Pi 4)
- Add a root-task driver backend for Broadcom GENETv5, implemented in pure Rust with HAL ownership for MMIO, IRQ, DMA, and cache maintenance.
- Use this design-reference order for architecture review: Linux
bcmgenetdriver behavior (primary) -> Linuxbcm2711Pi 4 DT bindings for GENET/MDIO/PHY wiring (secondary) -> U-Bootbcmgenetbring-up behavior (tertiary sanity reference). - References are design-only inputs; no direct code lift is permitted.
- Integrate backend selection into existing
NetBackendplumbing and keep QEMU backends (rtl8139/virtio-net) unchanged. - Promote GENET from in-root compatibility path to
driver-genetonce the frame-driver ABI, DMA ring grants, IRQ notification, and bounded frame IPC pass QEMU and Pi 4 checks.
- Profile-gated static IPv4 for
pi4-uboot-aarch64- Extend manifest IR and validation with bounded static IPv4 fields for Pi 4 U-Boot profile (interface IP, prefix length, optional gateway).
- Generate root-task networking config from
coh-rtcartifacts instead of hard-wired dev-virt defaults whenprofile.name=pi4-uboot-aarch64(or accepted legacy alias). - Reject invalid/static-zero network configs deterministically at compile time or early boot.
- Docs-as-built alignment
- Update
docs/ARCHITECTURE.md,docs/INTERFACES.md, anddocs/SECURITY.mdwith:- profile-gated backend matrix (QEMU vs Pi 4),
- static IPv4 configuration source of truth,
- deterministic bounds and failure modes for GENETv5 bring-up.
- Update
docs/HARDWARE_BRINGUP.mdwith Pi 4 U-Boot network checklist and expected boot evidence lines.
- Update
Commands
cargo check -p root-taskcargo test -p sel4-syscargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::driver_taskcargo test -p root-task net:: -- --nocapturecargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsonscripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.tomlscripts/uboot/qemu-uboot-smoke.sh --net usercargo run -p cohsh --features tcp -- --transport tcp --tcp-host <STATIC_IP> --tcp-port 31337 --script scripts/cohsh/boot_v0.coh
Checks (DoD)
- HAL driver-task contracts exist and validate for serial, USB/local-seat, HDMI text, GENET, CYW43, SDIO host, PCIe root, RTL8139, and virtio-net.
- Network stack construction rejects missing or invalid driver scheduling contracts before device initialisation.
- Pi 4 and QEMU driver-task acceptance must distinguish contract declaration from isolation: root-task compatibility service turns are useful diagnostic evidence only, while reopened physical Pi closure requires the manifest-selected active driver-task set to report
DRIVER_TASK_COMPATIBILITY=0,DRIVER_TASK_DEDICATED_READY=yes, role-specificDRIVER_TASK_SERIAL_DEDICATED=yes,DRIVER_TASK_USB_DEDICATED=yes,DRIVER_TASK_DISPLAY_DEDICATED=yes,DRIVER_TASK_NET_DEDICATED=yes, selected-roleDRIVER_TASK_SDIO_DEDICATED=yesfor Wi-Fi, andDRIVER_TASK_PCIE_DEDICATED=yes, plusDRIVER_TASK_SUBSTRATE_READY=yes,DRIVER_TASK_FAILED_COUNT=0,DRIVER_TASK_CAPSET_PROOF=yes,DRIVER_TASK_FAULT_PROOF=yes,DRIVER_TASK_REVOKE_PROOF=yes,DRIVER_TASK_SCHED_PROOF=yes,DRIVER_TASK_AFFINITY_PROOF=yes, selected active affinity configured/applied proof,DRIVER_TASK_AFFINITY_MANIFEST_PROOF=yes,DRIVER_TASK_VSPACE_PROOF=yes,DRIVER_TASK_POINTER_FREE_IPC_PROOF=yes,DRIVER_TASK_OWNER_STATE_PROOF=yes, and active-net identity proof underscripts/pi4_gate_proof.sh --require-driver-task-proof; QEMU compatibility smoke may still prove all nine declared contracts as transport-substrate evidence only.DRIVER_TASK_OWNER_STATE_PROOF=yesrequires concrete descriptor proof forserial-console,usb-keyboard,hdmi-text,pcie-root, and the selected network role (genet-nicfor wired, orcyw43-wifiplussdio-hostfor Wi-Fi); SDIO only credits after a non-root-context isolated runtime CMD52/CMD53/POLL_IRQ completion proves hardware progress. Aggregateowner_state=driver-ownedtext is not closure. ADRIVER_TASK_AFFINITY_DEFERRED ... reason=pi4-child-tcb-affinity-boot-stall-guardline is stale mitigation evidence, not affinity proof; it must keepDRIVER_TASK_AFFINITY_PROOFandDRIVER_TASK_AFFINITY_MANIFEST_PROOFred. ADRIVER_TASK_NOTIFICATION_BIND_DEFERRED ... reason=pi4-early-tcb-notification-bind-boot-stall-guardline remains mitigation evidence for non-CYW43/SDIO runtimes and not notification lifecycle proof; for either generated CYW43/SDIO peer it is a Wi-Fi acceptance failure. Host tests must keep the pointer-free ring records fixed-layout and primitive-only, prove the physical Pi profile cuts over to driver-task client shells instead of root-owned hardware constructors, and cover the Pi 4 hot-path command catalog for serial console, USB keyboard, HDMI text, GENET RX/TX, CYW43 RX/TX, SDIO host, and PCIe root service. Callback-pointer service turns, including live-TCB callback turns, remain compatibility evidence until the driver state boundary is owned by a ring-backed task. The Pi 4 manifest assignsbcmgenet-v5to core1and retainscyw43455plussdio-hoston core3; boot evidence must show the selected contract’s exact manifest affinity before claiming placement. - Root-owned driver-task substrate can create, monitor, fault-report, and revoke at least one non-authority driver task without changing console grammar.
- Serial and HDMI service remain responsive while synthetic GENET traffic consumes its full allowed budget.
- Pi 4 U-Boot boot reaches root-task network init and reports
GENETv5backend with static IPv4 from manifest-generated config. cohsh --transport tcpsucceeds against the configured static address with no console grammar or ACK/ERR/END drift.- Any 26a GENET latency evidence is recorded as physical static-IPv4 responsiveness diagnostics and must not be compared against QEMU loopback latency as a closure gate.
- Invalid Pi 4 static IPv4 manifest settings are rejected deterministically (compiler validation and/or early-boot fail-fast).
- Pi 4 26a validation explicitly demonstrates transition from Milestone 26 no-NIC baseline to 26a NIC-enabled boot using profile-gated configuration only.
- No DHCP client path is introduced in 26a; DHCP remains scoped to Milestone 26b.
- Existing macOS/Linux QEMU test and operator flows remain backward compatible with pre-26 behavior.
- Full regression pack remains green on QEMU; any profile-gated divergence is explicitly documented and fixture-backed.
Compiler touchpoints
coh-rtcemits driver-task contract tables for profile-selected hardware roles, including task id, service class, priority band, period/budget target, IRQ badge, DMA/ring bounds, queue depth, and shutdown/revoke behavior.coh-rtcemits profile-gated network config tables (backend selection + static IPv4 fields) into generated root-task artifacts.- Manifest validation enforces:
- static IPv4 required for
pi4-uboot-aarch64network-enabled profile, - prefix bounds (
1..=32), - backend/profile compatibility (
bcmgenetonly where declared inhw.devices).
- static IPv4 required for
- Docs snippet regeneration includes static IPv4 and backend mapping excerpts for Architecture/Interfaces docs.
Task Breakdown
Title/ID: m26a-driver-task-hal-contracts
Goal: Make hardware driver service admissible only through HAL-declared scheduling contracts.
Inputs: apps/root-task/src/hal/*, apps/root-task/src/net/*, apps/root-task/src/serial/*, apps/root-task/src/local_seat.rs, docs/DRIVERS.md, docs/TEST_PLAN.md.
Changes:
- apps/root-task/src/hal/* — add driver-task contract types, built-in role contracts, and per-turn budget validation.
- apps/root-task/src/net/mod.rs + apps/root-task/src/net/stack.rs — require valid NIC driver contracts before network device construction and expose active contract diagnostics.
- apps/root-task/src/serial/mod.rs + apps/root-task/src/local_seat.rs — expose serial and local-seat contracts for event-loop admission.
Commands:
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::driver_task
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib net::tests::network_driver_task_contracts_match_backend_labels
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib serial::tests::poll_io_obeys_driver_task_budget
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib event::tests::serial_input_skips_ready_network_data_poll_for_driver_task_turn
Checks:
- Missing, zero-budget, blocking, or non-preemptible driver contracts fail deterministically before service.
- Built-in contracts preserve the priority order: serial/USB input before network control, network control before network data, diagnostics/display last.
Deliverables:
- HAL scheduling-contract ratchet for current compatibility drivers and future dedicated seL4 driver tasks.
Title/ID: m26a-smp-activity-diagnostic
Goal: Add bounded root-console activity diagnostics for cross-core evidence without enabling seL4 kernel benchmark builds.
Inputs: crates/cohsh-core/src/command.rs, crates/cohsh-core/src/verb.rs, apps/root-task/src/event/mod.rs, apps/root-task/src/console/mod.rs, apps/root-task/src/local_seat.rs, apps/root-task/src/net/mod.rs, apps/root-task/src/hal/driver_task.rs, apps/root-task/src/affinity.rs, docs/USERLAND_AND_CLI.md.
Changes:
- crates/cohsh-core/src/command.rs + crates/cohsh-core/src/verb.rs — expose the canonical grammar as `smp [activity|dump]`, reject unknown pseudo-profile arguments, map bare `smp` and explicit `smp activity` to bounded userspace telemetry, and retain the raw debug-kernel scheduler snapshot only as explicit `smp dump`.
- apps/root-task/src/affinity.rs + apps/root-task/src/event/mod.rs — implement the default `smp` activity view from bounded userspace telemetry: event-pump command/timer counters, serial backpressure, local-seat keyboard/HDMI mirror counters, network status/counters when present, HAL driver-task contracts, driver-task runtime proof masks, manifest affinity assignments, and repeated-sample per-core counter-delta rows; keep `smp dump` on the same multi-assignment core bucket formatter.
- apps/root-task/src/console/mod.rs — keep early-console behavior explicit when the event-pump telemetry source is unavailable.
- docs/USERLAND_AND_CLI.md + docs/snippets/cohsh_grammar.md — document that default `smp` activity output is not a cycle-accurate profiler, does not require kernel benchmark builds, and is mirrored to HDMI through the local-seat path while explicit raw `smp dump` text remains UART-only.
Commands:
- cargo test -p cohsh-core smp
- cargo test -p root-task smp_activity
- cargo test -p root-task --features net-console smp_activity
Checks:
- `smp` and `smp activity` never depend on `CONFIG_BENCHMARK_TRACK_KERNEL_ENTRIES`, debug-kernel benchmark syscalls, PMU counters, or unbounded sampling.
- Output is line-bounded and useful for Pi 4 diagnostics: it distinguishes parser/event-loop progress, serial pressure, HDMI/local-seat mirroring, attached network progress, driver-task compatibility vs dedicated proof, and configured role/driver affinity.
- The htop-ish core rows are assignment buckets, not exclusive CPU owners: when multiple roles/drivers map to the same core, `tasks=` lists all of them and the rate fields aggregate only safe userspace counter deltas for that bucket while keeping `cpu_pct=unavailable`.
- Explicit debug-kernel `smp dump` also treats core rows as assignment buckets: before each UART-only seL4 scheduler/CPU dump, the probe line includes every role/driver allocated to that core instead of dropping secondary assignments.
- HDMI display receives the same event-pump activity lines when local-seat mirroring is active; raw kernel debug output from `smp dump` remains serial-only and unavailable after linked-UART cutover.
- Unknown arguments such as `smp profile` fail grammar validation instead of silently aliasing to default `smp`.
Deliverables:
- Root-console `smp` activity diagnostic, compatibility spelling, explicit raw dump path, event-pump/HDMI mirroring, and feature-scoped network test coverage.
Title/ID: m26a-driver-task-kernel-substrate
Goal: Add root-owned seL4 task/capability substrate for hardware driver tasks without changing authority semantics.
Inputs: apps/root-task/src/kernel.rs, apps/root-task/src/hal/*, apps/root-task/src/cspace*, configs/root_task.toml, docs/ROLES_AND_SCHEDULING.md.
Changes:
- crates/sel4-sys/src/lib.rs + apps/root-task/src/sel4.rs — add driver TCB scheduling/resume/notification wrappers, CNode revoke, and remote-safe IPC buffer install.
- apps/root-task/src/hal/* + apps/root-task/src/kernel.rs — add driver-task handles/rings for TCB creation, CSpace/VSpace setup, scheduling attributes, per-driver SMP affinity, notification binding, fault endpoint badges, and revocation.
- configs/root_task.toml + coh-rtc outputs — add profile-gated driver-task specs, per-driver affinity, and bounds.
Commands:
- cargo check -p root-task --target aarch64-unknown-none --no-default-features --features release-pi4
- cargo test -p sel4-sys
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::driver_task
Checks:
- Root retains cap ownership and can fault-report/revoke a driver task.
- Driver tasks receive only declared device grants and bounded ring frames.
Deliverables:
- Dedicated driver-task creation substrate ready for serial/display, GENET, USB, CYW43, SDIO, and PCIe migration.
Title/ID: m26a-serial-display-driver-tasks
Goal: Move normal serial and HDMI display service behind dedicated driver-task contracts while preserving emergency debug fallback.
Inputs: apps/root-task/src/serial/*, apps/root-task/src/local_seat.rs, apps/root-task/src/event/*, docs/DRIVERS.md.
Changes:
- apps/root-task/src/serial/* — replace blocking normal-output paths with bounded driver-task IPC after early boot handoff.
- apps/root-task/src/local_seat.rs — route HDMI text refresh through a bounded display-sink task.
- apps/root-task/src/event/* — preserve serial/USB priority over network data and display flushing.
Commands:
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib serial::tests
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib local_seat::tests
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib event::tests
Checks:
- Serial echo and HDMI mirror remain fluid while GENET consumes its full data budget.
- Emergency debug UART remains available only for boot/fault diagnostics, not normal console output.
Deliverables:
- Serial/display task isolation proof with no ACK/ERR/END grammar drift.
Title/ID: m26a-genet-driver-task
Goal: Promote GENET from in-root compatibility driver to isolated frame driver task.
Inputs: apps/root-task/src/drivers/driver_task_net.rs, apps/root-task/src/net/*, apps/pi4-driver-runtime/src/lib.rs.
Changes:
- apps/root-task/src/drivers/driver_task_net.rs — keep root as the GENET ring client only and fail closed when the isolated runtime has not returned owner progress.
- apps/pi4-driver-runtime/src/lib.rs — keep DMA ring ownership, TX reclaim, RX refill, and service turns in the isolated `driver-genet` runtime.
- apps/root-task/src/net/* — consume bounded Ethernet-frame IPC from the GENET task while keeping smoltcp/listener semantics in root.
Commands:
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
Checks:
- GENET static IPv4 reachability is preserved, ring pressure is observable, and serial/HDMI remain responsive under wired load.
Deliverables:
- First production dataplane driver task and preserved 26a static IPv4 behavior.
Compatibility baseline tasks below are retained because they describe the original 26a GENET/static-IPv4 behavior that must keep working. They do not close reopened 26a by themselves; closure now requires both the baseline behavior and the driver-task substrate/migration checks above.
Title/ID: m26a-bcmgenet-driver
Goal: Preserve HAL-declared Broadcom GENETv5 NIC behavior through the isolated Pi driver runtime.
Inputs: apps/root-task/src/net/*, apps/root-task/src/drivers/driver_task_net.rs, apps/pi4-driver-runtime/src/lib.rs, crates/pi4-driver-abi/src/lib.rs, apps/root-task/src/hal/*, docs/SECURITY.md, Linux `bcmgenet` + Linux `bcm2711` DT binding notes + U-Boot `bcmgenet` bring-up notes (reference-only).
Changes:
- apps/root-task/src/drivers/driver_task_net.rs — keep root as the GENET ring client only and fail closed when isolated runtime owner-state proof is missing.
- apps/pi4-driver-runtime/src/lib.rs — carry the GENETv5 register/ring/IRQ/PHY implementation inside the isolated `driver-genet` runtime with HAL-declared MMIO/IRQ/DMA/MDIO resources only.
- apps/root-task/src/net/mod.rs + apps/root-task/src/net/stack.rs — backend selection and ring-client init wiring.
- docs/ARCHITECTURE.md + docs/SECURITY.md — record GENET design-reference provenance and explicit no-code-lift policy.
Commands:
- cargo check -p root-task
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib drivers::driver_task_net
- cargo test -p pi4-driver-runtime
- rg -n "EFI_|boot_services|runtime_services|uefi::" apps/root-task/src tools/coh-rtc/src
Checks:
- Link-up, RX/TX smoke, and deterministic error paths are covered by unit/integration tests.
- GENET hardware service remains in the isolated runtime with HAL-declared resources; root exposes only the bounded ring client.
Deliverables:
- Pi 4 GENETv5 isolated runtime backend integrated behind existing net abstractions with documented source provenance order (Linux `bcmgenet` -> Linux `bcm2711` DT -> U-Boot `bcmgenet`) and reference-only compliance.
Title/ID: m26a-static-ipv4-profile-gate
Goal: Make Pi 4 U-Boot static IPv4 config manifest-authoritative and profile-gated.
Inputs: configs/root_task.toml, tools/coh-rtc, apps/root-task/src/generated, docs/INTERFACES.md.
Changes:
- tools/coh-rtc/src/* — add IR fields + validation for `pi4-uboot-aarch64` static IPv4 network config.
- apps/root-task/src/generated/* — regenerated network config outputs.
- apps/root-task/src/net/mod.rs — consume generated profile config before dev-virt fallback defaults.
Commands:
- cargo test -p coh-rtc
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
Checks:
- Invalid static IPv4 entries fail deterministically; valid configs produce stable generated artifacts.
Deliverables:
- Manifest-driven static IPv4 for Pi 4 U-Boot profile with docs-as-built parity.
Title/ID: m26a-pi4-uboot-validation
Goal: Prove end-to-end TCP console reachability on Pi 4 using static IPv4 with no protocol drift.
Inputs: scripts/pi4-image-build.sh, docs/HARDWARE_BRINGUP.md, scripts/cohsh/boot_v0.coh.
Changes:
- docs/HARDWARE_BRINGUP.md — Pi 4 checklist, expected boot lines, static IPv4 examples.
- docs/ARCHITECTURE.md + docs/SECURITY.md — backend and threat-model updates.
Commands:
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
- cargo run -p cohsh --features tcp -- --transport tcp --tcp-host <STATIC_IP> --tcp-port 31337 --script scripts/cohsh/boot_v0.coh
Checks:
- Validation includes a before/after proof: Milestone 26 no-NIC transcript and Milestone 26a NIC-enabled transcript for the same board profile family.
- Console attach/tail/test flows are unchanged except for profile-gated backend/address selection.
Deliverables:
- Reproducible Pi 4 U-Boot network bring-up evidence and updated docs.
Title/ID: m26a-nettest-profile-gate
Goal: Extend `nettest` so the same command works on QEMU `dev-virt` and Pi 4 static IPv4 without changing console grammar.
Inputs: apps/root-task/src/net/*, apps/root-task/src/event/mod.rs, docs/INTERFACES.md, docs/USERLAND_AND_CLI.md.
Changes:
- apps/root-task/src/net/stack.rs — remove `dev-virt`-only assumptions from self-test target selection and bind probe/echo targets to the active profile-gated interface config (including Pi 4 static IPv4/gateway paths).
- apps/root-task/src/net/mod.rs — expose deterministic nettest target/report fields required by both QEMU and Pi 4 backends.
- apps/root-task/src/event/mod.rs — update `help`/`netstats` lines so `nettest` no longer appears `dev-virt`-only when built for Pi 4 profiles.
- docs/INTERFACES.md + docs/USERLAND_AND_CLI.md — document backend-agnostic `nettest` behavior and expected output fields.
Commands:
- cargo check -p root-task
- cargo test -p root-task net:: -- --nocapture
- scripts/cohesix-build-run.sh --no-run --cargo-target aarch64-unknown-none
Checks:
- `nettest` remains unchanged for QEMU (`127.0.0.1:{31338,31339}` hostfwd workflows still valid).
- Pi 4 static IPv4 profile can run `nettest` and produce deterministic pass/fail evidence with no new in-VM listeners.
- ACK/ERR/END console grammar and existing command names remain unchanged.
Deliverables:
- Single `nettest` path that is profile-gated by backend/address config and validated on both QEMU and Pi 4 static IPv4.
Milestone 26b — Pi 4 USB/Wi-Fi Driver Tasks + DHCP/Benchmark Concurrency
Status: Complete — accepted on image 7a10b8fd6acc with an image-specific
local-seat exception and separate Wi-Fi/GENET qualification.
As-built scope: HAL-admitted USB/HID and CYW43/SDIO runtimes own physical service. Root consumes bounded input/frame records. Durable, generation-bound foreground and DPC transactions preserve IRQ ordering, control-before-bulk progress, bounded recovery, DHCP, authenticated TCP and operator liveness. The retained task contracts below define the accepted timing and authority bounds.
Qualification limits: Wi-Fi is a research/diagnostic transport at its
documented worker envelope. The owner accepted the measured transport envelope
in place of the earlier 10-cold/10-warm, <=40-ms p95 and >=29-requests/s proposal;
semantic-error accounting was unchanged. In the final matrix, W04 remains an
operator-excluded RF-affected failure; cold, W01–W03, W05 and the same-image
GENET control supply the accepted evidence. No fresh key was typed in that
matrix. The owner accepted Gate 10, the one-deep idle-report queue, command
readiness, zero USB recovery/no-reply debt, healthy HDMI completions and exact
restoration of the board-proven 2668c34f76ff input path. This exception does not
prove a fresh first-byte/printable-key observation and cannot qualify a changed
physical input path. GENET production performance and Wi-Fi diagnostic evidence
remain distinct.
Evidence: Qualification and implementation records retain the boot matrices, exact provenance, excluded samples and restoration history. Driver contracts, hardware qualification and benchmarks own the reusable procedures. Historical evidence does not qualify a changed image.
Prerequisite
- Milestone 26a is complete before 26b closure, including the HAL driver-task admission substrate, serial/display isolation, GENET driver-task migration, and preserved Pi 4 GENETv5/static-IPv4 compatibility behavior.
Goal
Move USB/xHCI/HID and CYW43/SDIO Wi-Fi onto dedicated, HAL-admitted driver-task contracts, preserve DHCP and single-interface policy behavior, prove Wi-Fi/network load cannot degrade USB keyboard, serial console, or HDMI responsiveness, and close same-harness isolated runtime throughput parity for the production wired/GENET Pi path against the accepted best-QEMU reference. Wi-Fi closure proves bounded research/diagnostic transport behavior at the documented worker envelope and reports latency as physical-link evidence instead of QEMU-loopback parity.
Deliverables
- USB/xHCI/HID driver task
- Promote Pi 4 VL805/xHCI/HID keyboard service from in-root compatibility polling to a
driver-usbtask with a realtime-input scheduling contract. - Preserve the poll-only xHCI lane until hardware proves interrupt delivery; timer IRQ 27 remains timer-only evidence, not USB evidence.
- Preserve the 128 armed keyboard interrupt-IN runway, bounded HID event draining, bounded EP0
GET_REPORTinput fallback, and Gate 10 first-byte/first-printable-byte acceptance criteria. - Preserve the May 18-19 physical hub-keyboard behavior through current descriptor/owner proof, Gate 10, the exact one-deep interrupt-IN queue, command readiness, and real linked-runtime first-report/first-byte/parser/HDMI evidence. The reserved old-good ABI receipt is not currently published and is not closure authority; late Gate 10 text without the functional evidence remains insufficient.
- Root consumes only bounded local-seat byte events; it does not own xHCI registers, rings, DMA, or HID polling after driver-task handoff.
- Promote Pi 4 VL805/xHCI/HID keyboard service from in-root compatibility polling to a
- CYW43/SDIO Wi-Fi driver task
- Promote SDIO host I/O, CYW43 firmware/control plane, EAPOL admission, RX/TX queues, credit handling, and optional glom/deaggregation into
driver-wifi. - Graduate standalone
sdio-hostinto the 26b acceptance set with one HAL-declared SDHCI MMIO page, fixed-layout CMD52/CMD53/POLL_IRQ service records, atomic card-reset/pending-generation/commit records, and required owner-state proof. - Split Wi-Fi work into network-control and network-data budgets so EAPOL/DHCP/TCP ACK progress cannot be starved by bulk RX/TX, while USB/serial still preempt both.
- Preserve the May 18-19 Linux-shaped host-EAPOL order as an additive isolated runtime replay contract. Final Wi-Fi closure requires both
WIFI_GATE=10/WIFI_BLOCKER=noneandWIFI_OLDGOOD_REPLAY=yes/WIFI_OLDGOOD_MISSING=none; DHCP/netstats and condensedjoin completesummaries cannot substitute for ordered SDIO/CYW43 owner-state, control setup, association/link, M1/M2/M3/M4, PTK/GTK, secure release, DHCP, nettest, and final netstats proof. - Root receives Ethernet frames through bounded IPC/rings and never waits synchronously on SDIO credit, CMD52/CMD53 loops, firmware replies, or glom deaggregation.
- CYW43 startup preserves Linux’s
bus:rxglom=1throughevent_msgs_extandWLC_UP; aggregated RX is bounded in the driver task, and any future runtime disable/superframe expansion must run only after secure carrier proof with capped work and recovery gates. - Runtime Wi-Fi data/glom RX is separated from control-plane reply reads: control replies retain the conservative Linux first-read/remainder shape, while runtime RX uses one 512-byte block-aligned Function 2 read into the bounded 28-KiB RX partition of the compiler-declared 32-KiB shared aperture and caps deaggregation at 16 subframes plus a 16-entry ready queue.
- Promote SDIO host I/O, CYW43 firmware/control plane, EAPOL admission, RX/TX queues, credit handling, and optional glom/deaggregation into
- Normalized benchmark and isolated runtime parity gates
- Add benchmark reporting that separates raw
cohshover Pi Wi-Fi, REST cold gateway overhead, and REST hot/cache projection. - Define the accepted best-QEMU reference by artifact path, harness command, worker count, request suite, gateway/auth mode, QEMU SMP topology, pressure settings, and error-budget policy.
- Compare QEMU and Pi isolated runtime artifacts with the same harness and matched workload/provenance. QEMU results alone remain semantic/capacity references; production Pi hardware parity requires fresh wired/GENET evidence.
- Treat Wi-Fi as a separate research/diagnostic lane: the routine sustained Wi-Fi gate is capped at
120workers, exploratory pressure is capped at300workers, and1500workers is retained only as a stress ceiling for driver fault discovery. - Exclude QEMU-latency parity from pass/fail only after preserving latency fields in JSON and human summaries and verifying Pi 4 wired NIC/Wi-Fi latency remains within the documented physical-network expectations for the selected transport; throughput, successful operation count, error rate, and bounded-backpressure behavior decide the production wired/GENET verdict.
- Pi 4 performance acceptance requires zero USB/serial/HDMI responsiveness regression during Wi-Fi/NIC load and no root-owned steady-state physical-driver service path.
- Add benchmark reporting that separates raw
- Minimal DHCP core (
no_std)- Add a bounded DHCPv4 client core in root-task with strict packet validation, deterministic timers, bounded retransmits, and no dynamic protocol extensions beyond required lease fields.
- Keep memory usage fixed and auditable; no unbounded allocations, no background worker threads, and no protocol parser ambiguity.
- Interface binding: wired + Wi-Fi (profile-gated)
- Wire DHCP core to existing Pi 4 GENETv5 backend.
- Add a profile-gated Wi-Fi association + link-up path for Pi 4 CYW43xx-class devices sufficient to reach DHCP (design remains HAL-bound and capability-scoped).
- Introduce a dedicated CYW43xx Wi-Fi backend wired through HAL traits and existing
NetBackendpolicy selection; no alternate ad-hoc control path is allowed. - Record implementation provenance in docs (OpenBSD
bwfmdesign shape, Zephyr/WHD HAL layering, Linuxbrcmfmacrecovery/link edge cases) and enforce reference-only usage. - Maintain a single network control-plane surface: existing root console + NineDoor behavior only.
- U-Boot-configurable network policy
- Extend manifest/compiler schema with bounded policy fields for
pi4-uboot-aarch64, including:- network mode (
off,static,dhcp), - interface policy (
wired,wifi,auto), - bounded static IPv4 override fields (
ip,prefix_len, optionalgateway) for explicitmode=static, - DHCP timing bounds and retry limits.
- network mode (
- When bootloader setup can provide network policy inputs, capture them pre-handoff and normalize through manifest/DTB-generated structures validated by
coh-rtc. - Preserve deterministic fallback behavior when U-Boot policy inputs are missing or invalid.
- Stage an interactive Pi 4 U-Boot wizard whose
Cohesix boot menuoffersBoot with saved settingswhen coherent saved policy exists, otherwiseBoot with default settings; useAutomatic (DHCP)/Manual (static IPv4)andEthernet (wired)/Wi-Fi (wireless)choices,0Back/Cancel and9advanced-shell submenu navigation, explicit one-time versus saved restart actions, reset confirmation, USB-keyboard/HDMI-only credential capture, and optional stateful HDMI logo display without introducing any new Cohesix protocol semantics.
- Extend manifest/compiler schema with bounded policy fields for
- Backward-compatibility guardrails
- Keep QEMU
aarch64/virtbehavior for macOS/Linux unchanged by default (existing static/dev-virt flows must keep working with no required operator command changes). - Add explicit regression checks proving 26/26a/26b additions are profile-gated and do not alter prior QEMU console grammar, ACK/ERR/END behavior, or existing transport fixtures.
- Keep QEMU
Commands
cargo check -p root-taskcargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::driver_taskcargo test -p root-task --no-default-features --features driver-tests-pi4 --lib local_seat::testscargo test -p root-task --no-default-features --features driver-tests-pi4 --lib serial::testscargo test -p root-task --no-default-features --features driver-tests-pi4 --lib event::testscargo test -p root-task net:: -- --nocapturecargo test -p pi4-driver-abicargo test -p pi4-driver-runtimecargo test -p coh-rtcpython3 -m pytest tests/test_rest_perf_harness.py tests/test_pi4_compare_driver_models.pycargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsonscripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.tomlscripts/uboot/qemu-uboot-smoke.sh --net userscripts/cohesix-build-run.sh --no-run --cargo-target aarch64-unknown-nonepython3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --log-dir out/bench --log-prefix m26b-qemu-referencepython3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --no-qemu --no-gateway --rest-url http://<pi4-gateway-host>:<port> --log-dir out/bench --log-prefix m26b-pi4-linked-runtime
Checks (DoD)
driver-usbprovesUSB_GATE=10,USB_BLOCKER=none, first-byte/first-printable-byte evidence, and fast typing remains fluid while the manifest-selected network driver consumes its data budget.- Serial command echo p50/p95 and HDMI mirror progress remain bounded while Wi-Fi or wired network tasks consume their data budgets; GENET/CYW43 pre-root runtime-init may defer before the root shell when pointer-free ring proof is incomplete, and that deferral must not be counted as selected-NIC proof.
driver-wifireports bounded control/data service counters: SDIO ops, bytes, RX/TX frames, credit waits, budget exhaustion/yield count, queued frames, drops, and max service latency.driver-sdioreports dedicated-role and owner-state proof from non-root-context isolated runtime SDIO hardware progress beforesdio-hostcan count toward Pi 4 acceptance.- Wi-Fi accepts load only through the driver-task frame ABI; root never spins on SDIO credit, CMD52/CMD53 loops, firmware replies, or glom deaggregation.
- Pi 4 wired path acquires a DHCP lease within bounded retries/timeouts and exposes acquired config through existing diagnostics surfaces.
- Pi 4 Wi-Fi path (when enabled in profile and credentials are present) reaches link-up and acquires DHCP with deterministic failure modes and audited errors.
- Invalid DHCP options, malformed offers, lease overflows, and timeout exhaustion fail safely and deterministically.
- U-Boot-configurable network policy (where available) is honored through compiler-validated handoff structures; missing/unsupported bootloader policy cleanly falls back to manifest defaults.
- Existing macOS/Linux QEMU workflows remain backward compatible, including serial/TCP console behavior and existing regression fixtures.
- CYW43xx Wi-Fi path demonstrates HAL-only access in runtime code and tests; no direct MMIO/bootloader-service usage exists outside HAL-owned modules.
- Raw Pi
cohshWi-Fi latency, REST cold gateway overhead, and REST hot projection latency are reported separately; QEMU benchmark results are not used as Pi Wi-Fi hardware proof without a matched fresh Pi run. - Wi-Fi DoD uses the research envelope: a fresh
120-worker sustained run must pass the accepted error budget, retain post-load rawcohshreachability, and show clean CYW43/SDIO counters (tx_submit == tx_complete, no RX drops/overflows, no trace faults/retries outside explicitly recorded recovery).300-worker Wi-Fi runs are useful exploratory pressure, and1500-worker Wi-Fi runs are stress diagnostics rather than production or closure requirements. - A comparator identifies the selected best-QEMU benchmark artifact and the matched Pi isolated runtime artifact, rejects workload/provenance mismatches, excludes QEMU-latency parity from pass/fail, reports Pi 4 wired NIC/Wi-Fi latency against documented physical-network expectations, and reports a deterministic production PASS only when wired/GENET Pi throughput meets or exceeds QEMU with the accepted error budget.
- Isolated runtime hot-path changes remain bounded and preserve active-slot, fingerprint, completion, and busy-on-conflict invariants; no root-owned physical driver service path is added or re-enabled to win the benchmark.
- Pi benchmark evidence is fresh, non-empty, normalized, and separated from flash, shell, USB/local-seat, HDMI, and serial-responsiveness proof lanes.
- Full regression pack remains green on QEMU; any profile-gated divergence is explicitly documented and fixture-backed.
Compiler touchpoints
coh-rtcadds boundedpi4-uboot-aarch64network policy fields for mode/interface selection and DHCP retry/timing limits.coh-rtcextends driver-task contract emission for USB, CYW43/SDIO, and network-control/network-data priority classes.- Benchmark or counter fields that become generated artifacts must be covered by
scripts/check-generated.shbefore 26b closes. docs/DRIVERS.md,docs/BENCHMARKS.md,docs/TEST_PLAN.md, andscripts/ci/test_plan_run.shmust agree on which evidence is benchmark proof, board-acceptance proof, and compatibility-only proof.- Validation enforces:
- policy bounds and enum validity,
- interface/profile compatibility (wired vs Wi-Fi declarations),
- deterministic fallback policy when optional U-Boot-provided inputs are absent.
- Generated snippets in architecture/interfaces/security docs include the new policy and DHCP bounds so docs-as-built remains authoritative.
Task Breakdown
Title/ID: m26b-usb-hdmi-local-seat-liveness
Milestone: Milestone 26b — Pi 4 USB/Wi-Fi Driver Tasks + DHCP/Benchmark Concurrency / reopened USB/local-seat and HDMI liveness defect
Goal: Restore truthful and fluid physical Pi local-seat behavior during selected-network startup without changing console grammar, device authority, or Wi-Fi progress.
Inputs: crates/pi4-driver-abi/src/lib.rs, apps/pi4-driver-runtime/src/lib.rs, apps/root-task/src/{local_seat.rs,event/mod.rs,hal/driver_task.rs}, scripts/{pi4_trace_normalize.py,pi4_gate_proof.sh,pi4_serial_reboot.py}, tests/test_pi4_{trace_normalize,serial_reboot,gate_proof}.py, scripts/ci/check_driver_test_coverage.py, docs/{DRIVERS,HARDWARE_BRINGUP,TEST_PLAN,USERLAND_AND_CLI}.md, current Wi-Fi-selected Pi USB/HDMI evidence.
Changes:
- crates/pi4-driver-abi/src/lib.rs — retain one fixed 48-byte, commit-last, role-qualified USB old-good record reservation in the existing ring gap. It remains pointer-free and has no admission, command, wake, retry, recovery, scheduling, ownership, or acceptance semantics; root may passively project the zero record for compatibility.
- apps/pi4-driver-runtime/src/lib.rs — request a one-second HID idle report on the existing interrupt-IN lifetime so an unchanged keyboard establishes its safe attach baseline before the separate five-second liveness deadline, repeat only held arrow usages from the exported virtual counter and selected timer frequency, preserve make/release edges for every ordinary key, and render bounded one-row HDMI scroll steps without report-count timing or a second input/display owner. Remove the USB old-good partial/final publication state and hooks after fresh exact-image regressions at phases 198, 316, and 412, restoring the prior physical enumeration/one-deep queue path while preserving every Wi-Fi change.
- apps/root-task/src/local_seat.rs — revoke stale prompt and console-ready presentation across attach/recovery boundaries, re-release the interactive HDMI prompt after current USB command admission and display health, re-admit the ready banner after current USB command admission, retain the canonical prompt/input row until its matching display completion, preserve FIFO output and the prompt backspace floor, and chase completed viewport state through bounded receipts. Retain the bounded canonical `[local-seat] usb keyboard command-ready action=enable-command-input ...` receipt exactly once in `queen.log`, keep its verbose counter detail log-only, and do not project either through a pre-cutover raw-UART path. Restore the known-working `2668c34f76ff` command/first-report path: keep PCIe descriptor/prep and owner registration followed by USB descriptor replay/runtime init and USB owner registration before enumeration, but remove the second post-completion descriptor/owner proof scheduler and its deferred endpoint/byte cache. Valid linked input follows the existing parser-admission path once and a valid first report follows the existing command-ready transition.
HAL and gate acceptance ordinarily require current USB/PCIe owners and descriptors, Gate 10, the exact one-deep queue, and real HID/parser/HDMI liveness. The final `7a10b8fd6acc` record uses the explicit operator-approved passive local-seat exception documented in the milestone status and does not claim a fresh key byte. An ordinary pending enumeration retry retains the existing pre-prompt deferral, which grants no descriptor or owner proof authority.
- apps/root-task/src/event/mod.rs — project passive bounded USB controller, keyboard-enumeration, and first-report startup feedback, and attribute USB/HDMI SMP activity to each manifest-selected runtime core while preserving `Dispatch -> Display -> Serial` priority and granting no USB or HDMI scheduling authority. EventPump is the sole serial projector for the canonical command-ready receipt and queues it exactly once immediately before `[drivers] USB console ready` through the existing HighImpact/EventPump path. Sustained status treats the single armed interrupt-IN transfer and a zero current no-reply streak as healthy, and uses current HDMI driver-task active authority instead of cumulative submitted/completed gaps. The existing passive `usb diag`/`usb status` and `smp activity` response paths project compact current USB/PCIe owner state and the reserved zero compatibility record through the linked serial owner; they must fit the bounded line/backlog contract and cannot issue, retry, wake, or authorize hardware.
- apps/root-task/src/hal/driver_task.rs — bound the retained steady USB poll to its existing finite no-progress allowance, fail closed instead of retaining a permanently split submitted/completed request, and require a current live-complete keyboard probe rather than promoting cached readiness. Classify the existing `USB_RESET_DONE` progress edge as part of the already bounded extended controller-init/reset timeout so the following run-stage setup is not cut down to the generic three-resume allowance. Preserve an exact retained descriptor request as pending rather than projecting a terminal no-reply blocker; only its own replacement, timeout, typed fault, or fail-closed terminal may make it red. Expose one shared compact owner-state formatter sourced only from the current HAL registration and descriptor-seal truth so USB, PCIe, CYW43, SDIO, and GENET diagnostic receipts cannot drift.
- scripts/pi4_gate_proof.sh + focused gate-proof fixtures — keep passive `usb status` as the default hardware-proof action, make active `usb probe-kbd` opt-in, and accept only current end-to-end input/display receipt evidence.
- scripts/pi4_serial_reboot.py + focused helper fixtures — preserve one bounded contiguous serial stream across the `OK PING`/fresh-root-prompt read boundary so a prompt split after its first byte cannot cause a false timeout, while rejecting an interrupted or noncontiguous tail and retaining existing secret redaction. This host-only orchestration repair adds no target command, proof authority, retry, or acceptance inference.
- scripts/pi4_trace_normalize.py + focused Python fixtures — preserve the existing machine-consumed `usb-console-command-ready` token and keep display projection non-authorizing; report a command-ready boot with no current accepted linked-runtime byte as `usb-physical-input-unproven`, and never infer first-byte evidence from Gate 10 or emit a `usb-post-first-byte-*` blocker before that byte exists. Validate the current one-deep interrupt-IN queue, current no-progress/no-reply state, all exact `hdmi:` completion rows, and current USB/PCIe descriptor/owner proof without treating historical cumulative counters or the dormant receipt as live work. A pending retained descriptor identity is nonterminal; missing, replaced, timed-out, or faulted current proof remains acceptance-red. Under the reopened Wi-Fi DPC closure, scope selected-interface state separately from component-local booleans and bind DPC acceptance to the exact accounting/scope/live-ring-truth triplet, with stale client samples classified as rerun-required rather than live-ring poison.
- focused Rust tests + scripts/ci/check_driver_test_coverage.py + docs — cover readiness revocation/re-release and bounded startup feedback, map the new USB/HDMI/event/local-seat invariants to production-feature tests, and describe the as-built local-seat behavior.
- complete host-tool compatibility review — verify `coh`, `cohsh`, `hive-gateway`, SwarmUI, `tools/cohesix-py`, and the performance benchmark scripts require no implementation, fixture, schema, or workload change because the repair alters only physical local-seat projection and preserves authenticated console, Secure9P, REST, and benchmark semantics.
Commands:
- scripts/ci/test_plan_run.sh --list
- cargo fmt --all -- --check
- cargo test -p pi4-driver-runtime --lib usb_keyboard -- --test-threads=1
- cargo test -p pi4-driver-runtime --lib hdmi_runtime -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib local_seat::tests -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib event::tests -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib local_seat::tests::usb_command_ready_receipt_and_details_fit_bounded_log_records
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib event::tests::usb_console_ready_projects_canonical_receipt_once_and_first
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib event::tests::linked_usb_runtime_queue_fields_decode_first_report_telemetry
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib event::tests::hdmi_completion_status_uses_current_active_request_not_cumulative_gap -- --exact
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::driver_task::tests::usb_engine_init_controller_reset_stage_uses_extended_bounded_timeout
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::driver_task::tests::retained_usb_keyboard_poll_fails_closed_at_its_protocol_bound -- --exact
- python3 -m pytest tests/test_pi4_trace_normalize.py tests/test_pi4_serial_reboot.py tests/test_pi4_gate_proof.py -k 'usb or hdmi or local_seat or wifi_diag_complete'
- python3 scripts/ci/check_driver_test_coverage.py
- scripts/ci/check_test_plan.sh
- scripts/check-generated.sh
- cargo check -p pi4-driver-runtime --target aarch64-unknown-none
- SEL4_BUILD_DIR=seL4/build_UBOOT cargo check -p root-task --target aarch64-unknown-none --no-default-features --features release-pi4
Checks:
- Ordinary keys emit once per make/release edge; only held arrows repeat, after a 300 ms initial delay and at 50 ms intervals scaled from `CNTVCT_EL0` and `TIMER_CLOCK_HZ`, and arrow escape bytes never enter the command parser.
- HID setup requests an unchanged boot report every one second on the existing endpoint lifetime, so an idle keyboard can establish the attach baseline before the unchanged five-second exact-transfer failure deadline; no additional poll, retry, wakeup, fallback, or owner is introduced.
- A retained steady USB poll cannot remain permanently split between submitted and completed state: the existing bounded no-progress allowance terminalizes it fail-closed, and cached keyboard readiness alone cannot promote a pending live probe to attached.
- The restored `2668c34f76ff` local-seat path has no second descriptor/owner proof scheduler or deferred endpoint/byte cache after a linked completion. The established attach phase performs PCIe descriptor/prep and owner registration, then USB descriptor replay and runtime initialization; it registers the USB owner once controller init is ready, before enumeration. HAL/gate acceptance ordinarily fails closed without current USB/PCIe owner and descriptor proof, Gate 10, the exact one-deep queue, and real HID/parser/HDMI liveness. The dormant old-good receipt authorizes neither progress nor acceptance. Exact image `7a10b8fd6acc` closes only through the separately recorded operator-approved passive exception.
- `USB_RESET_DONE` retains the existing bounded extended controller-init/reset allowance; it does not create a new timeout, retry, wake, owner, or unbounded lifetime.
- The canonical command-ready receipt remains exactly once in `queen.log` and appears exactly once on serial immediately before `[drivers] USB console ready`; EventPump is the only serial projector. Before a current linked-runtime HID byte is accepted, the truthful state is `usb-physical-input-unproven`, with no post-first-byte failure classification.
- Serial remains usable during USB startup; HDMI shows bounded passive startup feedback but no interactive prompt until current USB command readiness and display health both hold. The console-ready banner is re-admitted canonically only after current USB command readiness and becomes visible only through healthy display service. Attach/recovery revokes stale first-report, command, prompt, and ready-banner presentation, and only current-lifetime proof re-releases them.
- An older HDMI completion cannot acknowledge a newer canonical input row or viewport request; FIFO output remains ordered, backspace cannot erase the prompt prefix, and rapid arrows advance one completed viewport row per bounded display turn without stale tails, full-screen blink, or unbounded queue growth.
- Passive hardware proof never turns a diagnostic into USB authority: default helpers use `usb status`, an active keyboard probe is explicit, and USB/HDMI SMP accounting names each selected runtime core from current manifest truth.
- USB remains the sole xHCI/HID owner and HDMI remains child-only. The reserved fixed USB evidence record changes no authority or command ABI semantics and runtime publication remains dormant; no parser command, `ACK`/`ERR`/`END`, network, REST, `cohsh`, or benchmark semantic changes occur.
- The exact rebuilt image preserves Wi-Fi first-pair progress and repeatedly proves USB enumeration, Gate 10, the one-deep idle-report queue, command readiness, zero current recovery/no-reply debt, and bounded HDMI completion under selected-network load. No fresh key was typed on `7a10b8fd6acc`; the closure record therefore makes no first-byte, printable-byte, arrow-history, or visible-key-echo claim.
- Matrix closure ordinarily includes one same-image functional local-seat anchor captured after `usb diag` is armed, plus passive current owner/one-deep-queue/HDMI sentinels on each network-repeatability reboot. For `7a10b8fd6acc`, the operator explicitly accepted the passive sentinels and exact known-working-path restoration without a fresh anchor; this exception is image-specific and cannot be reused after changing the physical USB path.
Deliverables: Focused source/tests/docs repair, warning-free Pi target builds, exact rebuilt image, and the operator-approved same-image USB/HDMI evidence recorded above.
Title/ID: m26b-usb-driver-task
Goal: Move Pi 4 xHCI/HID keyboard service behind the realtime USB driver-task contract.
Inputs: apps/root-task/src/local_seat.rs, apps/pi4-driver-runtime/src/lib.rs, crates/pi4-driver-abi/src/lib.rs, apps/root-task/src/event/*, scripts/pi4_trace_normalize.py, tests/test_pi4_trace_normalize.py, docs/DRIVERS.md.
Changes:
- apps/root-task/src/local_seat.rs — route local-seat keyboard-byte consumption through the isolated `driver-usb` runtime.
- apps/pi4-driver-runtime/src/lib.rs — own the direct-root-port xHCI command/event/EP0/interrupt-IN rings, root-port reset, slot/address/configuration, HID boot-protocol setup, and DMA report polling in the isolated USB runtime.
- apps/root-task/src/local_seat.rs — keep root-task as a ring-client/prompt consumer only; no root-owned USB implementation crate remains.
- apps/root-task/src/event/* — consume bounded local-seat byte events and preserve USB priority over serial dispatch and all network work.
Commands:
- cargo test -p pi4-driver-runtime --lib -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib local_seat::tests
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib event::tests
Checks:
- USB first-byte and first-printable-byte proof remain Gate 10.
- Fast typing remains fluid while network data queues are saturated.
Deliverables:
- Isolated USB keyboard task path with existing local-seat console semantics preserved.
Title/ID: m26b-wifi-driver-task
Goal: Move CYW43/SDIO Wi-Fi service behind a dedicated driver task with bounded control/data budgets.
Inputs: apps/root-task/src/drivers/driver_task_net.rs, apps/root-task/src/hal/pi4_wifi.rs, apps/root-task/src/hal/driver_task.rs, apps/pi4-driver-runtime/src/lib.rs, crates/pi4-driver-abi/src/lib.rs, apps/root-task/src/net/*, scripts/pi4_trace_normalize.py, scripts/pi4_compare_driver_models.py, tests/test_pi4_trace_normalize.py, tests/test_pi4_compare_driver_models.py, docs/DRIVERS.md.
Changes:
- apps/root-task/src/hal/pi4_wifi.rs — grant only SDIO, fixed Pi 4 WL_ON power/reset, firmware-bundle, IRQ/OOB, and DMA/ring resources declared for `driver-wifi`; `sdio-host` owns the noncontiguous firmware-mailbox page, a channel-bounded BCM2835 DMA-controller mapping, one private low request page, one low control-block page, and eight low CMD53 bounce pages after a one-way root bootstrap handoff.
- apps/root-task/src/drivers/driver_task_net.rs — keep root as the CYW43 ring client only and fail closed when isolated SDIO/CYW43 service has not returned owner progress; retain immutable firmware/control context for a complete pair replay after a partially issued bootstrap.
- crates/pi4-driver-abi/src/lib.rs + apps/pi4-driver-runtime/src/lib.rs — define fixed-layout SDIO CMD52/CMD53/POLL_IRQ plus atomic card-reset/pending-generation/commit command records and service them in the isolated SDIO runtime as the bus-owner ABI that CYW43 must use. Function enable and ALP acquisition use elapsed virtual-counter deadlines and Linux-compatible default windows rather than CPU-speed spin timing.
- apps/root-task/src/net/* + apps/root-task/src/userland/mod.rs + apps/root-task/src/event/mod.rs — consume bounded Ethernet-frame IPC without changing authenticated TCP console semantics; publish serial/local-seat first and run exactly one outer CYW43 boot episode as `attempt=1`, with no automatic whole-bootstrap backoff, reset, or attempt 2. Before the unique service-ready terminal, an uncertain exact owner may be drained and fenced but cannot restart the physical pair or renew the absolute Gate 8 deadline. Exact service readiness alone admits one later consumed-once runtime pair repair; restored service publishes `CYW43_RUNTIME_RECOVERY`, never a second bootstrap Ready. Gate-local association, DHCP, and protocol retries remain independently bounded.
Commands:
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::pi4_wifi
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib net::
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
Checks:
- Wi-Fi control progress yields on budget exhaustion instead of spinning.
- Root accepts smoltcp TX tokens into the bounded queue without mirroring firmware credit. The CYW43 runtime alone admits physical issue while its SDPCM window is open and retains the exact op7 in `WAIT_CREDIT` without a root spin or second completion boundary when it is not.
- Runtime CYW43 TX staging lets smoltcp fill the bounded SDPCM/BDC transmit frame directly instead of copying through an extra stack frame buffer.
- CYW43 startup does not write `bus:rxglom=0` before `event_msgs_ext`/`WLC_UP`; aggregated RX is bounded, counted, and recoverable inside the Wi-Fi driver task.
- A transient startup fault cannot kill the physical-Pi boot or operator surfaces. A terminal boot failure quarantines network service for that boot, reports the typed cause, and returns to the ordinary EventPump with serial, local-seat, HDMI diagnostics, authentication, and reboot live. There is no automatic second whole-bootstrap attempt.
Deliverables:
- CYW43/SDIO driver task that can make Wi-Fi progress without stealing root-task USB/serial turns.
Title/ID: m26b-sdio-host-driver-task-graduation
Goal: Graduate standalone SDIO host service from diagnostic runtime to 26b acceptance-eligible driver task.
Inputs: configs/root_task*.toml, apps/root-task/src/hal/{mod.rs,driver_task.rs,pi4_wifi.rs}, apps/pi4-driver-runtime/src/lib.rs, crates/pi4-driver-abi/src/lib.rs, scripts/pi4_gate_proof.sh, scripts/pi4_trace_normalize.py, docs/DRIVERS.md, docs/TEST_PLAN.md.
Changes:
- configs/root_task*.toml + generated manifest artifacts — declare `sdio-host` with one HAL-declared SDHCI MMIO page, one firmware-mailbox page, one channel-bounded BCM2835 DMA-controller page, ten private DMA pages, the shared budget, and `hardware_state_migrated=true`.
- apps/root-task/src/hal/* — map SDHCI into the SDIO isolated runtime resource set, keep runtime commands pointer-free, and register `sdio-host` owner-state only after non-root-context CMD52/CMD53/POLL_IRQ hardware progress.
- scripts/pi4_gate_proof.sh + scripts/pi4_trace_normalize.py — require SDIO dedicated-role and owner-state evidence as part of reopened 26a/26b Pi 4 acceptance.
- docs/BUILD_PLAN.md + docs/DRIVERS.md + docs/TEST_PLAN.md + docs/HARDWARE_BRINGUP.md — record SDIO as a 26b acceptance hot path rather than a future diagnostic guard.
Commands:
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::driver_task
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::pi4_wifi
- cargo test -p pi4-driver-runtime
- python3 -m pytest -q tests/test_pi4_gate_proof.py tests/test_pi4_trace_normalize.py
- scripts/check-generated.sh
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
Checks:
- Generated Pi 4 specs report `sdio-host root_context_required=false hardware_state_migrated=true mmio_pages=3 dma_pages=10`.
- `scripts/pi4_gate_proof.sh --require-driver-task-proof` requires `DRIVER_TASK_SDIO_DEDICATED=yes` and a `DRIVER_TASK_OWNER_STATE ... hot_path=sdio-host ... root_pointer=no` descriptor.
- SDIO production ring commands do not carry `DRIVER_TASK_RING_FLAG_ROOT_CONTEXT_NON_ACCEPTANCE`; root-context diagnostic turns remain explicitly non-acceptance.
Deliverables:
- SDIO runtime acceptance promotion with generated, code, proof-gate, and docs-as-built alignment.
Title/ID: m26b-wifi-sdio-notification-dpc-closure
Goal: Restore the original 26b root-no-wait CYW43/SDIO contract with one durable persistent op11 transaction, one typed intake-sealed Host-EAPOL finite-op7 key-response transaction, one generation-long post-release DPC activation, a disjoint commit-last sideband RX/ACK handoff, a generated reciprocal notification topology, one bounded event-sequence DPC lease from the first post-release event through steady service, and fault-only deadline containment that cannot become a traffic scheduler.
Inputs: configs/root_task*.toml, tools/coh-rtc/src/{ir.rs,codegen/**}, apps/root-task/src/generated/**, crates/pi4-driver-abi/src/lib.rs, apps/root-task/src/{drivers/driver_task_net.rs,event/mod.rs,hal/{mod.rs,driver_task.rs}}, apps/pi4-driver-runtime/src/lib.rs, scripts/{pi4_trace_normalize.py,pi4_gate_proof.sh,pi4_serial_reboot.py}, scripts/ci/check_driver_test_coverage.py, tests/test_pi4_{trace_normalize,serial_reboot}.py, docs/{DRIVERS,HARDWARE_BRINGUP,TEST_PLAN}.md, fresh Pi serial/pcap evidence gathered during Milestone 26d.
Changes:
- The generated reciprocal topology gives SDIO sole physical issue/IRQ ownership and CYW43 sole protocol/DPC ownership. Root is a bounded ring client. Sequence-last records bind each command, completion, RX batch, ACK and continuation to the exact physical epoch, generation and consumer sequence; badges supply wake hints only.
- Persistent op11 crosses one HAL admission, commit and signal and remains owned until terminal. Finite urgent Host-EAPOL op7 uses a typed intake seal and the existing four-operation parent. Missing or competing seals return typed zero-I/O terminals. Other foreground work retains its exact grant/endpoint contract; no second root grant or independent issuer advances a persistent child.
- Generation-long post-release DPC service retains software-pending work and wire order. Private phases run to bounded quiescence; exact child, credit, queue and peer waits block immediately after the final durable-state recheck. Coalesced notifications neither lose retained work nor authorize new work. Terminal IRQ closure, empty-ring rearm and disjoint commit-last RX/ACK handoff retain the accepted owner lifetime.
- One no-allocation bootstrap/recovery supervisor owns the outer boot episode, initial physical pair and every later whole-pair recovery. Recovery records retain both current recovery and unresolved-action owner generations. Steady service cannot clear sticky failure, revive an old generation or become a deadline/hintless recovery scheduler.
- TX submission is queue-only. The generation-scoped two-class queue has aggregate capacity 16; urgent/control traffic precedes bulk without changing admitted op7 cadence. An issued owner retires before promotion, committed RX has priority, joined Function-2 completion releases the root parent, and SDPCM tx_max remains runtime admission. Current causal PTK successors and reserved response space survive bounded rotation without another issuer.
- Join keeps logical connection identity separate from physical bus epochs and retains its outer lease across named waits. EAPOL M2/M4/group-key replies use the sealed finite parent; pending CARD_INT cannot reject an already sealed data write. Accepted timing, register order, retries, fairness, pair restart, DHCP and local-seat contracts remain owned by the detailed checks and DRIVERS.md.
- Non-authoritative diagnostics distinguish active owner state from stale compatibility snapshots. Current acceptance requires ABI v8 sealed-owner proof and exact nonzero diagnostic/pair/generation identity; older trace formats remain readable historical evidence. Counter normalization and gate validation reject missing, mixed, stale or poisoned ownership evidence.
- Host tools, Python, SwarmUI, generated consumers and raw/REST benchmarks retain their public grammar, authority and workload contracts. Only affected diagnostic/proof readers track the versioned records. Exact-image multi-boot transport and unchanged USB/serial/HDMI evidence remain separate from pure-contract or source checks.
Commands:
- cargo test -p coh-rtc
- cargo test -p pi4-driver-abi
- cargo test -p pi4-driver-runtime
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::driver_task
- cargo test -p pi4-driver-abi cyw43_dpc_client_layout_is_bounded_and_sequence_last
- cargo test -p pi4-driver-runtime cyw43_dpc_client_record_is_current_sequence_last_and_passive
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::driver_task::tests::cyw43_dpc_client_reader_is_stable_passive_and_sequence_last
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib event::tests::wifi_diag_authority_lines_fit_the_untruncated_console_budget
- python3 -m pytest -q tests/test_pi4_wifi_repeatability.py tests/test_pi4_trace_normalize.py
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- scripts/check-generated.sh
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
Checks:
- The current DPC-client record is exactly 128 bytes, 64-byte aligned at offset 49,984, ends at 50,112 without overlap, commits the nonzero publication sequence last, and is read only as one passive `ring -> record -> ring` snapshot. Exact physical epoch and live consumer sequence are mandatory; transient staleness requests a bounded rerun and never becomes recovery or owner authority.
- Retained Gate 7 and current Gate 8 proof share one exact nonzero diagnostic id, pair, and generation between matching `diag_begin` and `diag_complete` records. Any clipped proof may be recovered only from that current terminal identity; malformed or cross-transaction evidence revokes acceptance.
- HAL does not release an exact op11 at raw ring observation. It replaces the cleared active request with a sequence-last semantic-terminal receipt binding request, command fingerprint, logical `aux1`, and physical pair epoch. That receipt and the logical owner remain authoritative until the canonical consumer commits the copied or routed body and the complete outer policy turn compare-clears them. An interleaved physical terminal clears only its receipt and preserves the logical op11 owner; dropped, uncommitted, mismatched, or orphaned retirement authority fails closed through the existing pair-recovery lane.
- Focused production-path root/HAL coverage proves healthy logical terminal retirement, interleaved physical-only retirement, recovery becoming sticky before canonical consumption, and successor fencing when an outer-turn finalizer is omitted. Construction-level raw-token-drop coverage proves that uncommitted authority fails closed; receipt matching separately proves every exact identity field gates release. Claims about duplicate or mismatch behavior require a production-reachable receipt test before publication.
- EventPump derives one immutable canonical-owner snapshot and one combined service-routing snapshot per active outer policy turn, so repeated scheduling questions do not reconstruct staged WiFi payload identity or stable-read the same op7/op8/op11 and DPC state. Both snapshots are typed hints only: final consumer/HAL admission revalidate exact state, while the explicit before-sleep boundary double-samples a narrow current-lifetime and durable-level cut and HAL rechecks the active parent's sequence-last completion or op8 grant. Fresh DPC/runtime/root RX, control, requestless policy, or exact-parent progress overrides an idle same-turn routing hint; a merely waiting parent masks identity-only policy levels plus retained TCP flush, console, and ICMP demand and cannot hot-run, while independent committed driver progress still resumes the same episode. The finalizer invalidates both hints, outside-turn diagnostics bypass them, and no hint can issue, complete, retire, recover, or create notification-history authority.
- Generation vocabulary is explicit throughout these checks: a root/CYW43 parent generation is logical connection identity, while a DPC ring generation is the generated physical bus-link epoch. Phrases such as `same-generation DPC ring` mean the same physical bus-link epoch and never authorize comparing it with parent `aux1`.
- Generated topology contains exactly one SDIO physical owner for level-triggered SDHCI IRQ 158 and DMA channel-4 IRQ 116 plus one reciprocal `cyw43-sdio` link with bounded notification slots and four-entry event ring; malformed, split-owner, overlapping, unbounded, or unknown topology fails validation. PIO reaches one terminal from its SDHCI/host conditions with zero DMA use; external DMA joins the two IRQ results into one terminal for the immutable request in either arrival order.
- A condition-first SDIO terminal cannot retire its cursor before the sole owner has closed the matching IRQ158 episode: request-owned residual bits are W1C/read-back exact, any visible or crossing `CARD_INT` is committed before exact handler ACK, otherwise crossing-safe rearm completes before the child terminal. An external-DMA terminal also joins exact IRQ116 ACK. Intake-sealed and active one-way children emit zero event/IRQ peer hints before completion commit and exactly one generic hint after sequence-last terminal; failed commit emits zero, while a standalone idle crossing emits one immediate post-event hint. The final valid-empty-ring/masked-`CARD_INT` level is serviced without a queued command and cannot require notification history.
- Healthy current-physical-epoch activation is reused across the full control lifetime: only an explicitly owner-active, empty, unmasked ring reaches the Function-2 fence without a `DPC_ACTIVATE` child, while one visible front event is bound by exact sequence until its durable consumed watermark and later events cannot starve TX. Only when activation/mask state is absent or skewed may the physical-generation-bound Join source probe be admitted; if one IRQ158 ACK epoch becomes pending after its exact frontier is submitted, that same probe ACKs the epoch, commits cleared health, and reconciles state with zero SDHCI command issue before the parent continues. Removing or mutating the exact frontier, losing or replacing a bound event without consumed proof, wrong physical generation, absent owner-active proof, owner poison, invalid/poisoned/overrun ring, partial marker, and every non-activation child under the same unhealthy condition remain rejected. A failed final idle rearm records `DRIVER_RUNTIME_REJECT_SDIO_DPC_SOURCE_REARM_FAILED` rather than allowing the next child to appear marker-invalid.
- Root never waits synchronously on SDIO credit, CMD52/CMD53, firmware replies, or glom work; durable DPC/transaction progress remains inside the isolated SDIO/CYW43 runtimes, notifications remain hints only, and pointer-free active-slot bounds hold. A stable `Waiting` result for the exact issued persistent op11 suppresses only that parent's root self-demand; independent committed DPC/RX work and `TerminalVisible` cannot be masked.
- Driver-runtime ABI v8 wait-receipt tests prove exact offset 40, exact 24-byte size and distinct magic; logical generation zero; body clean/barrier and commit-last publication; a producer-monotonic nonzero epoch with overflow failure; root stable double-read; and rejection of torn, stale, wrong-request, wrong-fingerprint, wrong-generation, wrong-epoch, or wrong-commit state. Production composition crosses `Stage -> CommitRing -> Issued`, exactly one signal, prompt same-parent re-admission through Open and bounded Closing, exact receipt or terminal, ordinary park, later exact-terminal resume, semantic consumption, and deterministic lease release. It covers Stage clearing, changed-condition clearing, terminal-before-receipt, terminal-after-receipt, publish/clear failure, clear-before-wake interpretation, and proves receipt and terminal are alternative handoff proofs rather than simultaneous authority. It admits no second request, grant, signal, issue, rescue wake, unrelated NIC owner, idle policy gap, or duplicate path.
- Driver-runtime ABI v7 placed the 128-byte episode ledger exactly at shared offset 49,344 with its publication sequence committed in the final word; ABI v8 retains that ledger unchanged and non-authoritative. Stable, staged, torn, stale-version, wrong-sequence, overlapping foreground/DPC, PIO, DMA, queue-only-op8, prewait, fairness, first-fault-dominant, reset, transaction-clear, and pair-scrub tests preserve one diagnostic identity without changing any command, notification, operation, retry, deadline, recovery, or queue count. The exact child descriptor records its selected PIO/DMA and required IRQ contract while the child-terminal flag distinguishes an expected active contract from a completed owner join. A condition changed across passive publication prevents sleep, and completion signalling precedes diagnostic work. Root rejects unstable records and emits at most one bounded `CYW43_BUS_EPISODE` line per `wifi diag`; current trace/gate fixtures require descriptor version 8 and reject version 7 or earlier as historical-only evidence.
- An accepted normal exact `SteadyLease` completion releases the old global child before one bounded deterministic private `FifoWindow` `AdvanceState` transition may claim and publish exactly one successor. That CYW43 call returns at the successor's external child wait and performs no physical issue. Focused coverage compositionally proves the old terminal mailbox is stable-read into its immutable accepted CYW43 trace entry before coherent successor staging reuses the sequential mailbox, and `OrdinaryContinuation`, `RxQuantumBoundary`, `RxQueueWait`, `RecoverySettle`, `CompleteEvent`, `DeferredOwner`, contained or fatal fault, malformed identity, issued-unknown, quarantine, and recovery produce no same-call successor. The one-child-at-a-time invariant, later SDIO-only issue, foreground fairness, and zero new poll, signal, priority, EventPump, GENET, or authority behavior remain explicit.
- The production reciprocal ring has one CYW43 producer and one SDIO physical owner. Non-op11 foreground commands preserve their exact endpoint/grant cadence. The finite urgent-op7 lease preserves its identity and budget, while its current durable condition decides the handoff: deterministic private phases continue even on an equal snapshot, and an exact child, credit, queue, or peer wait blocks immediately even when newly observed. An exact op11 crosses one sequence-last parent commit and exactly one root notification, stays `Issued` through every completion miss, and reaches one terminal with zero recurrent root grants or notification signals. Interleaved EVENT/DATA is delivered through the committed sideband batch plus exact disjoint ACK without completing or republishing op11. Each derived SDIO child carries the paired persistent marker and reaches its terminal under the sole SDIO owner with zero delegated grants. The one post-release activation remains valid for the physical generation; ordinary controls do not manufacture a new activation child. Before every persistent Function-2 child issues, the same owner proves a healthy empty same-generation DPC ring and physical `CARD_INT` enable; masked-empty state is rearmed and durably committed, pending source work defers without issue, and health or ACK debt fails closed. The final ring/register/source sample is the issue linearization point for both PIO and DMA. A committed sequence-last SDIO command always reaches matching owner dispatch; a missing or competing seal produces a typed zero-I/O terminal rather than disappearing as no intake. From the first post-release DPC event, the separate event-sequence steady lease is the only production DPC child mode and never falls back to ordinary recurrent grants based on Gate 8 state. Each immutable hardware request issues at most once; bounded condition-driven private progress may traverse consecutive owner-loop iterations to quiescence without a yield, while SDIO alone preserves one live joined-hardware sample after a changed steady cursor before blocking. Its final idle boundary rechecks the ring-only one-way intake, and a fresh command re-enters arbitration without another signal. Non-CYW43 retained endpoints cannot substitute for any boundary. The RX handoff above the CYW43 runtime is batch-shaped: a full 256-frame software backlog requires 32 committed eight-frame parents rather than 256 per-frame root grants, terminals, or notification signals. Current flags and pending state, not historical `ack_failures`, decide admission; DPC overrun and ACK-attempt counters are scoped to the current physical pair and reset on pair replacement. Every blockable active SDIO phase publishes its exact physical-lifetime counter deadline, including pre-issue inhibit/status-clear; containment clock settle publishes the earlier settle/overall expiry. Phase progress refreshes or clears the arm, terminal/reset clears it before publication, ordinary service records no hint, and an unchanged expired arm permits at most one root-to-CYW43-to-SDIO fault hint before SDIO alone terminalizes or contains it. EventPump/NetStack have no private Wi-Fi EAPOL, pre-root, tail-ingest, TCP-flush, hot-dispatch, or device-operation burst; stale completions and issued-unknown actions cannot mutate or replay into a replacement generation.
- Real production-chain tests drive an exact op11 through one HAL admission with zero root continuation-grant publications, prove there is no grant 19 or second root notification after the `PreTxDrain -> WaitCredit` transition, and then drive its marker-paired cached-window F2 child to one terminal with no delegated grant. Focused scheduler coverage proves an owner-active healthy physical epoch reaches `PreTxDrain` without a `DPC_ACTIVATE` child; a committed front event binds exactly one attempt-scoped sequence, services that event through canonical DPC from `PreTxDpcProbe` without another wake, and advances after durable consumed proof even if a later event is queued. Wrapped sequence zero remains valid, and a missing or replaced bound event quarantines rather than creating activation work. Equal snapshots in deterministic private phases still route to `ContinueToQuiescence`, while exact child, credit, queue, and peer waits route to `WaitForWake` regardless of snapshot novelty; SDIO steady coverage separately preserves one changed-cursor live joined-hardware sample before blocking. A separate masked/ACK-pending production-chain test drives one marked logical-generation-zero persistent op11 through the retained `DPC_ACTIVATE` repair state machine, production SDIO intake and owner dispatch, a sequence-last terminal commit, a coalesced notification, and hintless exact-parent replay. The healthy control-lifetime composition then reuses the independent physical epoch, canonically consumes an owner-published source event, issues one persistent Function-2 TX child with exact terminal replay and no continuation grant, takes modeled IRQ158/CARD_INT capture through durable publication and Function-2 RX, publishes the control queue, and completes from the matching CONTROL reply. That Function-2 child must inherit the pre-TX arm fence even when its parent control flags are zero. Focused PIO and external-DMA tests prove masked-empty rearm and committed owner-active unmasked health before one command; existing-event and physical-source crossings produce a typed zero-I/O defer; event-plus-unmasked, ACK debt, bad epoch, absent activation, poison, and enable mismatch fail closed without command or DMA. Seal-conflict coverage proves an already committed command reaches a typed zero-I/O busy/missing-seal terminal and cannot be discarded as no intake. Tests separately exercise persistent op11 at logical generation zero and nonzero generations against a different physical epoch, prove parent `aux1` remains logical while every physical child uses the physical epoch, root masking for exact persistent-op11 `Waiting` without masking independent DPC/RX/sideband/deadline or `TerminalVisible`, the first post-release DPC event selecting the exact event lease before Gate 8 with no continuation grant, a PIO child terminalizing from IRQ158/host state with zero DMA use, external-DMA children joining IRQ158/IRQ116 in both arrival orders, an immediate terminal committed just before sleep, and missing, coalesced, and repeated notification hints. The idle-owner test commits a fresh ring-only one-way child after the earlier intake sample and requires the final sequence-last command-ring check to re-enter arbitration without another hint. Ordinary post-TX `WaitReply` must block because its current durable condition is an external peer wait, regardless of whether that condition was just observed, resume only for real CARD_INT/DPC/RX/credit/child-terminal progress, and record zero forced source probes or ordinary-traffic deadline hints. Production-reachable dependency tests retain a real op11 in `WaitReply` and a tagged no-credit op7 in `WAIT_CREDIT`, publish a current-physical-epoch DPC event after the original foreground watermark, and prove current durable state preflights that event despite a coalesced hint; the same sealed op7 then reaches its exact Function-2 child without a root or delegated continuation grant. The finite urgent-op7 lease and every non-op11 foreground retained grant cadence, including non-op11 bootstrap/recovery, receive regression coverage. Further production-chain coverage drives normal control and EAPOL TX through one cached-window F2 child, a genuine cold-window miss through exactly LOW/MID/HIGH/F2 with no steady-state IORx child, the 20-command post-F2 release culminating in the generation's one real DPC activation, and one physical DPC RX episode into the committed queue/batch handoff. The eight-frame case produces one immutable op8 parent and one terminal, survives missing/coalesced/repeated hints, and rejects torn queue/batch commits, stale logical or physical generation, mismatched queue commit or parent sequence, invalid entry bounds, and an authority-bearing header change during copy; a change confined to the passive packed timing word instead preserves the payload and exact ACK while degrading both timing halves to UNKNOWN. The same batch under active op11 must be nonterminal, deliver once, and advance only after the exact disjoint ACK commits last. A failed IRQ ACK followed by exact recovery clears current authority flags while retaining per-pair history and healthy admission. Deadline-arm tests cover phase selection for every timed autonomous owner wait, exact pre-issue inhibit and status-clear expiry publication, earlier settle/overall containment selection, body-before-commit, clear-before-terminal/reset, fail-closed handling when a blockable phase lacks a counter deadline, one stable-expired root-to-CYW43-to-SDIO hint, terminal-before-deadline, and zero ordinary-traffic hints. Reapplying one event's immutable frame hint, fabricating mailbox readiness or a terminal stream, substituting generic card commands for CMD52, or directly completing DPC activation fails this coverage.
- Diagnostic split tests prove v3 size/offset/version stability, raw-zero and modulo-wrap handling, Q11 floor/saturation, first-`CHANNEL_DATA` selection after an EVENT, post-queue-commit admission stamping, physical-slot reorder/clear, stable-copy coverage, and sequence-last publication. They also prove body validity ignores the passive word and a timing-only stable-sample mismatch yields `0xffff/0xffff` without batch rejection or recovery. Every split field's leading `n` remains visible coverage but may legitimately be below `rx2a_mod32 n`, because only the first DATA entry in a batch carries the packed word; each missing, saturated, or invalid sample is individually UNKNOWN. The bottleneck decision is complete only when the valid same-sample `slow.total` equals `rx2a_mod32.max`; if `slow.total` is smaller, the worst sample remains UNKNOWN. The `slow=<total>/<s2q>/<q2p>/<p2r>/<r2a>` tuple must come from that single valid sample rather than mixing independent per-stage maxima.
- The retained supervisor remains live after initial network attachment and deterministically owns every sticky pair, generation, association, EAPOL, and data recovery. Steady paths publish only an immutable recovery record that binds both the current recovery generation and the unresolved action's owner generation, then perform lock-free admission fencing. A logical association-epoch change or pair-restart signal while an op11 join cursor is unresolved retains that cursor's original owner generation and exact descriptor, payload digest, and ticket under the current recovery generation; it cannot collapse the cursor into an empty pair signal. After guards unwind, the supervisor alone clears retained session state and poisons the current generation. The sole outer boot episode is always `attempt=1`, admits one initial physical pair, and has zero pre-service pair-repair budget. Gate-local association, DHCP, and protocol retries remain bounded inside their owning gates, while Gate 8 commit, DHCP, and listener admission share the original absolute deadline. A pre-service physical fault drains/fences ownership and terminates/quarantines instead of opening pair 2. Exact service readiness alone admits one later consumed-once runtime repair; duplicate Ready cannot replenish it, and restored new-generation service uses `CYW43_RUNTIME_RECOVERY` before one later episode can be re-armed. Gate 10 remains downstream acceptance proof, not recovery authority. A lease conflict before issue that changed no scheduler state fails locally, while issued or scheduler-mutating uncertainty requires the bounded runtime repair. Duplicate current records coalesce, stale records cannot mask current faults, and neither can relock a steady session, replay a child operation, or mutate a replacement generation. Terminal boot failure quarantines network service and returns to ordinary operator service; recovery fencing never prevents independent linked serial, buffered local-seat input, HDMI status, timer/IPC, authentication, diagnostics, or reboot dispatch from remaining bounded and available.
- Host tests execute the production descriptor-validation and SDHCI owner-transfer path through an injected deterministic controller model; cut every whole action in the production pair-restart schedule with stateful register/resume/ready/descriptor/engine transitions; inject each modeled CARD_INT and notification/IRQ substep plus persistent outer-suspend and CARD_INT-mask failures; and prove continuously reasserted CARD_INT remains bounded without weakening quarantine or issued-unknown ownership.
- Fresh repeated Wi-Fi boots show no `DRIVER_TASK_NOTIFICATION_BIND_DEFERRED`, no DPC-ring overrun/drop, no IRQ-ACK failure, `sdio_deadline_hints=0` during ordinary traffic, ordered control/event/data delivery, working DHCP/TCP/cohsh, and unchanged serial/USB/local-seat gates. Per-pair counters are evaluated separately for every physical lifetime and must not be stitched across a restart.
Deliverables:
- Generated reciprocal CYW43/SDIO notification contract, typed persistent op11 parent/child ABI, typed commit-last wait receipt, fixed bounded DPC event-ring ABI, diagnostic-only scrub-surviving episode ledger, isolated-runtime implementation, deterministic offline fault/schedule coverage, exact-image repeatability gate, docs-as-built alignment, and repeatable Wi-Fi TCP evidence.
Title/ID: m26b-net-control-priority
Goal: Split network-control and network-data work so EAPOL/DHCP/TCP ACK progress is prioritized without starving physical input.
Inputs: apps/root-task/src/net/*, apps/root-task/src/drivers/driver_task_net.rs, apps/pi4-driver-runtime/src/lib.rs, apps/root-task/src/event/*.
Changes:
- apps/root-task/src/net/* — add diagnostics and scheduling hooks for network-control vs network-data service classes.
- apps/root-task/src/drivers/driver_task_net.rs + apps/pi4-driver-runtime/src/lib.rs — expose ring-client/runtime counters for EAPOL/DHCP/control progress and bulk RX/TX data. Admit CYW43 stack output through one generation-scoped bounded aggregate of 16 immutable frames, represented as urgent-control and bulk FIFO classes but feeding the sole active op7 owner. ARP, EAPOL, DHCP, TCP SYN/FIN/RST, payload-free TCP control frames, and any copied-RX paired response are urgent; other payload-bearing TCP and fragmented or ordinary data remain bulk; FIFO order is preserved within each class. Ordinary TxTokens reserve at most 15 aggregate slots; a TxToken paired with copied RX may reserve the final slot before RX dequeue, and consumption remains queue-only. EventPump is the sole production TX coordinator. An exact retained foreign HAL descriptor, including NetData op8, is non-revocable and keeps op7 queued/requestless without spending TX budget, deadline, or recovery. An already-started op7 remains exact and advances to its terminal. Before promoting a fresh or requestless op7, however, one committed copied/DPC/runtime RX level receives the next bounded drain/op8 turn so an immediate peer reply cannot sit behind a later DHCP or TCP retransmit. At full capacity, promotion removes one eligible head and restores a paired slot before its one advance. A terminal never promotes a successor; that frame remains queued for a later EventPump coordinator turn. `Device::receive` and reservation failure do not service TX. Promotion starts the sole op7 lifetime without a root-owned predecessor-credit gate. The runtime alone owns `sdpcm_seq` and the dongle-advertised `tx_max` admission window; an exhausted window retains the same op7 in `WAIT_CREDIT` until DPC commits a newer window. The exact joined Function-2 terminal releases the root frame and may advance its ordered logical continuation without a later RX acknowledgement. A stable committed terminal wins before lifetime policy; a terminal-absent `Waiting` op7 remains retained only while its exact generation, pair epoch, and physical-lifetime epoch are current, and an invalidated lifetime enters the sole pair-recovery lane without replay. Generation/reset purges never-issued queued frames, while an issued or otherwise ambiguous active op7 deadline remains fail-closed; GENET is excluded.
- apps/root-task/src/event/* — preserve actual serial/local-seat input and physical-response priority before either network class. For selected CYW43 only, a complete command belonging to the exact active authenticated connection may end its Network quantum and use the next existing hardware-free `Dispatch` turn before passive USB service debt. Its response advances only through the existing bounded connection-owned flush cursor; after any exact retained parent receives its current already-admitted turn, cursor completion hands passive USB debt the ordinary `Serial -> LocalSeat -> Dispatch` rotation before another buffered command. GENET and unauthenticated, stale-connection, physical-input, or response-tail cases retain the ordinary phase rotation.
- Cross-task boundary (`m26b-net-control-priority` with `m26b-wifi-sdio-notification-dpc-closure`) — the root rule that an op7 terminal cannot promote a queued successor is unchanged. The only same-call continuation is inside one already-admitted CYW43 DPC runtime invocation after a normal exact `SteadyLease` child terminal: one bounded deterministic private `FifoWindow` `AdvanceState` transition may publish at most one next DPC child, which SDIO can issue only on its own later owner turn. `OrdinaryContinuation`, `RxQuantumBoundary`, `RxQueueWait`, `RecoverySettle`, `CompleteEvent`, `DeferredOwner`, fault, and every other external-wait boundary remain later-turn. It creates no EventPump admission, priority episode, physical-operation burst, or authority path.
Commands:
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib event::tests
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib net::
Checks:
- Synthetic Wi-Fi data backlog cannot delay keyboard bytes or serial command echo.
- Control traffic is not blocked behind bulk data queue pressure. A received DHCP Offer cannot remain head-of-line behind the next retained Discover TX terminal.
- An exact authenticated CYW43 command dispatches in a separate hardware-free outer turn before passive USB service debt, while actual input and physical response tails still preempt it and continuous TCP cannot defer one post-cursor USB rotation.
Deliverables:
- Observable network-control/data scheduling contract for Pi 4 Wi-Fi and future high-performance drivers.
Title/ID: m26b-rest-normalized-parity
Goal: Reframe Wi-Fi performance proof as raw Pi Wi-Fi latency plus measured REST gateway overhead.
Inputs: scripts/rest_perf_harness.py, docs/BENCHMARKS.md, apps/hive-gateway/src/main.rs, apps/cohsh/src/transport/tcp.rs.
Changes:
- scripts/rest_perf_harness.py — report raw/cold/hot modes separately and preserve no-retry failure accounting.
- docs/BENCHMARKS.md — distinguish QEMU loopback capacity from Pi Wi-Fi physical proof.
- apps/hive-gateway/src/main.rs — preserve cache/coalescing as host-side projection only; no write bypass.
Commands:
- .venv/bin/python -m pytest -q tests/test_rest_perf_harness.py
- cargo run -p cohsh --features tcp -- --transport tcp --tcp-host <wifi-lease-ip> --tcp-port 31337 --auth-token <token> --script scripts/cohsh/boot_v0.coh
- python3 scripts/rest_perf_harness.py --mode perf --rest-url <pi4-rest-url> --suite status --runs 20 --no-transient-retries
Checks:
- REST cold p95 is reported as raw `cohsh` p95 plus gateway overhead.
- Hot projection results are labeled separately and cannot satisfy raw Wi-Fi hardware gates.
Deliverables:
- Honest Pi Wi-Fi benchmark model that optimizes toward QEMU semantics without claiming impossible physical loopback parity.
Title/ID: m26b-benchmark-comparator
Goal: Define and enforce same-harness QEMU-vs-Pi isolated runtime throughput parity while evaluating Pi latency against documented physical-network norms instead of QEMU loopback parity.
Inputs: scripts/rest_perf_harness.py, tests/test_rest_perf_harness.py, tests/test_pi4_compare_driver_models.py, docs/BENCHMARKS.md, existing out/bench QEMU and Pi summaries.
Changes:
- scripts/rest_perf_harness.py or scripts/pi4_compare_driver_models.py — emit/compare benchmark provenance, reject mismatched workloads, and calculate pass/fail from throughput/error metrics only.
- tests/test_rest_perf_harness.py and tests/test_pi4_compare_driver_models.py — cover matched PASS, throughput FAIL, workload mismatch, stale-artifact rejection, and latency-excluded verdict behavior.
- docs/BENCHMARKS.md — document the best-QEMU selection rule, Pi artifact requirements, and latency-exclusion rule.
Commands:
- python3 -m pytest tests/test_rest_perf_harness.py tests/test_pi4_compare_driver_models.py
Checks: comparator rejects stale or mismatched artifacts and produces deterministic PASS/FAIL for matched QEMU/Pi runs without using QEMU latency parity as a verdict metric; it still flags Pi wired NIC/Wi-Fi latency outside documented industry-normal physical LAN/control-plane ranges.
Deliverables: benchmark comparator, tests, and documented parity rule.
Title/ID: m26b-linked-runtime-counters
Goal: Add bounded counters required to explain isolated runtime benchmark misses without UART spam.
Inputs: crates/pi4-driver-abi, apps/pi4-driver-runtime, apps/root-task/src/hal/driver_task.rs, apps/root-task/src/drivers/driver_task_net.rs.
Changes:
- crates/pi4-driver-abi/src/** — fixed-layout counter fields for turns, drained descriptors, staged bytes, cache work, busy/backpressure, and overruns where existing records are insufficient.
- apps/pi4-driver-runtime/src/** — update counters inside GENET, CYW43, SDIO, USB, HDMI, serial, and PCIe service loops.
- apps/root-task/src/hal/driver_task.rs and apps/root-task/src/drivers/driver_task_net.rs — expose bounded, activity-gated counter snapshots through existing diagnostics/evidence surfaces.
- scripts/pi4_trace_normalize.py + tests/test_pi4_trace_normalize.py — normalize `DRIVER_TASK_COUNTER_*` fields, reject empty or truncated counter lines through `DRIVER_TASK_COUNTER_INVALID`, and keep counters diagnostic-only.
Commands:
- cargo test -p pi4-driver-abi
- cargo test -p pi4-driver-runtime
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib drivers::driver_task_net
- python3 -m pytest -q tests/test_pi4_trace_normalize.py
Checks: counters are fixed-layout, bounded, non-authority-bearing, activity-gated, not updated from polling-loop atomics, normalized with `DRIVER_TASK_COUNTER_INVALID=0`, and do not change console grammar or Secure9P semantics.
Deliverables: counter ABI, runtime updates, root-side evidence snapshots, normalizer guard fields, and tests.
Title/ID: m26b-linked-driver-hotpath-closure
Goal: Remove avoidable single-frame or single-descriptor overhead while preserving isolated runtime active-slot invariants.
Inputs: apps/pi4-driver-runtime, crates/pi4-driver-abi, apps/root-task/src/hal/driver_task.rs, docs/DRIVERS.md.
Changes:
- apps/pi4-driver-runtime/src/** — bounded local batching for descriptor drain, cache maintenance, completion publication, and telemetry counters where benchmark evidence shows contention.
- crates/pi4-driver-abi/src/** — fixed burst bounds and max-turn evidence where ABI fields are needed.
- apps/root-task/src/hal/driver_task.rs — preserve staged active-slot submit, range validation, busy-on-conflict, and completion publication under batching.
Commands:
- cargo test -p pi4-driver-abi
- cargo test -p pi4-driver-runtime
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib
Checks: batching is bounded, cannot overwrite active payload-bearing turns, and does not add root-owned physical-driver service.
Deliverables: lower-contention isolated runtime hot paths with contract-local backpressure evidence.
Title/ID: m26b-target-benchmark-proof
Goal: Produce fresh same-harness QEMU and Pi 4 isolated runtime benchmark evidence before 26b closes.
Inputs: scripts/rest_perf_harness.py, selected QEMU reference, Pi 4 serial capture, active wired or Wi-Fi profile, docs/TEST_PLAN.md.
Changes:
- out/bench/m26b-* — archived QEMU reference, Pi isolated runtime run, comparator output, and normalized serial evidence.
- docs/BENCHMARKS.md — update benchmark verdict and artifact table after proof is produced.
- docs/TEST_PLAN.md and scripts/ci/test_plan_run.sh — add 26b QEMU/Pi benchmark stages if not already covered by target-qualified runner configuration.
Commands:
- python3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --log-dir out/bench --log-prefix m26b-qemu-reference
- python3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --no-qemu --no-gateway --rest-url http://<pi4-gateway-host>:<port> --log-dir out/bench --log-prefix m26b-pi4-linked-runtime
Checks: Pi isolated runtime throughput meets or exceeds the selected QEMU reference under matched workload/provenance, latency remains recorded and checked against documented industry-normal physical LAN/control-plane ranges but excluded from the QEMU-throughput parity verdict, and side proof lanes stay separate.
Deliverables: fresh benchmark artifacts, comparator PASS/FAIL, normalized Pi proof, and updated benchmark docs.
Title/ID: m26b-authenticated-cohsh-reboot
Goal: Add an authenticated `cohsh reboot` command that works over TCP and local-seat without introducing a new in-VM listener or bypassing existing Queen secrets.
Inputs: crates/cohsh-core/src/{verb.rs,command.rs,help.rs}, apps/cohsh/src/lib.rs, apps/cohsh/src/transport/tcp.rs, apps/root-task/src/{event/mod.rs,reboot.rs,kernel.rs}, scripts/pi4-image-build.sh, third_party/u-boot/configs/rpi_4_defconfig, docs/{HARDWARE_BRINGUP.md,INTERFACES.md,USERLAND_AND_CLI.md}.
Changes:
- crates/cohsh-core/src/* — add the shared `reboot` console verb and `REBOOT` ACK label so serial, TCP, cohsh, and local-seat parse the same command.
- apps/root-task/src/reboot.rs + apps/root-task/src/kernel.rs — register the Pi 4 BCM2711 watchdog reset backend through HAL-owned device mapping, best-effort mark authenticated Pi resets as one-shot fast boots through a Cohesix-specific BCM2711 PM RSTS high marker before watchdog arming, report the retained watchdog software-reset status bit as diagnostics only, follow the BCM2711 PM WDOG/RSTC restart sequence for reset, and fail closed when that reset path is unavailable.
- apps/root-task/src/event/mod.rs — require a secret-backed Queen session, emit `OK REBOOT detail=scheduled`, then defer the hardware reboot request long enough to flush the acknowledgement.
- apps/cohsh/src/* — expose `cohsh reboot` through the existing authenticated TCP console flow and stop waiting for trailing lines once `OK REBOOT` is received.
- scripts/pi4-image-build.sh + third_party/u-boot/configs/rpi_4_defconfig — generate a Pi 4 U-Boot script that loads saved `cohesix.env` policy, consumes and clears the authenticated reboot marker when visible, reports software-reset status as diagnostics only, enters the interactive Cohesix menu by default, and rejects stale U-Boot binaries that still use generic `bootflow scan`.
- docs/USERLAND_AND_CLI.md + docs/snippets/cohsh_grammar.md — document reboot grammar and the TCP/local-seat authorization model.
- docs/HARDWARE_BRINGUP.md + docs/INTERFACES.md — document the authenticated reboot fast-boot handoff and saved-policy behavior.
Commands:
- cargo test -p cohsh-core
- cargo test -p cohsh --lib network_console_verbs_forward_to_transport
- cargo test -p root-task reboot --lib
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib event::tests::local_seat_ticket_backed_reboot_schedules_backend_request
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
Checks: Bare `reboot` without an authenticated session fails; physical console/local-seat reboot requires a Queen ticket minted from the existing Queen secret; TCP reboot remains gated by the existing TCP auth token plus Queen session; Pi 4 reset access uses only HAL-mapped PM/watchdog registers; an authenticated Pi reset best-effort sets the Cohesix high RSTS marker without making marker readback a policy gate; the watchdog reset path follows the BCM2711 PM WDOG/RSTC restart sequence and fails closed if those reset-critical accesses are unavailable; the next generated U-Boot script load consumes high marker state before menu/input setup when present, reports the software-reset bit as diagnostics only, and enters the interactive Cohesix menu whose first action is `Boot with saved settings` or `Boot with default settings` as appropriate; the Pi 4 U-Boot default command sources `boot.scr.uimg` directly rather than entering EFI/bootflow scan.
Deliverables: Shared reboot verb, host CLI forwarding, authenticated root-task scheduling, HAL-backed Pi 4 reboot backend, one-shot authenticated reboot marker diagnostics, preserved interactive splash/menu behavior, generated-script validation, and tests for denial/success paths.
Title/ID: m26b-queen-log-evidence-dump
Goal: Make `/log/queen.log` a bounded, useful Pi 4 benchmark evidence surface and expose a host-side dump workflow through `cohsh` and SwarmUI without changing console or Secure9P semantics.
Inputs: apps/root-task/src/{log_buffer.rs,event/mod.rs,ninedoor.rs,bootstrap/log.rs}, apps/cohsh/src/lib.rs, apps/swarmui/src/{lib.rs,transport.rs}, apps/swarmui/frontend/{app.js,index.html,styles.css}, scripts/rest_perf_harness.py, docs/{HOST_TOOLS.md,USERLAND_AND_CLI.md,INTERFACES.md,TEST_PLAN.md}.
Changes:
- apps/root-task/src/log_buffer.rs — raise live `/log/queen.log` retention to 2048 lines, add sequence/eviction metadata if needed for evidence integrity, and preserve bounded line storage.
- apps/root-task/src/event/mod.rs + apps/root-task/src/ninedoor.rs — export the retained log through chunked, non-lossy streaming so `cat`/`tail`/`log` do not allocate or copy a 2048-line snapshot in one pending buffer and `END` is emitted only after the final retained line.
- apps/root-task/src/bootstrap/log.rs + selected audit call sites — keep high-rate driver chatter out of the log while adding curated benchmark evidence markers: boot/build/session identity, log retention metadata, benchmark start/end, host write summaries, policy/lifecycle denials, telemetry wrap/quota, and bounded backpressure/error summaries.
- apps/cohsh/src/lib.rs — add `log dump <local-file.txt>` as a host-only command that reads `/log/queen.log` through the existing transport, writes only payload lines to the destination, refuses existing files unless an explicit force form is documented, and preserves ACK/ERR/END grammar on the wire.
- apps/swarmui/src/** + apps/swarmui/frontend/** — expose the same bounded log dump/read workflow as a SwarmUI projection over existing console/REST transport semantics, with no UI-owned evidence serializer, no second session in live console mode, and no hidden polling.
- docs and tests — document the 2048-line bounded retention/export behavior, diagnostic contents, `cohsh log dump` usage after REST harness runs, SwarmUI workflow, and performance constraints.
Commands:
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib log_buffer event::tests
- cargo test -p cohsh
- cargo test -p swarmui
- python3 -m pytest -q tests/test_rest_perf_harness.py
Checks: `/log/queen.log` retains up to 2048 curated lines with explicit oldest-line eviction, host/UI dumps preserve every retained line without truncation, generic command streaming remains bounded per turn, Pi 4 benchmark hot paths do not gain high-rate log writes, `cohsh log dump` and SwarmUI use existing read semantics only, and REST harness benchmark evidence can identify the run, transport/session, recent control failures, backpressure, and retention window without relying on UART spam.
Deliverables: 2048-line bounded queen log, non-lossy chunked dump path, curated benchmark evidence contents, `cohsh log dump` command, SwarmUI log dump/read projection, docs, and focused regression coverage.
Compatibility baseline tasks below are retained because they describe the original 26b DHCP, U-Boot policy, Wi-Fi, and QEMU guardrails that must not regress. They did not close reopened 26b by themselves; accepted closure combined the USB/Wi-Fi driver-task and concurrency/benchmark gates above with the retained baseline checks below.
Title/ID: m26b-dhcp-core-nostd
Goal: Implement bare-bones, bounded DHCPv4 client logic for root-task networking.
Inputs: apps/root-task/src/net/*, docs/INTERFACES.md, docs/SECURITY.md.
Changes:
- apps/root-task/src/net/dhcp.rs — deterministic DHCP state machine and packet parser (DISCOVER/OFFER/REQUEST/ACK only).
- apps/root-task/src/net/mod.rs — integrate DHCP mode into existing net bootstrap sequencing.
Commands:
- cargo check -p root-task
- cargo test -p root-task --features "kernel net-console" dhcp
Checks:
- Lease acquisition and timeout paths are bounded and test-covered.
Deliverables:
- `no_std` DHCP core integrated with deterministic diagnostics.
Title/ID: m26b-uboot-net-policy
Goal: Make wired/Wi-Fi DHCP policy compiler-authoritative with optional U-Boot-provided inputs.
Inputs: configs/root_task.toml, tools/coh-rtc, apps/root-task/src/generated, docs/HARDWARE_BRINGUP.md.
Changes:
- tools/coh-rtc/src/* — add policy IR fields (`mode`, `interface`, DHCP bounds) and validation.
- apps/root-task/src/generated/* — regenerated network policy constants/artifacts.
- docs/HARDWARE_BRINGUP.md — document U-Boot policy source, fallback rules, and expected boot lines.
Commands:
- cargo test -p coh-rtc
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
Checks:
- Invalid policy settings fail deterministically; valid settings generate stable artifacts.
Deliverables:
- Manifest/U-Boot-policy-driven DHCP mode selection with docs-as-built parity.
Title/ID: m26b-uboot-network-wizard
Goal: Add an interactive Pi 4 U-Boot network wizard with saved-config continue flow, bounded static IPv4 prompts, and optional logo display.
Inputs: scripts/pi4-image-build.sh, third_party/u-boot/configs/rpi_4_defconfig, docs/HARDWARE_BRINGUP.md, docs/INTERFACES.md, docs/COHESIX_LOGO.png.
Changes:
- scripts/pi4-image-build.sh — generate an `askenv`-driven Pi 4 boot script that can continue with saved policy, choose DHCP vs static, choose wired vs Wi-Fi, collect bounded static IPv4 fields, persist only Cohesix policy to a dedicated FAT-side file, and optionally render a staged BMP logo on HDMI.
- third_party/u-boot/configs/rpi_4_defconfig — enable the `askenv` and `bmp display` support required by the wizard while keeping the seL4-recommended Pi 4 USB baseline.
- docs/HARDWARE_BRINGUP.md + docs/INTERFACES.md — document the wizard flow, persisted `coh_*` variables, bounded `/chosen/cohesix,*` static IPv4 properties, and the saved-config fast path.
Commands:
- bash -n scripts/pi4-image-build.sh
- make -C third_party/u-boot rpi_4_defconfig
- make -C third_party/u-boot CROSS_COMPILE=aarch64-linux-gnu- -j$(sysctl -n hw.ncpu)
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
Checks:
- The first wizard action is `Boot with saved settings` when a coherent persisted network override exists; a logo-only or cleared policy presents `Boot with default settings`.
- `Manual (static IPv4)` collects bounded static IPv4 fields and mirrors them into DTB `/chosen/cohesix,static-*` properties before handoff.
- Review distinguishes `Boot once without saving` from `Save settings and restart`; saved-settings reset requires explicit confirmation, and a new Wi-Fi policy can be entered without deleting or reflashing the SD image.
- The HDMI logo is optional: it renders when enabled and available, and boot still proceeds cleanly when it is disabled or cannot be staged.
Deliverables:
- Pi 4 U-Boot network wizard with deterministic saved-config continuation and optional logo display.
Title/ID: m26b-pi4-wifi-dhcp-baseline
Goal: Add minimal Pi 4 Wi-Fi path sufficient for DHCP-backed diagnostics connectivity.
Inputs: apps/root-task/src/drivers/*, apps/root-task/src/hal/*, docs/ARCHITECTURE.md, docs/SECURITY.md.
Changes:
- apps/root-task/src/hal/* — add Pi 4 Wi-Fi HAL traits for SDIO host I/O, power/reset control, OOB/host-wake observation, and firmware/NVRAM/CLM handoff; default implementations must fail deterministically with `unsupported`.
- apps/root-task/src/drivers/* — add a dedicated CYW43455/CYW43xx-class driver path that follows the reference shape `bwfm` -> Zephyr/WHD HAL split -> Linux `brcmfmac` (`sdio.c`, `firmware.c`, `cfg80211.c`) without lifting source.
- apps/root-task/src/drivers/* — implement the Pi 4 SDIO transport path first (function-0 direct I/O, function-1/2 enable, mailbox/interrupt handling, bounded firmware download, NVRAM/CLM staging) before join/auth logic.
- apps/root-task/src/net/* — bind Wi-Fi link state and Ethernet frame ingress/egress into the shared smoltcp bootstrap/DHCP flow without introducing any new in-VM listener surface.
- docs/ARCHITECTURE.md + docs/SECURITY.md — update the network backend matrix, bounds, threat notes, silicon identification (Pi 4B uses CYW43455 over SDIO), and reference-only provenance (`bwfm` -> Zephyr/WHD HAL split -> `brcmfmac` edge-case guidance; no code lift).
Commands:
- cargo check -p root-task
- cargo test -p root-task wifi:: -- --nocapture
- rg -n "EFI_|boot_services|runtime_services|uefi::" apps/root-task/src tools/coh-rtc/src
Checks:
- Wi-Fi join + DHCP works when enabled and declared; failure modes remain deterministic and auditable.
- Wi-Fi runtime/device access remains HAL-only; any non-HAL direct access path fails review.
Deliverables:
- Profile-gated CYW43xx Wi-Fi DHCP diagnostics path for Pi 4 with explicit reference-only provenance documentation.
Title/ID: m26b-pi4-wifi-hal-foundation
Goal: Add the HAL surface required to support Pi 4 Wi-Fi without any direct MMIO or firmware-service bypass in drivers.
Inputs: apps/root-task/src/hal/*, apps/root-task/src/kernel.rs, docs/ARCHITECTURE.md.
Changes:
- apps/root-task/src/hal/mod.rs — add bounded SDIO, Wi-Fi control GPIO, OOB/host-wake, and firmware bundle traits/types with deterministic `unsupported` defaults.
- apps/root-task/src/kernel.rs — keep Wi-Fi runtime rejection paths explicit until HAL-backed implementations are present.
- docs/ARCHITECTURE.md — document HAL ownership of Pi 4 Wi-Fi transport/control resources.
Commands:
- cargo check -p root-task --no-default-features --features net-console
- cargo test -p root-task hal:: -- --nocapture
Checks:
- All Wi-Fi transport/control operations are represented in HAL before any driver code depends on them.
- Non-Pi4 or pre-implementation HALs fail deterministically with `unsupported`.
Deliverables:
- Auditable Wi-Fi HAL contract for subsequent 26b tasks.
Title/ID: m26b-pi4-sdio-host-bringup
Goal: Implement the Pi 4 SDIO host path needed by CYW43455.
Inputs: apps/root-task/src/hal/*, apps/root-task/src/drivers/*, Pi 4 DTB/U-Boot handoff artifacts.
Changes:
- apps/root-task/src/hal/* — add Pi 4 SDIO host implementation for the BCM2835/BCM2711 SDIO controller used by the on-board Wi-Fi device.
- apps/root-task/src/drivers/* — add bounded command/data path helpers for function-0 direct I/O and function-1/2 CMD53 transfers.
- docs/HARDWARE_BRINGUP.md — record the Pi 4 SDIO host node/pin assumptions and bring-up evidence.
Commands:
- cargo check -p root-task
- cargo test -p root-task sdio:: -- --nocapture
Checks:
- SDIO host init, clocking, bus-width changes, and direct/extended transfers are HAL-only and test-covered.
Deliverables:
- Pi 4 SDIO transport substrate for CYW43455.
Title/ID: m26b-cyw43455-firmware-transport
Goal: Bring the CYW43455 to a firmware-ready state with bounded mailbox and firmware/NVRAM/CLM handling.
Inputs: apps/root-task/src/drivers/*, out/pi4-sd/*, docs/SECURITY.md.
Changes:
- apps/root-task/src/drivers/* — add CYW43455 reset/attach sequencing, core discovery, mailbox handling, firmware download, NVRAM application, and CLM load.
- docs/SECURITY.md — document firmware provenance, bounds, and runtime trust assumptions for the bundled Pi 4 Wi-Fi blobs.
Commands:
- cargo check -p root-task
- cargo test -p root-task cyw43:: -- --nocapture
Checks:
- Firmware bundle validation is bounded and deterministic.
- Driver reaches a ready-for-join state without bypassing HAL.
Deliverables:
- CYW43455 transport/firmware path ready for association work.
Title/ID: m26b-cyw43455-join-dhcp
Goal: Complete Pi 4 Wi-Fi diagnostics connectivity by joining a network and binding the shared DHCP/bootstrap flow.
Inputs: apps/root-task/src/net/*, apps/root-task/src/drivers/*, docs/INTERFACES.md, docs/HARDWARE_BRINGUP.md.
Changes:
- apps/root-task/src/drivers/* — add bounded open-network/WPA2-PSK join sequencing, link-state reporting, and audited failure reasons.
- apps/root-task/src/net/* — route `wifi` and `auto` policy through the CYW43455 path while preserving single-active-interface guarantees.
- docs/INTERFACES.md + docs/HARDWARE_BRINGUP.md — document required credentials handoff, join breadcrumbs, DHCP evidence, and operator workflow.
Commands:
- cargo check -p root-task
- cargo test -p root-task wifi:: -- --nocapture
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
Checks:
- `wifi` reaches link-up + DHCP when credentials are present.
- `auto` prefers Wi-Fi only when the CYW43455 path is healthy and still exposes at most one active control-plane interface.
Deliverables:
- End-to-end Pi 4 Wi-Fi diagnostics path with DHCP and console reachability.
Title/ID: m26b-pi4-wifi-hardware-validation
Goal: Capture Pi 4 on-device evidence for CYW43455 join, DHCP, and deterministic historical `auto` compatibility behavior before closing the retained 26b compatibility baseline.
Inputs: flashed Pi 4 SD image, serial capture, Linux known-good brcmfmac/MMC/SDHCI capture, U-Boot USB handoff trace, Wi-Fi credentials, direct-link/compatibility host setup, docs/HARDWARE_BRINGUP.md, docs/TEST_PLAN.md.
Changes:
- scripts/pi4_trace_normalize.py — normalize Pi 4 USB/Wi-Fi serial traces into JSONL/summary artifacts for boot-to-boot comparison.
- docs/HARDWARE_BRINGUP.md — record the exact serial breadcrumbs, host commands, and observed IP/console evidence for a successful Wi-Fi boot.
- docs/TEST_PLAN.md — add the final Pi 4 Wi-Fi validation transcript and `auto` fallback proof.
Commands:
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
- minicom -D /dev/cu.usbserial-0001 -b 115200 -o -C pi4-serial.log
- python3 scripts/pi4_trace_normalize.py pi4-serial.log --summary
- python3 scripts/pi4_trace_normalize.py pi4-serial.log --gate-summary --expect USB_GATE=10 --expect USB_BLOCKER=none --expect WIFI_GATE=10 --expect WIFI_BLOCKER=none --expect WIFI_EXACT=none
- python3 scripts/pi4_trace_normalize.py pi4-serial.log --gate-summary --expect USB_BOOTLOADER_HANDOFF_SEEN=no --expect USB_COLD_BOOT_SEEN=yes --expect BOOT_HALTED=no --expect TIMER_IRQ27_SEEN=no
- python3 scripts/pi4_trace_normalize.py pi4-linux-known-good.log --domain wifi --summary
- cargo run -p cohsh --features tcp -- --transport tcp --tcp-host <wifi-lease-ip> --tcp-port 31337 --auth-token bootstrap
Checks:
- Normalized Cohesix, U-Boot, and Linux comparison traces preserve USB/Wi-Fi stages, blockers, and latest verdicts as machine-readable evidence.
- Final Pi 4 USB acceptance requires `USB_COLD_BOOT_SEEN=yes`, command/event-ring proof before live Cohesix-owned root-port power assertion/readback/sampling/reset, and no Linux/U-Boot captured root-port enumeration.
- Serial shows CYW43455 attach/join breadcrumbs followed by `[dhcp] lease bound ...`.
- `netstats` / `netstatus` report the Wi-Fi lease on `policy=wifi`.
- `auto` proves single-active-interface behavior; historical compatibility profiles may exercise absent-device wired fallback, while the physical driver-task profile treats selected-CYW43 attach/join/runtime failure as fatal driver evidence.
Deliverables:
- Pi 4 hardware validation evidence, normalized trace summaries, and known-good Linux/U-Boot comparison artifacts required to preserve the historical Milestone 26b compatibility baseline.
Title/ID: m26b-qemu-compat-gate
Goal: Prove 26/26a/26b changes do not break macOS/Linux QEMU backward compatibility.
Inputs: scripts/qemu-run.sh, scripts/uboot/qemu-uboot-smoke.sh, regression fixtures, docs/TEST_PLAN.md.
Changes:
- docs/TEST_PLAN.md — add explicit compatibility matrix checks for macOS/Linux QEMU after 26/26a/26b.
- scripts/ci/* — add guard checks that fail on console/protocol drift for existing QEMU fixtures.
Commands:
- scripts/cohesix-build-run.sh --no-run --cargo-target aarch64-unknown-none
- scripts/uboot/qemu-uboot-smoke.sh --net user
Checks:
- Existing QEMU fixtures on macOS/Linux remain passing with no operator-facing behavior regressions.
Deliverables:
- Auditable compatibility evidence for the Pi 4 bare-metal rollout milestones.
Title/ID: m26b-nettest-interface-policy
Goal: Extend `nettest` to honor 26b network policy (`wired|wifi|auto`) while enforcing a single active control-plane interface at runtime.
Inputs: apps/root-task/src/net/*, tools/coh-rtc/src/*, apps/root-task/src/generated/*, docs/INTERFACES.md, docs/HARDWARE_BRINGUP.md.
Changes:
- apps/root-task/src/net/mod.rs + apps/root-task/src/net/stack.rs — add policy-aware interface selection for self-test execution and report active/standby interface state in `netstats`.
- apps/root-task/src/net/dhcp.rs — surface bounded lease/state signals needed by `nettest` diagnostics for DHCP paths.
- tools/coh-rtc/src/* + apps/root-task/src/generated/* — emit and validate nettest-relevant policy fields (`mode`, `interface`, retry/timing bounds) for `pi4-uboot-aarch64`.
- docs/INTERFACES.md + docs/HARDWARE_BRINGUP.md — codify deterministic single-active-interface behavior and failover evidence requirements for `auto`.
Commands:
- cargo check -p root-task
- cargo test -p root-task net:: -- --nocapture
- cargo test -p coh-rtc
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
Checks:
- `nettest` on `wired` and `wifi` policies executes against only the selected interface.
- `auto` policy uses deterministic priority/failover, with at most one active TCP console interface at any moment.
- Existing QEMU `nettest` behavior and host workflows remain backward compatible with no required command changes.
Deliverables:
- Policy-driven `nettest` behavior for Pi 4 DHCP milestones with explicit single-active-interface guarantees and compatibility evidence.
Title/ID: m26b-swarmui-tauri2-host-upgrade
Goal: Keep SwarmUI on the latest stable Tauri desktop line without changing Cohesix transport or UI semantics during the Pi 4 DHCP rollout.
Inputs: apps/swarmui/*, scripts/setup_environment.sh, scripts/linux_host_tools_sync.sh, docs/HOST_TOOLS.md.
Changes:
- apps/swarmui/Cargo.toml + apps/swarmui/src-tauri/main.rs + apps/swarmui/tauri.conf.json — migrate SwarmUI from Tauri 1 to Tauri 2 while preserving the existing command surface, replay/bootstrap flow, CSP, and `window.__TAURI__` frontend bridge.
- apps/swarmui/src-tauri/capabilities/default.json — add the minimum desktop capability set required by the Tauri 2 permission model.
- apps/swarmui/tests/no_http_deps.rs — scope dependency-policy checks to the active desktop target so Tauri 2 mobile-only transitive crates do not create false failures.
- scripts/setup_environment.sh + scripts/linux_host_tools_sync.sh + docs/HOST_TOOLS.md — align Linux runtime/build prerequisites to the Tauri 2 WebKitGTK 4.1 package line.
Commands:
- cargo check -p swarmui
- cargo test -p swarmui
Checks:
- SwarmUI keeps the existing host-side command/invoke surface and passes its replay, cache, security, transcript, and console-parity tests after the Tauri 2 migration.
- Linux host setup/build scripts install WebKitGTK 4.1 packages required by Tauri 2.
- No new Cohesix protocol verbs, transports, or UI authority are introduced.
Deliverables:
- SwarmUI upgraded to the current Tauri 2 desktop line with host-tool packaging and test coverage kept in sync.
Title/ID: m26b-swarmui-spectrum-shell
Goal: Rebuild the SwarmUI desktop shell around Spectrum Web Components while preserving Cohesix transport semantics, replay behavior, and Live Hive rendering.
Inputs: apps/swarmui/frontend/*, tools/swarmui-ui-tests/*, docs/USERLAND_AND_CLI.md.
Changes:
- apps/swarmui/frontend/index.html + app.js + components/console.js + styles/* — adopt a vendored Spectrum-based shell (`sp-theme`, `sp-button`, `sp-textfield`, `sp-picker`, `sp-divider`) for operator controls while preserving all current IDs, panel outputs, and Pixi-backed Live Hive behavior.
- apps/swarmui/frontend/vendor/spectrum.bundle.js — self-host the exact Spectrum Web Components bundle needed by SwarmUI so Tauri/release builds remain offline-safe and CDN-free.
- tools/swarmui-ui-tests/tests/swarmui.spec.js + screenshots — update the Playwright harness for Spectrum-backed text fields/buttons, keep replay/canvas coverage intact, and add shell regression checks for ticket minting and control wiring.
- docs/USERLAND_AND_CLI.md — record that SwarmUI ships a vendored Spectrum shell while remaining a presentation-only frontend over existing Cohesix transports.
Commands:
- cargo check -p swarmui --all-targets
- cargo clippy -p swarmui --all-targets -- -D warnings
- cargo test -p swarmui
- cd tools/swarmui-ui-tests && npm test
Checks:
- SwarmUI keeps the same Tauri command surface, replay/bootstrap flow, and Live Hive polling semantics after the Spectrum shell migration.
- The shell remains self-hosted for Tauri/release bundles with no CDN requirement and no new transport authority.
- Playwright coverage exercises the Spectrum-backed controls without weakening existing Live Hive and transcript assertions.
Deliverables:
- World-class SwarmUI shell using vendored Spectrum Web Components with replay-safe UI regression coverage and warning-free SwarmUI Rust builds.
Milestone 26c — Regression-Gated Refactor + Surface Audit (Zero-Regression)
Status: Complete.
As-built scope: The milestone established documentation and implementation inventories, a docs-as-built audit, characterization and host/VM boundary checks, target-qualified staged runners, and behavior-preserving decomposition of host tools, root-task adapters and HAL-facing code. Public references distinguish implemented capability, target evidence and planned work. The documentation restoration is closed; historical release snapshots remain immutable.
Qualification limits: The original QEMU and wired-GENET Pi closure remains
accepted for its recorded source and target. Pi DMA is bounded_no_iommu;
counter-qualified timing uses the 54-MHz virtual counter. This evidence does not
qualify later kernel or image changes. The four Worker implementation proposals
marked inactive below established models and declarations, not loaded Worker
objects, delivered capabilities or target execution. 26e owns executable
Worker isolation and SMP+MCS acceptance. Subsequent production binding belongs to
28d, service-turn optimization to 29a, and operator responsiveness
to 29b; the roadmap mapping resolves historical numbers below.
Evidence: Original qualification and scope corrections, documentation drift ledger, and the task-owned audit records retain the original test roots, source limits and dispositions.
The completed milestone’s M26C_* audit files are preserved in the
pinned audit archive.
File names and commands below describe that historical checkout, not required
files in the 1.1.0-beta source tree. Current risk and acceptance controls remain
in docs/audit/rust_risk_baseline.toml, docs/audit/findings.csv,
docs/audit/EXCEPTIONS.md, and docs/TEST_PLAN.md. Generate new documentation
inventories under out/ when needed.
Non-negotiable constraints:
- No protocol, namespace, ACK/ERR/END, telemetry, manifest, console grammar, Secure9P, or release-behavior drift may hide under a “refactor”, “cleanup”, or “humanizing” label.
- Refactors are behavior-preserving only: extraction, decomposition, deduplication, typed-error cleanup, naming cleanup, and invariant documentation after characterization coverage exists for the touched surface.
- The earlier named Worker architecture, phase-1 cap-backed endpoint, notification-lifecycle, and MCS tasks are inactive historical proposals. No 26c behavior change is authorized by this truth-correction reopening.
- Future Worker/root-task isolation and the one SMP+MCS QEMU/Pi transition must
land and obtain target acceptance in Milestone 26e. Milestone 38 (
m29a-core-local-event-pumps) optimizes that accepted scheduler with core-local service buckets, Milestone 39 (m29b-event-pump-qos) proves mixed-load operator responsiveness on it, and Milestone 33 (m28b-production-worker-ticket-driver-inventory) binds production Worker ticket/lease ledgers, projects the already complete driver inventory, and adds structured quarantine/evidence. Each requires its own post-behavior external-contract baseline. - The target-qualified staged runner is an enabling blocker, not merely closure polish.
scripts/ci/test_plan_run.sh --target qemu|pi4andscripts/ci/check_test_plan.shmust exist and agree before cleanup or structural decomposition can start. - Humanization is evidence-first and mostly subtractive: delete generic boilerplate before rewriting, keep comments only for invariants/bounds/authority/failure behavior, and make the AI-fingerprint audit an independent gate.
- Simplicity must be measured, not asserted. Cleanup/refactor waves must show reduced duplication, clearer ownership, fewer generic comments, smaller or better-named hot modules where practical, and no new abstraction unless it removes real repetition or isolates authority.
- Every cleanup/refactor wave must be bisectable: one owned surface, one preserved-contract list, one characterization artifact, one scorecard entry, one targeted test subset, and final QEMU/Pi staged-run compatibility evidence before milestone closure.
- Generated snippets, generated reports, tracked release snapshots, append-only audit evidence, seL4/reference mirrors, and vendored Markdown are update-by-source or inventory-only surfaces. Do not hand-edit them for style.
- VM-side Cohesix remains
no_std; shared semantic helpers must beno_stdby construction and must not pull host transport, filesystem, process, network, or provider crates into VM closure profiles. - HAL remains the only path for device authority, MMIO, DMA publication, IRQ binding, physical-address handling, firmware-service handoff, and cache-maintenance policy. SDIO/USB seams are extraction-only and must not introduce new hardware support or a parallel driver framework.
- Pi 4 DMA truth is
bounded_no_iommu: bounded HAL-managed DMA ownership and evidence, not malicious-device DMA confinement or SMMU/IOMMU isolation. - Linked Pi 4 runtime-image specs,
pi4-driver-abi, runtime CPIO staging, owner-state descriptors, the 26b SDIO acceptance state, and fresh-Pi hardware proof remain separate evidence states; generated eligibility or QEMU proof is not board closure. Milestone 26c may audit and preserve this evidence split, but SDIO graduation belongs to 26b. - Isolated runtime performance evidence is counter-qualified: valid
DRIVER_TASK_COUNTERsnapshots, owner-state proof, and same-harness Pi benchmark evidence do not close latency claims unless the Pi profile provestimers-arch-counterwithTIMER_BACKEND=arch-counter,TIMER_CLOCK_HZ=54000000,TIMER_EL0_COUNTER=vct, andDUMMY_TIMER_SEEN=no. Dummy-timer captures, stale serial logs, or physical-counter/timer-control exports leave performance proof red. - Multi-agent execution is mandatory. Each lane must leave a checked-in or attached handoff with inputs, files touched or intentionally skipped, commands, artifact paths, blockers, deferrals, residual gaps, and PASS/FAIL status.
- Milestone closure requires a clear/deferred blocker ledger, complete lane handoffs, green task gates, and full target-qualified staged Test Plan PASS on QEMU and Pi 4 with no
INCOMPLETEmarkers.
Prerequisite
- Reopened Milestones 26a and 26b completed or explicitly scoped for this historical 26c dependency, including checked-in Pi 4 USB/serial/HDMI responsiveness evidence under wired and Wi-Fi load, driver-task scheduling evidence, arch-counter timer-backend proof, GENET/static compatibility evidence, DHCP/Wi-Fi compatibility evidence, QEMU compatibility evidence, regenerated profile-specific manifest evidence, isolated
pi4-driver-*runtime image/ABI evidence, and explicit closure or deferral of any runtime-image owner-state proof boundary.
Goal
Humanize and simplify Cohesix-authored code and documentation without losing behavioral proof. The milestone succeeds only if the audit artifacts, characterization gates, accepted runtime additions, cleanup refactors, generated outputs, and QEMU/Pi 4 staged evidence all agree on the as-built system. The former Worker behavior proposals below are retained as inactive history and are not part of the accepted implementation set.
Execution Order
Later phases may start only when earlier phase gates are complete for the touched surface or explicitly deferred in docs/audit/M26C_AS_BUILT_BLOCKERS.md with dependency impact.
| Phase | Purpose | Tasks | Gate |
|---|---|---|---|
| 0 | Scope, ownership, blockers | m26c-as-built-blocker-ledger, m26c-target-qualified-runner-baseline, m26c-refactor-map-and-risk-ratchet, lane setup in M26C_AGENT_HANDOFFS.md |
No unowned files, hidden blockers, missing target-qualified runner contract, missing sub-agent lanes, or unmeasured simplification targets. |
| 1 | Documentation and provenance truth | m26c-authoring-charter-and-header-rules, m26c-ai-fingerprint-authorship-review, m26c-markdown-inventory-and-disposition, m26c-mermaid-as-built-diagram-audit, m26c-docs-as-built-audit, m26c-runtime-boundary-and-semantic-parity-audit |
Inventories, drift ledger, AI-fingerprint audit, parity matrix, and generated-source dispositions are complete. |
| 2 | Accepted runtime additions and superseded Worker proposals | Accepted: m26c-pi-runtime-dma-proof-closure, m26c-dma-protection-profile-truth, and the non-Worker baseline evidence. Inactive history: m26c-worker-architecture-implementation, m26c-cap-backed-worker-endpoints, m26c-notification-backed-worker-lifecycle, and m26c-worker-driver-mcs-budget-evidence. |
Accepted Pi/runtime behavior remains compiler-declared and tested. Inactive Worker proposals supply no implementation claim; 26e owns complete Worker isolation plus linked-driver SMP+MCS authority, 38 (m29a-core-local-event-pumps) owns later core-local optimization, and 33 (m28b-production-worker-ticket-driver-inventory) owns production Worker ledger binding, driver-inventory projection, and structured quarantine/evidence. |
| 3 | Refactor safety gates | m26c-characterization-gates-before-refactor, m26c-no-std-boundary-gates |
Cleanup-sensitive behavior and VM dependency closures are pinned before structural edits. |
| 4 | Humanization and structural cleanup | m26c-low-risk-surface-cleanup, m26c-host-tool-structural-cleanup, m26c-root-task-runtime-decomposition, m26c-hal-network-and-local-seat-decomposition |
Each cleanup wave is bisectable and starts only after its characterization artifact, preserved-contract list, owner, scorecard entry, and target test subset are recorded; risk-ratchet does not regress and HAL/no_std/protocol boundaries hold. |
| 5 | Closure | m26c-full-test-plan-qemu-and-pi4 |
QEMU and Pi 4 staged Test Plan runs pass with target-qualified artifacts and no incomplete markers. |
Documentation Scope
The Markdown and Mermaid lanes cover only tracked Markdown returned by git ls-files '*.md' | sort. Ignored build output, local evidence folders, caches, virtualenvs, and nested external checkouts are excluded unless the main Cohesix repository tracks them.
The inventory must cover root docs, app/crate/tool READMEs, docs/**/*.md, audit registers, dated audit snapshots, checklists, generated compliance reports, snippets, release snapshots, tracked seL4/**/*.md, and tracked third_party/**/*.md. Each entry must be classified as one of: human-edited canonical source, live audit register, append-only audit evidence, generated report, generated snippet, release snapshot, vendored reference, or external reference mirror. Mermaid blocks inherit the disposition of their containing file unless the Mermaid inventory records a stricter update rule.
Required Artifacts
Task blocks below own the exact file changes, commands, checks, and deliverables. At milestone level, closure requires these artifact families:
- Audit control:
docs/audit/M26C_AS_BUILT_BLOCKERS.md,M26C_AGENT_HANDOFFS.md,M26C_TARGET_RUNNER_BASELINE.md,M26C_REFACTOR_MAP.md,M26C_REFACTOR_RISK_RATCHET.csv,M26C_REFACTOR_OWNERSHIP.md,M26C_SIMPLICITY_SCORECARD.md,M26C_POST_BEHAVIOR_BASELINE.md. - Documentation truth:
M26C_MARKDOWN_INVENTORY.{csv,md},M26C_MERMAID_INVENTORY.csv,M26C_MERMAID_GITHUB_RENDER_AUDIT.md,M26C_DOCS_AS_BUILT_AUDIT.md,M26C_DOC_DRIFT_LEDGER.md,M26C_AI_FINGERPRINT_AUDIT.md. - Runtime boundaries:
M26C_RUNTIME_BOUNDARY_AUDIT.md,M26C_NINEDOOR_PARITY_MATRIX.md, VM-target dependency trees, generated manifest/snippet hashes, Pi 4 runtime/DMA proof classification, arch-counter timer-backend proof, and DMA protection profile evidence. - Worker/runtime implementation evidence: worker architecture tests, cap-backed endpoint negative tests, notification lifecycle tests, then-current scheduling evidence, isolated runtime ABI tests, and fresh-source provenance for staged Pi runtime artifacts.
- Cleanup evidence: before/after characterization for each refactor wave, risk-ratchet review, no-std/HAL boundary evidence, simplification scorecard entries, and authoring cleanup decisions tied back to as-built facts.
- Closure evidence: QEMU and Pi 4 state dirs with
stage_01.donethroughstage_05.done, required target artifacts present beforestage_05.done, no incomplete markers, due-diligence outputs, and a final planner reconciliation of all sub-agent handoffs.
Commands
git ls-files '*.md' | sort > out/audit/m26c_markdown_inventory.txtcut -d, -f1 docs/audit/M26C_MARKDOWN_INVENTORY.csv | sed '1d' | sort > out/audit/m26c_markdown_inventory_checked_in.txtdiff -u out/audit/m26c_markdown_inventory.txt out/audit/m26c_markdown_inventory_checked_in.txtscripts/ci/mermaid_inventory.py --markdown-list out/audit/m26c_markdown_inventory.txt --out docs/audit/M26C_MERMAID_INVENTORY.csvscripts/ci/check_mermaid_github.sh --markdown-list out/audit/m26c_markdown_inventory.txtscripts/ci/render_mermaid_github.sh --markdown-list out/audit/m26c_markdown_inventory.txt --out out/audit/m26c-mermaid-renderedcargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsonscripts/check-generated.shcargo fmt --all -- --checkcargo clippy --workspace --all-targets -- -D warningscargo check --workspacecargo test --workspacecargo auditcargo deny check advisoriesrg -n "unsafe|unwrap\\(|expect\\(|panic!" apps crates toolsrg -n "robust|flexible|seamless|world-class|comprehensive|easy to use|powerful|simple and intuitive|AI-generated|generated by" README.md CONTRIBUTING.md AGENTS.md docs apps crates toolsrg -n "Defines the|Provides the|CLI entry point|library surface|module for|This module" apps crates tools docs README.md CONTRIBUTING.md AGENTS.mdcargo test -p secure9p-corecargo test -p nine-door --test integrationcargo test -p coh --features mockcargo test -p cohshcargo test -p cohsh-corecargo test -p host-ticket-agentcargo test -p gpu-bridge-hostcargo test -p hive-gatewaypython3 -m pytest tools/cohesix-py/tests -qcargo test -p root-task --testscargo test -p root-task --libcargo test -p worker-heartcargo test -p worker-gpucargo test -p worker-loracargo test -p pi4-driver-abicargo test -p pi4-driver-runtimecargo check -p root-task --target aarch64-unknown-none --no-default-features --features "cohesix-dev"cargo tree -p root-task --target aarch64-unknown-none -e normal --no-default-features --features "cohesix-dev" > out/audit/m26c_root_task_tree_qemu.txtcargo check -p root-task --target aarch64-unknown-none --no-default-features --features "kernel bootstrap-trace serial-console net-console"cargo tree -p root-task --target aarch64-unknown-none -e normal --no-default-features --features "kernel bootstrap-trace serial-console net-console" > out/audit/m26c_root_task_tree_pi4.txtcargo check -p pi4-driver-runtime --target aarch64-unknown-nonescripts/ci/check_test_plan.shscripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.tomlscripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26c-qemuscripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26c-pi4
Closure Gates
- Every task block below satisfies its own Commands, Checks, and Deliverables; any skipped command has a documented environment blocker and remediation owner in the 26c handoff log.
- The target-qualified runner contract is implemented and checked before Phase 4 begins;
--target qemu|pi4is not allowed to remain a milestone-closing TODO while cleanup is underway. - The blocker ledger is clear or explicitly deferred to named later milestones, and no deferred item is used as satisfied evidence.
- Markdown, Mermaid, docs-as-built, AI-fingerprint, runtime-boundary, NineDoor parity, refactor-map, risk-ratchet, and sub-agent handoff artifacts all exist and agree with generated/source truth.
- Pi 4 runtime/DMA evidence separates generated eligibility, target compile, QEMU proof, fresh hardware proof, 26b SDIO owner-state evidence, and full board closure; Pi 4 DMA wording remains
bounded_no_iommuand never implies SMMU/IOMMU isolation. Milestone 26c does not reopen SDIO graduation. - Pi 4 performance evidence separates valid
DRIVER_TASK_COUNTERsnapshots, owner-state proof, same-harness benchmark evidence, and timer-backend proof; any missing or dummy timer backend keeps latency proof red even when runtime/DMA proof is otherwise present. - Worker-heart, worker-gpu, and worker-lora helper loops are model/build artifacts only. The Worker execution, badged endpoint invocation, notification delivery, and applied scheduling gates are reopened until a selected target loads and runs the declared child objects.
docs/audit/M26C_POST_BEHAVIOR_BASELINE.mdpreserves the accepted non-Worker behavior snapshot and explicitly supersedes the earlier Worker-execution interpretation.- Cleanup/refactor waves have before/after characterization, preserve console/Secure9P/manifest/telemetry/release behavior, keep HAL-only device authority, keep VM builds
no_std, and do not increase non-test risk indicators without approved exceptions. - Each cleanup/refactor wave is small enough to revert independently and records owner, touched surface, preserved contracts, characterization artifact, targeted test subset, before/after result, and scorecard delta.
M26C_SIMPLICITY_SCORECARD.mdrecords before/after evidence for touched high-value surfaces: boilerplate removed, duplicated logic collapsed, module/function boundaries improved, docs shortened or clarified, and any net complexity increase justified by required worker/runtime behavior or tests.- Workspace baseline checks (
fmt,clippy -D warnings,check,test,cargo audit, andcargo deny check advisories) pass or have scoped blockers recorded before closure. - QEMU and Pi 4 staged Test Plan runs both pass through
stage_05.done, contain required target artifacts, and contain no incomplete markers. - Final closure evidence includes representative before/after diffs, inventories, audits, generated-artifact proof, QEMU/Pi 4 state dirs, due-diligence outputs, and a planner reconciliation of every sub-agent lane.
Compiler / docsystem touchpoints
coh-rtcgenerated snippets referenced bydocs/snippets/*.mdremain authoritative; 26c may only change their source schemas or generators, never hand-edit the derived snippet text.docs/nist/REPORT.mdremains generated from its source registry; 26c may only update it through the proper generator flow.- Mermaid diagrams inside generated, release-derived, vendored, or reference-only Markdown follow the same disposition rules as their containing file; 26c may audit and report them, but edits must occur through the proper source, release-cut, or provenance flow.
- Tracked release-cut documentation under
releases/RELEASE_NOTES-*.md,releases/*/{README.md,QUICKSTART.md,RELEASE_NOTES.md},releases/*/docs/**/*.md, andreleases/*/python/**/README.mdremains derived from canonical docs and release packaging; if snapshot wording changes, the corresponding release-cut flow and notes must change in the same work. Release-local validation outputs underreleases/**/out/**, embedded virtualenv content underreleases/**/.venv*/**, and other untracked byproducts are provenance inputs only and are not part of the 26c inventory. docs/TEST_PLAN.md,scripts/ci/test_plan_run.sh,scripts/ci/check_test_plan.sh, and the stage scripts become authoritative for both QEMU and Pi 4PASSsemantics.- Generated
root_task.driver_imagesrecords,crates/pi4-driver-abi, isolatedpi4-driver-*runtime image artifacts, and driver-runtime CPIO packaging are authoritative boundary artifacts for Pi 4 driver-task cleanup; 26c may audit, test, and refactor around them only without changing acceptance status or hand-editing generated descriptors. - Pi 4 runtime/DMA proof fields, descriptor resource totals, owner-state evidence, and source artifact freshness are 26c audit/test-plan surfaces; later operator tooling may project them only after this milestone defines the evidence semantics.
- Pi 4 timer-backend fields are 26c audit/test-plan surfaces for performance claims. The accepted Pi profile uses read-only EL0 virtual-counter telemetry only when
KernelArmExportVCNTUser/CONFIG_EXPORT_VCNT_USERis enabled, scales elapsed-time proof fromTIMER_CLOCK_HZ, and rejects physical counter or EL0 timer-control exports for isolated runtime latency evidence. - DMA protection profile fields are compiler-owned surfaces. Pi 4 profiles must resolve to bounded no-IOMMU discipline, while SMMU-backed profiles are future hardware targets that require generated per-device DMA-domain state before code or docs may claim hardware-enforced isolation.
- Any future shared semantic helpers introduced to reduce host/VM drift must remain explicitly
no_std-safe, must not import host-side capabilities, transports, or provider crates into the VM build, and must be reviewed against the archived per-profile dependency trees. - Worker role manifests, ticket scopes, lease bindings, telemetry paths, and
lifecycle-model gates are compiler-owned surfaces. Current generated roles
are non-executable; any future implementation field must enter
coh-rtcIR and generated docs before code depends on it. - Cap-backed Worker endpoint and notification fields remain compiler-owned but disabled. Reserved badge values are not minted caps or delivered events; enabling them requires the reopened target-execution task and matching negative/target evidence.
- Worker and driver scheduling fields are compiler-owned and profile-qualified. Current Worker non-MCS values are metadata because no Worker TCB consumes them; driver-task applied scheduling evidence remains a separate implemented lane. Any MCS profile must generate and prove its budget/period, timeout, donation, and consumed-budget contract.
- Refactor-generated module boundaries must not become new public interfaces unless
docs/INTERFACES.md,docs/HOST_TOOLS.md, or the relevant canonical doc is updated in the same change. - HAL/network decompositions must retain generated manifest authority for boot policy defaults and must not hand-code policy values that already belong in
root_task.tomlorcoh-rtcoutputs.
Task Breakdown
Title/ID: m26c-as-built-blocker-ledger
Goal: Record and gate current as-built mismatches before 26c cleanup or downstream milestones claim alignment.
Inputs: docs/BUILD_PLAN.md, AGENTS.md, docs/SECURE9P.md, docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/SECURITY.md, docs/SECURITY_NIST_800_53.md, docs/TEST_PLAN.md, docs/HARDWARE_BRINGUP.md, configs/root_task_pi4_uboot_aarch64.toml, scripts/ci/test_plan_run.sh, apps/root-task/src/net/**, apps/root-task/src/drivers/**, apps/root-task/src/hal/**, apps/root-task/src/ninedoor.rs, apps/pi4-driver-runtime/**, crates/pi4-driver-abi/**, apps/worker-heart/src/kernel.rs, apps/worker-gpu/src/kernel.rs, scripts/release_bundle.sh
Changes:
- docs/audit/M26C_AS_BUILT_BLOCKERS.md — checked-in blocker ledger with owner, severity, dependency impact, evidence command, and closure/defer decision for each initial blocker.
- docs/BUILD_PLAN.md — keep 26c and later milestones synchronized with blocker disposition changes.
- docs/TEST_PLAN.md — reference target-qualified evidence expectations once the runner is implemented.
Commands:
- rg -n "TCP_SMOKE_PORT|31339" apps/root-task scripts docs
- rg -n "read_volatile|write_volatile|from_exposed_addr|phys|MMIO" apps/root-task/src/drivers apps/root-task/src/serial
- cargo test -p secure9p-codec
- scripts/ci/check_test_plan.sh
Checks:
- Initial blocker entries cover 26b evidence, isolated Pi 4 runtime-image acceptance gaps, Pi 4 network IR/docs validation drift, target-qualified runner, Secure9P path validation, non-console in-VM TCP, HAL MMIO ownership, generated-doc drift, fixture/default secrets, placeholder auth defaults, worker-task docs/implementation mismatch, and later-milestone as-built overclaims for persistence, `coh-status`, delegated REST identity, writer-epoch fencing, AI namespace roots, and AWS/ENA/IMDS support.
- No structural cleanup task starts until blockers are fixed or explicitly deferred with dependency impact.
Deliverables:
- Auditable 26c blocker ledger that prevents downstream milestones from inheriting unresolved as-built drift silently.
Title/ID: m26c-target-qualified-runner-baseline
Goal: Make target-qualified staged-run semantics real before any cleanup or structural decomposition depends on them.
Inputs: docs/TEST_PLAN.md, docs/HARDWARE_BRINGUP.md, scripts/ci/test_plan_run.sh, scripts/ci/test_plan_stage_*.sh, scripts/ci/check_test_plan.sh, scripts/pi4-image-build.sh, scripts/uboot/qemu-uboot-smoke.sh
Changes:
- scripts/ci/test_plan_run.sh — add explicit `--target qemu|pi4` selection, write target metadata into the shared state dir, pass the selected target to every stage, and reject unsupported target/stage combinations before a stage can write misleading evidence.
- scripts/ci/test_plan_run.sh + scripts/ci/test_plan_common.sh — add explicit `--iteration` rerun semantics and per-stage input fingerprints so focused reruns cannot be mistaken for target-qualified PASS and stale earlier evidence is detected before later-stage reuse.
- scripts/ci/test_plan_stage_*.sh — consume the selected target and write target-qualified stage markers, logs, iteration markers, input fingerprints, and incomplete records without treating QEMU artifacts as Pi 4 proof or Pi 4 hardware logs as QEMU proof.
- scripts/ci/test_plan_stage_05_due_diligence.sh + scripts/ci/due_diligence_gate.sh — permit Stage 05 to validate and reuse fresh Stage 03 regression evidence from the same state dir while leaving standalone due-diligence exhaustive by default.
- scripts/ci/check_test_plan.sh — enforce that docs, runner usage, stage scripts, and target matrix language agree.
- docs/TEST_PLAN.md + docs/HARDWARE_BRINGUP.md — document the QEMU/Pi 4 target matrix, target-specific prerequisites, allowed stage combinations, state-dir metadata, and PASS/INCOMPLETE interpretation.
- docs/audit/M26C_TARGET_RUNNER_BASELINE.md — checked-in evidence for runner syntax, target matrix, smoke commands, intentionally unsupported combinations, and the rule that Phase 4 cleanup cannot start without this gate.
Commands:
- scripts/ci/test_plan_run.sh --list
- scripts/ci/test_plan_run.sh --target qemu --stage 1 --state-dir out/test-plan/m26c-runner-qemu-smoke
- scripts/ci/test_plan_run.sh --target pi4 --stage 1 --state-dir out/test-plan/m26c-runner-pi4-smoke
- scripts/ci/check_test_plan.sh
Checks:
- `--target qemu|pi4` is accepted by the runner, recorded in the state dir, and visible to every stage script.
- Unsupported target/stage combinations fail before producing `stage_*.done` or target-qualified PASS evidence.
- Focused `--iteration` runs write only `stage_*.iteration` / `stage_*.<target>.iteration` plus input fingerprints, never PASS markers.
- `COHSH_BATCH_GROUPS` subsets are iteration-only; final Stage 03 and due-diligence runs require the full regression batch or verified reuse of a fresh full Stage 03 batch.
- The checker fails if docs mention runner commands, stage matrices, or closure criteria that the scripts do not implement.
- No Phase 4 cleanup or structural decomposition task may start until this runner baseline is present and PASS.
Deliverables:
- Target-aware staged-runner contract and smoke evidence available early enough to guard all later cleanup.
Title/ID: m26c-authoring-charter-and-header-rules
Goal: Replace generic repository-wide authoring templates with explicit human-authored comment, header, and documentation rules.
Inputs: AGENTS.md, CONTRIBUTING.md, README.md, docs/CODING_GUIDELINES.md, docs/API_GUIDELINES.md, docs/BUILD_PLAN.md
Changes:
- AGENTS.md — narrow file-header requirements to legal/provenance metadata plus rules for when comments are required.
- CONTRIBUTING.md — codify review expectations for comment quality, diff shape, subtractive cleanup, and no-regression sequencing.
- README.md — align contributor-facing quality language with the new authoring policy.
- docs/CODING_GUIDELINES.md — define acceptable doc-comment content, prohibited template phrasing, when generic comments should be deleted rather than rewritten, and behavior-preserving cleanup rules.
- docs/API_GUIDELINES.md — require interface docs to describe contracts, invariants, and failure modes instead of file/module summaries.
Commands:
- rg -n "Purpose:|Defines the|Provide(s)? the|CLI entry point|library and public module surface|module for" AGENTS.md CONTRIBUTING.md README.md docs/CODING_GUIDELINES.md docs/API_GUIDELINES.md
- cargo fmt --all -- --check
Checks:
- Repository guidance no longer instructs contributors to write generic file-summary boilerplate.
- Header and comment rules are internally consistent across canonical contributor documents.
Deliverables:
- Canonical authoring policy for human-readable code and docs without hidden behavior changes.
Title/ID: m26c-ai-fingerprint-authorship-review
Goal: Make authored code, docs, tests, and examples read as repository-native work rather than template or model-generated filler.
Inputs: README.md, CONTRIBUTING.md, AGENTS.md, docs/**/*.md, apps/**/README.md, crates/**/README.md, tools/**/*.md, apps/**/src/**/*.rs, crates/**/src/**/*.rs, tools/**/*.rs, tools/cohesix-py/**/*.py, tests/**/*.rs, docs/audit/M26C_MARKDOWN_INVENTORY.csv, docs/audit/M26C_DOCS_AS_BUILT_AUDIT.md, docs/audit/M26C_REFACTOR_MAP.md
Changes:
- docs/audit/M26C_AI_FINGERPRINT_AUDIT.md — checked-in audit of generic phrasing, template comments, repetitive cadence, inflated adjectives, placeholder examples, and non-specific test names, with delete/rewrite/defer decisions and evidence links.
- docs/audit/M26C_AGENT_HANDOFFS.md — record the independent authorship-review lane, reviewer, inspected surfaces, commands, residual gaps, and PASS/FAIL decision.
- README.md + CONTRIBUTING.md + docs/CODING_GUIDELINES.md + docs/API_GUIDELINES.md — document authorship expectations and the difference between required provenance metadata and low-value boilerplate.
- Cohesix-authored docs, comments, tests, and examples classified as low-risk by `M26C_REFACTOR_MAP.md` — delete or rewrite AI-fingerprint findings without changing behavior, grammar, fixture outputs, generated snippets, release snapshots, vendored references, or append-only audit evidence.
Commands:
- rg -n "robust|flexible|seamless|world-class|comprehensive|easy to use|powerful|simple and intuitive|AI-generated|generated by" README.md CONTRIBUTING.md AGENTS.md docs apps crates tools
- rg -n "Defines the|Provides the|CLI entry point|library surface|module for|This module" apps crates tools docs README.md CONTRIBUTING.md AGENTS.md
- cargo fmt --all -- --check
- scripts/check-generated.sh
Checks:
- Every finding is classified as delete, rewrite, acceptable-as-specific, generated/do-not-edit, release-derived, vendored/reference-only, append-only, or deferred with rationale.
- Rewritten prose names the actual Cohesix contract, invariant, failure mode, evidence path, or operator-visible behavior instead of using generic praise or template structure.
- Generated snippets, release snapshots, vendored references, and append-only audit evidence are not hand-edited to satisfy style.
- An independent reviewer lane signs off in `docs/audit/M26C_AGENT_HANDOFFS.md` before low-risk cleanup or public documentation polish is marked complete.
Deliverables:
- Checked-in AI-fingerprint/authorship audit and cleanup evidence that make first-read code and documentation feel specific, technical, and maintained.
Title/ID: m26c-markdown-inventory-and-disposition
Goal: Inventory and disposition every tracked Markdown file in the main Cohesix repository so canonical, generated, release-derived, append-only, and vendored docs are handled correctly.
Inputs: `git ls-files '*.md' | sort`, root/project docs, apps/**/README.md, crates/**/README.md, docs/**/*.md, tracked release-cut docs, seL4/**/*.md, tests/integration/README.md, tools/**/*.md, third_party/**/*.md
Changes:
- docs/audit/M26C_MARKDOWN_INVENTORY.csv — authoritative checked-in inventory/disposition source for every tracked Markdown file returned by `git ls-files '*.md'`.
- docs/audit/M26C_MARKDOWN_INVENTORY.md — rendered human-readable report derived from the checked-in inventory source.
- docs/BUILD_PLAN.md — record milestone scope, disposition rules, and inventory obligations.
- docs/REPO_LAYOUT.md — document Markdown path classes and which ones are canonical, derived, or vendored.
- docs/SECURITY.md — capture documentation provenance rules for generated, release, and vendored Markdown when they influence audit evidence.
Commands:
- git ls-files '*.md' | sort > out/audit/m26c_markdown_inventory.txt
- cut -d, -f1 docs/audit/M26C_MARKDOWN_INVENTORY.csv | sed '1d' | sort > out/audit/m26c_markdown_inventory_checked_in.txt
- diff -u out/audit/m26c_markdown_inventory.txt out/audit/m26c_markdown_inventory_checked_in.txt
Checks:
- Every tracked repository Markdown file is accounted for exactly once in the checked-in inventory.
- Each entry has an explicit disposition and an update rule.
- The rendered report is mechanically derived from the machine-readable source.
Deliverables:
- Auditable Markdown inventory and disposition source/report pair covering canonical docs, release snapshots, audit evidence, reference mirrors, and vendored material.
Title/ID: m26c-mermaid-as-built-diagram-audit
Goal: Inventory, validate, and refine every Mermaid diagram in tracked Markdown so Cohesix visual documentation is as-built, review-grade, and 100% GitHub-online compatible.
Inputs: `git ls-files '*.md' | sort`, README.md, docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/HOST_TOOLS.md, docs/USE_CASES.md, docs/FAILOVER.md, docs/GPU_NODES.md, docs/NETWORK_CONFIG.md, docs/SECURE9P.md, docs/HARDWARE_BRINGUP.md, docs/TEST_PLAN.md, docs/audit/M26C_MARKDOWN_INVENTORY.csv, docs/audit/M26C_DOCS_AS_BUILT_AUDIT.md, apps/root-task/src/hal/**, apps/root-task/src/net/**, apps/root-task/src/event/**, apps/root-task/src/console/**, apps/nine-door/src/host/**, configs/root_task*.toml
Changes:
- docs/audit/M26C_MERMAID_INVENTORY.csv — checked-in inventory of every Mermaid block in tracked Markdown with file, heading, diagram type, disposition, owner, as-built evidence source, GitHub compatibility status, and update rule.
- docs/audit/M26C_MERMAID_GITHUB_RENDER_AUDIT.md — render evidence for every edited or newly added diagram, including GitHub-online proof or the exact compatibility check path used.
- scripts/ci/mermaid_inventory.py — produce the Mermaid inventory from the tracked Markdown list without scanning ignored build outputs or local evidence directories.
- scripts/ci/check_mermaid_github.sh + scripts/ci/render_mermaid_github.sh — fail on unsupported GitHub Mermaid syntax and render all accepted diagrams into 26c audit evidence.
- README.md + docs/*.md + apps/**/README.md + crates/**/README.md + tools/**/*.md — refine stale or underspecified Mermaid diagrams; add new diagrams where canonical docs lack visual explanation of as-built contracts.
- docs/ARCHITECTURE.md — add or refine a HAL architecture Mermaid diagram if the as-built audit shows HAL ownership, driver boundaries, or host/VM capability separation is not clear enough for external review.
Commands:
- git ls-files '*.md' | sort > out/audit/m26c_markdown_inventory.txt
- scripts/ci/mermaid_inventory.py --markdown-list out/audit/m26c_markdown_inventory.txt --out docs/audit/M26C_MERMAID_INVENTORY.csv
- scripts/ci/check_mermaid_github.sh --markdown-list out/audit/m26c_markdown_inventory.txt
- scripts/ci/render_mermaid_github.sh --markdown-list out/audit/m26c_markdown_inventory.txt --out out/audit/m26c-mermaid-rendered
Checks:
- Every Mermaid block in tracked Markdown is inventoried exactly once and classified as canonical human-edited, generated/regenerate-only, release-derived, vendored/reference-only, append-only audit evidence, or external reference mirror.
- Edited and newly added diagrams render correctly in GitHub online and avoid unsupported Mermaid features such as custom init directives, raw HTML labels, external assets, theme CSS, local renderer extensions, or experimental diagram syntax unless GitHub-online proof is archived.
- Canonical diagrams describe the as-built system with enough detail to show authority boundaries, HAL ownership, host/VM separation, generated-manifest authority, Secure9P paths, worker roles, Pi 4 boot/network flows, and operator-visible control/data paths.
- Diagram changes do not contradict generated snippets, manifests, fixtures, test-plan evidence, or the 26c blocker ledger.
Deliverables:
- Review-grade GitHub-renderable Mermaid diagram set with inventory, compatibility proof, and as-built traceability for every tracked Markdown diagram.
Title/ID: m26c-refactor-map-and-risk-ratchet
Goal: Freeze the aggressive refactor scope, ownership, preserved contracts, simplicity targets, and risk-ratchet baseline before structural edits begin.
Inputs: docs/BUILD_PLAN.md, docs/audit/EXCEPTIONS.md, docs/audit/findings.csv, apps/**/src/**/*.rs, crates/**/src/**/*.rs, tools/**/src/**/*.rs, tools/cohesix-py/**/*.py, scripts/ci/*.sh
Changes:
- docs/audit/M26C_REFACTOR_MAP.md — classify each Cohesix-authored candidate as no-touch, low-risk cleanup, characterization-first refactor, boundary-sensitive refactor, or deferred, and assign each accepted wave a single owned surface, preserved-contract list, characterization artifact, target test subset, and rollback-sized scope.
- docs/audit/M26C_SIMPLICITY_SCORECARD.md — record before/after simplification targets for high-value authored surfaces: duplicate branches/helpers to collapse, generic comments to delete, large modules/functions to split or explicitly defer, docs to shorten, abstractions that must justify their existence, and the post-wave scorecard delta.
- docs/audit/M26C_REFACTOR_RISK_RATCHET.csv — record the non-test `unsafe`, `unwrap`, `expect`, and `panic!` baseline plus allowed exceptions and reviewer sign-off requirements.
- docs/audit/M26C_REFACTOR_OWNERSHIP.md — assign disjoint ownership for host tools, root-task adapters, HAL/network, docs/audit, and staged-run plumbing.
- docs/BUILD_PLAN.md — keep 26c scope synchronized with the checked-in map if refactor lanes are added or deferred.
Commands:
- rg -n "unsafe|unwrap\\(|expect\\(|panic!" apps crates tools
- rg -n "Defines the|Provides the|CLI entry point|library surface|module for|This module|robust|flexible|seamless" apps crates tools docs README.md CONTRIBUTING.md AGENTS.md
- cargo fmt --all -- --check
- cargo clippy --workspace --all-targets -- -D warnings
Checks:
- Every structural refactor target has a named owner, preserved external contracts, required characterization evidence, and an explicit rollback-sized scope.
- Every accepted Phase 4 wave is independently reviewable and revertible, with its own target test subset and baseline comparison path.
- Every cleanup/refactor target has a concrete simplicity target or a written deferral reason; "cleaned up" without before/after evidence is not acceptable closure.
- New abstractions are accepted only when the scorecard shows they remove meaningful duplication, isolate authority, reduce module pressure, or make an invariant easier to audit.
- Non-test risk indicators do not increase unless an approved exception is recorded before merge.
- Deferred high-risk refactors have a concrete reason instead of being silently skipped.
Deliverables:
- Checked-in refactor map, simplicity scorecard, ownership plan, and risk-ratchet baseline that make aggressive cleanup auditable.
Title/ID: m26c-docs-as-built-audit
Goal: Audit canonical documentation against the actual generated and observed system before any humanizing prose cleanup lands.
Inputs: docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/HOST_TOOLS.md, docs/SECURE9P.md, docs/SECURITY.md, docs/TEST_PLAN.md, docs/HARDWARE_BRINGUP.md, docs/USERLAND_AND_CLI.md, docs/BOOT_REFERENCE.md, docs/FAILURE_MODES.md, docs/OPERATOR_WALKTHROUGH.md, README.md, docs/snippets/*.md, apps/root-task/src/generated/*, configs/generated/root_task_resolved.json, tracked release-cut docs under releases/**, staged test evidence, scripts/ci/check_test_plan.sh
Changes:
- docs/audit/M26C_DOCS_AS_BUILT_AUDIT.md — trace each canonical doc surface to generated snippets, manifests, fixtures, release artifacts, or staged-run evidence.
- docs/audit/M26C_DOC_DRIFT_LEDGER.md — record docs/script drift discovered during the audit and the closure evidence for each item.
- docs/ARCHITECTURE.md + docs/INTERFACES.md + docs/HOST_TOOLS.md + docs/SECURE9P.md + docs/SECURITY.md + docs/TEST_PLAN.md + docs/HARDWARE_BRINGUP.md + docs/USERLAND_AND_CLI.md + docs/BOOT_REFERENCE.md + docs/FAILURE_MODES.md + docs/OPERATOR_WALKTHROUGH.md + README.md — correct any prose that does not match the current as-built system before tone cleanup begins.
- docs/snippets/*.md + tracked release-cut docs under releases/** — verify provenance and regeneration paths; update only through the proper source or release-cut flow.
- scripts/ci/check_test_plan.sh — update whenever 26c changes authoritative test-plan commands, stage semantics, or target-qualified PASS requirements.
Commands:
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
Checks:
- Canonical docs can be traced to current manifests, generated snippets, fixtures, release snapshots, script behavior, or staged-run evidence.
- Any docs/script drift is corrected or explicitly deferred with scope-safe rationale before humanizing edits are accepted.
Deliverables:
- Auditable docs-as-built report and drift ledger proving documentation truth before presentation cleanup.
Title/ID: m26c-readme-linked-doc-suite-remediation
Milestone: Milestone 26c — Regression-Gated Refactor + Surface Audit / documentation-closure defects discovered during Milestone 26d
Goal: Maintain the human-authored documents linked directly or transitively from `README.md` as one concise, production-grade, as-built suite without changing system behavior or generated truth.
Inputs: README.md, its directly linked human-authored Markdown documents, historical glossary-bearing revisions of docs/HOST_TOOLS.md and docs/USERLAND_AND_CLI.md, AGENTS.md, docs/BUILD_PLAN.md, docs/HOST_API.md, resources/openapi/hive-gateway.yaml, docs/audit/M26C_MARKDOWN_INVENTORY.csv, docs/audit/M26C_DOCS_AS_BUILT_AUDIT.md, docs/audit/M26C_DOC_DRIFT_LEDGER.md, docs/audit/M26C_MERMAID_INVENTORY.csv, configs/root_task*.toml, configs/generated/root_task_resolved.json, docs/snippets/*.md, current CLI help, source/tests, current target-qualified evidence, and the Milestone 26d Pi 4 proof boundary.
Changes:
- README.md — present current scope, evidence status, supported targets, safe getting-started paths, and a categorized documentation map without release or hardware overclaiming.
- docs/ARCHITECTURE.md + docs/INTERFACES.md + docs/SECURE9P.md + docs/ROLES_AND_SCHEDULING.md + docs/DRIVERS.md — establish non-overlapping ownership for architecture, external contracts, protocol invariants, role/scheduling policy, and physical-driver methodology.
- docs/USERLAND_AND_CLI.md + docs/HOST_TOOLS.md + docs/API_GUIDELINES.md + docs/PYTHON_SUPPORT.md + docs/FAILURE_MODES.md + docs/OPERATOR_WALKTHROUGH.md — establish one operator journey, one tool catalogue, and cross-referenced API, Python, and recovery guidance grounded in current command help and fixtures.
- resources/openapi/hive-gateway.yaml + docs/HOST_API.md — correct the machine-readable placement of the existing optional `TAIL lines` query and replace the stale duplicated schema mirror with a concise link-backed operator reference, without changing gateway behavior.
- docs/USE_CASES.md + docs/HARDWARE_BRINGUP.md + docs/BOOT_REFERENCE.md + docs/GPU_NODES.md + docs/BENCHMARKS.md — separate implemented capability, current proof, historical evidence, candidate deployment patterns, and planned work; keep flash, current-image boot, transport, and benchmark proof lanes distinct.
- docs/BUILD_PLAN.md — record this restoration-only scope and return 26c to `Complete` only after every check below passes.
- docs/OPERATOR_RECIPES.md — when needed, own task-oriented evidence, mount, lifecycle, PEFT, and federation workflows so the canonical walkthrough remains one ordered journey.
- docs/GLOSSARY.md — own plain-language definitions for Cohesix-specific terms and the foundational OS, security, protocol, AI, hardware, and proof concepts needed to understand them; link to owning contract documents rather than restating full schemas or limits.
- CONTRIBUTING.md + docs/QUICKSTART.md + docs/SECURITY.md + docs/TOOLCHAIN_MAC_ARM64.md — keep the transitive onboarding and project-governance perimeter consistent with current security, validation, release, and seL4 16 requirements.
- Canonical Mermaid blocks — retain only diagrams that materially clarify an as-built boundary or sequence; validate both syntax and semantic ownership against code, manifests, and current evidence.
- docs/audit/M26C_DOCS_AS_BUILT_AUDIT.md + docs/audit/M26C_DOC_DRIFT_LEDGER.md + docs/audit/M26C_MERMAID_INVENTORY.csv + docs/audit/M26C_MERMAID_GITHUB_RENDER_AUDIT.md + docs/audit/M26C_AGENT_HANDOFFS.md + docs/audit/M26C_SIMPLICITY_SCORECARD.md — refresh the live audit records with source anchors, before/after size and ownership evidence, lane handoffs, and the final Mermaid inventory/render result.
Commands:
- git ls-files '*.md' | sort > out/audit/m26c-doc-remediation-markdown.txt
- scripts/ci/mermaid_inventory.py --markdown-list out/audit/m26c-doc-remediation-markdown.txt --out docs/audit/M26C_MERMAID_INVENTORY.csv
- scripts/ci/check_mermaid_github.sh --markdown-list out/audit/m26c-doc-remediation-markdown.txt
- scripts/ci/render_mermaid_github.sh --markdown-list out/audit/m26c-doc-remediation-markdown.txt --out out/audit/m26c-doc-remediation-mermaid-rendered
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
- scripts/ci/test_plan_run.sh --list
- python3 scripts/ci/check_driver_test_coverage.py
- cargo check --workspace
- cargo test -p hive-gateway
- git diff --check
Checks:
- Every directly linked canonical document has one stated purpose, an explicit as-built or planning boundary, retained 2026 Lukas Bower metadata, and useful cross-references instead of copied contracts.
- Every transitive onboarding, contribution, security, and toolchain guide reached from the suite is current, secret-safe, reproducible, and consistent with the charter.
- Durable public namespace, record, derivation, evidence-pack, driver-profile, and simulation contracts remain documented even when generated mirrors and historical debug prose are removed.
- Every Cohesix-specific term used by the README documentation map is defined for a newcomer or points to a more specific canonical definition; collision-prone terms such as LoRA prose versus lowercase `lora` identifiers, NineDoor/NineDoorBridge, host/target, mock/QEMU/hardware, and source/resolved manifest are explicitly distinguished.
- Selected-profile manifests, resolved output, generated snippets, current source/tests, and target-qualified evidence remain authoritative; generated snippets are linked or reproduced only through their generator and are not hand-edited.
- Current QEMU evidence, accepted historical Pi 4 evidence, current-image Pi 4 revalidation, Wi-Fi research status, host-only integrations, and future milestones are never presented as interchangeable proof.
- All local links and referenced anchors resolve, code fences are balanced, Markdown is structurally consistent, and every active Mermaid block passes the GitHub compatibility checker plus an available CLI render pass.
- No runtime command, endpoint implementation, namespace, ACK/ERR/END behavior, authority path, release snapshot, or hardware acceptance state changes under the documentation rewrite; the OpenAPI correction describes existing handler behavior.
Deliverables:
- A reviewable README-linked documentation suite with clear information ownership, materially less repetition, complete GitHub-compatible diagrams, and validation evidence.
Title/ID: m26c-runtime-boundary-and-semantic-parity-audit
Goal: Document the intentional host `std` / VM `no_std` runtime split and prove overlapping NineDoor semantics remain aligned without runtime convergence.
Inputs: apps/root-task/src/ninedoor.rs, apps/root-task/src/event/**, apps/root-task/src/console/**, apps/root-task/src/log_buffer.rs, apps/root-task/src/lib.rs, apps/root-task/src/net/**, apps/root-task/src/hal/**, apps/root-task/src/local_seat.rs, apps/root-task/tests/**, apps/nine-door/src/host/*.rs, apps/nine-door/tests/*.rs, docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/SECURE9P.md, docs/SECURITY.md, docs/audit/M26C_DOCS_AS_BUILT_AUDIT.md, docs/audit/M26C_REFACTOR_MAP.md
Changes:
- docs/audit/M26C_RUNTIME_BOUNDARY_AUDIT.md — record VM TCB boundaries, forbidden host-side capabilities in the VM, and adapter ownership of host/VM surfaces.
- docs/audit/M26C_NINEDOOR_PARITY_MATRIX.md — enumerate overlapping host/VM semantics, expected outputs, and evidence paths for each parity claim.
- docs/ARCHITECTURE.md + docs/INTERFACES.md + docs/SECURE9P.md + docs/SECURITY.md — replace any ambiguous "eventual merge" language with explicit boundary language: separate adapters, shared contracts only.
- apps/nine-door/tests/*.rs + apps/root-task/tests/** and host-mode root-task bridge tests — add or extend parity coverage for overlapping operator-visible surfaces without changing protocol grammar.
Commands:
- cargo test -p nine-door --test integration
- cargo test -p root-task --tests
- cargo test -p root-task --lib
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
Checks:
- Checked-in audit artifacts state clearly that VM-side Cohesix remains `no_std` and that host `std` capability is not a valid convergence target.
- Every overlapping host/VM semantic surface in the parity matrix has either passing test evidence from the relevant `apps/nine-door` and `root-task` test suites or an explicit host-only/VM-only disposition.
- Canonical docs describe the runtime split as intentional architecture rather than an accidental temporary inconsistency.
Deliverables:
- Auditable runtime-boundary report and semantic-parity matrix that establish the proof surface required before boundary-sensitive runtime refactors.
Title/ID: m26c-pi-runtime-dma-proof-closure
Goal: Define and prove Pi 4 isolated runtime descriptor, DMA, owner-state, and artifact-freshness evidence before 26c cleanup or later operator tooling cites the runtime path as closed.
Inputs: apps/root-task/src/hal/**, apps/root-task/src/local_seat.rs, apps/root-task/src/generated/**, apps/pi4-driver-runtime/src/**, crates/pi4-driver-abi/src/**, configs/root_task_pi4_uboot_aarch64.toml, scripts/pi4-image-build.sh, scripts/ci/test_plan_run.sh, docs/TEST_PLAN.md, docs/HARDWARE_BRINGUP.md, docs/audit/M26C_DOCS_AS_BUILT_AUDIT.md
Changes:
- crates/pi4-driver-abi/src/** — add or tighten descriptor-resource tests for runtime MMIO, DMA, shared-buffer, IRQ, bus-alias, and framebuffer ranges emitted by generated Pi 4 driver-image records.
- apps/pi4-driver-runtime/src/** — add runtime tests that classify DMA reservation/allocation and owner-state evidence without relying on root-owned fallback paths.
- apps/root-task/src/hal/** + apps/root-task/src/local_seat.rs — surface bounded evidence for DMA arena reservation, bus-address publication, cache maintenance, runtime-init descriptor delivery, and hardware-state handoff while preserving HAL-only authority.
- docs/audit/M26C_DOCS_AS_BUILT_AUDIT.md + docs/TEST_PLAN.md + docs/HARDWARE_BRINGUP.md — define absent, stale, generated-only, target-build, QEMU, fresh Pi hardware proof, valid counter snapshot, and arch-counter timer-backend proof states and require source artifact provenance for each claim.
- scripts/ci/test_plan_run.sh + stage checks where needed — fail 26c Pi closure if runtime/DMA proof is absent, stale, or inferred from generated eligibility alone.
Commands:
- cargo test -p pi4-driver-abi
- cargo test -p pi4-driver-runtime
- cargo test -p root-task --tests
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- scripts/check-generated.sh
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
- scripts/pi4_gate_proof.sh --require-driver-task-proof
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26c-pi4
Checks:
- Runtime-image eligibility, descriptor resource totals, DMA reservation/allocation evidence, owner-state fields, and source artifact freshness are reported separately.
- Missing DMA proof is a blocking absent-evidence state, not inferred success from manifest generation, target compilation, QEMU smoke output, or stale serial logs.
- Isolated runtime performance proof requires valid `DRIVER_TASK_COUNTER` evidence plus Pi arch-counter proof (`TIMER_BACKEND=arch-counter`, `TIMER_CLOCK_HZ=54000000`, `TIMER_EL0_COUNTER=vct`, `DUMMY_TIMER_SEEN=no`); counters alone remain diagnostic.
- DMA ownership, cache maintenance, bus-address publication, runtime-init descriptor delivery, and hardware handoff remain behind HAL/generated interfaces with no direct MMIO or ad-hoc physical-address path.
- Fresh Pi evidence, when claimed, names the exact serial log, manifest hash, image build, and test-plan state directory used for the claim.
Deliverables:
- 26c-owned Pi 4 runtime/DMA proof semantics and evidence gates strong enough for later operator tools to project read-only summaries without defining acceptance.
Title/ID: m26c-dma-protection-profile-truth
Goal: Add compiler-owned DMA protection profiles that state Pi 4 as bounded no-IOMMU DMA discipline and reserve SMMU-backed isolation claims for future hardware profiles.
Inputs: tools/coh-rtc/src/ir.rs, tools/coh-rtc/src/validate.rs, configs/root_task_pi4_uboot_aarch64.toml, configs/root_task.toml, apps/root-task/src/hal/**, docs/ARCHITECTURE.md, docs/HARDWARE_BRINGUP.md, docs/SECURITY.md, docs/TEST_PLAN.md, docs/audit/M26C_DOCS_AS_BUILT_AUDIT.md
Changes:
- tools/coh-rtc/src/ir.rs + tools/coh-rtc/src/validate.rs — add a generated DMA protection profile enum such as `none`, `bounded_no_iommu`, `smmu_v2`, and `smmu_v3`, with Pi 4 profiles required to resolve to `bounded_no_iommu`.
- configs/root_task_pi4_uboot_aarch64.toml + generated manifests/snippets — record Pi 4 DMA as HAL-mediated bounded DMA ownership, not hardware-enforced IOMMU/SMMU isolation.
- apps/root-task/src/hal/** — expose profile-specific evidence fields for bounded arenas, descriptor validation, bus-address publication, cache maintenance, buffer quarantine, and absent SMMU capability.
- docs/ARCHITECTURE.md + docs/HARDWARE_BRINGUP.md + docs/SECURITY.md + docs/TEST_PLAN.md — document the Pi 4 limitation, prohibit SMMU/IOMMU isolation wording for BCM2711, and define the future SMMU hardware contract separately.
- docs/audit/M26C_DOCS_AS_BUILT_AUDIT.md — add a docs-as-built check that rejects diagrams, prose, or evidence claims that imply Pi 4 malicious-device DMA confinement.
Commands:
- cargo test -p coh-rtc dma_protection
- cargo test -p root-task --tests dma
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- scripts/check-generated.sh
- rg -n "IOMMU|SMMU|hardware-enforced DMA|DMA isolation" docs README.md AGENTS.md
Checks:
- Pi 4 manifests and docs resolve to bounded no-IOMMU DMA discipline and explicitly refuse hardware-enforced SMMU/IOMMU isolation claims.
- Bounded Pi 4 DMA evidence covers per-driver arenas, descriptor validation, bus-address publication, cache maintenance, quarantine/reuse policy, and fresh proof provenance.
- Future `smmu_v2` or `smmu_v3` profiles cannot be enabled unless generated per-device DMA-domain state, StreamID/context-bank or equivalent IO-space mapping policy, fault evidence, and revoke/unmap semantics are present.
- No public doc, Mermaid diagram, evidence pack, or operator output describes BCM2711/Pi 4 as providing malicious-device DMA confinement.
Deliverables:
- Review-grade DMA protection vocabulary that keeps Pi 4 claims honest while preserving a clean path to real SMMU-backed targets.
Inactive historical proposal — superseded as active Milestone 26c work and not
authorized by the truth-correction reopening:
Title/ID: m26c-worker-architecture-implementation
Status: Inactive and superseded as active 26c work; retained for historical traceability only.
Goal: Replace placeholder kernel-side worker GPU/LoRA paths with real seL4 worker ticket, lease, telemetry, and revocation loops matching public Queen/Worker documentation.
Inputs: apps/worker-heart/src/**, apps/worker-gpu/src/**, apps/worker-lora/src/**, apps/root-task/src/ninedoor.rs, apps/root-task/src/event/**, apps/root-task/src/lifecycle.rs, apps/root-task/src/generated/**, tools/coh-rtc/src/**, crates/cohesix-ticket/**, docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/GPU_NODES.md, docs/WORKER_TICKETS.md, docs/ROLES_AND_SCHEDULING.md, docs/SECURITY.md, docs/TEST_PLAN.md
Changes:
- apps/worker-heart/src/kernel.rs — implement the VM-side heartbeat worker loop that attaches with a scoped worker ticket, emits bounded telemetry to the documented worker path, observes lifecycle/revocation state, and exits deterministically on shutdown.
- apps/worker-gpu/src/kernel.rs + apps/worker-gpu/src/lib.rs — replace placeholder spin/stub behavior with a no_std worker loop that consumes WorkerGpu tickets, reads lease/model pointers through the documented namespace, emits GPU lease/job telemetry receipts, and never touches CUDA/NVML or raw GPU hardware.
- apps/worker-lora/src/lib.rs + apps/worker-lora/src/common.rs — implement the VM-side LoRA worker control/telemetry loop for ticket-scoped adapter/model lifecycle receipts while keeping training, TensorRT, CUDA, and PEFT execution host-side.
- apps/root-task/src/ninedoor.rs + apps/root-task/src/event/** + apps/root-task/src/lifecycle.rs — publish worker namespace entries, ticket-gated attach state, lease/lifecycle revocation signals, and bounded telemetry paths needed by the VM workers without changing Secure9P grammar.
- tools/coh-rtc/src/ir.rs + tools/coh-rtc/src/validate.rs + generated snippets — add worker-role implementation state, ticket scopes, lease paths, telemetry bounds, shutdown/revoke policy, and docs-as-built validation so public worker claims are compiler-aligned.
- docs/ARCHITECTURE.md + docs/INTERFACES.md + docs/GPU_NODES.md + docs/WORKER_TICKETS.md + docs/ROLES_AND_SCHEDULING.md + docs/SECURITY.md + docs/TEST_PLAN.md — update public Queen/Worker behavior to match the implemented seL4 worker loops and host-only GPU/PEFT boundaries.
Commands:
- cargo test -p worker-heart
- cargo test -p worker-gpu
- cargo test -p worker-lora
- cargo test -p root-task --tests worker
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- scripts/check-generated.sh
- cargo check -p worker-heart --target aarch64-unknown-none
- cargo check -p worker-gpu --target aarch64-unknown-none
- cargo check -p worker-lora --target aarch64-unknown-none
Checks:
- Worker-heart, worker-gpu, and worker-lora no longer rely on placeholder kernel spin loops for public VM worker semantics.
- Each worker loop uses scoped tickets and documented namespace paths, emits bounded telemetry/receipts, and handles lease expiry, lifecycle cut, revocation, and shutdown deterministically.
- GPU and LoRA workers remain control-plane workers only: CUDA, NVML, TensorRT, PEFT training/import execution, and raw hardware access stay host-side.
- Generated manifests and docs agree on which worker roles are implemented, which paths they may access, and which telemetry/lease bounds apply.
- Existing console grammar, Secure9P framing, ACK/ERR/END behavior, and host-side worker helper APIs do not drift.
Deliverables:
- Real seL4 worker architecture matching public Queen/Worker docs, with host/VM boundaries and tests strong enough for 26c closure.
Inactive historical proposal — superseded as active Milestone 26c work and not
authorized by the truth-correction reopening:
Title/ID: m26c-cap-backed-worker-endpoints
Status: Inactive and superseded as active 26c work; retained for historical traceability only.
Goal: Make first-phase VM worker tickets cap-backed by requiring badged seL4 endpoint capabilities for worker attach, telemetry, lease renewal, and revocation-sensitive paths.
Inputs: apps/root-task/src/lifecycle.rs, apps/root-task/src/ninedoor.rs, apps/root-task/src/event/**, apps/root-task/src/generated/**, apps/worker-heart/src/**, apps/worker-gpu/src/**, apps/worker-lora/src/**, tools/coh-rtc/src/**, crates/cohesix-ticket/**, docs/WORKER_TICKETS.md, docs/ROLES_AND_SCHEDULING.md, docs/SECURITY.md, docs/INTERFACES.md
Changes:
- apps/root-task/src/lifecycle.rs + apps/root-task/src/event/** — mint role/lease/epoch-badged endpoint caps for worker attach, control, telemetry, and revoke-sensitive receipt paths; retain the parent cap path needed to revoke derived lease caps.
- apps/root-task/src/ninedoor.rs — reject worker attach, telemetry append, lease-renewal, and receipt paths when only ticket metadata is present and no matching badged endpoint cap was invoked.
- apps/worker-heart/src/** + apps/worker-gpu/src/** + apps/worker-lora/src/** — replace metadata-only ticket presentation with endpoint-cap invocation in the worker loops while preserving bounded no_std behavior.
- tools/coh-rtc/src/** + generated snippets — add the historical proposal's phase-1 cap-backed-ticket fields for endpoint badges, lease epochs, role scopes, revoke behavior, and explicit deferred full-cap-bundle status. This design was never accepted; Milestone 26e now owns the complete live Worker bundle and Milestone 27e only adds production ticket/lease ledger binding.
- docs/WORKER_TICKETS.md + docs/ROLES_AND_SCHEDULING.md + docs/SECURITY.md + docs/INTERFACES.md — document Cohesix tickets as audit records backed by badged endpoint caps for VM worker authority.
Commands:
- cargo test -p root-task --tests worker
- cargo test -p worker-heart
- cargo test -p worker-gpu
- cargo test -p worker-lora
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- scripts/check-generated.sh
- cargo check -p worker-heart --target aarch64-unknown-none
- cargo check -p worker-gpu --target aarch64-unknown-none
- cargo check -p worker-lora --target aarch64-unknown-none
Checks:
- Forged ticket strings or stale ticket metadata without the corresponding badged endpoint cap cannot attach as a worker, renew a lease, emit accepted telemetry, or publish a valid receipt.
- Revocation deletes or invalidates the derived endpoint caps and late invocations from the old lease epoch fail deterministically.
- Historical generated manifests and docs would have distinguished phase-1 endpoint-cap-backed tickets from later work; active planning instead requires complete live bundles in Milestone 26e and production ledger binding in Milestone 27e.
- Existing Secure9P grammar, console ACK/ERR/END behavior, and host-ticket schemas do not drift.
Deliverables:
- First-phase cap-backed VM worker ticket authority with concrete seL4 endpoint caps and negative tests, without overclaiming full frame/notification/DMA cap-bundle isolation.
Inactive historical proposal — superseded as active Milestone 26c work and not
authorized by the truth-correction reopening:
Title/ID: m26c-notification-backed-worker-lifecycle
Status: Inactive and superseded as active 26c work; retained for historical traceability only.
Goal: Replace lifecycle polling dependency with generated seL4 notification objects for worker revoke, shutdown, lease expiry, telemetry pressure, and driver IRQ wakeups.
Inputs: apps/root-task/src/lifecycle.rs, apps/root-task/src/event/**, apps/root-task/src/hal/**, apps/root-task/src/generated/**, apps/worker-heart/src/**, apps/worker-gpu/src/**, apps/worker-lora/src/**, apps/pi4-driver-runtime/src/**, tools/coh-rtc/src/**, docs/ROLES_AND_SCHEDULING.md, docs/SECURITY.md, docs/INTERFACES.md, docs/TEST_PLAN.md
Changes:
- tools/coh-rtc/src/** — add generated notification lifecycle fields and badge classes for revoke, shutdown, lease-expiry, telemetry-pressure, and IRQ events where applicable.
- apps/root-task/src/lifecycle.rs + apps/root-task/src/event/** — publish notification caps/badges to worker loops and signal lifecycle changes without introducing new protocols or namespace grammar.
- apps/root-task/src/hal/** + apps/pi4-driver-runtime/src/** — keep driver IRQ delivery notification-backed and expose bounded evidence for notification badges and acknowledgement behavior.
- apps/worker-heart/src/** + apps/worker-gpu/src/** + apps/worker-lora/src/** — wait on endpoint IPC plus notification delivery for lifecycle changes, and remove unbounded lifecycle polling from worker loops.
- docs/ROLES_AND_SCHEDULING.md + docs/SECURITY.md + docs/INTERFACES.md + docs/TEST_PLAN.md — document the historical notification-backed lifecycle proposal and badge meanings. This design was never accepted; Milestone 26e now owns complete lifecycle/completion notification authority and Milestone 27e only binds the accepted Worker bundle to production ticket/lease ledgers.
Commands:
- cargo test -p root-task --tests worker
- cargo test -p root-task --tests notification
- cargo test -p worker-heart
- cargo test -p worker-gpu
- cargo test -p worker-lora
- cargo test -p pi4-driver-runtime
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- scripts/check-generated.sh
Checks:
- Revoke, shutdown, lease-expiry, telemetry-pressure, and applicable IRQ events are delivered through generated notification caps/badges rather than unbounded lifecycle polling.
- Worker loops block or yield deterministically while waiting for endpoint IPC or notification events and still handle lease expiry, revoke, telemetry backpressure, and shutdown.
- Driver IRQ notification behavior remains HAL-owned and does not create a new polling path or direct IRQ bypass outside generated descriptors.
- Historical generated docs would have distinguished the 26c notification proposal from later work; active planning instead requires complete lifecycle/completion notification authority in Milestone 26e and production ledger binding in Milestone 27e.
Deliverables:
- Event-driven worker and driver lifecycle signaling with seL4 notification objects, bounded tests, and no new Cohesix protocol surface.
Inactive historical proposal — superseded as active Milestone 26c work and not
authorized by the truth-correction reopening. Its future replacement is owned
by the staged Milestone 26e MCS tasks and must satisfy
`docs/audit/M26D_MCS_DECISION.md` first:
Title/ID: m26c-worker-driver-mcs-budget-evidence
Status: Inactive and superseded as active 26c work; retained for historical traceability only.
Goal: Preserve the record of the rejected 26c dual-scheduler proposal without authorizing its fallback design.
Inputs: docs/audit/M26D_MCS_DECISION.md, Milestone 26e `m26e-mcs-abi-foundation`, Milestone 26e `m26e-mcs-smp-target-acceptance`.
Changes:
- None authorized. Milestone 26e replaces this proposal with one SMP+MCS QEMU/Pi architecture and no compiled classic fallback.
Commands:
- None; this task is not executable.
Checks:
- No implementation or fallback-profile claim cites this historical proposal.
Deliverables:
- Traceability from the superseded proposal to the selected Milestone 26e SMP+MCS tasks.
Title/ID: m26c-post-behavior-baseline-freeze
Goal: Freeze the external behavior snapshot after the authorized 26c worker/runtime additions and before cleanup refactors begin.
Inputs: docs/audit/M26C_DOCS_AS_BUILT_AUDIT.md, docs/audit/M26C_RUNTIME_BOUNDARY_AUDIT.md, docs/audit/M26C_NINEDOOR_PARITY_MATRIX.md, docs/audit/M26C_TARGET_RUNNER_BASELINE.md, docs/audit/M26C_REFACTOR_MAP.md, apps/root-task/tests/**, apps/nine-door/tests/**, worker test suites, generated snippets/manifests, scripts/ci/test_plan_run.sh, scripts/ci/check_test_plan.sh
Changes:
- docs/audit/M26C_POST_BEHAVIOR_BASELINE.md — record the post-Phase-2 external contract snapshot: console grammar, Secure9P/NineDoor namespace semantics, manifest and generated-snippet hashes, worker ticket/lease/telemetry/lifecycle behavior, cap-backed endpoint evidence, notification evidence, then-current scheduling evidence, Pi runtime/DMA evidence classifications, and known deferred blockers.
- docs/audit/M26C_REFACTOR_MAP.md — link every Phase 4 cleanup candidate to the relevant post-behavior baseline section and preserved-contract list.
- docs/audit/M26C_AGENT_HANDOFFS.md — record the freeze decision, commands, skipped commands, residual blockers, and PASS/FAIL status before any cleanup lane starts.
- docs/TEST_PLAN.md — state that Phase 4 refactors compare against the post-behavior baseline rather than pre-26c placeholder worker behavior.
Commands:
- scripts/check-generated.sh
- cargo test -p nine-door --test integration
- cargo test -p root-task --tests
- cargo test -p worker-heart
- cargo test -p worker-gpu
- cargo test -p worker-lora
- scripts/ci/check_test_plan.sh
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26c-post-behavior-qemu
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26c-post-behavior-pi4
Checks:
- The baseline is recorded only after all authorized Phase 2 behavior-changing tasks are complete or explicitly deferred without being used as satisfied evidence.
- Refactor waves use this post-behavior snapshot as their preserved external contract, so cleanup does not accidentally revert or mutate the new intended worker/cap/notification/MCS behavior.
- Any remaining Pi 4 or runner blocker is recorded with dependency impact, and no Phase 4 task cites blocked evidence as proof.
- The target-qualified QEMU/Pi 4 state dirs and command outputs named in the baseline match the runner contract from `m26c-target-qualified-runner-baseline`.
Deliverables:
- Hard baseline separating authorized 26c behavior changes from later behavior-preserving cleanup.
Title/ID: m26c-characterization-gates-before-refactor
Goal: Add characterization tests and merge gates around cleanup-sensitive crates before accepting structural refactors.
Inputs: .github/workflows/ci.yml, scripts/ci/test_plan_run.sh, scripts/ci/test_plan_stage_*.sh, scripts/ci/check_test_plan.sh, apps/coh/src/mount.rs, apps/cohsh/src/**, crates/cohsh-core/**, apps/host-ticket-agent/src/*.rs, apps/gpu-bridge-host/src/**, apps/root-task/src/net/**, apps/root-task/src/hal/**, apps/root-task/src/local_seat.rs, apps/root-task/src/ninedoor.rs, apps/root-task/src/event/**, apps/root-task/src/console/**, apps/pi4-driver-runtime/**, crates/pi4-driver-abi/**, apps/nine-door/tests/*.rs, docs/TEST_PLAN.md, docs/audit/M26C_REFACTOR_MAP.md
Changes:
- .github/workflows/ci.yml — stop excluding cleanup-sensitive crates without compensating gate coverage, or add explicit targeted jobs for `coh`, `cohsh`, `cohsh-core`, `host-ticket-agent`, `gpu-bridge-host`, `root-task`, `pi4-driver-abi`, `pi4-driver-runtime`, and `nine-door` parity surfaces.
- scripts/ci/test_plan_stage_02_host_fast.sh — exercise `coh`, `cohsh`, `cohsh-core`, `host-ticket-agent`, `gpu-bridge-host`, `nine-door` integration coverage, `root-task --tests`, `root-task --lib`, `pi4-driver-abi`, `pi4-driver-runtime`, and VM-target boundary checks as first-class checks.
- scripts/ci/check_test_plan.sh — enforce the updated target-aware staged-run contract and authoritative command matrix.
- docs/TEST_PLAN.md — document the expanded cleanup-target coverage, VM boundary evidence, target-qualified artifacts, post-behavior baseline comparison, and required artifact retention.
- apps/coh/src/mount.rs + apps/cohsh/src/** + crates/cohsh-core/** + apps/host-ticket-agent/src/*.rs + apps/gpu-bridge-host/src/** + selected apps/root-task/src/* helpers + selected `apps/nine-door` and root-task parity surfaces — add characterization tests for current outputs, errors, and state transitions before refactor.
Commands:
- cargo test -p coh --features mock
- cargo test -p cohsh
- cargo test -p cohsh-core
- cargo test -p host-ticket-agent
- cargo test -p gpu-bridge-host
- cargo test -p nine-door --test integration
- cargo test -p root-task --tests
- cargo test -p root-task --lib
- cargo test -p pi4-driver-abi
- cargo test -p pi4-driver-runtime
- cargo check -p pi4-driver-runtime --target aarch64-unknown-none
- rg -n "unsafe|unwrap\\(|expect\\(|panic!" apps crates tools
- scripts/ci/check_test_plan.sh
Checks:
- Cleanup-sensitive crates have deterministic tests that pin current operator-visible behavior.
- Characterization artifacts name the post-behavior baseline section they preserve, so behavior-changing Phase 2 work and behavior-preserving Phase 4 cleanup cannot be conflated.
- Driver runtime ABI descriptors, isolated runtime service turns, acceptance-eligibility fixtures, and board-proof boundaries remain pinned before cleanup touches driver-task code.
- CI and staged test-plan coverage run those tests automatically and retain root-task VM-boundary evidence and target-qualified staged-run artifacts.
- Risk-ratchet output is attached to refactor reviews and does not drift without an approved exception.
Deliverables:
- Regression safety net expanded ahead of structural cleanup.
Title/ID: m26c-no-std-boundary-gates
Goal: Add explicit CI and audit gates that fail if host-side capability leaks into the VM build across the closure profiles used by 26c.
Inputs: .github/workflows/ci.yml, scripts/ci/test_plan_stage_02_host_fast.sh, apps/root-task/Cargo.toml, apps/nine-door/Cargo.toml, apps/pi4-driver-runtime/Cargo.toml, crates/pi4-driver-abi/Cargo.toml, configs/root_task.toml, configs/root_task_pi4_uboot_aarch64.toml, docs/TEST_PLAN.md, docs/ARCHITECTURE.md
Changes:
- .github/workflows/ci.yml — add root-task VM-profile and `pi4-driver-runtime` `no_std` checks and archive dependency-tree artifacts for the QEMU `cohesix-dev` and Pi 4 U-Boot closure profiles at minimum.
- scripts/ci/test_plan_stage_02_host_fast.sh — emit `out/audit/m26c_root_task_tree_qemu.txt`, `out/audit/m26c_root_task_tree_pi4.txt`, and driver-runtime VM-target dependency evidence (or equivalent state-dir artifacts) from the VM-target dependency tree as part of cleanup gating.
- docs/TEST_PLAN.md + docs/ARCHITECTURE.md — document the VM boundary gate, expected artifacts, and interpretation rules per closure profile.
- docs/BUILD_PLAN.md — record that shared semantic helpers are allowed only when they remain `no_std`-safe and do not drag host-side crates into the VM build.
Commands:
- cargo check -p root-task --target aarch64-unknown-none --no-default-features --features "cohesix-dev"
- cargo tree -p root-task --target aarch64-unknown-none -e normal --no-default-features --features "cohesix-dev" > out/audit/m26c_root_task_tree_qemu.txt
- cargo check -p root-task --target aarch64-unknown-none --no-default-features --features "kernel bootstrap-trace serial-console net-console"
- cargo tree -p root-task --target aarch64-unknown-none -e normal --no-default-features --features "kernel bootstrap-trace serial-console net-console" > out/audit/m26c_root_task_tree_pi4.txt
- cargo check -p pi4-driver-runtime --target aarch64-unknown-none
- cargo tree -p pi4-driver-runtime --target aarch64-unknown-none -e normal > out/audit/m26c_pi4_driver_runtime_tree.txt
- scripts/ci/check_test_plan.sh
Checks:
- The VM-target root-task build and Pi 4 isolated driver runtime build remain `no_std` and succeed without host-side operator/tooling dependencies across the closure profiles.
- The dependency-tree artifacts are reviewed as part of 26c evidence and show no accidental pull-in of host-only surfaces.
- Cleanup work cannot merge if boundary evidence is missing or contradicts the documented VM/host split.
Deliverables:
- Explicit per-profile `no_std` boundary gate for cleanup-era work, reducing drift risk without touching runtime behavior.
Title/ID: m26c-low-risk-surface-cleanup
Goal: Humanize the highest-visibility low-risk code and doc surfaces after docs-as-built, AI-fingerprint, characterization, and no-std gates cover the touched surface.
Inputs: apps/*/README.md, crates/**/README.md, tools/cohesix-py/README.md, tests/integration/README.md, public crate roots under apps/*/src/lib.rs, tests/**/*.rs, docs/OPERATOR_WALKTHROUGH.md, docs/QUICKSTART.md, docs/QUICKSTART_ALPHA.md, docs/audit/M26C_DOCS_AS_BUILT_AUDIT.md, docs/audit/M26C_AI_FINGERPRINT_AUDIT.md
Changes:
- apps/*/README.md + crates/**/README.md + tools/cohesix-py/README.md + tests/integration/README.md — replace template summaries with role-specific descriptions, assumptions, and operator-facing boundaries.
- apps/*/src/lib.rs + apps/*/src/main.rs + crates/**/src/lib.rs — remove generic module-surface comments and rewrite surviving doc comments around invariants or usage.
- tests/**/*.rs — rename template-like test names/descriptions to scenario-driven names and tighten helper naming.
- docs/OPERATOR_WALKTHROUGH.md + docs/QUICKSTART.md + docs/QUICKSTART_ALPHA.md — remove repetitive prose and keep operator sequences concrete.
Commands:
- cargo test -p secure9p-core
- cargo test -p cohsh-core
- cargo test -p tests --quiet
Checks:
- High-visibility surface files read as authored, file-specific documentation instead of generated scaffolding.
- Humanized docs remain consistent with the audit evidence produced by `m26c-docs-as-built-audit`.
- AI-fingerprint findings for touched low-risk surfaces are closed or explicitly deferred in `docs/audit/M26C_AI_FINGERPRINT_AUDIT.md`.
- Each cleanup batch maps to one accepted wave in `M26C_REFACTOR_MAP.md`, with a preserved-contract list, targeted tests, and before/after scorecard evidence.
- The simplicity scorecard shows net clarity improvement for touched surfaces; cleanup-only changes that add more prose, wrappers, or concepts than they remove require explicit reviewer justification.
- Test names and doc comments describe behaviors and scenarios, not file names.
Deliverables:
- First-wave cleanup across low-risk surfaces with zero behavior changes and passing tests.
Title/ID: m26c-host-tool-structural-cleanup
Goal: Refactor repetitive host-side validation, transport, and ticket-processing flows once characterization tests are in place.
Inputs: apps/coh/src/**, apps/cohsh/src/**, crates/cohsh-core/**, apps/host-ticket-agent/src/**, apps/gpu-bridge-host/src/**, apps/hive-gateway/src/**, tools/cohesix-py/cohesix/**, docs/ARCHITECTURE.md, docs/HOST_TOOLS.md, docs/INTERFACES.md, docs/API_GUIDELINES.md
Changes:
- apps/host-ticket-agent/src/** — factor manifest validation, ticket-processing branches, executor selection, and receipt handling into explicit invariant-bearing helpers without changing lifecycle semantics.
- apps/coh/src/** + apps/cohsh/src/** + crates/cohsh-core/** — consolidate duplicated path, grammar, request-auth, mount, and transport validation while preserving ACK/ERR/END, FUSE, REST, and TCP behavior.
- apps/gpu-bridge-host/src/** + apps/hive-gateway/src/** — tighten host-only boundary checks, error shaping, and telemetry/report formatting without changing documented host-side contracts.
- tools/cohesix-py/cohesix/** — align Python-side validation and examples with the same documented host API contracts where characterization coverage exists.
- docs/ARCHITECTURE.md + docs/HOST_TOOLS.md + docs/INTERFACES.md + docs/API_GUIDELINES.md — update any as-built explanations needed to reflect clearer code structure while preserving external contracts.
Commands:
- cargo test -p host-ticket-agent
- cargo test -p coh --features mock
- cargo test -p cohsh
- cargo test -p cohsh-core
- cargo test -p gpu-bridge-host
- cargo test -p hive-gateway
- python3 -m pytest tools/cohesix-py/tests -q
- cargo clippy --workspace --all-targets -- -D warnings
Checks:
- Host-side cleanup reduces repetition and makes invariants explicit without protocol, file-layout, receipt, or request-auth drift.
- Each host-tool refactor wave is independently reviewable and revertible, with one owner, one preserved-contract list, one characterization artifact, and one targeted test subset recorded before edits.
- Characterization tests stay unchanged and passing across refactors.
Deliverables:
- Human-readable host-side control-plane code with preserved external behavior and tighter shared validation boundaries.
Title/ID: m26c-root-task-runtime-decomposition
Goal: Decompose root-task runtime adapter code into smaller invariant-bearing modules after parity and `no_std` gates pin behavior.
Inputs: apps/root-task/src/lib.rs, apps/root-task/src/ninedoor.rs, apps/root-task/src/event/**, apps/root-task/src/console/**, apps/root-task/src/log_buffer.rs, apps/root-task/src/audit/**, apps/root-task/src/bootstrap/**, apps/root-task/src/hal/driver_task.rs, apps/root-task/tests/**, apps/pi4-driver-runtime/**, crates/pi4-driver-abi/**, configs/root_task*.toml, docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/SECURE9P.md, docs/TEST_PLAN.md, docs/audit/M26C_RUNTIME_BOUNDARY_AUDIT.md, docs/audit/M26C_NINEDOOR_PARITY_MATRIX.md
Changes:
- apps/root-task/src/ninedoor.rs + apps/root-task/src/event/** + apps/root-task/src/console/** — split parsing, dispatch, event pumping, completion formatting, and permission-denial paths into narrowly named modules without changing console grammar or Secure9P namespace semantics.
- apps/root-task/src/log_buffer.rs + selected `/proc` emitters — extract append-only, cursor, and evidence formatting helpers while preserving current output fixtures.
- apps/root-task/src/lib.rs + apps/root-task/src/bootstrap/** + apps/root-task/src/hal/driver_task.rs — clarify initialization sequencing, generated-manifest handoff boundaries, and manifest-declared isolated driver runtime descriptor ownership without moving authority out of compiler-generated artifacts.
- apps/pi4-driver-runtime/** + crates/pi4-driver-abi/** — keep ABI and runtime changes behavior-preserving, pointer-free, and aligned with generated `root_task.driver_images` records.
- apps/root-task/tests/** + apps/nine-door/tests/*.rs — preserve and extend parity fixtures before and after the decomposition.
- docs/ARCHITECTURE.md + docs/INTERFACES.md + docs/SECURE9P.md + docs/TEST_PLAN.md — update as-built module ownership only when public contracts or evidence paths become clearer.
Commands:
- cargo test -p nine-door --test integration
- cargo test -p root-task --tests
- cargo test -p root-task --lib
- cargo test -p pi4-driver-abi
- cargo test -p pi4-driver-runtime
- cargo check -p root-task --target aarch64-unknown-none --no-default-features --features "cohesix-dev"
- cargo check -p root-task --target aarch64-unknown-none --no-default-features --features "kernel bootstrap-trace serial-console net-console"
- cargo check -p pi4-driver-runtime --target aarch64-unknown-none
- cargo clippy --workspace --all-targets -- -D warnings
Checks:
- Root-task decomposition preserves ACK/ERR/END grammar, namespace layout, `/proc` output shapes, event ordering, append-only behavior, and generated-manifest authority.
- Linked driver-runtime descriptor handling, fixed-ring command/completion ABI, and acceptance-eligibility classification remain unchanged unless a reopened 26a/26b acceptance task changes them with hardware evidence.
- VM-target builds remain `no_std` across QEMU and Pi 4 closure profiles.
- Each root-task decomposition wave has a baseline-linked preserved-contract list and can be reverted without undoing unrelated worker/runtime behavior.
- No new `unsafe`, `unwrap`, `expect`, or `panic!` appears in non-test root-task code without an approved exception.
Deliverables:
- Smaller root-task runtime modules with preserved operator-visible behavior and explicit boundary evidence.
Title/ID: m26c-hal-network-and-local-seat-decomposition
Goal: Refactor Pi 4 HAL-facing network, Wi-Fi, and local-seat code into clearer bounded units and narrow SDIO/USB platform seams without changing boot policy, transcripts, or device authority.
Inputs: apps/root-task/src/hal/**, apps/root-task/src/net/**, apps/root-task/src/drivers/**, apps/root-task/src/local_seat.rs, apps/root-task/src/generated/**, apps/pi4-driver-runtime/**, crates/pi4-driver-abi/**, configs/root_task_pi4_uboot_aarch64.toml, docs/HARDWARE_BRINGUP.md, docs/NETWORK_CONFIG.md, docs/BOOT_REFERENCE.md, docs/TEST_PLAN.md
Changes:
- apps/root-task/src/net/** — separate policy parsing, DHCP state, static IPv4 validation, active/standby interface selection, and evidence formatting while preserving manifest and DTB override semantics.
- apps/root-task/src/hal/** + apps/root-task/src/drivers/** + apps/pi4-driver-runtime/** + crates/pi4-driver-abi/** — keep all device access behind HAL traits, split device-state and firmware/handoff bookkeeping from transcript emission, preserve isolated runtime command ownership, extract current-behavior-only SDIO host and USB platform/DMA seams after characterization tests exist, and remove duplicated bounds checks under the same evidence gate.
- apps/root-task/src/local_seat.rs — isolate local-seat input/display policy from boot evidence and network policy handoff code without changing first-boot operator behavior.
- docs/HARDWARE_BRINGUP.md + docs/NETWORK_CONFIG.md + docs/BOOT_REFERENCE.md + docs/TEST_PLAN.md — update as-built explanations and evidence commands for any clearer module boundaries.
Commands:
- cargo test -p root-task --tests
- cargo test -p root-task --lib
- cargo test -p pi4-driver-abi
- cargo test -p pi4-driver-runtime
- cargo check -p root-task --target aarch64-unknown-none --no-default-features --features "kernel bootstrap-trace serial-console net-console"
- cargo check -p pi4-driver-runtime --target aarch64-unknown-none
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26c-pi4
Checks:
- HAL access remains centralized behind HAL traits; no direct MMIO, physical address, DMA publication, IRQ binding, or firmware-service shortcuts are introduced outside HAL.
- New SDIO/USB seams are extraction-only, have before/after characterization evidence, and do not add new hardware support or generic future-driver behavior.
- Each HAL/network/local-seat wave is isolated to one preserved behavior surface and records the exact tests plus Pi 4/QEMU evidence needed to prove no transcript or authority drift.
- Isolated runtime acceptance eligibility and the separate fresh-Pi board-proof boundary remain explicit until owner-state proof and fresh Pi hardware evidence close them.
- Boot transcripts, `netstats`, `netstatus`, DHCP/static policy evidence, Wi-Fi fallback semantics, and no-NIC compatibility remain unchanged unless a separately approved breaking-change path is followed.
- Pi 4 staged evidence proves the refactor did not regress local-seat, network-policy, or U-Boot handoff behavior.
Deliverables:
- Clearer Pi 4 HAL/network/local-seat modules with preserved hardware bring-up semantics and explicit SDIO/USB platform seams ready for later milestone evaluation.
Title/ID: m26c-full-test-plan-qemu-and-pi4
Goal: Make full staged Test Plan PASS on both QEMU and Pi 4 the explicit closure gate for 26c.
Inputs: docs/TEST_PLAN.md, docs/HARDWARE_BRINGUP.md, docs/audit/M26C_TARGET_RUNNER_BASELINE.md, docs/audit/M26C_POST_BEHAVIOR_BASELINE.md, scripts/ci/test_plan_run.sh, scripts/ci/test_plan_stage_*.sh, scripts/ci/check_test_plan.sh, scripts/pi4-image-build.sh, scripts/uboot/qemu-uboot-smoke.sh
Changes:
- docs/TEST_PLAN.md — verify QEMU and Pi 4 execution matrices, evidence paths, PASS criteria, and target-qualified artifact requirements still match the early runner baseline and post-behavior baseline.
- docs/HARDWARE_BRINGUP.md — verify Pi 4 hardware setup, log capture, and operator prerequisites remain sufficient to run the full Test Plan.
- scripts/ci/test_plan_run.sh + scripts/ci/test_plan_stage_*.sh — use the already implemented `--target qemu|pi4` contract to archive final target-qualified evidence without pretending QEMU and Pi 4 evidence are identical.
- scripts/ci/check_test_plan.sh — enforce final alignment between target-aware docs, stage scripts, baseline artifacts, and authoritative commands.
- scripts/pi4-image-build.sh — produce deterministic artifacts consumed by Pi 4 staged test-plan runs.
Commands:
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26c-qemu
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26c-pi4
Checks:
- The staged runner produces `stage_01.done` through `stage_05.done` for both QEMU and Pi 4 state dirs.
- Neither state dir contains `*.incomplete` markers.
- Stage 05 verifies the required target-qualified artifacts exist before writing `stage_05.done`.
- Pi 4 evidence includes serial logs, network or console validation, and due-diligence outputs matching the documented PASS contract.
Deliverables:
- Full Test Plan PASS on QEMU and Pi 4 as the hard milestone exit criterion, with archived evidence for both targets.
Milestone 26d — seL4 16 Baseline Refresh + Reference/Performance Realignment
Status: Complete.
As-built scope: The milestone refreshed the external kernel baseline and references to seL4 16.0.0, made QEMU kernel/profile provenance reproducible, enforced fail-closed executable mappings, corrected overstated Worker execution claims, and revalidated the driver-task and benchmark baseline. It also delivered the named SMP command-routing and CYW43 ownership repairs without changing public control authority or introducing a component framework.
Qualification limits: Selected kernel headers, generated profiles and exact target evidence determine the supported configuration. Host capability checks do not establish Wi-Fi or Pi acceptance. The completed 26b contract supersedes older CYW43 scheduling proposals: current-generation post-Gate-8 op7 transactions share one finite cadence; provenance controls capacity and urgent ordering; completion is durable before wake and rechecked before sleep; software-only drains stop at eight terminals per Network wake. Ordinary traffic has no deadline-driven scheduler, hintless watchdog, fallback or second owner. General executable Worker isolation and SMP+MCS qualification belong to 26e.
Evidence: Baseline decisions and implementation records retain the prior comparator identities and superseded proposals. The task criteria below and the selected as-built contracts define the accepted result.
Non-negotiable constraints:
- No further system-model change beyond the reopened 26a/26b driver-task baseline, except the explicitly named W^X enforcement, canonical profile, generated/docs-as-built Worker truth repairs, and
m26d-smp-command-post-cutover-usabilitycompatibility correction in this milestone. Cohesix remains an upstream seL4, pure-Rust root-task authority system with hardware driver tasks; Microkit, CAmkES, and capDL loader adoption are explicitly out of scope for 26d. - CAmkES 3.13.0 is recorded only as the upstream component-framework release paired with seL4 16.0.0. A separate host smoke build may test that upstream pairing, but CAmkES, capDL component generation, and their Haskell/Python dependency closure must not enter Cohesix profiles, target artifacts, or TCB.
- No new operator-visible protocol, namespace, ACK/ERR/END, telemetry, manifest, or release-behavior changes are permitted under a kernel-refresh label except the named
m26d-smp-command-post-cutover-usabilitycorrection, which changes only command routing and preserves the existing activity and raw-dump payloads. - Concurrent CYW43/SDIO reliability, exact-image identity, operator-liveness, and Pi evidence files remain owned by the accepted 26b/26d closure record. Capability work must not rewrite driver timing/state-machine logic, evidence classification, image packaging, or hardware claims, and offline capability PASS results must not be counted as Wi-Fi or exact-image proof.
rust-sel4adoption is out of scope. Cohesix may audit upstream Rust support for compatibility reference, but 26d must preserve the current Cohesix-ownedsel4-sys/sel4-runtime/ root-task bootstrap stack unless a separate milestone authorizes replacement.- Canonical kernel/manual provenance must be updated with specific versions and, where available, upstream commit identifiers for QEMU, SMP, and Pi 4/U-Boot build flows.
- Canonical fresh seL4 profile builds must be configured from the pinned official seL4 16.0.0 manifest through a source-controlled Cohesix profile wrapper. Hand-edited CMake caches, stripped generated settings, or unauthenticated copied external build trees cannot establish production, diagnostic, or proof-profile closure. The tracked
seL4/build_UBOOTtree is the narrow Pi image exception: its completed causal stamp and every relocated artifact identity must validate before it can serve as immutable diagnostic composition input, and it still cannot establish fresh source-build, release, or hardware proof. - Older manual/reference mentions are known 26d blockers, not acceptable post-26d residue. Later milestones must not cite seL4 16 alignment until
m26d-kernel-provenance-refreshupdates or explicitly retires those references. - Any seL4 build configuration that still depends on legacy
KernelDomainSchedule/domain_schedule.chandling must be either removed when semantically unused or migrated/documented consistently with seL4 16 behavior; one-domain configurations must not retain hidden schedule-file dependencies. - Generated Worker roles may be described as implemented, capability-backed, notification-backed, or live only when the selected target actually creates the declared TCB, CSpace, VSpace, IPC buffer, stack, endpoint badge, lifecycle notifications, and fault/revocation path. Model-only or in-process Worker behavior must be emitted and documented as such.
- MCS activation and root-service decomposition remain explicit decisions, not implicit benefits of the version refresh. Milestone 26d keeps the accepted non-MCS scheduling model and current root-task service boundary. Pending Milestone 26e owns both the ordered root-service/Worker split and the SMP+MCS ABI, generated policy, and exact-target acceptance after 26d closes.
- The seL4 16 refresh must preserve the Pi 4 hardware-counter contract used by isolated runtime performance proof:
release-pi4/timers-arch-counterbuilds expose only the read-only EL0 virtual counter (KernelArmExportVCNTUser/CONFIG_EXPORT_VCNT_USER), keep physical counter and EL0 timer-control exports disabled, and derive elapsed-time proof from refreshedTIMER_CLOCK_HZ=54000000generated headers. Kernel refresh work must not reclassify dummy-timer or physical-counter captures as valid latency evidence. - Performance tuning is permitted in 26d only when tied to a measured same-harness regression, regression-risk, or drift exposed by the seL4 16 refresh. Allowed tuning includes bounded scheduler/budget constants, driver-runtime service-turn cadence, cache-maintenance batching thresholds, TCP/REST gateway timeout plumbing, harness provenance/reporting fixes, and comparator hygiene. Tuning must preserve Secure9P semantics, ACK/ERR/END grammar, manifest authority, HAL-only physical-device authority, root/driver-task ownership boundaries, no-retry benchmark accounting, and the documented Pi 4 wired/GENET versus Wi-Fi proof split.
- 26d tuning must not become service-bucket/core-local redesign, new protocol work, new namespace or telemetry grammar, relaxed error budgets, retry masking, root-owned physical-driver shortcuts, larger unbounded queues, or a reclassification of Wi-Fi stress diagnostics as production parity. Those remain outside accepted 26b and belong only to 38 (
m29a-core-local-event-pumps) or later explicitly scoped work. - QEMU and Pi 4 target-qualified evidence must be regenerated on the refreshed kernel baseline before 26d can close.
Prerequisite
- The original Milestone 26c runtime/refactor closure is accepted (target-qualified test-plan runner, docs-as-built audit, refactor map, risk-ratchet baseline, and no-std boundary evidence available). Its later documentation-only remediation may run concurrently and does not invalidate those accepted prerequisite artifacts.
- At the accepted 26d closure, Milestones 26a and 26b were complete where their driver-task and benchmark artifacts were inputs to the kernel refresh. Milestone 26b was later reopened for the bounded evidence defects recorded above and returned to Complete on exact image
7a10b8fd6acc; no isolated runtime performance assumption may be rewritten under the kernel-refresh label. - The root-service/Worker task-isolation claims in Milestone 25 and Worker capability/notification claims in Milestone 26c are reopened to restore as-built truth in the first 26d phase. Root-service decomposition and actual general Worker TCB launch are routed to pending Milestone 26e after their compiler, bootstrap, event, image, and operator surfaces are available; neither can be inferred from driver-runtime TCB evidence or model tests.
Goal
Upgrade Cohesix’s external seL4 baseline and normative references to seL4 16.0.0 while preserving root-task authority plus the accepted 26a/26b hardware driver-task model, prove zero operator-visible drift across QEMU and Pi 4, and preserve or recover the accepted 26b REST/driver-runtime benchmark envelope when the refreshed kernel baseline exposes a bounded performance regression.
Deliverables
- Kernel baseline refresh
- Refresh external seL4 build inputs used by Cohesix bring-up, CI, and Pi 4 image flows to seL4 16.0.0.
- Record the exact upstream seL4 version/commit accepted for Cohesix in canonical docs and test evidence.
- Record refreshed Pi 4 counter-export evidence for
KernelArmExportVCNTUser/CONFIG_EXPORT_VCNT_USER, forbidden physical-counter/timer-control exports, andTIMER_CLOCK_HZ.
- Reference-manual and docs realignment
- Update
docs/BUILD_PLAN.md,docs/TOOLCHAIN_MAC_ARM64.md,README.md, and other canonical docs that currently describe the normative seL4 manual/baseline so they align with seL4 16.0.0 as built and link the official seL4 Reference Manual v16.0.0 PDF (https://sel4.systems/Info/Docs/seL4-manual-16.0.0.pdf). - Refresh the carried seL4 manual mirror under
seL4/if the repo continues to store it as a tracked reference artifact. - Record any seL4 16 changes that are intentionally irrelevant to Cohesix today, especially domain-schedule features tied to Microkit/CAmkES/capDL workflows.
- Update
- Direct-API compatibility audit and fixes
- Audit
crates/sel4-sys,crates/sel4-runtime,crates/pi4-driver-abi, profile-selectedapps/pi4-driver-runtimeimages, generatedroot_task.driver_imagesdescriptors, and root-task bootstrap code against seL4 16 headers and generated metadata. - Preserve Cohesix’s explicit TLS and IPC-buffer installation path unless a compatibility fix requires adjustment.
- Keep SMP affinity, boot-info handling, CSpace assumptions, and debug-syscall guards aligned with seL4 16 generated headers for both single-core and SMP builds.
- Keep root-task and linked-driver-runtime timer build guards aligned with seL4 16 generated
TIMER_CLOCK_HZand VCNT export truth; compatibility fixes may not introduceCNTPCT_EL0, EL0 timer-control register use, or raw CPU-speed spin loops for elapsed time.
- Audit
- Domain-schedule debt removal
- Audit build caches and Pi 4/U-Boot kernel configuration for stale
KernelDomainSchedule/domain_schedule.cassumptions. - For configurations with
KernelNumDomains=1, remove or document any stale schedule-file dependency so Cohesix does not inheritsel4testdomain-schedule defaults as an accidental build requirement. - If any Cohesix-owned configuration genuinely uses domains later, migrate that path to seL4 16 runtime/domain-schedule semantics in a scoped follow-on task before enabling it.
- Audit build caches and Pi 4/U-Boot kernel configuration for stale
- Isolated-runtime W^X closure
- Reject malformed, unknown-flag, write-plus-execute, and effective page-level W+X ELF load plans before allocating child authority.
- Map only validated read-only executable image pages with execute permission; map writable and read-only data, holes, stack, IPC buffer, rings, shared payloads, DMA, MMIO, and framebuffers execute-never in both root aliases and child VSpaces.
- Preserve device/cache attributes while adding execute-never and retain the reviewed read-only executable trampoline exception.
- Canonical profile intent and validation
- Define pinned production, diagnostic, and proof profile contracts from the official seL4 16.0.0 manifest, including allowed debug/benchmark features and claim eligibility.
- Make QEMU
aarch64/virtGICv3 and one-domain/no-schedule-file intent explicit, then validate source provenance, cache settings, generated headers, DTB/launcher inputs, and forbidden settings as one contract. - Make the validated
qemu_smp_productiontree the default for QEMU build, release, regression, staged-test, and newcomer runbooks; explicit legacy trees remain diagnostic and claim-ineligible unless a named contract passes. - Treat proof-profile eligibility as a fail-closed evidence classification; a diagnostic build may exercise behavior but may not support production or performance claims.
- Worker execution truth repair
- Correct manifest IR, generated outputs, tests, and canonical docs so model-only Worker roles are not emitted as target-implemented, capability-backed, notification-backed, or live.
- Reject
implemented=trueat manifest validation until compiler IR contains and validates the selected image, TCB, CSpace, VSpace, IPC buffer, stack, fault, and revocation contract needed to make that claim meaningful. - Preserve the existing host/session ticket and namespace behavior while separating it from seL4 target-execution claims.
- Keep actual general Worker TCB creation, badged IPC, lifecycle notifications, fault suspension/revocation, and QEMU/Pi execution evidence as an explicit reopened phase rather than borrowing isolated driver-runtime proof.
- Capability, MCS, and root-TCB decision evidence
- Publish the seL4 16 capability-use matrix with implemented, partial/model-only, intentionally unused, and blocker classifications.
- Record why non-MCS remains the accepted 26d baseline, compare classic SMP, single-core MCS, and SMP+MCS, identify MCS as the preferred Cohesix temporal architecture, and route staged implementation/admission to the exact 26e tasks without enabling it in 26d.
- Record the current root-owned parsing/network/supervision surface and route the security-first split order to exact pending Milestone 26e tasks without claiming that decomposition has occurred.
- Regression and evidence refresh
- Re-run generated-artifact guards, root-task checks/tests, QEMU bring-up, Pi 4 image build, and the full target-qualified Test Plan on the seL4 16 baseline.
- Publish refreshed audit artifacts proving that operator-visible semantics remain unchanged, that the VM build remains
no_std, and that Pi 4 latency/performance proof still uses the virtual-counter backend rather than dummy timers or physical-counter exports.
- Benchmark revalidation and bounded tuning
- Archive a before/after benchmark ledger with five explicit lanes: historical top benchmark, accepted 26b baseline, accepted seL4 15 comparator, first seL4 16 baseline before tuning, and final seL4 16 evidence after any tuning.
- Re-run the REST performance harness in the same-harness QEMU/Pi shape used by 26b, keeping raw direct
cohsh/TCP proof, REST gateway overhead, QEMU semantic/capacity reference, wired/GENET production parity, and Wi-Fi research/diagnostic evidence separate. - Permit only bounded tuning that preserves existing authority and protocol semantics; every performance fix must identify the moved layer as kernel/generated-artifact drift, root-task scheduling cadence, isolated driver-runtime service cadence, gateway/harness behavior, physical-target variance, or pre-existing 26b debt.
- Update
docs/BENCHMARKS.mdonly for refreshed artifact indexes, verdict changes, or explicit non-blocking debt. Do not erase historical-best evidence or convert uncommitted local diagnostics into canonical proof without archived artifacts.
Commands
cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsonscripts/check-generated.shcargo fmt --all -- --checkcargo clippy --workspace --all-targets -- -D warningscargo check --workspacecargo test --workspacecargo test -p pi4-driver-abicargo test -p pi4-driver-runtimecargo check -p root-task --target aarch64-unknown-none --no-default-features --features "cohesix-dev"cargo check -p root-task --target aarch64-unknown-none --no-default-features --features "kernel bootstrap-trace serial-console net-console"cargo check -p pi4-driver-runtime --target aarch64-unknown-noneout/toolchain/sel4-profile-venv/bin/python -m pytest -q tests/test_sel4_profile.pyout/toolchain/sel4-profile-venv/bin/python scripts/sel4_profile.py validate --all --require-source --require-artifacts --evidence out/audit/m26d-profile-v2-all.jsoncargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::tests::runtime_SEL4_BUILD_DIR="$PWD/seL4/build_UBOOT" cargo check -p root-task --target aarch64-unknown-none --no-default-features --features release-pi4scripts/cohesix-build-run.sh --sel4-build out/sel4/profile-v2/qemu-smp-production --no-run --cargo-target aarch64-unknown-none --profile release --root-task-features cohesix-devscripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml --venv .venvpython3 -m pytest -q tests/test_rest_perf_harness.py tests/test_pi4_compare_driver_models.pypython3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --log-dir out/bench --log-prefix m26d-qemu-sel4-16-initialpython3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --no-qemu --no-gateway --rest-url http://<pi4-gateway-host>:<port> --log-dir out/bench --log-prefix m26d-pi4-sel4-16-initialpython3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --log-dir out/bench --log-prefix m26d-qemu-sel4-16-finalpython3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --no-qemu --no-gateway --rest-url http://<pi4-gateway-host>:<port> --log-dir out/bench --log-prefix m26d-pi4-sel4-16-finalscripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26d-qemu-sel4-16-gap-auditscripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26d-pi4
Checks (DoD)
- Canonical docs link the official seL4 Reference Manual v16.0.0 PDF and explicitly align to the accepted seL4 16.0.0 baseline, remaining consistent with the refreshed as-built evidence.
crates/sel4-sys,crates/sel4-runtime,crates/pi4-driver-abi,apps/pi4-driver-runtime, generated driver-image descriptors, driver-runtime CPIO packaging, and root-task bootstrap code build cleanly against seL4 16 generated headers/artifacts for the QEMU baseline, SMP baseline, and Pi 4 U-Boot baseline used by Cohesix.- QEMU and Pi 4 target-qualified Test Plan runs pass on the refreshed kernel baseline with no
*.incompletemarkers and no undocumented operator-visible output drift. - Secure9P bounds, console grammar, manifest outputs, release semantics, and host/VM runtime boundaries remain unchanged unless separately documented as defects fixed in the same change.
- Build artifacts and documentation no longer rely on an accidental
sel4test-provideddomain_schedule.cdependency for one-domain Cohesix configurations; any remaining dependency is explicit, justified, and documented. - Canonical QEMU configuration is reproducible from the pinned official seL4 16.0.0 manifest, official Arm GNU compiler archive, exact hash-locked Python closure, and DENX mkimage source provenance; selects GICv3 for
aarch64/virt; omits the legacy domain-schedule input; and has matching source, cache, generated-header, parsed-DTB, launcher, strict executable-ELF, and causal build-stamp evidence. The aggregate closure gate requires all five freshout/sel4/profile-v2/*source and artifact sets by default; configuration-only relaxation is explicit and claim-ineligible. Production, diagnostic, and proof profile contracts reject unknown evidence classes, class/eligibility mismatches, stale outputs, forbidden settings, shipping-artifact RWX, malformed/non-executable ELF inputs, and claim-ineligible settings rather than silently normalizing them, while upstream seL4Test RWX exceptions remain machine-recorded and non-shipping. Active QEMU build, release, regression, staged-test, and runbook defaults consumeout/sel4/profile-v2/qemu-smp-productionand validate it before runtime/release claims; explicit legacy trees remain diagnostic unless a named contract passes. - Every isolated child mapping is W^X by construction: only validated read-only executable image pages and the reviewed trampoline are executable; writable/data/hole/stack/IPC/ring/shared/DMA/MMIO/framebuffer mappings are execute-never; malformed, unknown, RWX, and page-colliding ELF segments are rejected before launch.
- Generated outputs and canonical docs describe general Workers as model-only until target TCB/CSpace/VSpace/IPC/stack, badged endpoint, lifecycle notification, and fault/revocation evidence exists. Isolated driver-runtime execution and host/session ticket behavior do not satisfy that gate.
- The accepted 26d scheduler remains non-MCS and the accepted service boundary remains root-owned exactly as recorded in the decision audits; neither is presented as an implemented isolation improvement.
- Pi 4 refreshed evidence reports
TIMER_BACKEND=arch-counter,TIMER_CLOCK_HZ=54000000,TIMER_EL0_COUNTER=vct, andDUMMY_TIMER_SEEN=no; any missing/mismatched counter export leaves isolated runtime latency proof red until fixed or explicitly scoped back to reopened 26a/26b acceptance. - 26d benchmark evidence includes the historical-best, accepted 26b, first seL4 16, and final seL4 16 lanes; any tuning is explained by layer, bounded by existing authority/protocol rules, and rechecked with the REST performance harness without retry masking or relaxed error budgets.
- If final seL4 16 benchmark evidence remains below the accepted 26b envelope, the closure record classifies the gap as blocking regression, physical-target variance with evidence, pre-existing 26b debt, or explicitly deferred later-milestone work. Deferred work cannot be counted as 26d closure evidence for downstream milestones.
- The carried seL4 manual/reference artifacts, if tracked in-repo, match the accepted kernel baseline or are explicitly relinked to the authoritative upstream 16.0.0 source.
Compiler / docsystem touchpoints
coh-rtcoutputs, docs snippets, and manifest fingerprints remain authoritative; 26d may update generators or schemas only when required by the seL4 16 baseline refresh, and any such change must be reflected in the same evidence set.- Pi 4 manifest-declared isolated driver runtime ABI/descriptors/images remain authoritative for driver-task bootstrap evidence during the kernel refresh; 26d may adapt them only for seL4 16 compatibility and must not reclassify runtime-spec acceptance or board-proof boundaries without reopened 26a/26b hardware acceptance evidence.
- Root-task and linked-driver-runtime hardware-counter guards remain authoritative for performance proof during the kernel refresh. Generated seL4 headers and CMake/cache config must agree before
timers-arch-counterevidence can satisfy 26d closure. - REST harness output, benchmark provenance fields, and
docs/BENCHMARKS.mdartifact indexes remain the source of truth for same-harness performance claims during the refresh. Any harness change made in 26d must improve provenance, strictness, or failure classification without changing the workload contract used for comparison. docs/TEST_PLAN.md,scripts/ci/test_plan_run.sh, and target-qualified state-dir evidence remain the source of truth for QEMU/Pi 4 pass semantics during the kernel refresh.configs/sel4/profiles.toml, the Cohesix seL4 profile wrapper, and its validator are the source of truth for profile intent and claim eligibility; build-directory caches are evidence to validate, not configuration authority.- Worker manifest IR and regenerated artifacts must disable executable-role capability/notification claims together. Prose, model tests, or host-side ticket flows may not override generated target truth.
Atomic tasks
Title/ID: m26d-kernel-provenance-refresh
Goal: Refresh Cohesix seL4 baseline inputs and record accepted seL4 16.0.0 provenance.
Inputs: external seL4 source/build trees, seL4 16.0.0 release notes, official seL4 Reference Manual v16.0.0 PDF (`https://sel4.systems/Info/Docs/seL4-manual-16.0.0.pdf`), docs/TOOLCHAIN_MAC_ARM64.md, README.md.
Changes:
- docs/TOOLCHAIN_MAC_ARM64.md — record the accepted seL4 16.0.0 baseline and external-build expectations.
- README.md — update high-level kernel/manual baseline references if they mention stale versions or assumptions.
- seL4/ — refresh tracked manual/reference artifacts only if the repo continues carrying them as canonical mirrors.
Commands: cargo check --workspace
Checks: canonical docs and carried references identify the accepted seL4 16.0.0 baseline with no stale older-manual pin left in normative guidance.
Deliverables: updated docs/reference provenance and a checked-in note of the accepted upstream version/commit.
Title/ID: m26d-sel4-api-compat-audit
Goal: Bring Cohesix-owned seL4 bindings/runtime/bootstrap code into clean alignment with seL4 16 generated artifacts.
Inputs: crates/sel4-sys, crates/sel4-runtime, crates/pi4-driver-abi, apps/pi4-driver-runtime, apps/root-task, configs/root_task*.toml, out/sel4/profile-v2/qemu-smp-production, out/sel4/profile-v2/qemu-smp-diagnostic, out/sel4/profile-v2/pi4-production, out/sel4/profile-v2/pi4-diagnostic, and the repo-managed `seL4/{build,SMP_build,build_UBOOT}` v16 reference mirrors.
Changes:
- crates/sel4-sys — compatibility fixes required by seL4 16 headers/generated metadata.
- crates/sel4-runtime — compatibility fixes required by seL4 16 root-task startup behavior.
- crates/pi4-driver-abi + apps/pi4-driver-runtime — compatibility fixes required by seL4 16 runtime-init descriptor layout, pointer-free ring transport, or target build rules.
- apps/root-task — bootstrap and generated driver-image handoff adjustments only where required by seL4 16 semantics.
Commands:
- cargo check -p root-task --target aarch64-unknown-none --no-default-features --features "cohesix-dev"
- cargo test -p pi4-driver-abi
- cargo test -p pi4-driver-runtime
- cargo check -p pi4-driver-runtime --target aarch64-unknown-none
Checks: direct-seL4 Cohesix builds compile on all supported kernel profiles, and manifest-declared isolated driver runtime ABI/build evidence stays green, without changing system model or operator-visible semantics.
Deliverables: passing workspace/build-target checks and refreshed low-level compatibility evidence.
Title/ID: m26d-pi4-counter-contract-refresh
Goal: Reprove the Pi 4 virtual-counter timer contract on the seL4 16 baseline before accepting isolated runtime latency or performance evidence.
Inputs: fresh-source Pi profile audit outputs, the repo-managed immutable `seL4/build_UBOOT` v16 diagnostic artifact input, apps/root-task/build.rs, apps/root-task/src/arch/aarch64/timer.rs, apps/pi4-driver-runtime/build.rs, apps/pi4-driver-runtime/src/lib.rs, scripts/pi4-image-build.sh, scripts/pi4_gate_proof.sh, scripts/pi4_trace_normalize.py, docs/HARDWARE_BRINGUP.md, docs/TEST_PLAN.md.
Changes:
- scripts/pi4-image-build.sh — keep seL4 16 Pi 4 staging blocked unless VCNT export is enabled, physical counter/timer-control exports are disabled, and generated `TIMER_CLOCK_HZ` matches the accepted Pi profile.
- apps/root-task/build.rs + apps/root-task/src/arch/aarch64/timer.rs — preserve root-task build/runtime checks that use `CNTVCT_EL0` only under the `timers-arch-counter` profile and scale elapsed-time proof from generated frequency.
- apps/pi4-driver-runtime/build.rs + apps/pi4-driver-runtime/src/lib.rs — preserve isolated runtime build/runtime checks and `RuntimeDeadline` conversion from legacy retry counts to counter-backed deadlines.
- scripts/pi4_gate_proof.sh + scripts/pi4_trace_normalize.py + docs/HARDWARE_BRINGUP.md + docs/TEST_PLAN.md — ensure refreshed Pi 4 proof gates require `TIMER_BACKEND=arch-counter`, `TIMER_CLOCK_HZ=54000000`, `TIMER_EL0_COUNTER=vct`, and `DUMMY_TIMER_SEEN=no` before latency proof is accepted.
Commands:
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml --venv .venv
- cargo check -p root-task --target aarch64-unknown-none --no-default-features --features "kernel bootstrap-trace serial-console net-console"
- cargo check -p pi4-driver-runtime --target aarch64-unknown-none
- scripts/pi4_gate_proof.sh --require-driver-task-proof
Checks:
- Refreshed seL4 16 Pi 4 generated headers and cache expose only the accepted virtual-counter path for EL0 timing.
- Root-task and isolated runtime builds fail on missing VCNT export, nonzero physical-counter/timer-control export, or missing/nonzero-invalid `TIMER_CLOCK_HZ`.
- Runtime latency telemetry and proof normalizer output reject dummy-timer captures, stale logs, physical-counter exports, and missing timer frequency as performance evidence.
Deliverables:
- Checked-in 26d evidence tying seL4 16 provenance, Pi 4 counter configuration, isolated runtime deadline behavior, and target-qualified performance proof into one refreshed contract.
Title/ID: m26d-benchmark-revalidation-and-tuning
Goal: Revalidate and, where needed, recover the accepted 26b REST/driver-runtime benchmark envelope on the seL4 16 baseline.
Inputs: scripts/rest_perf_harness.py, tests/test_rest_perf_harness.py, tests/test_pi4_compare_driver_models.py, tools/host-bootpd/{start-en8-bootpd.zsh,install-root-bootpd.zsh,com.lukasbower.cohesix.en8-bootpd.plist,README.md}, tests/test_host_bootpd_supervisor.py, apps/root-task/src/{event/mod.rs,drivers/driver_task_net.rs,hal/driver_task.rs}, apps/pi4-driver-runtime/src/lib.rs, docs/{BENCHMARKS.md,DRIVERS.md,HARDWARE_BRINGUP.md,TEST_PLAN.md}, out/bench/m26b-* artifacts, refreshed seL4 16 QEMU/Pi build artifacts, fresh Pi serial/pcap proof for the selected transport.
Changes:
- docs/BENCHMARKS.md — record refreshed artifact indexes, before/after verdicts, and any explicitly classified non-blocking debt.
- scripts/rest_perf_harness.py + tests/test_rest_perf_harness.py — provenance/reporting or strictness fixes only when needed to compare the seL4 16 run against the accepted 26b workload without changing the workload contract.
- tools/host-bootpd/{start-en8-bootpd.zsh,install-root-bootpd.zsh,com.lukasbower.cohesix.en8-bootpd.plist,README.md} + tests/test_host_bootpd_supervisor.py — keep the wired/GENET direct-link DHCP control deterministic when disposable runtime evidence is cleaned while the host supervisor remains alive; bind root LaunchDaemon state to `/Users/lukasbower/cohesix/host-bootpd`, migrate a sole legacy `out/host-bootpd` tree, and reject ambiguous dual runtime trees without writing new runtime state inside the repository.
- apps/root-task/src/**, apps/pi4-driver-runtime/src/**, crates/pi4-driver-abi/src/**, or apps/hive-gateway/src/** — bounded tuning only where same-harness evidence points to a moved layer caused or exposed by the seL4 16 refresh. For CYW43, preserve one HAL/runtime issuer and the three exact authorities required by accepted Milestone 26b task `m26b-wifi-sdio-notification-dpc-closure`: persistent op11, the separate finite urgent-op7 lease, and the post-release event-sequence DPC lease. Ordinary non-op11 foreground commands alone retain recurrent exact grants. SDIO owns and joins IRQ158 and DMA4 IRQ116 into one immutable request terminal. Root admits at most one CYW43 parent per outer turn; an exact op11 commits and signals once, and its stable `Waiting` state masks only runtime-descriptor, logical-owner, and HAL-lease self-demand. Persistent op11, urgent op7, and DPC event service route from current durable conditions rather than snapshot novelty: deterministic private phases continue even on equal snapshots, while exact child, runtime-owned credit, queue, and peer waits block immediately even when newly observed. SDIO alone takes one live joined-controller sample after a changed steady cursor before blocking. Every helper remains bounded and each immutable hardware request issues at most once. Preserve commit-before-signal, condition-before-sleep, the post-f4 immutable descriptor requirement, issued-unknown reaping, and the exact recovery lane. Decouple smoltcp admission from the sole physical owner with one CYW43-only bounded aggregate of 16 TX frames and one committed RX batch parent carrying up to eight frames. Notifications only prompt a durable-state recheck; they carry no work history or authority. A sequence-last SDIO command always reaches matching owner dispatch or a typed zero-I/O missing/competing-seal terminal; it is never discarded as no intake. Ordinary TxTokens reserve 15 aggregate slots, copied RX reserves the final paired slot before dequeue, consumption remains queue-only, and EventPump is the sole production TX coordinator. ARP, EAPOL, DHCP, TCP SYN/FIN/RST, and payload-free TCP control preempt other payload-bearing TCP and bulk while preserving FIFO order within each class. Preserve any exact retained foreign HAL descriptor, including the one RX batch parent, before op7 admission. Once the lane is free, advance one active op7 or promote and advance one eligible FIFO head before copied-RX service so replenished RX cannot starve control TX. Copied RX precedes the coordinator's physical op only while no op7 is legally runnable; otherwise it remains preserved for the following smoltcp poll. When full, promotion removes one eligible head and restores a paired slot before at most one physical advance. A terminal never promotes a successor; that frame remains queued for a later coordinator turn. Neither `Device::receive` nor reservation failure services TX. The runtime is the sole SDPCM flow-control owner: it admits each exact op7 only while `sdpcm_seq` is within the dongle-advertised `tx_max` window and retains the same op7 in `WAIT_CREDIT` otherwise. A joined Function-2 terminal releases the root frame immediately and is never converted into a second root wait for a future RX credit observation. A stable committed terminal wins before lifetime policy; a terminal-absent `Waiting` op7 remains retained only while its exact generation, pair epoch, and physical-lifetime epoch are current, and an invalidated lifetime enters the sole pair-recovery lane without replay. An issued or otherwise ambiguous active op7 deadline remains fail-closed. Purge only never-issued queue entries at generation/reset boundaries, preserve active issued-unknown poisoning, and leave GENET unchanged. RX deadlines contain exact faults only and never create source probes, rescue transactions, or another physical action.
- docs/DRIVERS.md + docs/HARDWARE_BRINGUP.md + docs/TEST_PLAN.md — record the measured transport-specific baseline, the as-built bounded cadence correction, and a fresh-hardware acceptance target without promoting source or model evidence into Pi performance proof.
Commands:
- python3 -m pytest -q tests/test_rest_perf_harness.py tests/test_pi4_compare_driver_models.py
- python3 -m pytest -q tests/test_host_bootpd_supervisor.py
- python3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --log-dir out/bench --log-prefix m26d-qemu-sel4-16-initial
- python3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --no-qemu --no-gateway --rest-url http://<pi4-gateway-host>:<port> --log-dir out/bench --log-prefix m26d-pi4-sel4-16-initial
- python3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --log-dir out/bench --log-prefix m26d-qemu-sel4-16-final
- python3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --no-qemu --no-gateway --rest-url http://<pi4-gateway-host>:<port> --log-dir out/bench --log-prefix m26d-pi4-sel4-16-final
Checks:
- Historical top, accepted 26b, first seL4 16, and final seL4 16 lanes are all recorded with artifact paths, workload parameters, tool version/provenance, selected seL4 build, gateway/auth mode, QEMU SMP topology, target transport, and error-budget policy.
- QEMU/Pi comparisons reject stale or mismatched artifacts before any verdict; Pi evidence remains fresh, timer-qualified, and paired with raw TCP/cohsh proof for the selected transport.
- The live direct-link DHCP supervisor recreates its disposable runtime directory before every service attempt, so an `out/` cleanup cannot silently strand the GENET control lane.
- Tuning preserves Secure9P bounds, console grammar, manifest authority, no-retry failure accounting, HAL/driver-task ownership, and root-task no-std constraints.
- CYW43 performance comparison retains the approximately 315-ms request-to-first-payload mean and 407-ms p95 / approximately 2.9-command-per-second baseline. The earlier proposed tenfold-improvement target of request-to-first-payload p95 at or below 40 ms and at least 29 successful requests per second, and the aggressive low-overhead target of p95 at or below 10 ms and at least 100 successful requests per second, remain non-blocking optimization targets rather than Milestone 26b closure gates. Accepted exact-image hardware proof is the usable, repeatable no-semantic-loss envelope established by the operator-approved `2668c34f76ff` candidate transport matrix above and required again from the repaired candidate, including honest bounded recovered retransmission accounting and an unchanged GENET control within its accepted envelope.
- Wi-Fi remains a research/diagnostic lane with the documented worker envelope; production throughput parity still requires fresh wired/GENET evidence.
Deliverables:
- Benchmark ledger and refreshed artifacts that make the seL4 16 performance delta reviewable before later milestones depend on the refreshed baseline.
Title/ID: m26d-domain-schedule-debt-removal
Goal: Remove or explicitly resolve stale legacy domain-schedule dependencies from Cohesix seL4 build configurations.
Inputs: fresh-source Pi profile audit outputs, the repo-managed immutable `seL4/build_UBOOT` v16 diagnostic artifact input, Pi 4 build scripts, seL4 16.0.0 upgrade notes.
Changes:
- scripts/pi4-image-build.sh and related build docs — ensure Cohesix-owned Pi 4 flows do not silently depend on stale `domain_schedule.c` defaults when domains are not in use.
- docs/HARDWARE_BRINGUP.md and docs/BUILD_PLAN.md — document the resolved seL4 16 domain-schedule posture for Cohesix.
Commands: scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml --venv .venv
Checks: one-domain Cohesix builds no longer inherit accidental `sel4test` schedule-file assumptions.
Deliverables: documented and verified domain-schedule posture for Cohesix seL4 16 builds.
Title/ID: m26d-isolated-runtime-wx-closure
Milestone: Milestone 26d — seL4 16 Baseline Refresh + Reference/Performance Realignment / isolated-runtime W^X closure
Goal: Make every isolated-runtime VSpace mapping fail-closed for execute permission without changing the driver-task ABI or CYW43 behavior.
Inputs: apps/root-task/src/hal/mod.rs, apps/root-task/src/sel4.rs, seL4 16 AArch64 page attributes, profile-selected isolated runtime ELF images.
Changes:
- apps/root-task/src/hal/mod.rs — validate ELF load flags and checked ranges, reject W+X and effective page-level permission collisions, and derive executable-page intent before child allocation.
- apps/root-task/src/hal/mod.rs + apps/root-task/src/sel4.rs — add execute-never while preserving cache/device attributes for every non-code root alias and child mapping; retain only validated read-only code and the reviewed trampoline as executable.
- apps/root-task/src/hal/mod.rs tests — cover malformed headers, unknown flags, RWX segments, page collisions, read-only code, data, holes, shared resources, DMA, and MMIO attribute policy.
Commands:
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::tests::runtime_
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hal::tests
- SEL4_BUILD_DIR="$PWD/seL4/build_UBOOT" cargo check -p root-task --target aarch64-unknown-none --no-default-features --features release-pi4
Checks: no writable child page is executable, no unvalidated ELF flag can create executable authority, cache/device policy is preserved, and the isolated-runtime ABI plus CYW43-owned state machine are unchanged.
Deliverables: reviewed W^X implementation, focused regression tests, and Pi 4 target compile evidence.
Title/ID: m26d-canonical-sel4-profile-closure
Milestone: Milestone 26d — seL4 16 Baseline Refresh + Reference/Performance Realignment / canonical seL4 profile closure
Goal: Make the accepted seL4 16 production, diagnostic, and proof configurations reproducible and fail-closed from pinned upstream source, then make the validated production contract the operational QEMU default.
Inputs: official seL4 16.0.0 manifest and project revisions, official Arm GNU Toolchain 15.2.Rel1 macOS ARM64 archive, official DENX U-Boot 2026.01 archive, configs/sel4/profiles.toml, configs/sel4/python-*.lock, toolchain/setup_macos_arm64.sh, tools/sel4-profile-project/CMakeLists.txt, scripts/sel4_profile.py, scripts/cohesix-build-run.sh, scripts/release_bundle.sh, scripts/qemu-run.sh, scripts/cohsh/run_regression_batch.sh, staged Test Plan scripts, seL4 build outputs, QEMU launch inputs.
Changes:
- configs/sel4/profiles.toml + configs/sel4/python-*.lock — pin official project revisions, the self-contained Arm compiler archive and executable identities, the exact Python distribution closure, the DENX mkimage source archive, and target, GIC, SMP, domain, debug, benchmark, counter-export, and claim-eligibility contracts for each supported profile.
- toolchain/setup_macos_arm64.sh — provision the pinned compiler, isolated hash-locked Python environment, and mkimage build without using a rolling compiler formula or a dirty/incomplete repository source tree; emit provenance records bound to the setup script and profile contract.
- tools/sel4-profile-project/CMakeLists.txt — configure upstream seL4 without inheriting the legacy sel4test domain-schedule assignment, regenerate the platform memory map required when fixed-address Pi elfloader images also load rootservers last, and add only the contract-selected bounded file-backed QEMU production placeholder reserve required for logical rootserver replacement.
- scripts/sel4_profile.py — require fresh build directories, disable configure-time memoization, reject stale or pre-existing stamps and outputs, bind a causally fresh completed stamp to every input and output, reject unknown evidence classes or class/eligibility mismatches, and validate source provenance, compiler/Python/mkimage identities, caches, generated headers including the rootservers-last elfloader memory map, QEMU rootserver-archive capacity, independently parsed DTB/launcher agreement, strict executable ELF structure, shipping/RWX policy, forbidden settings, and proof eligibility without mutating evidence to make it pass.
- scripts/cohesix-build-run.sh + scripts/release_bundle.sh + scripts/qemu-run.sh + scripts/tcp_*.sh + scripts/cohsh/run_regression_batch.sh + staged Test Plan scripts — default QEMU consumers to `out/sel4/profile-v2/qemu-smp-production`; validate runtime or release intent before consuming the canonical tree and classify explicit unvalidated alternatives as claim-ineligible.
- README.md + docs/QUICKSTART.md + docs/HARDWARE_BRINGUP.md + docs/DRIVERS.md + docs/OPERATOR_WALKTHROUGH.md + docs/TEST_PLAN.md + apps/root-task/README.md — publish the same canonical default while preserving explicit diagnostic/historical qualifications.
- docs/TOOLCHAIN_MAC_ARM64.md + docs/audit/M26D_SEL4_16_PROVENANCE.md — document the canonical workflow and distinguish accepted builds from legacy/diagnostic inputs.
Commands:
- toolchain/setup_macos_arm64.sh
- out/toolchain/sel4-profile-venv/bin/python -m pytest -q tests/test_sel4_profile.py
- out/toolchain/sel4-profile-venv/bin/python scripts/sel4_profile.py validate --all --require-source --require-artifacts --evidence out/audit/m26d-profile-v2-all.json
- scripts/cohesix-build-run.sh --sel4-build out/sel4/profile-v2/qemu-smp-production --no-run --cargo-target aarch64-unknown-none
Checks: QEMU uses GICv3 in both parsed DTBs; one-domain profiles have no schedule-file dependency; fixed-address Pi rootservers-last builds contain generated `memory_region` metadata; the QEMU production elfloader archive meets its declared minimum and accepts the current boot-minimized Cohesix root task without in-place ELF growth; source revisions and canonical Pi overlay digest match the official pin; compiler archive/version/target/binary identities, exact Python locks and installed-file digest, DENX source and mkimage provenance, caches, generated outputs, immutable input hashes/values, causal build times, and strict `ET_EXEC`/RX-entry ELF structure agree; aggregate closure requires all five fresh `out/sel4/profile-v2/*` source and artifact sets unless explicitly diagnostic-relaxed; evidence classes have fixed release/runtime eligibility; upstream wrapper artifacts remain machine-classified non-shipping; shipping artifacts reject RWX; diagnostic settings cannot earn proof claims; all active QEMU build/release/regression/test defaults consume the canonical production path and revalidate it before claims; validation fails on drift. A fresh target-qualified run at `out/test-plan/m26d-qemu-sel4-16-gap-audit` must pass linked GICv3 boot, authenticated TCP regression, REST parity, and due diligence before replacing the retained seL4 15 comparator.
Deliverables: source-controlled profile contract, wrapper, validator, operational/release adoption, tests, runbook alignment, and provenance record.
Title/ID: m26d-worker-execution-truth-repair
Milestone: Milestone 26d — seL4 16 Baseline Refresh + Reference/Performance Realignment / reopened Milestone 25 task-isolation and 26c Worker execution truth
Goal: Make generated and documented Worker execution claims match the currently launched target objects while preserving existing host/session behavior.
Inputs: configs/root_task*.toml, tools/coh-rtc, generated root-task artifacts, apps/root-task/src/worker_authority.rs, canonical Worker/security/interface docs, Milestone 25/26c audit ledgers.
Changes:
- configs/root_task*.toml + tools/coh-rtc — emit model-only general Worker roles as not target-implemented, disable executable-role capability/notification claims consistently, and reject `implemented=true` until a generated task-object contract exists.
- generated artifacts + focused tests — regenerate all profile outputs and reject manifests that claim executable-role authority or lifecycle notifications without an executable role contract.
- canonical docs + audit ledgers — distinguish host/session tickets and in-process models from target TCB execution, and record the reopened closure phase for real Worker objects, badged IPC, lifecycle notifications, fault handling, and revocation.
Commands:
- cargo test -p coh-rtc
- cargo test -p root-task --lib worker_authority
- scripts/check-generated.sh
Checks: generated truth, tests, and prose agree; no model-only role is called live or capability/notification-backed; existing namespace/ticket semantics remain unchanged; driver-runtime TCB proof is not reused as general Worker proof.
Deliverables: regenerated as-built Worker truth plus an explicit, separately gated target-execution closure phase.
Title/ID: m26d-sel4-capability-utilization-audit
Milestone: Milestone 26d — seL4 16 Baseline Refresh + Reference/Performance Realignment / capability, scheduling, and TCB decision closure
Goal: Bound what Cohesix uses from seL4 16 today and prevent unused features or model-only code from becoming product claims.
Inputs: seL4 Reference Manual v16.0.0, generated kernel headers, root-task/HAL/Worker code, docs/audit/M26D_SEL4_16_CAPABILITY_AUDIT.md, docs/audit/M26D_MCS_DECISION.md, docs/audit/M26D_ROOT_TCB_BOUNDARY_AUDIT.md.
Changes:
- docs/audit/M26D_SEL4_16_CAPABILITY_AUDIT.md — classify each relevant kernel capability as implemented, partial/model-only, intentionally unused, or blocked, with direct evidence and closure routing.
- docs/audit/M26D_MCS_DECISION.md — retain non-MCS for 26d, record the strong architectural-fit verdict and selected SMP+MCS successor, compare classic SMP/single-core MCS/SMP+MCS, define bindings, scheduling-contract, WCET/budget, fault, target-evidence, and atomic-reversion gates, and route implementation to `m26e-mcs-abi-foundation` and `m26e-mcs-smp-target-acceptance`.
- docs/audit/M26D_ROOT_TCB_BOUNDARY_AUDIT.md — record current root-owned parsers, networking, supervision, policy, and audit surfaces plus the exact ordered Milestone 26e split tasks and required evidence.
Commands:
- scripts/check-generated.sh
- cargo test -p root-task --lib
Checks: no audit entry confuses API availability with Cohesix use; no live Worker or MCS claim lacks target evidence; root-owned services are named rather than implied isolated; every deferred capability has an explicit milestone route or rationale.
Deliverables: capability matrix and accepted MCS/root-TCB boundary decisions tied to as-built evidence.
Title/ID: m26d-smp-command-post-cutover-usability
Milestone: Milestone 26d — seL4 16 Baseline Refresh + Reference/Performance Realignment / linked-UART SMP diagnostic defect correction
Goal: Make bare `smp` useful after linked-UART cutover by routing it to the existing bounded activity report while preserving the raw scheduler snapshot as explicit debug-only `smp dump`.
Inputs: crates/cohsh-core/src/{command.rs,verb.rs,help.rs}, apps/root-task/src/{console/mod.rs,event/mod.rs,affinity.rs}, docs/USERLAND_AND_CLI.md, docs/HARDWARE_BRINGUP.md, docs/snippets/cohsh_grammar.md, current seL4 16 QEMU/Pi diagnostic profiles, and linked-UART Pi evidence.
Changes:
- crates/cohsh-core/src/command.rs + crates/cohsh-core/src/verb.rs + crates/cohsh-core/src/help.rs — map bare `smp` and compatibility spelling `smp activity` to `SmpMode::Activity`, retain raw `SmpMode::Snapshot` only behind explicit `smp dump`, reject unknown/extra arguments, and align shared help/grammar.
- apps/root-task/src/console/mod.rs + apps/root-task/src/event/mod.rs — route both activity spellings through the existing bounded userspace report; keep the raw scheduler helper available only for explicit debug dumps and reject it after linked-UART cutover without reclaiming UART ownership.
- docs/USERLAND_AND_CLI.md + docs/HARDWARE_BRINGUP.md + generated grammar snippets — make bare `smp` the normal operator instruction, retain `smp activity` for compatibility, and describe the narrow pre-cutover/QEMU diagnostic use and UART restriction of `smp dump`.
Commands:
- cargo test -p cohsh-core smp
- cargo test -p cohsh-core --test doc_snippets
- cargo test -p root-task smp_
- cargo test -p root-task --features net-console smp_
- cargo fmt --all -- --check
- scripts/check-generated.sh
Checks:
- `smp` and `smp activity` emit the same bounded userspace activity records and terminate with `OK SMP mode=activity`.
- `smp dump` is the only operator route to the existing raw scheduler snapshot; non-debug builds and post-cutover linked-UART profiles reject it deterministically without touching UART MMIO.
- The correction adds no telemetry fields, authority path, namespace, manifest field, kernel benchmark dependency, or root-owned steady-state UART fallback.
- Shared help, generated grammar, canonical operator docs, parser tests, root-task tests, and generated-artifact drift checks agree.
Deliverables: One safe default SMP diagnostic, one explicit debug-only raw snapshot spelling, and aligned tests/operator instructions.
Title/ID: m26d-repository-gate-closure
Milestone: Milestone 26d — seL4 16 Baseline Refresh + Reference/Performance Realignment / repository-wide regression gate closure
Goal: Restore every mandatory repository-wide source, dependency, packaging, and staged-regression gate exposed while preparing the refreshed QEMU and Pi 4 evidence, without changing operator-visible semantics or hardware authority.
Inputs: Cargo.toml, Cargo.lock, deny.toml, apps/root-task/build.rs, apps/root-task/build_support.rs, apps/root-task/sel4.ld, apps/root-task/src, scripts/cohesix-build-run.sh, scripts/pi4-image-build.sh, scripts/pi4_image_identity.py, scripts/pi4_wifi_repeatability.py, scripts/pi4_trace_normalize.py, scripts/ci/test_plan_*.sh, scripts/ci/due_diligence_gate.sh, .github/workflows/*.yml, README.md, docs/TEST_PLAN.md, docs/audit risk registers, current M26b/M26d source and build evidence.
Changes:
- Cargo.toml + Cargo.lock + CI — update vulnerable or yanked transitive dependency selections to supported compatible versions without widening VM dependency closure, track the lockfile, and reject stale resolution before build/test commands.
- apps/root-task/build.rs + apps/root-task/build_support.rs + apps/root-task/src — correct fresh-checkout generated-artifact validation, deterministic test-contract drift, and strict lint failures exposed by the canonical Pi 4 Stage 02 feature set.
- apps/root-task/src/hal + apps/root-task/src/sel4.rs + configs/sel4/profiles.toml + tools/sel4-profile-project/CMakeLists.txt — admit the complete selected linked-runtime capability inventory before creating any child, retain bounded post-bootstrap CSpace headroom, transfer child-only code/stack/framebuffer mappings without permanent root aliases, and establish the then-required 14-bit Pi root-CNode minimum so runtime-image growth fails in deterministic build/bootstrap gates instead of panicking during shared HDMI setup. Milestone 26e later supersedes that minimum with the 16-bit full-Worker profile.
- apps/root-task/sel4.ld + scripts/pi4-image-build.sh + scripts/pi4_image_identity.py + scripts/pi4_wifi_repeatability.py — place one fixed-width marker in a dedicated file-backed root-task load section, keep the tracked `seL4/build_UBOOT` profile artifact tree immutable, reproduce its baseline elfloader byte-for-byte as a relink-tool oracle, compose the new rootserver/CPIO/wrapper only in disposable output, bind the canonical tree, tool identities, oracle, and derived tuple in provenance, seal the wrapper with the domain-separated normalized digest of the complete legacy Pi image, repair and revalidate U-Boot CRCs, and require staged/read-back bytes plus every UART slice to agree on that content-derived identity.
- scripts/pi4-image-build.sh + focused host tests/docs — make routine Pi media refresh a single exact-child in-place synchronization on an already provisioned MBR/FAT32 `COHESIX` card, reject locked macOS sessions before mutation, keep the host awake through the critical section, preserve and verify the private policy, compare every staged file, and unmount only that child. Whole-disk initialization remains an explicit operation and is never an automatic fallback; normal reflash must not repartition, reformat, force-unmount the whole medium, or select another same-label volume after AppleSDXC re-enumeration.
- scripts/cohesix-build-run.sh and focused tests/docs — keep the QEMU rootfs below the 4 MiB guard while preserving all manifest-declared runtime artifact names, bytes, and isolated-runtime lookup semantics.
- scripts/ci, tools/rust-risk-audit, README.md, and canonical docs — make Python selection exact and recoverable, count cfg-test Rust separately from production risk, record the real linked-runtime unsafe delta, and align as-built packaging explanations with the canonical QEMU path.
- .github/workflows/*.yml — keep one required per-change `ci` job as a small non-claiming health signal: locked dependency resolution, generated-contract integrity, one default workspace check/test pass, host compilation of the QEMU/Pi root-task feature test binaries, and the bare-metal Pi runtime target check. Keep fresh advisory checks weekly/manual, use least-privilege permissions and deterministic pins, rely on native job logs, and leave complete feature behavior, Python, UI, risk/lint, target, performance, and release qualification in focused developer validation or the canonical Test Plan instead of repeating them on every push. Stage 02 target compilation and QEMU packaging remain in the provisioned macOS ARM64 evidence lane because their canonical external seL4 build trees are intentionally not vendored.
- CI compatibility review — the hosted-policy reduction and corrected eight-millisecond QEMU guard oracle change no host-tool, `tools/cohesix-py`, benchmark implementation, report schema, external interface, or target authority. The NIST documentation smoke uses base-system `grep -E`, and the seL4 syscall-routing guard scans Rust sources in-process, so a clean hosted runner does not require a separately installed search tool. Those surfaces remain catalogued for focused and staged validation and require no implementation change here.
Commands:
- actionlint .github/workflows/*.yml
- cargo metadata --locked --no-deps
- cargo fmt --all -- --check
- cargo clippy --workspace --all-targets -- -D warnings
- cargo check --workspace
- cargo test --workspace -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-qemu --lib --no-run
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib --no-run
- cargo check -p pi4-driver-runtime --target aarch64-unknown-none
- cargo test -p rust-risk-audit
- scripts/ci/rust_risk_gate.sh --baseline docs/audit/rust_risk_baseline.toml
- cargo audit
- cargo deny check advisories
- scripts/check-generated.sh
- PATH=/usr/bin:/bin bash tests/security/nist_evidence_smoke.sh
- cargo test -p root-task --test sel4_syscall_guard -- --test-threads=1
- python3 -m pytest -q tests/test_pi4_image_identity.py tests/test_pi4_wifi_repeatability.py tests/test_pi4_trace_normalize.py
- scripts/cohesix-build-run.sh --no-run --cargo-target aarch64-unknown-none
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26d-repository-gates-qemu
- scripts/ci/test_plan_run.sh --target pi4 --stage 1 --state-dir out/test-plan/m26d-repository-gates-pi4
- scripts/ci/test_plan_run.sh --target pi4 --stage 2 --state-dir out/test-plan/m26d-repository-gates-pi4
Checks: mandatory lint, workspace, dependency, generated-artifact, QEMU packaging, cfg-aware risk-ratchet, and offline staged-regression gates pass with no newly ignored advisory, forged or duplicated image marker, invalid U-Boot envelope/CRC, staged/read-back alias, truncated supervisor record, skipped stage, rootfs-size exception, operator grammar drift, or loss of manifest-declared driver-runtime artifact identity; ordinary Pi reflash proves exact whole/child ownership, refuses locked-session mutation, performs no whole-disk topology change or global label fallback, preserves the bounded private policy, and verifies every staged file before exact-child unmount; accepted production unsafe growth is explicit and expiry-bounded; live Pi stages remain separately hardware-gated; the required hosted check reports only material source-contract, compile, target-compile, and default-test failures, its NIST and syscall-routing guards need no separately installed search tool, and it cannot be cited as staged or target acceptance; every retained workflow parses cleanly, references only tracked commands, preserves required event coverage, and has no redundant or no-op job.
Deliverables: reviewable dependency resolution and risk register, deterministic root-task/Python regression coverage, sub-4-MiB QEMU payload, clean QEMU plus offline Pi target-qualified gate evidence, and one coherent GitHub Actions surface consisting of the small required `ci` signal plus separately scheduled/manual dependency visibility.
Title/ID: m26d-cyw43-hardware-free-closure
Milestone: Milestone 26d — seL4 16 Baseline Refresh + Reference/Performance Realignment / hardware-free CYW43 reliability closure; Reopened Milestone 26b / m26b-wifi-sdio-notification-dpc-closure and m26b-net-control-priority
Goal: Make the Pi 4 CYW43/SDIO linked-runtime design software-complete, deterministic, event-pump-driven, adversarially tested, artifact-bound, and repository-green without claiming unavailable repeatability proof from physical hardware.
Inputs: AGENTS.md, docs/BUILD_PLAN.md, docs/DRIVERS.md, docs/HARDWARE_BRINGUP.md, docs/TEST_PLAN.md, /Users/lukasbower/REBOOT.md, newest non-empty Pi serial logs and boot-paired pcaps, configs/root_task.toml, configs/root_task_pi4_uboot_aarch64.toml, configs/generated/root_task_resolved.json, tools/coh-rtc, generated bootstrap/profile outputs, crates/pi4-driver-abi/src/lib.rs, apps/pi4-driver-runtime/src/lib.rs, apps/root-task/Cargo.toml, apps/root-task/src/{drivers/driver_task_net.rs,event,hal,net/{mod.rs,queue.rs,stack.rs},serial,userland}, scripts/pi4-image-build.sh, scripts/pi4_image_identity.py, scripts/pi4_wifi_repeatability.py, scripts/pi4_trace_normalize.py, and focused/runtime/repository gate suites.
Changes:
- The pointer-free ABI defines the 24-byte sequence-last continuation grant, 24-byte RX queue state at local offset 192 and 128-byte RX batch record at shared offset 36,864. Bounded records bind complete action identity, owner generation, grant/consumed sequence and immutable payload ownership; no partial record grants authority.
- SDIO alone captures/clears/acknowledges physical IRQs and publishes durable child completion before waking CYW43. CYW43 retains exact foreground, DPC and RX transactions. Non-CYW43 commands retain endpoint rendezvous; admitted CYW43 commands use their exact grant/persistent/finite-op7 contracts without endpoint fallback, arbitrary root continuation or duplicated physical issue.
- EventPump admits at most one root CYW43 parent per outer turn. Ordinary publication retains Stage, CommitRing, PublishGrant, NotifyRing and PollRing phases with signal last; exact persistent op11 commits and signals in its single admitted producer call. A terminal or accepted grant observed before replacement publication wins without redundant signal.
- Bootstrap and recovery use one retained no-allocation supervisor. Logical connection identity, physical pair generation and immutable action identity remain distinct. Shared-page aliases, parent/child ownership, whole-pair reset and named child/credit/queue waits are validated before device activity; a consumable wake edge cannot become recovery authority.
- RX uses immutable bounded batches and exact queue/ACK watermarks. TX consumption only enqueues into the generation-scoped urgent/bulk queue of aggregate capacity 16. One active op7 owner retires before another admission, committed RX precedes fresh TX, and a retained foreign HAL owner cannot be revoked to manufacture progress.
- Production-chain tests exercise actual admission, durable-state, race and terminal helpers. Hardware-free checks establish these contracts only. The accepted 26b task supersedes earlier urgent-only, normal-deadline, hintless and zero/no-ACK proposals; its physical acceptance remains independently required.
- Trace readers preserve historical formats and distinguish source/ABI evidence from exact-image radio, DHCP, TCP and local-seat proof. Public command, namespace, Secure9P, host-tool, Python and benchmark workload contracts remain unchanged.
Commands:
- cargo fmt --all -- --check
- cargo clippy --workspace --all-targets -- -D warnings
- cargo check --workspace
- cargo test --workspace -- --test-threads=1
- cargo test -p pi4-driver-abi -- --test-threads=1
- cargo test -p pi4-driver-runtime --lib -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib -- --test-threads=1
- cargo test -p root-task --lib --no-default-features --features net-console icmp_echo -- --test-threads=1
- cargo check -p pi4-driver-runtime --target aarch64-unknown-none
- cargo rustc --locked --release -p pi4-driver-runtime --lib --target aarch64-unknown-none -- -D warnings
- .venv/bin/python -m pytest -q tests/test_pi4_image_identity.py tests/test_pi4_wifi_repeatability.py tests/test_pi4_trace_normalize.py
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
- scripts/ci/rust_risk_gate.sh --baseline docs/audit/rust_risk_baseline.toml
- scripts/ci/due_diligence_gate.sh
- scripts/ci/test_plan_run.sh --list
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26d-cyw43-hardware-free-qemu
- scripts/ci/test_plan_run.sh --target pi4 --stage 1 --state-dir out/test-plan/m26d-cyw43-hardware-free-pi4
- scripts/ci/test_plan_run.sh --target pi4 --stage 2 --state-dir out/test-plan/m26d-cyw43-hardware-free-pi4
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml --venv .venv
Checks: every outer EventPump turn admits at most one root CYW43 parent. Ordinary foreground publication preserves bounded `Stage`, `CommitRing`, `PublishGrant`, `NotifyRing`, and `PollRing` phases with signal last, while exact op11 crosses Stage, sequence-last commit, and its sole signal inside the same admitted producer call and remains persistent to terminal. Focused EventPump/root-admission models cover both an already-open pair lease and an initially inactive outer lease with no test pre-open. The inactive case must prove exact association claim -> EventPump outer lease open -> NetStack Join `Stage -> CommitRing -> Issued -> one signal`, with zero request-bound boost/restore actions; the already-open case must reuse its pair reservations without duplicate boosts. Both retain the outer lease `Open` across the exact persistent wait receipt without polling, then resume the same episode for the durable terminal and deterministic close/restore, with no second signal, request, grant, completion poll clock, idle scheduling gap, or unrelated policy admission; sideband ACK admission remains `Issued`-only and rejects every terminal-restore phase without signalling. A stable receipt permits the ordinary waiting park, and a later exact terminal resumes and retires the same parent. These warm seam models are necessary but cannot qualify a hardware candidate. Qualification additionally requires one bounded composition starting at cold `Cyw43BootstrapSupervisor::new` and using the production EventPump, HAL admission, root client, CYW43 runtime, and SDIO runtime dispatch through the prior `q=0x408` DPC/RX frontier, Gates 1 through 10, and the raw-TCP software consumer; only post-issue card/AP boundary responses may be scripted. Production DPC uses one event-sequence lease from the first post-release event and never selects recurrent grants from mutable Gate 8 state; urgent op7 retains its separate finite identity and budget. EAPOL-Start and ordinary control prove the ordinary retained cadence. Valid sealed current-generation M2, M4, and group-key replies alone prove the existing paired finite-op7 marker, exact one-frame/four-operation/1,536-byte bounds, request-bound CYW43-plus-SDIO priority, one notification, no later grant or signal, durable matching-terminal resume, and recovery-only expiry. Their Function-2 data child does not inherit persistent control's pre-TX fence; a concurrent source-bearing event remains durable DPC work. Steady parent identity remains exact through both committed-source and ACK-before-source publication states; only the committed event is DPC service authority, and neither state can select an ordinary grant. Malformed, untagged, stale, wrong-message, and ordinary Ethernet inputs fail before issue. Ordinary post-Gate-8 TCP proves its O(1) path without the EAPOL-Key parser, poller, or fallback. Current durable conditions—not snapshot novelty—route persistent op11, urgent op7, and DPC event service: deterministic private phases continue locally even when equal, while exact child, credit, queue, and peer waits block immediately even when first observed. The post-release activation remains live for the physical generation; healthy owner-active empty/unmasked control state skips `DPC_ACTIVATE`, and one exact visible event is consumed before TX. Only activation-absent or mask-skewed state, plus exact ACK debt bound to an already-submitted immutable activation frontier, uses the activation-repair child; invalid, wrong-generation, poisoned, overrun, or lost-authority state fails closed. SDIO alone takes one live joined-controller sample after a changed steady cursor before blocking. Every helper is bounded and every immutable hardware request issues at most once. Before blocking, CYW43 rechecks its selected marker/event lease, parent/child terminal, event frontier, and queue/batch/ACK condition. SDIO separately rechecks its selected persistent marker or ordinary grant, active child/completion, joined IRQ/CARD_INT, deadline arm, owner health, and—immediately before idle receive—its own sequence-last one-way command ring. A fresh child re-enters SDIO arbitration; unchanged owner-local conditions may block. A committed sequence-last SDIO command reaches owner dispatch and either the validated physical path or a typed zero-I/O missing/competing-seal terminal; it is never discarded as no intake. Production-chain coverage proves both healthy activation reuse with no child and the separate activation-absent or mask-skewed `DPC_ACTIVATE` repair, plus exact ACK debt retained by an already-submitted immutable activation frontier, through production SDIO, a sequence-last terminal, coalesced notification, and hintless exact-parent replay. ACK failure performs zero I/O; after exact ACK retry succeeds, cleared current fault/mask flags plus durable `OWNER_ACTIVE` re-admit healthy work even though the per-pair historical count remains nonzero. Once an exact wait receipt proves the child is blocked, root exact-op11 `Waiting` masking cannot suppress independent DPC/RX/sideband/deadline/terminal work. Immutable generation-bound descriptors cannot fall back to endpoint authority, and issued-unknown reaping preserves the exact continuation until its late terminal or canonical restart.
SDIO alone owns IRQ 158 and IRQ 116. Tests deliver them in both orders, coalesce them, and withhold each independently; exactly one terminal appears only after the immutable request's SDHCI and DMA conditions join. The RX producer clears the queue commit before mutation, writes the body, cleans/barriers, and writes a new nonzero commit last. One parent writes one through eight payloads and batch entries, cleans/barriers, and writes `committed_parent_sequence` last. Op8 then publishes one detail-`0x5803` completion with `result=count`; op11 instead remains active while root copies the batch, post-copy rechecks the header, and commits an exact disjoint ACK body then `committed_queue_commit_sequence` last. CYW43 must not mutate or reuse the batch until that ACK matches. Missing, coalesced, and repeated notification hints produce identical delivery. A full 256-frame software backlog uses 32 full batch handoffs, not 256 root grants, terminals, or notification signals. SDIO arms every blockable active autonomous phase with its exact counter expiry, including pre-issue inhibit/status-clear, and selects the earlier settle/overall expiry during containment clock settle; a blockable phase without a counter deadline fails closed. Terminal/reset clears the arm before publication. Normal traffic completes from physical IRQs and durable levels with zero root fault hints; a stable expired arm produces at most one hint across the existing root-to-CYW43-to-SDIO chain, and terminal/arm races resolve by SDIO's final recheck without a rescue poll or synthetic receive progress. DPC overrun and ACK-attempt counts reset at pair replacement; current flags/pending state are authority, while final acceptance still requires zero errors in every fresh pair.
For the ABI v8 receipt check, `contiguous` means one externally uninterrupted
same-parent bus-service episode across HAL admission, CYW43 protocol ownership,
and SDIO physical ownership. Open, bounded Closing, and the exact handoff
boundary may include required Serial/LocalSeat/Dispatch fairness checkpoints,
but no idle gap or unrelated policy/NIC owner. The receipt is the distinct-magic
24-byte record at auxiliary offset 40; CYW43 uses a producer-monotonic nonzero
epoch and fails closed on exhaustion, and root accepts only a stable exact-field
double-read. Receipt or terminal proves the handoff, never both as concurrent
authority.
The exact ordinary-traffic diagnostic requirement is `sdio_deadline_hints=0`.
The TX aggregate proves total capacity 16, urgent-control-before-bulk FIFO selection, the ordinary 15-slot boundary, the final paired-RX reservation, queue-only TxToken consumption, EventPump-only physical coordination, preservation of an exact foreign owner before op7 admission, active-op7 terminal priority, and committed copied/DPC/runtime RX before fresh or requestless op7 promotion. The real firmware parent crosses the retained SDIO controller as `511 * 64 + 1 * 64`; normal control and EAPOL-Start use the ordinary cached-window F2 child, while sealed M2/M4/group-key responses use the bounded request-bound finite parent without inheriting persistent control's F2 fence. A cold miss uses exact LOW/MID/HIGH/F2 children, and the post-F2 release culminates in the generation's one DPC activation. No test may fabricate child completions, mailbox readiness, terminal streams, or per-frame op8 handoffs. Stale, torn, mutated, wrong-generation, replayed, exhausted-id, issued-unknown, and replacement-generation cuts fail closed. The sole boot episode cannot produce attempt 2; only exact-generation bound DHCP plus an admitted TCP listener authorizes the later consumed-once runtime repair. Operator surfaces remain bounded after quarantine, GENET remains unchanged, deterministic repository gates pass, and the exact image remains commit-bound. The common raw-ICMP owner retains the cold-neighbor ARP/reply and warm one-request/one-reply checks without creating CYW43 source work.
The root notify boundary additionally accepts only the exact legal
`unconsumed -> current-id` acknowledgement race: if it occurs between poll and
notify, root commits `Issued`, sends no redundant signal, and polls on the next
turn. A matching late completion before replacement publication likewise wins
without publishing or signalling.
Deliverables: retained linked-runtime implementation, production-chain adversarial tests, aligned canonical docs, exact-image identity metadata, deterministic gate records, and a Pi-ready exact image. This task's closure was hardware-free only. Its original 10-cold plus 10-warm proposal was superseded for final physical Milestone 26b acceptance by the operator-approved matrices recorded above. Exact image `7a10b8fd6acc` completed one settled cold Wi-Fi boot, five reboot attempts, and one same-image GENET control with raw TCP, first-attempt `.coh`, no-retry pressure, and boot-paired pcap evidence. W04 remains an explicitly excluded RF-affected sample; cold, W01-W03, W05, and G01 form the accepted closure set. No fresh USB key was typed, so the current-image record claims only repeated Gate 10, one-deep idle-report, command-ready, recovery-free, and HDMI-complete evidence plus exact restoration of the previously board-proven path under the operator-approved image-specific exception.
Title/ID: m26d-linked-runtime-unsafe-exception-remediation
Milestone: Milestone 26d — seL4 16 Baseline Refresh + Reference/Performance Realignment / repository-wide regression gate closure; reopened Milestone 26b / m26b-wifi-sdio-notification-dpc-closure defect remediation
Goal: Remove the accepted linked-runtime Rust unsafe delta by enforcing shared-state exclusivity and concentrating fixed mapped-memory and seL4 operations behind bounded reviewed abstractions without changing the CYW43/SDIO protocol or hardware authority.
Inputs: Cargo.toml, Cargo.lock, rust-toolchain.toml, apps/pi4-driver-runtime/src/lib.rs, apps/pi4-driver-runtime/build.rs, apps/root-task/build.rs, apps/root-task/src/hal, apps/root-task/src/drivers/driver_task_net.rs, crates/pi4-driver-abi/src, crates/cargo-build-directive, crates/sel4-sys/build.rs, tools/rust-risk-audit, scripts/ci/rust_risk_gate.sh, scripts/ci/test_rust_risk_gate.py, scripts/ci/due_diligence_gate.sh, scripts/ci/test_due_diligence_lifecycle.py, docs/audit/rust_risk_baseline.toml, docs/audit/findings.csv, docs/audit/EXCEPTIONS.md, docs/audit/BLOCKERS.md, docs/audit/CONTROL_TRACEABILITY.md, docs/audit/checklists/RELEASE_EVIDENCE_CHECKLIST.md, the `cf8f9ee30` Milestone 26c baseline, and current repository-gate evidence.
Changes:
- apps/pi4-driver-runtime/src/lib.rs — replace convention-only shared mutation with mechanically enforced exclusivity, keep volatile and syscall operations inside narrow fixed-resource helpers, and preserve sequence-last publication, reciprocal notification, DPC, MMIO, and bounded-yield behavior.
- apps/root-task/src/hal/driver_task.rs — consume completion and DPC commit words with acquire-before-body ordering, stable commit rechecks, and focused access-order tests.
- crates/cargo-build-directive + the three consuming build scripts — centralize control-character rejection for dynamic Cargo directives and tested Rust-string-literal escaping; bind the helper source, manifest, dependency wiring, and historical absence into the exact scanner contract.
- tools/rust-risk-audit + docs/audit/rust_risk_baseline.toml + scripts/ci/rust_risk_gate.sh + scripts/ci/test_rust_risk_gate.py — retain the global production ratchet and add linked-runtime/HAL plus outside-component budgets replayed from exact commit `cf8f9ee30` only after every scanner-input path matches its raw `HEAD` blob and mode and the attested path set has no additions or omissions; count qualified/UFCS, raw-identifier, macro-indirected, and conditional unsafe-attribute syntax across repository-authored `apps/`, `crates/`, and `tools/` production sources; pin exact active and historical tuples; execute the scanner directly on the host after a hash-checked build in a fresh private target directory and Cargo home that re-extracts checksum-verified registry archives; resolve the exact repository-selected tools from the canonical OS-account Rustup home by named-toolchain lookup so directory overrides cannot supersede the pin; reject component relocation, baseline inflation, broad test-path hiding, workspace/package/Cargo target/dependency escapes, nested-package test relabeling, local proc-macro synthesis, source redirects, symlink/non-Rust includes, shadowable generated includes, unreviewed generated Rust, uncontracted build scripts/compiler wrappers or inputs, repository-controlled `cfg(test)` injection, Cargo runner/compiler/Rustup selectors, external Cargo configuration, inherited or redirected Git repository binding, replacement refs, clean filters, ignored extra sources, caller-supplied scanner artifacts, malformed metadata, and duplicate TOML keys.
- scripts/ci/due_diligence_gate.sh + scripts/ci/test_due_diligence_lifecycle.py — enforce a one-to-one finding/exception lifecycle, exact CSV/table schemas and arity, known severities/states, non-expired complete policy metadata, and cover fail-closed mismatches with focused fixtures.
- docs/audit/findings.csv + docs/audit/EXCEPTIONS.md + docs/audit/BLOCKERS.md + docs/audit/CONTROL_TRACEABILITY.md + docs/audit/checklists/RELEASE_EVIDENCE_CHECKLIST.md — reconcile superseded `DD-2026-0016`/`DD-2026-0017` lifecycle drift and close `DD-2026-0018`/`EX-2026-0018` only after current global, linked-runtime/HAL, and outside-component counts are at or below their replay-derived budgets, focused concurrency/bounds/order tests pass, and clean detached-worktree evidence is bound to the immutable remediation commit.
Commands:
- cargo test -p pi4-driver-runtime -- --test-threads=1
- cargo check -p pi4-driver-runtime --target aarch64-unknown-none
- cargo test -p root-task --lib --features driver-tests-pi4 -- --test-threads=1
- cargo test -p pi4-driver-abi
- cargo test -p cargo-build-directive
- cargo test -p rust-risk-audit
- scripts/ci/rust_risk_gate.sh --baseline docs/audit/rust_risk_baseline.toml
- scripts/ci/rust_risk_gate.sh --root <cf8f9ee30-scanner-input-worktree> --historical-replay
- python3 scripts/ci/test_due_diligence_lifecycle.py
- python3 scripts/ci/test_rust_risk_gate.py
- bash scripts/ci/due_diligence_gate.sh --check-exceptions-register docs/audit/findings.csv docs/audit/EXCEPTIONS.md
- cargo fmt --all -- --check
- cargo clippy --workspace --all-targets -- -D warnings
- cargo check --workspace
- cargo test --workspace -- --test-threads=1
- cargo audit
- cargo deny check advisories
- scripts/ci/check_test_plan.sh
- go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12 .github/workflows/*.yml
- scripts/check-generated.sh
- scripts/cohesix-build-run.sh --no-run --cargo-target aarch64-unknown-none
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26d-unsafe-remediation-qemu
- scripts/ci/test_plan_run.sh --target pi4 --stage 1 --state-dir out/test-plan/m26d-unsafe-remediation-pi4
- scripts/ci/test_plan_run.sh --target pi4 --stage 2 --state-dir out/test-plan/m26d-unsafe-remediation-pi4
Checks: scanner v4 replays exact commit `cf8f9ee30` only after raw scanner-input attestation, yielding global `unsafe=693`, `unwrap=38`, `expect=240`, `panic=96`, linked-runtime/HAL `unsafe=146`, `unwrap=0`, `expect=2`, `panic=0`, and outside-component `unsafe=547`, `unwrap=38`, `expect=238`, `panic=96`; immutable remediation-commit ceilings are global `unsafe=691`, `unwrap=38`, `expect=240`, `panic=96`, linked-runtime/HAL `unsafe=144`, `unwrap=0`, `expect=2`, `panic=0`, and outside-component `unsafe=547`, `unwrap=38`, `expect=238`, `panic=96`; every dynamic generated-Rust include has one source/output/generator/hash contract; no active P2 exception remains; shared-state concurrency, mapped-range bounds/alignment, sequence-last publication/consumption, DPC ownership, reciprocal notification, and exception-lifecycle tests pass; offline evidence is not represented as live Pi Wi-Fi proof.
Deliverables: mechanically enforced linked-runtime state ownership, concentrated and documented hardware/ABI boundaries, global/component/outside risk-ratchet evidence, reconciled and closed P2 finding/exception records, and refreshed repository-wide offline gates.
Title/ID: m26d-full-regression-refresh
Goal: Prove the seL4 16 baseline refresh preserves operator-visible behavior and accepted benchmark envelopes across QEMU and Pi 4.
Inputs: refreshed generated artifacts, seL4 16 build trees, docs/TEST_PLAN.md, scripts/ci/test_plan_run.sh, m26d benchmark ledger.
Changes:
- docs/TEST_PLAN.md — update kernel-baseline references only where needed to match the refreshed evidence.
- out/test-plan/m26d-qemu-sel4-16-gap-audit and out/test-plan/m26d-pi4 — fresh target-qualified PASS evidence required on the refreshed baseline; QEMU is build/runtime-gated and the Pi path remains hardware-gated.
Commands:
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26d-qemu-sel4-16-gap-audit
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26d-pi4
Checks: QEMU and Pi 4 staged Test Plan runs are PASS with no undocumented drift, and benchmark revalidation has either recovered the accepted 26b envelope or recorded a scoped blocker/defer decision that downstream milestones cannot count as satisfied evidence.
Deliverables: target-qualified refreshed evidence proving seL4 16 upgrade safety and performance continuity for Cohesix.
Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation
Status: Reopened — only the bounded lease-history view restoration in
m26e-qemu-shared-control-path-performance, discovered during M27g preflight.
The release-owner-approved 1.0.0-beta closure on 2026-09-14 remains historical.
Its Stage 05 decision remains PASS_WITH_RESIDUAL_RISK under the
approved evidence carry-forward
and DD30 release waiver, preserving the
original source/target evidence identities and accepted residual risks.
As-built scope: QEMU and Pi 4 use compiler-declared restricted NineDoor, console/network, Worker and physical-driver runtimes with SMP+MCS temporal authority. Queen policy, HAL admission, authoritative ordering, emergency serial and supervision remain explicit root responsibilities. Heartbeat, GPU-receipt and LoRA-receipt Workers have executable target contracts; GPU/PEFT execution remains host-side. WorkerBus remains model-only. Operational profiles exclude dummy time, fixture hardware/provider state, stub executors and an operational classic-scheduler fallback.
Qualification limits: Completion retains the approved release’s residual risk, carry-forward and source/target limits. DD30’s dynamic fault/wake test was not executed and is not a PASS; its disposition and permitted reuse are governed by the linked audit records. Component, full-system, runtime-release and production-use-case acceptance are distinct. Later production Worker binding cannot be inferred from the completed isolation work.
Evidence: Benchmarks, release audit, the carry-forward/waiver above, and implementation and test history retain qualification decisions, exact artifact identities and failed candidates. The earlier immutable archive retains older provenance. Historical failures remain failures for their original source, target and gate. Runtime contracts are maintained in architecture, drivers, scheduling and interfaces.
Prerequisites
- Milestone 26d complete for the selected QEMU and Pi 4 profiles, including the accepted linked GICv3 QEMU run, exact-image Pi proof, operator-liveness, and benchmark evidence. Static profile PASS alone is insufficient.
- Reopened Milestones 25 and 26c accepted for truth correction: current root-owned services and model-only Workers remain documented honestly until this milestone produces target evidence.
- Milestone 26b is complete for CYW43/SDIO reliability and current-image evidence. No 26e task may rewrite its accepted CYW43 timing, restart, packaging, or proof-classification logic. The 26e Pi component, full-system, and release gates still require the accepted exact-image CYW43 closure and a matching MCS coexistence record.
Goal
Move untrusted namespace parsing, TCP/network parsing, and executable Worker loops into compiler-declared restricted seL4 child tasks; establish the version-pinned MCS ABI and generated temporal-authority contract before those child ABIs freeze; and make exact SMP+MCS builds the sole accepted operational architecture on QEMU and Pi 4 while keeping Queen policy, HAL admission, emergency serial, authoritative ordering, and every existing protocol and operator-visible contract explicit.
Non-negotiable constraints
- No new VM transport, Secure9P verb, namespace root, authority path, or
ACK/ERR/END shape. The one authorized grammar extension is a manifest-gated
loratarget for the existing/queen/ctl/cohsh spawnoperation so the mandatory WorkerLora task can project existing PEFT lifecycle receipts. It requires the normal schema-version, generated grammar, docs, and fixture updates; it does not create a new verb or VM-side PEFT executor. The same change addspeft.exportto the existing generated host-ticket action allowlist beside import/activate/rollback so all four PEFT use cases share one bounded result-to-WorkerLora receipt path; that adds no VM path or transport. Every split uses a bounded compiler-generated internal ABI. - Every child is pure Rust
no_std, separately packaged, W^X-loaded, and given only generated TCB/CSpace/VSpace/IPC-buffer/stack/endpoint/notification/fault authority. There is no ambient root CSpace, catch-all namespace cap, or undeclared shared-memory shortcut. - Queen policy and authoritative mutation ordering remain serialized. Parser and transport children may validate, prepare, and project requests but may not make policy decisions or mutate authoritative state directly.
- HAL remains the only resource-admission path. Physical driver ownership and the fixed driver-task ABI do not move into the namespace or network child.
- Emergency serial and fatal reporting remain root-owned. The TCP child must preserve the sole-listener exception and cannot starve serial/local-seat input or deterministic response flushing.
- The Milestone 26d accepted scheduler remains classic non-MCS only until the atomic 26e transition. Milestone 26e owns the mandatory MCS ABI, generated policy, and exact SMP+MCS target acceptance. Accepted QEMU and Pi 4 operational profiles may not retain a non-MCS scheduler switch, compatibility mode, fallback profile, or runtime branch. If acceptance fails, 26e does not close and the scheduler change set is reverted as a whole.
- Operational kernel contracts remain four-node, one-domain, non-hypervisor AArch64 profiles with MCS enabled. Milestone 26e does not introduce domain scheduling, VCPU/hypervisor support, or a second placement mechanism.
- The root/Queen authority path, emergency serial, fault supervisor, Worker
supervisor, and driver supervisor retain independent active scheduling
contexts and reserved admitted CPU time. A child never receives
SchedControlauthority. - Dedicated active scheduling contexts are the default for asynchronous network ingress, periodic/event-driven Workers, IRQ/DPC work, locality-bound drivers, and authoritative mutation. Passive-server donation is allowed only for compiler-allowlisted, short, synchronous request/reply paths with bounded call depth, explicit Reply-object cardinality, timeout/revoke recovery, and proof that the donated scheduling context always returns. Cross-core donation is prohibited for IRQ- or locality-bound paths unless separately admitted.
- MCS budgets do not replace max-operations, max-bytes, max-completions, queue, backpressure, cancellation, or replay bounds; both kernel temporal authority and application service-turn bounds remain mandatory.
- MCS work may change only the shared driver scheduler/IPC/runtime-init scaffolding needed to make every accepted linked driver execute under MCS. It may not change CYW43/SDIO ownership, protocol state machine, hardware timing, deadlines, retries, recovery order, ring semantics, or error policy. The accepted classic artifact is retained as an immutable behavioral comparator; 26e emits a new MCS driver-runtime hash and reruns exact-image CYW43 coexistence without reclassifying the separate CYW43 proof.
- Every capability, mapping, scheduling context, Reply object, fault route, and kernel object actually used by a 26e service, Worker, or linked driver belongs to a complete 26e instance bundle and teardown/containment path. No live 26e child may depend on Milestone 33 to become safely revocable. Milestone 33 binds these already complete Worker bundles to production ticket/lease ledgers, projects the already complete driver authority inventory into production ledgers, and adds structured quarantine/evidence plus fresh-ticket Worker restart; it does not finish basic Worker or driver isolation, authority, or revocation.
- Static executable configuration and operational acceptance are distinct.
implemented = truemeans a selected manifest has a complete compiler-valid executable task contract; it does not assert that later QEMU or Pi evidence has passed. Release claims require a separate exact-image acceptance record keyed by target, kernel configuration, resolved manifest, root image, MCS driver archive and manifest, CYW43 coexistence record, Worker archive, Worker image manifest, Worker image, role, ABI version, and evidence-pack identity. - Host/model tests, QEMU execution, fresh Pi execution, transport proof, and benchmark evidence remain separate classes.
- Every workspace binary, library surface, feature/profile fallback, generated
namespace, host/provider adapter, example, playbook, proof source, package,
release asset, and tracked README is recorded in one generated implementation
inventory. Implementation class and observed mode are separate. The allowed
classes are
production_live,model_only,host_model,test_fixture,diagnostic,contract_only,not_enabled,deferred, andretired; observed modes remainunknown|missing|disabled|fixture|mock|dry-run|live. Onlyworker-busmay bemodel_onlyin a selected Cohesix profile. An explicit test fixture may remain in source, but no operational build may select it or fall back to it after a live-path error. - Operational QEMU and Pi profiles require generated virtual-counter truth, real serial/emergency output, and typed service/provider state. Dummy or read-count clocks, hard-coded timer-frequency fallback, inert timer bypass, null/no-op serial, compiled spin-stub entrypoints, fabricated host/GPU/model state, client-authored receipts, and synthetic evidence are fatal selection errors rather than degraded operation.
Selected MCS topology
- Root/Queen authoritative mutation, fault/fatal supervision, and emergency serial execute on distinct generated TCBs with distinct active SCs and per-core reserves; assigning several SC records to the current single event pump is invalid. A dedicated Worker-supervisor TCB/SC owns Worker IPC and lifecycle progress, and a separate driver-supervisor TCB/SC owns linked-driver command-Reply recovery, containment anchors, and restart admission, so Queen policy, the fault supervisor, and emergency serial never block on or donate time to a Worker or faulted driver.
- Root-control and root-fault hand work to the Worker supervisor through two separate generated bounded single-producer/single-consumer record sets plus one supervisor-bound wake notification. The supervisor also owns the only Read cap to the Worker telemetry endpoint. Root-control request, root-fault teardown, and per-slot durable-completion signal caps use distinct one-hot bits from a reserved notification-badge range that cannot overlap endpoint identity badges. The supervisor decodes coalesced bitsets, drains every indicated record to its sequence watermark, and returns bounded busy/refusal rather than blocking a critical producer. Fault handoff has one reserved mailbox per admitted child and cannot be dropped.
- Root-fault hands each linked-driver fault to the driver supervisor through a separate per-runtime reserved record plus a driver-supervisor-bound wake notification. The driver supervisor owns the retained origin/recovery caps, per-runtime command-Reply record, and least authority needed to suspend, reply-fail, revoke, contain, and readmit that runtime; it receives no SchedControl or device-policy authority. Worker and driver supervisor badge, record, and notification domains are disjoint.
- Standard and timeout fault send caps share one generated root-fault endpoint
and retain disjoint exact-identity badges. Root-fault owns its sole Read cap
and one Reply object, blocks in
Recv, and resolves class through the sealed registry after receive; noNBRecv/yield poller or second class lane is permitted. For a linked-driver fault, root-fault keeps that Reply association serialized after publishing the containment record and waits on the existing root-fault wake notification. Only the independently scheduled driver supervisor’s exact generated release-badge signal, emitted after command failure and containment release the association, permits another fault receive. The notification carries no fault identity or policy authority. - The critical-TCB fault graph is generated and acyclic: service, Worker, driver, root-control, Worker-supervisor, and driver-supervisor faults route to root-fault; root-fault failure routes to the minimal root-emergency terminal handler; and root-emergency itself has no self/cyclic handler and fails stop if it faults. Faulting a handler can never recurse into the same TCB or strand the only critical scheduling reserve.
- The synchronous NineDoor parser/provider child is steady-state passive and
caller-funded. Manifest
root_task.schema = "1.14"retains one root-retained, one-shot bootstrap SC candidate (8 object bits,3000 us / 10000 us,max_refills = 2) outside the steady temporal topology. After root-fault is active, root must perform the frozenResume -> validated empty Log prepare -> atomic ReplyRecv queued -> unbindtransition before ordinary Calls may donate theroot-controlSC. The child receives no SC or SchedControl cap and noTCB.SetAffinitycall. Its allowed steady donors, Reply objects, call depth, timeout path, and SC return are generated. Any autonomous provider drain uses a separate admitted active SC. The bootstrap candidate remains QEMU-unqualified. - TCP/smoltcp owns an active SC because receive, retransmission, and protocol timers require autonomous progress. A separately isolated pure request parser may be passive only if its donation chain is compiler-validated.
- Serial, USB, and every physical driver runtime retain generated dedicated
active SCs during 26e. The shared driver command/Reply and runtime-init paths
are ported explicitly to the seL4 16 MCS ABI, but passive driver donation and
CYW43/SDIO behavioral changes are prohibited. IRQ/DPC and other autonomous
work is notification-woken and always executes on the active SC bound to the
driver TCB, never to a notification; locality-bound paths may not accept
cross-core donation. Root command caps are exact
Write + GrantReplycapabilities with noGrant; driver receive caps are Read-only. Driver IRQ wait caps are Read-only, root/software signal caps are Write-only, and IRQ, command, completion, and fault badges occupy generated disjoint domains. - Every 26e general Worker uses one small dedicated active SC bound directly to
its TCB.
worker-heartblocks on generated timer/lifecycle wakeups;worker-gpuandworker-lorablock when no receipt or lifecycle work is pending. General Worker IPC uses no SC donation in 26e. The former passive-receipt plus active notification-SC proposal is rejected because it did not define a realizable one-TCB SC receive/return state machine. - Telemetry/persistence drains use capped low-priority active SCs. HDMI draws may be caller-funded; autonomous refresh, if enabled, uses a separate capped background SC.
- Every executable path is classified as active/periodic,
notification-woken, or synchronous caller-funded IPC, with one generated
owner for its time authority. A plain nonblocking send does not imply
donation, and
seL4_NBSendRecvis prohibited from the Worker ABI because it can donate an SC.
Worker execution contract
Required role matrix and capacity
- 26e closure requires at least one executable
worker-heartbeat, one executable receipt-onlyworker-gpu, and one executable receipt-onlyworker-loraon both four-core QEMU and fresh Pi 4.worker-gpureceives no CUDA, NVML, MMIO, DMA, or raw GPU authority; hardware access remains ingpu-bridge-host. worker-loraprojects bounded receipts for the existing PEFT export, import, activate, and rollback lifecycle and/queen/export/lora_jobsreferences. It never trains, imports adapter bytes, loads a model, executes inference, owns a registry, or becomes the PEFT source of truth; those actions remain host-side.- Receipt-bearing GPU and PEFT actions continue to use the existing
/host/tickets/specand/host/tickets/status|deadletterpaths. The generated boundedhost-ticket/v2request adds requiredoperation_id,subject_ref,receipt_worker_role,receipt_worker_id, and opaquereceipt_supervisor_generationandreceipt_cap_generationfields; the matchinghost-ticket-result/v2echoes those fields, adds root-authoritativeresolved_worker_slotandresolved_lease_epoch, and adds a required canonicalresult_digest, defined as SHA-256 over the generated canonical serialization of every result field exceptresult_digestitself. The echoed public binding plus the resolved fields names the same immutable five-part Worker identity used by the supervisor; no host consumer infers slot or epoch from a public id string. Version 1 remains valid for host actions that request no VM Worker receipt, but a receipt-bearing action must use version 2 and unknown, omitted, cross-role, or oversized fields fail closed. The compiler emits accepted request/result schema sets and an(action, receipt_mode) -> required schemamatrix:receipt_mode=noneuses version 1;receipt_mode=workeris permitted only for the three GPU lease and four PEFT actions and requires version 2. Receipt-bearing version 2 is local-hive-only in 26e: federation/relay fields are rejected, while the existing version-1 federated key and relay behavior remain unchanged. Before ticket execution, the host client must explicitly select a matching READY Worker or spawn one through the existing/queen/ctlpath and wait for READY; the ticket agent never chooses a generic or merely configured Worker implicitly. When the version-2 spec is appended, root independently validates READY, resolves the public binding to the exact live(role, slot, logical lease epoch, supervisor generation, cap generation)tuple, and pins that immutable tuple in the admitted ticket record before the host executor may claim it. Caller-supplied bytes never become executable input directly: root’s existing read-only/host/tickets/spec.snapshotprojection emits the canonical admitted version-2 record with an admission sequence, exact validated action args, and root-only resolved slot/lease-epoch fields. The agent claims only that normalized root-owned projection and rejects a raw, unadmitted, missing-sequence, or caller-forged enrichment. Version-1 compatibility remains separately classified and cannot be mistaken for an admitted Worker receipt action. worker-gpuhas one concrete receipt contract for existinggpu.lease.grant,gpu.lease.renew, andgpu.lease.releaseterminal results. Root maps the action code, confirmed/rejected outcome, receipt sequence, exact Worker identity, and SHA-256 digests of the idempotency key, operation id, lease/devicesubject_ref, and canonical result into the fixed-sizeGPU_LEASE_RECEIPTsupervisor record.succeededmaps toconfirmed,failedmaps torejected, andexpiredmaps tostale; nonterminal states produce no Worker completion. WorkerGpu publishes the matching durable completion and boundedworker-gpu-receipt/v1record through/shard/<label>/worker/<id>/telemetry, but never receives a lease credential or GPU cap. Version-2 lease actions never use the current compatibility executor’s implicit/queen/ctlspawn-on-grant or kill-on-release behavior: the host client selects/spawns and waits for the receipt Worker before the ticket, while grant/renew/release map only to the existing lease-control operation (releaseuses the generated release/preempt form). The terminal lease result reaches the still-live Worker before any separately authorized Worker teardown. Version-1 compatibility behavior is classified separately and cannot satisfy this receipt contract.- The generated host-action allowlist adds
peft.exportbeside existingpeft.import,peft.activate, andpeft.rollback. Root maps those four terminal version-2 results through the same fixed digest/identity envelope and thePEFT_RECEIPTlabel; WorkerLora publishes the corresponding durable confirmed/rejected completion and boundedworker-lora-receipt/v1record through/shard/<label>/worker/<id>/telemetry. This is an additive action/schema version on existing paths, not a new VM verb, transport, namespace, or execution plane. - The supervisor retains each immutable terminal receipt result for one
generated bounded idempotency window keyed by role, supervisor generation,
cap generation, ticket-id digest, operation-id digest, and idempotency-key digest.
Same-key/same-result replay for the same still-live Worker returns the same
receipt sequence. Divergent duplicates fail; after Worker teardown the cached
version-2 result remains readable as
stalehost evidence on the existing/host/tickets/status|deadletterprojections and in evidence timelines, but is never republished under a removed Worker path, rebound, or delivered to a new generation. A new Worker requires a newly bound operation. Disconnected/direct-local GPU or PEFT work remains host-only and emits no VM receipt. - For the seven receipt-bearing version-2 actions,
host-ticket-agentholds a local single-agent lock/fence and durably writes a bounded pre-execution journal containing the accepted schema/action, full root-resolved Worker tuple, action fingerprint, idempotency key, and provider fence before any side effect. It persistsprepared,executing, canonical provider result, result-published, and terminal/cursor state in crash-safe order. Recovery never blindly repeats an ambiguous side effect: it uses the action’s generated provider idempotency key or bounded observe/reconcile operation and dead-letters an action whose outcome cannot be established. Crash injection before and after every journal, provider, result, Worker-receipt, and cursor boundary proves same-operation recovery cannot mint a second GPU lease, apply a PEFT transition twice, or deliver divergent Worker receipts. This is narrow local version-2 safety, not exactly-once federation; general version-1 provider durability and relay recovery remain Milestones 27a/27b work. - Only
worker-busremains explicitly model/session-only in 26e. It may not be packaged, markedimplemented = true, or counted toward executable-role closure without a later, separately named BUILD_PLAN task that supplies its target binary, interface contract, and QEMU/Pi evidence. - Namespace/model capacity and executable kernel-object capacity are separate generated bounds. The manifest declares per-role executable slot counts and a maximum simultaneous role mix; generation fails if the worst-case mix exceeds admitted TCB, CNode, VSpace/page-table, ASID, frame, endpoint, notification, fault/timeout, Reply, SC, CSpace-slot, untyped-memory, or per-core CPU budgets. Fault-registry capacity is generated from every admitted TCB, and registration failure is fatal rather than silently ignored.
- Executable slots use compiler-bounded supervisor-owned resource pools. A spawn fails closed when no admitted role slot remains; the much larger namespace model capacity does not imply that the kernel can launch that many tasks.
Worker task ABI v1, identity, and notifications
- A shared
worker-task-abi/v1is versioned, pointer-free, fixed-size, andno_std. Its generated matrix names every endpoint/notification object, holder, CSpace slot, rights mask, permitted syscall, message label, word/frame bound, direction, maximum one in-flight control operation per slot, memory ordering rule, timeout, cancellation, replay, and late-completion outcome.extraCapsis zero and unexpected labels, lengths, caps, sequences, epochs, generations, or child-produced values fail closed. - The ABI is only an internal typed projection of existing mounted namespace/file-and-event semantics. It introduces no host RPC or parallel policy plane: root/NineDoor validates child output, Queen retains policy and authoritative ordering, and no authoritative transaction is held open across Worker IPC.
- Each live instance has an immutable compiler-generated identity tuple
(role, slot, lease_epoch, supervisor_generation, cap_generation). In 26e,lease_epochis logical lifecycle/session metadata used for stale-instance rejection; it is not yet a claim that a production ticket is bound one-to-one to the live cap bundle. Milestone 33 adds that production ledger binding. A Worker-to-supervisor endpoint cap is minted once with a badge that uniquely resolves that tuple; ABI action is carried by a validated message label, never by synthesizing a new badge at send time. Standard-fault and timeout-fault badges also identify the complete tuple and fault class. Hard-coded CPtrs, badge bases, instances, epochs, generations, clocks, or synthetic identities are prohibited. - Badge fields and generations fail closed on overflow. A slot cannot reuse an
identity until admission is closed, every old descendant is revoked, all
mappings, notification state, completion records, and fault/Reply/SC
relationships are gone, and the supervisor proves zero old-generation
activity. Normal Worker IPC has no blocking endpoint send queue to cancel;
generation gates every durable record and droppable
NBSend. Exhausted generation space quarantines the slot until a full reset or a wider generated format is deployed. - Each slot owns a lifecycle notification. Signal-cap badges are distinct
one-hot event bits; the generator rejects zero, overlapping, multi-bit, or
OR-aliasing values. Receivers decode a bitset because seL4 ORs and coalesces
pending signals. Generated precedence is
revoke > shutdown > lease-expired > pressure > timer-wake. - Notifications are wakeups only. Lease epoch, TTL, timestamp, pressure, sequence, generation, and command data live in a bounded generation-stamped control record published with release/acquire ordering. Repeated, combined, coalesced, and missing-signal tests are mandatory.
- Normal Worker ABI v1 control does not use
Send,Call,NBSendRecv, Reply objects, or SC donation. Root publishes one bounded control record and signals the per-slot lifecycle notification. Required READY, operation, and receipt results use a per-slot generation-stamped durable completion record published release/consumed acquire, followed by the slot’s one-hot signal on the supervisor-bound wake notification. Coalescence is safe because only one control operation is in flight per slot and the supervisor drains through the published sequence. The identity-badged output endpoint is Write-only in the Worker and carries only boundedNBSendtelemetry that is explicitly droppable and counted; the supervisor endpoint cap is Read-only, and neither cap hasGrantorGrantReply. - The Worker lifecycle-notification cap is Read-only in the Worker; every supervisor signal cap is Write-only. The Worker active SC is bound only to its TCB, never to a notification. The generator rejects broader rights, wrong-direction caps, notification-bound SCs, overlapping endpoint/ notification badge domains, any normal Worker Reply object, or any blocking Worker send syscall.
- Standard and timeout fault caps installed for a child are exact-identity
badged
Write + GrantReplycaps to one generated root-fault receive endpoint; root-fault holds the only Read cap and supplies its one serialized Reply object to blockingRecvbefore decoding the fault. The registry fixes receive-endpoint and receive-Reply cardinality at one; the Reply cannot be reused while associated. Ordinary Worker faults are terminal: root-fault suspends the TCB, relies on the version-pinned MCS Suspend association-clear contract, never invokes Reply, verifies the Reply is reusable, and signals the reserved supervisor teardown mailbox. A linked driver fault instead retains the association until the driver supervisor has completed faulted-Call failure and containment and signals the exact generated release badge on root-fault’s wake notification. Only a generated allowlisted recoverable timeout may apply its bounded budget/replenishment policy and issue exactly one typed reply; every other timeout is terminal. Success, terminal, recoverable, driver-release, handler-fault, and concurrent-fault tests prove Reply/SC ownership and the acyclic fault graph.
Image, readiness, lifecycle, and teardown
- Worker images build first. The build validates ELF class/machine, entrypoint,
relocation policy, load bounds, W^X segments, stack guard, IPC-buffer
alignment, initial registers/TLS, and content digest before compiling root’s
generated expectations. QEMU and Pi package a deterministic additive
cohesix-worker-images.cpio, including Heartbeat, GPU, and LoRA; it is not appended to or substituted for the CYW43/SDIOcohesix-driver-runtimes.cpioand is bound separately into exact image identity and the< 4 MiBrootfs gate. - A sealed runtime-init descriptor supplies role, slot, epoch, supervisor
generation, cap generation,
image digest, CPtr table, mapped-frame inventory, virtual addresses, SC/core/
budget/period, notification bits, and fault identities. Each target entrypoint
consumes that descriptor and blocks in real seL4 IPC/wait paths; hard-coded
CPtr
1, synthetic time, and busy-spin lifecycle loops do not qualify. - Spawn is transactional:
free -> allocated -> image-verified -> mapped -> configured -> admitted -> resumed -> ready. A successful/queen/ctlwrite acknowledges admission to the bounded supervisor queue, notready; the reserved Worker id may expose a non-authoritative starting state, but namespace and telemetry publication begin only after a valid READY record from the exact role, slot, epoch, supervisor generation, cap generation, and image.ATTACHremains session authority and never creates a task. - Kill, shutdown, fault, and construction failure use one idempotent teardown: close admission; publish and signal generation-stamped shutdown; wait only the generated grace bound; suspend the TCB; clear durable records/notification state; resolve fault Reply state; unbind notification and SC; unmap and invalidate every private/shared frame; revoke every derived endpoint, notification, fault/timeout, Reply, SC, frame, CSpace, and VSpace cap from supervisor-owned anchors; delete final child caps and objects; verify zero old-generation caps, mappings, pending records/signals, Replies, SC bindings, blocking send queues, or execution; then reclaim the slot and advance generation.
- Fresh supervisor-generation recreation repeats full allocation, image verification, configuration, admission, and READY. It never resumes a faulted TCB or reuses stale caps. Milestone 33 later adds fresh-ticket/lease binding; it is not required to make this 26e teardown safe.
Host integration and use-case acceptance contract
Executable Worker tasks are necessary but not sufficient for a usable Cohesix system. The repository already contains real host implementations for CUDA/NVML inventory, direct and REST-backed FUSE, basic systemd/Docker/Kubernetes observation and ticket actions, GPU leases, PEFT file lifecycle, gateway/REST, Python, SwarmUI, federation, evidence, and release tooling. That does not make the complete integration set production-proven: current coverage mixes live adapters with mock/dry-run fixtures; host-ticket PEFT export and live Worker receipt correlation are absent; PEFT transactions and provenance are incomplete; and production provider conformance, identity mapping, deployment profiles, Prometheus/OpenTelemetry, broader industry bridges, NeMo, MCP, and A2A remain later work.
Milestone 26e therefore freezes a compiler-owned
host-integration-dependency/v1 graph before host tools are updated for real
Workers. It is dependency metadata over existing generated paths, actions, and
schemas, not a second provider-action registry or a new authority plane. Every
record names the integration id and implementation owner, host OS/architecture
and deployment profile, dependent Worker roles and documented use cases,
existing namespace/action/schema references, allowed/required modes and observed
unknown, missing, disabled, fixture, mock, dry-run, or live state,
plus explicit unavailable/future ownership, auth/secret-reference posture,
timeouts/retries/cancellation/idempotency/fencing, readiness and degraded-state
semantics, required package/artifact hashes, evidence lane, and owning
milestone. Milestone 27b extends these same records into the complete provider
action and production coexistence registry; it may not create a parallel
catalogue.
Each selected dependency has exactly one acceptance obligation:
role_required: failure prevents the dependent executable Worker role from being accepted. Mock, dry-run, skipped, or inferred readiness never satisfies it.release_required: failure prevents a release from advertising or packaging that host surface, but does not turn a healthy Worker task into a faulted task.use_case_required: failure prevents only the named use case or built-in playbook from being promoted beyond its proven support level.optionalorfuture: the integration must return a deterministicunavailable,not_enabled, orfuture_milestonestate and cannot be used implicitly as acceptance evidence.
The 26e dependency floor separates a live Worker runtime path from the external provider and product projections that later use it:
| Integration family | 26e acceptance obligation | Dependent role or release claim | Later production ownership |
|---|---|---|---|
Direct cohsh control/observation, root Worker supervisor, shared evidence validator, and release verification |
role_required with live QEMU and Pi target modes |
Heartbeat, GPU, and LoRA runtime acceptance | Milestone 33 later binds production ticket/lease ledgers to the already accepted task bundle. |
host-ticket-agent v2 result-to-root-to-Worker receipt path |
role_required with a bounded fixture provider result for each generated GPU and PEFT action; this proves the live VM path, not the external side effect |
WorkerGpu and WorkerLora runtime acceptance | Milestones 27a/27b add crash-safe production execution, writer fencing, and live provider conformance. |
coh, console/direct transport, hive-gateway, REST/OpenAPI, Python, SwarmUI, and the coh-status library/offline fixtures |
release_required compatibility and false-promotion tests; optional projections preserve or lower the source claim and cannot block otherwise valid direct runtime proof |
Packaged host projections of all three roles | Milestone 27a adds delegated multi-caller hardening; 27b adds production identity/read-visibility and deployment profiles; Milestone 40 adds the standalone coh-status CLI. |
gpu-bridge-host, real NVML/CUDA inventory, GPU executor/device-isolation behavior, telemetry, and lease side effects |
use_case_required; 26e proves only all three result labels through the live receipt path and classifies mock/dry-run/live provider availability separately |
GPU Flight Deck and GPU-backed playbooks | Milestone 27b supplies live provider/version/package and external-executor conformance; 27d adds governed inference-provider run contracts, not GPU authority to the VM. |
| PEFT/model-registry export/import/activate/rollback provider transactions, training/evaluation/scanning, runtime reload, and canary health | use_case_required; 26e proves all four action/result shapes through WorkerLora but cannot promote a real PEFT data plane from fixture results |
Model rollout, Private LoRA Foundry, and PEFT-backed playbooks | Milestone 27d owns transactional host lifecycle, provenance, framework/training/evaluation adapters, runtime-reload receipts, and production AI-use-case acceptance. |
coh mount direct and REST FUSE, including Linux FUSE and packaged macOS MacFUSE where advertised |
release_required compatibility for canonical /shard paths and use_case_required for live mounted-namespace workflows; never a Worker readiness source |
Host filesystem clients | Milestone 27b adds live package/deployment conformance and delegated read visibility. |
| systemd, Docker, and Kubernetes status plus the currently generated allowlisted ticket actions | use_case_required; 26e preserves compatibility and classifies the current primitive, but cannot promote action-airlock/self-healing/playbook claims from mocks or basic command adapters |
Agent Action Airlock, Self-Healing Edge Swarm, and selected built-in playbooks | Milestones 27a/27b add delegated identity, writer fencing, live-safe and negative conformance, rollback/fail-safe policy, and packaging before production promotion. |
| Evidence packs/timelines, SIEM NDJSON, CAS/model-artifact refs, and release bundles | release_required schema/projection compatibility; Worker and integration evidence stays distinct from target task evidence and secrets remain redacted |
All release and audit claims | Milestone 27b adds live package conformance, Prometheus/OpenTelemetry, and provider-wide evidence reconstruction. |
| Host-ticket federation and fleet fan-in | use_case_required; version-2 Worker receipts remain local-hive-only in 26e and cannot be relayed or rebound |
Multi-Hive Mission Control | Milestones 27a/27b provide production delegated identity, provider conformance, and deployment posture. |
| MODBUS/DNP3/other sidecars and WorkerBus session/model state | Regression-only in 26e; no provider ready record may parse as executable Worker readiness |
No executable 26e Worker role; WorkerBus remains model-only | Reopened Milestone 18 supplies real MODBUS/DNP3 host protocol I/O and durable acknowledgement; Milestone 27b registers, packages, and proves it while later industry providers remain explicitly unavailable until implemented. |
| Semantic extractors/stores, general CUDA jobs, model training/inference runtime adapters, NeMo, MCP, A2A, Prometheus/OpenTelemetry, and not-yet-built industry providers | future; the matrix must name the owning milestone and reject production claims now |
Use-case-specific host data planes, not the VM Worker task contract | Accepted 27b–27d remain at their qualified scope; selected CUDA/PEFT/Apple/MCP/A2A/NeMo extensions belong to 28a–28f; broader providers, semantics, AI frameworks, inference and namespaces belong to 30/31/34/35/42 under the ownership map. |
The generated graph covers all six scenarios in docs/USE_CASES.md, every
built-in cohesix-playbook id, and every host integration or host-facing binary
advertised by canonical docs or release manifests. A selected role, release
surface, use case, or playbook with an unclassified or unsatisfied transitive
dependency fails generation or promotion. Host availability never promotes a
Worker to READY, and Worker task evidence never promotes an external provider
to live or production-conformant.
Integration evidence uses cohesix-worker-integration-evidence/v1 with
record_kind=worker-integration, exactly one dependency row, and an observed
mode from unknown|missing|disabled|fixture|mock|dry-run|live. Each bounded
record names its target session when applicable, dependency-graph and
selected-manifest hashes, host profile/OS/architecture, component/provider and
package versions, action/observation/receipt outcomes, artifact hashes,
redacted raw-evidence hashes, PASS/FAIL, and blockers. Only exact live
satisfies a row whose required mode is live. QEMU and Pi Worker component
records contain a sorted bounded list of only the exact role-required
integration records they consume; optional projection and later use-case rows
remain separate and cannot block or promote runtime acceptance. The six-record
Worker-runtime release graph remains top-level-stable, but validation
recursively checks its required integration rows and rejects a wrong-mode,
wrong-host, stale, missing, or mismatched dependency. It is not general
use-case release acceptance; Milestone 27b emits that only after joining every
required live provider, authority, package, recovery, and evidence row.
Definition of done
- The selected manifest and generated outputs enumerate every service/Worker image, object, cap, shared frame, bound, fault badge, and revoke rule. Every live TCB also has an MCS scheduling record declaring either a bound active SC or an allowlisted passive donation chain. Active records contain SC object/size, SchedControl core, budget, period, refill/max-refill policy, priority/MCP, timeout/overrun policy, consumed-time evidence, and WCET/admission provenance; passive records contain allowed donor SCs/cores, Reply-object cardinality, timeout/recovery policy, and maximum donation depth. Invalid or incomplete executable-task declarations fail closed.
- Manifest
root_task.schema = "1.14"accounts for the root-retained NineDoor bootstrap SC exactly once, producing aggregate scheduling-context totals of 18 on QEMU and 25 on Pi. It proves the validated empty bootstrap exchange and SC unbind before the child is admitted as passive, without placing an SC or SchedControl cap in the child CSpace or invokingTCB.SetAffinityfor NineDoor. - The exact heartbeat/GPU/LoRA role matrix is executable on both targets; zero-role or host/model-only closure is impossible. Static executable-contract state and exact-target acceptance records remain distinct, and public/release wording never promotes a candidate image from host tests alone.
- Host tools consume one generated Worker state contract with independent
transport/action, declaration, lifecycle, artifact, receipt, and proof axes.
No shared
statusoracceptedboolean may collapse request admission,implemented = true, READY, receipt confirmation, artifact verification, host-model evidence, QEMU evidence, fresh-Pi evidence, or release acceptance. Rust host consumers share one bounded validator; Python and UI consumers use the same generated schemas and conformance vectors. - The generated host-integration dependency graph contains every documented use case, built-in playbook, advertised host surface, and host-facing release binary with no unowned dependency. Heartbeat has a live control/telemetry/ evidence path; GPU has a live three-action result-to-Worker receipt path; and LoRA has a live four-action result-to-Worker receipt path. External CUDA/NVML, PEFT/training/runtime-reload, FUSE, systemd, Docker, Kubernetes, federation, SIEM, sidecar, and optional provider rows retain their independent observed modes and milestone owners. A fixture may prove only the 26e VM receipt path; mock/dry-run/fixture evidence cannot satisfy a later live provider or production use-case row.
- NineDoor parser/provider, TCP/smoltcp, and enabled Worker execution occur in restricted child VSpaces in the required order, with the superseded root implementation path removed or profile-disabled rather than duplicated.
- Injected child faults are attributed to role/slot/epoch/supervisor-generation/ cap-generation, handled by the independent fault-supervisor TCB, and followed by complete bounded instance teardown. Old generations cannot mutate authoritative state, retain a mapping, strand a Reply/SC, or publish late telemetry.
- Four-core QEMU transcripts preserve deterministic authority order and existing protocol fixtures. Fresh Pi proof preserves serial, local-seat, TCP, driver, and fatal-status liveness with boot/image identity.
- The retired 26d classic-SMP baseline, four-core QEMU SMP+MCS, and fresh Pi SMP+MCS remain separate evidence classes. Both operational targets must pass SMP+MCS scheduling, fault, liveness, and performance gates; a boot or throughput win alone is insufficient. Failure blocks 26e and triggers whole-change reversion rather than a shipped fallback.
- Before/after TCB inventory, mapped authority, latency, pressure, and full same-harness benchmark evidence are archived with the atomic change-set and pre-change baseline identities. A split that increases authority, creates duplicate policy, or regresses bounded operator behavior is rejected and reverted as a whole.
Task Breakdown
Title/ID: m26e-mcs-abi-foundation
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / MCS ABI and generated temporal-authority foundation
Goal: Establish the seL4 16 SMP+MCS syscall, object, IPC, profile, and compiler contract and prove it with minimal four-core QEMU and fresh Pi scheduler probes before service-child ABIs freeze.
Inputs: seL4 Reference Manual v16.0.0, tag-pinned seL4 16 headers/caveats, configs/sel4/profiles.toml, crates/sel4-sys/**, crates/sel4-runtime/**, apps/root-task/src/sel4/**, tools/coh-rtc/src/**, selected QEMU/Pi kernel builds, docs/audit/M26D_MCS_DECISION.md.
Changes:
- crates/sel4-sys/** + crates/sel4-runtime/** — add version-pinned SchedContext, SchedControl, Reply, timeout-fault, `Consumed`, `YieldTo`, TCB setup, receive, call, reply, and reply-receive bindings with ABI/negative tests; remove classic reply/scheduling behavior from the QEMU/Pi operational VM closure.
- configs/sel4/profiles.toml + profile tooling — make the four-node QEMU and Pi production/diagnostic runtime contracts MCS-only, validate `KernelIsMCS`, object sizes, cores, and generated headers, and provide no non-MCS runtime-eligible counterpart.
- configs/sel4/profiles.toml + tools/sel4-profile-project/** + scripts/{sel4_profile.py,cohesix-build-run.sh,qemu-run.sh,release_bundle.sh} — restore the canonical macOS QEMU execution envelope to HVF and bind it as generated truth rather than a host heuristic. The QEMU profiles use `virt,gic-version=3,virtualization=off`, QEMU-native PSCI `method = "hvc"`, `cortex-a57`, and the host-visible 24,000,000 Hz virtual-counter frequency; the root console-network descriptor must carry the same frequency. Because upstream seL4 16 rejects HVC for SMP and implements only SMC `CPU_ON`, the wrapper owns a narrow DTB-selected HVC conduit while preserving the upstream SMC path for SMC-selected platforms. The wrapper also applies `-mgeneral-regs-only` to the elfloader-linked `cpio` target before the MMU/FP context exists. The profile validator rejects a mismatched DTB, timer header, CPU, machine, or compile command; it also requires exactly one wrapper dispatch object, exactly one HVC conduit object, no upstream duplicate PSCI driver, and the scalar libcpio compile-edge flag. Explicit TCG remains a claim-ineligible diagnostic comparator; it is not a performance fallback.
- selected seL4 profiles + apps/root-task/src/{arch/aarch64/timer.rs,kernel.rs,userland/mod.rs} — require `KernelArmExportVCNTUser`/`CONFIG_EXPORT_VCNT_USER` and generated `TIMER_CLOCK_HZ` for both operational targets, include the architected-counter backend in `release-qemu` as well as Pi, remove the hard-coded frequency default, and make missing/zero counter truth or timer initialization fatal. `DummySoftTimer`, `bypass-timers`, and `bypass-timers-ipc` remain explicit host/bring-up fixtures only and are rejected from runtime-eligible feature closures and evidence.
- tools/coh-rtc/src/** + generated artifacts — require each live TCB to declare either a bound active scheduling context or a compiler-validated passive donation chain. Active records carry SC object/size, SchedControl core, budget, period, refill/max-refill policy, priority/MCP, timeout/overrun policy, consumed-time evidence, and WCET/admission provenance; passive records carry allowed donor SCs/cores, Reply-object cardinality, timeout policy, and maximum donation depth.
- apps/root-task/src/sel4/** + focused probe child — allocate/bind MCS objects only through BootInfo/untyped authority and prove active execution, passive donation and return, timeout-fault routing, Reply ownership, budget exhaustion/replenishment, consumed time, and four-core SC placement before broad extraction begins.
- docs/ROLES_AND_SCHEDULING.md + docs/TEST_PLAN.md + docs/BENCHMARKS.md + docs/TOOLCHAIN_MAC_ARM64.md — define the selected MCS topology, offline admission calculation, exact accelerator/timer/DTB execution envelope, evidence schema, and explicit whole-change-reversion rule. The compatibility review records no console grammar, Secure9P, `.coh`, Hive REST, `coh`, `cohsh`, SwarmUI, or `tools/cohesix-py` schema change; launch/evidence tooling and performance methodology must consume the corrected profile atomically.
Commands:
- cargo test -p sel4-sys -p sel4-runtime
- cargo test -p coh-rtc
- cargo test -p root-task --test schedule
- python3 scripts/sel4_profile.py validate --profile qemu_smp_production --build-dir out/sel4/profile-v2/qemu-smp-production --require-source --require-artifacts --for-runtime
- python3 scripts/sel4_profile.py validate --profile pi4_production --build-dir out/sel4/profile-v2/pi4-production --require-source --require-artifacts --for-runtime
- scripts/check-generated.sh
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26e-mcs-foundation-qemu
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26e-mcs-foundation-pi4
Checks: both operational contracts are four-node MCS with no runtime-eligible classic profile; each uses the selected build's exported virtual counter and exact generated frequency with no dummy, bypass, read-count, or hard-coded fallback; every active probe TCB has an admitted SC/core/budget/period and every passive probe has an allowlisted donor/Reply/timeout chain; Reply/donation ownership returns on success, timeout, cancellation, and fault; root emergency/fault work retains independent time; a failed QEMU or Pi gate stops 26e and requires atomic source/configuration reversion.
Deliverables: One MCS-only QEMU/Pi scheduling ABI and compiler contract, minimal target evidence, and a stable foundation for every later 26e child.
The QEMU execution-envelope repair above is evidence-bound to the first
systemic failure behind the v6-v23 canaries, not a new leaf split. The exact
V23 root `e3d757a79f2fa186a405e3199d8b62633dbf22fb9c12462341f8344e94c04731`
failed under ordinary wall-clock TCG at moving boundaries across unrelated
owners. The same immutable image under instruction-counted TCG completed AUTH
and the write/read portion of `9p_batch.coh`, proving path reachability but not
acceptance. Its first HVF exception was EC `0x07` at `cpio_get_file+28` on
`ldr q25`, before seL4, because the release libcpio object was auto-vectorized
without `-mgeneral-regs-only`; its generated DTB and 62.5 MHz timer truth were
also TCG-shaped while this Mac exposes a 24 MHz counter under HVF. Conversely,
the historical 0.4 macOS release reached seL4 and root bootstrap under HVF on
this host. The repaired profile must therefore be rebuilt once and pass boot,
AUTH, focused `.coh`, REST core/parity/Python smoke, and Conditional B2's
no-retry exact-three executable QEMU pressure before any QEMU acceptance or
target benchmark claim. Conditional D is a separately retained host-model
gateway comparator and supplies no QEMU or Pi target evidence. Neither
`-icount` nor an artificial CNTFRQ override is admissible evidence.
Title/ID: m26e-production-surface-truth-and-stub-retirement
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / production surface truth and mock-stub retirement
Goal: Inventory every reachable implementation surface, retain useful mocks only as explicit fixtures, and make the selected QEMU/Pi/runtime-release closure free of silent mock, stub, no-op, dummy, synthetic, or placeholder behavior.
Inputs: `m26e-mcs-abi-foundation`, Cargo.toml and all workspace Cargo metadata/targets/features, apps/**, crates/**, tools/**, configs/**, scripts/**, all tracked README/docs/generated snippets, release manifests/assets, current build/package scripts, and the frozen CYW43 source/artifact boundary.
Changes:
- tools/coh-rtc/src/** + configs/implementation_surfaces.toml + configs/generated/implementation_surface_inventory.json — generate and validate `cohesix-implementation-surface-inventory/v1`. Each workspace member, binary, feature/profile, selected entrypoint, namespace seed, provider/action, host adapter, Python/example/playbook, proof source, package/release asset, and public claim has exactly one implementation class, owner, milestone, production reachability, selection source, package disposition, evidence requirement, and current observed mode. Only WorkerBus may be `model_only`; unclassified, duplicate, or production-reachable fixture/stub entries fail generation.
- scripts/ci/check_implementation_surfaces.py + tests — scan source/config/build/release/docs for compiled spin stubs, `Ok(())` no-op provider success, dummy/null/bypass fallbacks, mock/default fixture selection, fabricated identities/state, placeholder credentials/private keys, client-authored proof, and public claims missing an inventory row. The scanner is an inventory/drift guard, not a keyword-only assertion; explicitly registered test fixtures remain legal.
- apps/root-task/src/{kernel.rs,userland/mod.rs,serial/**,console/**,uart/**,trace.rs} — make missing operational serial or real time a fatal profile/construction error; keep emergency serial live; remove/profile-exclude the null serial and dummy/bypass clock from target closures; ensure early help exposes only implemented pre-auth diagnostics; return a typed authorization/unavailable refusal for pre-auth reboot instead of a stub; eliminate duplicate legacy bootstrap entrypoints from selected artifacts; and remove the unused `TraceSink::Ipc` alias unless it is wired to the generated bounded service IPC and proven as such.
- apps/root-task/src/ninedoor.rs + generated host/GPU contracts — operational target state starts `unavailable source=none`, with no predefined units, nodes, temperatures, GPUs, models, lease, or active model. Populate it only from authenticated, versioned, sequence/epoch/time/TTL/manifest-bound host snapshots; atomically replace a provider generation, reject stale/forged snapshots, and withdraw expired data. Explicit dev-virt/mock profiles may retain clearly labelled fixture topology that never produces live evidence.
- apps/gpu-bridge-host/** — live mode requires a validated real registry/CAS source or publishes an explicit empty/unavailable registry; invalid/missing state never installs fixture models or selects the first model as active. Model/source identity, sequence, epoch, observation time, TTL, manifest/CAS/base-adapter compatibility, activation generation, and receipt are explicit. Placeholder auth fails before connection outside explicit fixture mode.
- binary/workspace disposition — stop building or staging the current spinning target `nine-door` binary; the later `nine-door-runtime` child is the only selected target namespace-service image. Make the host NineDoor crate library-only unless 27b supplies a real bounded host-service use case. Remove the unused all-mock `domain-intents` crate from the Cohesix workspace/release (optionally preserving deterministic records under test fixtures) rather than inventing media/finance authority. Label `coh-status` deferred to Milestone 40, not implemented.
- packaging/release gate — replace non-empty-directory and wildcard-copy acceptance with the inventory's exact expected-artifact set for 26e runtime releases; reject unexpected/missing/wrong-kind/wrong-architecture/wrong-hash binaries, compiled stubs, mock-only configuration, placeholder tokens, private fixture signing keys, synthetic proof, and historical assets presented as current. Linux ARM64 host tools and the final Linux tarball are built on one explicitly selected remote ARM64 builder whose host, user, authentication, cargo, build, release, GLIBC ceiling, and local output locations are command-line inputs; release tooling never embeds a site-specific host, user, home, or NVMe path. The exact canonical Pi 4 SD staging file set is compiler-selected and converted into a peer `<release-name>-Pi4` bundle containing a compact raw MBR/FAT32 image, hash, layout/provenance metadata, documentation, and exact bundle manifest. Image size derives from the payload, and the metadata declares the minimum target byte capacity so the image works on any sufficiently large SD card without inheriting a build card's geometry. Packaging remains build proof only and cannot promote media, boot, network, performance, or Pi acceptance. Historical releases remain immutable and receive errata only.
- Release-readiness closure for 1.0.0-beta — bind each host bundle to its native Mac/HVF or Linux/KVM accepted artifact and TCP result; retain source/profile/tool/image identities in BUILD_PROVENANCE.json; include all generated compile-time contracts in remote source transfer; require the executable Conditional G three-archive installation gate, exact Pi raw-image readback and observed fresh provisioning before publication. The complete host suite, target-neutral Python package and benchmark contracts receive the same-change compatibility review recorded in HOST_TOOLS.md. Historical release snapshots are unchanged.
- Release source-identity repair — the staged runner's metadata-only source hash differs from the standalone artifact/factory hash for the same clean commit, rejecting passing native TCP evidence at assembly. Use the existing complete checkout/Git/mode/submodule digest for staged context v2 as well; retain the original metadata fingerprint as a separate source-state binding and bind the shared helper in the action digest. Preserve historical evidence without translation or relabeling. An end-to-end producer/factory regression must accept unchanged source and reject changed bytes or executable modes before fresh qualification; dirty submodule state must still invalidate staged resume.
- Release quickstart — ship the maintained Mac/Linux/Pi guide at every archive root, preserve its first-boot and authentication instructions, and relocate its local documentation links. Include the referenced Pi network-policy runbook; native CLI, Python and benchmark contracts remain unchanged.
- Release 1.0.0-beta publication preparation — update README, status, quickstart, failover and layout guidance, and document changes since v0.9.0-beta. Retain 0.9.0-beta and remove earlier superseded distribution files from the current tree while preserving their original Git tags and the build inputs, fixtures and audit records still required by this release. Review all eight host executables, tools/cohesix-py, generated contracts and performance scripts; this documentation and historical-package cleanup changes no runtime, protocol, policy, scheduling or workload contract. The owner explicitly directs this preparation to reuse qualification from the separate release-qualification task and run no tests. Retain every reused result at its original source/artifact identity; packaging must not create a new target PASS. The owner separately approves an explicit publication-only factory mode: compare two clean commits, reject every runtime or generated-contract change, preserve original qualified artifacts/results and Pi identity, and record the allowed documentation, retired-distribution and factory delta with before/after hashes. Additive publication metadata must be understood by the release collector without promoting the packaging commit to a staged or target PASS. The subsequent owner instruction authorizes fresh canonical builds without tests, explicit build-only factory provenance, completion and push to main, and a v1.0.0-beta lightweight tag following v0.9.0-beta. All built artifacts retain current-source identity and NOT_RUN status; the separate Stage 5 acceptance remains bound to 5be3ca588. The canonical Linux source transfer includes the pinned third_party/fuser Cargo patch so clean native builds retain the working FUSE implementation. Native host tools regenerate the complete selected KVM policy/default set from a full hash-checked Git tree, preventing Mac timer/manifest identities from leaking into the Linux host binaries.
- Release-candidate host validation — restrict Pi handoff ring publication to the bare-metal runtime and its explicit unit-test buffer. Preserve the target publication path and align feature guards with their implementations. Give the Pi host library its compiler-generated Pi tables while retaining the QEMU partition tests in the QEMU suite; select SDIO fixture IRQs by owner rather than global list position. Restore stale sharding, temporal admission, NineDoor timeout, diagnostic counter, CLI grammar, SwarmUI transcript, artifact and toolchain fixtures to the canonical manifests and documented contracts. Align QEMU preflight timers with native Mac HVF and Linux KVM profiles. Bind QEMU Worker GDB fault tests to the current passive Worker ABI v2 and verify all three role bindings against the generated topology; reject old or unknown layouts before debugger attachment. The quarantine defect discovered here is restored under `m26e-driver-runtime-mcs-port-and-cyw43-coexistence` below.
- QEMU release-pressure isolation — allow the canonical clean-build runner to use an explicitly selected disposable Git checkout with `--clean-root`. Preserve its exact-root, output ownership, no-writer, profile, pressure and five-stage acceptance checks; the development checkout's retained output is outside that clean boundary. Exercise hostile path admission in an explicitly selected clean test checkout, independent of the developer's path or uncommitted work. The bench-specific bootpd template test retains the installed host path even when read from a disposable checkout. Queue and verify one single-use `/queen/ctl` approval before each setup spawn/kill over direct TCP or REST, including capacity/model refusal probes and stale-generation recreation. Preserve the control result without retries or a policy bypass.
- Release fleet discovery — restore SwarmUI direct/REST/Secure9P discovery and the executable benchmark census when the real population occupies more than one 64-entry aggregate directory reply. Enumerate only compiler-declared shard addresses and read actual per-shard Workers and structured state. Restore the target aggregate listing to a bounded view of up to 64 distinct active shard labels, consistent with the host model, instead of failing once that view fills. Retain read refusals, placement/identity validation, target buffers, quotas, workloads and thresholds. Record the complete host-suite and Python compatibility review in HOST_TOOLS.md; verify the failing 256-Worker native Jetson scenario before reporting closure.
- Release-candidate compatibility review — reviewed `cohsh`, `coh` (including doctor), `hive-gateway`, `swarmui`, `gpu-bridge-host`, `host-sidecar-bridge`, `cas-tool`, `host-ticket-agent`, `tools/cohesix-py`, raw TCP and REST/Worker benchmark workloads and report schemas. Existing shared 256-shard and bounded timeout contracts require fixture/document synchronization; public commands, credentials, wire ABI, Python APIs, workload definitions and performance thresholds remain unchanged. Native QEMU, Jetson/Pi benchmarks, and Mac SwarmUI direct/gateway multi-Worker checks must retain separate evidence before release construction.
- Provisioned component selection — build Stage 02 console-network images with the selected QEMU `direct-virtio` or canonical Pi `direct-genet` and optimization settings before checking exact root bindings. The normal QEMU production build selects its direct transport independently of optional diagnostic tracing. Keep exact generated page admission and image identity checks; no target budget, protocol, or benchmark threshold changes.
- docs — correct nested crate READMEs and all current docs to distinguish `production_live`, fixture, host-model, diagnostic, deferred, and retired surfaces; current code/package state, not milestone prose, determines the initial row.
Commands:
- cargo test -p coh-rtc implementation_surface
- python3 scripts/ci/check_implementation_surfaces.py --inventory configs/generated/implementation_surface_inventory.json
- cargo test -p root-task --tests production_fallbacks
- cargo test -p gpu-bridge-host
- scripts/cohesix-build-run.sh --clean --no-run --cargo-target aarch64-unknown-none
- scripts/release_bundle.sh --check-manifest --pi4-stage-dir out/pi4-sd --macos-artifact <accepted-mac-artifact.json> --macos-result <accepted-mac-base.json>
- scripts/check-generated.sh
Checks: operational QEMU/Pi feature and package closures contain real time/serial and no null, dummy, bypass, spin-stub, preseeded host/GPU/model state, implicit active model, fixture key/token, client-authored proof, or automatic live-to-mock fallback; expired provider state becomes unavailable; explicit fixtures still pass isolated tests; WorkerBus is the only model-only role; every other non-live surface is fixture/diagnostic/contract/not-enabled/deferred/retired with an exact owner and cannot satisfy target, integration, release, attestation, or use-case evidence; no CYW43 source, timing, state machine, or proof classification changes.
Deliverables: Compiler-owned production-surface inventory, fail-closed operational profiles, truthful target namespace state, exact release selection, and no ambiguous mock/stub functionality.
Title/ID: m26e-worker-resource-admission-critical-tcbs
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / executable-slot admission and critical root TCB reserves
Goal: Prove the complete kernel-object, memory, CSpace, and per-core time budget for every executable slot while creating independent root-control, fault, emergency, Worker-supervisor, and driver-supervisor progress domains.
Inputs: `m26e-mcs-abi-foundation`, `m26e-production-surface-truth-and-stub-retirement`, selected seL4 16 generated headers/object sizes, BootInfo/untyped inventory, apps/root-task/src/hal/**, apps/root-task/src/kernel.rs, apps/root-task/src/sel4/**, tools/coh-rtc/src/**, configs/root_task*.toml, docs/ROLES_AND_SCHEDULING.md, docs/audit/M26D_ROOT_TCB_BOUNDARY_AUDIT.md.
Changes:
- Release critical reservation exhaustion restoration — discovered by `m26e-mcs-smp-target-acceptance` on exact native KVM source `9b1bf2eaa057a268851d068a9b4372f37e692217`. A hardware breakpoint at the emitted seL4 `endTimeslice` timeout branch, before fault IPC, captured the LoRA executor at its blocking Wait with an empty request queue, one published completion, no pending root fault, and no fatal state. Its charged SC retained a 5,196-us head due in 2,000 us and a 2,804-us later refill. Earlier exact-source failures separately identify GPU-executor, Worker-supervisor, and root-fault timeouts; cumulative consumed fields do not establish single-operation WCET or distinguish guest execution from host scheduling delay. Select existing NaturalPostpone for the five resumable critical service loops (root-fault, both supervisors, both executors) in QEMU, regression, and Pi manifests, and reject terminal policy drift in the compiler. Preserve budgets, periods, refills, priorities, core placement, WCET/admission checks, standard-fault endpoints, emergency fail-stop, passive Worker timeout containment, and NineDoor recovery. Keep timeout capabilities reserved and accounted. Review the complete host-tool suite, Python library, and performance scripts: regenerated profile/hash bindings change; public protocols, workloads, thresholds, receipt requirements, and report schemas do not. Require focused generated/fault contracts, exact Mac/KVM/Pi builds, fresh target fault and pressure evidence, and all applicable staged gates before acceptance.
- Pi exact-4c future-anchor collision restoration — image `b24b3eac1794570ba2b0c64b16570e7f92102437a545822d7ff8694faf7909c2` reaches console-network construction with ordinary root slots ending at `0x3f09`, the generated NineDoor anchor. The subsequent exact reservation fails with `seL4_DeleteFirst` before NineDoor construction or the registry seal. Exclude all enabled compiler-declared service, Worker and critical-retention anchors from ordinary allocation from the outset; retain one-time exact claims and rejection of occupied, duplicate, kernel-reserved, out-of-window or previously allocated ordinary slots. Preserve generated slot addresses, resource counts, constructors, revoke ownership, MCS contracts and physical-driver behavior. This restores executable-slot admission after the defect was discovered under `m26e-driver-runtime-mcs-port-and-cyw43-coexistence`; focused allocator contracts, a narrow QEMU activation canary and a fresh exact-image Pi boot are distinct proof requirements.
- Pi exact-4c repeated Worker service scan restoration — ordinary linked-runtime phases repeatedly inspect all 256 projection slots even with no claimed Workers. Maintain a bounded claimed-slot bitmap in the same existing admission/checkpoint transaction and snapshot it after immediate fault/policy work, then enforce every claimed deadline with the unchanged call time and manifest order. Preserve terminal claims, fault-mailbox precedence and QEMU service quantum; skip an empty pending-operation scan only after validating population bounds. This removes source-proven repeated lock/lookup work while the measured 4c GENET raw latency bands and remaining pressure dispatch-to-stage delay remain unassigned to actual SC consumption. Pure set/order/failure-atomicity tests, exact target compilation, QEMU canary and fresh physical performance must remain distinct.
- tools/coh-rtc/src/** + configs/root_task*.toml — separate namespace/model capacity from per-role executable slots; declare allowed role mixes, fixed core placement, TCB/CNode/VSpace/page-table/ASID/frame/endpoint/notification/fault/timeout/Reply/SC/CSpace-slot/untyped costs, budget/period/deadline/refill/priority/MCP/blocking/jitter/WCET inputs, and fail-closed per-core response-time/admission results. The V26-era QEMU root-control repair candidate remains on core 0 with `5500 us / 10000 us`, `5000 us` per-phase WCET, `m26e-qemu-root-disconnect-single-issue-candidate-v26` provenance, and a derived `7600 us` per-phase response bound rather than an end-to-end host/TCP latency claim. Only the QEMU console-network task, matching service config, and SchedControl selection move from core 0 to core 2; its `3000 us / 10000 us` budget and `2400 us` WCET stay fixed while its response becomes `2400 us`; V26-era child provenance was `m26e-qemu-console-peer-close-timewait-relisten-candidate-v13`. The two same-priority core-2 GPU/LoRA Worker responses become `3000 us`; core-0 demand is `8750 us` and core-2 demand is `3800 us`, each within `9000 us` usable after the unchanged `1000 us` reserve. Pi root-control retains V23 provenance, placement, timing, response, and admission truth; its child at that chronology point advanced only to V13 provenance under schema 1.12, with timing and placement unchanged. Root-fault is `3000 us / 10000 us`, with `2400 us` per admitted containment unit, `2600 us` per-unit response, and `m26e-qemu-root-fault-service-units-candidate-v6` provenance. Root-fault V6 preserves `PrimeReceive -> Receive -> Classify`; service records then advance `ResolveService -> SuspendService -> RecoverPassiveService -> PublishService -> Receive`, with active console skipping `RecoverPassiveService`, while the legacy critical branch remains `SuspendCritical -> SignalEmergency -> Receive`. Resolution is one fixed generated lookup plus a nonblocking registry-lock/scalar-snapshot attempt with lossless retry, suspension is one quiet bounded syscall, passive recovery issues at most one Reply while active console issues zero, and publication is one mailbox action that retains its snapshot on backpressure. Terminal-critical and service containment span distinct admitted units, so `2600 us` is not an end-to-end terminal-fault latency claim. Root-fault numerics remain unchanged; V26 retained every V25 timing and placement value and changes only the QEMU root's successful Disconnect transaction from repeatable to per-connection single-issue. The v2 whole-turn interpretation and v3 combined Network/runtime-IPC phase are live-falsified; source `00bf02540` timed out `root-control` at the console-network control poll. Source `4d1a47b89` timed out in `VirtioTxToken::consume` after queue notify, falsifying v4's multi-unit Network turn. The following live v5 run raised child timeout badge `0x26ee0007` at `Send` after `publish_exchange` with exactly `3000 us` consumed, then raised root timeout badge `0x26ee0001` at the sole outer yield after containment/quarantine with exactly `2750 us` consumed, falsifying a multi-material child turn and whole-containment Recovery turn. The canonical v6 root ELF `0059fd675b476106888d6ca62c8bba21f9b340b9aa607e000fbf96997fd29900` then raised root badge `0x26ee0001` at the outer yield after a single Network visit composed empty ObserveChild, no-op StageOutput and Disconnect, and committed/signalled 60-byte ARP ingress sequence 1. The child was healthy and no Recovery ran, so v6 falsifies composition of no-op lower units rather than child or containment progress. None is qualification evidence.
- apps/root-task/src/hal/** + generated records — reserve compiler-bounded per-slot untyped/CSpace pools and supervisor-owned revoke anchors without changing the existing isolated driver-runtime constructor or allocator contract. On the QEMU VirtIO profile, the ordinary root-control phase also suppresses the Pi/GENET-only synchronous raw-UART idle-input trace in live and quarantined adapter states; the pre-gate v3 run exhausted at the following outer yield after emitting that complete nonessential line.
- apps/root-task/src/kernel.rs + apps/root-task/src/sel4/** — create distinct `root-control`, `root-fault`, `root-emergency`, `root-worker-supervisor`, and `root-driver-supervisor` TCBs with distinct active SCs and least-authority CSpace views; no reserve is a Worker or driver donor.
- apps/root-task/src/kernel.rs + tools/coh-rtc/src/** — generate the bounded root-control-to-Worker-supervisor queue, per-admitted-Worker root-fault teardown mailboxes, Worker-supervisor wake notification, per-runtime root-fault-to-driver-supervisor records, driver-supervisor wake notification, reserved disjoint notification-badge ranges, exact Read/Write rights, one-hot signal caps, backpressure/refusal policy, and coalesced drain precedence. Critical producers never block on a supervisor and fault handoff cannot be dropped.
- apps/root-task/src/sel4/** + tools/coh-rtc/src/** — generate one acyclic critical-TCB fault graph and exactly one blocking MCS fault receive endpoint with one serialized Reply: standard and timeout child fault caps are disjointly badged `Write + GrantReply` caps to that endpoint, root-fault's receive cap is Read-only, ordinary Worker faults suspend/terminate without Reply, only allowlisted timeout faults may reply once, and linked-driver faults retain the association while root-fault waits for the independent driver supervisor's exact release-badge notification after command-Reply failure and containment; root-fault failure routes to root-emergency, and root-emergency failure is fail-stop rather than self/cyclic recovery.
- apps/root-task/src/kernel.rs + tools/coh-rtc/src/** — size the fault registry from every admitted service, Worker, driver, and critical root TCB and propagate duplicate/overflow registration as a fatal construction error.
- docs/ROLES_AND_SCHEDULING.md + docs/TEST_PLAN.md — publish executable-slot/resource arithmetic, per-core reserves, response-time inputs, and allocation-failure gates separately from model capacity.
Commands:
- cargo test -p coh-rtc worker_admission
- cargo test -p root-task --test worker_resource_admission
- cargo test -p root-task --test worker_fault_registry
- cargo test -p root-task --test critical_tcb_reserves
- cargo test -p root-task --test critical_tcb_handoff
- cargo test -p root-task --test driver_supervisor_handoff
- cargo test -p root-task --test mcs_fault_lanes
- scripts/check-generated.sh
Checks: the maximum generated role mix fits exact selected-kernel object/untyped/CSpace/page and per-core time bounds; every critical duty runs on the named TCB/SC; Worker and driver handoff queues, mailboxes, badge ranges, cap rights, Reply cardinality, terminal/recoverable fault transitions, and the acyclic fault graph match generated truth under coalescence, saturation, simultaneous faults, handler fault, and allocation failure; no registration or construction error is ignored; model capacity cannot overcommit executable slots. This admission task does not edit driver-runtime or CYW43 behavior; the following driver-port task owns the required MCS rebuild.
Deliverables: Compiler-proven executable resource pools, generated fault capacity, and independent temporal reserves required before any 26e child is trusted to run.
Title/ID: m26e-driver-runtime-mcs-port-and-cyw43-coexistence
Status: Reopened narrowly — M27g / m27g-assembled-journeys-and-recovery found that long driver proof records become blank in the bounded Queen log, early constructor affinity records expire before export, and the descriptor checker still selects an obsolete ABI. Restore complete bounded receipt retention, preserve original constructor identity in the existing trusted boot reserve, and align fail-closed decoding with the current ABI; fresh exact-image physical proof remains required.
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / linked-driver MCS port and behavioral coexistence proof
Goal: Replace the current MCS driver stubs with the real seL4 16 MCS command, Reply, notification, fault, active-SC, and faulted-call recovery paths for every linked Pi driver while preserving CYW43/SDIO behavior and re-proving it under the new binary identity.
Inputs: `m26e-mcs-abi-foundation`, `m26e-worker-resource-admission-critical-tcbs`, crates/pi4-driver-abi/**, apps/pi4-driver-runtime/**, apps/root-task/src/kernel.rs, apps/root-task/src/hal/driver_task.rs, apps/root-task/src/sel4/**, tools/coh-rtc/src/**, configs/root_task_pi4_uboot_aarch64.toml, scripts/cohesix-build-run.sh, scripts/pi4-image-build.sh, scripts/pi4_gate_proof.sh, the accepted classic driver archive/hash and exact CYW43 evidence, and selected QEMU/Pi MCS generated headers.
Changes:
- Every linked Serial, USB, HDMI, GENET, CYW43, SDIO and PCIe runtime has a compiler-admitted active SC, core, command endpoint, exact command Reply, notifications and containment identity. MCS command receives use Recv/NBRecv with the declared Reply; the SC remains bound to the TCB. Drivers receive neither SchedControl nor ticket authority.
- Root-driver-supervisor solely owns driver containment and command-Reply recovery. Root-fault publishes the separate fault record and holds its serialized fault Reply until the supervisor closes the exact command/recovery generation. Construction, call failure, teardown and recreation retain bounded cap, mapping, Reply and SC ownership.
- Syscall wrappers use borrowed badge outputs, kernel-only child binding and private fast registers or the explicitly borrowed active IPC buffer. Restricted TCB waits and error cleanup cannot write the process-global root IPC pointer. Checked HAL windows and typed peer handoffs preserve volatile/publication order without duplicate raw-access boundaries.
- PCIe admission requires complete endpoint/firmware owner proof, revokes it before reset or failure and measures hardware settling with the selected virtual counter. Local-seat profiles complete PCIe-to-USB owner publication before deferred Wi-Fi service. No partial link/MSI flags or CPU-spin timing substitute for admission.
- Runtime continuation uses generated policy and durable identity. The ABI v13 DROW/DROA handshake binds request, action, generation and strictly-next wait slice; exact acknowledgement permits one continuation. Duplicate, skipped, stale, torn or mismatched records grant none. CYW43/SDIO retain their accepted source-yield, physical issue, retry, recovery and pair-restart contracts.
- Serial uses two generation-bound, two-page 8,128-byte SPSC rings. CPU-only shared/control pages use matching coherent Normal/XN aliases and acquire/release publication; DMA, MMIO and framebuffer attributes remain separately admitted. Cursor wrap, rearm and both final wake races are bounded. Terminal serial poison retires only affected output and preserves other operator paths without root UART takeover.
- HDMI keeps child-private terminal cells, a logical row ring and bounded dirty raster work; parse, clear, scroll, tab and raster turns remain capped at 1,280 operations. Boot framebuffer absence makes display work non-runnable. Startup takeover and bounded progress reporting preserve child-exclusive framebuffer authority and physical input priority.
- GENET's direct path is a generated CPU-ring connection between the sole NIC owner and console child after bounded DHCP/cutover admission. Root remains control/lease owner and cannot reclaim physical service. Exact generation, quiesce, cursor and failure fences prevent dual ownership; direct RX and ACK progress survive retained response/control debt.
- Wi-Fi preserves durable foreground publication, finite child/credit waits, exact RX queue/ACK watermarks and recovery identity. Root/child scheduling repairs do not change accepted register/wire order, retry ceilings, timing source, IRQ policy or evidence classes. New driver archives retain exact QEMU/Pi hashes and an immutable classic comparator.
- Partial serial input does not exclude authenticated TCP; complete queued input/parser work retains its priority. Quarantined network adapters cannot be inspected for response progress. Serial, USB, HDMI, network and independent emergency/fault service retain bounded liveness under load and failure.
- MCS/driver diagnostics are bounded passive projections of current and retained lifetime records. Complete CPU/consumption, wake, idle-fence, queue and stage receipts distinguish elapsed time from the owner actually consuming CPU; diagnostics cannot schedule work or qualify performance.
- Host-tool, Python SDK, CLI/REST/UI, generated-profile and benchmark compatibility retains authority, public grammar and workload semantics; versioned driver/diagnostic consumers change atomically with the producer. Build, source, QEMU and image-readback checks do not prove Pi transport, latency or repeatability.
- Release 1.0.0-beta closure retains the exact DD30 and carry-forward decisions linked above. DD30's dynamic fault/wake test remains unexecuted; permitted source, release, expiry and later retirement disposition come from the canonical audit records. Carry-forward preserves original Stage 01–04 identities and the failed fresh attempt; it cannot create replacement markers or relax ordinary resume rules. All other findings and target obligations remain mandatory.
Commands:
- cargo test -p pi4-driver-abi -p pi4-driver-runtime
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib pi_attached_wifi_continuation_requires_one_productive_network_successor
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib linked_cyw43_rx_admission_honors_input_and_clears_on_guards
- cargo test -p console-network-abi
- cargo test -p root-task --tests driver_task
- cargo test -p root-task --test driver_task_mcs
- cargo test -p root-task --test driver_faulted_call_recovery
- cargo test -p root-task --test mcs_activation_order
- cargo test -p root-task --test direct_genet_network_phasing
- cargo test -p cohsh --features tcp --test tcp_cli_script
- python3 -m pytest -q tests/test_pi4_trace_normalize.py
- cargo test -p coh-rtc --test pi4_profile
- cargo test -p coh-rtc --test python_profile
- cargo test -p coh-rtc resource_admission
- .venv/bin/python -m pytest -q tools/cohesix-py/tests
- cargo build --locked --release --target aarch64-unknown-none -p pi4-driver-runtime
- scripts/cohesix-build-run.sh --clean --no-run --cargo-target aarch64-unknown-none
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml --clean
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26e-driver-mcs-qemu
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26e-driver-mcs-pi4
- scripts/check-generated.sh
Checks: focused regressions prove exact two-by-two-page/8,128-byte serial SPSC layout, coherent cacheable Normal-memory mappings only for compiler-declared CPU rings, uncached DMA/MMIO retention, generation and cursor rejection, wrap/order isolation, both final wake-race rechecks, and pending UART IRQ-ACK continuation after full-ring drain; every HDMI parse, multi-cell clear/scroll/tab, and raster turn remains at or below 1,280 operations with no replay, an aligned tab advances eight cells, and only the final visible raster completes; SDIO bulk copies match bytewise truth at every source/destination alignment and reject zero-page, overflow, range, and discontinuity violations without altering the pre-scrub discriminator; Pi profile generation requires only IRQ 189/badge 1024 for GENET default queue 16, while QEMU retains exactly three driver-runtime IRQ entries and no GENET IRQ; GENET queue/DPC tests prove the 16-frame/24,576-byte quantum, overflow preservation, bounded control/data fairness, exact badge, store-completion/unmask readback, final source/ring recheck, and durable continuation before handler acknowledgement. Direct GENET tests prove the exact CPU-only 32-page split, no DMA/device-visible/paddr authority, reciprocal least-right notifications, generation and handoff identity, sequence-last publication, final sleep-race rechecks, corruption poison, one-way root mediation cut, and complete external-frame teardown. Direct-diagnostic tests additionally prove the `[320,512)` optional diagnostic-v3 record, record-relative commit 184, stable exact-generation read, still-reserved `[512,4096)` tail, raw notification receipts/rejections/32-bit badge union counted exactly once before filtering with no service authority, eleven ordered nontruncating rows, one-shot causal replay, legacy-normalizer compatibility, and no traffic or acceptance authority. Deferred WiFi tests prove exact bound DHCP selects one exclusive handoff turn before readiness evaluation, while retained-grant tests prove max-three pure bookkeeping, Service/Empty/Inactive/Ready and ACK-failure behavior, one physical quantum, and unchanged postphysical boundaries. Every linked runtime reaches real MCS Recv/service/Reply or IRQ/notification progress with the generated TCB-bound active SC/core and no unsupported stub; exact endpoint/notification rights and disjoint badge domains match generated truth; installed terminal policies retain timeout-fault coverage, while each selected Pi natural-postpone runtime proves current-refill exhaustion postponement plus explicit device-deadline and standard-fault containment; synchronous, one-way, IRQ/DPC, fault-before/during/after-command, caller-cancellation, restart, and command-versus-fault Reply tests return one normal or typed-failure result, preserve ownership, and leave no blocked caller, SC, Reply association, stale recovery cap, old-generation authority, or root packet fallback; the new archive differs only within the authorized shared MCS scheduler/IPC/runtime-init surface; normalized CYW43/SDIO traces, constants, ordering, timing, retries, rings, error outcomes, DHCP/raw TCP/cohsh behavior, and operator-liveness gates match the accepted contract on the new exact Pi image; an accepted CYW43 blocker permits preparatory work only and cannot produce this task's Pi PASS; classic comparator, new MCS driver, Worker, QEMU, Pi, and CYW43 evidence remain distinct.
Deliverables: Real active-SC MCS linked drivers, a newly hash-bound driver archive, immutable classic comparison evidence, and exact-image CYW43 coexistence proof with no behavioral rewrite.
Title/ID: m26e-ninedoor-service-isolation
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / NineDoor parser-provider isolation
Goal: Move untrusted target namespace parsing and provider projection behind a bounded restricted seL4 child without moving Queen policy authority.
Inputs: `m26e-mcs-abi-foundation`, `m26e-production-surface-truth-and-stub-retirement`, `m26e-worker-resource-admission-critical-tcbs`, `m26e-driver-runtime-mcs-port-and-cyw43-coexistence`, apps/root-task/src/ninedoor.rs, apps/root-task/src/event/**, apps/root-task/src/console/**, apps/nine-door/src/**, crates/secure9p-transport/**, tools/coh-rtc/src/**, configs/root_task*.toml, scripts/worker_task_evidence.py, scripts/m26e_qemu_pressure.sh, docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/SECURITY.md.
Changes:
- Release-candidate recovered-Call containment ordering — discovered by `m26e-mcs-smp-target-acceptance`: a RecoveryFault reply can return before root-fault publishes the durable service record. Keep each Recovery turn bounded and yield while that promised record is absent; consume it before teardown instead of treating the recovered standard fault as a manual revoke and abandoning its mailbox generation. The same ordering applies to terminal RecoveryTimeout; ordinary local transport revocation remains immediate. Test the stage contract and repeat exact QEMU fault/revoke evidence plus both affected target builds. Review coh/cohsh, SwarmUI, gateway, host bridges/agent, CAS, Python and benchmark surfaces: no public grammar, provider operation, generated contract or report-schema changes are needed.
- Pi exact-1c5165 bounded passive timeout restoration — the unchanged
two-WiFi/two-GENET matrix captures a donated root-control timeout during
G00 medium16 discovery, with badge `0x26ee0001` and resettable SC consumed
accounting of 121 us. Yield retires the current head, so elapsed time
after Yield cannot prove a full reservation. Schema 1.17 introduces
`resume-once-return-error` only for the exact local passive NineDoor
donation contract. Root-fault resumes the first well-formed timeout of
each armed Call with a zero-label, zero-length kernel Reply. It preserves
the original request and donated SC; a second timeout, wrong donor,
malformed payload, or standard fault retains typed terminal containment.
QEMU keeps `return-error`. This is a candidate restoration, requiring
exact target build and fresh physical pressure evidence.
- Cross-surface review for the same candidate covers coh, cohsh, SwarmUI,
Hive Gateway, host-side bridge/provider tools, tools/cohesix-py, all .coh
scripts, and the raw/REST/pressure benchmark entry points. Their command,
namespace, authority, request, timeout, retry, workload and report
contracts remain unchanged. Compiler-owned policy, Python profiles and
schema fixtures regenerate together. The Pi trace normalizer gains the
passive timeout receipt; USERLAND_AND_CLI documents that row and the
expanded CPU-owner rows. Host adapters need no hand-authored change.
- Pi exact-fabc fault operand retention — the same unchanged four-boot matrix captures a NineDoor Timeout during G00 high32 discovery at LS /shard/dd/worker, followed by terminal teardown and refused later ATTACH/reboot admissions. G01 completes the same workload, so functional repeatability remains open. Retain the kernel fault label, exact length and two message registers already copied into the bounded fault mailbox, and render them after the existing diagnostic prefix in the ordinary output turn. No extra syscall, admission policy, restart, retry, timeout, budget or teardown change is authorized by this retention repair. Test maximum-width exact rendering and host evidence-prefix compatibility; interpret Timeout Data/Consumed only against the selected kernel ABI, without calling it remaining refill budget or per-call CPU cost.
- tools/coh-rtc/src/** + configs/root_task*.toml — under selected `root_task.schema = "1.14"`, retain the compiler-owned NineDoor service-image, TCB, CSpace, VSpace, IPC-buffer, stack, endpoint, shared-frame, MCS Reply/donation/timeout, fault-badge, revoke records, one root-retained one-shot bootstrap SC (8 object bits, `3000 us / 10000 us`, `max_refills = 2`), and the profile-scoped root VirtIO Operator serial-I/O bound introduced by schema 1.11. Account for that fixed SC exactly once so aggregate QEMU/Pi SC totals are 18/25; schema 1.14 retains the console publication-ACK and ABI v3 SendBatch/response-lane contracts and owns `NaturalPostpone` for the active console child and the selected QEMU V35/Pi V24 root-control records, without changing NineDoor resources.
- apps/nine-door-runtime/** — add a pure-Rust `no_std` child image that parses bounded namespace requests, returns typed prepared operations over the generated internal ABI, receives once for bootstrap, and uses atomic `seL4_ReplyRecv` for every reply-and-next-receive transition.
- crates/secure9p-transport/** — replace the empty scaffold with the bounded transport-neutral request/response, partial-frame, close, backpressure, and cancellation traits actually consumed by the in-process host adapter and the generated seL4 endpoint/shared-frame adapter. It provides no target TCP listener. Migrate named consumers and prove revoke/short-frame/queue-full behavior; if the final child ABI cannot use this layer without duplicating semantics, remove the crate and its public claim atomically instead of retaining contract-only scaffolding.
- apps/nine-door/src/{main.rs,kernel.rs,lib.rs} + scripts/cohesix-build-run.sh — remove/profile-exclude the host print-and-exit and target spin-loop binaries from selected packages; stage `nine-door-runtime` under its generated image identity. Keep `apps/nine-door` as the host library/fixture provider unless a later registered host-service use case owns a real executable.
- apps/root-task/src/ninedoor.rs + apps/root-task/src/event/** — retain policy and authoritative mutation in root, replace in-root untrusted parsing for enabled profiles with bounded child IPC, and delete/profile-disable the duplicate parser path. Configure and bind only the root-retained bootstrap SC while the child is suspended and before registry seal; after root-fault activation perform `Resume -> validated empty Log prepare -> atomic ReplyRecv queued -> unbind -> steady passive donation`. Install no SC or SchedControl cap in the child, issue no NineDoor `TCB.SetAffinity`, and revoke the boundary on activation, probe, or unbind failure while suspending where possible.
- apps/root-task/src/{ninedoor.rs,ninedoor_service.rs,event/**,hal/ninedoor_service.rs} + focused root-task tests — make terminal NineDoor containment resumable on the common MCS QEMU/Pi root-control path. The first exclusive Recovery turn only consumes the durable fault record, fences new Calls, retains the four mappings, initializes `SuspendTcb`, and returns `InProgress`. Later turns execute exactly one of 18 successor-committed units: `SuspendTcb`; request 0 `ScrubCleanRequestFrame`, `UnmapRequestFrame`; request 1 `ScrubCleanRequestFrame`, `UnmapRequestFrame`; response 0 `UnmapResponseRead`, `MapResponseWritable`, `ScrubCleanResponseWritable`, `UnmapResponseWritable`; response 1 with the same four units; `RevokeRecoveryReply`; `DeleteFaultCap(0)`; `DeleteFaultCap(1)`; `RevokeAnchor`; and pure `Finalize`. Scrub/clean uses the bounded lock-free cache path, each response `MapResponseWritable` performs exactly one `Page_Map`, and Reply/fault-cap deletion uses quiet bounded kernel operations. Every material unit exposes its successor before work and restores only that exact selected unit after a synchronous error. `Finalize` advances to `Complete` without removal; the next idempotent `Complete` turn publishes the five-field proof, and only that complete proof permits the old runtime record to be removed. `InProgress`, an incomplete proof, and every error fence the ordinary EventPump for the complete refill. This changes common MCS containment behavior, not ordinary Pi scheduling; fresh Pi containment evidence remains pending, and no QEMU result may substitute for it. Preserve schema, provenance, generated artifacts, capabilities, temporal numerics, and all external NineDoor semantics.
- scripts/worker_task_evidence.py + scripts/m26e_qemu_pressure.sh — require one prior exact-artifact non-claiming `ninedoor` convergence PASS with a live authenticated-cohsh UART record, then run the donated-Call standard fault and root-local between-Calls transport revoke in distinct fresh terminal-service boots. Bind the exact emitted four-file target-session bundle, launch record/artifact bytes, observation/UART bytes, service ELF, and root ELF. The between-Calls hook may only request local boundary revoke after two successful post-prepare hits; it adds no command grammar, target authority, child fault, or replacement path. Collect the two NineDoor UART/GDB pairs separately so no same-boot reconstruction or fabricated between-Calls standard fault can satisfy the gate. For console-network, collect a fresh standard-fault terminal-containment boot and a distinct budget-exhaustion natural-postponement liveness/isolation boot; V18 retains V17's timeout contract and does not install or expect a console Timeout teardown.
- compatibility review — `apps/cohsh/**`, `apps/coh/**`, `.coh` scripts, `apps/hive-gateway/**`, `tools/cohesix-py/**`, and the REST/performance harnesses retain their command grammar, ACK/ERR/END behavior, namespace and authority contracts, retry/timeout policy, workloads, evidence records, and report schemas. The bounded containment cursor is internal target recovery behavior and requires no host, script, Hive Gateway, Python, or performance-schema implementation change. Existing target regressions must still be rerun against the new exact image after QEMU containment qualifies; fresh Pi containment proof remains separate.
- docs/ARCHITECTURE.md + docs/ROLES_AND_SCHEDULING.md + docs/TEST_PLAN.md + docs/BUILD_PLAN.md + docs/INTERFACES.md + docs/SECURITY.md — document the target child separately from host NineDoor, the frozen bootstrap/passive transition, and the no in-VM 9P/TCP-listener rule.
Commands:
- cargo test -p coh-rtc
- cargo test -p root-task --tests ninedoor
- cargo test -p nine-door
- cargo check -p nine-door-runtime --target aarch64-unknown-none
- .venv/bin/python -m pytest -q tests/test_worker_task_evidence.py
- bash -n scripts/m26e_qemu_pressure.sh
- scripts/check-generated.sh
Checks: selected schema 1.14, including rejection of immediate predecessor 1.13, the profile-scoped serial-I/O bound, and any bootstrap-candidate drift fail closed; the exact root-retained SC is accounted once and raises QEMU/Pi SC totals to 18/25; source tests prove construction-time configure/bind while suspended before seal, one initial `seL4_Recv`, validated empty `Log` preparation, atomic `seL4_ReplyRecv` queueing, unbind before passive admission, repeated calls, and boundary revoke plus suspension where possible on activation/probe/unbind failure. Recovery tests prove the latch-only first turn; the exact 18-unit order and count; one unit per later refill; successor-before-action; exact-unit restoration on synchronous failure; bounded lock-free cache cleaning; one `Page_Map` per response remap; quiet Reply/fault-cap deletion; pure `Finalize`; the distinct idempotent `Complete` proof/removal turn; and zero ordinary EventPump work on `InProgress`, incomplete proof, or error. Malformed and over-limit requests are contained in the child; root receives only typed bounded operations; the passive donor/Reply/timeout chain returns its SC on success, denial, timeout, cancellation, and child fault; partial-frame, backpressure, close, and revoke behavior passes through the real shared transport boundary; the selected archive contains `nine-door-runtime` and no print-and-exit/spin stub; namespace, Secure9P, console, replay, error, host-tool, `.coh`, Hive Gateway, Python, and performance schemas do not drift; no broad namespace, target TCP listener, child SC/SchedControl cap, NineDoor `TCB.SetAffinity`, or root CSpace authority reaches the child. Four-core GICv3 QEMU must first pass one exact-artifact authenticated `ninedoor` convergence boot, then use separate fresh boots for a live standard fault during a donated Call and a root-local transport revoke after two completed Calls. The latter must begin with no outstanding Reply association and cannot be labeled a child standard fault. Both paths must complete every bounded containment turn without root-control timeout or pump fallthrough; exact artifact/session/observation hashes and bytes must match. The common MCS source applies to QEMU and Pi, but ordinary Pi scheduling is unchanged and fresh Pi containment evidence remains pending. A marker, successful boot, or QEMU result alone does not satisfy the Pi gate.
Deliverables: Executable target namespace service with generated least-authority objects, bounded IPC, fault containment, and unchanged external semantics.
Title/ID: m26e-console-network-service-isolation
Status: Reopened narrowly — M27g / m27g-assembled-journeys-and-recovery found that a physical PING can defer its prompt behind an unrelated TCP stream, leaving physical response priority to starve that stream and HDMI. Restore source-owned prompt completion without changing scheduling bounds, response authority or display rendering; require a deterministic ownership regression and fresh mixed-surface Pi evidence.
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / TCP console-network isolation
Goal: Move TCP framing, authentication parsing, and smoltcp packet handling into a restricted child while preserving root-owned operator policy and emergency surfaces.
Inputs: `m26e-mcs-abi-foundation`, `m26e-worker-resource-admission-critical-tcbs`, `m26e-driver-runtime-mcs-port-and-cyw43-coexistence`, `m26e-ninedoor-service-isolation`, crates/console-network-abi/**, apps/root-task/src/console_network_service.rs, apps/root-task/src/net/**, apps/root-task/src/console/**, apps/root-task/src/event/**, apps/root-task/src/serial/**, apps/root-task/src/hal/**, tools/coh-rtc/src/**, configs/generated/cohsh_policy.toml, scripts/cohsh/run_regression_batch.sh, scripts/ci/test_run_regression_batch.py, docs/ARCHITECTURE.md, docs/ROLES_AND_SCHEDULING.md, docs/SECURITY.md, docs/USERLAND_AND_CLI.md, docs/TEST_PLAN.md.
Changes:
- The generated console/network child owns TCP framing, authentication parsing and smoltcp packet handling in a restricted address space. Root retains sole-listener admission, Queen policy, authoritative response ordering, emergency serial and fatal output. The child receives only the declared pages, caps, SC, Reply and fault/lifecycle channels.
- Four fixed 4,096-byte exchange pages use compact scalar headers and active payload, commit-last publication and exact generation/connection/control sequence. Root-to-child pages are read-only in the child; child-to-root pages have only declared write authority. One-slot publication ACK credit is explicit: ordinary notifications cannot mint credit, overwrite pending publication or complete a control.
- Root privately validates and retains a complete publication before acknowledging it. The child services retained completion/event/egress work before new ingress/control, rechecks badges and credit between bounded units, polls only eligible private work and waits when idle or uncredited. Selected NaturalPostpone policy enforces the admitted 3,000-us/10,000-us child budget without treating ordinary exhaustion as terminal failure.
- Root activation, compact Operator/Runtime/Network phases and their retained cursors separate command dispatch, runtime IPC and NIC service. Recovery has precedence and advances one material containment unit per bounded turn. Console quarantine fences only its owned network work; it does not combine phases or starve physical input, NineDoor or independent root reserves.
- The isolated VirtIO Operator shares one generated 64-byte serial credit across RX/TX; entry TX backlog reserves 32 bytes. It attempts at most one retained output record, while Pi/non-VirtIO retain their own bounds. Compact Runtime and Network cursors commit successors before work and preserve no-op, forced-observe, retained egress and deferred-diagnostic state.
- Connection identity survives every control read and completion. Well-formed stale controls retire once without touching replacement-session output; malformed or unauthenticated current controls fail closed. Peer-first close, TIME_WAIT relisten, terminal-response Disconnect fencing and failed stream-producer retirement preserve exactly one listener and complete bounded ACK/ERR/END behavior.
- Binary SendBatch retains complete-record encoding inside the existing 2,368-byte payload; later CommandBatch retains per-command timestamps and exact FIFO ownership. The bounded authenticated response lane preserves ordinary-service debt, operator/recovery fences and exact consumed-but-undrained control identity. Synchronous capture uses the selected adapter's real identity and bounded storage.
- Stack ingress, egress and Session service are separately bounded. Nonzero receive or committed wire progress retains service; only zero receive with no commit quiesces. Authenticated oversize input drains exactly its declared body. Sending requires can_send and complete-frame capacity; backpressure never fabricates completion or discards a retained frame.
- Routine QEMU audit output uses a private capacity-four drop-new FIFO with one admitted physical byte per eligible visit. It cannot populate public queen.log, outrank useful network/input work or suppress critical/fatal diagnostics. Pi diagnostics retain their selected route; MCS reports retain complete lifetime and CPU records within bounded transport output.
- Compatibility repairs preserve one TCP owner per pooled connection, canonical generated cohsh policy selection, target-local policy/replay fixtures, composed REST deadlines and exact runner-environment restoration. CAS uses the shared maximum of eight chunks, preflights payload capacity and keeps the ninth-chunk failure atomic. Synthetic performance populations require exact host-model backend classification; target pressure uses generated executable populations.
- Host tools, Python, SwarmUI, CAS/evidence tools and benchmark consumers preserve the external protocol and authority contract. Derived generated fields, fixtures and evidence readers follow their owning versioned changes; QEMU containment, host-model comparators and Pi performance remain separate proof classes.
Commands:
- cargo test -p cohesix-cas
- cargo test -p cas-tool
- cargo test -p nine-door host::cas::tests::ninth_chunk_quota_refusal_preserves_exact_eight_chunk_state -- --exact
- cargo test -p root-task --no-default-features --features driver-tests-qemu --lib ninedoor::tests::cas_ninth_chunk_quota_refusal_preserves_exact_eight_chunk_state -- --exact --test-threads=1
- cargo test -p coh-rtc --test roundtrip manifest_codegen_is_deterministic -- --exact
- cargo test -p coh-rtc --lib implementation_surface::tests -- --test-threads=1
- .venv/bin/python -m pytest -q scripts/ci/test_check_implementation_surfaces.py tests/test_release_bundle.py
- .venv/bin/python -m pytest -q tests/test_rest_perf_harness.py
- cargo test -p coh-rtc root_control_turn_candidate_is_exactly_accounted
- cargo test -p coh-rtc supervisor_cold_activation_candidates_are_profile_scoped
- cargo test -p coh-rtc --test ai_lora_contract
- cargo test -p console-network-abi -p console-network-runtime
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib pi_attached_wifi_continuation_requires_one_productive_network_successor
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib linked_cyw43_rx_admission_honors_input_and_clears_on_guards
- cargo test -p console-network-runtime buffered_oversize_body_and_quit_retain_service_until_same_connection_parse -- --exact
- cargo test -p root-task --no-default-features --features driver-tests-qemu isolated_response_lane_pays_exactly_one_ordinary_debt_after_eight_units -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-qemu isolated_help_capture_publishes_complete_body_then_one_terminal -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-qemu private_routine_audit -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-qemu stalled_routine_audit_uart_does_not_block_new_network_event_or_line -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-qemu routine_audit_tx_tag_survives_empty_record_and_promotes_on_ordinary_admission -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-qemu cat_queen_log_ack_includes_recent_echo_batch -- --exact --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-qemu hal::cache::tests -- --test-threads=1
- cargo test -p root-task --test console_network_service
- cargo test -p root-task --no-default-features --test mcs_activation_order -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-qemu --lib bootstrap::log::tests -- --test-threads=1
- cargo test -p root-task --no-default-features --test isolated_virtio_network_phasing -- --test-threads=1
- cargo test -p cohsh --test script_catalog
- cargo test -p cohsh --features tcp pooled_tcp_uses_one_wire_attach_for_twenty_four_exact_authority_leases -- --exact --test-threads=1
- cargo test -p cohsh --features tcp -- --test-threads=1
- cargo test -p cohesix-rest
- cargo test -p cohsh --features rest -- --test-threads=1
- cargo test -p hive-gateway -- --test-threads=1
- cargo clippy -p cohsh --features tcp --all-targets -- -D warnings
- cargo build -p cohsh --release --features tcp
- .venv/bin/python -m pytest -q tests/test_console_network_runtime_packaging.py
- .venv/bin/python -m pytest -q tests/test_qemu_tcp_response_matrix.py scripts/ci/test_run_regression_batch.py
- .venv/bin/python -m pytest -q scripts/ci/test_test_plan_evidence.py
- .venv/bin/python -m pytest -q scripts/ci/test_rest_regression_batch.py
- bash -n scripts/ci/test_plan_stage_04_rest_multiplexer.sh
- cargo check -p console-network-runtime --target aarch64-unknown-none
- cargo check -p root-task --target aarch64-unknown-none --no-default-features --features release-qemu
- cargo check -p root-task --target aarch64-unknown-none --no-default-features --features release-pi4
- cargo fmt --all -- --check
- scripts/check-generated.sh
- python3 scripts/ci/test_plan_catalog.py recommend scripts/qemu_tcp_response_matrix.py tests/test_qemu_tcp_response_matrix.py
- python3 scripts/ci/test_plan_catalog.py converge --target qemu --format json scripts/qemu_tcp_response_matrix.py tests/test_qemu_tcp_response_matrix.py
- scripts/ci/test_plan_run.sh --list
- scripts/ci/check_test_plan.sh
- scripts/cohsh/run_regression_batch.sh
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26e-console-qemu-v35-v18
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26e-console-pi4-v24-v18
Checks:
- Malformed packet/auth/control input fails inside the restricted child. Page access, nonzero identity, lengths and commit sequence validate before mutation; inactive padding grants no authority. Emitted page-helper frames avoid whole-page copies and the nested child stack stays strictly within 32 pages.
- Publication credit is consumed before mutation and restored only by the matching post-retention ACK (badge 64). Root clears ACK debt before signalling and forces observation. Duplicate/late ACK, stale sequence, coalesced hint and revoke cannot publish; graceful shutdown retires exact terminal debt before containment.
- Authentication and a two-session stale-control canary precede pressure qualification. A streamed response retained when session 1 closes must retire once with no bytes entering session 2; session 2 must authenticate, attach and receive its own ACK/TAIL/END. Peer close/relisten, full-frame send capacity, oversize-body drain and failed producer cleanup retain the listener and exact response ownership.
- The child retains completion -> event -> egress -> service continuation -> ingress -> control order. PollService commits StackIngress -> StackEgress -> Session before dispatch; each stack leaf performs one bounded poll. Nonzero RX or committed output returns Continuation; only zero RX and no commit return Complete. Idle/uncredited work blocks; ordinary SC exhaustion follows the selected NaturalPostpone policy.
- Isolated QEMU serial credit is 64 bytes shared across helpers, with 32 reserved for entry TX backlog. One output-record attempt is permitted per Operator; linked/Pi paths retain their separate two-record bound. Routine audit drains one byte per eligible visit from a capacity-four private FIFO. No helper resets credit or advances later FIFO/response-tail state early.
- Compact Runtime uses persistent Worker -> ControlEndpoint -> BootstrapDrain -> StreamFlush -> RebootTail ownership. Stream final line, cursor/bandwidth finalization and END occupy separate visits. Selected bulk Worker/command quanta remain generated and bounded. The HAL timebase/timer prelude cannot execute a second generic tail; Pi/non-VirtIO retains its own 48-line/16-KiB stream bound.
- Network retains ObserveChild -> StageOutput -> Disconnect -> Ingress -> ServiceTick ordering, advances on no-op, forces observation after child signal, and commits Timer/Nic successors before work. Retained TX permits at most two reclaim checks and one transmit/notify; sampled diagnostics occupy a separate non-publish visit. Successful sequences 0–63 and every 64th later success are sampled without changing continuous counters. No buffer mutation, head reuse, duplicate publication, completion spin or dropped egress is allowed.
- Containment advances one owner-local material unit per Recovery turn, preserves ordinary/runtime/network cursors and services console containment before NineDoor when both fault. Quarantine preserves operator liveness and prevents poisoned NIC access. Budget, Reply, independent root/emergency/fault reserves and authority boundaries remain generated; no second listener or root physical NIC owner appears.
- The fixed one-socket HELP/NETSTATS/SMP/CACHELOG matrix, exact-session lifecycle canary, separate standard-fault and natural-postponement liveness/isolation evidence, canonical .coh batch, Stage 03/04 and required host/Python checks retain exact source and target provenance. Conditional B2 executable target pressure and Conditional D host-model comparison cannot substitute for each other; Pi performance requires fresh Pi evidence and the generated 54-MHz virtual counter.
- Compact page/stack checks, stale-control rejection, negative CAS capacity, pooled-owner safety, deadline composition and backend/population classification remain independent contracts. Historical candidate failures and partial passes stay in the linked audit record; milestone completion is governed by the release qualifications above, not by those intermediate outcomes.
Deliverables: Restricted console/network child with bounded compact shared-page IPC, ABI v3 SendBatch plus explicit publication ACK, exact-identity bounded synchronous capture, a bounded authenticated response lane with ordinary-service debt, preserved external operator semantics, fixed response-matrix evidence, target-disassembly evidence, and live four-core GICv3 QEMU containment evidence.
Title/ID: m26e-qemu-shared-control-path-performance
Status: Reopened narrowly for the preemption-history byte-view restoration discovered by M27g / m27g-two-hour-pi4-operator-burn-in. Earlier release acceptance remains historical; this restoration requires focused host/model checks and fresh exact-image QEMU/Pi evidence before closure.
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / QEMU pressure validation and shared bounded service quanta
Goal: Remove measured artificial service-turn, Worker-scan, activation, transport head-of-line, and per-instance-SC ceilings while preserving one bounded shared architecture across QEMU and Pi.
Inputs: `m26e-console-network-service-isolation`, `m26e-worker-supervisor-child-isolation`, accepted executable-Worker pressure harness, ABI v3 SendBatch/publication-ACK boundary, configs/root_task*.toml, crates/{console-network-abi,worker-task-abi}/**, apps/{cohsh,console-network-runtime,hive-gateway,nine-door,root-task,worker-heart}/**, tools/{coh-rtc,cohesix-py}/**, scripts/m26e_qemu_pressure.sh, scripts/rest_perf_harness.py, docs/{INTERFACES,ROLES_AND_SCHEDULING,USERLAND_AND_CLI,TEST_PLAN,BENCHMARKS}.md.
Changes:
- The accepted GENET gate is unpaced 1,024-request canonical raw TCP at >=600 requests/s and <=5-ms p95 on two exact-image release boots. The owner-approved 9 September decision replaces the former 1.845-ms gate; controlled 180/s latency is diagnostic. Medium/high REST, cohsh, zero-failure and bounded-liveness checks remain required. Wi-Fi throughput/latency and complete <=42-second boot obligations remain unchanged. RAM results, QEMU evidence and final SD-boot qualification are distinct.
- Console ABI v6 retains the v4-introduced CommandBatch=27 encoding: one through eight consecutive same-connection authenticated commands, each with its original timestamp and UTF-8 bytes inside the unchanged 2,368-byte payload. Lifecycle/identity transitions fence batches. Root validates and reserves capacity for the whole private batch before exact FIFO admission; malformed, stale or oversized batches execute nothing.
- A rotating pending bitmap and fixed Worker quantum provide fair service, checking mailbox/fault priority between records. QEMU and Pi admit 256 executable Workers (1 Heartbeat, 127 GPU, 128 LoRA) through two active executor lanes and passive Worker SC donation. Pi uses a 16-bit root CNode with compiler-proved reserve and immutable role-image sharing. Generation-scoped Reply recovery returns donated time once and reclaims the faulted instance before recreation.
- One authenticated target stream carries bounded command/read batches through three fixed host lanes: admitted ticket specifications, receipt/control progress, and bulk telemetry. Every input retains an exact result; capacity/backpressure and cancellation cannot manufacture authority or bypass the existing ticket/journal path.
- Useful progress may retain a bounded activation through transient empty observations, with independent counter, quantum, completion and probe caps. GENET continuation binds exact generation, connection and control sequence; current-response completion retires that continuation. Fresh durable work earns one separately charged operator-first recheck. Empty rechecks stop; no speculative future-request spin, unbounded tail, larger hidden queue or new executor is admitted.
- The physical-Pi direct-GENET idle path binds root-control's existing fan-in notification and exact Reply to multiplexed endpoint receive. One nonblocking receive and the complete timer, endpoint, durable producer, operator, network, fault/recovery, quarantine and reboot fences precede blocking. Endpoint messages are copied into dispatcher-owned storage; notification badges are hints. Wi-Fi does not enter this global-idle receive.
- The existing isolated PCIe runtime solely owns the separately tagged system-timer page at 0xFE003000 and IRQ 99 (SPI 67), badge 2048, handler slot 4 and local notification slot 3. Descriptor adoption is Disarmed. The first exact direct-GENET enable uses a Reply-bearing call, publishes Enabled and arms channel 3 at 5,000 us, half the admitted 10,000-us owner period. Wi-Fi remains disarmed. IRQ service performs only bounded clear/sample/rearm/order/signal/ACK and then receives; no catch-up, retry or second timer owner exists. The lower timer page is pre-admitted before higher Pi MMIO and consumed only in the child VSpace.
- Fresh foreground CYW43-to-SDIO publication captures the complete parent/child/route/generation and recovery fences before sequence-last commit. Selected MCS atomically prompts slot 8 and waits on slot 3 before another semantic operation. The returned path reclassifies the durable child and first-owner receipt; it never sends a second prompt. SDIO seals fresh one-way work before wake telemetry/blocking while preserving physical IRQ priority. Inexact/classic paths retain their original bounded behavior.
- Driver runtime ABI v13 gives asynchronous generic MCS commands one initial prompt and an exact 24-byte DROW/DROA continuation handshake. Sequence, action, runtime generation and strictly-next wait slice validate before acknowledgement and one child resume. Bootstrap calls retain supervised Call/Reply donation; CYW43/SDIO retain their hard source-yield boundary. No retry, queue, physical owner or SC numeric changes are implied by a scheduling hint.
- Passive NineDoor remains local to its sole root-control donor, with release/acquire publication around exact request/response frames. CPU-only shared/control aliases use coherent Normal/XN memory and barriers; MMIO, framebuffer and private DMA retain their own admitted attributes. The root stack reservation is 1 MiB with independent layout/emitted-frame checks and the 2-MiB heap retained; an upper IPC gap is not a downward-overflow guard.
- Shared schedule dequeue is exact FIFO and rejects empty/stale/out-of-order IDs without mutation. Host-ticket compaction removes only terminal payloads after result publication and durable cursor advancement, retaining the cumulative admission fence. Completed preemptions use a fixed chronological ring whose oldest observation may be evicted without weakening active lease state. Restore the byte-limited preemption view to the newest complete chronological suffix: selecting the oldest prefix hid recent release effects from host-ticket-agent reconciliation after ordinary history growth. Preserve all entry/byte bounds, record grammar, cumulative counts and fail-closed ambiguous outcomes; do not replay an already admitted release.
- M27g compatibility review: host-ticket-agent requires the matching retained release record; coh/cohsh, Hive Gateway, SwarmUI, coh-status, host-sidecar-bridge, gpu-bridge-host, cas-tool, sidecar-bus, the Python SDK and performance scripts retain their existing contracts. Only root and host-model history selection changes; readers keep the same schema and chronological ordering, and omitted history never establishes an outcome. Fresh target evidence remains required.
- The compiler owns target population, runtime/console ABI, root fan-in, resource and temporal declarations. Worker and driver archives remain separate and hash-bound. Pi build compatibility derives from the selected SMP+MCS profile; the shared contract does not relabel earlier QEMU or classic evidence as Pi acceptance.
- Host tools, Python, SwarmUI and evidence readers consume generated target identity and the complete 265-task QEMU/272-task Pi temporal seals while retaining three detailed role exemplars. Gateway metadata exposes configured-backend target_host/target_port for endpoint binding, not proof of a live target. TCP-only cohsh builds exclude model transport closure; CAS/UI test binary resolution and Python population checks retain portable host compatibility.
- Benchmark comparison requires matched source, image, profile, target, population, harness, workload and error policy. It judges QEMU/Pi parity by successful throughput and errors while reporting physical latency separately. Exact-image diagnostics, scripts, raw TCP, pressure, operator liveness and repeatability determine Pi claims; successful builds, media verification, models and functional pressure alone do not.
Commands:
- cargo test -p pi4-driver-runtime --lib persistent_child_publication_selects_atomic_mcs_handoff_and_classic_signal -- --test-threads=1
- cargo test -p pi4-driver-runtime --lib sdio_peer_wake_admits_the_fresh_durable_one_way_command_immediately -- --test-threads=1
- cargo test -p pi4-driver-runtime --lib atomic_sdio_publication_never_replays_legacy_wait_progress -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib direct_genet_causal_wait_matches_only_the_current_control_identity -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib pi_genet_completed_response_does_not_open_a_future_request_tail -- --test-threads=1
- scripts/ci/test_plan_converge.sh --target qemu --focus root-mcs --path apps/root-task/src/event/mod.rs
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib pi_root_control_ -- --test-threads=1
- cargo test -p root-task --test mcs_activation_order -- --test-threads=1
- cargo test -p root-task --test mcs_fault_lanes -- --test-threads=1
- cargo test -p root-task --lib service_fault_frontier -- --test-threads=1
- cargo test -p root-task --lib service_call_arm -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib isolated_self_test -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib linked_cyw43_ -- --test-threads=1
- cargo test -p pi4-driver-runtime --lib direct_genet_ -- --test-threads=1
- python3 -m pytest -q tests/test_pi4_trace_normalize.py tests/test_pi4_gate_proof.py
- cargo test -p console-network-abi
- cargo test -p console-network-runtime
- cargo test -p root-task --no-default-features --test console_network_service -- --test-threads=1
- cargo test -p root-task --no-default-features --test isolated_virtio_network_phasing -- --test-threads=1
- cargo test -p coh-rtc console_network_service
- cargo test -p nine-door --test schedule_create --test schedule_bounds
- cargo test -p nine-door lease_
- cargo test -p host-ticket-agent
- cargo test -p worker-task-abi -p worker-heart
- cargo test -p root-task --test worker_ipc --test worker_supervisor --test worker_fault_lifecycle --test worker_resource_admission
- cargo test -p coh-rtc temporal resource_admission
- cargo test -p cohsh -p hive-gateway
- cargo test -p cohsh --no-default-features --features tcp
- python3 -m pytest -q tests/test_console_network_runtime_packaging.py
- python3 -m pytest -q tests/test_rest_perf_harness.py tests/test_pi4_compare_driver_models.py tests/test_worker_task_evidence.py tools/cohesix-py/tests/test_orchestration.py
- cargo test -p coh-rtc --test pi4_profile --test python_profile
- cargo test -p coh-rtc resource_admission
- cargo test -p root-task --test isolated_virtio_network_phasing
- python3 -m pytest -q tests/test_pi4_image_build.py tests/test_pi4_prebuilt_composition.py tests/test_sel4_profile.py
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
- .venv/bin/python scripts/sel4_profile.py validate --repo-managed --profile pi4_diagnostic --build-dir seL4/build_UBOOT --require-artifacts --for-runtime
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml --clean
- scripts/cohesix-build-run.sh --no-run --cargo-target aarch64-unknown-none
- scripts/m26e_qemu_pressure.sh with the canonical medium and high executable-Worker REST profiles on macOS, followed by equivalent Linux/KVM runs for an accepted Mac candidate
Checks: one child publication admits at most eight already-authenticated commands; original timestamps, per-key FIFO order, connection identity, and queue bounds remain exact; lifecycle events never coalesce; peer-assisted self-test observes decisive state despite ordinary activity, uses one fresh per-connection epoch, and cannot combine replacement or post-retirement traffic; Worker selection is fair; every internal quantum and active window retains hard bounds; the CYW43 outer cap counts only active Network service while its real-wall operator checkpoint and 192-turn cap remain independent; a quiescent direct-GENET Block closes only its software episode while continuous durable work and endpoint freshness retain their guards; the QEMU and Pi 256-Worker populations each consume only the two generated executor-lane utilization reservations; the Pi fixed-plus-maximum-plus-reserve inventory fits its exact 16-bit root CNode with 46,020 slots left; each passive Worker has exactly one allowlisted donor lane and generation-scoped Reply path; shared mappings are immutable and role/image exact while all writable mappings remain private; fault/timeout injection releases the donor once before complete containment; the passive NineDoor service is compiler-rejected unless co-located with its sole root-control donor; the exact selected seL4-16 AArch64 MCS ABI admits eight but rejects eleven refills in an 8-bit SC; direct GENET compiler/profile validation rejects any `wcet_us` other than 800, handoff/runtime validation rejects drift from exact max-eight-refill `3,000/10,000 us`, each guarded slice admits at most one material packet operation, and continuous bidirectional pressure receives an exact 8/8 split inside the 16-slice window; diagnostic-v4 packet-slice high-water and dense-window reason fields round-trip and render without authority; nonforeground CYW43-to-SDIO copies pass both directions and every alignment without crossing either admitted arena or changing foreground trace/overlay authority; the exact authenticated response rotation retains activation only through `Network -> Serial -> LocalSeat -> Dispatch -> Network` and rechecks the loop-top guard before another Network unit; non-VirtIO profiles cannot select direct VirtIO DMA containment and reject an invalid cursor; the retained Pi manifest still hashes to the stage proof after canonical QEMU cleanup; the provenance-bound Pi driver-runtime CPIO rejects tampering and remains byte-identical in a skip-build stage even after later QEMU children occupy the Cargo target directory; schedule depth returns after each completed benchmark lifecycle; terminal execution journals compact without weakening exactly-once recovery; preemption evidence turns over without refusing valid lease control and retains cumulative accounting; public output is byte-compatible apart from documented additive diagnostics; no unbounded loop, queue, retry, donation chain, or authority exists; medium/high QEMU pressure improves materially without unexpected fault, MCS timeout, queue runaway, or operator-liveness regression on either host. Static Pi profile and stage-only PASS remain non-hardware evidence.
Deliverables: ABI v6 bounded command quantum retaining the v4-introduced
CommandBatch contract, two bounded Worker executor lanes, target-qualified QEMU
and Pi 256-Worker populations, a 16-bit Pi root-CNode profile with deterministic
reserve, immutable role-image sharing, generation-safe donated-SC recovery,
three-tier bounded authenticated transport progress, bounded progress-retaining
root activation, shared schedule consumer lifecycle, durable terminal-journal
compaction, rolling preemption evidence, focused regression evidence, and
same-source macOS/Linux QEMU before/after pressure records. Pi hardware
acceptance remains a separate future evidence lane.
Qualification: QEMU performance results retain their original source, host,
profile and proof class in the linked audit record and BENCHMARKS.md; they do
not establish Pi hardware acceptance.
Title/ID: m26e-mcs-operator-inspection
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / bounded root-shell MCS operator inspection
Goal: Expose source-labelled generated and live seL4 MCS state through `bi`, `caps mcs`, and `smp mcs` without perturbing scheduler accounting.
Inputs: `m26e-mcs-abi-foundation`, `m26e-worker-resource-admission-critical-tcbs`, `m26e-console-network-service-isolation`, selected seL4 BootInfo, generated temporal/resource-admission records, live fault-registry and critical-domain state, crates/cohsh-core/**, apps/root-task/src/{console,event,critical_tcb.rs,hal/critical_tcb.rs}, docs/{INTERFACES,USERLAND_AND_CLI,SECURITY,TEST_PLAN}.md.
Changes:
- crates/cohsh-core/** + generated grammar/fixtures — preserve bare `caps` and `smp`; add strict `caps mcs` and `smp mcs`; list both MCS spellings as explicit root-shell and host-client help rows; update every parser/help/transcript consumer.
- apps/root-task/src/{console,event}/** — retain the legacy `bi` line, source every production help path from the shared root-console inventory, and emit bounded kernel BootInfo and generated profile records; keep every `caps mcs` record within the 77-byte Pi linked-HDMI fallback width without dropping fields.
- apps/root-task/src/{critical_tcb.rs,hal/critical_tcb.rs,event/**} — copy the live registry nonblockingly, release its lock before output, and render authority/object, per-core admission, and per-task temporal/registration/generation state. Never call `seL4_SchedContext_Consumed`, mutate accounting, perform a debug dump, or create authority.
- docs and compatibility — document provenance and separate QEMU/Pi evidence; review `coh`, `cohsh`, SwarmUI, Hive Gateway, `.coh`, `tools/cohesix-py`, fixtures, release, and performance surfaces without changing their semantics.
Commands:
- cargo test -p cohsh-core
- cargo test -p root-task mcs_operator_inspection
- scripts/cohesix-build-run.sh --clean --no-run --cargo-target aarch64-unknown-none
- python3 -m pytest -q tests/test_qemu_tcp_response_matrix.py
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26e-mcs-operator-inspection-qemu
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26e-mcs-operator-inspection-pi4
Checks: legacy behavior remains; every production help path lists literal `caps mcs` and `smp mcs`; output is strict and bounded; every `caps mcs` field survives the Pi linked-HDMI fallback width; generated/live sources stay distinct; missing, contended, early, and fatal state are explicit; QEMU and fresh-Pi evidence remain separate.
Deliverables: Additive root-shell MCS inspection, grammar compatibility, deterministic tests, and separate exact-target evidence.
Title/ID: m26e-worker-abi-identity-notifications
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / Worker task ABI v1 and exact executable-role matrix
Goal: Freeze one pointer-free namespace-projection ABI, collision-free instance identity, seL4-correct notification contract, and non-vacuous Heartbeat/GPU/LoRA role matrix before any Worker image or supervisor depends on it.
Inputs: `m26e-mcs-abi-foundation`, `m26e-worker-resource-admission-critical-tcbs`, `m26e-mcs-operator-inspection`, apps/worker-heart/**, apps/worker-gpu/**, apps/worker-lora/**, apps/root-task/src/worker_authority.rs, tools/coh-rtc/src/**, configs/root_task*.toml, docs/INTERFACES.md, docs/ROLES_AND_SCHEDULING.md, docs/USERLAND_AND_CLI.md, docs/WORKER_TICKETS.md, docs/GPU_NODES.md.
Changes:
- crates/worker-task-abi/** — add `worker-task-abi/v1` runtime-init, identity, bounded control/completion, READY, telemetry/receipt, shutdown, standard-fault, timeout-fault, and evidence records with fixed layouts, explicit version/length/sequence/epoch/generation fields, release/acquire rules, and no pointers or extra caps. Define exact `GPU_LEASE_RECEIPT` and `PEFT_RECEIPT` labels/records carrying the generated action code, confirmed/rejected outcome, receipt sequence, full Worker identity, and fixed SHA-256 idempotency/operation/subject/result digests, plus their bounded `worker-gpu-receipt/v1` and `worker-lora-receipt/v1` canonical telemetry encodings.
- tools/coh-rtc/src/** + configs/root_task*.toml — generate immutable `(role, slot, lease_epoch, supervisor_generation, cap_generation)` endpoint/fault identities; lifecycle and supervisor-wake notification objects; reserved disjoint endpoint/notification badge ranges; per-slot one-hot lifecycle/completion bits and precedence; per-slot durable control/completion records; exact holders/slots/rights/syscalls; one active Worker SC bound only to its TCB; zero normal-IPC blocking Send/Call/Reply/donation depth; standard/timeout fault caps with `Write + GrantReply`; exactly one root-fault Read cap and one serialized receive Reply; per-role slots/images; accepted host-ticket request/result schema sets; the action/receipt-mode version matrix; root-pinned version-2 Worker bindings; and Heartbeat/GPU/LoRA `implemented = true` candidate contracts while WorkerBus remains model-only.
- tools/coh-rtc/src/** + evidence schema — distinguish model-only, configured executable, QEMU-accepted, Pi-accepted, Worker-runtime-release-accepted, and production-use-case-accepted states; define strict, non-interchangeable `cohesix-worker-observation/v1` (`record_kind=observation`), `cohesix-worker-integration-evidence/v1` (`record_kind=worker-integration`), `cohesix-worker-task-evidence/v1` (`record_kind=target-component`), `cohesix-root-tcb-acceptance/v1` (`record_kind=root-tcb`), `cohesix-mcs-smp-system-acceptance/v1` (`record_kind=full-system`), and `cohesix-worker-release-acceptance/v1` (`record_kind=release`, scope `worker-runtime`) schemas with per-kind required/forbidden field matrices. Exact-target component records key the sorted exact role-required Worker-integration rows plus target/kernel/resolved-manifest/root/MCS-driver-archive/MCS-driver-manifest/CYW43-coexistence-record/Worker-archive/Worker-image-manifest/Worker-image/ABI/evidence hashes; the release record contains exactly six matching component/root/system record references plus the recursively cross-checked runtime artifact/integration graph. No consumer infers record kind, `implemented = true` never depends on later hardware proof, and the runtime release record cannot be parsed as a production use-case acceptance record.
- docs/INTERFACES.md + docs/USERLAND_AND_CLI.md + generated grammar/fixtures — add the manifest-gated `lora` value to the existing spawn operation and `peft.export` to the existing host-ticket action enum/allowlist; define strict per-action version-2 request/result schemas on the existing host-ticket paths with exact argument sets/bounds, `operation_id`, `subject_ref`, receipt Worker role/id/supervisor-generation/cap-generation, root-resolved Worker slot/lease epoch, and canonical `result_digest`; reject unknown args, free-form host paths, symlink/traversal PEFT inputs, ungenerated GPU/device ids, and cross-subject bindings before dispatch; publish the accepted-schema sets and action/receipt-mode matrix; retain version 1 only for actions requesting no Worker receipt; reject federation fields for receipt-bearing version 2; keep `ATTACH` non-instantiating; and map validated terminal GPU/PEFT results through the generated supervisor records and exact receipt labels without a new VM verb, namespace, or executor.
- docs/ROLES_AND_SCHEDULING.md + docs/WORKER_TICKETS.md + docs/GPU_NODES.md + docs/TEST_PLAN.md — define exact rights, capacity, identity, coalescing, durable completion, terminal-versus-recoverable fault, PEFT idempotency/receipt, and acceptance-state contracts.
Commands:
- cargo test -p worker-task-abi
- cargo check -p worker-task-abi --target aarch64-unknown-none
- cargo test -p coh-rtc worker_task
- cargo test -p root-task --test worker_contract
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
Checks: duplicate/overlapping badge domains, zero or multi-bit notification events, OR aliases, role/slot/epoch/supervisor-generation/cap-generation overflow, unknown or action-incompatible ABI/host-ticket schema versions, unknown/oversized/action-incompatible args, free-form or escaping host paths, missing root-resolved slot/lease epoch, missing/cross-role/non-READY receipt bindings, federated/relayed version-2 receipts, post-admission Worker rebinding, extra caps, unbounded frames, broadened or reversed cap rights, SC-to-notification binding, normal Worker Send/Call/Reply/donation, missing durable completion, invalid fault `GrantReply`/Reply cardinality, missing Heartbeat/GPU/LoRA contracts, executable WorkerBus, and circular evidence-dependent `implemented` validation all fail closed; every WorkerGpu record maps exactly one terminal `gpu.lease.grant|renew|release` result, every WorkerLora record maps exactly one terminal `peft.export|import|activate|rollback` result, and both prove id/ticket/idempotency/digest/generation/replay behavior without granting host execution, credential, model, or device authority.
Deliverables: Compiler-owned Worker ABI v1, exact mandatory role matrix, additive LoRA spawn value, and exact-image acceptance schema.
Title/ID: m26e-worker-image-pipeline-loader
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / content-addressed Worker images and generic least-authority child loader
Goal: Build, validate, package, hash, and load the three mandatory Worker images before root compilation without repackaging or modifying the newly accepted 26e MCS driver archive.
Inputs: `m26e-mcs-abi-foundation`, `m26e-driver-runtime-mcs-port-and-cyw43-coexistence`, `m26e-worker-abi-identity-notifications`, apps/worker-heart/**, apps/worker-gpu/**, apps/worker-lora/**, apps/root-task/build.rs, apps/root-task/src/hal/**, scripts/cohesix-build-run.sh, scripts/pi4-image-build.sh, scripts/ci/size_guard.sh, generated Worker ABI/slot records, and the newly hash-bound MCS driver/CYW43 coexistence identity.
Changes:
- apps/worker-heart/** + apps/worker-gpu/** + apps/worker-lora/** — provide real `no_std` target binaries and linker contracts that consume only the sealed runtime-init descriptor, issue READY, block on real IPC/notifications, use admitted time, and remove hard-coded CPtrs, synthetic identity/time, and spin loops; LoRA emits bounded PEFT lifecycle receipts and never trains, imports, loads, activates, rolls back, or infers itself.
- scripts/worker_image_manifest.py + tests — validate AArch64 ELF class/machine, entrypoint, relocation/load span, W^X segments, stack/IPC bounds, canonical stripped bytes, role/ABI identity, content hashes, duplicate names, and tampering.
- scripts/cohesix-build-run.sh + scripts/pi4-image-build.sh + apps/root-task/build.rs — add `worker-heart`, `worker-gpu`, and `worker-lora` explicitly to the target Worker build/staging inventory, build Workers first, create a deterministic separate `cohesix-worker-images.cpio` plus `cohesix-worker-image-manifest/v1`, then compile root with generated target-qualified digest expectations and retain the exact archive/manifest in rootserver for target loading. Byte-identical system-CPIO copies remain the host/release projection; typed BootInfo FDT records are never treated as that CPIO. A selected executable role missing from the build list, staged directory, archive, or manifest fails instead of being silently skipped. Do not append to, rename, reorder, or reinterpret `cohesix-driver-runtimes.cpio`, `COHESIX_PI4_DRIVER_RUNTIME_PAYLOAD`, or its seven-driver evidence fields.
- apps/root-task/src/hal/** — add an additive HAL-backed generic W^X child-image planner/loader for generated Worker records without refactoring or duplicating the MCS-ported physical driver-runtime loader and ABI path.
- exact-image/release metadata — bind the Worker archive, Worker image-manifest, and per-image hashes separately into QEMU and Pi identity and preserve the rootfs `< 4 MiB` guard.
Commands:
- cargo build --locked --release --target aarch64-unknown-none -p worker-heart -p worker-gpu -p worker-lora
- cargo test -p root-task --test worker_image_loader
- python3 -m pytest -q tests/test_worker_image_pipeline.py tests/test_pi4_image_build.py
- scripts/cohesix-build-run.sh --clean --no-run --cargo-target aarch64-unknown-none
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml --clean
- scripts/ci/size_guard.sh out/cohesix/cohesix-system.cpio
Checks: root builds only after all three canonical image hashes exist; the exact archive and manifest contain Heartbeat/GPU/LoRA and no WorkerBus; wrong architecture, W+X, bad entry/load bounds, stale/tampered hash, missing LoRA binary, malformed runtime-init bounds, or rootfs overflow fail; QEMU/Pi Worker archives are target-qualified; this task leaves the input MCS driver archive/hash, CYW43/SDIO behavior, inventory, timing, restart, and evidence classification unchanged.
Deliverables: Deterministic separately packaged Worker images, target-qualified image manifest, and reusable least-authority Worker loader without a driver/CYW43 packaging refactor.
Title/ID: m26e-worker-supervisor-child-isolation
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / transactional executable Worker supervision
Goal: Replace model-only target claims with real Heartbeat/GPU/LoRA child tasks whose spawn, READY, operation, shutdown, fault, teardown, and fresh-generation recreation are atomic and authority-safe.
Inputs: `m26e-worker-resource-admission-critical-tcbs`, `m26e-worker-abi-identity-notifications`, `m26e-worker-image-pipeline-loader`, apps/root-task/src/worker_authority.rs, apps/root-task/src/lifecycle.rs, apps/root-task/src/event/**, apps/root-task/src/ninedoor.rs, apps/worker-heart/**, apps/worker-gpu/**, apps/worker-lora/**, generated slot/image records, canonical Worker docs.
Changes:
- Release Worker bootstrap reservation restoration — discovered by `m26e-mcs-smp-target-acceptance` on native KVM source `3603bd507f2d252d3dec825dabcffcd15c76569c`: an initiating kernel timeout capture identifies LoRA slot 43 (`worker-172`) executing init-record hashing at PC `0x212700`, with its temporary 400-us SC exhausted before READY; the final population is 255. Under schema 1.18, explicitly select `bootstrap_timeout_policy = "natural-postpone"` for MCS Worker startup, retaining 400/10,000 us, two refills, priority/core assignment, the five-second READY deadline and standard-fault containment. Unbind that SC before installing the existing passive ReturnError timeout endpoint, and publish READY only after both operations succeed. A failed transition keeps admission closed and deadline containment armed. Missing or terminal bootstrap policy and the previous schema fail compilation. Review the complete host-tool suite, Python library and performance scripts: regenerate manifest/profile/hash bindings together; public protocols, workloads, receipt requirements, thresholds and report schemas remain unchanged. Require focused compiler/transition/deadline checks, exact Mac/KVM/Pi builds, full QEMU lifecycle/fault gates and fresh uninterrupted Jetson bootstrap/pressure repeatability. This is a defect restoration under the existing executable-admission and transactional-supervision tasks, not evidence of release acceptance.
- apps/root-task/src/worker_authority.rs + lifecycle/event code — implement the generated free/allocate/verify/map/configure/admit/resume/READY state machine, reserve ids before READY without publishing live authority, validate every child record, and serialize Queen decisions without blocking root-control, root-fault, or root-emergency TCBs.
- apps/root-task/src/ninedoor.rs + console projection — make accepted spawn acknowledge bounded queue admission, add the generated LoRA spawn target, expose bounded starting/live/closing/faulted/terminal state, stop new authority immediately on kill, and preserve `ATTACH` as session-only.
- supervisor completion/fault handling — drain generated per-slot durable READY/operation/receipt records from the supervisor-wake notification, validate sequence/identity/digest, preserve one-in-flight semantics, count droppable telemetry, receive nonblocking critical-TCB handoffs, and keep fault Reply ownership in root-fault until its terminal or allowlisted-recoverable decision completes.
- supervisor teardown — close admission, signal one-hot shutdown, enforce the grace bound, suspend, clear durable records and notification state, resolve fault Replies, unbind notification/SC, unmap/scrub frames, revoke descendants from retained anchors, delete child objects, prove zero old-generation authority and no blocking-send path, reclaim the slot, and advance generation before reuse.
- apps/worker-heart/** + apps/worker-gpu/** + apps/worker-lora/** — validate init/control records, publish durable READY/completion/receipt records before signaling, produce only explicitly droppable endpoint telemetry, honor coalesced lifecycle precedence, block when idle, and reject late/stale generations; WorkerLora maps the four PEFT result actions exactly and only WorkerBus remains model-only.
- generated artifacts + canonical Worker docs — use `implemented = true` only for complete static executable contracts and describe acceptance-pending versus exact-target-accepted state separately.
Commands:
- cargo test -p root-task --test worker_ipc
- cargo test -p root-task --test worker_supervisor
- cargo test -p root-task --test worker_notification
- cargo test -p root-task --test worker_fault_lifecycle
- cargo test -p worker-heart -p worker-gpu -p worker-lora
- cargo check -p worker-heart -p worker-gpu -p worker-lora --target aarch64-unknown-none
- scripts/check-generated.sh
Checks: ring/control saturation, duplicate sequence, forged role/slot/epoch/supervisor-generation/cap-generation, two sequential same-role generations with a simultaneous second-live-slot refusal, coalesced notifications, durable-completion publish/signal races, READY timeout, construction failure at every phase, ordinary terminal fault, allowlisted timeout recovery, fault before READY/during IPC, attempted forbidden blocking send, dropped telemetry, late completion/receipt, kill/fault repetition, generation exhaustion, and repeated maximum-slot churn fail or recover deterministically with no orphan namespace state, cap, mapping, pending record/signal, Reply, SC, or executable TCB; PEFT export/import/activate/rollback receipts prove the exact host-ticket-result-to-supervisor-to-WorkerLora mapping without moving host work into the VM.
Deliverables: Real transactional Heartbeat/GPU/LoRA tasks and complete per-instance 26e containment/reclamation; WorkerBus remains honestly model-only.
Title/ID: m26e-gpu-refresh-control-retention
Milestone: Milestone 26e — host integration / m26e-host-integration-dependency-contract; release burn-in defect restoration
Goal: Keep admitted GPU control records readable during ordinary inventory refreshes from the same live publisher generation.
Inputs: exact Pi GENET burn-in 8c050a0aaf7b image, continuous real Orin inventory, 30-second GPU lease lost after a six-second observation interval, and WorkerGpu READY records.
Changes:
- apps/root-task/src/ninedoor.rs — preserve bounded ctl/lease/status append logs for an unchanged GPU identity within the same unexpired publisher epoch; withdrawal, changed device/source/epoch, expiry and stale-snapshot rejection remain fail-closed.
- apps/nine-door/src/host/{core.rs,namespace.rs} — preserve the corresponding host-model journal semantics without claiming target execution or provider freshness acceptance.
- docs/GPU_NODES.md and docs/HOST_TOOLS.md — describe inventory seeds versus appended control history and record complete host-tool, Python SDK and benchmark compatibility review.
Commands:
- cargo test --locked -p nine-door --test integration gpu_inventory_refresh
- cargo test --locked -p root-task --lib --features driver-tests-pi4 gpu_snapshot
- exact-profile Pi release build, image-bound RAM boot, first raw GENET gate, live refresh/lease/Worker and FUSE checks
Checks: successful same-generation refresh preserves control bytes; changed generation/device, withdrawal, expiry and rejected updates cannot retain or create stale authority. No new CUDA executor, lease enforcement claim, schema, namespace, unsafe code or performance threshold.
Deliverables: material retention repair with focused host contracts and fresh Pi evidence before a revised timed attempt.
Title/ID: m26e-host-integration-dependency-contract
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / generated host-integration and use-case dependency contract
Goal: Inventory every advertised host integration and use case, generate its transitive Worker/provider/release dependencies and acceptance obligation, and prevent a Worker, release, use case, or playbook from being promoted while a required host path is mock-only, missing, or unowned.
Inputs: `m26e-production-surface-truth-and-stub-retirement`, `m26e-worker-abi-identity-notifications`, `m26e-worker-supervisor-child-isolation`, Cargo.toml, configs/root_task*.toml, configs/generated/implementation_surface_inventory.json, tools/coh-rtc/src/**, apps/cohsh/**, apps/coh/**, apps/coh-status/**, apps/hive-gateway/**, crates/cohesix-rest/**, apps/swarmui/**, tools/cohesix-py/**, apps/gpu-bridge-host/**, crates/host-cuda/**, apps/host-ticket-agent/**, apps/host-sidecar-bridge/**, apps/sidecar-bus/**, apps/cas-tool/**, scripts/release_bundle.sh, docs/USE_CASES.md, docs/HOST_TOOLS.md, docs/HOST_API.md, docs/GPU_NODES.md, docs/PYTHON_SUPPORT.md, docs/INTERFACES.md, docs/TEST_PLAN.md, and current release manifests.
Changes:
- tools/coh-rtc/src/** + configs/root_task*.toml — add compiler-owned `host-integration-dependency/v1` records that reference existing generated namespace paths, host-ticket actions, schemas, and authority rather than redefining them. Require integration id/owner, host profiles, dependent Worker roles/use cases/playbooks, `role_required|release_required|use_case_required|optional|future` obligation, required/allowed observed modes, unavailable/future ownership, auth/secret refs, timeout/retry/cancel/idempotency/fencing posture, readiness/degraded semantics, package/artifact requirements, evidence lane, and owning milestone.
- tools/coh-rtc/src/codegen/** + configs/generated/** + docs/snippets/** — extend the implementation-surface inventory with one bounded dependency graph and conformance vectors consumed by Rust/Python/REST/UI/release tools. Include every host-facing workspace binary and library API presented as a product surface, every host integration named by any tracked README/canonical doc/help/example, all six `docs/USE_CASES.md` scenarios, and every built-in `cohesix-playbook` id; fail generated-drift checks when an advertised surface is missing, hand-classified elsewhere, or reaches a live row through a fixture/model/no-op dependency.
- crates/cohesix-worker-evidence/** + schemas — add strict validation for `cohesix-worker-integration-evidence/v1` (`record_kind=worker-integration`) and a sorted bounded reference list on target-component evidence. Each record covers exactly one dependency row and binds its observed `unknown|missing|disabled|fixture|mock|dry-run|live` mode to the exact dependency graph, manifest, component/config/artifact hashes, optional QEMU or Pi target session, host profile/OS/architecture, provider/package versions, action/observation/receipt outcomes, redacted raw evidence, PASS/FAIL, and blockers without containing secrets or becoming Worker READY evidence.
- configs/host_integration_acceptance.toml + scripts/ci/host_integration_run.sh + scripts/ci/check_host_integration_inventory.py + tests/test_host_integration_run.py — create the matrix-only, fixture/mock/dry-run/live, projection-compatibility, and release validation lanes plus their schema, tamper, mode-substitution, missing-owner, and secret-redaction tests. The mandatory 26e live target-session rows are `worker-control`, `gpu-receipt-path`, and `peft-receipt-path`; external GPU/PEFT provider rows remain separately observed and cannot be promoted from the receipt fixture. Advertised FUSE, systemd, Docker, Kubernetes, federation, SIEM/evidence, sidecar, CAS/artifact, and packaging surfaces receive their exact release/use-case obligation and deterministic unavailable behavior. Later NeMo, MCP/A2A, Prometheus/OpenTelemetry, general inference/training, and unbuilt industry providers are explicit future records, never silent omissions.
- docs/USE_CASES.md + docs/HOST_TOOLS.md + docs/GPU_NODES.md + docs/PYTHON_SUPPORT.md + docs/TEST_PLAN.md — generate or embed the dependency/support-level table and define that executable-Worker proof, provider availability, package presence, mock/dry-run success, and use-case promotion are independent states.
Commands:
- cargo test -p coh-rtc host_integration
- cargo test -p cohesix-worker-evidence
- python3 scripts/ci/check_host_integration_inventory.py
- python3 -m pytest -q tests/test_host_integration_run.py
- scripts/ci/host_integration_run.sh --matrix configs/host_integration_acceptance.toml --matrix-only --state-dir out/host-integration/m26e-matrix
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
Checks: Duplicate ids, unknown action/path/schema refs, missing owners, unclassified host binaries/docs/playbooks, circular dependencies, a role-required integration with no live runtime lane, fixture/mock/dry-run satisfying a provider-live row, a release-required surface with no package/evidence rule, a use case promoted with an unsatisfied dependency, a future provider selected as live, secret-bearing evidence, and host/provider readiness interpreted as Worker READY all fail deterministically; the resulting graph assigns every integration gap to exactly one task-owning milestone id that exists in this plan, including the distinct 31 semantic, 35 inference, 28d/28e selected MCP/A2A, 36 extended protocol, 33 production-bundle, and 27f UI owners under the ownership map, with no ambiguous or compound deferral.
Deliverables: One compiler-owned host-integration/use-case dependency graph, exhaustive inventory guard, strict per-row Worker-integration evidence schema, and exact milestone ownership for every dependency needed by fully functional Workers and their documented use cases.
Title/ID: m26e-host-worker-integration
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / protocol-faithful host integration for real Workers
Goal: Make Cohesix host tools and every mandatory 26e host-integration lane discover, start, observe, correlate, execute, package, and evidence real Heartbeat/GPU/LoRA Workers through existing Secure9P/console projections with one generated state/dependency contract, no new authority plane, and no VM-local GPU/PEFT execution.
Inputs: `m26e-production-surface-truth-and-stub-retirement`, `m26e-worker-abi-identity-notifications`, `m26e-worker-image-pipeline-loader`, `m26e-worker-supervisor-child-isolation`, `m26e-host-integration-dependency-contract`, Cargo.toml, configs/root_task*.toml, configs/host_integration_acceptance.toml, crates/worker-task-abi/**, crates/cohsh-core/**, crates/cohesix-rest/**, apps/cohesix-proto/**, apps/nine-door/**, apps/cohsh/**, apps/coh/**, apps/coh-status/**, apps/gpu-bridge-host/**, crates/host-cuda/**, apps/host-ticket-agent/**, apps/host-sidecar-bridge/**, apps/sidecar-bus/**, apps/cas-tool/**, apps/hive-gateway/**, apps/swarmui/**, tools/cohesix-py/**, tools/swarmui-ui-tests/**, tools/coh-rtc/src/**, resources/openapi/hive-gateway.yaml, scripts/cohsh/**, scripts/ci/host_integration_run.sh, scripts/rest_perf_harness.py, tests/test_rest_perf_harness.py, scripts/release_bundle.sh, docs/USE_CASES.md, docs/HOST_TOOLS.md, docs/HOST_API.md, docs/GPU_NODES.md, docs/PYTHON_SUPPORT.md, docs/BENCHMARKS.md, docs/TEST_PLAN.md, docs/audit/checklists/RELEASE_EVIDENCE_CHECKLIST.md, generated Worker image manifests, and the accepted 26e MCS driver/CYW43 coexistence identities by immutable hash/reference only.
Changes:
- Release host-model Queen-log tail restoration — discovered by `m26e-mcs-smp-target-acceptance` during Conditional E's native three-hive scale comparator. The in-process `cohsh` transport must apply the target's existing 64-record default specifically to `/log/queen.log`; preserve explicit 1..256 line requests, complete CAT reads, and other paths. Fresh native KVM and native model probes provide the independent default-window oracle. Keep every benchmark operation, byte limit, Worker count, timeout, retry rule, error budget and report schema unchanged; preserve the failed 3,000-Worker run. Review all host tools and Python consumers as recorded in HOST_TOOLS. Host-model success remains distinct from live federation/provider and target acceptance.
- Release systemd status parsing restoration — discovered by `m26e-mcs-smp-target-acceptance` during Conditional E on native Linux: the compatibility executor flattened successful `systemctl show` property records before the line-based parser, rejecting a valid inactive/dead response. Preserve property line boundaries inside the existing UTF-8-safe 256-byte capture bound; flatten only operator receipt/error summaries. Test actual property framing, byte boundaries and single-line summaries. Provider publication availability and federation success remain separate live gates; do not manufacture target unit entries or treat this parser repair as provider acceptance. Review the complete eight-tool host suite, Python library, generated contracts and benchmark consumers together; only host-ticket-agent parsing and its focused fixtures change, with no interface, workload, retry or threshold change.
- Release staged host-test restoration — QEMU `4474dafe4` passed its medium/high pressure workloads but Stage 01 exposed two test-isolation defects. Preserve the documented QEMU Worker-supervisor/GPU-executor refill allocations of 10/10 and Pi allocations of 2/8, assert each exact value and 256-byte SC size, and remove only those two fields from cross-target equality. Isolate all TCP authentication resolver environment inputs in SDK tests and retain the primary-token precedence contract so the authenticated release runner cannot contaminate fallback tests. Runtime, generated manifests, host-tool interfaces, SDK behavior and benchmark workloads remain unchanged; rerun the complete Python gate with the release environment present.
- Release pressure proof retention — discovered by `m26e-mcs-smp-target-acceptance` on QEMU `4474dafe4`: 87,683 medium operations and 3,106 successful GPU/LoRA receipts completed, but periodic qlog exports lost the Heartbeat teardown during full-fleet discovery; per-Worker receipt counters also coincided across live slots. Capture target teardown/READY records before dependent discovery and exact receipt/completion records before reusing their Worker lane. Retain original unique fragments within the existing 64 MiB bound, with bounded serialized capture and fatal missing/conflicting evidence. New pressure rows carry the authenticated five-part identity; the collector correlates that identity with target records and preserves strict ambiguity rejection for legacy rows. Runtime, scheduling, raw benchmark thresholds, console/REST, the complete host-tool suite and Python SDK remain unchanged; the benchmark producer, shared host log collector, evidence consumer, focused tests and benchmark contract change together. Preserve the original run and require fresh actual pressure/log correlation before promotion.
- Release executable pressure report restoration — discovered by `m26e-mcs-smp-target-acceptance` on exact QEMU source `1e8254be3`: medium pressure completed 1,664 GPU renewals and 1,547 LoRA exports with zero receipt errors, but report validation required a setup-only GPU grant that had left the bounded 256-record window. Require the actual timed GPU renewal and LoRA export actions plus positive timed receipt counts; setup grants alone cannot qualify pressure. Preserve the producer's existing per-receipt timing/read diagnostics and validate their exact optional shape, finite nonnegative timings and positive read counts at the collector boundary. Unknown fields, malformed diagnostics, stale identity, nonmonotonic sequence, unconfirmed receipts and missing target-log correlation still fail. The complete host-tool suite and Python SDK need no protocol or generated-contract changes; both QEMU/Pi report builders, benchmark documentation and deterministic producer/collector tests change together. Preserve the failed canonical run and rerun real target reporting before promotion.
- Release-candidate PEFT projection restoration — discovered by `m26e-mcs-smp-target-acceptance`: restore host registry activation/rollback without writing the read-only `/gpu/models/active` view. The CLI publishes the existing validated bridge snapshot; ticket-agent and Python local commits report pending projection. Prepare bounded state before the atomic active-pointer commit and reject interrupted state/pointer disagreement. Apply the existing 32-byte lease-id bound before every version-2 GPU provider operation, preserving the one-round-trip renewal. Repair receipt fixtures to admit valid GPU subjects before provider rejection, deliver expired results to their exact READY Workers, and independently retain fault/teardown/generation tests. Review all host tools, Python, generated contracts and benchmark consumers together; do not relax target policy, receipt outcomes, workload, thresholds or evidence provenance.
- Release-candidate integration evidence routing — discovered by `m26e-mcs-smp-target-acceptance` after all nine Worker fault cases and 21 host terminal results passed: decode the authenticated Worker fragment stream and hash its original bytes in host-integration observations. Retain service teardown validation in the existing preflight collector over its three separate exact-boot UART/GDB pairs. Wait for each exact Worker receipt and retain its authenticated log before eviction. Reconcile the target gate with the existing host-ticket mapping: failed and expired results produce Rejected on a live Worker; a late result after retirement is fenced as stale at root and never delivered to the replacement. Preserve all 21 live receipt cases and add seven real agent publication barriers with ordered teardown, fresh same-role READY, exact ticket snapshots and unchanged replacement sequences. After sealing those observations, require fresh confirmed GPU and LoRA receipts on the final live replacements before preflight; retired completions remain ineligible. Correct unattended PTY input ownership and recognize only the exact root shutdown completion following synchronous teardown. The full host-tool suite, Python library, generated contracts and benchmark report consumers require no interface changes; runtime behavior and provenance remain unchanged.
- Release benchmark liveness verdict — discovered by `m26e-mcs-smp-target-acceptance` on native KVM: 64 GPU/LoRA receipt failures and root-emergency were hidden by an aggregate error rate below one percent. Preserve numerical metrics and the declared budget, but fail both executable modes on lost Worker receipts or fatal UART status. Review the complete host-tool suite, Python API and benchmark consumers: no transport, provider, generated contract or report schema changes are needed; the command verdict now preserves the existing execution-liveness contract. Retain the failed target for diagnosis before any runtime repair.
- Release benchmark passive Heartbeat parity — discovered by `m26e-mcs-smp-target-acceptance` after exact QEMU component preflight passed: align the benchmark acceptance-summary parser with the existing shared Worker evidence contract. A freshly recreated READY Heartbeat may have zero workload completions; GPU and LoRA still require positive completion sequences and confirmed receipts. Reject malformed, negative and Boolean sequences. Independent Heartbeat progress, lifecycle and fault evidence remains mandatory. The complete host-tool suite and Python library already preserve this role distinction; no public protocol, schema, workload, threshold or target-runtime change is required.
- Release pressure agent state isolation — discovered by `m26e-mcs-smp-target-acceptance` after component and live preflight passed: execution lane topology and completed ticket cursors must survive the transition into pressure. Use eight lanes from the first receipt-matrix invocation, preserve its completed state as evidence, and resume pressure from a copy of those same cursors and journals. Empty state replays deliberately retired tickets and blocks later live work. Keep the agent's topology mismatch rejection, journal reconciliation and receipt fencing unchanged. Verify both emitted lane configurations and exact state handoff, then rerun the real target transition. The complete host-tool suite, Python library, generated contracts and benchmark schemas need no changes; the canonical harness preserves existing agent restart semantics.
- Pi exact-132a W02 host-profile correction — the target correctly publishes worker-15 under shard 0f, but the gateway unconditionally reports the QEMU six-bit profile and makes structured discovery expect 03. Add an explicit generated Worker runtime profile selection, retain the QEMU default and select the existing eight-bit Pi profile for managed Pi benchmark gateways. Preserve the shard algorithm, namespace, bounds response shape, authentication, broker/pool limits, workload, readiness predicates and evidence classes. Focused CLI/default/profile bounds and managed-launch tests must cover both targets; actual Pi discovery and pressure remain physical evidence.
- Cargo.toml + crates/cohesix-worker-evidence/** — add a host-only bounded parser/validator shared by Rust host consumers. It represents transport/action outcome separately from declaration (`model-only` or `executable`), lifecycle (`absent`, `queued`, `starting`, `ready`, `closing`, `faulted`, or `terminal`), artifact (`missing`, `verified`, or `mismatch`), receipt (`none`, `pending`, `confirmed`, `rejected`, or `stale`), integration obligation/observed mode, and execution proof (`none`, `host-model`, `qemu`, or `fresh-pi`). It validates record kind and its required/forbidden field matrix, role, public instance id, slot, logical lease epoch, supervisor generation, cap generation, receipt sequence, ABI/schema version, target class, dependency-graph and Worker-integration record hashes, kernel/root/driver/CYW43/Worker archive/image-manifest/image hashes, record bounds, duplicate identity, and stale generation without exposing raw badges, CPtrs, capability values, or secrets. Worker-runtime release eligibility is derived separately from artifact state plus satisfied role/release compatibility rows and the matching QEMU/Pi component, root-TCB, and full-system acceptance graph; a missing or mismatched kind/hash/schema/target/evidence layer is a typed failure, never a downgraded proof class, and this release status never implies production use-case acceptance.
- apps/cohesix-proto/src/lib.rs — provide stable canonical role labels, strict parse/round-trip behavior, and `ALL_ROLES`; preserve `Role::Worker` compatibility as canonical `worker-heartbeat`. WorkerBus recognition never implies executability, and profile-dependent declaration/lifecycle/receipt/proof state does not enter this protocol-label crate.
- tools/coh-rtc/src/** + generated clients/docs — generate the executable-role matrix, host-integration dependency graph, Worker ABI/evidence schema versions, maximum live tasks, canonical sharded telemetry template, legacy-alias gate, lifecycle vocabulary, receipt bounds, archive identity, and proof vocabulary from the selected profile. Rust, Python, REST, and UI consumers use the same generated JSON schemas and conformance vectors; direct-TCP local manifests remain expectations, while remote declarations come from bounded remote metadata and proof comes only from hash-matched Worker plus per-row Worker-integration evidence.
- crates/cohsh-core/** + apps/cohsh/** + scripts/cohsh/** — support `lora`/`worker-lora` in the existing spawn/kill flow through `/queen/ctl`, keep WorkerBus target spawn deterministically rejected as model-only, discover canonical sharded Worker paths, render queued/starting/ready/closing/faulted/terminal separately, and never treat a successful control write as READY. Ticket mint/attach for WorkerBus remains session/model authority and never task-creation proof; help, generated grammar, transcripts, and ACK/ERR/END fixtures land together.
- apps/coh/** — preserve existing GPU/PEFT transport or host-action `status` meanings and add independent declaration, lifecycle, artifact, receipt, and proof fields. Connected receipt-bearing GPU lease and PEFT flows explicitly select or spawn the matching WorkerGpu/WorkerLora, wait for READY within the generated bound, submit the strict version-2 record on the existing host-ticket path, and correlate grant/renew/release or export/import/activate/rollback terminal results with bounded Worker receipt ids and canonical telemetry paths. Direct/local flows remain host-only; a successful write advances only to queued/request-admitted, never READY or target-accepted.
- apps/root-task/src/ninedoor.rs + apps/host-ticket-agent/src/{claim,lib,main,status,wal}.rs — make root's existing `spec.snapshot` the canonical enriched version-2 admitted projection and forbid execution from raw request bytes. Add the local single-agent lock/fence and crash-safe version-2 `prepared -> executing -> provider-result-persisted -> result-published -> terminal/cursor` journal for exactly the seven receipt-bearing GPU/PEFT actions, with action-specific observe/reconcile recovery. Separate v2 Worker lifecycle from GPU lease lifecycle so grant/renew/release never implicitly spawn/kill the receipt Worker and release/preempt result delivery precedes any independent teardown. Preserve version-1 behavior as a separately classified compatibility input; do not claim its general provider/federation durability is repaired here.
- apps/host-ticket-agent/src/** + provider executor helpers — replace every byte-indexed `str[..N]` output/error truncation touched by the v2 path with a shared UTF-8-boundary-safe bounded encoder; add multibyte, exact-boundary, oversized, provider-error, journal-recovery, and receipt-output tests so untrusted non-ASCII text cannot panic the agent or an executor.
- apps/coh/src/evidence.rs + apps/coh/src/evidence_timeline.rs — discover generated canonical paths; validate Worker image identity, lifecycle, receipts, integration obligations/observed modes, and exact-target evidence; emit `cohesix-worker-observation/v1` for live/host-model observations and import but never synthesize the distinct worker-integration, target-component, root-TCB, full-system, or release records; and keep host, host-model, integration, QEMU, fresh-Pi, runtime-release, production-use-case, GPU, PEFT, provider, and CYW43 evidence separate. Missing or mismatched target or required integration evidence produces no proof and a typed blocker, never a degraded PASS.
- crates/host-cuda/** + apps/gpu-bridge-host/** — retain deterministic NVML-to-CUDA discovery/fallback and publish the existing GPU/model/LoRA snapshots with bounded generated operation, lease, model, and exact version-2 WorkerGpu receipt correlation when a receipt-bearing lease action names one. Classify mock/demo catalogs as `host-model`, zero-device/unavailable probes explicitly, and real NVML/CUDA inventory as provider `live`; a missing, malformed, unsafe, or unreadable live model registry yields explicit empty/unavailable state and never falls back to the demo catalog or implicitly activates the first model. Live TCP/REST publication resolves a non-placeholder secret reference before connection. The 26e role gate injects bounded provider results to prove all three result-to-Worker paths but does not promote inventory, publication, or a fixture result into GPU execution/device-isolation proof. Keep CUDA, NVML, model registry, adapter bytes, training, activation, and inference host-side; never call an internal Worker endpoint, derive READY from bridge publication, grant hardware caps, or imply that receipt-only WorkerGpu performs GPU work. Milestone 27b owns live GPU provider/executor conformance.
- apps/coh/src/peft/** + apps/host-ticket-agent/** — add `peft.export` through the existing bounded `coh` export helper and generated action allowlist; consume only root-admitted, exact-READY-Worker-pinned, local-hive version-2 records for all three GPU lease and all four PEFT actions; and produce the canonical immutable result digest. Make the local version-2 executor safe enough to prove every receipt path: confine canonical registry/export paths, reject symlinks/traversal, lock per registry/active pointer, use unique bounded temporary files with file/directory sync plus atomic rename where supported, preserve the prior active pointer until commit, record recoverable partial host/VM publish state, and verify adapter/manifest/base-model/job hashes before import or activation. Distinguish host action completion, VM request admission, Worker READY, Worker receipt confirmation/rejection/stale state, timeout, terminal fault, artifact identity, and target proof while preserving version-1 uncorrelated/federated action-result semantics. Executors use only the root-admitted canonical record, existing console/Secure9P paths, the v2 pre-execution journal, and bounded observation; disconnected/local direct work stays explicitly host-only and never synthesizes a Worker receipt. These fixture/local transaction tests do not provide the production PEFT registry, training, evaluation, scanning, runtime-reload, or provenance acceptance owned by Milestone 27d.
- apps/coh/src/mount.rs + generated `coh.mount` policy + release packaging/tests — add canonical sharded Worker roots and bounded dynamic Worker entries to the FUSE allowlist instead of relying on the legacy `/worker` root; run real direct-console and REST-backed Worker telemetry/receipt append/read/unmount/cleanup smokes through FUSE 3 on supported Linux packages and MacFUSE on advertised macOS packages. Resolve the current REST-backed write `EINVAL` limitation without broadening append-only offsets or target policy. Verify generated mount allowlists, dynamic telemetry bounds, request-auth, one-gateway-mount locking, disconnect behavior, and no generic POSIX create/rename/delete semantics; `--mock`, mount-directory creation, or library presence alone is not FUSE acceptance and a mount never supplies Worker readiness.
- apps/host-sidecar-bridge/** + apps/host-ticket-agent/src/executors/{systemd,docker,k8s}.rs + tools/cohesix-py/cohesix/integrations.py — preserve current schemas/actions and prove they do not drift or masquerade as Worker state while the dependency matrix classifies them as current primitives/integration patterns. Mock, probe, or basic command-adapter success cannot promote an action-airlock, self-healing, Kubernetes, systemd, or Docker use case. Milestones 27a/27b own delegated identity, writer fencing, disposable live-safe and negative fixtures, full provider/version conformance, rollback/fail-safe policy, and installable production deployment profiles; 26e must name those blockers rather than silently substituting mock data.
- host federation, SIEM/evidence, CAS/artifact, sidecar, and release surfaces — attach every shipped surface to its generated obligation and evidence lane. Preserve version-1 federation/fleet compatibility tests while classifying current action-completion as non-promotable until the later owner proves true pre-forward write-ahead persistence, enforced relay timeout, no pending-entry eviction, source-visible terminal receipt correlation, live metrics, and writer fencing; reject version-2 Worker receipt relay outright in 26e. Prove SIEM and evidence output is bounded/redacted/reconstructable, hash CAS/model refs without packaging payload secrets, and prove sidecar/provider readiness cannot parse as Worker READY. Optional or future integrations produce explicit unavailable/future records.
- apps/hive-gateway/** + crates/cohesix-rest/** + resources/openapi/hive-gateway.yaml — add optional declaration-only `WorkerRuntimeBounds` to the existing bounds response: role matrix, ABI/schema version, maximum live tasks, canonical telemetry template, and legacy-alias gate. Absence means `unknown`, never model-only. Add optional gateway `backend_class` (`host-model`, `console-projection`, or `unknown`) to status; even `console-projection` proves no target class. Add an explicit bounded `--worker-acceptance-evidence <path>`/generated-config import for a local evidence record or release-bundle acceptance file: require a size-bounded canonical regular file under the explicit operator/release root with no symlink traversal, validate its `record_kind`, complete hashes, target, and schema through `cohesix-worker-evidence`, then expose only a redacted optional `worker_acceptance` summary on the existing status response. Absence or validation failure yields no proof and a typed diagnostic. Live lifecycle/receipts stay on existing LS/CAT/TAIL namespace projections. Add canonical `/shard` post-control cache invalidation and backward-compatible absence tests; add no Worker REST action, direct Worker RPC, authority-bearing route, or optimistic success state.
- apps/swarmui/** + tools/swarmui-ui-tests/** — stop inferring Worker roles from id prefixes or defaulting generic `worker-*` ids to Heartbeat. Render declaration, lifecycle, receipt, artifact, and proof separately from structured generated data; consume proof only from the gateway's shared-validator-backed optional `worker_acceptance` summary; version and migrate older model-only replay/snapshot fixtures so absent fields never default to READY; keep unrelated workbench redesign in Milestone 27f.
- tools/coh-rtc/src/codegen/cohesix_py.rs + tools/cohesix-py/cohesix/generated.py — generate Worker declarations, ABI/host-ticket/evidence schema versions, maximum live tasks, sharding data, receipt bounds, and `/shard` mount permission. Add a typed bounded `cohesix/worker.py`; add existing-path `worker_spawn`, `worker_observe`, and bounded `worker_wait` APIs for Heartbeat/GPU/LoRA; reject WorkerBus spawn; and retain existing GPU lease entrypoints as compatibility wrappers over the same generated control and ticket projections.
- tools/cohesix-py/cohesix/client.py + receipts.py + evidence.py — add grant/renew/release WorkerGpu and export/import/activate/rollback WorkerLora receipt consumers that explicitly bind a READY Worker through the existing host-ticket path while keeping `execution_location=host`; wait for and validate the root-admitted request, lease/Worker identity, terminal provider result, canonical result digest, Worker receipt, target manifest/image identity, and evidence reference. A successful append, local ACK, subprocess exit, local argument summary, unknown manifest, or `/proc` snapshot may be recorded only as a client transcript/observation and is never named or serialized as the authoritative receipt. Never invent or rebind a VM receipt when disconnected or after Worker teardown.
- tools/cohesix-py/cohesix/backends.py + orchestration.py + playbooks.py + tests/examples/docs — classify MockBackend as `host-model`, REST from gateway `backend_class`, and TCP/filesystem as projection/unknown; model Heartbeat/GPU/LoRA lifecycle/receipts and reject WorkerBus in mocks; keep high-count playbooks explicitly control-model rather than task-creation proof; expose the typed API and host-only PEFT boundary.
- apps/nine-door/src/host/** + Hive Gateway mock — mirror the generated Heartbeat/GPU/LoRA grammar and structured lifecycle/receipt records for compatibility tests, reject WorkerBus spawn, and mark every mock Worker `host-model`. Generic provider records such as `/host/... state=ready` cannot parse as Worker READY and mocks claim no image/task/MCS/fault/QEMU/Pi execution.
- apps/host-sidecar-bridge/** + apps/sidecar-bus/** — keep provider/link readiness and WorkerBus session/model state independent of executable Worker lifecycle. These are regression-only surfaces in 26e: add no task-creation path, and prove their `ready`/linked/provider records cannot parse as Worker READY or target proof.
- apps/coh-status/src/lib.rs + read-only tests — keep 26e to the existing library/replay surface: consume the shared Worker validator and generated canonical paths, replace the current generic `/queen/ctl`/legacy-`/worker` transcript with read-only canonical `/shard` and evidence fixtures, and prove no authority command or inferred proof exists. Do not add or claim a live `coh-status` binary here; Milestone 40 owns that standalone read-only CLI.
- scripts/rest_perf_harness.py + tests/test_rest_perf_harness.py — add explicit `host-model` and `executable` population modes. Synthetic high-count workloads remain host-model; executable mode obeys generated `max_live_tasks`, discovers real structured READY instances through canonical `/shard` paths, forbids synthetic id expansion, records requested/discovered/READY populations plus backend/proof class, and calls a control write `admitted` rather than `accepted`. Starting QEMU alone never yields QEMU proof.
- scripts/cohesix-build-run.sh + scripts/ci/host_integration_run.sh + scripts/release_bundle.sh — add `host-ticket-agent` and every selected-profile host tool explicitly to source-build/staging lists; execute selected target-session dependency rows and emit strict Worker-integration records; add verification-only `--verify-worker-acceptance`, Worker QEMU/Pi component, root-TCB QEMU/Pi, and full-system QEMU/Pi evidence inputs. Generate an exact named host-tool/image/evidence manifest and require externally supplied host-tool directories to match it; a missing required binary, Worker image, schema, or evidence file fails rather than being silently skipped or accepted because the directory is non-empty. Hash-validate the dependency graph and every role/release-required integration record plus `cohesix-worker-images.cpio`, its image manifest, ABI versions, MCS driver archive/manifest, CYW43 coexistence record, and every target acceptance input for selected executable 26e profiles. The release manifest selects the complete canonical Pi 4 SD stage by an exact compiler-owned file list, validates the sealed primary/fallback image identity against the current source commit, and rejects omitted, extra, linked, or stale stage files. Linux release production requires an argument-selected remote ARM64 builder, a source-bound exact host-tool provenance manifest, and remote creation plus local byte verification of the final tarball. Packaging alone yields artifact `verified` and execution proof `none`; it may report Worker-runtime release eligibility only after the matching integration/component/root/system graph exists, and it cannot emit the final release-accepted record before `m26e-mcs-smp-target-acceptance` or copy stale evidence onto a different host profile, provider, kernel, root image, driver archive, Worker archive, manifest, dependency graph, or CYW43 record.
- canonical host/Worker/PEFT/interface/release docs and fixtures — document the shared state axes, existing-authority projections, host-only GPU/PEFT boundary, canonical sharded paths, evidence promotion, replay migration, and release requirements. No CYW43/SDIO timing, state-machine, restart, packaging, image-build, trace-normalization, or proof-classification file may be edited; this task consumes only its frozen artifact identity.
Commands:
- cargo test -p cohesix-worker-evidence
- cargo test -p nine-door -p coh-status
- cargo test -p cohsh-core -p cohsh
- cargo test -p host-cuda
- cargo test -p coh --features fuse,nvml
- cargo test -p gpu-bridge-host -p host-ticket-agent -p hive-gateway -p cohesix-rest
- cargo test -p host-sidecar-bridge -p sidecar-bus
- cargo test -p cohesix-proto
- cargo check -p swarmui --bin swarmui
- cargo test -p swarmui --tests
- python3 scripts/ci/check_swarmui_dependencies.py
- npm --prefix tools/swarmui-ui-tests test
- python3 -m pytest -q tools/cohesix-py/tests
- python3 -m pytest -q tests/test_rest_perf_harness.py tests/test_release_bundle.py tests/test_worker_task_evidence.py tests/test_worker_image_pipeline.py
- scripts/cohsh/run_regression_batch.sh
- cargo test -p coh-rtc
- scripts/ci/host_integration_run.sh --matrix configs/host_integration_acceptance.toml --mode live --target qemu --target-session out/m26e-qemu/target-session.json --observations out/m26e-qemu/host-integration-observations.json --state-dir out/host-integration/m26e-qemu
- scripts/ci/host_integration_run.sh --matrix configs/host_integration_acceptance.toml --mode live --target pi4 --target-session out/m26e-pi4/target-session.json --observations out/m26e-pi4/host-integration-observations.json --state-dir out/host-integration/m26e-pi4
- scripts/check-generated.sh
Checks: Heartbeat/GPU/LoRA use the existing spawn, kill, namespace, console, policy, and ticket paths, while WorkerBus target spawn returns an existing-form deterministic model-only error; every host surface agrees on role, public instance id, slot, epoch, supervisor generation, cap generation, lifecycle, receipt, artifact, integration obligation/observed mode, execution proof, and separately derived runtime-release versus production-use-case state; control ACK proves only admission, `implemented = true` only executable declaration, READY only live runtime state, host-model only modelling, and QEMU/fresh-Pi proof only matching evidence; absent REST bounds mean unknown and gateway connection/QEMU launch never imply proof; generic ids are never inferred to be Heartbeat; GPU lease ACTIVE, bridge publication, ticket success, PEFT completion, FUSE mount, provider `ready`, package presence, or mocks cannot independently promote READY or target proof; connected GPU grant/renew/release and PEFT export/import/activate/rollback fixtures obtain the exact bounded WorkerGpu/WorkerLora confirmed/rejected/stale receipts without moving host hardware/registry/training/inference authority; mandatory live `worker-control`, `gpu-receipt-path`, and `peft-receipt-path` target-session rows pass, while every advertised FUSE/systemd/Docker/Kubernetes/federation/SIEM/CAS/sidecar/release/provider surface records its exact current mode and later blocker rather than being promoted by compatibility; canonical `/shard` invalidation, sharding, version-1/version-2 accepted-schema matrices, local-only v2 rejection, root-pinned admitted projections, crash-safe v2 journal recovery, replay retention on existing host-ticket status/deadletter paths, validated gateway evidence-file import, SwarmUI proof sourcing, and ACK/ERR/END fixtures pass; absent, wrong-kind, stale, forged, duplicate, late, oversized, wrong-role, wrong-generation, wrong-host-profile, wrong-provider-mode, wrong-target, wrong-ABI, hash-mismatched, mode-substituted, and secret-bearing records fail deterministically; release artifacts expose no ticket, host secret, raw badge, CPtr, or capability value; no CYW43 behavioral contract or evidence classification changes.
Deliverables: One generated protocol-faithful host Worker state/dependency contract; target-session per-row Worker-integration evidence; LoRA support across all four Cohesix PEFT receipt actions and Rust/Python/REST/UI compatibility projections; exact GPU/PEFT result-to-Worker correlation; canonical FUSE `/shard` compatibility; crash-safe local v2 execution; honest current modes for every shipped/future host surface; hash-bound Worker-runtime release inputs; and host tools ready for the separate exact QEMU/fresh-Pi promotion gate without claiming production provider/use-case completion.
Title/ID: m26e-python-library-as-built-compatibility
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / Python SDK as-built compatibility gate
Goal: Verify and, where required, correct the non-authoritative `cohesix` Python package against the freeze-bound 26e generated Worker, integration, receipt, evidence, namespace, and backend contracts without creating a second protocol or authority path.
Inputs: `m26e-host-worker-integration`, configs/sel4/profiles.toml, configs/root_task.toml, configs/root_task_pi4_uboot_aarch64.toml, tools/coh-rtc/src/codegen/cohesix_py.rs, configs/generated/**, generated Worker/integration schemas and conformance vectors, tools/cohesix-py/pyproject.toml, tools/cohesix-py/cohesix/**, tools/cohesix-py/tests/**, resources/openapi/hive-gateway.yaml, configs/host_integration_acceptance.toml, scripts/ci/host_integration_run.sh, scripts/release_bundle.sh, docs/PYTHON_SUPPORT.md, docs/HOST_API.md, docs/INTERFACES.md, and the accepted QEMU/Pi `worker-control`, `gpu-receipt-path`, and `peft-receipt-path` integration records.
Changes:
- tools/coh-rtc/src/codegen/cohesix_py.rs + tools/cohesix-py/cohesix/generated.py + configs/generated/cohesix_python_{qemu_smp_production,pi4_production}.json + scripts/check-generated.sh + tools/cohesix-py/tests/test_generated_contract.py — keep the wheel's generated module target-neutral and emit a versioned target-qualified `cohesix-python-profile/v1` contract for each selected resolved manifest. The profile contract, not a universal wheel constant, binds manifest hash, canonical role labels, executable-role matrix, Worker ABI/host-ticket/evidence schema versions, `/shard` paths and legacy-alias gate, lifecycle/receipt/proof vocabularies, operation and byte bounds, maximum live tasks, and host-integration modes. Extend the generated-artifact guard to resolve `configs/root_task.toml` through `qemu_smp_production` and `configs/root_task_pi4_uboot_aarch64.toml` through `pi4_production` into isolated temporary outputs, then byte-compare both committed target contracts in addition to the target-neutral default output; no target contract may be hand-edited or inferred from the other target. Static defaults are bounded fallback expectations only and cannot establish live target identity or proof; stale, hand-maintained, missing, one-sided, or mismatched contracts fail generated drift checks.
- tools/cohesix-py/cohesix/{backends.py,client.py,worker.py,receipts.py,evidence.py,orchestration.py,playbooks.py} + focused tests — load an explicit target-qualified contract or bounded remote metadata for live use and verify Mock, filesystem, TCP, and REST behavior against the same fixtures. Cover Heartbeat/GPU/LoRA spawn, observe, wait, receipt, teardown, and stale-generation behavior; deterministic WorkerBus spawn refusal; canonical sharding; optional REST bounds and backend-class absence as `unknown`; version-1 compatibility versus local-only version-2 Worker receipts; all three GPU and four PEFT actions; and strict separation of request admission, READY, provider completion, Worker receipt, artifact verification, QEMU/Pi proof, runtime-release acceptance, and production-use-case acceptance.
- scripts/ci/python_compat_run.sh + configs/host_integration_acceptance.toml — add a bounded `python-sdk-projection` release-required lane that runs the Python client through the existing target-session integration fixtures for QEMU and Pi and emits the existing `cohesix-worker-integration-evidence/v1` record. Package/backend conformance covers the minimum supported Python 3.11 and canonical macOS release-host Python 3.13; each target-session record names the exact interpreter/platform, shared wheel hash, and matching target-qualified profile-contract hash. The lane may consume but never replace the direct target role-required records, and it cannot promote external CUDA/NVML, PEFT, FUSE, systemd, Docker, Kubernetes, federation, or other provider modes.
- tools/cohesix-py packaging/tests + scripts/release_bundle.sh — install and import the core package and declared `integrations`, `ml`, and `dev` extras on the Python 3.11/3.13 host matrix, build one target-neutral wheel, install that wheel into an isolated environment for import/public-entrypoint smoke, and emit an exact package manifest containing the wheel and QEMU/Pi profile-contract hashes. `dev` remains test-only and is excluded from deployed requirements; missing optional runtimes return typed unavailable rather than silently selecting mocks.
- docs/PYTHON_SUPPORT.md + tools/cohesix-py/README.md + docs/TEST_PLAN.md — document the 26e Worker APIs, target-neutral wheel/profile-contract model, as-built proof boundaries, supported backend matrix, compatibility/migration rules, and the distinction between Python projection compatibility and target or provider acceptance.
Commands:
- python3 -m pip install -e 'tools/cohesix-py[integrations,ml,dev]'
- python3 -m pip check
- python3 -m pytest -q tools/cohesix-py/tests
- python3 -m pip wheel --no-deps --wheel-dir out/python-wheels tools/cohesix-py
- scripts/ci/python_compat_run.sh --wheel-smoke --wheel-dir out/python-wheels --package-manifest out/python-compat/m26e-python-package.json --state-dir out/python-compat/m26e-wheel
- scripts/ci/python_compat_run.sh --python-matrix 3.11,3.13 --target qemu --profile-contract configs/generated/cohesix_python_qemu_smp_production.json --package-manifest out/python-compat/m26e-python-package.json --wheel-dir out/python-wheels --matrix configs/host_integration_acceptance.toml --target-session out/host-integration/m26e-qemu/integration/worker-control.json --state-dir out/python-compat/m26e-qemu
- scripts/ci/python_compat_run.sh --python-matrix 3.11,3.13 --target pi4 --profile-contract configs/generated/cohesix_python_pi4_production.json --package-manifest out/python-compat/m26e-python-package.json --wheel-dir out/python-wheels --matrix configs/host_integration_acceptance.toml --target-session out/host-integration/m26e-pi4/integration/worker-control.json --state-dir out/python-compat/m26e-pi4
- scripts/check-generated.sh
Checks: The same isolated-wheel smoke and public API pass on Python 3.11 and 3.13; each target-qualified contract matches its selected resolved manifest byte-for-byte where specified, while the shared wheel remains target-neutral; all supported backends preserve ACK/ERR/END, bounds, canonical paths, role identity, lifecycle, receipt, and evidence semantics; existing public compatibility wrappers remain valid or receive an explicit versioned migration; malformed, oversized, absent, unknown, wrong-version, wrong-role, stale-generation, wrong-target, wrong-contract, hash-mismatched, client-authored, and secret-bearing inputs fail deterministically; static fallback defaults and mocks remain non-proof `host-model`; no Python ACK, local file, subprocess result, provider state, or JSON object can become READY, an authoritative receipt, target proof, runtime release acceptance, or production-use-case evidence; QEMU/Pi Python rows bind the same wheel to their respective generated profile contract and target-session records but remain projection evidence only.
Deliverables: One clean target-neutral wheel and exact package manifest, generated QEMU/Pi profile contracts, backend conformance tests, separate QEMU/Pi `python-sdk-projection` records, and release gating that proves the shipped Python SDK matches each 26e as-built target without widening Cohesix authority.
Title/ID: m26e-worker-target-evidence-promotion
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / exact QEMU and Pi Worker acceptance
Goal: Emit separate QEMU-accepted and Pi-accepted component records for the three configured executable roles only after exact-image evidence proves real IPC, faults, complete teardown, and fresh-generation recreation; do not promote release acceptance yet.
Inputs: all preceding 26e target-runtime Worker tasks through `m26e-host-worker-integration`, matching live `worker-control`, `gpu-receipt-path`, and `peft-receipt-path` Worker-integration records for each target, selected QEMU/Pi SMP+MCS builds and manifests, positive exact-image CYW43 closure plus the matching 26e MCS-driver coexistence record, scripts/ci/test_plan_run.sh, scripts/pi4_gate_proof.sh, exact image identities, docs/TEST_PLAN.md, canonical Worker/security/interface docs. The adjacent `m26e-python-library-as-built-compatibility` task must finish any Python-only codegen/package corrections before the shared artifact freeze, but its PASS/FAIL record is not target-component evidence and cannot substitute for or alter this gate.
Changes:
- scripts/worker_task_evidence.py + scripts/m26e_qemu_pressure.sh + tests/test_worker_task_evidence.py — replace the pressure runner's inline target-session synthesis with the standalone `emit-qemu-target-session` command. It accepts only the repository root, verified QEMU output, resolved manifest, generated topology, and a new output directory; validates the immutable launch record and exact launch/Worker/driver/archive bytes, stable git-visible source inventory, Worker ABI identity, and topology-to-manifest parity; derives the QEMU CYW43 not-applicable binding and current exact target-session schema without caller-supplied hashes; and publishes each artifact atomically without overwriting an existing session directory.
- scripts/pi4_gate_proof.sh + scripts/worker_task_evidence.py + scripts/rest_perf_harness.py + focused tests — capture one fresh Wi-Fi boot's serial and packets concurrently, emit a positive CYW43 v2 record only after the exact live gate passes, and finalize those immutable bytes into a canonical Pi target-session bundle. The finalizer independently validates the clean v5 stage/image graph, generated topology, source and Worker ABI identities, archives/manifests, latest boot marker, live outcomes, and controlled pcap before exclusive publication. A later same-image GENET boot supplies its own current runtime/pcap; qualified performance freezes and revalidates every input, binds the exact session/topology/Worker manifest to the live census and role exemplars, and cannot turn build, stage, offline, stale, caller-authored, or QEMU evidence into Pi proof. The separately collected Pi Worker component remains a full-milestone acceptance prerequisite and is neither consumed nor claimed by this performance lane.
- scripts/worker_task_evidence.py + tests/test_worker_task_evidence.py + docs/TEST_PLAN.md — create the emitter/validator and tamper/mode/hash/target tests for `cohesix-worker-task-evidence/v1` with `record_kind=target-component`, exactly one proof target/class, a sorted bounded list of the three exact live role-required Worker-integration records, source/resolved-manifest/kernel/root/MCS-driver-archive/MCS-driver-manifest/CYW43-coexistence-record/Worker-archive/Worker-image-manifest/Worker-image hashes, one detailed live Heartbeat/GPU/LoRA exemplar, the exact topology digest and complete compiler-declared temporal-task/fault-registry seal for the aggregate 256-Worker population, role/slot/epoch/supervisor-generation/cap-generation/badge/core/SC/object inventories, bounded event outcomes, raw-artifact hashes, PASS/FAIL, and blockers. The generic evidence-list bound remains unchanged; only the topology-derived list may exceed it, and any count, order, identity, role-class, driver, service, critical-TCB, or registry drift fails closed.
- QEMU target gate — prove all three mandatory roles through the direct target authority/observation path, including Heartbeat progress, fixture-backed but live root-to-Worker GPU grant/renew/release and LoRA export/import/activate/rollback confirmed/rejected receipts for success, failure and expiry, plus stale root disposition after each action's pinned Worker retires before the result arrives; also prove two sequential same-role generations, simultaneous second-live-slot and maximum-slot refusal, bounded control/receipt paths, combined notifications, durable-completion publish/signal ordering, budget exhaustion/timeout attribution, fault before READY/during IPC, forbidden-blocking-send refusal, stale-record revocation, no post-revoke activity/leak, and fresh generation under four-core SMP+MCS. Rust/Python/REST/UI/FUSE compatibility records are separate projections and cannot raise or block this runtime claim unless an explicit release profile independently requires them.
- fresh Pi target gate — prove the identical direct runtime and receipt-path matrix on the exact flashed/booted image while preserving serial, local-seat, TCP, fatal, driver, and Queen liveness; require positive exact-image CYW43 closure plus the matching MCS coexistence record by immutable artifact/hash without merging proof classes. An accepted CYW43 blocker cannot produce Pi component PASS, and no host integration record can substitute for Pi execution.
- generated/docs gate — publish only separate QEMU/Pi component acceptance records and update as-built role wording only when the selected exact hashes pass; missing target evidence cannot degrade to host/model PASS, and this task cannot emit `release-accepted`.
Commands:
- python3 scripts/worker_task_evidence.py emit-qemu-target-session --repo-root . --qemu-out out/cohesix --resolved-manifest configs/generated/root_task_resolved.json --topology configs/generated/root_task_topology.json --out-dir out/m26e-qemu/session
- scripts/pi4_gate_proof.sh --skip-build --serial-device "$PI_SERIAL_DEVICE" --log "$PI_WIFI_SERIAL_LOG" --require-wifi-ready --require-driver-task-proof --network-interface "$PI_CAPTURE_INTERFACE" --network-capture-out "$PI_WIFI_NETWORK_CAPTURE" --gateway-status-url "$COH_REST_URL" --gateway-target-host "$PI_WIFI_TARGET_IP" --runtime-dma-proof-out "$PI_WIFI_RUNTIME_DMA_PROOF" --cyw43-coexistence-record-out "$PI_WIFI_CYW43_RECORD"
- python3 scripts/worker_task_evidence.py emit-pi4-target-session --repo-root . --runtime-proof "$PI_WIFI_RUNTIME_DMA_PROOF" --cyw43-coexistence-record "$PI_WIFI_CYW43_RECORD" --max-age-secs 21600 --out-dir "$PI_SESSION_DIR"
- python3 scripts/worker_task_evidence.py collect-pi4-component --target-session "$PI_SESSION_DIR/target-session.json" --generated-inventory out/pi4-sd/cohesix-root-task-topology.json --runtime-proof "$PI_RUNTIME_DMA_PROOF" --network-capture "$PI_NETWORK_CAPTURE" --transport genet --integration-dir "$PI_INTEGRATION_DIR" --max-age-secs 21600 --out-dir "$PI_COMPONENT_DIR"
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26e-worker-qemu
- python3 scripts/worker_task_evidence.py validate --target qemu --evidence out/test-plan/m26e-worker-qemu/worker-task-evidence.json
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26e-worker-pi4
- python3 scripts/worker_task_evidence.py validate --target pi4 --evidence out/test-plan/m26e-worker-pi4/worker-task-evidence.json
- scripts/check-generated.sh
Checks: The QEMU session emitter refuses stale launch bytes, manifest/topology drift, malformed Worker/driver archives, aliases, source drift, unignored repository output, and any existing output directory before target execution; it derives every digest from exact bytes and emits only the current source-inventory, Worker-ABI, QEMU-CYW43, and target-session records. The complete topology/fault-registry seal covers all 256 Worker tasks plus the generated non-Worker tasks while the component retains only the three bounded live role exemplars; neither layer substitutes for the other. Heartbeat/GPU/LoRA each reach READY and complete their exact role contract on both exact targets through direct `cohsh` control/observation, root-admitted host-ticket v2 records, the host-ticket agent's crash-safe local receipt path, and the shared evidence validator; GPU grant/renew/release and PEFT export/import/activate/rollback receipt fixtures correlate with the complete root-resolved Worker identity/result digests without moving host execution or proving the external provider; confirmed/rejected live receipts and stale root fencing/replay behavior are deterministic across teardown; fault/timeout/revoke identity is unambiguous; combined notification, durable completion, stale-generation, and no-blocking-send tests pass; complete teardown leaves zero caps/mappings/pending records/signals/Replies/SCs/execution; recreation uses a fresh supervisor generation; operator and MCS-driver liveness hold; WorkerBus remains model-only; configured, queued, READY, host-model, projection compatibility, QEMU-only, or Pi-only state cannot satisfy runtime release acceptance, and runtime release acceptance cannot satisfy a production use-case row.
Deliverables: Separate exact QEMU and fresh-Pi Worker component evidence/acceptance records closing the Milestone 26d general-Worker execution-truth gap without premature release promotion.
Title/ID: m26e-root-tcb-target-proof
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / target containment and regression proof
Goal: Prove the ordered service/Worker split reduces root authority and preserves deterministic QEMU/Pi behavior under normal, pressure, and injected-fault conditions.
Inputs: `m26e-worker-target-evidence-promotion`, selected generated profiles and images, scripts/ci/test_plan_run.sh, scripts/rest_perf_harness.py, docs/TEST_PLAN.md, docs/BENCHMARKS.md, docs/audit/M26D_ROOT_TCB_BOUNDARY_AUDIT.md.
Changes:
- Production manifest and paired-kernel capacity parity (2026-09-08): refresh
only `seL4/build_UBOOT` from the pinned external seL4 16 production profile,
retaining its default immutable Pi image input. Align QEMU/Pi enabled
production features and common scheduling policies at the existing safe
256-Worker execution capacity and maximum 8-bit sharding. Preserve selected
kernel SC object sizes, hardware driver topology, measured WCET envelopes,
memory accounting and fault/operator reserves. Document every remaining
target difference and guard common feature/resource parity. This authorizes
the manifest/kernel compatibility repair; it does not expand execution
counts beyond admitted inventories or substitute static/QEMU proof for Pi.
- root-task/service/Worker tests — add critical-TCB reserve, cap-inventory, W^X, IPC-bound, wrong-badge, notification-coalescence, stale-frame, fault-injection, complete teardown, fresh-generation recreation, shutdown, replay, cancellation, and pressure coverage for every split child.
- scripts/ci/test_plan_run.sh + docs/TEST_PLAN.md — add separate host/model, QEMU execution, fresh Pi execution, operator-liveness, and fault-containment gates; emit separate `cohesix-root-tcb-acceptance/v1` QEMU/Pi records with `record_kind=root-tcb`, exactly one target, and bindings to the exact kernel, root, MCS driver archive/manifest, CYW43 coexistence record, Worker archive/image manifest/images, generated topology, raw evidence hashes, and observed critical-TCB/cap/SC/Reply inventories.
- docs/BENCHMARKS.md + evidence packs — archive before/after TCB inventory, authority matrices, latency, pressure, and same-harness QEMU/Pi results with atomic change-set and pre-change baseline identity.
Commands:
- cargo fmt --all -- --check
- cargo clippy --workspace --all-targets -- -D warnings
- cargo check --workspace
- cargo test --workspace -- --test-threads=1
- scripts/check-generated.sh
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26e-root-tcb-qemu
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26e-root-tcb-pi4
- python3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --log-dir out/bench --log-prefix m26e-root-tcb-qemu
Checks: generated and observed cap/SC/Reply inventories agree; root-control, root-fault, root-emergency, root-worker-supervisor, root-driver-supervisor, root-worker-executor-gpu, and root-worker-executor-lora each retain independent admitted progress; each child runs in the selected image, contains injected faults/timeouts, completes its 26e teardown/containment, loses stale authority, returns or revokes any service-only donated time, and cannot bypass serialized policy; QEMU and fresh Pi evidence preserve console/network/driver/operator behavior and separated proof lanes; the accepted split measurably reduces root authority without an unbounded latency, temporal-reserve, or TCB regression; each root-TCB acceptance record validates only against the exact immutable artifacts it names.
Deliverables: Separate hash-bound QEMU/Pi root-TCB acceptance records closing the reopened Milestone 25 root-service/Worker task-isolation claims and establishing the prerequisite for final 26e and Milestone 33 acceptance.
Title/ID: m26e-mcs-smp-target-acceptance
Milestone: Milestone 26e — Root-Service Compartmentalization + Worker Task Isolation + SMP+MCS Temporal Isolation / full-system SMP+MCS target acceptance
Goal: Accept the single four-core SMP+MCS operational architecture on QEMU and Pi 4 using the real root, service, Worker, and driver topology under normal, overload, timeout, fault, complete task teardown, fresh-generation recreation, and operator-liveness conditions, as a verification-only gate over the frozen artifacts produced by preceding 26e implementation tasks.
Inputs: `m26e-mcs-abi-foundation`, `m26e-worker-resource-admission-critical-tcbs`, `m26e-driver-runtime-mcs-port-and-cyw43-coexistence`, `m26e-python-library-as-built-compatibility` for the independent Python package gate, `m26e-worker-target-evidence-promotion`, `m26e-root-tcb-target-proof`, all enabled 26e child images and generated task records, separate matching QEMU/Pi Worker component records, separate matching QEMU/Pi root-TCB acceptance records, matching QEMU/Pi `python-sdk-projection` compatibility records plus their target-qualified contracts and shared wheel/package manifest for any release profile that ships Python, positive exact-image CYW43 closure plus matching MCS coexistence record, configs/sel4/profiles.toml, configs/root_task*.toml, scripts/worker_task_evidence.py, scripts/release_bundle.sh, scripts/ci/test_plan_run.sh, scripts/rest_perf_harness.py, tests/test_release_bundle.py, docs/ROLES_AND_SCHEDULING.md, docs/TEST_PLAN.md, docs/BENCHMARKS.md, docs/audit/M26D_MCS_DECISION.md.
Changes:
- Release console convergence dispatch repair — the exact `a5ef48045` QEMU console canary passes, but the following filtered Cargo commands compile unrelated kernel integration binaries and fail to link ELF `_text`/`_end` symbols on macOS. Select the existing complete `host.root-task-qemu-features` library action as a console convergence regression and remove its ten overlapping filtered invocations. Preserve all separate ABI, console runtime, direct-GENET, service integration, transport and packaging checks, nonzero inventories and the canonical ban on filtered library suites. Regenerate the Test Plan projection and execute the selected regression actions. This changes only test dispatch; runtime, manifests, host tools, Python, benchmark workloads and target evidence requirements remain unchanged. Open P1 findings and independent review still block final release acceptance.
- final artifact-freeze gate — make no runtime, generated-policy, manifest, kernel-profile, or image change in this task. Validate that the MCS-only profiles, per-core admission, seven critical root reserves including both Worker executor lanes, active/passive/Reply topology, child runtimes, and exact kernel/root/MCS-driver/CYW43/Worker-archive/Worker-image-manifest/Worker-image identities are unchanged from the preceding component and root-TCB records. Any hash or generated-output drift sends execution back to the owning implementation task and requires all affected evidence to be rerun before promotion.
- scripts/ci/test_plan_run.sh + scripts/worker_task_evidence.py — run the complete frozen topology on each target, then emit separate `cohesix-mcs-smp-system-acceptance/v1` QEMU/Pi records with `record_kind=full-system`, exactly one target, and bindings to the exact Worker component record, root-TCB record, kernel/root images, MCS driver archive/manifest, positive CYW43 coexistence record, Worker archive/image manifest/images, ABI schemas, full-system raw evidence, admission totals, timeout/fault/Reply outcomes, and performance/liveness results.
- configs/sel4/profiles.toml + build/release validators — verify that the already-produced four-core MCS contracts are the sole runtime/release profiles for QEMU and Pi 4 and that no non-MCS switch, compatibility profile, or fallback selection remains; do not modify the profile here.
- scripts/worker_task_evidence.py + scripts/release_bundle.sh + tests/test_release_bundle.py — create/extend Worker-runtime release promotion tests and, only after both full-system records validate, consume all six immutable QEMU/Pi Worker-component, root-TCB, and full-system records; recursively cross-check their role-required Worker-integration rows and complete artifact/evidence hash graph including the Worker image manifest; emit the `release-accepted` `cohesix-worker-release-acceptance/v1` record with `record_kind=release`, explicit scope `worker-runtime`, no singular target field, and exactly those six references; and exercise release verification. Missing either target or evidence layer, missing/wrong-mode role-required integration row, QEMU-only/Pi-only proof, stale hashes, wrong kernel/root/driver/Worker image or Worker image manifest, wrong ABI/resolved-manifest/CYW43 record, or artifact-only packaging fails closed. This record cannot satisfy the Milestone 27b production use-case release schema.
- scripts/release_bundle.sh + tests/test_release_bundle.py — independently verify every selected release-required projection through exact paths recorded in the generated package manifest. A release profile that ships Python must carry both exact `python-sdk-projection` records, the shared target-neutral wheel hash, and each record's matching target-qualified profile-contract hash; a missing, one-sided, stale, wrong-target, wrong-contract, or mismatched Python record fails Python packaging without entering, raising, lowering, or changing the six-reference Worker-runtime acceptance record.
- docs/ROLES_AND_SCHEDULING.md + docs/TEST_PLAN.md + docs/BENCHMARKS.md + evidence packs — record WCET/admission inputs, per-core totals/reserves, full topology, exact build/image identity, timeout/fault/restart results, operator-liveness results, and performance deltas without overstating upstream AArch64 or SMP verification.
Commands:
- cargo test -p sel4-sys -p sel4-runtime
- cargo test -p coh-rtc
- cargo test -p root-task --test schedule
- cargo test -p pi4-driver-abi -p pi4-driver-runtime
- scripts/check-generated.sh
- python3 scripts/sel4_profile.py validate --profile qemu_smp_production --build-dir out/sel4/profile-v2/qemu-smp-production --require-source --require-artifacts --for-release --for-runtime
- python3 scripts/sel4_profile.py validate --profile pi4_production --build-dir out/sel4/profile-v2/pi4-production --require-source --require-artifacts --for-release --for-runtime
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m26e-mcs-smp-qemu
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m26e-mcs-smp-pi4
- python3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --log-dir out/bench --log-prefix m26e-mcs-smp-qemu
- HIVE_GATEWAY_REQUEST_AUTH_TOKEN="$HIVE_GATEWAY_REQUEST_AUTH_TOKEN" .venv/bin/python scripts/rest_perf_harness.py --mode simulate --population-mode executable --benchmark-target pi4 --benchmark-transport genet --pi-runtime-dma-proof "$PI_RUNTIME_DMA_PROOF" --pi-network-capture "$PI_NETWORK_CAPTURE" --pi-cyw43-coexistence-record "$PI_CYW43_RECORD" --benchmark-evidence-max-age-secs 21600 --target-session "$PI_TARGET_SESSION" --no-qemu --no-gateway --rest-url "$COH_REST_URL" --tcp-host "$PI_TARGET_IP" --tcp-port 31337 --workers-min 256 --workers-max 256 --intensity-min 8 --intensity-max 8 --duration-mins 2 --base-rps 4 --max-inflight 32 --seed 2608 --no-transient-retries --strict-control-errors --error-budget-rate 0.01 --log-dir out/bench/pi4-genet --log-prefix m26e-pi4-genet-high
- python3 scripts/pi4_compare_driver_models.py --qemu-report "$QEMU_HIGH_REPORT" --pi-report "$PI_GENET_REPORT" --reference-unix-s "$(date +%s)" --max-age-secs 21600 --min-throughput-ratio 1.0 --genet-max-p95-ms "$GENET_SAME_HARNESS_P95_MAX_MS" --output out/bench/pi4-genet/qemu-pi-parity.json
- python3 scripts/worker_task_evidence.py validate-system --target qemu --worker out/test-plan/m26e-worker-qemu/worker-task-evidence.json --root out/test-plan/m26e-root-tcb-qemu/root-tcb-acceptance.json --run out/test-plan/m26e-mcs-smp-qemu --out out/test-plan/m26e-mcs-smp-qemu/system-acceptance.json
- python3 scripts/worker_task_evidence.py validate-system --target pi4 --worker out/test-plan/m26e-worker-pi4/worker-task-evidence.json --root out/test-plan/m26e-root-tcb-pi4/root-tcb-acceptance.json --run out/test-plan/m26e-mcs-smp-pi4 --out out/test-plan/m26e-mcs-smp-pi4/system-acceptance.json
- python3 scripts/worker_task_evidence.py promote-release --worker-qemu out/test-plan/m26e-worker-qemu/worker-task-evidence.json --worker-pi4 out/test-plan/m26e-worker-pi4/worker-task-evidence.json --root-qemu out/test-plan/m26e-root-tcb-qemu/root-tcb-acceptance.json --root-pi4 out/test-plan/m26e-root-tcb-pi4/root-tcb-acceptance.json --system-qemu out/test-plan/m26e-mcs-smp-qemu/system-acceptance.json --system-pi4 out/test-plan/m26e-mcs-smp-pi4/system-acceptance.json --out out/test-plan/m26e-mcs-smp/worker-release-acceptance.json
- scripts/release_bundle.sh --verify-worker-acceptance --worker-qemu-evidence out/test-plan/m26e-worker-qemu/worker-task-evidence.json --worker-pi4-evidence out/test-plan/m26e-worker-pi4/worker-task-evidence.json --worker-root-qemu-evidence out/test-plan/m26e-root-tcb-qemu/root-tcb-acceptance.json --worker-root-pi4-evidence out/test-plan/m26e-root-tcb-pi4/root-tcb-acceptance.json --worker-system-qemu-evidence out/test-plan/m26e-mcs-smp-qemu/system-acceptance.json --worker-system-pi4-evidence out/test-plan/m26e-mcs-smp-pi4/system-acceptance.json
- scripts/release_bundle.sh --verify-python-compatibility --python-package-manifest out/python-compat/m26e-python-package.json --python-qemu-evidence out/python-compat/m26e-qemu/python-sdk-projection.json --python-pi4-evidence out/python-compat/m26e-pi4/python-sdk-projection.json
- python3 -m pytest -q tests/test_release_bundle.py tests/test_worker_task_evidence.py
Checks: every active TCB has an admitted MCS budget/period/core, every passive service TCB has a bounded allowlisted donor/Reply/timeout chain to an admitted active context, every passive Worker has zero bound SC, exactly one allowlisted active executor donor, and a generation-scoped Reply path that returns donated time once, every linked driver uses its admitted MCS path, and all paths preserve correct ownership; aggregate demand preserves all seven critical reserves: root-control, root-fault, root-emergency, root-worker-supervisor, root-driver-supervisor, root-worker-executor-gpu, and root-worker-executor-lora; four-core QEMU and fresh Pi pass cold/warm boot, the aggregate 256-Worker READY seal with three detailed role exemplars, mixed load, budget exhaustion, timeout, fault, faulted-driver-call recovery, complete Worker task-instance teardown, fresh supervisor-generation recreation, SC/Reply/cap/mapping/record leak, operator-liveness, protocol-regression, GPU/PEFT receipt, and positive CYW43 behavioral-coexistence; QEMU additionally passes Conditional B2 full-population executable pressure driven through the three role exemplars, fresh Pi independently passes its exact-evidence-bound same-harness performance gate, and the target-neutral comparator rejects stale or mismatched provenance and decides QEMU/Pi parity from successful throughput and error budgets only; Conditional D separately qualifies only the host-model gateway comparator. Worker-runtime release promotion binds exactly the six target/root/system records and complete artifact graph, rejecting every missing, one-sided, stale, or mismatched input; independently, a profile cannot ship or advertise Python without both exact `python-sdk-projection` records, the shared wheel/package manifest, and the corresponding QEMU/Pi profile-contract hashes, and Python compatibility cannot raise or lower target, component, full-system, or Worker-runtime acceptance; no implementation or artifact changes occur after component evidence, and no operational classic scheduler path or profile remains. Any failure blocks closure and requires whole-change source/configuration reversion rather than a shipped fallback.
Deliverables: One target-qualified SMP+MCS scheduling architecture for QEMU and Pi 4, final `cohesix-worker-release-acceptance/v1` evidence, and no runtime scheduler rollback path.
Post-26d Benchmark Cadence (Milestones 26e+)
26d establishes the refreshed seL4 16 performance baseline. Later milestones must use that evidence as the rolling comparison point, but they must not turn every feature into a full hardware benchmark gate. Benchmarking after 26d is tiered:
- Full same-harness benchmark gate: required only when a milestone changes runtime scheduling, physical driver/runtime service, hot network paths, gateway broker behavior used by the canonical REST harness, or a new physical target. The run must compare against the latest accepted rolling baseline and archive QEMU/Pi or target-specific artifacts in
out/bench/ordocs/bench/as appropriate. - Targeted microbenchmark gate: required when a milestone adds bounded storage drains, namespace roots, read/write authorization checks, protocol projections, exporters, UI render loops, or evidence-pack processing that can add measurable overhead but does not change the physical network/runtime path.
- No runtime benchmark gate by default: applies to documentation-only, verification-only, schema-only, read-only inspection, and pure conformance milestones. These milestones may measure CI/proof/tool runtime or bounded command latency, but they do not rerun Pi/QEMU throughput unless their changes land in a runtime or gateway hot path.
Benchmark evidence must keep proof lanes separate: raw direct cohsh/TCP, REST/gateway overhead, QEMU semantic/capacity reference, Pi wired/GENET production parity, Pi Wi-Fi research/diagnostic evidence, storage/spool pressure, UI render cadence, and target-specific ENA/AWS proof are not interchangeable. Any claimed optimization must identify the moved layer and preserve Secure9P bounds, ACK/ERR/END grammar, manifest authority, HAL-only physical-device authority, no-retry accounting, and bounded queues.
Cadence by milestone family:
- 26e task isolation and SMP+MCS transition: full same-harness QEMU/Pi benchmark, timeout/fault-containment, admission, and operator-liveness gates because root-service IPC, network parsing, Worker execution, and the kernel scheduling model change together.
- 37 persistence (
m29-target-acceptance): targeted QEMU/Pi spool/settings and block-pressure gates; final Pi acceptance also reruns the established CYW43 same-harness workload against the exact accepted pre-persistence baseline, first with persistence idle and then under representative storage load. QEMU does not qualify Pi storage or Wi-Fi behavior, and 37 does not create a broader benchmark framework. - 29 verification (
m28-verification-ci): no runtime benchmark; track verification-gate runtime and proof reproducibility only. - 38 core-local scheduling (
m29a-pressure-and-target-proof): full same-harness QEMU/Pi benchmark gate with service-bucket counters and fresh target evidence. - 39 operator lanes (
m29b-pressure-and-target-proof): full latency/fairness gate under mixed serial, USB local-seat, TCP console, HDMI, diagnostics, network, telemetry, and persistence pressure; throughput claims remain tied to 26d/38 baselines and must not collapse separated proof lanes. - 27 read-only utilities: no full benchmark; require bounded command latency for inspect/diff/attest over representative evidence packs.
- 27a/28/28d/28e gateway authority/protocol work: gateway-focused latency/backpressure benchmarks for REST delegated writes, MCP resources/tools, and A2A task flows; full Pi hardware benchmark only if gateway results expose runtime-path regression.
- 27b–27e, 28a–28c and deferred 30–35: targeted provider/exporter, semantic extraction/capsule, AI-run-cost, inference, or fault-recovery timing where the milestone changes those paths; no full Pi/QEMU throughput gate by default.
- 27f UI workbench: UI render/backlog benchmark gate for Live Hive, replay, and inactive-view polling behavior.
- 40/41 field status (
m30-readonly-regressions,m30a-hw-status-regressions): bounded command-latency checks only. - 42 AI namespace (
m30b-ai-regressions): namespace-scale microbenchmarks for high-churn job/run roots; no full hardware benchmark unless the namespace provider changes hot runtime paths. - 43 AWS/ENA (
m31-ena-performance-closure): new-target benchmark gates; single-queue first-link evidence is not peak performance, and peak ENA claims require archived EC2 evidence tied to generated queue and service-bucket policy.
Milestone 27 — Operator Utilities: Inspect, Trace, Bundle, Diff, Attest
Status (2026-09-14): Complete — Lukas Bower explicitly approved closure on
the disclosed evidence: QEMU Stages 01–05 and live TCP/REST operator checks
pass; Pi Stages 01–02 pass, while the final-image Pi boot, live operator checks,
and Stages 03–05 remain unexecuted following failed serial recovery. The
completion record binds tested source
b54bdd2fcff97fe35c5e3a61faa4d5a761b2a1ac, evidence hashes, and the exact
decision. This closes the m27-* tasks without asserting full Pi qualification
or activating downstream milestones. DD30 remains P1 / ACCEPTED_RISK under
its separate approval; dynamic fault/wake remains UNEXECUTED. The stock Pi’s
positive signed-device requirement is excluded by the earlier owner decision.
Absent signed evidence still produces a typed non-attested result, never a
hash-based PASS; device-bound issuance remains the conditional reopened
m26-device-identity-attestation-closure task.
Delivery posture: Release A priority and the shared read-only foundation for the AI workflow and 27f showcase.
Why now (operator & adoption): After Milestone 26e closes the selected task/topology and evidence baseline, Cohesix needs deterministic tools to understand, reproduce, compare, and explain system behavior before it adds more production AI authority. Milestone 27 is deliberately read-only and does not wait for downstream Milestone 29 assurance or conditional Milestones 37 persistence, 38 service-turn scheduling, or 39 operator lanes. When persistence, proof witnesses, service buckets, operator-lane counters, or signed attestation are absent, the tools report typed unavailable or unknown state and preserve the source evidence class. Mutating authority hardening remains Milestone 27a, not a hidden prerequisite inside Milestone 27.
As-built alignment (2026-09-14): The current implementation adds
coh inspect, coh trace, coh diff, a fail-closed coh attest, and the thin
coh bundle alias. Canonical packs include bounded inspect observations,
optional host attachments and digests; timelines add scenario-aware case
summaries. Canonical trace capture supports live TCP and REST, with shared
offline consumers and preserved version-1 fixtures. See
the operator contract. The shared TPM2 signature verifier
and explicit proof classes are implemented. Final-source QEMU trace acceptance
passes; final-source Pi trace acceptance remains unexecuted under the completion
decision. Public measurements never produce attestation PASS.
This milestone delivers a small, opinionated set of host-side utilities that read existing file-shaped state and artifacts. They do not mutate system state, do not self-heal, and do not bypass policy.
Milestone 27 is a convergence milestone. It does not create a second trace format or a second reproducibility artifact. Instead:
- the existing
cohsh-core/cohshtrace format remains the canonical trace substrate; - the existing
coh evidence pack/coh evidence timelinesurface remains the canonical reproducibility pack; - this milestone fills the missing operator-facing commands and makes those existing foundations compose cleanly.
Implementation status (2026-09-14): Host utilities, case synthesis,
Python consumers, audit consistency coverage, and bounded latency coverage are
complete on the approved basis above. The signed wire/trust contract and
m27-attestation-verifier are implemented and pass the shared cryptographic
fixtures; optional-device availability remains explicit. Offline signature
fixtures and QEMU success do not establish a live signed-device result.
Authoritative receipt validation and verified-execution verdicts remain owned
by m27b-authoritative-receipt-and-evidence-core.
Goal
Provide a coherent operator toolkit that:
- Explains current system state (
inspect) - Reuses canonical trace artifacts for deterministic diagnostics (
trace) - Produces self-contained reproducibility artifacts without inventing a second pack format (
bundle) - Compares system state and policy deterministically (
diff) - Verifies device identity and attestation evidence (
attest) - Refreshes audit blocker/risk ledgers from current generated artifacts and evidence packs so later milestones do not inherit stale proof claims.
All tools must be:
- host-side only
- deterministic and scriptable
- aligned with existing Secure9P / NineDoor surfaces
- auditable and replay-compatible
Non-Goals (Explicit)
- No automatic remediation or self-healing
- No in-VM UI or interactive tooling
- No new protocols or transports
- No mutation of authority, policy, or state
- No persistent mutation of authority, policy, or state. A bounded authenticated attestation nonce request to the versioned ephemeral challenge node defined by Milestone 26 is permitted; it cannot alter policy or grant authority.
- No dependency on POSIX filesystem semantics inside the VM
- No second trace recorder/replayer distinct from the existing
cohsh-coretrace stack - No second bundle/evidence artifact format distinct from
coh evidence pack
Deliverables
1) coh inspect — Correlated System Explanation
Purpose: Provide a correlated, human-readable explanation of the system’s current operational state.
Reads (examples):
/proc/lifecycle/*/proc/root/*/proc/9p/session/*/proc/pressure/*/proc/spool/status/proc/attest/*
Output characteristics:
- Structured text (stable field ordering)
- No “healthy/unhealthy” judgment
- Explains why the system is in its current state
- Zero side effects
Exit codes:
0— state internally consistent>0— invariant violation (corruption, impossible state)
2) trace — Canonical Live Capture and Consumption
Purpose: Consume the existing deterministic trace format for debugging, testing, and operator diagnostics without defining a parallel recorder.
Capabilities:
- Record bounded canonical traces through the real TCP and REST/console projection transports without changing their requests or responses
- Reuse
.traceartifacts emitted by the existingcohsh/cohsh-corestack - Correlate traces with relevant
/proc/*and evidence-pack state when available - Replay traces against:
cohsh- SwarmUI Live Hive
- read-only field diagnostics surfaces that consume the same shared core
Constraints:
- No live mutation during replay
- Authentication exchanges, raw tickets, secret-bearing payload fields, and host credentials are omitted or schema-redacted before persistence
- Byte-identical ACK/ERR ordering required
- No second trace grammar, schema, or recorder is introduced by this milestone
3) bundle — Canonical Reproducibility Pack
Purpose:
Produce a single, self-contained artifact for bug reports, audits, and incident review by extending the existing coh evidence pack / coh evidence timeline workflow rather than creating a new pack format.
Bundle contents (bounded):
- Manifest + resolved manifest hash
- Serial log excerpt (if available from the host capture)
- Trace files (if present)
/procsnapshots (inspect-equivalent)- Spool status summary
- Attestation summary
- When Milestone 27d host-side AI control is enabled, the same canonical evidence pack may additionally include bounded AI run envelopes, checkpoint manifests, retrieval manifests, provider receipts, and prefix-reuse summaries; no AI-specific bundle format is introduced.
Output:
- Deterministic directory or archive layout
- No secrets unless explicitly authorized
- Hash recorded and printed
Canonical surface:
coh evidence packremains the primary CLI- If a
coh bundlealias is later added, it must be a thin alias over the exact same artifact layout and tests
4) coh diff — Deterministic Comparison
Purpose: Answer “what changed?” without guesswork.
Supported comparisons:
- Two live targets
- Live target vs bundle
- Two bundles
Diff surfaces:
- Namespace shape
- Manifest-resolved limits
- Policy rules
- Lifecycle / root state
- Attestation fingerprints
- AI run/checkpoint/prefix evidence when present through the canonical evidence-pack layout
Output:
- Minimal, ordered diff
- No semantic inference
- Script-friendly format
5) coh attest — Identity & Evidence Verification
Purpose: Verify device identity and boot provenance.
Capabilities:
- Submit a bounded fresh nonce through the Milestone 26 ephemeral challenge
node and parse the uniquely correlated TPM2 Quote or DICE evidence from
/proc/attest - Verify manifest fingerprint binding
- Validate certificate/signature chain, nonce, boot/session identity, measurement selection, exact artifact hashes, freshness/replay data, and configured trust anchors
- Emit clear PASS / FAIL + reason
measurement_only, unsigned hashes, virtual TPM evidence presented as Pi
hardware, and unavailable trust roots always produce a non-attested result.
This command is binary by design and suitable for CI and compliance workflows.
Implementation Scope
- Host tools centered on
apps/coh/with shared read-only internals reusable bycoh-statusand SwarmUI where appropriate - Reuse existing parsing and transport crates
- No changes to VM-side authority logic
- Minimal, additive code only
Documentation Updates
docs/USERLAND_AND_CLI.md- Command reference
- Output guarantees
docs/SECURITY.md- Operator tooling trust model
docs/audit/*- Current blocker ledger, risk baseline, and accepted-risk cross references
docs/ARCHITECTURE.md- Operator interaction layer (read-only tools)
Testing & Validation
- Golden output fixtures for each command
- Evidence-pack/bundle → diff → inspect roundtrip tests
- Trace replay regression using the existing canonical trace fixtures
- Attestation positive and negative cases
- Audit ledger consistency checks across blockers, exceptions, findings, and risk baseline files
- Bounded command-latency checks for
inspect,diff,attest, and evidence-pack reads over representative live and offline artifacts. This is a host-tool microbenchmark gate, not a QEMU/Pi throughput rerun. - Tools must operate correctly against:
- the accepted four-core QEMU SMP+MCS profile
- retired single-core QEMU evidence bundles only as offline parser/ compatibility fixtures, never as an operational target or proof source
- Pi 4 boot profile (where applicable)
Checks (Definition of Done)
- All tools produce deterministic output
- No tool mutates system state
- No new protocols introduced
- Trace replay yields byte-identical ACK/ERR using the existing canonical trace format
- Canonical evidence packs/bundles are sufficient for offline diagnosis
- Audit blocker/risk ledgers agree with current generated artifacts and evidence-pack schema before Milestone 27a/27d tasks cite them.
- Read-only operator-tool latency evidence stays bounded on representative artifacts and any regression is classified as parser, evidence-pack, transport, or artifact-size overhead before downstream tools depend on the shared core.
- Documentation reflects as-built behavior
Outcome
After Milestone 27:
- Cohesix is operable, not just correct
- Incidents are explainable and reproducible
- Operators can reason about state without guesswork
- Support and integration costs drop sharply
- The control plane remains small, auditable, and boring
- Milestone 27d reuses the same evidence/timeline/diff substrate rather than introducing an AI-only forensic path
Sharpened Implementation Sequence
- Add
coh inspectas a read-only synthesis over existing/proc/*, fleet, and evidence-pack state. - Keep
coh evidence pack/coh evidence timelineas the canonical reproducibility artifact; ifbundleis exposed, make it a thin alias only. - Add
coh diffagainst live targets and canonical evidence packs. - Add
coh attestover/proc/boot+/proc/attest/*with trust-anchor validation. - Reuse the existing trace substrate for pack correlation and diagnostics; do not add a second trace recorder.
- Refresh audit ledgers from the current repo state and generated outputs before 27a/27d hardening work cites blocker or exception state.
Task Breakdown
The M27 task statuses below share the explicit completion decision above. Their checks describe the preserved contracts; physical checks listed as unexecuted in the completion record were accepted as remaining evidence gaps, not relabelled PASS.
Title/ID: m27-owner-review-closure
Milestone: Milestone 27 — Operator Utilities / exact owner approval and due-diligence closure
Status: Complete — approved evidence basis recorded above
Goal: Record Lukas Bower's DD30/Rust sign-off and subsequent milestone completion approval without altering historical approvals or target results.
Inputs: Reviewed 7c3b82abbaf938f82f958dc40886d24fcf1c9f01; tested b54bdd2fcff97fe35c5e3a61faa4d5a761b2a1ac; both exact owner statements in docs/audit/M27_COMPLETION_EVIDENCE.md.
Changes: Separate DD30_M27_APPROVAL.toml; explicitly selected DD_MILESTONE_ID=27 lifecycle validation; negative approval/source/expiry checks; completion record and reconciled Build Plan, status, Test Plan and audit documentation.
Commands: scripts/check-generated.sh (includes scripts/ci/check_test_plan.sh); git diff --check; scoped documentation link, header and retained evidence hash checks.
Checks: Exact protected and complete host/target/SDK/manifest implementation binding; unchanged P1/ACCEPTED_RISK and 2026-10-13 expiry; dynamic fault/wake remains UNEXECUTED; final Pi boot/operator/Stages03–05 remain unexecuted under the separate completion approval.
Deliverables: Durable human review, residual-risk and completion decisions; passing QEMU evidence and explicitly unexecuted Pi checks bound to their original source.
Title/ID: m27-pi-regression-isolation
Milestone: Milestone 27 — Operator Utilities / physical regression prerequisite restoration
Status: Complete — approved evidence basis recorded above
Goal: Preserve exact append-stream assertions and fresh-boot Worker isolation across the complete physical TCP matrix.
Discovery: The exact 9a5eb97f1 Pi image passed 14 of 17 scripts; the append test inspected an ACK preview, and later groups inherited a live heartbeat slot and boot-local Worker IDs.
Changes:
- scripts/cohsh/9p_batch.coh + TCP/REST batch runners — validate ordered appended records in the completed CAT data stream, independently of bounded ACK previews and interleaved audit records.
- scripts/ci/pi4_regression_boot.py + TCP/Stage03 runners — invoke an explicitly configured, bounded external boot collector for each selected Pi group; verify fresh boot IDs and unchanged source/image/host/gateway bindings; retain each group's evidence and finish on base for existing Stage04 continuity.
Checks: Missing, reordered or repeated append records fail; boot-hook failure, stale boot identity and changed image/source fail; all four groups retain distinct exact-image boot records and the complete 17-script matrix remains required.
Compatibility: No target/runtime/Worker/console grammar change. Host suite, Python SDK, REST and benchmark consumers retain their contracts; only canonical test collection and evidence composition change.
Deliverables: Deterministic workflow tests, passing final-source QEMU matrix, preserved failed Pi attempt and owner-approved closure with final-source Pi execution unexecuted.
Title/ID: m27-live-operator-closure
Milestone: Milestone 27 — Operator Utilities / live inspect and evidence-pack composition
Status: Complete — approved evidence basis recorded above
Goal: Close fresh-Pi-discovered host collection defects without weakening missing/error or proof classifications.
Changes:
- apps/coh/src/operator.rs + evidence.rs — use the bounded advertised /proc inventory for optional-root absence, preserve lease-ID directory semantics when empty, and retain nested directory listings in separate .listing leaves.
- apps/coh/tests/operator.rs — exercise empty/populated lease directories, absent optional roots, refused parent listings, advertised-node read failures, and pack round trips.
- docs/OPERATOR_EVIDENCE.md — document inventory-based availability and backward-readable listing storage.
Checks: Fresh Pi TCP/REST capture composes with complete packs and byte-stable offline inspection/replay; actual read failures remain incomplete exports; old inventory-selected paths remain readable.
Compatibility: Complete host-tool suite, Python SDK and benchmarks reviewed; inventory-based consumers need no schema or workload change. No target namespace, driver, scheduling, wire grammar or authority change.
Deliverables: Host collector correction and separate exact-image live evidence.
Title/ID: m27-build-evidence-blockers
Milestone: Milestone 27 — Operator Utilities / restoration of build and evidence prerequisites; discovery in m27-attestation-verifier, restoring the exact-source invariant of m26e-worker-target-evidence-promotion
Status: Reopened — M27g assembled-journeys-and-recovery discovered that the Pi build's exact generated-output allowlist omits the current provider projections; restore only that build prerequisite, retaining the prior completion evidence.
Goal: Restore canonical test and image-build prerequisites without relaxing source integrity, evidence bounds or target acceptance.
Changes:
- scripts/pi4-image-build.sh + tests/test_pi4_image_build.py — recognize the exact compiler-emitted provider and recipe paths during temporary profile generation; continue refusing unrelated tracked or untracked changes and require canonical restoration after the build.
- tests/test_linux_host_tools_sync.py, tests/test_release_bundle.py, tests/test_sel4_profile.py — exercise the existing exact tracked-tree archive and argument-driven packaging contracts; preserve export-ignore coverage and secret exclusion.
- scripts/ci/test_run_regression_batch.py — explicitly select the QEMU fixture target and action so common-stage execution under Pi does not inherit physical transport requirements.
- scripts/worker_task_evidence.py + tests/test_worker_task_evidence.py — stream every git-visible regular source file in at most 1 MiB reads, including shipped images larger than the evidence parser's 64 MiB allocation bound; retain exact extent, metadata, path-set and repeated-content checks. This restoration does not reopen M26e runtime or physical behavior.
- toolchain and selected build outputs — restore pinned compiler/Python/mkimage and the pristine canonical QEMU profile through documented setup.
- scripts/ci/test_plan_target_root_check.sh + focused workflow tests — route Pi Stage 02 through the canonical clean-source Pi builder, compare its retained resolved manifest to the compiler-selected Pi identity, and verify exact staged image/source binding. Preserve QEMU identity rejection and all physical acceptance requirements.
- docs/TOOLCHAIN_MAC_ARM64.md — distinguish advertised HVF from the validated QEMU 10.1.0 HVF/GIC runtime; retain the QEMU 11.0.3 pre-guest assertion as failed evidence and select the verified external executable explicitly.
Commands: .venv/bin/python -m pytest -q tests/test_worker_task_evidence.py tests/test_linux_host_tools_sync.py tests/test_release_bundle.py tests/test_sel4_profile.py; scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml; scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m27-qualification-qemu
Checks: Source identities include exact large-image bytes without large allocations; same-read mutations and oversized evidence files still fail; canonical target and acceptance predicates remain unchanged.
Deliverables: Restored provenance/build workflows and fresh command evidence, separate from physical acceptance.
Title/ID: m27-evidence-case-summary
Milestone: Milestone 27 — Operator Utilities: Inspect, Trace, Bundle, Diff, Attest / reviewer-friendly evidence case summary
Status: Complete — approved evidence basis recorded above
Goal: Extend the canonical offline evidence workflow with a deterministic scenario-aware case summary that reconstructs observed request, admission/refusal, state/lease/lifecycle, host-result, and receipt/dead-letter links while declaring missing, errored, unknown, and ambiguous evidence without asserting target, hardware, health, or external-execution proof.
Inputs: apps/coh/src/evidence.rs, apps/coh/src/evidence_timeline.rs, apps/coh/src/main.rs, apps/coh/tests/evidence_pack.rs, apps/coh/tests/evidence_timeline.rs, tools/cohesix-py/examples/ci_evidence_pack.py, tools/cohesix-py/tests/test_examples_ci_siem.py, docs/USE_CASES.md, docs/OPERATOR_WALKTHROUGH.md, docs/OPERATOR_RECIPES.md, docs/HOST_TOOLS.md, docs/TEST_PLAN.md, current evidence-pack, audit, host-ticket, lease, lifecycle, and federation schemas.
Changes:
- apps/coh/src/evidence_timeline.rs + apps/coh/src/main.rs — extend `coh evidence timeline` rather than introduce a second pack format; emit additive, atomically written `case.json` and `case.md` with an explicit `generic`, `incident`, `change`, `maintenance`, `rollout`, or `federation` scenario class.
- case synthesis — consume `summary.json` and retained timeline sources, group records by stable correlation keys, preserve cross-hive identifiers, link every derived stage to its source path/event identity, and classify each request, decision, state/lease/lifecycle, host-result, receipt/dead-letter, and federation-relay stage as `observed`, `missing`, `error`, `unknown`, or `ambiguous`.
- outcome boundary — use only non-authoritative review outcomes such as `recorded-terminal`, `refused`, `deadlettered`, `incomplete`, and `ambiguous`; a current host-ticket status or client-derived record never proves external execution, target state, hardware behavior, or an authoritative receipt. Authoritative graph validation and verified-execution semantics remain deferred to `m27b-authoritative-receipt-and-evidence-core`.
- compatibility and safety — preserve existing `timeline.ndjson`, `timeline.md`, pack layout, redaction, generated byte bounds, deterministic ordering, atomic writes, missing/error inventory, partial-pack handling, and offline operation; unknown additive fields remain compatible and secret canaries never enter case outputs.
- tests and operator contract — add deterministic fixtures for incident, change, maintenance, rollout, and federation review; cover incomplete and conflicting chains, missing/error inventory, cross-hive correlation, malformed bounded inputs, secret canaries, and byte-stable reruns; update CI structural validation and operator documentation for the additive outputs and their proof limitations.
Commands: cargo test -p coh --test evidence_pack --test evidence_timeline && python3 -m pytest -q tools/cohesix-py/tests/test_examples_ci_siem.py && cargo fmt --all -- --check && cargo clippy -p coh --all-targets -- -D warnings && scripts/check-generated.sh && scripts/ci/test_plan_run.sh --list
Checks: Fixed evidence packs produce byte-stable case outputs without network access; every causal stage is source-linked or explicitly missing, error, unknown, or ambiguous; federation correlation remains operator-visible; existing pack/timeline consumers remain compatible; secret canaries do not survive; no outcome claims target/hardware proof, external execution, or authoritative receipt validation.
Deliverables: Additive `case.json` and `case.md` in the canonical evidence pack, scenario and negative fixtures, CI structural coverage, and operator-facing documentation that keeps current evidence and future 27b authoritative receipt semantics distinct.
Title/ID: m27-live-trace-capture
Milestone: Milestone 27 — Operator Utilities: Inspect, Trace, Bundle, Diff, Attest / live canonical trace capture
Status: Complete — approved evidence basis recorded above
Goal: Make the existing bounded trace format record real TCP and REST/console-projection sessions while keeping replay offline, deterministic, and non-mutating.
Inputs: apps/cohsh/src/{main.rs,trace.rs,transport/**}, crates/cohsh-core/src/trace.rs, apps/coh/src/**, apps/hive-gateway/**, existing trace fixtures/policy, docs/USERLAND_AND_CLI.md, docs/SECURITY.md, docs/TEST_PLAN.md.
Changes:
- crates/cohsh-core + apps/cohsh — wrap live TCP and REST transports with the existing recorder, preserve partial-stream/disconnect/reconnect boundaries, bind the header to schema, backend class, target/session id, manifest/image identity, capture time, and policy hash, and enforce generated byte/frame/duration limits with atomic finalization.
- redaction — omit authentication frames and apply generated field-aware redaction before bytes reach disk; raw tickets, placeholder/real auth tokens, secret refs, host credentials, and secret-bearing control payloads are never recoverable from a trace. Redaction metadata is authenticated as part of the trace header/digest.
- replay — keep replay transport-free and non-mutating, reject tamper/wrong-policy/oversize/secret-bearing input, and preserve byte-identical post-redaction ACK/ERR/END order across cohsh, SwarmUI, and shared read-only consumers.
- public docs/tests — distinguish fixture, captured-QEMU, captured-Pi, and captured-host-projection traces and stop describing mock-only recordings as live artifacts.
Commands: cargo test -p cohsh-core && cargo test -p cohsh && scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m27-live-trace-qemu
Checks: real TCP and REST sessions produce bounded, identity-bound, atomically complete canonical traces; disconnect/reconnect and truncated captures are explicit; secret canaries never appear; replay is byte-stable and emits no writes; mock traces remain fixtures and cannot satisfy live target evidence.
Deliverables: One canonical trace recorder usable on real transports and one honest replay/evidence classification.
Title/ID: m27-attestation-verifier
Milestone: Milestone 27 — Operator Utilities: Inspect, Trace, Bundle, Diff, Attest / signed attestation verification
Status: Complete — approved evidence basis recorded above
Goal: Implement `coh attest` as a real verifier of the Milestone 26 device-bound evidence contract rather than a manifest-hash comparison.
Inputs: accepted `m26-device-identity-attestation-closure` schema/evidence, apps/coh/**, shared evidence/attestation parser crate, trust-anchor inputs, QEMU vTPM and Pi hardware/device-root fixtures, docs/SECURITY.md, docs/TEST_PLAN.md.
Changes:
- shared host attestation core + apps/coh — generate a cryptographically random bounded nonce, submit the authenticated ephemeral challenge, correlate the response, parse TPM2 Quote or DICE evidence, validate algorithms/chain/signature/nonce/measurements/boot id/artifact identities/freshness/replay counter, and return stable machine-readable PASS/FAIL/UNAVAILABLE reasons.
- evidence/bundle/diff — retain signed raw evidence only within generated bounds, record its digest and trust-policy id, redact enrollment metadata as configured, and keep QEMU virtual-device, Pi device-root, offline fixture, measurement-only, and unavailable classes distinct.
- negative/conformance tests — replayed nonce, wrong PCR/manifest/image/kernel/root, wrong AK/DICE chain, expired or revoked trust anchor, malformed size, unsupported algorithm, measurement-only substitution, virtual-to-Pi proof substitution, and missing device all fail closed.
Commands: cargo test -p coh --test attest && cargo test -p coh --test evidence_pack && scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m27-attest-qemu && scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m27-attest-pi4
Checks: `coh attest` accepts only a fresh signed chain matching the exact target and configured trust policy; a matching public manifest hash alone never passes; no challenge grants or mutates authority; failure reasons and offline verification are deterministic.
Deliverables: Shared cryptographic verifier reused by evidence packs, SwarmUI, and later `coh-status` without a second attestation vocabulary.
Title/ID: m27-python-evidence-contract-parity
Milestone: Milestone 27 — Operator Utilities: Inspect, Trace, Bundle, Diff, Attest / Python evidence contract parity
Status: Complete — approved evidence basis recorded above
Goal: Keep the non-authoritative Python SDK compatible with the canonical evidence-pack, timeline, redaction, trace-reference, and attestation-result contracts established by Milestone 27.
Inputs: `m27-live-trace-capture`, `m27-attestation-verifier`, apps/coh evidence/attestation fixtures, canonical trace and legacy offline fixtures, generated evidence schemas and bounds, tools/cohesix-py/cohesix/{client.py,evidence.py}, tools/cohesix-py/tests/{test_evidence_receipts.py,test_examples_ci_siem.py}, docs/PYTHON_SUPPORT.md, docs/TEST_PLAN.md.
Changes:
- tools/cohesix-py/cohesix/{client.py,evidence.py} — consume the canonical generated evidence-pack layout, timeline ordering, opaque bounded trace references, redaction rules, bounds, artifact classes, and typed attestation outcomes without defining a second pack format, parsing or replaying trace payloads, verifying against weaker inputs, or inferring attestation success. Authoritative receipt migration remains owned by `m27b-authoritative-receipt-and-evidence-core`.
- tools/cohesix-py/tests/test_evidence_receipts.py + tools/cohesix-py/tests/test_examples_ci_siem.py — run the shared canonical fixtures plus explicitly classified legacy offline parser fixtures; cover unknown additive fields, missing optional artifacts, signed PASS/FAIL/UNAVAILABLE records, measurement-only inputs, virtual-versus-hardware proof separation, truncation, and secret canaries.
- docs/PYTHON_SUPPORT.md + docs/TEST_PLAN.md — document that Python may project or analyze the canonical record but cannot manufacture authoritative evidence or upgrade an offline/legacy/measurement-only artifact.
Commands:
- python3 -m pytest -q tools/cohesix-py/tests/test_evidence_receipts.py tools/cohesix-py/tests/test_examples_ci_siem.py
Checks: Rust and Python agree on canonical fixture bytes, ordering, classifications, bounds, and redaction; secret canaries never survive; matching hashes alone never become attestation PASS; legacy artifacts remain offline parser fixtures only; Python output cannot become a second evidence authority.
Deliverables: One evidence-pack/timeline/attestation-result contract shared by Rust producers and Python consumers.
Title/ID: m27-audit-ledger-refresh
Status: Complete — approved evidence basis recorded above
Goal: Refresh audit blockers, exceptions, findings, and risk baselines so later hardening milestones cite current state.
Inputs: docs/audit/, scripts/check-generated.sh, docs/BUILD_PLAN.md, current evidence-pack schema.
Changes:
- docs/audit/BLOCKERS.md — update blocker status and classify remaining issues by milestone owner.
- docs/audit/EXCEPTIONS.md — remove contradictory `None` state when active exceptions exist and cross-link accepted-risk ids.
- docs/audit/findings.csv + docs/audit/rust_risk_baseline.toml — align risk ids, counts, and accepted exceptions with current code.
- docs/TEST_PLAN.md — add audit-ledger consistency check before 27a/27d closure.
Commands: scripts/check-generated.sh && cargo test -p tests --test audit_ledgers
Checks: Blockers, exceptions, findings, and risk baseline agree; stale audit snapshots cannot be cited as current closure evidence.
Deliverables: Current, internally consistent audit ledgers for authority hardening and host-side AI milestones.
Title/ID: m27-readonly-command-latency
Status: Complete — approved evidence basis recorded above
Goal: Add bounded latency coverage for read-only operator utilities without treating Milestone 27 as a full runtime benchmark gate.
Inputs: apps/coh, tests/fixtures/traces/, representative evidence packs, docs/TEST_PLAN.md, docs/BENCHMARKS.md.
Changes:
- apps/coh/tests/operator_latency.rs — deterministic fixture-backed checks for inspect, diff, attest, and evidence-pack read latency.
- docs/TEST_PLAN.md + docs/BENCHMARKS.md — classify the evidence as host-tool latency, separate from REST/QEMU/Pi throughput proof.
Commands: cargo test -p coh --test operator_latency
Checks: Representative artifact sizes stay within declared parse/read bounds; failures classify parser, evidence-pack, transport, or artifact-size overhead.
Deliverables: Read-only operator utility latency evidence that later field and UI tools can cite without rerunning full hardware benchmarks.
Cross-Cutting Governance Value Contract for Milestones 27a-27g
Milestones 27a-27g may add many host-facing integrations, but they form one governance product rather than a collection of substitute platforms. Cohesix owns bounded decisions, delegated authority, and evidence. Existing model servers, agent frameworks, Kubernetes/systemd, GPU runtimes, observability, FinOps, identity, and domain systems continue to own their native execution and data planes.
Every task and public integration in Milestones 27a-27g, and every later consumer of those milestones, must preserve this common lifecycle:
observe -> preflight -> admit -> grant -> execute externally
-> observe result -> verify -> receipt -> review/replay
The stages may collapse for a read-only operation, but no mutating projection
may skip admission, call an executor directly, or manufacture a terminal
result. Release A operator admission means authenticated explicit human
approval plus generated allowlist, bounded ticket, idempotency/writer state,
and receipt under 27a; it is recorded as
admission_mode=operator_approved/admission_id=unavailable and cannot be
described as general machine-checked admission under 32. Release B governed or
autonomous admission means the accepted 28 m28-standing-authority-and-admission
typed-intent, authoritative-fact and state-bound decision path. General proof
artefacts remain 32 (m28c-admission-verdict-engine). A profile cannot silently switch between them.
Host APIs, OpenAI-compatible endpoints, MCP/A2A, Python, FUSE, exporters, and
SwarmUI are replaceable projections over this lifecycle, not independent
authority planes.
Before a new provider, alias, protocol projection, optimizer, semantic view, agent feature, exporter, or workbench action is authorized, its owning task and generated 27b integration/use-case row must answer:
- Governed decision: What consequential decision, resource, data boundary, or external action is being governed? Presentation or transport convenience alone is not a security or governance capability.
- Authority custody and bypass: Which credential, capability, lease, actuator, or provider permission performs the action, who holds it, and what prevents the requesting application from bypassing Cohesix? A path that remains bypassable may ship as observation or recommendation, but it cannot claim non-bypassable enforcement.
- One authority spine: Which existing generated ticket, policy, provider/action, idempotency, writer-epoch, and receipt contracts does the feature consume? A feature-specific authorization or executor shortcut is prohibited.
- Named external owner: Which host executor or external data plane performs the work, and which conformance lane proves its observed terminal behavior?
- Bounds and failure posture: What are the request, queue, cost, token, time, retry, retention, and evidence bounds, and does unavailability cause a deterministic refusal, an explicitly approved fixed route, a separately authorized and receipted human action, or read-only degradation? Silent fail-open, provider substitution, authority widening, and unrecorded fallback are prohibited.
- Fact and evidence boundary: Which records are Cohesix authority or observation, provider/executor reports, client-only observations, inferred, unknown, or explicit non-claims? The shared 27b receipt/evidence vocabulary is reused; each feature must not invent a stronger local truth class.
- Coexistence value: Why is this better than a hardened host-only adapter for the named use case, and what existing platform remains in place? If the answer is only feature breadth, keep the capability outside the Cohesix core or defer it.
Any provider, routing, AI-run, or agent-protocol feature that can influence external execution must expose generated governance modes distinct from its mock/dry-run/live evidence state:
observerecords only policy-permitted bounded inputs/metadata and the decision that would have been made without changing routing or execution;recommendemits a non-authoritative, reviewable recommendation and reasons while the existing execution choice remains in control;enforcemay alter selection or submit an action only through accepted delegated authority and the generated provider/action path.
Promotion to enforce requires a declared evaluation window, representative
shadow evidence, compatibility and refusal results, policy-violation findings,
and workload-relevant cost/latency/quality or verification measures. Shadow
evidence is advisory and cannot satisfy external-execution, Worker, hardware,
or production-use-case proof by itself.
The seL4 target must remain outside token streams, bulk artifacts, hot telemetry,
and provider-native data planes. Milestone 35 (m28f-gateway-admission-and-streaming) must preserve exact per-request
operator approval or, where selected, accepted 28 governed admission plus durable
reconciliation. A later optimization may introduce a
short-lived multi-request routing or budget grant only through a separately
versioned compiler-owned contract with one spender, exact policy/identity/
provider bounds, expiry and revocation, monotonic accounting, overspend
prevention, crash reconciliation, mandatory receipts, and measured need. A
generic host-local authority envelope or an optimization that weakens exact
admission is not authorized by Milestone 35.
Milestone 27a — Authority Hardening: Delegated REST Identity, Fenced Failover, Idempotent Queen Intents
Status (2026-09-14): Complete — implementation and focused current host/QEMU/Pi checks pass. Lukas Bower approved closure without the missing M26d status-baseline JSON and comparison; that comparison remains NOT_PERFORMED. The qualification record binds this scoped completion decision, candidate-F Rust sign-off, the separate DD30 accepted risk and each observed result. This decision grants no performance-equivalence claim or staged target PASS.
Scoped restoration (2026-09-15): m27a-host-ticket-validation-replay is
Complete after restoring the production Root version-1 parser discovered by
M27b native provider integration. Focused typed-parser, QEMU and Merlin checks
are recorded in the M27b record.
The earlier completion evidence remains historical.
Delivery posture: Release A authority floor. Delegated identity, strict idempotency, durable execution recovery, production secrets, audit/replay, and single-writer safety are required for the reference workflow. Multi-host failover and federation promotion evidence is required only for a profile that ships those features; it cannot block the single-Jetson reference profile.
Why now (risk closure): Milestones 25g and 25h delivered host tickets, federation relay, and bounded WAL behavior. As-built deployments still have two critical exposure points: 1) REST callers collapse into one gateway-attached Queen principal, and 2) profiles that enable failover still depend on external fencing discipline rather than deterministic writer fencing in the control-plane path.
This milestone closes those gaps using existing as-built mechanisms (hive-gateway, cohsh-core ticket claims, /host/tickets/*, relay WAL, manifest compiler) without introducing new VM protocols or relaxing single-writer semantics.
As-built alignment note: Mutating REST requests now require request authentication and a MAC-validated caller ticket. The gateway intersects caller role, scope, mount, expiry and quotas with its configured upstream authority and retains bounded quota state. The upstream console still authenticates as the gateway principal, so this is gateway-enforced caller delegation; no VM-verified caller identity is claimed. Strict Queen intent identities reserve bounded dedupe entries before effects, retain duplicate terminal results, and reject changed envelopes or non-current writer epochs. Host execution and relay journals preserve durable dedupe and writer fences. The Release A production profile requires strict intents, secret references and bounded audit/replay, disables legacy Queen control and memory diagnostics, and keeps production failover/federation and future VM authority gates disabled. Completion follows the evidence requirements and scoped owner decision below.
Current follow-on task owners: shared admission is 28
(m28-standing-authority-and-admission); selected protocols are 28d
(m28d-mcp-selected-workflows) and 28e (m28e-a2a-durable-jobs); production
binding is 33 (m28b-production-worker-ticket-driver-inventory); storage is 37
(m29-contract-baseline-admission); AI namespaces are 42 (m30b-ai-ir).
These references update prospective ownership only, not accepted 27a evidence.
Sequencing note: Milestone 27a closes the host/gateway authority floor required by the Milestone 27b coexistence gate, Milestone 28 per-intent admission, and Milestones 27d, 28d/28e, and 42. Milestone 26e owns complete live Worker and baseline linked-driver cap authority and basic containment; a persistence-enabled Milestone 37 profile must also have accepted its driver-storage bundle under that same contract. Production Worker ticket/lease ledger binding, complete driver-inventory projection for every selected accepted runtime, and structured worker/driver quarantine evidence are split into Milestone 33 so the host actuation floor can ship without bundling that production ledger work into the same atomic gate.
Goal
Strengthen authority and failover guarantees while preserving current transport and grammar boundaries:
- Require caller-scoped delegated authority for mutating REST operations.
- Make Queen control intents replay-safe with deterministic idempotency keys.
- Add explicit writer-epoch fencing for failover and relay paths.
- Eliminate fixture/bootstrap secret usage from release profiles.
- Ship production profiles with audit/replay enabled and bounded by manifest limits.
- Establish the mandatory authority floor for Milestone 27b provider conformance, Milestone 27d host-side AI actuation, and Milestone 42 AI namespace projections.
- Harden host-ticket execution so target/arg validation and replay durability are strong enough for host side effects.
- Harden host bridge and debug surfaces that can otherwise bypass the authority story: GPU bridge authentication/frame bounds and root-console memory diagnostics.
- Leave production Worker ticket/lease ledger binding, complete driver-inventory projection, and structured quarantine/evidence as the explicit Milestone 33 follow-on, not a hidden prerequisite inside the host/gateway write-safety gate or a reason to deny accepted pre-33 live cap authority from 26e and any selected, independently accepted Milestone 37 storage runtime.
Non-Goals (Explicit)
- No active/active multi-queen writers for one logical hive.
- No in-VM HTTP services or new RPC channels.
- No changes to ACK/ERR/END grammar or Secure9P transport framing.
- No silent replacement of the existing
/queen/ctlraw-command schema. Any strict intent envelope is introduced through a versioned compatibility path or the full breaking-change process: manifest schema bump, regenerated snippets, updated CLI fixtures, updated docs, and migration notes. - No best-effort reconciliation loops or autonomous remediation behavior.
Deliverables
1) Caller-Scoped REST Delegation (No Undifferentiated Write Authority)
Purpose: Preserve gateway multiplexing while restoring caller-level capability boundaries.
Implementation requirements:
- Mutating REST routes (
/v1/fs/echoand equivalent write paths) require:- gateway request-auth token, and
- delegated capability ticket header (
x-cohesix-ticket), validated using existing ticket claims rules.
- Gateway maintains caller identity and quota state keyed by delegated ticket identity (hash). The gateway’s configured upstream role/ticket is a transport-authority ceiling, not the caller identity: a request is admitted only when the delegated ticket is valid and the concrete path/action is within both the delegated claims and the gateway ceiling.
- If the VM console transport remains single-client or single-writer for the selected profile, the gateway serializes writes over the existing authenticated console path rather than opening parallel sessions or reattaching a shared session between callers. Audit/evidence records bind the delegated ticket hash, gateway credential class, concrete path/action, and upstream
ACK/ERRresult. - Delegated ticket claims (
role,subject,mount scopes,budgets) constrain what each REST caller can mutate. Gateway-enforced delegation must not be described as VM-verified caller identity unless a separately versioned VM envelope/path actually carries and verifies the caller binding. - Read-only REST routes may remain gateway-role scoped in compatibility mode. The delegated-ticket requirement for mutating REST paths is an authority-contract change and must update
docs/API_GUIDELINES.md,docs/HOST_API.md, OpenAPI fixtures, CLI/REST tests, and release notes in the same milestone work.
As-built leverage:
- Reuse
cohsh-coreticket parsing/validation and existing ticket quota semantics. - Reuse deterministic permission errors (
EPERM,ELIMIT) and existing audit logging surfaces.
2) Idempotent Queen Control Grammar
Purpose: Ensure retries/replays never duplicate side effects for Queen control intents while preserving legacy /queen/ctl compatibility unless a breaking-change path is taken.
Implementation requirements:
- Introduce strict envelope schema for idempotent Queen intents:
- required:
schema,id,idempotency_key,issued_unix_ms,cmd.
- required:
- Preserve existing
/queen/ctlraw-command behavior in compatibility profiles, or introduce a new versioned path such as/queen/intents/ctlfor strict envelopes. Production profiles may require strict envelopes only after the generated manifest schema and fixtures record that breaking authority posture. - Add bounded dedupe table in root-task authority path keyed by
id + idempotency_key. - Duplicate intent behavior is deterministic:
- no side effects repeated,
- stable acknowledgement path,
- audit line records dedupe decision.
- Provide read-only introspection node for recent dedupe outcomes (bounded bytes/entries).
As-built leverage:
- Align with existing idempotency model used by
/host/tickets/spec. - Keep all writes append-only and routed through existing authority flow.
3) Writer-Epoch Fencing and Failover Determinism
Purpose: Replace implicit human/process fencing with explicit, verifiable writer epochs.
Implementation requirements:
- Add monotonic writer epoch to host control ticket flows and relay envelopes.
- Host-ticket-agent and relay pipeline reject stale-writer intents deterministically.
- Expose read-only writer-epoch/fence state for operator diagnostics and evidence correlation.
- Update failover runbook to require epoch promotion before standby becomes writable.
As-built leverage:
- Reuse existing
/host/tickets/{spec,status,deadletter}lifecycle and relay WAL. - Reuse existing failover active/standby model and single-writer policy.
4) Production Secret and Key Discipline
Purpose: Remove bootstrap/fixture secret assumptions from release-grade configurations.
Implementation requirements:
- Replace literal ticket secrets and fixture CAS signing key usage in production manifests with secret references.
- Reject placeholder credentials in every live client/provider, including SwarmUI and the GPU bridge, before any connection is attempted. Warning-only acceptance is fixture behavior, not a production degradation mode.
coh-rtcrejects release profiles that include:- fixture signing key paths,
- bootstrap/default secret literals.
- Release assembly never copies a private fixture signing key or wildcard host directory; selected bundles contain only the exact generated artifact set and public verification material. Historical release snapshots remain immutable but their insecure examples receive current errata.
- Host tooling/docs define deterministic env/file resolution order for ticket secrets and CAS signing keys.
- Add rotation tests proving key rollover works without protocol changes.
As-built leverage:
- Extend existing manifest validation and due-diligence secret-hygiene checks from Milestone 25b.
5) Production Audit/Replay Baseline
Purpose: Make post-incident reconstruction and failover verification first-class in production profiles.
Implementation requirements:
- Production profile defaults:
ecosystem.audit.enable = trueecosystem.audit.replay_enable = true- bounded retention values sized for fleet operations.
- Evidence packs include writer-epoch and dedupe state snapshots.
- Release gate fails if production profile disables audit/replay without explicit exception record.
As-built leverage:
- Use current
/audit/*,/replay/*,coh evidence pack, and timeline tooling.
6) Host Ticket Validation and Durable Execution
Purpose: Keep /host/tickets/spec as a safe host-side actuation lane rather than an under-validated side-effect queue.
Implementation requirements:
- Introduce provider-specific validated newtypes for host ticket targets, args, ids, and action fields.
- Reject empty components,
.., slash-bearing identifiers where a single token is expected, control characters, overlong values, leading option-like values where they become argv operands, and unsupported provider-specific fields. - Enforce manifest action allowlists before executor dispatch, not only after schema parsing.
- Add durable execution WAL states such as
prepared,executed, andterminal, keyed byid + idempotency_key. - A crash or writeback failure after host side effects must not cause silent duplicate execution on restart; recovery must either publish the terminal receipt or deadletter with explicit replay state.
As-built leverage:
- Reuse the existing host-ticket schema, relay WAL, receipts, and idempotency key model.
7) Host Bridge Auth/Frame Caps and Debug Memory Gates
Purpose: Remove authority bypasses from host bridge and debug surfaces before they become production dependencies.
Implementation requirements:
gpu-bridge-hostmust reject placeholder auth such aschangemeoutside explicit mock/test modes and require a configured token source for live publish paths.gpu-bridge-hostconsole/REST clients must cap frame length before allocating buffers from peer-controlled sizes; the cap must be documented and tested.- Root-console memory diagnostics such as arbitrary-address hexdump must be disabled in release/production profiles or restricted to HAL-classified diagnostic ranges.
- Documentation must distinguish emergency bring-up diagnostics from production operator surfaces.
As-built leverage:
- Reuse existing cohsh placeholder-auth rejection patterns, Secure9P/console frame limits, HAL device coverage checks, and test-plan profile gates.
8) Production Ledger/Quarantine Follow-on Boundary
Purpose: Keep 27a atomic around host/gateway authority while preserving the required VM authority hardening path.
Implementation requirements:
- Milestone 27a must emit generated profile gates and documentation that distinguish:
- host tickets, REST delegated tickets, and provider/PEFT tickets as host authority records;
- model/session-only roles with no VM authority;
- the complete isolated Heartbeat/GPU/LoRA task-instance authority accepted by Milestone 26e, including basic fault containment and teardown but not production ticket/lease binding;
- any selected Milestone 37
driver-storagebundle only after its own complete authority inventory, fault containment, teardown, and fresh-generation evidence is accepted; - production Worker ticket/lease binding, projection of the already complete applicable driver MMIO/DMA/shared-ring inventory, and structured quarantine/evidence as Milestone 33 requirements.
- Target profiles must fail validation if they claim production ticket/lease cap-bundle binding or structured production fault/quarantine evidence before Milestone 33 evidence exists. They may describe accepted pre-33 task/driver authority only with the exact acceptance records from the milestone that owns each selected bundle.
- Milestones 27d, 28d/28e, and 42 may depend on 27a host/gateway delegated identity, idempotency, fencing, audit/replay, and host-ticket durability, and may consume accepted 26e Worker behavior where explicitly needed, but must not cite 33 production VM ticket/lease binding or quarantine closure before 33 completes.
As-built leverage:
- Reuse the accepted 26e isolated-task/acceptance terminology, any selected accepted Milestone 37 storage-runtime evidence, current driver applied-scheduling evidence, and 27a audit/replay profile gates without overclaiming 33 production ticket/lease binding.
9) Gateway authority performance guard
Purpose: Prove delegated REST identity, idempotency, and writer-epoch fencing do not create hidden gateway backpressure or push operators toward unsafe retry masking.
Implementation requirements:
- Add a targeted gateway benchmark for read-only REST status, delegated mutating REST writes, duplicate-idempotency refusals, and stale-writer refusals.
- Report p50/p95 latency, error/refusal counts, broker queue depth, backpressure responses, delegated-ticket cache behavior, and audit-line emission cost.
- Compare against the accepted 26d rolling baseline for equivalent REST status reads and against a pre-27a local gateway authority baseline for write-path overhead.
- Scoped completion decision (2026-09-14): Lukas Bower accepted M26d and waived recovery of its missing status-baseline JSON and the equivalent comparison for M27a closure. Record the comparison as NOT_PERFORMED; retain the measured pre-27a gateway comparison and its regressions. This exception does not establish equivalent performance or waive a future milestone’s benchmark requirements.
- This is a gateway/auth microbenchmark only. It must not be counted as fresh Pi hardware throughput proof unless the benchmark exposes a runtime-path regression that requires a full same-harness rerun.
10) Durable admission-correlation substrate
Purpose: Preserve the durable identity, replay, idempotency, and fencing fields that Milestone 28 will bind to a bounded current-state decision without overloading writer ownership as state freshness.
Implementation requirements:
- Version strict Queen intents, host tickets, execution WAL entries, terminal
receipts, audit records, and evidence correlation so they can carry or bind
admission_id,intent_hash,policy_hash,state_epoch,resource_generation, anddecision_expirywhen a later generated action requires admission. - Keep
writer_epochas the writer/authority-owner fence. It must not be replaced by, derived from, or overloaded asstate_epochor a resource generation. - Pre-28 compatibility actions retain their explicitly generated posture; 27a does not create or simulate an admission decision. Milestone 28 owns exact per-intent policy/state evaluation and decision-bound grant issuance.
Commands
cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsoncargo test -p hive-gatewaycargo test -p cohcargo test -p cohshcargo test -p gpu-bridge-hostcargo test -p host-ticket-agentcargo test -p root-taskcargo test -p tests --test host_ticket_agentcargo test -p tests --test failovercargo test -p coh-rtcscripts/cohsh/run_regression_batch.shscripts/ci/gateway_perf_probe.sh --scenario delegated-rest-authority --state-dir out/bench/m27a-gateway-authority
Checks (Definition of Done)
- Mutating REST request without delegated ticket is denied deterministically and audited.
- Delegated caller cannot exceed ticket scopes/quotas even when gateway is multiplexing many clients.
- Generated profile state and evidence distinguish gateway-enforced delegation from VM-verified caller identity; the default single-console projection cannot claim the latter.
- Duplicate strict Queen intent (
id + idempotency_key) never repeats side effects. - Legacy
/queen/ctlfixtures either continue to pass through compatibility mode or are updated under the full breaking-change process with schema-version evidence. - Stale writer epoch is rejected deterministically across local and relayed host tickets.
- Production manifest/profile fails validation if fixture/default secrets are present.
- Production profile surfaces
/audit/*and/replay/*; evidence packs include epoch and dedupe state. - Strict intent, WAL, receipt, audit, and evidence schemas preserve bounded
optional correlation for
admission_id,intent_hash,policy_hash,state_epoch,resource_generation, anddecision_expirywithout treating missing pre-28 fields as a fabricated admission. writer_epochremains the writer fence and is checked independently from decision state freshness and resource generations.- Host ticket targets and args are provider-validated before side effects; unsupported or ambiguous values fail deterministically with no executor call.
- Host ticket crash/restart tests prove no silent duplicate host side effects after an executor succeeds but status writeback fails.
gpu-bridge-hostrejects placeholder auth in live mode and refuses oversized peer frames before allocation.- Root-console arbitrary memory diagnostics are unavailable in release/production profiles or constrained to HAL-classified diagnostic ranges.
- Generated profiles and docs may claim exact accepted 26e Worker/baseline-driver live cap authority and accepted Milestone 37 storage-runtime authority and basic containment only with matching owner-milestone evidence; they do not claim production Worker ticket/lease binding, complete driver-inventory ledger projection, or structured quarantine evidence until 33 exists.
- Milestone 27d host-side AI control cannot be enabled in target profiles unless delegated REST identity, writer-epoch fencing, and audit/replay requirements are all active.
- Applicable regression pack preserves compatibility-mode contract outputs; any production-mode fixture update caused by delegated REST identity or strict Queen intent envelopes follows the documented breaking-change process.
- Gateway authority benchmark evidence shows delegated REST identity, idempotency, writer-epoch refusal, and audit/replay emission stay bounded; any material status/read or write-path regression is classified before downstream MCP/A2A or AI host-control milestones depend on the gateway.
Compiler touchpoints
coh-rtcschema/version update for:- delegated-ticket enforcement policy on REST mutating paths,
- delegated-identity claim class (
gateway_enforcedversus a separately evidencedvm_verifiedpath) and gateway transport-authority ceiling, - idempotent Queen intent envelope schema, compatibility mode, and dedupe bounds,
- writer-epoch fencing policy and relay requirements,
- bounded future admission correlation fields (
admission_id,intent_hash,policy_hash,state_epoch,resource_generation, anddecision_expiry) in strict intent, WAL, receipt, audit, and evidence schemas without implementing 28 evaluation, - production secret references,
- audit/replay required defaults for release profiles,
- host-ticket provider target/arg grammars and execution WAL policy,
- live host-bridge auth and frame-length limits,
- profile-gated debug diagnostic policy,
- deferred production Worker ticket/lease, driver-inventory projection, and structured-quarantine profile gates consumed by Milestone 33,
- provider-registry and host-AI enablement dependency gates consumed by Milestone 27b, Milestone 27d, and Milestone 42.
- Generated snippets refreshed in:
docs/INTERFACES.mddocs/ARCHITECTURE.mddocs/SECURITY.mddocs/FAILOVER.md
Task Breakdown
Title/ID: m27a-rest-delegated-identity
Goal: Require delegated capability tickets for mutating REST operations while preserving gateway multiplexing.
Inputs: apps/hive-gateway, apps/coh, apps/cohsh, docs/HOST_API.md, docs/API_GUIDELINES.md
Changes:
- apps/hive-gateway/src/main.rs — require x-cohesix-ticket on mutating routes, intersect delegated scope with the gateway transport-authority ceiling, serialize the single upstream console session, and correlate each write with its upstream ACK/ERR result.
- apps/hive-gateway/src/auth.rs — delegated ticket validation + bounded cache keyed by ticket hash, with explicit gateway-enforced versus VM-verified claim classification.
- apps/coh/src/rest.rs — pass delegated ticket header for mutating REST calls.
- apps/cohsh/src/transport/rest.rs — propagate delegated ticket on write paths.
- docs/HOST_API.md + docs/API_GUIDELINES.md + resources/openapi/hive-gateway.yaml — version and document the delegated REST authority contract.
Commands: cargo test -p hive-gateway && cargo test -p coh && cargo test -p cohsh
Checks: Writes without delegated ticket fail deterministically; writes with scoped tickets succeed only within the intersection of caller claims and gateway ceiling; single-console profiles do not claim VM-verified caller identity.
Deliverables: Gateway writes are caller-scoped and attributable without overstating the identity visible to the VM.
Title/ID: m27a-queen-ctl-idempotency
Status: Reopened — M27g pressure composition restoration; user approved 512 retained entries on 22 September 2026.
Goal: Add deterministic idempotency for Queen intents without silently breaking legacy /queen/ctl fixtures.
Inputs: apps/root-task, apps/nine-door, docs/INTERFACES.md
Changes:
- apps/root-task/src/control/queen_ctl.rs — strict envelope parser with required id/idempotency_key, bounded optional future admission correlation (`admission_id`, `intent_hash`, `policy_hash`, `state_epoch`, `resource_generation`, `decision_expiry`), and dedupe guard for the versioned intent path or compatibility-gated /queen/ctl mode.
- apps/root-task/src/control/dedupe.rs — bounded non-evicting dedupe table with deterministic capacity refusal and audit lines that preserve admission correlation when present without treating it as the dedupe key or a locally issued decision.
- apps/nine-door/src/host/proc.rs — read-only dedupe status surface for operators.
Commands: cargo test -p root-task && cargo test -p nine-door
Checks: Duplicate intent never repeats side effects; deterministic audit and /proc visibility prove dedupe behavior; admission correlation cannot change across a duplicate; legacy raw /queen/ctl behavior is either preserved or changed only with schema-bump fixtures.
Deliverables: Replay-safe Queen intent grammar with bounded dedupe state and explicit compatibility posture.
Title/ID: m27a-failover-epoch-fencing
Goal: Enforce monotonic writer-epoch fencing across local and federated host ticket flows.
Inputs: apps/host-ticket-agent, docs/FAILOVER.md, docs/INTERFACES.md
Changes:
- apps/host-ticket-agent/src/spec.rs — add writer_epoch validation plus bounded optional `admission_id`, `intent_hash`, `policy_hash`, `state_epoch`, `resource_generation`, and `decision_expiry` correlation to host-ticket schemas; validate writer ownership separately from decision freshness.
- apps/host-ticket-agent/src/relay.rs — enforce stale epoch rejection and WAL replay ordering by epoch.
- apps/host-ticket-agent/src/status.rs — expose bounded epoch/fence counters for evidence and diagnostics.
- scripts/failover_watchdog.py — make production cutover a durable transaction: verify old-writer fence, promote the new writer epoch, require uniquely correlated terminal receipts, then and only then change routing/symlink state; missing hooks, optional fencing, ambiguous receipt, failed post-cutover health, or rollback uncertainty enters fail-safe stopped state rather than silently continuing.
- docs/FAILOVER.md — describe the current optional-hook path as development-only until this gate passes and make fencing/promotion mandatory in production.
Commands: cargo test -p host-ticket-agent && cargo test -p tests --test failover
Checks: Stale writer epoch intents are rejected deterministically and deadlettered; the old writer is proven fenced before the promoted epoch can resume writes or routing changes; crash/restart at every cutover boundary converges to one writer or fail-safe stop; absent hooks never count as successful production fencing.
Deliverables: Explicit, verifiable writer fencing for active/standby failover.
Title/ID: m27a-production-secret-profile
Goal: Remove fixture/default secrets from release-grade manifests and enforce secret-reference policy.
Inputs: configs/root_task.toml, tools/coh-rtc, apps/swarmui, apps/gpu-bridge-host, scripts/release_bundle.sh, release manifests/docs, docs/SECURITY.md
Changes:
- tools/coh-rtc/src/validate.rs — reject fixture key paths and bootstrap/default secret literals in production profiles.
- configs/root_task.toml — introduce secret-reference fields for ticket and CAS signing material.
- apps/swarmui/src/lib.rs + tests — reject `changeme` and every generated placeholder before live TCP connection; permit fixture credentials only in an explicit mock/replay constructor and invert the warning-only success regression.
- apps/gpu-bridge-host/** + other live host clients — use the shared secret-reference resolver and reject placeholder or missing live credentials before transport setup.
- scripts/release_bundle.sh + release docs — remove the fixture CAS private key and placeholder-token examples, include only public verification material, and scan exact bundle contents for private-key/token canaries. Do not mutate historical release directories; publish current errata and reject them as current templates.
- scripts/ci/due_diligence_gate.sh — extend hardcoded-secret checks to generated manifests/profiles, all tracked examples/READMEs, package manifests, and assembled release contents.
Commands: cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json && cargo test -p swarmui --test tcp_console_warning && cargo test -p gpu-bridge-host && scripts/ci/due_diligence_gate.sh && scripts/release_bundle.sh --check-manifest --pi4-stage-dir out/pi4-sd
Checks: Production profile generation and release assembly fail on fixture/default/private keys, placeholder tokens, warning-only live clients, or unreferenced secret literals and pass only with scoped secret references/public verification material.
Deliverables: Release-manifest secret hygiene is compiler-enforced, not convention-only.
Title/ID: m27a-audit-replay-production-default
Goal: Ship production profile with audit/replay enabled and include fencing/dedupe state in evidence packs.
Inputs: configs/root_task.toml, apps/coh, docs/TEST_PLAN.md
Changes:
- configs/root_task.toml — production profile audit/replay defaults and bounded retention values.
- apps/coh/src/evidence.rs — include writer-epoch and dedupe status snapshots plus bounded admission/intention/policy/state/resource/expiry correlation when present, without creating a decision locally.
- docs/TEST_PLAN.md — add production-profile gate assertions for /audit and /replay availability.
Commands: cargo test -p coh && cargo test -p tests --test evidence && scripts/cohsh/run_regression_batch.sh
Checks: Evidence includes audit/replay plus fencing/dedupe state and preserves any exact admission correlation; writer and state epochs remain distinct; regression pack remains byte-stable.
Deliverables: Audit-first production baseline with deterministic incident reconstruction inputs.
Title/ID: m27a-host-ticket-validation-replay
Status: Complete — the scoped production Root version-1 parser restoration discovered by m27b-native-provider-discovery-and-actions on 15 September 2026 is closed. Strict typed arguments/correlation, current writer fencing and native ticket result delivery pass focused parser, exact QEMU and Merlin checks in docs/audit/M27B_IMPLEMENTATION_RECORD.md; the earlier M27a closure evidence remains unchanged.
Milestone: 27a / m27a-host-ticket-validation-replay; discovery: 27b / m27b-native-provider-discovery-and-actions
Goal: Harden host-ticket target/arg validation and make host side-effect replay durable across crashes.
Inputs: apps/host-ticket-agent, docs/INTERFACES.md, docs/SECURITY.md, docs/FAILOVER.md
Changes:
- apps/host-ticket-agent/src/claim.rs — parse provider-specific target and arg newtypes with strict component, length, and token validation.
- apps/host-ticket-agent/src/executors/mod.rs — dispatch only after manifest allowlist and provider grammar validation pass.
- apps/host-ticket-agent/src/wal.rs — record prepared/executed/terminal states keyed by id + idempotency_key while preserving immutable admission/intention/policy/state/resource/expiry correlation when the generated action requires it.
- apps/host-ticket-agent/tests/replay.rs — simulate crash after executor success but before status writeback.
- docs/INTERFACES.md + docs/SECURITY.md — document host-ticket validation, replay states, and deterministic refusal semantics.
Commands: cargo test -p host-ticket-agent && cargo test -p tests --test host_ticket_agent
Checks: Invalid target/arg values never reach executors; crash/restart replay publishes or deadletters existing execution state without duplicating side effects.
Deliverables: `/host/tickets/spec` is a durable, grammar-checked actuation lane rather than a best-effort command queue.
Title/ID: m27a-python-authority-contract-parity
Milestone: Milestone 27a — Authority Hardening: Delegated REST Identity, Fenced Failover, Idempotent Queen Intents / Python authority contract parity
Goal: Keep Python REST writes, Queen intents, host tickets, secret handling, and evidence capture compatible with the generated delegated-identity, idempotency, writer-epoch, and audit/replay contract.
Inputs: `m27-python-evidence-contract-parity`, `m27a-rest-delegated-identity`, `m27a-queen-ctl-idempotency`, `m27a-failover-epoch-fencing`, `m27a-production-secret-profile`, `m27a-audit-replay-production-default`, `m27a-host-ticket-validation-replay`, generated 27a policy and fixtures, tools/cohesix-py/cohesix/{auth.py,backends.py,orchestration.py,evidence.py}, tools/cohesix-py/tests/.
Changes:
- tools/cohesix-py/cohesix/backends.py + tools/cohesix-py/tests/test_rest_backend_auth.py — resolve and send gateway request authentication and a separate delegated capability ticket on mutating REST routes while preserving the existing read behavior unchanged until `m27b-read-visibility-classes`. Reject locally missing, placeholder, or malformed required credentials before mutation, and surface the gateway/agent's exact typed refusal for insufficient, overbroad, stale, or otherwise unauthorized delegated authority rather than claiming client-side authority adjudication.
- tools/coh-rtc/src/codegen/cohesix_py.rs + tools/cohesix-py/cohesix/orchestration.py + tools/cohesix-py/tests/test_orchestration.py — consume the codegen-owned strict Queen-intent compatibility mode, id/idempotency-key requirements, writer-epoch bounds, provider target/arg schemas, and deterministic stale-writer or legacy-path refusals rather than hand-maintaining a looser Python envelope or editing `generated.py` directly.
- tools/cohesix-py/cohesix/{auth.py,evidence.py} + tools/cohesix-py/tests/{test_auth.py,test_evidence_receipts.py} — reject placeholder live credentials, capture bounded writer-epoch/dedupe/audit/replay state using canonical evidence fields, and keep client observations distinct from authoritative target/provider receipts.
- docs/PYTHON_SUPPORT.md + tools/cohesix-py/README.md — document delegated REST configuration, compatibility profiles, writer-epoch behavior, typed refusals, and the fact that Python does not gain identity or replay authority beyond the generated gateway/target contract.
Commands:
- python3 -m pytest -q tools/cohesix-py/tests/test_rest_backend_auth.py tools/cohesix-py/tests/test_orchestration.py tools/cohesix-py/tests/test_evidence_receipts.py tools/cohesix-py/tests/test_auth.py
- scripts/check-generated.sh
Checks: Python cannot issue a production REST mutation without both request authentication and a delegated ticket; the gateway/agent rejects insufficient, overbroad, stale, or wrong-scope authority and Python preserves that typed refusal; Python cannot omit, regress, or reuse a stale required writer epoch; preserves legacy intent behavior only where the generated profile explicitly permits it; validates structural provider-specific ticket targets/args before append; preserves the pre-27a read contract until 27b; and reports epoch/dedupe evidence without inventing authority, successful execution, or an authoritative receipt.
Deliverables: Python clients remain protocol-faithful and fail closed under the complete Milestone 27a host/gateway authority floor.
Title/ID: m27a-gpu-bridge-auth-frame-caps
Goal: Enforce live GPU bridge auth discipline and bounded peer frame allocation.
Inputs: apps/gpu-bridge-host, docs/HOST_TOOLS.md, docs/GPU_NODES.md, docs/SECURITY.md
Changes:
- apps/gpu-bridge-host/src/main.rs — reject placeholder auth outside mock/test mode and require explicit token/env resolution for live publish.
- apps/gpu-bridge-host/src/console.rs — cap length-prefixed frames before allocation and return deterministic errors on oversize input.
- apps/gpu-bridge-host/tests/auth_frame_bounds.rs — placeholder-auth and oversized-frame negative tests.
- docs/HOST_TOOLS.md + docs/GPU_NODES.md — document live auth requirements and frame-size limits.
Commands: cargo test -p gpu-bridge-host && cargo test -p coh --features mock
Checks: Live bridge cannot start with placeholder auth; malicious or corrupted frame lengths are rejected without unbounded allocation.
Deliverables: GPU bridge remains a bounded host-side projection of Cohesix authority.
Title/ID: m27a-console-debug-memory-gate
Goal: Gate arbitrary memory diagnostics behind explicit bring-up policy and HAL-classified ranges.
Inputs: apps/root-task/src/kernel.rs, apps/root-task/src/hal, docs/SECURITY.md, docs/HARDWARE_BRINGUP.md
Changes:
- apps/root-task/src/kernel.rs — compile or profile gate raw hexdump commands out of production/release console builds.
- apps/root-task/src/hal/mod.rs — expose diagnostic-range classification for allowed bring-up memory reads where needed.
- apps/root-task/tests/console_debug_gate.rs — prove release profile rejects hexdump and bring-up profile bounds addresses/lengths.
- docs/SECURITY.md + docs/HARDWARE_BRINGUP.md — document emergency diagnostic scope and production refusal behavior.
Commands: cargo test -p root-task --test console_debug_gate && cargo test -p root-task
Checks: Production console cannot read arbitrary memory; bring-up diagnostics are range-bounded and audited.
Deliverables: Debug memory access is no longer an unbounded operator surface.
Title/ID: m27a-deferred-vm-authority-gates
Goal: Add explicit validation/docs gates that separate model-only, accepted pre-33 task/driver authority, and 33 production ticket/lease plus driver-bundle/quarantine claims.
Inputs: accepted 26e Worker/linked-driver evidence, conditional accepted Milestone 37 storage-runtime evidence, tools/coh-rtc/src/**, docs/WORKER_TICKETS.md, docs/SECURITY.md, docs/TEST_PLAN.md, docs/BUILD_PLAN.md.
Changes:
- tools/coh-rtc/src/** — profile states for model/session-only roles, accepted 26e isolated-task and linked-driver authority, conditional accepted Milestone 37 storage-runtime authority, 27a host-authority readiness, and 33 production Worker ticket/lease binding plus driver-inventory/structured-quarantine closure; no active endpoint-only compatibility tier.
- docs/WORKER_TICKETS.md + docs/SECURITY.md + docs/TEST_PLAN.md — document that 26e owns complete Worker task containment and baseline linked-driver authority and Milestone 37 owns its selected storage-runtime containment, while production Worker ledger binding, complete selected-driver inventory projection, and structured quarantine remain pending until 33 evidence exists.
Commands:
- cargo test -p coh-rtc
- scripts/check-generated.sh
Checks:
- Profiles cannot claim 33 production Worker ticket/lease binding, driver-inventory ledger projection, or structured quarantine authority from 27a alone, cannot reduce executable 26e Worker/driver authority to endpoint-only metadata compatibility, and cannot select a Milestone 37 storage runtime without its owner-milestone containment evidence.
Deliverables:
- Honest dependency gate for selected 28a–28f host work, deferred 31/34/35/42 semantic/inference/AI work, and 33 VM authority closure.
Title/ID: m27a-gateway-authority-performance
Goal: Prove delegated REST identity, idempotency, writer-epoch fencing, and audit/replay emission stay bounded in the gateway path.
Inputs: apps/hive-gateway, apps/host-ticket-agent, scripts/rest_perf_harness.py, docs/BENCHMARKS.md, docs/TEST_PLAN.md.
Changes:
- scripts/ci/gateway_perf_probe.sh — targeted gateway benchmark scenarios for read-only status, delegated writes, duplicate-idempotency refusal, stale-writer refusal, and audit/replay emission cost.
- docs/BENCHMARKS.md + docs/TEST_PLAN.md — classify gateway authority benchmark evidence separately from Pi/QEMU throughput proof.
Commands:
- scripts/ci/gateway_perf_probe.sh --scenario delegated-rest-authority --state-dir out/bench/m27a-gateway-authority
Checks:
- Read/status latency, delegated write latency, refusal counts, broker queue depth, ticket-cache behavior, and audit emission cost remain bounded or are classified before 27c/27d/27e/28d/28e depend on the gateway.
- Probe evidence preserves no-retry accounting and does not count as fresh Pi hardware throughput proof unless it exposes a runtime-path regression that triggers the full REST harness.
Deliverables:
- Gateway authority performance ledger for downstream MCP/A2A and AI-host-control milestones.
Outcome
After Milestone 27a:
- REST multiplexing retains convenience without collapsing caller identity.
- Failover safety relies on deterministic writer fencing, not operator luck.
- Queen control retries are safe by construction.
- Release profiles enforce key hygiene and enable audit-grade reconstruction by default.
- Production coexistence is still not complete until Milestone 27b turns the hardened authority floor into provider schemas, identity mapping, deployment artifacts, and conformance evidence.
- Host-side AI supervisors gain no special bypass: they inherit delegated identity, idempotency, fencing, and audit/replay before any live actuation is allowed.
- Milestone 28 can bind its per-intent decisions to durable 27a identity,
idempotency, fencing, WAL, audit, and replay records without overloading
writer_epochas state freshness. - Production Worker ticket/lease bundle binding, projection of the already complete applicable driver MMIO/DMA/shared-ring inventory, and structured quarantine/evidence remain explicitly pending for Milestone 33 rather than being buried inside the host/gateway authority floor; complete basic Worker task containment already belongs to 26e.
Milestone 27b — Executable Host Foundation
Status: Complete — 19 September 2026; selected executable foundation.
Retained-path restoration reopened for m27b-provider-action-registry only:
M27g / m27g-two-hour-pi4-operator-burn-in exposed an explicit stale-input
executor refusal becoming an ambiguous agent outcome. Preserve authenticated
pre-dispatch refusals and durably retain bound input admission failures for
lost-response reconciliation. Existing historical acceptance remains unchanged;
fresh focused native/Worker refusal and successful-work evidence is required.
Prerequisites: completed 26e, 27 and 27a.
Completion evidence: M27b implementation record. Exact QEMU admission and separately signed native/Worker chains pass real CUDA vector-add and matrix-multiply under both hardened systemd and a digest-pinned NVIDIA container. Native invocation/container/device identities and finite kernel controls are independently correlated. Focused refusal/recovery/evidence checks, safe OOM mapping, exact host/target builds and generated/Test Plan consistency pass. The full suite was not run, as requested. This closes only the selected foundation; later recipe, LoRA, packaging, UI and broad-provider qualification retain their own owners and truthful evidence status.
Goal: Qualify a small executable host foundation with one generated action contract, current scoped authority, shared evidence verification and real CUDA execution; no complete recipe, PEFT release or UI is required for closure.
The selected compatibility matrix is explicit: macOS ARM64 controller and Linux AArch64 NVIDIA CUDA host, with the maintained Mac/Pi/Jetson topology as the reference. QEMU remains the target integration lane. Jetson is a reference for the portable Linux AArch64 NVIDIA contract, not a requirement to buy that board. Retain older supported profiles and all newer working implementation; do not add an architecture or provider just for breadth. Pin actual OS, driver, CUDA/NVML, package/image and device identities at qualification; the current local work selected CUDA 13.2.2. Revalidate host availability rather than copying an old environment claim into a new result.
Required execution paths are a hardened native systemd unit and a digest-pinned NVIDIA Docker container, both using the existing host-ticket agent and bounded GPU bridge. Prove actual launch, immutable invocation/container/job/device identity, output verification, relevant enforcement and observed terminal state for each. A process exit, inventory, lease or container presence is insufficient. No free-form shell lane, arbitrary PTX, new VM protocol or second scheduler. CUDA, data, artifacts and serving remain host-side.
Use completed 27a authenticated operator approval, finite delegated scope,
allowlists, idempotency, writer fencing, secret references and WAL. Record
admission_mode=operator_approved and unavailable machine-checked admission;
never claim a later formal decision. Immediately before dispatch, recheck the
exact subject/action/target/artifact, expiry/revocation, relevant native/resource
generation and bounds. If a selected action lacks a necessary safety check,
this milestone owns the smallest complete repair, including tests and target
evidence where required, before it can qualify. No downstream control is a
substitute. Recovery and cancellation require their own current authority.
Keep requested, observed and enforced limits separate: name the enforcing native mechanism for device, memory, CPU/runtime/deadline and concurrency limits relevant to the selected workload. A CUDA allocation budget is not a hard hardware partition. Jetson shared memory uses measured free capacity and reserved OS headroom; reject unsafe requests before allocation. MIG, DLA and PVA are unsupported on the reference and do not block this physical-device lane. Retain working MIG discovery; broader MIG qualification has its own owner. NVML-to-CUDA fallback and absent sensors remain explicit capabilities.
The foundation exports durable logical operation identity before submission, per-action idempotency and attempt identity, native identity, causal refs and terminal/refusal/ambiguous states. This is sufficient for native reconciliation; 27c composes it into recipes. Cancellation requested never means confirmed cancellation. Keep unresolved native work and its reservations available for reconciliation after agent/bridge restart; never blindly redispatch.
Focused acceptance: real bounded vector-add and matrix-multiply on both selected native/container paths, independently checked outputs, wrong-device, stale inventory/authority, oversize refusal, deadline, cancel/revoke, lost ACK, restart and evidence-tamper cases. Test OOM mapping safely in an isolated capped child or deterministic fault injection; do not exhaust shared RAM. Preserve physical host, host-contract, QEMU, Pi and 26e Worker evidence as distinct proof classes. Host recovery is not Queen reboot persistence. Production seL4 Worker ticket-to-bundle binding is not claimed.
All original local implementation and historical evidence remain owned and
preserved; inventory what already works before changing it. Broad provider
completion, ecosystem-wide live qualification and domain playbooks are assigned
to 30 (m28a-native-provider-discovery-and-actions); selected useful CUDA
workload extensions belong to 28a (m28a-approved-user-workloads). Merely moving them does not disable working code or upgrade its proof.
Title/ID: m27b-provider-action-registry
Status: Reopened — retained CUDA refusal/reconciliation defect discovered by M27g; no broader provider expansion.
Milestone: 27b / provider-action-registry
Goal: Qualify selected provider/action and native execution contracts from one compiler source.
Inputs: 26e integration graph; 27a authority; actual coh-rtc, host-ticket-agent, gpu-bridge-host and native provider implementations.
Changes:
- coh-rtc IR/codegen and conformance records — exact actions, target grammar, artifact/entrypoint allowlists, topology, identity/generation, deadlines, read visibility, authority custody, state recheck, native enforcement and evidence fields; regenerate affected consumers when implemented.
- host-ticket-agent and GPU/native adapters — use native systemd D-Bus and version-negotiated Docker APIs, exact invocation/container identities, CUDA job/device binding and observed terminal postconditions.
- complete host-tool suite, Python, REST/OpenAPI and generated consumers — share schemas, refusal classes and conformance vectors; inventory retained/deferred surfaces with truthful modes.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: Selected live paths cannot bypass ticket checks, state recheck, native identity or enforcement; no downstream recipe is required by provider conformance.
Deliverables: Selected provider matrix and independently verified native/CUDA foundation evidence.
Title/ID: m27b-authoritative-receipt-and-evidence-core
Milestone: 27b / authoritative-receipt-and-evidence-core
Goal: Make every proof consumer verify the same bounded causal result graph.
Inputs: Existing cohesix-evidence, 27a audit/replay, target and native custody, CAS and exact source/profile evidence.
Changes:
- shared evidence core — preserve independent enrolled trust/custody, canonical hashes/signatures where configured, subject/action/idempotency/epoch/generation, chronology, expiry, predecessor integrity and unique terminal results.
- coh, Python, gateway, UI consumer vectors, CI/release and exporters — reject client-authored receipts, forged/missing/stale/tampered records and uncorrelated native labels; preserve explicit missing/unavailable/unverified states.
- evidence packs — retain deterministic directory layout, bounded causal graph, native event cursors and immutable external artifact refs; inspection never executes recovery. Historical offline verification never refreshes authority.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: A known native operation verifies offline with exact source refs; cross-custodian forgery, missing predecessors, duplicate terminal and corrupt CAS fail consistently. UI implementation is not needed to qualify its shared input vectors.
Deliverables: One authoritative verifier contract and honest non-authoritative operation reports.
Title/ID: m27b-scoped-authority-and-read-visibility
Milestone: 27b / scoped-authority-and-read-visibility
Goal: Close selected workflow scope, secret and visibility gaps before host execution.
Inputs: 27a tickets/approval/fencing and current identity/read-scope implementations.
Changes:
- gateway and host agents — bind approval to exact selected action/input, require current authority at dispatch, use protected secret refs and prevent cross-caller reads before payload construction.
- generated selected surface records — classify public, ticket_scoped and admin_only reads, custody/bypass assumptions and operator-approved authority; retain existing identity mappings without requiring enterprise breadth.
- negative fixtures and docs — missing/expired/revoked/widened approval, stale writer/state, wrong identity/audience, credential leakage and direct-executor bypass refusals.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: Every selected mutating path has exact authority and every read obeys its visibility; no generic admission engine or deferred proof is assumed.
Deliverables: Selected authority/visibility acceptance and secret-provisioning contract.
Title/ID: m27b-jetson-orin-nano-live-conformance
Milestone: 27b / jetson-orin-nano-live-conformance
Goal: Qualify the portable CUDA foundation on the maintained reference topology.
Inputs: Selected provider matrix, existing physical CUDA implementation, exact native host/target/package records.
Changes:
- conformance — exact CUDA/NVML/device/native invocation/container identity and independently verified vadd/matmul results through both paths, including safe refusal/cancel/deadline/restart and lost-ACK reconciliation.
- host snapshots and doctor inputs — bounded native network/Jetson power/thermal/storage observations with TTL/withdrawal and deterministic NVML fallback; no power/network/display/boot changes.
- compatibility report — distinguish controller, target and executor; preserve accepted 26e Worker correlation without production-bundle claims and record reusable earlier implementation evidence at its original identity.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: Discovery, execution, enforcement, terminal observation and output proof are separate and complete for the selected paths. No PEFT recipe, UI or broader-provider gate blocks closure.
Deliverables: Focused foundation qualification for 27c and later consumers.
Operator manuals and reference maintenance
Title/ID: m27b-operator-manuals-and-reference-maintenance
Milestone: Milestone 27b — Executable Host Foundation / Operator manuals and reference maintenance
Status: Complete — scoped validation and shared generated/Test Plan consistency checks pass.
Goal: Provide complete local cohsh manuals, aligned SwarmUI guidance, concise root help, and integrated community documentation.
Inputs: Current command handlers and generated contracts; origin/main operator guides; current M27b implementation.
Changes:
- cohsh and SwarmUI — shared host-side manuals with explicit surface restrictions and complete examples.
- root console — complete, bounded help without duplicate entries.
- AGENTS.md and public references — require integrated current usage and organize authority/provider material by topic.
Commands: Recorded in docs/audit/OPERATOR_MANUALS_RECORD.md.
Checks: Manual lookup and examples agree with dispatch and policy; host builds and focused tests; generated and Test Plan consistency checks.
Deliverables: Embedded manuals, aligned help, updated references, scoped validation record.
Milestone 27c — Recoverable CUDA Recipes
Status: Complete — 19 September 2026; bounded host CUDA recipe lifecycle.
Completion evidence: M27c implementation record. The durable CLI/Python journal, generated recipe contract, dependency-aware reuse, cumulative accounting, current-authority cancellation and canonical diagnostics pass focused contract checks. A fresh admitted CUDA recipe completes with verified output and native cleanup after a deliberately lost submission ACK; a new controller reconciles the same operation without a second CUDA submission. Both host builds, generated consistency and Test Plan checks pass. The diagnostic case explicitly retains one partial-pack lease-detail capture error; it does not claim complete release evidence. No full suite or new Pi qualification was run.
Prerequisites: completed 27b (and its earlier dependencies).
Goal: Complete one useful approved CUDA recipe through
plan -> authorise -> execute -> observe -> verify -> recover, reusing the
27b native executor, authority, verifier and artifact cache.
Choose a bounded existing CUDA workload and checked configuration from the repository; allow adopters to supply a compatible allowlisted artifact and entrypoint. This is a reusable staged recipe lifecycle, not a general workflow engine, scheduler, experiment platform or optimiser. Give every stage explicit inputs, dependencies, expected outputs, limits, authority and recovery behavior. Use existing CLI/Python command families and the host journal; no second queue, executor, receipt vocabulary, VM protocol or arbitrary shell escape.
Persist logical operation identity, recipe/configuration digest, stage/attempt identity and submission intent before dispatch. Native job identity and original idempotency survive disconnect, lost submission acknowledgement, controller or runner failure. Reconcile journal, native state and accepted evidence first; resubmit only when non-execution is established and current authority permits it. Uncertain execution remains ambiguous and retains bounded accounting/retention.
Dependency-aware stage reuse keys include workload/code, data, parameters, provider/runtime, relevant device compatibility and predecessor output digests. Reuse existing verified CAS/cache outputs only after integrity, visibility, compatibility and freshness checks. Invalidate the changed stage and descendants; do not repeat independent verified work. Reuse results, never an expired grant. Fresh execution, cancellation, cleanup and compensation need current exact scope and state checks. Artifact reuse does not imply native training resume.
Account for requested, observed and enforced limits, reservations, actual resource use and released capacity across failure and retry. Bound parallelism, retries, journal growth, artifacts and cleanup; never reset cumulative accounting on recovery or declare a resource released before confirming native termination.
Focused acceptance: one real recipe completes with verified outputs and cleanup; interruption, lost ACK, stale authority, resource refusal, output corruption and cancel/restart reconcile without duplicate CUDA execution. Changed-input tests prove selective reuse and invalidation. Export one canonical diagnostic case from actual evidence explaining a refused/failed stage, cause, remaining uncertainty and authorized recovery; it is not a second evidence format.
Title/ID: m27c-recipe-lifecycle-and-identity
Milestone: 27c / recipe-lifecycle-and-identity
Status: Complete — focused contract and live recipe evidence in audit/M27C_IMPLEMENTATION_RECORD.md.
Goal: Compose approved CUDA actions into a durable recoverable recipe.
Inputs: 27b action/native identity and verifier; existing coh run, Python orchestration, CAS and host-ticket WAL.
Changes:
- host recipe/journal and generated records — logical operation identity, bounded dependency stages, attempts, native reconciliation, terminal state and cancellation requested/confirmed distinction.
- CLI/Python — plan, status/watch, explain, verify and recover over the same record, showing topology, action/approval, native job, limits, stage reuse and exact evidence refs.
- recovery fixtures/live lane — interrupt at submission and stage boundaries; retain original idempotency and confirm native state before retry, cancel or cleanup.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: Lost ACK or runner restart resolves existing work; no ambiguous operation is duplicated and no lifecycle action bypasses fresh authority.
Deliverables: Reusable recipe lifecycle, checked CUDA example and durable recovery evidence.
Title/ID: m27c-stage-reuse-accounting-and-diagnostics
Milestone: 27c / stage-reuse-accounting-and-diagnostics
Status: Complete — focused contract and live recipe evidence in audit/M27C_IMPLEMENTATION_RECORD.md.
Goal: Reuse compatible verified results and make resource use and failures understandable.
Inputs: m27c-recipe-lifecycle-and-identity, current artifact cache and evidence/timeline tooling.
Changes:
- recipe dependency keys — exact input/output/runtime compatibility and descendant invalidation; existing cache verification and access checks.
- accounting and cleanup — separate request/observation/enforcement, retain reservations for unresolved native jobs, record confirmed release and bounded artifact retention.
- evidence case and host tools — one canonical diagnostic case, explicit blocker/recovery plan, selective-reuse measurements and docs/benchmark schema ownership.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: Independent verified stages survive a changed input; descendants rerun only when necessary and newly authorized; verified cleanup and remaining uncertainty match native evidence.
Deliverables: CUDA recipe acceptance, reuse/accounting report and canonical diagnostic case.
Agent adoption documentation
Title/ID: m27c-agent-adoption-documentation
Milestone: 27c / Agent adoption documentation
Status: Complete — owner-authorized documentation scope; validation recorded below.
Goal: Make existing Cohesix capabilities discoverable and safely usable by unfamiliar agents.
Inputs: AGENTS.md; current source/interfaces/examples; release evidence; Agent Skills specification and llms.txt convention.
Changes:
- llms.txt — concise fit guidance and task-oriented authoritative documentation map.
- skills/*/SKILL.md — minimal operational skills for inspection, governed GPU outcomes, evidence and Python usage; conditional Jetson/PEFT routing.
- README.md — expose the agent entry points without changing product behavior.
- docs/HOST_TOOLS.md, docs/HOST_API.md and docs/PYTHON_SUPPORT.md — align read-auth guidance with current implementation.
- docs/BUILD_PLAN.md — command, link, format and task-trial evidence with explicit limitations.
Commands: scripts/check-generated.sh; scripts/ci/check_test_plan.sh; applicable documentation/metadata checks; git diff --check; bounded offline examples and fresh-context task trials where available.
Checks: Current source and released behavior remain distinct; portable references and verified workflows preserve credentials, authority, side effects and evidence boundaries; unsuitable training/CUDA-installation/shell tasks and MCP/A2A requests route honestly.
Deliverables: Agent entry points, scoped compatibility review and validation record on main.
Scope: Documentation-only owner-authorized addition to 27c, independent of CUDA recipe closure. Does not activate 27d/27e or future functionality and does not require expensive target acceptance.
Agent entry points and qualification
Three standalone skills cover inspection, governed GPU outcomes and evidence,
with Python inside those workflows and conditional Jetson/PEFT guidance.
llms.txt and README route agents to matching installed-version contracts.
Discovery defines Queen and Worker, maps all six use cases and nine playbooks
to user goals, and offers a no-hardware inspection trial.
Guidance preserves scoped read credentials, exact request identity, bounded
ticket status/deadletter recovery, independent verification and the distinction
between registry updates, native serving and verified deployment. At this
entry point’s qualification, MCP/A2A were still planned 28d/28e
scope under m28d-mcp-selected-workflows and m28e-a2a-durable-jobs; these
entry points used CLI, Python and REST.
Documentation, links, generated consistency, CLI/parser checks and explicit mock/localhost-fixture exercises qualified the guidance. No live Queen/GPU/Jetson, fresh Pi, enrolled signed-verifier runtime, production adoption or release acceptance was established. The complete host-tool, Python and benchmark review required no runtime, schema, authority or workload change. Detailed commands, trials and corrections remain in the validation record.
Milestone 27d — Verified Private LoRA Release
Status: Complete — 19 September 2026. Native import and HF training, comparable evaluation, real serving promotion, regression refusal and failed-canary verified rollback pass the focused acceptance contract. Exact host/QEMU builds, boundary/refusal tests, generated consistency and Test Plan checks are recorded in the implementation record. The full staged release campaign remains Milestone 27g.
Prerequisites: completed 27b and 27c.
Goal: Make native adapter import and training through one qualified Hugging Face stack converge on a verified private adapter release using the same 27c lifecycle, native executor, durable identity and 27b verifier.
Select and pin one mutually compatible Hugging Face PEFT/Transformers/PyTorch training/evaluation stack, base model/tokenizer and real adapter-capable serving runtime on the supported CUDA host. Use small licensable reference inputs that fit measured headroom. No general inference gateway, Context Capsule system, NeMo platform, agent orchestration or new evaluator is required. Reuse existing evaluator outputs and native runtime APIs through thin typed ticket adapters.
Two entry paths are required: import a genuine native adapter with required
provenance, or train one through the qualified stack. Both converge on
validate -> evaluate -> scan -> stage -> load/reload -> canary -> promote,
with verified rollback and cleanup. An import needs no invented training job;
missing mandatory provenance cannot pass. Training records native job identity
and read-only train/checkpoint/eval/end observations, not callback authority.
Validate safetensors/config hashes, base-model revision/digest, tokenizer, framework/CUDA/runtime versions, dataset snapshot and permitted-use/license refs, resolved training settings, source provenance and required attestations. Reject path traversal/symlinks, oversized/corrupt artifacts, incompatible base/runtime, unsafe pickle import and synthetic adapter bytes/metrics in live paths. Keep weights, datasets, checkpoints and serving host-side under configured CAS roots.
Keep three things distinct: recipe workflow position, a native training checkpoint (optimizer/scheduler/RNG and exact resume compatibility), and a deployable adapter. Reuse compatible verified outputs; resume native training only where the pinned stack proves its checkpoint contract, otherwise explain and authorize a fresh attempt without overwriting earlier evidence or identities.
Candidate evaluation must compare against the currently accepted deployment using the same dataset/split/digest, preprocessing, model/base/tokenizer, evaluator/version, parameters, seed policy and comparable resource/runtime configuration. Record meaningful workload metrics, direction, sample sufficiency, predeclared acceptance bounds and critical regression guardrails. Reuse existing evaluator reports; neither Cohesix nor a client manufactures a score. Bind comparison to exact candidate and baseline artifacts, evaluation configuration, policy, target runtime and accepted deployment generation. Missing, stale, incomparable or insufficient evidence cannot pass. Immediately before promotion, recheck current authority, evidence freshness and baseline/deployment generation; a changed baseline requires renewed comparison and approval.
For first deployment, explicitly record no accepted adapter, compare against the qualified base-model/reference behavior using the same evaluation configuration, require all absolute quality/safety/compatibility bounds and human approval, and retain the pre-deployment runtime state as the rollback target. No empty baseline or zero score can manufacture an improvement claim. If a comparison or recovery target cannot be established, refuse promotion.
Use the existing host phase journal, registry lock, same-filesystem atomic writes, fsync/rename ordering and compare-and-swap deployment generations. Load the exact candidate into the real runtime, verify model/adapter identity and behavior, and observe bounded canary metrics before promotion. Publication or a registry rename is not serving. Failed reload/canary must preserve the failed candidate outcome and restore the previously accepted runtime/artifact/generation (or first-deploy base state), then verify identity, health and behavior. Failed canary plus verified rollback is recovered failure, never successful candidate release.
Focused acceptance: both imported-adapter and training paths, measured candidate versus accepted baseline, actual runtime reload/canary/promotion, a candidate regression refusal and failed-canary verified rollback. Crash/duplicate/ lost-ACK/expiry/revocation tests cover each transaction boundary. Correlate exact 26e WorkerLora receipts where the selected path requires them without claiming production ticket-to-bundle binding. Complete package adoption and UI follow later.
Title/ID: m27d-live-peft-reference-paths
Milestone: 27d / native-adapter-and-training-paths
Goal: Join native import and qualified HF training into one recipe.
Inputs: 27b executor and evidence, 27c lifecycle/cache, existing coh peft and native HF/runtime interfaces.
Changes:
- PEFT typed adapters — genuine native import and allowlisted HF training with exact artifacts, data/base/runtime compatibility and bounded native callback observations.
- 27c recipe records — distinct workflow cursor, native checkpoint and deployable adapter; dependency-aware reuse, current authorization, cancel/reconcile and cleanup.
- CLI/Python/examples/docs — supported workload/adapter configuration, deterministic provenance refusals and genuine reference artifacts.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: Both entry paths reach the same verified staging contract; synthetic adapters, incompatible checkpoints and client-created receipts fail.
Deliverables: One qualified stack, two checked entry paths and provenance/compatibility evidence.
Title/ID: m27d-evaluation-promotion-and-rollback
Milestone: 27d / evaluation-promotion-and-rollback
Goal: Release only a comparable verified candidate and recover failed canaries honestly.
Inputs: m27d-live-peft-reference-paths; accepted deployment identity; existing evaluator reports and native serving runtime.
Changes:
- comparison verifier — exact candidate/baseline/config/dataset/generation bindings, sufficient samples, meaningful metrics and critical regression guardrails; first-deployment rules.
- phase journal and native serving adapter — locked CAS staging, real load/reload, observed canary, generation-CAS promotion, current authority/evidence recheck and verified rollback.
- failure evidence and tests — missing/stale/incomparable/insufficient evaluation, candidate regression, baseline race, interruption at every phase, duplicate/lost ACK, reload/canary failure and rollback failure.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: Only the requested candidate actually served and verified can pass release; recovered failure stays failed, and unknown or failed rollback blocks further promotion.
Deliverables: Verified Private LoRA Release reference, exact evaluation/runtime evidence and recoverable transaction.
Milestone 27e — Installation, Adoption and CI
Status: Complete — 20 September 2026. Selected Mac/Linux ARM64 signed packages, explicit Python wheel/sdist builds, workflow doctor and durable CI identity/verified-outcome gates are implemented. Focused package, service, retry/refusal and lifecycle tests, native host builds, clean installs and installed verification of accepted CUDA/LoRA outcomes pass. See the implementation record for exact package/source identities, native evidence reuse and the compatibility review. The full suite, fresh assembled workflows and integrated release qualification remain 27g; no new physical Pi or production release acceptance is claimed.
Prerequisites: completed 27b, 27c and 27d.
Goal: Deliver the accepted CUDA and LoRA journeys through installable CLI/Python tools, useful doctor checks, straightforward configuration and one maintained CI example using the same logical operation and evidence contracts.
Retain the reference Mac controller, Pi control target and Jetson CUDA executor; document which components are needed for each supported deployment so an adopter need not reproduce the reference topology. A newcomer can bring a supported allowlisted CUDA artifact or native adapter using published inputs and secret references, with no hidden scripts, source patches or author-only setup. Test this as a clean-environment walkthrough, not as an invented external-user study.
Packages have exact registered artifact type/architecture/version/digest, signature/SBOM/config/schema membership, least-privilege service definitions and explicit state/CAS ownership. Reject missing/unexpected/wrong-profile artifacts, stubs, fixture keys and embedded secrets. Build Python wheel/sdist from explicit source manifests. Offline help/assets are self-contained; optional providers report unavailable without blocking the selected workflows. Doctor distinguishes controller, control target, CUDA executor, native runtime, secrets/authority, resource bounds, cache/evidence and package drift with actionable remediation.
The CI example uses ordinary runner jobs and the packaged CLI/Python contract; no CI service, custom integration platform or arbitrary shell execution lane. Choose stable logical operation/idempotency identity from workflow purpose and immutable inputs before submission; retain it outside ephemeral runner state. Retry, runner loss and lost ACK query/reconcile that identity instead of starting new training or deployment. Changed inputs create a new operation; explicit rerun intent is separate from retry. Fresh authority is required on continuation.
Submission ACK is pending, not completion. CI succeeds only when the requested CUDA output or exact LoRA candidate deployment outcome is independently verified. Refusal, ambiguity, insufficient evidence, candidate regression, failed canary with successful rollback and timeout are non-success states with evidence refs. Production credentials are unavailable to untrusted PR/fork execution and unreviewed artifacts; use protected trusted jobs/environments and bounded scoped secret refs. Dry-run validation receives no production credentials or authority.
Title/ID: m27e-packages-doctor-and-newcomer-path
Milestone: 27e / packages-doctor-and-newcomer-path
Goal: Package and document the selected workflows for clean-environment adoption.
Inputs: 27b-d accepted contracts; existing packaging/installer/release tooling, CLI/Python wheel and doctor.
Changes:
- package manifests/service definitions — exact selected contents, least privilege, protected secret refs, offline assets and state/CAS ownership.
- CLI/Python/doctor/help/manuals — one configuration and failure model; clear controller/target/executor topology and supplied-workload/native-adapter inputs.
- clean-environment walkthrough — install, configure, doctor, plan, approve, run, inspect, verify and recover using only shipped instructions.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: Both journeys work from extracted packages without hidden files or source edits; fixture/unsigned/incorrect artifacts fail; optional breadth stays explicitly unavailable.
Deliverables: Installable selected profiles, checked examples and recorded first-use friction.
Title/ID: m27e-ci-reconciliation-and-verified-gate
Milestone: 27e / ci-reconciliation-and-verified-gate
Goal: Make CI retries reconcile a stable operation and gate on the verified requested outcome.
Inputs: 27c logical identity and reconciliation; 27d deployment/evaluation generations; packaged CLI/Python.
Changes:
- one maintained CI example — persist logical identity independent of runner attempt, reconcile after lost ACK/restart and attach verified evidence to the run.
- CLI/Python outcome contract — distinguish submission, running, ambiguous, refused, cancelled, recovered failure and verified requested completion; define bounded waits and stable non-success exit mapping.
- trusted CI configuration/docs — isolate untrusted contribution validation from production credentials and deployment authority; test runner loss, duplicate retry and evidence rejection.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: Retry never duplicates training/deployment; a successful submit or successful rollback of a failed candidate never greens the candidate-release gate.
Deliverables: Ordinary CI integration with stable identity and verified-outcome acceptance.
Milestone 27f — SwarmUI Community Showcase: Spectrum Workbench + Live AI Hive
Status: Complete (2026-09-20) — editable Queen/gateway connections, guided operations, installed host tools, namespace/evidence/replay desks, plain-English contextual help and the native Spectrum/PixiJS workbench are implemented. Focused source and packaged Mac checks, native Jetson checks, signed reference journeys, screenshots and capture pass. The implementation record binds exact artifacts, final UI corrections and the retained Linux platform observation. Integrated release qualification remains 27g.
Operator experience contract: A user can open the installed application, choose a Queen or Hive Gateway, enter the endpoint and protected credentials, connect, discover available operations and complete them without a terminal or knowledge of Cohesix command grammar. Connection settings are editable in the application; environment variables remain optional compatibility inputs. Named profiles retain endpoint and non-secret preferences only. Authentication, role, delegated scope, connection ownership, refusal and reconnect state are visible. Direct Queen connections explain exclusive console ownership; gateway connections explain shared access. Failed authentication never becomes connected.
All currently supported Cohesix operations must be discoverable through labelled, validated forms, contextual actions and searchable help. Common journeys receive purpose-built entry points; advanced operations remain available through structured forms over the owning command schema. Users review consequential actions before submission and see progress, exact results, recovery and evidence. The console is an optional expert surface, never a prerequisite. Capability and profile limits explain why an operation is unavailable and the next supported step.
Appropriate host tools run from the desktop through a Rust-owned, bounded bridge to installed tools or their shared libraries. Reuse their argument validation, admission, idempotency, cancellation, durable journals and evidence verification. Do not introduce a shell executor, arbitrary executable/argument runner, provider bypass or UI-owned success classifier. Credentials stay out of saved profiles, previews, transcripts, exports and showcase assets. Long-running work remains responsive, exposes uncertainty honestly and can be reconciled through the owning lifecycle after interruption.
Delivery posture: Deliver the full Spectrum operator workbench and PixiJS showcase over the accepted CUDA/PEFT workflows. Namespace, tickets/approval, evidence, replay, console, settings, Run Story, GPU/Jetson Flight Deck and packaged-native qualification are all required. Codex has latitude over layout, interaction and polish within Rust-owned protocol and authority semantics. Semantic, general inference and formal-governance inspectors move with their backend owners; placeholders cannot count as completed functionality.
Why now (operator workflow and community energy): 20c/20d supply Tauri, Spectrum, PixiJS, and the gateway as sole console owner; 27 supplies evidence views. A navigable desktop showcase can make live Queen/Worker/Jetson work, policy, and failures understandable to newcomers and contributors.
As-built alignment note: SwarmUI uses Rust-owned Tauri transport.
Generated /worker assumptions must follow canonical
/shard/<label>/worker/<id>/telemetry; the alias exists only with
sharding.legacy_worker_alias = true. Declaration, executable lifecycle,
receipt, and proof are distinct axes, never inferred from IDs or model names.
Fake-Tauri Playwright tests do not prove the packaged native Rust bridge,
authentication, or live QEMU behavior. Labels, tickets, GPU publication, PEFT
registries, cached state, and mocks cannot establish production execution.
Prerequisites: completed 20c, 20d, 24e, 26e, 27, 27a and 27b–27e. 27b supplies the shared verifier, scoped reads and native provider truth; 27c supplies recoverable CUDA stages; 27d supplies the LoRA transaction and runtime evidence; 27e supplies packaged operator/CI contracts. Only accepted 26e Worker proof is displayed. No deferred admission, semantic, inference, protocol or production-bundle backend is a prerequisite.
Candidate packaging: use the accepted 27e assembly tools to build an
unpublished candidate for native-app and offline-asset checks in this milestone.
releases/<candidate> below denotes that exact staged bundle, not an existing
immutable release and not a dependency on the later 27g release cut.
Goal Redesign SwarmUI into a desktop-style operator workbench and community showcase that uses Spectrum for shell chrome, controls, forms, menus, dialogs, status, and workflow affordances while retaining PixiJS/Live Hive as the primary high-performance visualization surface. The UI must make the live AI journey and the seL4 authority/evidence boundary visually obvious, while keeping Secure9P namespaces, evidence packs, replay, tickets, policy gates, and gateway state navigable through familiar desktop patterns without introducing a new authority plane.
Significant frontend redesign and refactoring is explicitly in scope. The implementation may replace the current single-dashboard layout, split the large frontend controller into workbench/view/state modules, rebuild CSS around Spectrum density and layout primitives, and restructure Playwright coverage around the new desktop model. The stability boundary is the Rust-owned protocol/session/replay/evidence semantics, generated defaults, transcript grammar, and PixiJS Live Hive renderer contract, not the current HTML panel arrangement.
Non-Goals (Explicit)
- No new Cohesix console verbs, Secure9P verbs, in-VM TCP listeners, ad-hoc RPC, or UI-owned control semantics.
- No replacement of PixiJS Live Hive with DOM, SVG, D3, Spectrum charts, or a generic graph library.
- No second evidence-pack, replay, trace, or bundle format distinct from the canonical
cohsh-coretrace stack andcoh evidence packlayout. - No UI-owned semantic graph, capsule planner/store, inference protocol, provider call, or receipt format. SwarmUI may inspect accepted immutable artifacts and submit already-admitted actions only through their existing host surfaces.
- No default display or persistence of raw prompts, model outputs, retrieved source content, credentials, or model-produced tool calls.
- No hidden background watchers when a desktop view is closed, inactive, or offline.
- No generalized window manager, plugin host, web browser shell, or arbitrary host filesystem explorer.
- No CDN dependency, network font dependency, or unbounded Spectrum dependency expansion; all UI assets remain vendored/offline-safe.
- No change to ACK/ERR/END grammar, generated path defaults, namespace roots, or ticket policy unless routed through manifest IR,
coh-rtc, docs, fixtures, and regression tests in the same scoped change.
Community Showcase Experience
The showcase experience tells one truthful story rather than exposing every internal table at once:
Queen admits the operator-directed run
-> selected Worker/control path becomes active
-> Jetson external executor receives bounded work
-> GPU/model/PEFT phases progress with live metrics
-> receipt and evidence return to Cohesix
-> operator inspects, replays, promotes, rolls back, or refuses
- Live AI Hive: extend the PixiJS world model with visually distinct Queen, seL4 Worker, Pi/QEMU target, Jetson host, external model/runtime, artifact, and evidence nodes. Animated flow, pulse, and completion effects may make work feel alive, but topology, state, direction, and evidence source come only from accepted records.
- Run Story: a selected CUDA or PEFT run unfolds as a synchronized task graph and timeline: queued, approved, dispatched, GPU-active, checkpointed, evaluated, canaried, activated/rolled back, receipted, failed, or cancelled. Selecting a phase reveals its exact provider, Worker, artifact, receipt, and evidence refs.
- Jetson Flight Deck: a focused view presents board/profile identity,
runtime/provider state, GPU utilization, memory pressure, temperature/power
where available, selected model/adapter, queue wait, TTFT, decode rate, and
NVMe-backed artifact/cache health. Missing sensors or provider facts remain
unknownorunavailable; the UI never fabricates activity. - Evidence Ribbon: a compact visual chain follows intent or operator approval, ticket, Worker claim where applicable, external execution, receipt, artifact, and replay evidence. Each segment carries a visible proof class and opens the exact source rather than collapsing into one green badge.
- Showcase Mode: a presentation-safe, full-canvas layout prioritizes Live AI Hive, Run Story, the strongest current fact, and the most important blocker. It uses large readable type, smooth bounded transitions, restrained visual effects, keyboard control, and no hidden mutation.
- Replay as a feature: ship one deterministic, tamper-checked reference
replay of the complete reference walkthrough so anyone can experience the
story without hardware.
LIVE,REPLAY,FIXTURE, andOFFLINEremain persistent, high-contrast mode labels; replay can never look live by omission. - Failure is visible: cancellation, refusal, stale authority, provider timeout, Worker fault, GPU pressure, rollback, and missing evidence have designed states as polished as success. The visual language must make the containment boundary and recovery path understandable rather than merely turning the canvas red.
- Community assets: the release gate produces a hero screenshot, a short deterministic showcase capture, and an operator walkthrough generated from the same packaged application and replay/live evidence used by acceptance. Marketing assets cannot use a private fake topology or UI-only success state.
The visual direction should feel distinctive and energetic, but never become a sci-fi skin over ambiguous data. Motion communicates execution and causality; color communicates state and proof class; labels and inspectors retain exact truth for technical reviewers. Reduced-motion, keyboard navigation, contrast, and legible presentation-scale rendering are release requirements.
Desktop Model
- Application frame: compact desktop top bar with transport mode, role/ticket state, lifecycle, gateway health, pressure, replay/offline status, and active evidence target.
- Navigation dock: Spectrum action buttons or tab rail for
Hive,Namespaces,Tickets,Policy,Evidence,Replay,Console, andSettings. - Workspace: tabbed or split document area where each selected tool opens as a stable workbench view, not a stacked marketing/dashboard section.
- Inspector: right-side details for the selected worker, namespace path, recipe stage, adapter, ticket receipt, evidence pack, replay frame, or policy denial.
- Transcript drawer: bottom proof pane showing exact
OK/ERR/ENDlines for every backend action and preserving console parity. - Command palette: bounded local launcher for existing workbench actions and known paths; it must not execute arbitrary new commands or bypass role/ticket checks.
Frontend Architecture Expectations
- Split the current frontend controller into small modules for workbench routing, session/transport state, transcript state, namespace explorer state, evidence/replay state, Live Hive coordination, and shared Spectrum component wrappers.
- Keep DOM updates incremental and keyed for high-churn areas such as telemetry overlays, namespace listings, schedule/lease tables, and transcripts.
- Keep Live Hive canvas rendering independent from Spectrum layout reflows; workbench panels may select or inspect Live Hive entities, but must not make per-frame DOM updates.
- Preserve accessibility and keyboard efficiency: visible focus rings, keyboard navigation for dock/tabs/menus, command palette search, copy-path shortcuts, and screen-reader labels for status, transcript, and dialogs.
- Treat performance budgets as product requirements: bounded polling, no hidden watchers, no layout thrash in high-frequency paths, nonblank canvas proof, release-bundle asset proof, and deterministic replay screenshots.
- Existing element IDs may change when the desktop model requires it, but Playwright tests must migrate to stable user-facing roles, labels, test IDs, and replay fixtures instead of fragile dashboard layout assumptions.
Spectrum Design-System Use
- Use Spectrum components for desktop chrome and operator workflows:
sp-action-button,sp-action-group, or equivalent local wrappers for dock and toolbar commands.sp-tabsor a Spectrum-styled tab rail for workspace switching.sp-menu,sp-popover, and context menus for namespace entries, workers, evidence files, and replay artifacts.sp-dialogfor ticket minting, evidence export setup, policy approval preview, replay open, and risky write confirmation.sp-field-label,sp-textfield,sp-picker,sp-checkbox, andsp-switchfor structured forms.- Spectrum status/alert patterns for lifecycle, gateway health, policy denials, backpressure, offline/replay, and tamper rejection.
- Inventory the current vendored Spectrum bundle before adding components. Any new Spectrum component must be self-hosted, tested in the release bundle, and covered by the dependency policy.
- Spectrum tokens become the primary source for HTML UI density, spacing, focus rings, control states, and accessible contrast. PixiJS may mirror semantic colors through generated or documented tokens, but must remain a renderer over bounded telemetry state.
Live Hive Continuity
- PixiJS remains the owner of the Live Hive canvas, world model, LOD/degrade behavior, selection hooks, and replay rendering.
- Spectrum frames the Live Hive as a desktop document view:
- toolbar controls for connect/start/stop, fit/reset, detail toggle, replay speed, and snapshot source;
- status strip for frame cap, polling cadence, replay/live source, and degraded mode;
- inspector for selected worker, canonical namespace path, role, lease, schedule state, and bounded telemetry detail;
- transcript drawer for the exact
tail,cat,ls, replay, or attach proof that produced visible state.
- Live Hive state remains reconstructable from streams, traces, and CBOR snapshots. Restarting SwarmUI must not require hidden UI state to rebuild the view.
Completion boundary: Complete all listed desks, inspectors,
controls, showcase assets, replay, performance checks, and packaged native
application evidence. Policy/manifest restrictions may disable an operation in
a deployment; placeholders do not satisfy its implementation requirement.
Selected protocol integration belongs to 28d (m28d-mcp-selected-workflows)
and 28e (m28e-a2a-durable-jobs), with assembled views in 28g
(m28g-installation-and-integrated-adoption). It consumes these workbench
components without making 27f depend on a future transport.
Deliverables
- Live AI Hive, Run Story, Jetson Flight Deck, Evidence Ribbon, Showcase Mode, failure-state language, deterministic reference replay, hero screenshot, and short showcase capture described above.
- Desktop shell refactor for
apps/swarmui/frontend/with Spectrum-backed app frame, dock/tab rail, workspace, inspector, and transcript drawer. - Namespace Explorer workbench:
- path breadcrumb and tree/list split for
/proc,/queen,/shard,/workerwhen enabled,/log,/gpu,/host,/policy,/actions,/audit, and/replayas allowed by generated roots and role policy; - explicit read-only, append-only, control-file, generated, legacy-alias, and unavailable-provider labels;
- bounded
cat,tail, copy-path, reveal-in-transcript, and open-in-replay affordances.
- path breadcrumb and tree/list split for
- Evidence Desk:
- front-end workflow over existing
coh evidence pack,coh evidence timeline, CI summary, and SIEM NDJSON export; - visible pack contents, manifest/policy hashes, trace references, redaction state, and deterministic output path;
- no second pack schema or UI-owned evidence serializer.
- front-end workflow over existing
- Replay Desk:
- open trace, Hive CBOR snapshot, and evidence pack artifacts offline;
- show tamper/replay validation, trace limits, frame/ACK counts, selected timeline event, and Live Hive replay source;
- network access remains disabled in offline/replay mode.
- Tickets and Policy Desk:
- read-only ticket status/deadletter, idempotency key, relay fields, policy rules, pressure, audit, and approval queue views;
- command-preview forms for existing host-ticket or approval lines, with submit disabled unless the active milestone/profile admits the write path.
- Live Hive desktop integration:
- preserve PixiJS renderer and replay fixtures;
- update canvas framing, toolbar, inspector, worker selection, canonical shard path display, and
No telemetry yetremediation flow. - render declaration, session, executable lifecycle, provider receipt, external-executor result, 26e target proof as separate fields; production-binding/quarantine inspectors belong to 33 (
m28d-production-binding-workbench-inspector). Missing or mock integration rows display their generated mode and never collapse into a generic healthy/ready badge.
- UI performance gate:
- add deterministic source and release-bundle checks for Live Hive frame cadence, pending-event backlog, inactive-view polling, replay rendering, and layout thrash under fixture load;
- record UI render/backlog metrics separately from REST or Pi hardware performance; UI regressions do not reopen driver/runtime performance unless the transcript or gateway evidence shows backend slowdown.
- Native application integration gate:
- retain the injected-Tauri Playwright suite as the fast deterministic frontend fixture lane, but add a separately labelled packaged native-Tauri lane that launches the real Rust/WebView command bridge and connects through an authenticated
hive-gatewayto an accepted QEMU image; - exercise login/secret-ref refusal, canonical
/shardbrowsing, executable/model-only Worker distinctions, authoritative provider/Worker receipts, Live Hive updates/backpressure, disconnect/reconnect, replay/offline isolation, and clean shutdown without injectingwindow.__TAURI__, canned command replies, or target topology; - run the same lane against the release-bundle application and bind results to app, gateway, registry, and QEMU image identities.
- retain the injected-Tauri Playwright suite as the fast deterministic frontend fixture lane, but add a separately labelled packaged native-Tauri lane that launches the real Rust/WebView command bridge and connects through an authenticated
- Documentation updates:
docs/USERLAND_AND_CLI.mddescribes the SwarmUI desktop workbench, Spectrum/PixiJS split, namespace navigation, evidence desk, replay desk, and non-goals.docs/INTERFACES.mdrecords that the UI remains a projection of existing Secure9P/console/evidence/replay semantics.docs/TEST_PLAN.mdrecords Rust, generated-drift, replay, and Playwright validation.
Commands
cargo fmt --all -- --checkcargo test -p swarmuicargo test -p swarmui --test transcriptcargo test -p swarmui --test console_paritycargo test -p swarmui --test securitycargo test -p swarmui --test cachecargo test -p swarmui --test tracecargo test -p swarmui --test replaycargo test -p coh --test evidencecargo test -p cohsh --test tracescripts/check-generated.shcd tools/swarmui-ui-tests && npm cicd tools/swarmui-ui-tests && npx playwright install webkitcd tools/swarmui-ui-tests && npm testcd tools/swarmui-ui-tests && npm test -- --grep live-hive-performancescripts/ci/swarmui_native_e2e.sh --target qemu --state-dir out/swarmui-native/m27fSWARMUI_RELEASE_DIR=../../releases/<candidate> npm testfromtools/swarmui-ui-testsduring release-bundle validation.
Checks (DoD)
- A first-time viewer can follow one accepted CUDA or PEFT run from operator approval through Jetson execution to receipt/evidence and can open the exact supporting record from every visual phase.
- Visual flow, pulse, completion, and fault effects are derived from immutable event/receipt ordering; animation timing, cached UI state, screenshots, or replay controls cannot create readiness, execution, success, or proof.
- Showcase Mode, the hero screenshot, and the short capture visibly retain
LIVE,REPLAY,FIXTURE, orOFFLINEmode plus host-only/QEMU/Pi proof classification and the strongest missing evidence. - Jetson Flight Deck reports only registered provider/host facts and preserves
unknownorunavailablesensors, runtime capabilities, and evidence. - SwarmUI uses Spectrum for desktop shell, controls, forms, menus, dialogs, status, focus, and workflow chrome while PixiJS remains the only Live Hive rendering engine.
- The frontend is refactored into coherent workbench modules;
app.jsdoes not remain a monolithic controller for every view, transcript, and Live Hive interaction. - UI actions preserve byte-stable
OK/ERR/ENDtranscripts for equivalentcohshoperations; no ACK grammar, NineDoor error,/procformat, trace, or evidence-pack schema drift occurs. - Namespace Explorer rejects relative paths,
.,.., NUL, over-depth walks, unsupported roots, and paths outside role/ticket scope before reaching provider logic. - Canonical
/shard/<label>/worker/<id>/telemetryis preferred in labels and inspectors; legacy/worker/<id>/telemetryis shown only as a generated compatibility alias when enabled. - Evidence Desk invokes/reuses canonical evidence-pack and timeline internals and never serializes a UI-specific pack format or raw auth tokens/tickets.
- Replay Desk rejects tampered traces and oversized artifacts, disables network access in offline/replay mode, and reconstructs Live Hive state from trace/CBOR/evidence artifacts only.
- Ticket/Policy Desk shows status and denials without granting new authority; any write-capable affordance is explicitly gated by active profile/milestone state and emits transcript proof.
- Worker/provider/use-case state comes from the generated 27b graph and correlated evidence records. UI ids, labels, tickets,
/gpu/models, PEFT registry entries, telemetry, or cached snapshots cannot independently create executable, live-provider, production-bundle, or production-use-case status. - Direct TCP mode clearly warns about single-client console ownership; REST/gateway mode presents gateway health, request-auth state, and backpressure counters before operators tune publish rates.
- No hidden polling or background watchers run when a workbench view is inactive, stopped, or offline; Live Hive polling remains bounded by generated defaults.
- Playwright desktop and narrow screenshots are updated intentionally, with checks for nonblank PixiJS canvas, visible legends/status, text fit, no overlapping controls, keyboard/focus behavior, and accessible labels.
- Live Hive UI performance evidence records frame cadence, pending/backlog bounds, inactive-view polling state, and replay render stability for source and release-bundle runs; failures are fixed in the UI/render loop unless backend transcript evidence proves a runtime regression.
- Release-bundle UI tests pass against the assembled candidate assets, not only source files.
- The native-Tauri source and release lanes use the actual packaged app, Rust command bridge, authenticated gateway, and accepted QEMU image; placeholder auth fails before connection, injected/canned bridge state is absent, and identity-bound evidence covers namespace, Worker/integration truth, Live Hive pressure/reconnect, replay isolation, and shutdown.
Compiler touchpoints
coh-rtcremains the source for SwarmUI path roots, cache limits, trace limits, Live Hive frame/LOD limits, line caps, ticket scope, and any new desktop-workbench defaults.coh-rtcgenerates SwarmUI views of 27b integration/use-case and native evidence axes, 27c recipe and 27d PEFT phase/receipt fields, and accepted 26e Worker evidence. Frontend code may format but not reclassify them.- If additional UI roots, Spectrum component allowlists, evidence-desk defaults, replay-desk defaults, or workbench view limits are needed, add manifest IR and regenerate
apps/swarmui/src/generated.rs,docs/snippets/swarmui_defaults.md, docs snippets, and tests in the same change. - Generated docs must be refreshed before implementation patches land; stale embedded snippets in
docs/USERLAND_AND_CLI.mdor other canonical docs block merge.
Task Breakdown
Title/ID: m27f-connections-and-guided-operations
Milestone: 27f / m27f-connections-and-guided-operations
Goal: Make every supported operator journey discoverable and executable from the installed UI without terminal use or command-grammar knowledge.
Inputs: Existing Rust console/session contracts, coh host-tool argument schemas and 27b-e lifecycle/evidence libraries, generated deployment policy, installed tool bundle.
Changes:
- Rust session bridge and connection desk — editable Queen/gateway endpoints, protected credentials, role/ticket selection, non-secret profiles, explicit disconnect and recoverable reconnect.
- Guided operation catalog and contextual forms — searchable supported commands, field help, validation, exact review, authority/refusal explanations and evidence-linked results.
- Host-tool bridge — schema-bound installed tools/shared libraries, bounded output and process ownership, progress and durable lifecycle reconciliation, without a shell or provider shortcut.
- Native/fixture acceptance and guides — first-launch connection, both transport modes, invalid credentials/input, guided mutation refusal, canonical host workflows, recovery, keyboard navigation and secret non-persistence.
Commands: Focused SwarmUI/owning-schema tests, exact affected host builds, desktop/narrow UI checks, packaged native source/candidate journeys, generated and Test Plan consistency; no duplicate or full-workspace suite.
Checks: No supported operation requires the terminal; previews match the owning parser; invalid input/authority and offline mode fail closed; secrets are absent from persisted/exported UI state; native operations retain canonical outcome and evidence semantics.
Deliverables: Terminal-free connection and operation workflows integrated into the complete 27f workbench.
Title/ID: m27f-swarmui-scope-and-drift
Goal: Establish the desktop-workbench scope and clear generated-doc/grammar drift before changing UI layout.
Inputs: AGENTS.md, docs/BUILD_PLAN.md, docs/USERLAND_AND_CLI.md, docs/snippets/*.md, tools/coh-rtc/tests/swarmui_docs.rs, apps/swarmui/src/generated.rs, crates/cohsh-core/src/verb.rs, apps/cohsh/src/lib.rs, apps/swarmui/src/lib.rs
Changes:
- docs/USERLAND_AND_CLI.md — refresh generated snippets and document the desktop-workbench non-goals.
- tools/coh-rtc/tests/swarmui_docs.rs — keep generated SwarmUI snippet checks authoritative.
- docs/INTERFACES.md — record Spectrum/PixiJS split and no-new-semantics guardrails.
Commands:
- scripts/check-generated.sh
- cargo test -p swarmui --test transcript
- cargo test -p swarmui --test console_parity
Checks:
- Embedded generated snippets match docs/snippets and generated Rust.
- Echo grammar documentation agrees with actual parser/help or the mismatch is resolved through the manifest/compiler path.
- No protocol, ACK, path, ticket, or evidence semantics change in this task.
Deliverables:
- Clean scope baseline for the SwarmUI desktop redesign.
Title/ID: m27f-integration-truth-model
Milestone: 27f / m27f-integration-truth-model
Goal: Replace inferred Worker/provider health with generated declaration, lifecycle, receipt, executor, proof, and use-case axes.
Inputs: 27b host-integration/use-case registries, accepted 26e Worker evidence, apps/swarmui/src/**, apps/swarmui/frontend/hive/**, replay fixtures.
Changes:
- apps/swarmui/src/** — parse and correlate generated integration/use-case rows plus 26e and selected host evidence without deriving role or maturity from ids, model/session entries, tickets, or telemetry.
- apps/swarmui/frontend/hive/** + inspector views — render declaration, session, executable lifecycle, provider receipt, external outcome, target proof, confirmed native recovery and use-case maturity independently.
- apps/swarmui/tests/** + tools/swarmui-ui-tests/** — negative fixtures for model-only sessions, mock providers, stale receipts, mismatched target proof, unavailable production binding, and cached/replay state.
Commands:
- cargo test -p swarmui
- cd tools/swarmui-ui-tests && npm test -- --grep integration-truth
Checks:
- No UI path synthesizes executable Worker, live provider/executor, production bundle, or production use-case state; absent/stale/mismatched evidence is visible and deterministic in live and replay modes.
Deliverables:
- SwarmUI communicates the real end-to-end integration state without collapsing independent proof layers.
Title/ID: m27f-concise-contextual-help
Goal: Help a novice or occasional operator understand the next step in plain English, without assuming Cohesix terminology or cluttering the workbench.
Inputs: Existing inline guidance, shared command manuals, vendored Spectrum controls and the completed desktop desks.
Changes:
- One discreet screen-help control plus brief hints for presentation, transcript, recent activity and snapshot naming.
- Spectrum-styled plain-text tooltips support hover, keyboard focus, Escape and touch; essential authority and input guidance remains visible inline.
Commands: Focused help/accessibility browser cases; exact Mac and Jetson native builds and help smoke checks; generated consistency.
Checks: Hints are concise, remain in the viewport, dismiss predictably, introduce no network dependency and never execute an operation.
Deliverables: Discoverable contextual help and an updated operator guide.
Title/ID: m27f-spectrum-desktop-shell
Goal: Rebuild SwarmUI chrome around Spectrum-backed desktop primitives and split the frontend into maintainable workbench modules while preserving backend protocol semantics.
Inputs: apps/swarmui/frontend/index.html, apps/swarmui/frontend/app.js, apps/swarmui/frontend/styles/**, apps/swarmui/frontend/components/**, apps/swarmui/frontend/vendor/spectrum.bundle.js, tools/swarmui-ui-tests/**
Changes:
- apps/swarmui/frontend/index.html — introduce app frame, navigation dock/tab rail, workspace, inspector, and transcript drawer.
- apps/swarmui/frontend/app.js — split monolithic controller behavior into workbench routing, state, transcript, namespace, evidence/replay, and Live Hive coordination modules.
- apps/swarmui/frontend/styles/** — align layout, density, focus, status, and form styling with Spectrum tokens and remove dashboard-specific layout assumptions.
- apps/swarmui/frontend/components/** — add reusable workbench, toolbar, status, dialog, menu, command-palette, and inspector wrappers around vendored Spectrum components.
- tools/swarmui-ui-tests/** — update UI-only desktop/narrow tests and screenshots to target stable user-facing roles, labels, test IDs, and replay fixtures.
Commands:
- cargo test -p swarmui
- cd tools/swarmui-ui-tests && npm test
Checks:
- Existing Tauri command names and backend semantics remain stable even if frontend module boundaries and DOM structure change substantially.
- `app.js` is no longer the owner of all workbench, transcript, namespace, evidence/replay, and Live Hive UI behavior.
- Spectrum components render offline from vendored assets with no CDN or network dependency.
- Desktop and narrow layouts have no overlapping controls, clipped text, unreachable focus targets, or keyboard traps.
Deliverables:
- Spectrum-backed SwarmUI workbench shell.
Title/ID: m27f-namespace-explorer
Status: Reopened narrowly — M27g / m27g-assembled-journeys-and-recovery observed a native file preview under the previous directory's heading and breadcrumb. Bind visible path metadata to each read response, including refusals, and require focused presentation plus native revalidation.
Goal: Replace the root picker with a desktop namespace explorer that makes Secure9P paths familiar and safe.
Inputs: apps/swarmui/src/lib.rs, apps/swarmui/src-tauri/main.rs, apps/swarmui/frontend/**, configs/root_task.toml, docs/ROLES_AND_SCHEDULING.md, docs/SECURE9P.md, tests/fixtures/traces/trace_v0.trace
Changes:
- apps/swarmui/src/lib.rs — add read-only list/cat/tail helpers if needed without changing command grammar or provider semantics.
- apps/swarmui/frontend/** — add breadcrumb, tree/list split, preview/tail pane, path copy, transcript reveal, and path metadata labels.
- docs/USERLAND_AND_CLI.md — document canonical shard navigation and legacy `/worker` alias presentation.
Commands:
- cargo test -p swarmui --test security
- cargo test -p swarmui --test trace
- cd tools/swarmui-ui-tests && npm test
Checks:
- Absolute-path, walk-depth, role/ticket, legacy-alias, and unsupported-root behavior is enforced and visible.
- `ls`, `cat`, and `tail` transcript order remains byte-stable with `cohsh`.
Deliverables:
- Secure9P namespace explorer suitable for day-to-day operator browsing.
Title/ID: m27f-evidence-and-replay-desks
Goal: Make evidence packs, timelines, traces, snapshots, and replay first-class desktop workbench flows using canonical artifacts only.
Inputs: apps/coh evidence internals, apps/swarmui/src/cache.rs, apps/swarmui/src/hive.rs, apps/swarmui/src-tauri/main.rs, crates/cohsh-core/src/trace.rs, tools/cohesix-py/examples/ci_evidence_pack.py, tools/cohesix-py/examples/siem_export_ndjson.py, docs/OPERATOR_WALKTHROUGH.md
Changes:
- apps/swarmui/src/** — expose host-side wrappers or shared read-only internals for evidence/timeline/replay metadata where milestone 27 provides them.
- apps/swarmui/frontend/** — add Evidence Desk and Replay Desk views with pack contents, hashes, validation, timeline, SIEM/CI export, and Live Hive replay source selection.
- docs/USERLAND_AND_CLI.md + docs/TEST_PLAN.md — document evidence/replay workflows and validation.
Commands:
- cargo test -p swarmui --test cache
- cargo test -p swarmui --test replay
- cargo test -p swarmui --test trace
- cargo test -p coh --test evidence
- cd tools/swarmui-ui-tests && npm test
Checks:
- Evidence Desk reuses canonical pack/timeline output and does not leak raw tickets or auth tokens.
- Replay Desk rejects tampered/oversized traces and keeps network disabled in offline/replay mode.
- Live Hive replay remains deterministic from trace-adjacent `.hive.cbor` and snapshot CBOR artifacts.
Deliverables:
- Desktop evidence and replay workflows ready for audit, support, CI, and demos.
Title/ID: m27f-live-ai-community-showcase
Milestone: 27f / m27f-live-ai-community-showcase
Goal: Turn the exact reference CUDA and Verified Private LoRA Release journeys into a
visually compelling, deterministic, truth-preserving Live AI Hive story and
community demo.
Inputs: accepted 26e QEMU/Pi Worker evidence; 27b native CUDA/provider and verifier records; 27c recipe/cancellation/recovery records; 27d import/training/evaluation/runtime/canary/promotion/rollback evidence; 27e packages; Milestone 27 case/timeline output; PixiJS renderer; packaged SwarmUI and deterministic replay fixtures.
Changes:
- apps/swarmui/frontend/hive/** — add distinct Queen, seL4 Worker, target,
Jetson host, external runtime/model, artifact, and evidence visual entities
plus bounded flow/pulse/completion/failure effects driven only by accepted
records.
- apps/swarmui/frontend/** — add Run Story, Jetson Flight Deck, Evidence
Ribbon, Showcase Mode, persistent live/replay/fixture/offline labelling,
reduced-motion support, and designed cancellation/refusal/fault/rollback/
missing-evidence states.
- apps/swarmui/src/** — consume shared generated integration, run, receipt,
evidence, and hardware/provider snapshots without adding a UI receipt,
health classifier, provider client, or success state.
- tools/swarmui-ui-tests/** + apps/swarmui/tests/** — deterministic complete-
journey, false-promotion, mode-label, reduced-motion, presentation-layout,
failure-state, evidence-correlation, and replay-tamper coverage.
- scripts/ci/swarmui_showcase_capture.sh + release assembly — produce the
hero screenshot and short deterministic showcase capture from the packaged
application and accepted replay/live inputs; no private fake topology.
- docs/OPERATOR_WALKTHROUGH.md + docs/USERLAND_AND_CLI.md + release notes —
explain the visible story, proof classes, live/replay distinction, and
exact reference journey.
Commands:
- cargo test -p swarmui --test live_ai_showcase
- cd tools/swarmui-ui-tests && npm test -- --grep live-ai-showcase
- scripts/ci/swarmui_native_e2e.sh --target qemu --state-dir out/swarmui-native/m27f
- scripts/ci/swarmui_showcase_capture.sh --result out/swarmui-native/m27f/result.json --out out/swarmui-showcase/m27f.html
Checks:
- A viewer can distinguish Queen, seL4 Worker, Pi/QEMU target, Jetson host,
external AI runtime, artifact, and evidence ownership without opening a
debug table; the inspector provides the exact identities and refs.
- The full CUDA/PEFT story is reconstructable from accepted records and
the same evidence pack; UI animation order cannot become execution truth.
- Live, replay, fixture, offline, host-only, QEMU, Pi, and unavailable states
remain persistently and accessibly labelled in the application, screenshot,
and capture.
- Cancellation, refusal, stale state, timeout, fault, rollback, and missing
evidence are polished deterministic states and never collapse into generic
failure or false readiness.
- Presentation mode remains responsive, readable, bounded, keyboard usable,
reduced-motion compatible, and free of hidden mutation or network access
during replay.
Deliverables:
- Packaged Live AI Hive showcase, deterministic reference replay, hero
screenshot, short capture, and operator walkthrough that make Cohesix's
real architecture exciting without weakening its evidence discipline.
Title/ID: m27f-live-hive-continuity
Goal: Preserve PixiJS Live Hive while integrating it into the desktop workbench with Spectrum toolbar and inspector controls.
Inputs: apps/swarmui/frontend/hive/**, apps/swarmui/frontend/app.js, apps/swarmui/frontend/styles/hive.css, apps/swarmui/tests/replay.rs, tools/swarmui-ui-tests/tests/swarmui.spec.js
Changes:
- apps/swarmui/frontend/hive/** — preserve PixiJS renderer, world model, LOD, and debug hooks while accepting workbench selection/inspector events.
- apps/swarmui/frontend/** — add Spectrum toolbar, source status, replay speed, fit/reset, detail toggle, and selected-worker inspector.
- tools/swarmui-ui-tests/** — assert canvas is nonblank, responsive, and framed correctly across desktop/narrow modes.
Commands:
- cargo test -p swarmui --test replay
- cd tools/swarmui-ui-tests && npm test
- cd tools/swarmui-ui-tests && npm test -- --grep live-hive-performance
Checks:
- PixiJS remains the rendering engine; Spectrum does not replace canvas rendering.
- Selection, overlays, details, replay, and degraded-mode indicators remain bounded and reconstructable.
- Canvas pixel checks, screenshots, and Live Hive performance checks prove nonblank rendering, bounded frame cadence/backlog, inactive-view polling state, and no UI overlap.
Deliverables:
- Live Hive preserved as the high-performance visualization inside the desktop workbench.
Title/ID: m27f-native-tauri-live-e2e
Milestone: 27f / m27f-native-tauri-live-e2e
Goal: Prove the real packaged Tauri application, Rust command bridge, authenticated gateway, and accepted QEMU runtime work together without injected frontend responses.
Inputs: m27b-authoritative-receipt-and-evidence-core, accepted QEMU image/evidence, apps/swarmui/{src,src-tauri,frontend,tauri.conf.json}, apps/hive-gateway, generated integration/use-case registries, tools/swarmui-ui-tests fixture lane, release application bundle, docs/TEST_PLAN.md.
Changes:
- scripts/ci/swarmui_native_e2e.sh + native harness — build/launch the real Tauri app and gateway, provision auth through secret refs, bind exact app/gateway/registry/QEMU identities, drive the actual WebView-to-Rust command path, collect bounded logs/screenshots/evidence, and terminate all processes deterministically.
- native scenarios — validate placeholder/missing auth refusal, canonical `/shard` navigation, model-only versus executable Worker rendering, authoritative and stale/mismatched receipt handling, Live Hive state/pressure/backpressure, disconnect/reconnect, replay/offline network isolation, and clean shutdown against accepted QEMU state.
- tools/swarmui-ui-tests/** — retain injected Tauri responses only in the explicitly classified frontend fixture lane; make test output and evidence metadata state `fixture` versus `native_live`, and forbid fixture output from satisfying this task or release acceptance.
- release gate — repeat the native scenarios from the packaged SwarmUI/gateway artifacts with offline assets and exact manifest verification.
Commands:
- cargo test -p swarmui
- scripts/ci/swarmui_native_e2e.sh --target qemu --state-dir out/swarmui-native/m27f-source
- scripts/ci/swarmui_native_e2e.sh --target qemu --release-dir releases/<candidate> --state-dir out/swarmui-native/m27f-release
Checks:
- No native-live scenario injects `window.__TAURI__`, canned invoke replies, fake topology, placeholder credentials, or fixture receipts.
- Source and packaged lanes exercise the same real command/session/reconnect/evidence paths and bind every result to immutable app, gateway, registry, and QEMU identities.
- The deterministic Playwright fixture lane remains fast and useful but cannot promote native integration or release status.
Deliverables:
- Native SwarmUI integration evidence across the actual application, host gateway, and Cohesix runtime.
Title/ID: m27f-release-bundle-ui-regression
Goal: Prove the redesigned workbench works from source and the assembled candidate bundle without hidden runtime or asset assumptions.
Inputs: m27f-native-tauri-live-e2e, tools/swarmui-ui-tests/**, releases/<candidate>/ui/swarmui/**, apps/swarmui/frontend/**, docs/TEST_PLAN.md
Changes:
- tools/swarmui-ui-tests/** — add desktop workbench regression coverage for dock, tabs, namespace explorer, evidence desk, replay desk, Live Hive, console, and dialogs.
- docs/TEST_PLAN.md — update SwarmUI UI regression commands and screenshot policy.
Commands:
- cd tools/swarmui-ui-tests && npm ci
- cd tools/swarmui-ui-tests && npx playwright install webkit
- cd tools/swarmui-ui-tests && npm test
- cd tools/swarmui-ui-tests && npm test -- --grep live-hive-performance
- cd tools/swarmui-ui-tests && SWARMUI_RELEASE_DIR=../../releases/<candidate> npm test
- cd tools/swarmui-ui-tests && SWARMUI_RELEASE_DIR=../../releases/<candidate> npm test -- --grep live-hive-performance
- scripts/ci/swarmui_native_e2e.sh --target qemu --release-dir releases/<candidate> --state-dir out/swarmui-native/m27f-release
Checks:
- Source and release-bundle frontend tests pass with deterministic fixtures, and the separate native release lane passes without injected bridge state.
- Screenshots are intentionally updated and stable.
- Release bundle includes all Spectrum, icon, font, and PixiJS assets needed for offline operation.
- Source and release-bundle Live Hive performance checks record frame cadence, pending/backlog bounds, inactive-view polling state, and replay stability separately from backend REST/Pi performance.
Deliverables:
- Replay-first UI regression gate for the SwarmUI desktop workbench.
Outcome After Milestone 27f:
- SwarmUI is the primary desktop operator workbench for Cohesix, not a dense single-page dashboard.
- Operators can browse Secure9P namespaces with file-manager familiarity while still seeing exact role/ticket/path bounds.
- Evidence packs, timelines, traces, snapshots, and Live Hive replay are first-class, deterministic desktop workflows.
- Deferred backend inspectors are delivered with their owning milestones; the release workbench remains complete for the supported CUDA/PEFT journeys.
- Spectrum owns the desktop interaction language; PixiJS Live Hive remains the rendering engine for hive state.
- Cohesix gains usability without increasing the VM TCB, adding protocols, weakening transcript parity, or creating a second evidence/replay format.
Title/ID: m27f-tickets-approvals-console-and-settings
Milestone: 27f / tickets-approvals-console-and-settings
Goal: Complete the supported operator controls with clear approval, refusal and recovery states.
Inputs: 27a authority, 27b scoped reads, 27c-d lifecycle and 27e package configuration; existing SwarmUI Rust command/session paths.
Changes:
- Spectrum forms/desks — ticket status, approval queues, exact action previews, policy refusal explanations, cancellation requested/confirmed and evidence-linked recovery; preserve original logical operation identity.
- console/settings — byte-stable transcript parity, protected secret refs, transport/topology and provider availability, polling/render bounds and offline-safe preferences.
- accessibility/native checks — keyboard-only workflows, focus restoration, screen-reader labels, contrast, reduced motion and persistent LIVE/REPLAY/FIXTURE/OFFLINE/unavailable states.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: All supported workflows are usable from the packaged app; stale authority disables mutation, rejection remains understandable and no UI state can invent success.
Deliverables: Complete operator controls and accessibility evidence, alongside the full workbench/showcase tasks.
Milestone 27g — Integrated Qualification and Next Release
Status: Complete — owner-approved limited Release A qualification, 23 September 2026.
The repaired two-hour Pi/Mac/Linux burn-in, post-burn staged plans, QEMU
pressure and exact-source merge baseline passed at their recorded identities.
The installed 7b4a08d95 Pi SD candidate passed raw readback, fresh numbered
U-Boot-menu GENET static, GENET DHCP and Wi-Fi DHCP boots, packaged TCP checks,
a final Apple Home power-cycled GENET boot and HDMI observation. The final
archive has the same 27 embedded files but different FAT metadata; its raw
bytes were not written and read back, and no fresh 10-cold/10-warm Wi-Fi
series was run. Lukas Bower explicitly selected the final GENET cold boot and
approved publication with these limits on 23 September. This scoped release
decision does not give the final raw image a media-readback PASS, make the
three-archive verifier PASS, or extend M26e Wi-Fi/repeatability acceptance to
the new image. The qualification record
retains the passing results and owner-accepted gaps.
Prerequisites: completed 27b, 27c, 27d, 27e and 27f.
Goal: Qualify the exact assembled next release across complete CUDA and Verified Private LoRA Release journeys, CLI/Python/CI and the packaged native UI. Earlier milestones own focused conformance; this stage verifies their composition and packaging without adding deferred features or inventing a second executor.
Run from exact assembled artifacts, with selected source/image/manifest, compiler/provider/runtime, trust, package and replay identities. Exercise both journeys through the published CLI/Python and maintained CI entrypoints, then inspect/control/recover them in the actual native SwarmUI via the authenticated gateway. Include both native adapter import and training for LoRA. Native runtime and target proof stay separate. Apply the complete applicable staged TEST_PLAN, pressure/repeatability, due-diligence, human-review and promotion requirements; prior component success never substitutes for assembled release evidence.
Before the complete staged Test Plan, execute the two-hour Pi 4/Mac/Linux AArch64 NVIDIA operator burn-in below. Target-entry checks and focused defect checks may precede it; the full release test plan follows successful burn-in.
The selected defaults enable the existing host-provider paths consistently on
QEMU and Pi: Mac launchd actions remain bound to compiler-enrolled services,
native network discovery uses its measured host helper, and read-only endpoint
compliance is enrolled and published by default. M27g owns this assembled
configuration and provisioning correction; it does not implement deferred 30
providers (m28a-native-provider-discovery-and-actions) or claim their broader
qualification. Retain existing admission,
credential, exact native target and Worker-receipt boundaries.
Compatibility review for these defaults covers coh/coh-status, cohsh, Hive Gateway, SwarmUI, host-ticket-agent, host-sidecar-bridge, gpu-bridge-host, cas-tool, sidecar-bus, the Python SDK and benchmark scripts. Regenerate their manifest/provider projections and rebuild the selected host packages. Existing CLI grammar, wire formats, GPU/PEFT receipt matrix and benchmark thresholds remain applicable. The user-approved M27a restoration permits and selects 512 non-evicting Queen intent entries in matching QEMU/Pi Release A profiles under manifest schema 1.28; compatibility policy defaults and all other quotas remain unchanged. Include fault-preflight reservations in the frozen pressure budget; Mac service actions use the existing version-1 host-ticket contract and do not acquire Worker receipt authority.
Integrated cases cover interrupted execution, runner failure/lost ACK, stale or revoked authority, relevant resource refusal, changed inputs/cache invalidation, candidate regression, stale/incomparable/insufficient evaluation, failed canary, verified rollback and missing/tampered evidence. Confirm no duplicate native work, no false success and no leaked reservations. CI must remain failed when the requested candidate was not released, even after successful recovery. Replay and fixture evidence cannot substitute for live host execution or native-app proof.
Measure first-use steps/time, manual interventions, repeated versus reused work, recovery time/outcome, resource use and Cohesix overhead against the same native CUDA/HF/serving stack with comparable inputs/configuration on the same host. Report native compute, Cohesix orchestration/verification, gateway and UI cost separately with exact conditions and uncertainty. Reuse compatible component measurements under TEST_PLAN provenance rules; do not invent results, speedups or external-user tests, and do not change benchmark thresholds to pass.
Retain reserved Release A = 1.1.0-beta, B = 1.2.0, C = 1.3.0-beta
and Cohesix-<release-version>-<platform> artifact naming. This is the A cut; B/C
remain reserved for later qualified delivery. Existing release files, exception
records and accepted/historical evidence are immutable. A plan or successful
build cannot create release acceptance.
Title/ID: m27g-assembled-journeys-and-recovery
Milestone: 27g / assembled-journeys-and-recovery
Goal: Qualify both complete journeys from the exact assembled artifacts.
Inputs: 27b-f focused acceptance, exact packages/target images, TEST_PLAN and canonical release checklist.
Changes:
- release integration matrix — CLI/Python/CI and packaged native UI over CUDA plus LoRA import/training, including required negative/recovery cases and exact identities.
- evidence/acceptance — independently verify every requested outcome, correlate target and provider proofs and preserve blockers/non-claims and historical exceptions.
- walkthrough/replay/showcase — qualify shipped instructions and native assets against the same accepted execution graph.
- delegated pressure evidence — preserve each caller's delegated authority through the retired-result test proxy and Worker-log export, including missing-ticket refusal; gateway authentication and Worker retirement boundaries remain unchanged.
- physical timer evidence — retain the existing selected-backend summary in the trusted bounded boot reserve so startup log pressure cannot erase physical acceptance evidence; timer mechanics and thresholds remain unchanged.
- strict pressure authority — under reopened m27a-queen-ctl-idempotency, select 512 retained outcomes on both Release A targets, route all pressure mutations through strict intents, budget the complete boot before mutation, and preserve duplicate/refusal/fencing semantics and unchanged workload thresholds.
- provisioned pressure preflight — check canonical generated contracts before selecting the image profile; retain the authenticated canary, selected seL4 build, immutable launch identity and focused NineDoor guard. Bind canary labels and service evidence to the host-specific profile and timer in that identity. Isolate common test credentials from the live credentials supplied to subsequent target stages. The complete host-tool suite, Python SDK and benchmark workloads keep their existing contracts; these collector corrections change no runtime, bounds, thresholds or burn-in outcome.
Commands: scripts/ci/test_plan_run.sh --list; select and execute the complete applicable qemu/pi4 staged gates and registered provider/native-app/release lanes with fresh exact-profile state directories under TEST_PLAN.
Checks: All required assembled-path and staged gates pass for the exact release; ACK-only, recovery-only or fixture-only results cannot promote it.
Deliverables: Integrated acceptance matrix, retained logs/evidence and honest release decision.
Title/ID: m27g-two-hour-pi4-operator-burn-in
Milestone: 27g / two-hour-pi4-operator-burn-in
Goal: Complete 120 minutes of useful operator work with the current Queen on Pi 4 GENET and native work on both the Mac and Linux AArch64 NVIDIA host.
Inputs: Exact current Pi image and boot identity, matching installed host packages and generated contracts, cohesix-release-burn-in and cohesix-pi4-wifi-hardware-loop skills, OPERATOR_WALKTHROUGH, OPERATOR_RECIPES, PRIVATE_LORA_RELEASE and TEST_PLAN.
Changes:
- run record and coverage matrix — freeze artifact/runtime/trust identities, sustainable workload, job counts, budgets, ownership and expected effects before timing begins.
- canonical host defaults and provisioning — keep QEMU/Pi host selections aligned, enable existing Mac service actions and read-only compliance, provision native helpers and exact owned services, and preserve typed unavailability for missing dependencies.
- assembled workflows — exercise 27b-f CUDA and LoRA import/training, installed CLI/Python/CI and native SwarmUI alongside supported 1.0.0 operator, FUSE, host-provider, lifecycle and evidence workflows on both hosts.
- recovery and defect closure — retain failures, reconcile ambiguous effects without duplicate work, repair their owning contracts and validate fresh artifacts before resuming.
Commands: Execute the skills' physical-entry and operator-workflow procedures; retain exact per-host commands and protected credential references in out/burn-in/<run-id>; after successful burn-in, execute the complete applicable qemu/pi4 staged Test Plan and registered release lanes in fresh state directories.
Checks: 120 minutes of measured work with independently checked outcomes, complete feasible tool coverage, bounded freshness/liveness, planned maintenance/recovery, no duplicate or unauthorized effects, and reconciled final resources. Major repairs require a new complete 120-minute attempt. Minor repairs retain the original failure and use separately identified focused revalidation and continuation; never claim unchanged-artifact duration across a repair. Missing required capabilities or proof block completion.
Deliverables: Immutable attempt logs, per-host coverage, early/middle/late reliability observations, defect/recovery records, verified offline handoff and explicit burn-in verdict before full release testing.
Title/ID: m27g-adoption-overhead-and-release-cut
Milestone: 27g / adoption-overhead-and-release-cut
Goal: Measure adoption and overhead, then cut the reserved release only from qualified artifacts.
Inputs: m27g-assembled-journeys-and-recovery, BENCHMARKS, release manifests and current native-stack baseline.
Changes:
- benchmark/adoption report — first-use friction, manual intervention, work reuse, failure recovery, resource use and native-versus-Cohesix overhead under comparable inputs.
- release assembly — exact manifest/SBOM/signature/content checks, offline docs, native UI hero/capture/replay and version-reserved names.
- release notes/status — only measured outcomes and accepted residual risks, with links to exact evidence and compatibility review.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: No thresholds or proof classes change; complete integration evidence and named review support the A release, while B/C reservations remain intact.
Deliverables: Qualified 1.1.0-beta artifacts and evidence-backed adoption/overhead report.
Milestone 27h — Release A Community Video Index
Status: Complete — 24 September 2026. Five public YouTube links resolve to the intended Cohesix videos, and the README indexes them for newcomers. This post-release documentation task changes no Release A artifact, qualification result, or acceptance boundary.
Title/ID: m27h-community-video-index
Milestone: 27h / Release A Community Video Index
Goal: Make the five completed 1.1.0-beta videos easy for newcomers to find.
Inputs: completed YouTube uploads, README.md, Release A notes and status.
Changes:
- README.md — link the narrated and raw Pi boot videos and three Mac/Jetson use cases with accurate, short descriptions.
- seL4 development-list note — draft a concise introduction for readers unfamiliar with AI tooling; do not send it as part of this task.
Commands: scripts/check-generated.sh; scripts/ci/check_test_plan.sh; git diff --check; verify the five public video links.
Checks: Each README link opens the intended video for a reader, descriptions preserve live/replay and release-evidence limits, and no release acceptance claim changes. AI-assisted copy and link selection were checked against the public uploads.
Deliverables: Public README video index and a reviewable mailing-list draft.
Live Hive video index extension
Status: Complete — 24 September 2026. The sixth public link resolves to the intended Live Hive video. This documentation-only addition does not change the sealed release or its qualification evidence.
Title/ID: m27h-live-hive-video-index
Milestone: 27h / Release A Community Video Index
Goal: Add the approved Live Hive SwarmUI demonstration to the public video index.
Inputs: approved Pi 4 and Jetson video export, verified public YouTube upload, README.md.
Changes:
- README.md — add one link describing the live Worker visualization and its observed limits.
Commands: scripts/check-generated.sh (includes scripts/ci/check_test_plan.sh); git diff --check; verify the public video link in a signed-out browser.
Checks: The link opens the intended video; the AI-assisted description distinguishes Worker state and host inventory from completed execution or release acceptance.
Deliverables: A sixth public README video link.
Milestone 27i — Release A Python Index Publication
Status: Complete — the 1.1.0b0 publication and bounded
m27i-pypi-1-1-0b1-page-correction both completed on 24 September 2026.
The correction restores public installation and navigation metadata. It does
not change the sealed
1.1.0-beta archives, their historical acceptance, or Release B scope.
Title/ID: m27i-pypi-1-1-0b0-publication
Milestone: 27i / Release A Python Index Publication
Goal: Publish a version-aligned Cohesix Python distribution from the exact 1.1.0-beta tagged SDK source through a reviewer-gated GitHub trusted publisher.
Inputs: v1.1.0-beta source commit 8bda91891591466b67f5f4a35e733fe2d3acf0e8, selected Python source inventory, PyPI personal pending publisher for cohesix, GitHub pypi environment and retained package qualification.
Changes:
- .github/workflows/release-pypi.yml — manually triggered, source-pinned build, package validation, artifact digest handoff and environment-gated OIDC upload of only 1.1.0b0.
- docs/{PYTHON_SUPPORT,HOST_TOOLS}.md — document the published Python-only install path and its host-bundle boundary.
- docs/BUILD_PLAN.md — record the bounded post-release publication scope, ownership handoff and proof limits.
Commands: actionlint .github/workflows/release-pypi.yml; python3 scripts/install/build_python_package.py --repo <exact-tag-stage> --inventory <exact-tag-inventory> --out <fresh-dist>; python3 -m twine check <fresh-dist>/*.whl <fresh-dist>/*.tar.gz; scripts/check-generated.sh; scripts/ci/check_test_plan.sh; git diff --check; dispatch the reviewed workflow and inspect its build hashes before approving the pypi environment.
Checks: The workflow checks out the exact tagged commit, changes only the Python package version from 0.2.0-alpha2 to 1.1.0b0 in its isolated build source, validates wheel/sdist source and metadata, and uploads those exact checked artifacts only after named reviewer approval. PyPI's project/version API must report both uploaded filenames and SHA-256 digests; the project remains personally owned until a separately verified transfer after Cohesix organization approval. No target, bundle or overall-release acceptance is inferred from this host publication.
Deliverables: Reviewed dedicated workflow, GitHub run/build digest record, PyPI cohesix 1.1.0b0 wheel and sdist URLs/hashes, and an explicit pending organization-transfer record.
Publication evidence: workflow PR #2229
passed CI and merged as 36ec41da868500ed63fd77d84d63a89374a7b906.
Run 35963322755
built from tagged source 8bda91891591466b67f5f4a35e733fe2d3acf0e8,
passed package checks, recorded the pypi approval by lukeb-aidev, and
uploaded with GitHub OIDC. PyPI lists the
1.1.0b0 wheel and sdist:
wheel SHA-256 7a1ef4d996f8c5366200ea8ef6359a9b587ba95ec9016fe372249490f85068dd
and sdist SHA-256 85ec35c9c21239c7df42ec06bd6da0062d790f3c11385fc05b055b85e07f708c.
Independent downloads matched both hashes and the selected source files.
An isolated pip install cohesix==1.1.0b0 from the public index and both CLI
help commands passed on Python 3.13.
The Cohesix Community organization request remains pending; verify project
ownership and transfer it only after PyPI approves the organization. Package
publication does not add target or overall-release acceptance evidence. A
post-upload page review found checkout-only installation guidance, a stale
Homepage URL and five relative documentation links that resolve to 404 on
PyPI. The uploaded 1.1.0b0 metadata cannot be edited in place; a corrected
page requires a separately versioned distribution.
Title/ID: m27i-pypi-1-1-0b1-page-correction
Milestone: 27i / Release A Python Index Publication
Goal: Publish a corrected 1.1.0b1 Python-only distribution from the sealed 1.1.0-beta SDK code so PyPI readers get working installation instructions, documentation links and project identity.
Inputs: m27i-pypi-1-1-0b0-publication defect record, v1.1.0-beta tagged SDK source, exact metadata-only delta, registered GitHub trusted publisher and pypi reviewer environment.
Changes:
- tools/cohesix-py/{pyproject.toml,README.md} — align the Python version, summary, URLs and index-facing instructions while preserving SDK behavior.
- .github/workflows/release-pypi.yml — build and validate 1.1.0b1 from the tagged SDK plus the pinned metadata delta, then hand off exact reviewed bytes to the existing OIDC gate.
- docs/{BUILD_PLAN,HOST_TOOLS,PYTHON_SUPPORT}.md — record the correction scope, Python-only install route and resulting publication evidence.
Commands: actionlint .github/workflows/release-pypi.yml; python3 scripts/install/build_python_package.py --repo <tag-plus-metadata-stage> --inventory <tag-inventory> --out <fresh-dist>; python3 -m twine check <fresh-dist>/*.whl <fresh-dist>/*.tar.gz; isolated Python 3.11 and 3.13 wheel/CLI smoke; scripts/check-generated.sh; scripts/ci/check_test_plan.sh; git diff --check; inspect reviewed GitHub artifact hashes before pypi environment approval.
Checks: The staged source differs from the sealed tag only in the two declared Python metadata files; built wheel/sdist contents, description, public URLs and package version are inspected; the rendered PyPI page and downloaded public hashes match the approved GitHub artifacts. The correction makes no new target, bundle, runtime or overall-release acceptance claim.
Deliverables: Reviewed workflow and source delta, exact artifact digest record, corrected PyPI 1.1.0b1 wheel and sdist with verified page and provenance, and retained 1.1.0b0 historical evidence.
Correction evidence: PR #2231
passed CI and merged as f0f4bc224a8d74576da15021f3e64f2a00dec8d6.
Run 35969770663
used the sealed v1.1.0-beta SDK source and metadata commit
da3ff4c7e1df1fbe97087c2d9a1df2d3334a5d49, passed package checks,
recorded the exact-artifact pypi environment approval by lukeb-aidev, and
uploaded with GitHub OIDC. The
1.1.0b1 PyPI page lists the
wheel SHA-256 b3af61edb295168b5f7f7012d484ea48d2a31f297e66d689c2fbdeeedc1d38ff
and sdist SHA-256 c573717ffd47b87367fe329dbd68ef8c57982a8d869c94a308ea41c337f56b78,
both matching independently downloaded public files and the retained GitHub
artifact. The rendered install command, seven public links, Python requirement
and trusted-publishing provenance were checked. Fresh PyPI installs and both
CLI help commands passed on Python 3.11 and 3.13. All 28 SDK code files match
the prior wheel; no native archive, target or overall-release acceptance claim
changes. The Cohesix Community organization request and project transfer remain
pending.
Release B — Governed CUDA, PEFT, Apple and NeMo Workflows
Status: Planned — owner-directed scope, 23 September 2026. Milestones 28–28g together deliver 1.2.0. Release A and every 0–27g milestone, including 27g’s status, tasks, acceptance and evidence, remain unchanged. This planning revision neither activates implementation nor approves a release.
Product outcome: existing NeMo agents, CUDA/PEFT workflows and Mac applications can perform useful GPU work through Cohesix with bounded authority, observed results and recoverable failures. They do not need another agent framework, model platform or infrastructure stack.
The release must deliver three complete user journeys:
- Register an approved useful CUDA workload without changing Cohesix source; preflight, submit, observe, verify outputs, cancel and recover safely.
- Train or import a genuine LoRA adapter, compare it with the base and accepted deployment, serve a real canary, promote or roll back and inspect evidence.
- Use those operations from NeMo through MCP/A2A and from macOS 27 through App Intents/Shortcuts; follow the same run in SwarmUI/CLI. Demonstrate genuine local MLX/Metal work as well as explicit remote CUDA operation, including selected workflows that use both providers when advertised.
Release boundaries and common acceptance
- Reuse 27a authority, 27b providers/evidence, 27c recipes, 27d LoRA transactions, 27e installation and 27f workbench. Extend actual gaps, not duplicate their registries, journals, schedulers, verifiers, deployment or recovery machinery.
- Complete every narrow milestone below. An unavailable profile, mock, read-only demonstration or documentation-only adapter cannot satisfy a required live workflow. No milestone 29–43 gates this release.
- Numerical order is the default delivery sequence, not a blanket dependency chain. Each milestone lists its actual contracts. Apple is not a runtime or installation prerequisite for NeMo; MCP and A2A remain independently usable.
- Every client uses the same authenticated, delegated action/job contract, current-state admission, expiry/revocation, idempotency, writer fencing, cumulative budgets and observed result. UI, voice, model output, protocol adapters and provider metadata never mint authority or terminal receipts.
- Models, training, inference, NeMo, Apple frameworks and CUDA/Metal stay host-side. Pi Workers remain control-plane roles, not GPU hosts. Large inputs, models, datasets, checkpoints and outputs remain in bounded host storage/CAS; only control metadata and references cross the VM boundary.
- Record external executor credential custody and bypass limits. A lease or preflight estimate is not hard GPU isolation, and seL4 confinement does not prove a privileged external host cannot bypass Cohesix. Distinguish estimates, enforced limits, observed usage and unavailable measurements.
- Qualify exact Pi 4 Queen, Apple-silicon macOS 27 and Jetson Orin Nano 8GB reference profiles. Keep QEMU and any explicitly supplied remote/discrete GPU evidence separate. Verify actual SDK, OS, JetPack/L4T/CUDA, model/runtime and protocol versions; do not inherit assumed compatibility from old proposals.
- Ship installation, doctor diagnostics, task-oriented CLI/Python help, relevant SwarmUI views and failure guidance with each capability. 28g integrates them; it is not permission to deliver libraries without a journey.
- Use the existing TEST_PLAN catalog and changed-surface proof layers. Add missing focused actions through their owner during implementation. Preserve all applicable merge/release gates and immutable evidence rules; no mocks as target proof, arbitrary retries, threshold relaxation or unrelated hardware reruns. Review all host-tool/Python/generated/benchmark consumers, update affected ones atomically and record genuine non-impact.
- Standing authorisation avoids repeated human prompts within its limits; platform-required or selected-policy approval remains enforceable. Individual changes and milestone acceptance need no human sign-off. Only overall release publication/promotion requires the named human release owner’s approval.
Execution and evidence contract
Each milestone below is Planned until explicitly activated. Component checks use accepted earlier contracts; downstream clients cannot become hidden prerequisites. M28 tests authority and lifecycle through existing CLI/REST/Python consumers. M28d and M28e independently prove protocol integration; M28f proves NeMo composition; M28g proves cross-client release integration. Fixtures cannot close live client acceptance. Both protocols consume M28 controls independently.
Task commands are future implementation instructions, not executed evidence. Existing Cargo/Python tests are starting points to extend. New tests, native packages and cases named below are planned outputs of their named owner. Missing tests or empty selections cannot pass. Use the existing conformance runner and TEST_PLAN catalog, not a second acceptance or execution system.
m28-selected-job-contract owns --case <id> and
--reference-config <path> options for scripts/ci/provider_conformance_run.sh.
The selected M28 runner rejects unknown, duplicate and incompatible selections;
its live results still require exact-source execution and retained evidence.
Validate the reference file’s installed binary/package paths, source/generated
profile digests, endpoints, secret references, device/runtime versions, approved
workload/model/data hashes, resource caps and evidence paths. It contains no
credential values and cannot widen generated authority. Cases invoke maintained
installed clients and provider observers, never raw effects. Each implementing
task registers its cases in configs/provider_conformance.toml and
configs/test_plan_actions.toml, with proof layers in docs/TEST_PLAN.md.
For live commands, set RELEASE_B_REFERENCE to that validated file,
RELEASE_B_HOST_PROFILE to its selected host profile, and RELEASE_B_EVIDENCE
to a fresh evidence directory. These are operator-supplied paths/identifiers,
not secrets. Run CUDA/PEFT observations on the Linux AArch64 NVIDIA reference
and Apple checks on the supported Mac; record remote client/executor topology.
Each case retains command/exit status, case ID, source/package/manifest/runtime
identities, bounds, raw observation hashes, logical/native job and receipt links,
expected/observed results and proof class. Preserve failures and unresolved
outcomes. Reports reference existing signed evidence, not a new receipt authority.
Every task also runs scripts/check-generated.sh (including its Test Plan check)
and git diff --check, plus applicable charter merge gates. Changed-path
selection determines target checks; host tests cannot qualify QEMU/Pi. Component
closure links each check to retained evidence in the planned
docs/audit/M28_IMPLEMENTATION_RECORD.md, populated by the implementing owners.
M28g separately binds assembled evidence. Select exact platform/model/protocol
versions before their implementation or live qualification; do not infer them
from old proposals.
m28-agent-protocol-controls owns compiler-controlled
[gateway.agent_protocols].enabled, [gateway.mcp].enabled and
[gateway.a2a].enabled, all default false. Effective enablement is master AND
protocol. CLI, environment, desktop launch and clients cannot raise this ceiling.
Disabled protocols start no listener, handler, discovery/card/catalogue, stream
or background work. Disabling access preserves underlying jobs and pending
delivery; it never silently cancels or replays effects. Existing authenticated
REST/CLI recovery remains usable.
Planning maintenance record
Title/ID: m28-release-b-plan-readiness
Milestone: 28 / m28-release-b-plan-readiness (documentation-only owner request)
Goal: Make Release B milestones actionable and consistently reviewable without activating runtime work.
Inputs: AGENTS.md; CONTRIBUTING.md task format; docs/TEST_PLAN.md; current source paths and milestone ownership map.
Changes:
- docs/BUILD_PLAN.md — expand owners, commands, bounds and evidence; retain protocol controls in Release B; reconcile prospective references while preserving historical IDs and evidence.
Commands:
- scripts/check-generated.sh
- git diff --check
Checks: Unique task IDs/anchors and valid local links; consistent Planned sections and task fields; no downstream foundation gates; future commands explicitly labelled.
Deliverables: Planning revision with AI-assisted analysis and drafting; no runtime, platform compatibility, milestone closure or release acceptance claim.
Planning validation (23 September 2026): scripts/check-generated.sh
passed, including Test Plan catalog/cross-file integrity and NIST evidence
checks; git diff --check passed. Structural review found 488 unique task IDs
and 108 unique explicit anchors, preserving every prior ID/anchor. All eight
sections have the required task fields and consistent milestone structure;
added local links and exact task/case references resolve. The 15 retained design
inventories are unchanged. No product runtime or hardware qualification was run.
Milestone 28 — Shared Governed Jobs and Bounded Unattended Authority
Status: Complete — selected foundation accepted on 24 September 2026.
Implementation and evidence are tracked in M28_IMPLEMENTATION_RECORD. The three task records and the definition of done below have focused host checks and exact-source Linux AArch64 CUDA, KVM target, and native service evidence. This component acceptance does not qualify Release B or future MCP/A2A listeners.
Value: every client safely operates the same durable job without granting unrestricted host access or repeatedly asking permission inside valid policy. Prerequisites: accepted 27g and its exact authority/executor/recipe contracts.
Extend existing run identity with exact subject, action, target, input hashes, limits, policy, state/resource generation, deadline and idempotency bindings. Persist execution separately from pending result delivery. Supply status, cancel, reconcile and verifiable evidence; a lost response never justifies a second effect. Resume only from a valid runtime-supported checkpoint, otherwise report a known terminal or explicitly uncertain outcome and an authorised plan.
Implement revocable standing scopes with expiry, cumulative budgets, concurrency and retry/cooldown limits shared across CLI, REST, Apple, MCP and A2A. Every effect still needs a fresh state-bound decision. Use the smallest generated deterministic evaluator for these actions, with authoritative inputs and dispatch-time reservation/recheck. Missing, contradictory, stale, malformed or unverifiable inputs refuse. Retain target-side checks; host verdict strings and model assertions are not grants. Administrative changes require separate authority; escalation cannot approve itself. General solvers/proofs stay in 29/32, not on the critical path.
Before implementation, enumerate existing persisted job/WAL schemas and the specific extensions needed. Distinguish execution state from delivery state; terminal execution with pending delivery remains a retained obligation. Declare finite journal/evidence/queue limits and deterministic full/corrupt-state errors. Reservation, dispatch and settlement share one durable identity: reserve before effects, recheck current authority at dispatch, settle confirmed usage once, and retain uncertain allocations until native reconciliation establishes safety. Revocation prevents new effects but does not invent termination of existing work. Persisted schema evolution must preserve old identity and replay meaning.
Deliverables: Versioned job/authority contracts, durable accounting, generated protocol controls, client/help updates and focused recovery evidence.
Task breakdown
Title/ID: m28-selected-job-contract
Milestone: 28 / m28-selected-job-contract
Goal: Extend the accepted durable job lifecycle once for all selected ecosystem clients.
Inputs: Accepted 27a–27g; configs/root_task*.toml; configs/cuda_recipe.toml; docs/HOST_TOOLS.md; docs/INTERFACES.md; docs/SECURITY.md; existing signed provider/receipt contracts.
Changes:
- tools/coh-rtc/src/{ir,recipe,authority}.rs + codegen — version exact subject/action/target/input/policy/state-generation/deadline bindings, generated bounds and backward-compatible persisted decoding or an explicit migration refusal.
- apps/coh/src/{run,recipe,workflow}.rs + apps/host-ticket-agent/src/{wal,status}.rs — reuse existing identities/journals; distinguish submission intent, native execution, cancellation requested/confirmed, uncertain result, terminal verification and pending result delivery.
- tools/cohesix-py/cohesix/{orchestration,workload,client}.py + apps/hive-gateway/src/main.rs — shared status/cancel/reconcile semantics and scoped evidence visibility; no second scheduler or native executor.
- scripts/ci/provider_conformance_run.py + scripts/ci/provider_matrix.py + tests/test_provider_matrix.py — implement the bounded case/reference selection contract above; preserve current modes and reject missing or empty case execution.
- configs/provider_conformance.toml + configs/test_plan_actions.toml + docs/TEST_PLAN.md — register m28-jobs-live; extend existing recovery fixtures and installed-client observations; docs/HOST_TOOLS.md + docs/PYTHON_SUPPORT.md describe the same lifecycle.
Commands:
- cargo test --locked -p coh --test recipe --test run --test workflow
- cargo test --locked -p host-ticket-agent --lib
- cargo test --locked -p coh-rtc
- python3 -m pytest -q tools/cohesix-py/tests/test_orchestration.py tools/cohesix-py/tests/test_workload.py tests/test_provider_matrix.py
- scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28-jobs-live --reference-config "${RELEASE_B_REFERENCE}" --host-profile "${RELEASE_B_HOST_PROFILE}" --state-dir "${RELEASE_B_EVIDENCE}/m28-jobs-live"
Checks:
- Crash before dispatch, after native start and after terminal observation preserves original identity; lost replies reconcile without a second effect.
- Pending delivery survives execution completion, restart and retention; acknowledged delivery can retire only under declared bounds. A corrupt/full journal refuses new work without evicting unresolved obligations.
- Wrong subject/target/input and stale generations refuse; old persisted records retain meaning or receive an explicit supported migration/refusal. Existing CLI/REST/Python prove parity without future protocol clients.
Deliverables: Versioned shared job contract, updated clients/manuals, journal compatibility fixtures and m28-jobs-live case report with original/native identities and outcome/delivery evidence.
Title/ID: m28-standing-authority-and-admission
Milestone: 28 / m28-standing-authority-and-admission
Goal: Admit unattended effects only within revocable current policy and durable cumulative limits.
Inputs: m28-selected-job-contract; crates/cohesix-authority; 27a delegation/fencing; generated action policies; target ticket/lease checks.
Changes:
- tools/coh-rtc/src/{authority,ir,lib}.rs + crates/cohesix-authority/src/ — declare scope, delegation attenuation, authoritative fact sources/freshness, decision expiry, budget units, concurrency and bounded retention; generate the narrow evaluator contract.
- apps/hive-gateway/src/{auth,identity}.rs + apps/host-ticket-agent/src/{claim,wal,provider}.rs — one budget identity across clients; atomic reservation before dispatch, generation/revocation recheck, cancellation/compensation authority and confirmed settlement.
- apps/coh/src/policy.rs + tools/cohesix-py/cohesix/authority.py — inspect/revoke standing scopes and explain deterministic denials; administration requires separate authority.
- configs/provider_conformance.toml + configs/test_plan_actions.toml + docs/TEST_PLAN.md — m28-authority-live and focused concurrent spend/crash tests; docs/SECURITY.md + docs/HOST_API.md record enforcement custody and bypass limits.
Commands:
- cargo test --locked -p cohesix-authority
- cargo test --locked -p coh-rtc
- cargo test --locked -p hive-gateway
- cargo test --locked -p host-ticket-agent --lib
- python3 -m pytest -q tools/cohesix-py/tests/test_authority.py
- scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28-authority-live --reference-config "${RELEASE_B_REFERENCE}" --host-profile "${RELEASE_B_HOST_PROFILE}" --state-dir "${RELEASE_B_EVIDENCE}/m28-authority-live"
Checks:
- Concurrent requests cannot overspend or evade shared concurrency limits; restart, changed client and retry cannot reset accounting. Unknown native termination retains its reservation; confirmed settlement is applied once.
- Stale/contradictory facts, expired/revoked/attenuated scopes, changed resource generations, clock invalidity and forged grants refuse before effects; dispatch races and policy-required approvals are exercised.
- One admitted GPU action and one enrolled service-recovery action execute and verify within standing policy; escalation cannot approve itself. Real MCP/A2A parity belongs to their later owners.
Deliverables: Generated authority primitive, bounded policy examples, denial/accounting evidence and m28-authority-live report; no general proof or non-bypassable privileged-host claim.
Title/ID: m28-agent-protocol-controls
Milestone: 28 / m28-agent-protocol-controls
Goal: Establish shared fail-closed manifest controls before either protocol is implemented.
Inputs: m28-selected-job-contract; tools/coh-rtc; configs/root_task*.toml; apps/hive-gateway; retained m28g-manifest-protocol-controls design in deferred 36.
Changes:
- tools/coh-rtc/src/{ir,lib}.rs + codegen + configs/root_task*.toml — schema-versioned false-default master/MCP/A2A flags, effective conjunctions and disabled-profile dependency validation; regenerate all affected consumers.
- apps/hive-gateway/src/main.rs + apps/coh/src/doctor.rs — enforce and explain the generated enablement ceiling before credentials, transport startup or discovery; preserve REST and existing job recovery.
- apps/hive-gateway/tests/agent_protocol_controls.rs (planned) + compiler tests — all eight flag combinations, invalid/missing configuration, CLI/env widening and existing-job preservation; M28d/e extend these tests with their real endpoints.
- docs/HOST_API.md + docs/HOST_TOOLS.md + docs/SECURITY.md + docs/TEST_PLAN.md — safe enable/disable and restart semantics, no active disabled surfaces, unchanged underlying effect/delivery obligations.
Commands:
- cargo test --locked -p coh-rtc
- cargo test --locked -p hive-gateway --test agent_protocol_controls
- cargo test --locked -p coh --lib doctor::
Checks:
- All combinations enforce master AND protocol and refuse runtime widening; absent configuration defaults disabled.
- Foundation closure proves generated policy and existing startup/recovery boundaries only. It does not claim absent MCP/A2A listener conformance; each protocol owner must prove no disabled handlers, discovery, streams or background tasks.
Deliverables: Shared generated controls and truth table, focused compiler/startup evidence and operator documentation; no dependency on either downstream protocol.
Checks / definition of done: shared controls pass their truth table, and a bounded GPU action and one existing allowlisted service-recovery action execute within standing policy, refuse invalid/stale requests and survive interrupted result delivery with inspectable outcomes. Selected-path safety checks are mandatory; broad formal assurance is not.
Milestone 28a — Useful CUDA Workloads and Reliable GPU Operations
Status: Complete — m28a-approved-user-workloads and m28a-cuda-operations-and-recovery at the selected Orin scope on 24 September 2026; see the M28a implementation record.
Value: users run their own approved useful workload, not only diagnostic kernels. Prerequisites: 28 and accepted 27b/27c CUDA/executor/recipe foundations.
Provide a supported registration path for a digest-pinned workload package or container, fixed entry point, typed parameters, declared inputs/outputs, environment/secret references and bounded resources. Registration is privileged configuration, never model-generated shell or arbitrary paths. No Cohesix source edit is needed to add an approved workload. Reuse native process/container owners.
Expose exact device/inventory freshness, memory headroom, admission/queue state, health/thermal observations, deadline, cancellation, terminal outcome and output digests. Clean up only the owned job; preserve unrelated processes. Distinguish supported checkpoint resume from reconciliation or explicit restart. Bound shared memory and disk; test OOM mapping safely. Ship a real batch inference, embedding or other useful CUDA/PyTorch recipe and a documented user adaptation, with actual GPU execution. Retain advertised native/container paths, without rebuilding them. Jetson is required; discrete GPU, MIG, distributed placement and deep profiling are independent later claims, not silent substitutes or new baseline scope.
Deliverables: Workload registration and useful recipes, GPU diagnostics, installed client views and exact-device execution/recovery evidence.
Task breakdown
Title/ID: m28a-approved-user-workloads
Milestone: 28a / m28a-approved-user-workloads
Goal: Run approved user workloads through the existing native/container executor without Cohesix source edits.
Inputs: 28; accepted 27c recipes; configs/cuda_recipe.toml; crates/host-cuda; apps/gpu-bridge-host; apps/host-ticket-agent/src/executors/workload.rs.
Changes:
- tools/coh-rtc/src/recipe.rs + configs/cuda_recipe.toml — bounded registration schema: package/container digest, fixed entrypoint, typed parameter limits, declared input/output roots, secret references, memory/disk/deadline limits and selected device compatibility.
- apps/coh/src/{recipe,run}.rs + apps/host-ticket-agent/src/executors/workload.rs — privileged register/validate flow, immutable workload identity and existing executor dispatch; reject unapproved executables, traversal/symlink escapes and parameter-to-shell injection.
- tools/cohesix-py/examples/cuda_recipe.py + tools/cohesix-py/cohesix/workload.py — useful pinned batch inference or embedding reference, a second user adaptation and an independent bounded output validator; freeze model/data/expected tolerances before the live run.
- apps/swarmui/src/workbench.rs + docs/HOST_TOOLS.md + docs/PYTHON_SUPPORT.md — registration/preflight/run/result views and installed-native/container instructions; conformance matrix/catalog gain m28a-workloads-live.
Commands:
- cargo test --locked -p coh --test recipe --test run
- cargo test --locked -p host-ticket-agent --lib executors::workload
- cargo test --locked -p coh-rtc
- python3 -m pytest -q tools/cohesix-py/tests/test_workload.py
- scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28a-workloads-live --reference-config "${RELEASE_B_REFERENCE}" --host-profile "${RELEASE_B_HOST_PROFILE}" --state-dir "${RELEASE_B_EVIDENCE}/m28a-workloads-live"
Checks:
- Reference and independently configured adaptation run on the admitted Jetson GPU with verified output hashes and task-specific tolerances, not only a zero exit code.
- Each advertised native/container lane is exercised; stale device inventory, altered digests, unsafe paths/credentials and parameter bound violations refuse before native start.
Deliverables: Versioned registration contract, installable reference/adaptation and m28a-workloads-live evidence identifying each supported lane, GPU and output verifier.
Title/ID: m28a-cuda-operations-and-recovery
Milestone: 28a / m28a-cuda-operations-and-recovery
Goal: Make resource refusal, cancellation and interrupted CUDA recovery safe and understandable.
Inputs: m28a-approved-user-workloads; executor WAL/native identity; apps/coh/src/doctor.rs; gpu-bridge-host telemetry; existing shared verifier.
Changes:
- apps/gpu-bridge-host/src/ + apps/coh/src/doctor.rs — freshness-aware device/memory/health diagnostics with separate estimates, measurements and enforced caps.
- apps/host-ticket-agent/src/executors/workload.rs + apps/coh/src/recipe.rs — exact-owner cancellation, bounded cleanup and runtime-supported checkpoint validation; reconcile uncertain work before any newly authorised restart.
- tools/cohesix-py/cohesix/workload.py + apps/swarmui/src/workbench.rs + docs/HOST_TOOLS.md — consistent interruption, unsupported-resume and unresolved-outcome guidance; matrix/catalog gain m28a-recovery-live.
Commands:
- cargo test --locked -p gpu-bridge-host --lib
- cargo test --locked -p coh --test recipe
- cargo test --locked -p host-ticket-agent --lib executors::workload
- scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28a-recovery-live --reference-config "${RELEASE_B_REFERENCE}" --host-profile "${RELEASE_B_HOST_PROFILE}" --state-dir "${RELEASE_B_EVIDENCE}/m28a-recovery-live"
Checks:
- Timeout, revoke/cancel, runner restart and lost-response cases preserve native identity, never kill unrelated processes and release capacity only after observed termination.
- Exercise OOM mapping with a capped child or deterministic injection, never shared-host exhaustion. Corrupt/incompatible checkpoints refuse; unsupported resume is distinguished from explicit restart.
- Live recovery shows a verified output or retained uncertainty with bounded resource accounting; no retry masks the failed attempt.
Deliverables: Actionable diagnostics/recovery guide and m28a-recovery-live report including cancellation timing, native cleanup and reservation settlement.
Checks / definition of done: a newcomer configures useful work without patching Cohesix and handles an interruption from published instructions, obtaining verified outputs or an explicit unresolved outcome rather than invented success.
Milestone 28b — Deeper PEFT Lifecycle and Verified Serving
Status: Complete — m28b-configurable-peft-training-and-import and m28b-evaluate-canary-promote-rollback completed on 24 September 2026 at the selected Linux AArch64 NVIDIA/KVM component scope. The implementation record binds the focused checks and admitted lifecycle evidence; it does not qualify Pi hardware or Release B.
Value: a private edge adapter moves from pinned training or import to a measured, reversible release whose exact served generation a real client sees. Prerequisites: 28, 28a and accepted 27d LoRA transaction; extend its journal, registry, evaluator, activation and recovery rather than recreate them.
Use HF PEFT as the primary open training/artifact boundary. Support configurable LoRA training and independent compatible adapter import. Add QLoRA only where a qualified model/runtime pair needs it to fit the reference; not every PEFT method. Pin base revision, tokenizer/config, dataset snapshot, framework/runtime and training settings. Validate structure, sizes, hashes, format, compatibility and provenance. Use safe formats; disable arbitrary remote-code loading in the reference. Explicitly configure licence acceptance, gated downloads, uploads and private data. An imported adapter cannot invent training provenance; an artifact reference is not licence or safety certification. For the qualified private reference, stage approved inputs explicitly and keep base weights, private data, prompts, outputs and adapters on the selected host during execution. Retain only bounded digests, metrics and scoped evidence in control-plane reports. Record any authorised external transfer separately; an offline setting alone is not proof that payloads did not leave the host.
Reuse real framework checkpoints where supported, distinguishing full training resume from adapter-only restart. Record stochastic settings without promising identical weights. Compare candidate, base and incumbent on held-out task data using predeclared quality/resource/latency thresholds; preserve negative results. No judge score or scan alone proves safety or quality.
Complete train/import, evaluate, scan, canary, generation-fenced promotion and rollback through the existing phase-journalled path. Serve a real application through one supported native runtime endpoint, with observed model/adapter identity, readiness and inference canary. Publication or HTTP success is not a verified deployment. Keep general API cloning/proxying/routing in 35. HF, MLX and NeMo adapters interoperate only for actually qualified format/model/runtime pairs; no blanket compatibility or general conversion programme.
Make the operator decision portable across CLI, Python playbook, SwarmUI and later agent protocols: bind one immutable operation/request identity, distinguish unsubmitted, uncertain and terminal states, and expose the signed evidence graph reference separately from the requested-outcome verdict. Only accepted signed evidence checked by the shared verifier can mark a successful requested outcome; a serving HTTP response, Python object, MCP tool result or A2A task state cannot. A lost submit response must resume observation of the original operation, never create a second effect. The Python path must give a newcomer explicit plan, submit, inspect and recovery steps without implementing a second journal or evaluator. Record the held-out comparison policy, exact serving generation and rollback observation in the 28b evidence so later protocol adapters can project them without reinterpretation.
After a bake-off, distributing its winning weights is a separate, planned
host-artifact operation. An accepted comparison chooses an immutable artifact;
it does not copy or activate it. Admit an exact source digest, format and
revision, selected destination host/profile, export authority, capacity and
retention before payload movement. Keep model bytes on an authenticated
host-to-host data path. Queen and its bounded coh-ref-c/v1 namespace may
record chunk digests and operation evidence, but a reference is neither payload
delivery nor destination verification. Do not route model bytes through Pi
FUSE, MCP messages or A2A task artifacts. Distribution never implies format
conversion or deployment to an incompatible MLX/CUDA runtime. The dedicated
task below is inactive until selected; existing 28b lifecycle completion does
not claim weight distribution.
Deliverables: Configurable training/import, fixed evaluation and serving contracts, runtime canaries and verified promotion/rollback evidence.
Task breakdown
Title/ID: m28b-configurable-peft-training-and-import
Milestone: 28b / m28b-configurable-peft-training-and-import
Goal: Extend accepted HF PEFT training/import with bounded configuration and truthful checkpoint recovery.
Inputs: 28/28a; accepted 27d; tools/cohesix-py/cohesix/hf_native.py; apps/coh/src/peft/; existing CAS/registry and peft executors.
Changes:
- tools/cohesix-py/cohesix/hf_native.py + examples/private_lora_release.py — select and pin one Jetson-feasible base/tokenizer, training and disjoint held-out datasets, framework/runtime and independent adapter source before qualification; declare memory/disk caps and licence/credential references.
- apps/coh/src/peft/{import,transaction,release}.rs + apps/host-ticket-agent/src/executors/{peft,peft_release}.rs — bounded parameter schema, safe artifact parsing, exact base/config compatibility and provenance; imported artifacts retain unknown training provenance.
- tools/coh-rtc/src/ + configs/root_task*.toml + configs/cuda_recipe.toml — generate supported training/import/checkpoint capabilities; admit QLoRA only for an explicitly qualified pair, not as implicit extra scope.
- docs/HOST_TOOLS.md + docs/PYTHON_SUPPORT.md + matrix/catalog — supported full-state resume versus adapter-only restart, independent import instructions and m28b-peft-live.
Commands:
- cargo test --locked -p coh --test peft_import --test peft_release
- cargo test --locked -p host-ticket-agent --lib executors::peft
- python3 -m pytest -q tools/cohesix-py/tests/test_hf_native.py
- scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28b-peft-live --reference-config "${RELEASE_B_REFERENCE}" --host-profile "${RELEASE_B_HOST_PROFILE}" --state-dir "${RELEASE_B_EVIDENCE}/m28b-peft-live"
Checks:
- Real training and independent compatible import both complete; checkpoint evidence explicitly binds optimizer/scheduler/RNG/data position where the selected runtime supports full resume.
- Reference staging and live execution disclose every external model/data transfer; no unapproved upload or implicit runtime download carries private payloads. The control plane receives bounded identity/evidence rather than raw model/data content.
- Corrupt/oversize/unsafe artifacts, path races, wrong base/tokenizer, stale generations and duplicate submissions fail safely; no arbitrary remote-code loading or invented provenance.
- Record actual runtime checkpoint support before execution; an unsupported checkpoint cannot pass a resume claim, and adapter restart cannot be relabelled full training resume.
Deliverables: Pinned model/data/runtime selection, configurable train/import instructions, safe format/checkpoint fixtures and genuine adapter/recovery evidence in m28b-peft-live.
Title/ID: m28b-evaluate-canary-promote-rollback
Milestone: 28b / m28b-evaluate-canary-promote-rollback
Goal: Measure candidate quality and deploy through one real application-facing runtime with reversible promotion.
Inputs: m28b-configurable-peft-training-and-import; accepted 27d evaluator/activation/journal; base and incumbent artifacts; docs/BENCHMARKS.md.
Changes:
- apps/coh/src/peft/{controller,activate,release}.rs + tools/cohesix-py/cohesix/hf_native.py — select the supported native serving endpoint and predeclare held-out task metric, quality floor, latency/resource caps and comparison procedure before candidate evaluation.
- apps/host-ticket-agent/src/executors/peft_release.rs — runtime readiness/model-adapter observations and real inference canaries, fenced generation promotion, interrupted transition reconciliation and verified rollback.
- tools/cohesix-py/cohesix/{model_release,playbooks}.py + tools/cohesix-py/tests/test_model_release.py + docs/PYTHON_SUPPORT.md — a bounded Python release client over the existing CLI plan/apply/watch/verify/recover path; freeze request identity, require explicit submit, retain uncertain/recovered-failure states and expose a verified-success flag only after CLI verification.
- apps/swarmui/src/workbench.rs + docs/HOST_TOOLS.md + docs/BENCHMARKS.md — base/incumbent/candidate comparison and rejection/recovery views; matrix/catalog gain m28b-serving-live.
Commands:
- cargo test --locked -p coh --test peft_release
- cargo test --locked -p host-ticket-agent --lib executors::peft_release
- python3 -m pytest -q tools/cohesix-py/tests/test_hf_native.py tools/cohesix-py/tests/test_model_release.py tools/cohesix-py/tests/test_playbooks.py
- scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28b-serving-live --reference-config "${RELEASE_B_REFERENCE}" --host-profile "${RELEASE_B_HOST_PROFILE}" --state-dir "${RELEASE_B_EVIDENCE}/m28b-serving-live"
Checks:
- Base/incumbent/candidate use the same held-out inputs and declared thresholds; failed quality/canary or stale generation cannot promote.
- A real application request observes the serving identity and output; interrupt promotion, reconcile the generation and prove rollback restores the incumbent using another inference request.
- Python plan/submit/inspect/recover preserves the original operation and request digest across a lost response; wrong-identity, malformed or contradictory reports fail closed. MCP and A2A later project this same result through their separately admitted and activated tasks.
- Publish negative comparisons and stochastic settings; HTTP success, registry publication and judge scores alone cannot qualify deployment.
Deliverables: Usable native endpoint, fixed evaluation configuration, comparison/canary/rollback guide and m28b-serving-live report with observed served generations.
Title/ID: m28b-verified-weight-distribution
Milestone: 28b / m28b-verified-weight-distribution
Goal: Distribute a bake-off-selected model artifact to admitted compatible hosts and verify exact destination bytes before a separate deployment decision.
Inputs: Accepted m28b-evaluate-canary-promote-rollback result; shared 28 job/admission/identity/evidence contract; selected source and destination host profiles; bounded coh-ref-c/v1 references when Queen indexing is selected.
Changes:
- apps/coh/src/peft/ + apps/host-ticket-agent/src/executors/ (planned) — one durable transfer identity and host-side data mover with destination capacity reservation, digest-addressed chunks, bounded resume and independent full-file verification; no arbitrary path-copy or provider credential forwarding.
- tools/coh-rtc/src/ + selected host profiles — generated transfer bounds and authority for source/destination, artifact digest/size/format, approved export, byte/chunk quotas, retention and cancellation; reject incompatible destination or stale winning generation before effects.
- tools/cohesix-py/cohesix/ + apps/swarmui/src/workbench.rs + docs/HOST_TOOLS.md — plan/submit/inspect/recover the shared operation and show distinct reference-published, bytes-moving, destination-verified and deployment states; Python and UI do not copy bytes or issue their own success verdict.
- Host executor/CLI/Python tests + matrix/catalog — m28b-weight-distribution-live using a genuine model weight of at least 1 GiB from a Mac source to one qualified Linux AArch64 NVIDIA destination, with a second destination only when advertised.
Commands:
- cargo test --locked -p coh --test peft_release
- cargo test --locked -p host-ticket-agent --lib executors::artifact_transfer
- python3 -m pytest -q tools/cohesix-py/tests/test_model_release.py tools/cohesix-py/tests/test_artifact_transfer.py
- scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28b-weight-distribution-live --reference-config "${RELEASE_B_REFERENCE}" --host-profile "${RELEASE_B_HOST_PROFILE}" --state-dir "${RELEASE_B_EVIDENCE}/m28b-weight-distribution-live"
Checks:
- The source digest/size and frozen bake-off choice bind every chunk and the destination receipt. A separately observed destination reassembly and full SHA-256 match precede verified transfer; activation needs its own compatible provider admission and serving canary.
- Lost response, source/destination restart and interrupted transport recover the same operation, reconcile present chunks by digest and never infer success from a Queen reference, transport exit or A2A/MCP client state. Record actual payload route and bytes; bounded Pi references are measured separately.
- Wrong host/format/base, stale choice, revoked export, insufficient space, changed/truncated chunk, unsafe path and cross-subject receipt access refuse or remain explicitly unresolved without a replacement effect.
Deliverables: Bounded host-transfer contract, source and destination receipts, recovery/operator guide and m28b-weight-distribution-live evidence separating reference publication, payload movement, verification and deployment.
Checks / definition of done: both genuine training and independent import work; a real client uses the canary and accepted deployment; rejection and rollback are demonstrated. Judge depth by this lifecycle, not the number of supported frameworks.
Milestone 28c — macOS Developer Actions and Local Metal Workbench
Status: Complete — focused supported-Mac, installed Shortcuts component, local Metal, optional vMLX compatibility and final notarised-app evidence are retained in the M28c completion record. The selected private service-job observations remain component evidence; a revoked-scope status Shortcut on final installed bytes returned HTTP 403 as expected. The 28c1 admitted deployment lifecycle remains Planned.
Scope decision (25 September 2026): A developer needs authenticated Mac actions and useful local model work. Spoken Siri invocation is removed from this milestone: macOS exposes these App Intents through user-created Shortcuts, and voice adds no required developer capability. The original governed Mac MLX release, accepted generation, canary and rollback and generation-fenced vMLX serving move to 28c1. They remain required before any later mixed MLX/CUDA or accepted Mac deployment claim. Local observations never become signed Cohesix outcomes.
Value and prerequisites: On the supported macOS 27 Apple Silicon host, the installed SwarmUI and extension use a delegated, Keychain-backed hive connection. A user-created Shortcut can start, inspect and cancel an approved service job and the app can explain that job from scoped evidence with Foundation Models; coh resolves the same durable identity. Separately, the developer can select pinned local model/data/adapter bytes in SwarmUI, run bounded MLX inference and held-out evaluation on the observed Metal GPU, and see device, hashes, memory and result. The Python package supplies actual local LoRA training. Installed vMLX 1.6.65 is an optional, bounded loopback compatibility target for a disposable fused copy of the evaluated adapter. Missing vMLX does not remove direct MLX work.
Evidence boundary: The selected 28b journal admits neither this Mac’s local MLX process nor vMLX’s diagnostic generation label. SwarmUI’s existing release and job forms expose the genuine selected coh contracts when an admitted profile exists; their presence is not an accepted local MLX release. The local MLX panel must label inference/evaluation as observations, refuse changed model/data/adapter bytes and never infer promotion, a signed outcome or recovery from an HTTP response. Its chosen Python environment must contain the pinned Apple MLX dependencies and this exact Cohesix package. The frozen four-question vMLX comparison measures narrow compatibility only; repeated answer templates do not establish broad quality.
Completion gate: Retain the passed m28c-platform-live supported-host probe. On the selected Mac, verify installed app/extension Shortcuts discovery; authenticated selected service start, inspection, held cancellation and scope revocation; one source-linked Foundation Models explanation with deterministic manual operation; actual local MLX LoRA training plus SwarmUI inference and held-out evaluation with pinned input and observed Metal identity; the signed installed vMLX engine’s bounded four-response compatibility against the disposable fused candidate; and the final exact-source Developer ID signed, notarised, stapled, Gatekeeper-accepted app. Bind the final evidence to source, app, extension, Mac and private target/model identities. Focused owner tests and these live observations suffice; no full suite, spoken Siri, Release B or Pi hardware acceptance is implied.
Task breakdown
Title/ID: m28c-apple-platform-feasibility
Milestone: 28c / m28c-apple-platform-feasibility
Goal: Pin the public macOS 27 SDK, supported Mac, signed App Intents discovery and local AI/Metal availability.
Inputs: 28/28b; supported Apple Silicon Mac; Xcode/macOS 27 SDK; existing SwarmUI package.
Changes: Native feasibility probe, exact app/extension identities and signing profile; HOST_TOOLS and TOOLCHAIN_MAC_ARM64 support matrix.
Commands: swift test --package-path apps/swarmui/native/apple; scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28c-platform-live --reference-config "${M28C_PLATFORM_REFERENCE}" --host-profile macos-apple-silicon --state-dir "${M28C_EVIDENCE}/m28c-platform-live"
Checks: Installed signed actions are discoverable; actual device and public API availability are recorded.
Deliverables: Focused m28c-platform-live support matrix and signing decision.
Title/ID: m28c-native-apple-actions
Milestone: 28c / m28c-native-apple-actions
Goal: Use App Intents in user-created Shortcuts to operate one selected delegated service job without new authority.
Inputs: m28c-apple-platform-feasibility; selected gateway standing scope and stable job identity.
Changes: Typed start/inspect/cancel native actions, shared Keychain enrollment, bounded scope filtering and deep links; HOST_TOOLS first-use path.
Commands: swift test --package-path apps/swarmui/native/apple; cargo test --locked -p hive-gateway --bin hive-gateway jobs::tests; cargo test --locked -p swarmui --lib.
Checks: Installed Shortcuts start and inspect one admitted service job; held cancel prevents dispatch; revoked scope disappears. `coh` resolves the original ID. An unavailable or revoked choice fails closed.
Deliverables: Installed authenticated Shortcuts workflow with private target record; no speech claim.
Title/ID: m28c-mlx-metal-provider
Milestone: 28c / m28c-mlx-metal-provider
Goal: Provide bounded, content-bound local MLX inference, LoRA training and held-out evaluation on Metal.
Inputs: m28c-apple-platform-feasibility; pinned mlx and mlx-lm; selected private model/data and optional adapter.
Changes: cohesix.mlx_native and cohesix.mlx_workbench validate inputs, observe GPU/memory/artifact identity and classify local results without admission.
Commands: python3 -m pytest -q tools/cohesix-py/tests/test_mlx_native.py tools/cohesix-py/tests/test_mlx_workbench.py.
Checks: Actual selected Mac trains one adapter and performs inference/evaluation on Metal; changed bytes, format, bound and absent GPU refuse. Evidence labels local results as observations.
Deliverables: Installable Python MLX extra and selected local model/data/adapter record.
Title/ID: m28c-swarmui-mlx-workbench
Milestone: 28c / m28c-swarmui-mlx-workbench
Goal: Let a developer use the pinned local MLX model from SwarmUI after selecting a Python runtime and private profile.
Inputs: m28c-mlx-metal-provider; existing SwarmUI native app and host command review flow.
Changes: Local MLX panel invokes the fixed Cohesix Python module without a shell or gateway credentials, presents inference and held-out results with device/hashes/memory and an explicit local proof class. Existing `coh` release/job controls remain conditional on actual admission.
Commands: cargo test --locked -p swarmui --test workbench; node --test apps/swarmui/tests/mlx_frontend.test.mjs; cargo check --locked -p swarmui --bin swarmui.
Checks: Installed panel runs one real Metal inference and evaluation; rejects missing runtime/profile, changed inputs, oversized prompt and unsupported helper result. No local reply appears as a signed release result.
Deliverables: Usable local Metal desk in the signed app, plus focused contract and UI evidence.
Title/ID: m28c-vmlx-compatibility
Milestone: 28c / m28c-vmlx-compatibility
Goal: Verify installed vMLX 1.6.65 as an optional loopback serving format for a separate fused local model copy.
Inputs: Pinned signed app/engine, source model and evaluated local adapter; disposable content-bound serving copy.
Changes: Bounded vMLX client/session with exact app/engine/model identity, no Cohesix credentials or tools, and before/after hashes for local alignment repair.
Commands: python3 -m pytest -q tools/cohesix-py/tests/test_vmlx_compat.py tools/cohesix-py/tests/test_vmlx_runtime.py.
Checks: Four frozen operational responses match direct fused MLX within the predeclared latency bound; wrong model/endpoint, mutation and unexpected tool use refuse. Diagnostic generation labels confer no rollout authority.
Deliverables: Optional installed runtime compatibility record with explicit unsupported-format and proof limits.
Title/ID: m28c-foundation-models-assistance
Milestone: 28c / m28c-foundation-models-assistance
Goal: Explain one scoped admitted service job and suggest a typed next action without submitting it.
Inputs: Public Foundation Models SDK; verified selected gateway facts and native App Intents action schema.
Changes: Native on-device explanation, source links, labelled interpretation, manual fallback and prompt-injection/cross-subject refusal.
Commands: swift test --package-path apps/swarmui/native/apple.
Checks: Installed explanation cites the original job; model prose has no operational authority and missing Intelligence leaves the manual job path usable.
Deliverables: Native assistance record with interpretation and receipt separated.
Title/ID: m28c-mac-developer-journey
Milestone: 28c / m28c-mac-developer-journey
Goal: Qualify the final installed, directly distributed developer app on the selected Mac.
Inputs: Accepted focused 28c tasks; exact app and extension IDs, selected Developer ID profiles/certificate and notarisation credential.
Changes: Final stage/sign/notarise/staple/Gatekeeper check, installed first-use walkthrough and source-bound evidence ledger.
Commands: scripts/install/sign_swarmui_macos.py sign; scripts/install/sign_swarmui_macos.py notarize; codesign --verify --deep --strict; xcrun stapler validate; spctl --assess --type execute.
Checks: Final installed bytes expose the Shortcuts job path and SwarmUI local MLX desk; source and signer identity match the retained report. No 28b Mac release or Release B claim is inferred.
Deliverables: Notarised developer-useful Mac app and M28c completion record.
Milestone 28c1 — Governed Mac MLX Release and vMLX Rollout
Status: Complete — the M28c1 implementation record binds the selected Apple M4/macOS 27 native release, signed train and recovered rollback, and generation-fenced vMLX serving to one exact-source pinned QEMU Queen. This is selected component evidence, not physical Pi or Release B acceptance.
Title/ID: m28c1-admitted-mlx-release
Milestone: 28c1 / m28c1-admitted-mlx-release
Goal: Admit local Mac MLX inference, train, evaluate, direct serve, canary, promote and rollback through the selected 28b durable job and phase journal.
Inputs: Accepted 28c local provider; selected 28b policy/ticket, gateway admission and signed evidence contracts.
Changes: Mac native executor, bounded cancellation/recovery, generation fence, source-bound Metal/quality/resource reports and shared `coh`/Python/SwarmUI projections.
Commands: Focused owner tests and a new m28c1-mlx-live selected-host case.
Checks: Actual admitted job, held-out comparison, observed canary, promotion, rollback and original-identity reconciliation have signed outcomes; no CPU or remote fallback.
Deliverables: Accepted local MLX deployment lifecycle, not a detached process result.
Title/ID: m28c1-vmlx-governed-serving
Milestone: 28c1 / m28c1-vmlx-governed-serving
Goal: Bind optional vMLX serving to an accepted Cohesix generation and return to the verified incumbent after rollback.
Inputs: m28c1-admitted-mlx-release; pinned signed vMLX app/engine and content-bound fused model copy.
Changes: Generation-aware selection, same-generation inference checks, bounded process custody and recovery, quality/resource policy and SwarmUI projection.
Commands: Focused vMLX tests and a new m28c1-vmlx-live selected-host case.
Checks: Exact accepted generation serves the admitted candidate, changed generation refuses, and governed rollback observes the verified incumbent. No vMLX tool or MCP authority is imported.
Deliverables: Optional governed vMLX serving evidence; prerequisite for later mixed MLX/CUDA deployment claims.
Milestone 28d — MCP Access to Complete Selected Workflows
Status: Complete — the M28d implementation record binds the selected authenticated MCP transport, exact-source KVM Queen, native Orin CUDA and PEFT effects, shared verifier, refusal and original-identity recovery. Mixed MLX/CUDA, verified weight distribution and vMLX MCP client paths were not advertised by this selection; this is component evidence, not physical Pi or Release B acceptance.
Value: ordinary agents use useful Cohesix workflows without learning its namespaces.
Prerequisites: 28 including m28-agent-protocol-controls, and selected
28a/28b actions; accepted 28c1 MLX actions only when exposed. The Linux-hosted
protocol and CUDA/PEFT path remain usable without Apple.
Use a pinned MCP revision and maintained SDK where suitable. Provide the network transport needed by NeMo and a packaged local desktop-client path, reusing transport adapters rather than authority implementations. Curate capability discovery, preflight/submit/status/cancel/recover, adapter comparison/promotion/rollback and evidence tools/resources. Generate schemas/descriptions from the shared contract; no generic arbitrary file-write or complete administrative catalogue requirement.
When qualified MLX and CUDA providers are selected, project their approved
mixed workflows through the same typed job and recipe operations. Discovery and
preflight identify the selected provider/host profile, capability, capacity,
budget, compatible artifacts and authorised transfer boundary for each stage.
The CUDA host may be any compatible NVIDIA platform with an independently
qualified OS/driver/CUDA/package profile, including JetPack where applicable;
one platform’s evidence does not qualify another. MCP carries bounded
references and existing stage/job identities, not implicit raw payload transfer,
backend conversion, resource escalation or fallback to another host.
When m28b-verified-weight-distribution has been accepted and enabled for a
selected host pair, expose its shared operation as scoped artifact discovery,
destination preflight, explicit submit, status/cancel/recover and verified
destination receipt. A client may then distribute the selected winner after
the bake-off; promotion/activation remains a separate admitted operation.
Without that host operation, discovery reports unavailable rather than offering
a copy-shaped tool. MCP resources and any later read-only FUSE projection carry
bounded references, never weight bytes or write-triggered transfer effects.
Include the vMLX desktop application as a named MCP client compatibility path:
its configured MCP client connects to the Cohesix server through a supported
authenticated transport, discovers only admitted tools and observes the same
CUDA/PEFT and qualified MLX/CUDA job identities as other clients. Pin the app,
MCP SDK and transport versions in that path and verify actual tool discovery,
execution, refusal and lost-response recovery. vMLX’s model gateway and MCP
client are separate roles; its OpenAI-compatible endpoint is not an MCP server
or a Cohesix provider receipt. This path does not require Cohesix’s 28c MLX
provider or make an Apple host mandatory for the Linux MCP service.
Keep the Python library’s selected workflow requests and result views aligned
with these provider/host, identity, transfer and recovery fields through its
existing shared CLI/REST path; MCP adds no separate Python authority or verifier.
Publish examples, counterexamples, required authority, pending/terminal semantics, refusal and recovery. Preserve delegated identity, shared budgets, revocation and current admission. Bound input/concurrency, enforce transport auth/Origin where applicable, pin negotiation/errors and scope discovery. Never forward caller credentials to providers or execute model-returned calls. Independently disabling MCP must not break REST, A2A or existing jobs.
Deliverables: Generated controls/catalogue, authenticated network/local transports, standard-client configuration and live workflow evidence.
Task breakdown
Title/ID: m28d-mcp-policy-and-transport
Milestone: 28d / m28d-mcp-policy-and-transport
Goal: Implement bounded MCP transports under shared generated controls and delegated authentication.
Inputs: m28-agent-protocol-controls; 28 job/authority schema; hive-gateway auth; public MCP specification and maintained SDK; 28f native-client transport requirements.
Changes:
- tools/coh-rtc/src/{ir,lib}.rs + codegen — pin one MCP revision, selected network/local transports, schemas, negotiation/error mapping, input/response/queue/session/concurrency/stream timeout bounds and availability gates.
- apps/hive-gateway/src/mcp/ (planned) + src/main.rs — network transport required by the selected NeMo client plus packaged local desktop path; delegated identity, Origin/auth validation and lifecycle before tool dispatch.
- apps/hive-gateway/tests/{agent_protocol_controls,mcp_protocol}.rs (planned) — real enabled/disabled endpoints, local stdout protocol integrity, auth/Origin failures, malformed/oversize messages and bounded disconnect cleanup.
- docs/HOST_API.md + docs/SECURITY.md + docs/TEST_PLAN.md — transport selection and control matrix; generated docs updated atomically. Selecting NeMo requirements is a version/configuration check, not a dependency on M28f implementation.
Commands:
- cargo test --locked -p coh-rtc
- cargo test --locked -p hive-gateway --test agent_protocol_controls --test mcp_protocol
Checks:
- All master/MCP combinations enforce policy on both transports, with no disabled listeners/handlers/discovery/streams/tasks and no CLI/env override.
- Unauthenticated/bad-Origin/incompatible-revision/oversize traffic fails deterministically; bounded cleanup preserves underlying accepted jobs and REST/A2A independence.
- Probe the selected NeMo Agent Toolkit `mcp_client` release against the chosen network transport and delegated auth: its native client can inspect a generated tool name/schema, and an unsupported transport or credential mode is identified before the workflow kit is built. This compatibility probe is not M28f workflow acceptance.
Deliverables: Pinned transport/configuration contract, packaged launch paths and focused protocol/auth/control evidence; live useful-work closure remains the next task.
Title/ID: m28d-mcp-selected-workflows
Milestone: 28d / m28d-mcp-selected-workflows
Goal: Let an ordinary MCP client discover, complete and recover selected CUDA/PEFT and qualified mixed MLX/CUDA workflows.
Inputs: m28d-mcp-policy-and-transport; accepted 28a/28b actions and 28b operation/request/outcome/evidence contract; accepted m28b-verified-weight-distribution only when weight distribution is advertised; accepted 28c1 admitted MLX provider and approved mixed workflow when selected; shared generated registry; maintained SDK and named standard client; pinned vMLX desktop/client version for its compatibility path.
Changes:
- apps/hive-gateway/src/mcp/ + tools/coh-rtc/src/codegen/ — generated catalogue of selected preflight/submit/status/cancel/recover, compare/promote/rollback and evidence operations with authority, examples, errors, bounded resources and selected mixed-provider stages/transfer refs; add artifact distribution operations only after accepted m28b-verified-weight-distribution.
- apps/hive-gateway/tests/{mcp_protocol,mcp_workflows}.rs (planned) — mapping parity, visibility, required fields and cross-client idempotency; no direct provider calls or model-authored success.
- tools/cohesix-py/cohesix/** + tools/cohesix-py/tests/** — review and align selected mixed-provider request/status fields, original stage identities, explicit transfers and recovery with the same generated operation contract; if distribution is selected, project its transfer identity and destination receipt through the existing CLI/REST execution and verifier path.
- docs/HOST_TOOLS.md + docs/HOST_API.md + installation/doctor owners — versioned ordinary-client and vMLX MCP configuration, transport/auth setup and recovery examples; matrix/catalog gain m28d-mcp-live and a separate vMLX client compatibility record.
Commands:
- cargo test --locked -p hive-gateway --test mcp_protocol --test mcp_workflows
- cargo test --locked -p host-ticket-agent --lib
- scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28d-mcp-live --reference-config "${RELEASE_B_REFERENCE}" --host-profile "${RELEASE_B_HOST_PROFILE}" --state-dir "${RELEASE_B_EVIDENCE}/m28d-mcp-live"
Checks:
- Named ordinary client and exact version complete a useful CUDA job and PEFT comparison/deployment operation inside standing authority; refusal and lost-response recovery preserve original identities.
- Each selected operation has generated input/output/authority/lifecycle/evidence mapping; scoped discovery hides inaccessible records. Credential forwarding, arbitrary writes and caller-supplied receipts refuse.
- PEFT tools project the accepted 28b operation/request identity, held-out comparison and exact serving generation; only the shared verifier's successful requested outcome is labelled verified. Lost tool responses reconcile the original operation, including recovered failure and rollback blockers.
- When MLX and CUDA are advertised together, the named client completes a selected workflow using both providers and recovers the original stage/job identities. Discovery and preflight expose actual host capabilities, capacity and permitted transfer refs; wrong host, incompatible artifact, exhausted budget and unapproved payload transfer refuse before effects. Queueing or provider unavailability cannot imply completion or silently select another host.
- If weight distribution is advertised, a standard MCP client submits a bake-off-selected artifact to one compatible destination through the accepted shared host operation, loses a tool response, then recovers the original transfer identity and destination-verified full digest. Refused export, insufficient space and incompatible format create no payload effect; a Queen reference or successful tool call never counts as delivered bytes.
- The installed vMLX client, when claimed supported, connects with its actual configured MCP transport and delegated credentials; its session discovers tools and model-backed calls preflight, submit and recover permitted CUDA/PEFT work. Confirm tool names/schema, client-side tool policy, refusal visibility and original operation identity across a lost response. A vMLX model response or MCP tool result alone cannot certify provider completion; no vMLX session or unavailable compatible model is recorded as a blocker, not a passing mock.
- The installed Python wheel projects the same selected request identity, host/provider selection, pending/refused/terminal states and verified outcome where its API exposes those operations; Python output cannot supply an MCP receipt or independent success verdict.
- MCP-only operation works; read-only conformance cannot close mutating acceptance. Real shared-budget/revocation tests use CLI/REST and MCP without requiring A2A.
Deliverables: Generated selected catalogue, client configuration/guide and m28d-mcp-live outcome/recovery evidence.
Checks / definition of done:
- The selected MCP revision, generated catalogue and packaged network/local transports pass real endpoint, negotiation, bounds and disabled-surface checks. Delegated authentication, Origin where applicable, scoped discovery, malformed input, incompatible revision, cross-subject access, revocation and concurrency refusal are exercised; disabling MCP leaves accepted jobs and REST/A2A usable. The pinned native NeMo client probes the selected network transport and auth mode; its complete agent workflows remain M28f’s acceptance.
- A named, versioned standard client uses the published configuration to discover admitted schemas and complete a real CUDA job plus a PEFT comparison and deployment operation. Retain the original request/job identity, native result and shared-verifier evidence across cancellation, lost response, reconnect and gateway restart. Denied or exhausted actions cause no effect; pending, uncertain and recovered failure never become verified success from an MCP result or model text. Exercise MCP-only operation and shared budget and revocation behavior with an existing authenticated client surface.
- When advertised, a selected mixed MLX/CUDA workflow runs on independently qualified provider profiles with explicit host selection, capacity and approved transfer boundaries; wrong-host, incompatible-artifact and unapproved-transfer requests refuse before effects. If verified weight distribution is advertised, its already accepted host operation supplies actual destination bytes, original transfer identity and destination digest evidence; a reference or tool result does not prove delivery.
- A claimed vMLX compatibility path uses a pinned live model session and the application’s configured MCP client to discover, invoke, refuse and recover the same admitted operation; retain a separate compatibility record. The installed Python wheel, where it exposes selected operations, agrees on identity, provider/host selection, pending/refused/terminal state and verified outcome without becoming another authority or receipt source.
- Retain exact source, generated profile, package, client/configuration and
native evidence identities for
m28d-mcp-liveand each claimed conditional path. Focused tests, read-only discovery, mocks and client-reported success cannot close live work. Full administrative parity and MCP FUSE remain in 36.
Milestone 28e — A2A Delegation of Durable Selected Jobs
Status: Complete — selected Linux CUDA/PEFT A2A delegation and recovery qualified against exact-source KVM and native Jetson evidence. Conditional mixed MLX/CUDA, weight distribution and vMLX composition were not selected.
Value: agents delegate long GPU/adapter jobs and reconnect to their actual result.
Prerequisites: 28 including m28-agent-protocol-controls, and selected
providers; shared gateway code may be reused,
but MCP enablement/conformance is not required.
Implement one pinned A2A revision/binding using a maintained SDK: scoped Agent
Card/skills, authenticated task creation, progress/streaming, status, verifiable
artifact references, cancellation and reconnect/recovery. Back tasks with existing
durable jobs, not another scheduler, mailbox or checkpoint engine. A task does
not grant arbitrary sub-actions. Each effect needs fresh admission and shared
accounting; retry across protocols cannot reset budgets or repeat uncertain work.
Map terminal/failed/cancelled/ambiguous states from observed provider outcomes.
For a selected mixed MLX/CUDA workflow, the A2A task correlates its existing
stage/job identities, provider/host selections and authorised artifact transfers.
If accepted m28b-verified-weight-distribution is selected, expose a distinct
distribution skill backed by its existing durable transfer operation. Task
progress may link bounded chunk-reference and byte-count evidence, but task
completion requires the scoped destination verification receipt; deployment
remains a separate authorised task/action. Without the host operation the skill
is absent. A2A artifacts never carry the model bytes or create a new copy path.
Queue delay, capacity refusal, disconnect and revocation remain visible without
submitting a replacement effect. Delegation cannot change hosts, export private
inputs, convert incompatible artifacts or expand the workflow’s admitted
authority. The A2A service remains usable on its Linux CUDA/PEFT path when
Apple is absent.
For a vMLX-assisted agent, a named A2A-capable peer uses vMLX’s explicitly
configured OpenAI-compatible model endpoint while the peer speaks A2A to
Cohesix. Verify this composition end to end when vMLX compatibility is
claimed; do not label the vMLX app itself an A2A peer or turn its model/tool
output into task, admission or outcome authority. A selected remote CUDA model
endpoint is separate from Cohesix CUDA job execution, with explicit endpoint,
data-routing and credential boundaries rather than an implicit fallback.
Arbitrary push callbacks, extra bindings and generic multi-agent coordination
stay in 36/34.
Deliverables: Pinned task/job state mapping, independently controlled A2A service, peer configuration and reconnect/cancellation evidence.
Task breakdown
Title/ID: m28e-a2a-durable-jobs
Milestone: 28e / m28e-a2a-durable-jobs
Goal: Delegate and recover long-running selected jobs, including qualified mixed MLX/CUDA workflows, through a standard A2A peer.
Inputs: 28 job/authority/control contracts; selected 28a/28b providers and 28b operation/request/outcome/evidence contract; accepted m28b-verified-weight-distribution only when its skill is advertised; accepted 28c1 admitted MLX release and approved mixed workflow when selected; shared gateway; pinned public A2A revision/binding and maintained SDK; selected NeMo Agent Toolkit native A2A client binding; a pinned vMLX model endpoint and named A2A-capable peer for the vMLX compatibility path; no MCP dependency.
Changes:
- tools/coh-rtc/src/{ir,lib}.rs + codegen — pin revision/binding, scoped Agent Card/skills and bounds for task creation, progress, streams, artifacts, reconnect cursors, retention and concurrency; advertise distribution only for an accepted underlying host operation.
- apps/hive-gateway/src/a2a/ (planned) — canonical task-to-job ID correlation; map pending/running/input-required/terminal/cancel-requested/cancel-confirmed/uncertain states to the selected binding without inventing terminal success.
- apps/hive-gateway/tests/{agent_protocol_controls,a2a_protocol,a2a_jobs}.rs (planned) — scoped task/artifact access, stream backpressure and cursor expiry, cancellation race, restart/reconnect and independently disabled endpoints.
- tools/cohesix-py/cohesix/** + tools/cohesix-py/tests/** — align the Python view of selected mixed jobs, stage lineage and verified outcomes, including transfer identity and destination receipt when selected, with the same shared operation after A2A reconnect; do not add a Python-owned task journal or provider executor.
- docs/HOST_API.md + docs/HOST_TOOLS.md + matrix/catalog — named standard peer configuration, vMLX model-endpoint/peer setup and m28e-a2a-live with a separate vMLX composition record; disabled A2A leaves underlying jobs recoverable through existing authenticated surfaces.
Commands:
- cargo test --locked -p coh-rtc
- cargo test --locked -p hive-gateway --test agent_protocol_controls --test a2a_protocol --test a2a_jobs
- scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28e-a2a-live --reference-config "${RELEASE_B_REFERENCE}" --host-profile "${RELEASE_B_HOST_PROFILE}" --state-dir "${RELEASE_B_EVIDENCE}/m28e-a2a-live"
Checks:
- A2A-only peer delegates a real job, disconnects, reconnects after gateway restart and obtains the correct scoped provider outcome/artifact references without re-execution.
- Before locking the binding, the selected NeMo Agent Toolkit `a2a_client` can read the scoped Agent Card, resolve a selected skill and use native task lookup/cancellation against the gateway. Its client timeout does not erase or silently cancel an accepted Cohesix job; full NeMo workflow acceptance remains M28f.
- Pending cancellation never means confirmed termination; ambiguous native outcomes remain explicitly uncertain and accounted. Stale/expired cursors return a bounded resynchronisation path.
- A PEFT task retains the same release operation/request identity, serving generation, verified-outcome verdict and evidence references after reconnect. Task completion alone cannot upgrade a failed comparison, recovered failure or rollback blocker to release success.
- When a mixed workflow is advertised, an A2A-only peer delegates it across selected MLX and CUDA providers, disconnects during pending or running work, and reconnects to the same stage/job lineage and verified outcome. Wrong-host, over-budget, incompatible-artifact and unapproved-transfer requests refuse; no task state supplies a missing native outcome or authorises a new host.
- If weight distribution is advertised, an A2A-only peer delegates the selected winner to a compatible destination, disconnects during real byte movement and reconnects to the same transfer/job identity and destination receipt. Task completion cannot replace the full-file digest check; failed or uncertain transfer remains distinguishable from deployment, and a cross-protocol retry cannot copy the bytes a second time.
- When vMLX-assisted A2A is claimed, the named peer uses a live pinned vMLX model session or explicitly selected remote endpoint, delegates a permitted CUDA/PEFT job through A2A, and reconnects to the same scoped task/job outcome after interruption. Record model endpoint, peer and provider identities separately; model text, tool calls and task completion do not establish a successful provider outcome.
- Python observation of that shared operation agrees with the A2A task's underlying job identity, native outcome and evidence reference; protocol task completion cannot upgrade a Python pending or failed result.
- All master/A2A flag combinations, cross-subject reads, unauthorised sub-actions, malformed/oversize traffic, slow consumers and revoked scopes fail safely; no push callbacks or second scheduler.
Deliverables: Pinned state-mapping table, service/peer package, lifecycle/recovery guide and m28e-a2a-live evidence separate from MCP acceptance.
Checks / definition of done: a named standard peer delegates a real CUDA/PEFT job, disconnects and reconnects to its correct scoped outcome. Discovery or mock task completion is insufficient.
Milestone 28f — NeMo Agent Toolkit Adoption Kit and Live Integration
Status: Complete for the selected Linux AArch64 NeMo Toolkit 1.9.0 and Jetson/KVM CUDA/PEFT component scope. The implementation record binds the installed wheel, native client workflows, exact target and model identities, focused checks, adverse results and proof limits. The physical Pi and assembled Release B remain separate acceptance gates.
Value: NeMo developers can use Cohesix inside a normal workflow, not only read a compatibility claim. Prerequisites: 28, selected CUDA/PEFT providers, 28d and 28e. Apple is optional for a NeMo deployment, not a required package or runtime dependency.
Verify and use the selected Toolkit release’s native MCP/A2A clients first. Ship a pinned kit with version constraints/lockfile, concise configuration, authentication/secret references, typed outputs, correlation and runnable workflows. Use a small plugin only for a demonstrated native-configuration gap; no fork, generic wrapper framework or duplicate SDK/action catalogue. Configure the native MCP function group with a selected tool list, protected transport and bounded timeout/reconnect behavior. The native A2A client uses the selected release’s per-user workflow and Agent Card/task helpers. If more than one user is served, use per-user MCP clients as well; map each verified gateway credential to the same delegated Cohesix subject across both protocols. Toolkit user-ID resolution or model text is not authentication, admission or a job receipt. Claim a combined authenticated per-user MCP and A2A Toolkit process only after the pinned release starts that exact configuration and both client paths work; otherwise keep the two native workflows separate and record the limitation.
Require two real workflows: a NeMo agent preflights/submits/inspects an approved CUDA job through MCP; and a NeMo workflow delegates adapter evaluation/canary/ release through A2A with a failed candidate or interruption. Demonstrate bounded unattended operation and a denied action. NeMo owns its planner/model/checkpoint state; Cohesix owns admitted effects, operational recovery and receipts.
Expose the accepted HF PEFT training/artifact/serving path through these workflows; it need not use NeMo Framework as trainer to be useful to NeMo agents. Qualify NeMo-produced imports by exact format/base/runtime evidence, never branding. Use the workflow’s configured model endpoint, including a qualified vMLX OpenAI-compatible gateway or selected CUDA serving endpoint, without a new Cohesix inference proxy. Pin and probe the chosen endpoint and keep NeMo’s MCP and A2A clients connected to Cohesix’s governed operations, not to a model endpoint as a substitute for job receipts. Local/remote NIM or other NeMo services are separately selected and probed, not required alongside full NeMo Framework/Triton/Kubernetes on the 8GB Jetson.
Use native Toolkit evaluation/profiling to compare direct and Cohesix-backed operation on the same task: setup, credential exposure, results, recovery, control latency and evidence utility. Record bad results and unknowns; tracing correlation never substitutes for authoritative provider outcomes. External upstream catalog acceptance is not a release gate; publication requires owner authorisation/credentials. Broad NeMo families remain deferred to 34.
Deliverables: Locked installable NeMo kit, two native-client workflows, reproducible setup and measured recovery/value evidence.
Task breakdown
Title/ID: m28f-nemo-agent-toolkit-kit
Milestone: 28f / m28f-nemo-agent-toolkit-kit
Goal: Provide useful Cohesix tools/jobs in an ordinary pinned NeMo Toolkit installation without a fork.
Inputs: 28d/28e; verified Toolkit native MCP/A2A clients; installed coh/Python/evidence interfaces; selected 28a/28b recipes.
Changes:
- integrations/nemo-agent-toolkit/ (planned) — exact dependency lock/version constraints, selected-tool `mcp_client` and per-user `a2a_client` configurations, protected transport/auth references, typed result/correlation mapping and two runnable workflows; add a plugin only for a demonstrated native-configuration gap.
- scripts/install/ + docs/HOST_TOOLS.md + tools/cohesix-py/README.md — distributable kit and clean-environment setup/doctor instructions; identify Toolkit host, model endpoint, Pi Queen and separate GPU executor.
- tests/test_nemo_agent_toolkit.py (planned) + matrix/catalog — config validation, dependency/optional-service refusal, installed artifact provenance and m28f-nemo-install.
Commands:
- python3 -m pytest -q tests/test_nemo_agent_toolkit.py
- scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28f-nemo-install --reference-config "${RELEASE_B_REFERENCE}" --host-profile "${RELEASE_B_HOST_PROFILE}" --state-dir "${RELEASE_B_EVIDENCE}/m28f-nemo-install"
Checks:
- Clean installation uses locked candidate/released artifacts without editable checkout or private steps; actual Toolkit native client compatibility is verified before configuring a fallback plugin.
- The pinned Toolkit's own MCP ping/tool-list/tool-call path resolves the selected Cohesix schema and a denied call; its A2A client resolves the scoped Agent Card and task helpers. Record native package versions, selected tool names, credential mode and transport rather than inferring compatibility from protocol labels.
- If the kit advertises both protected clients in one per-user Toolkit process, its exact pinned configuration starts and authenticates both paths. A failed combined startup is reported with a separate-workflow configuration, not hidden by dropping per-user auth.
- No raw executor credentials, parallel action registry, mandatory Apple dependency or implicit NIM/Framework/Triton/Kubernetes deployment; optional services report unavailable when absent.
Deliverables: Versioned kit/lockfile, documented reference topology/client matrix, quick start and m28f-nemo-install evidence.
Title/ID: m28f-nemo-live-workflows-and-value
Milestone: 28f / m28f-nemo-live-workflows-and-value
Goal: Demonstrate useful CUDA and adapter work, bounded autonomy and recovery through both native Toolkit clients.
Inputs: m28f-nemo-agent-toolkit-kit; real selected CUDA/PEFT providers; configured model endpoint; fixed task data/incumbent; native Toolkit evaluation/profiling.
Changes:
- integrations/nemo-agent-toolkit/ — MCP CUDA preflight/submit/inspect and A2A adapter evaluate/canary/release workflows using a real pinned HF PEFT candidate, failed-candidate and interruption recovery; NeMo retains its own planner/checkpoint state.
- Existing conformance collector + docs/BENCHMARKS.md — same-input direct versus Cohesix-backed procedure with fixed quality/control-latency budgets, setup/credential/manual-intervention measures and native Toolkit trace references.
- docs/HOST_TOOLS.md + matrix/catalog — m28f-nemo-live with denied action, cross-protocol retry/budget exhaustion, reconnect and portable evidence links.
Commands:
- python3 -m pytest -q tests/test_nemo_agent_toolkit.py
- scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28f-nemo-live --reference-config "${RELEASE_B_REFERENCE}" --host-profile "${RELEASE_B_HOST_PROFILE}" --state-dir "${RELEASE_B_EVIDENCE}/m28f-nemo-live"
Checks:
- Both ordinary native clients cause and observe real permitted work; a denied action causes no effect; failed candidate cannot promote and interruption preserves the original job identity.
- The A2A path uses the actual PEFT adapter/base metadata and verifies the served generation after canary/promotion or rollback. Client timeout, reconnect and native `get_task`/`cancel_task` helpers preserve the original task/job identity; timeout alone is neither confirmed cancellation nor failed training.
- In the multi-user configuration, two Toolkit users cannot inspect each other's scoped records, tasks, adapters or evidence, even if client-supplied user IDs differ from verified gateway subjects; no Toolkit credential is forwarded to the CUDA executor.
- One shared subject/workflow budget survives MCP/A2A retry and restart; traces correlate with verified outcomes but do not replace them.
- Comparison uses identical tasks/data and predeclared budgets, recording adverse/unknown results; another person or agent reproduces the instructions with evaluator identity disclosed.
Deliverables: Two reproducible workflows and m28f-nemo-live report with actual outcomes, failures, control overhead and practical setup/evidence assessment.
Checks / definition of done: another developer uses the kit with ordinary pinned Toolkit and a configured Cohesix deployment, reproducing both workflows from public instructions.
Milestone 28g — Installation, Integrated User Qualification and Release B
Status: Complete — the owner selected
the focused 1.2.0 acceptance gate below on 28 September 2026. Canonical QEMU
and physical Pi Test Plans passed Stages 01–05; native Mac and Jetson host
qualification, signed installer readback, Jetson KVM pressure, protocol
component runs, focused four-mode gateway tests and owner-evaluated adoption
have retained results at their original identities. The three archives and
native installers selected for release are the exact 869737b03982
publication set. The Linux reference is JetPack 7.2.1 / L4T 39.2.1. The
implementation record indexes the
evidence and its original source and artifact hashes. Publication to GitHub
and PyPI has its own post-acceptance record.
Value: complete capabilities form an adoptable release rather than disconnected adapters. Prerequisites: every required 28–28f outcome with exact-profile evidence; no later milestone is a replacement for missing work or a new release gate.
Extend existing least-privilege install/distribution, rollback and uninstall paths. Ship the Mac package, supported host/GPU tools, Python/NeMo kit, client configuration and recipes. Model/data downloads are explicit, with declared size, licence and credentials; do not hide them in installation or create a new distribution service. Preserve required package hashes/signatures/SBOMs.
Ship native Apple Silicon macOS .pkg and Ubuntu ARM64 .deb installers in
addition to the portable archives. Build them from the same exact source,
compiler-selected host profiles, generated policy, binaries, Python wheel and,
when selected, host-specific QEMU inputs as the assembled candidate. Keep the
existing 1.1.0-beta extraction path usable for side-by-side migration; a native package
cannot silently adopt its state. Install code separately from user-owned state,
CAS, evidence, models and credential references. QEMU, a graphical desktop and
GPU/model runtimes are required only for the selected journey; host-only use
must not require all three. Preserve existing advertised macOS 26 base-host
operation while qualifying macOS 27 for the Apple-specific journeys. The Linux
release reference is JetPack 7.2.1 (L4T 39.2.1, Ubuntu 24.04) on ARM64;
other Ubuntu and JetPack releases are outside this cut’s acceptance claim.
SwarmUI launches as a normal signed Mac app from Applications/Finder, Spotlight
and the Dock, and as a GNOME app from its application grid/search on Linux.
Both installations supply a stable name, icon and version, find their own
resources and matching coh/gateway without a shell PATH, source checkout or
bundle-root working directory, and open a useful connect/doctor state with no
running Queen. The Linux desktop entry and icon follow freedesktop paths;
headless Linux installation does not acquire desktop dependencies.
Doctor diagnoses versions, endpoint ownership, credentials, storage, GPU/model/ runtime compatibility, protocol controls and Apple availability with actionable remedies. Secrets never appear in example arguments/logs. CLI, SwarmUI, Siri and agents show the same job and distinguish local MLX from remote CUDA. Improve existing task views and explanations, not the UI theme or rendering architecture.
For 1.2.0, use the executed native CUDA/PEFT, Mac MLX, MCP, A2A and NeMo component journeys with their original source, host and target identities. Check the four effective gateway modes with the focused real-process protocol control test. The owner-evaluated full installation and client walkthrough binds the installed package hashes; report its measurements as unrecorded. Protocol services work without macOS/Apple Intelligence. Do not claim unobserved community adoption or numerical setup and latency results.
The assembled Release B QEMU and Pi production profiles select the gateway master, MCP and A2A switches enabled. Verify those values in each resolved manifest and its matching packaged host gateway. The false schema defaults and master/per-protocol disable modes remain available for explicit deployments. The Pi has exact-image SD boot and TCP qualification and a separately identified MCP/A2A hardware diagnostic.
Retain the frozen installation, quality and latency definitions for measured checks. The owner’s manual walkthrough has no measured steps, time, downloads or first-job latency; do not claim a numeric result from it. Compare native output quality where a component run measured it; no invented savings or deterministic model-output promises.
Keep host-process recovery separate from Queen reboot persistence. Queen loss must fail closed and reconcile safely; automatic VM-local durable resumption remains 37, not a Release B claim. A missing required API/package/credential/ hardware/evidence for the selected 1.2.0 gate is a named blocker.
The owner selected the focused 1.2.0 release gate
on 28 September 2026. It accepts the already completed staged QEMU/Pi,
physical SD, host, installer, pressure, component-live, focused gateway-mode
and owner-attested adoption results at their original identities. The exact
869737b03982 archive and signed-installer set is the distribution input;
publication-only documentation and pressure/adoption proof-tool changes in
later commits do not require a new target image or native installer. The
catalogued same-job four-mode live case and a separate raw client-parity
matrix remain available for expanded qualification outside this cut.
Deliverables: Native Mac and Ubuntu ARM64 installers, launchable SwarmUI apps, portable archives and guides, integrated acceptance matrix, exact release evidence and approval-ready release notes.
The documentation-only tasks below were authorized directly by the owner. They prepare use-case, operator-skill, glossary and diagram guidance for Release B readers; they do not change this milestone’s release status or supply release acceptance evidence.
Task breakdown
Title/ID: m28g-use-case-adoption-skills
Milestone: 28g / m28g-use-case-adoption-skills
Status: Complete — documentation-only adoption guidance, 26 September 2026.
Goal: Give agents and operators distinctive, usable procedures for each documented use case and a complete community-facing Release B overview.
Inputs: docs/USE_CASES.md; existing repo skills; installed-client, provider, evidence and authority contracts; 28–28g evidence boundaries.
Changes: skills/*/SKILL.md; docs/USE_CASES.md; README.md; llms.txt; this task record. Host-routing correction also classifies the NeMo kit README in configs/implementation_surfaces.toml and regenerates its dependent outputs. Preserve six generated use-case headings and nine playbooks.
Commands: skill-creator quick_validate for each new or changed skill; python3 scripts/ci/check_host_integration_inventory.py; scripts/check-generated.sh; git diff --check; local-link and claim review.
Checks: Skills have distinct triggers and outcomes, route to exact-version contracts, preserve scoped authority and original-identity recovery, and make no unearned installed, Pi, provider or industry claim. USE_CASES keeps all existing use cases and playbook ideas while explaining the assumed Release B workflows.
Validation: Initial addition: six skill entrypoints passed quick_validate; host inventory retained six use cases and nine playbooks; check-generated, local links and git diff --check passed. Host-routing correction: nine skill entrypoints passed quick_validate; eight implementation-surface tests, host inventory, check-generated (including Test Plan and NIST guards), local links and git diff --check passed. Skills inspect actual Mac/Linux compatibility and offer supported fixes; model rollout supports one-host and mixed-host journeys. No live target, native provider, installer or release gate was run for this documentation task.
Deliverables: Discoverable repo-managed skills, revised use-case guide and focused validation record. This documentation does not qualify or publish Release B.
Title/ID: m28g-operator-skill-portability
Milestone: 28g / m28g-operator-skill-portability
Status: Complete — instruction portability at the stated Mac/Linux scope, 26 September 2026.
Goal: Make the nine operator skills usable from matching Mac and Linux installations by agents with different skill-loading and MCP/A2A capabilities.
Inputs: The nine repo-managed skills; README.md; docs/HOST_TOOLS.md; selected host tools and gateway; Mac and Jetson test beds; m28g-use-case-adoption-skills and m28g-host-clients-as-built-alignment.
Changes: skills/cohesix-*/SKILL.md, skills/cohesix-ai-host-setup/references/linux.md, README.md and docs/HOST_TOOLS.md — resolve copied-skill document routes, absolute installed tool paths, non-login executable discovery, gateway ownership, private protocol headers and subject-scoped multi-user checks. Preserve existing role and authority contracts.
Commands: Validate each skill with skill-creator quick_validate; check local links and Bash snippets on Mac and Linux; exercise read-only CLI/Python and mock evidence from an unrelated working directory; run python3 scripts/ci/check_host_integration_inventory.py, scripts/check-generated.sh and git diff --check.
Checks: Instructions work without a source-root current directory, identify installed-version and agent transport constraints, prevent two gateways from claiming one Queen, and require separate subject credentials plus independently observed native job outcomes for any many-user claim. Documentation and mock checks cannot establish installed Release B, live MCP/A2A jobs, native provider work or diverse-vendor acceptance.
Validation: AI-assisted review and edits; nine skill entrypoints passed quick_validate; 31 local links and anchors resolved; 13 Bash snippets passed syntax checks on both Mac and Jetson; host inventory, generated consistency, and git diff --check passed. Mac source-built mock inspection and Jetson 1.1.0-beta mock pack creation/inspection worked from /tmp. The pinned Jetson NeMo executable worked from a non-login SSH shell by absolute path; Mac Codex MCP help was inspected, but no cross-vendor live Cohesix job was accepted. The M28g implementation record separates these observations from Release B acceptance.
Refinement at `020a516300`: the delegation and GPU skills describe cumulative standing attempts, caller-ticket operation quotas and publisher-epoch Worker replacement observed in the Pi diagnostic; both amended skills passed quick_validate and the generated implementation inventory remained consistent. This instruction check does not add a cross-vendor live acceptance result.
Deliverables: Corrected skills and host guide with an exact Mac/Linux validation matrix and proof limits in the M28g implementation record.
Title/ID: m28g-glossary-as-built-alignment
Milestone: 28g / m28g-glossary-as-built-alignment
Status: Complete — documentation-only owner request, 27 September 2026.
Goal: Give Release B readers a complete, source-aligned glossary for the selected host, agent-protocol, model-release and evidence workflows.
Inputs: docs/GLOSSARY.md; docs/STATUS.md; docs/HOST_API.md; docs/PRIVATE_LORA_RELEASE.md; docs/USE_CASES.md; selected 28–28f component records and generated protocol controls.
Changes:
- docs/GLOSSARY.md — AI-assisted terminology review and drafting define missing Release B operator terms and distinguish selected component behavior, native outcome proof and unselected weight transfer.
- docs/BUILD_PLAN.md — retain this documentation-only task and its validation record.
Commands: scripts/check-generated.sh; git diff --check; local-link, heading and source-claim review.
Checks: Every added term agrees with its owning as-built contract; glossary sections and links remain usable; no component evidence is promoted into a new target or release claim.
Validation: Generated consistency, Test Plan cross-file checks, local links and metadata, glossary sections and unique headings, and git diff --check passed. Source-claim review used the selected 28–28f records and owning public contracts. No runtime, native provider, QEMU, Pi or assembled-release gate was run.
Deliverables: Updated public glossary and focused validation record; no runtime, Pi or release-acceptance evidence.
Title/ID: m28g-user-diagram-as-built-audit
Milestone: 28g / m28g-user-diagram-as-built-audit
Status: Complete — documentation-only owner request, 27 September 2026.
Goal: Help 1.2 users follow the selected cross-protocol job path and private LoRA recovery, and distinguish target runtime address spaces from external host work in a rotatable cutaway.
Inputs: Tracked Markdown inventory; existing Mermaid diagrams; docs/ARCHITECTURE.md; docs/HOST_TOOLS.md; docs/HOST_API.md; docs/PRIVATE_LORA_RELEASE.md; docs/ROLES_AND_SCHEDULING.md; selected QEMU and Pi manifests; docs/TEST_PLAN.md; selected 28d–28f contracts; GitHub diagram syntax.
Changes:
- docs/HOST_TOOLS.md — AI-assisted as-built review adds one gateway-to-native-job flowchart with original-ID inspection and outcome boundaries.
- docs/PRIVATE_LORA_RELEASE.md — AI-assisted as-built review adds one trained-or-imported candidate flowchart with canary, recovery and blocked-promotion branches.
- docs/ARCHITECTURE.md + docs/diagrams/target_host_boundary.py + docs/diagrams/target-host-boundary.svg — generate one embedded ASCII STL cutaway and labelled static plan; distinguish target address-space wells, host process pads and the console-only ingress. The source owns both outputs and supports deterministic regeneration.
- docs/BUILD_PLAN.md — retain this scoped documentation task and validation record. Existing diagrams stay where they already explain their owning contract; README remains lightweight.
Commands: scripts/ci/check_mermaid_github.sh against all tracked Markdown; focused Mermaid CLI SVG/PNG renders; python3 docs/diagrams/target_host_boundary.py --check; local STL geometry and rotated-view checks; scripts/check-generated.sh; local-link and metadata checks; git diff --check.
Checks: New arrows follow the selected gateway or PEFT release contract; the cutaway keeps CUDA/PEFT outside seL4 and shows only selected child runtime isolation. Original-ID recovery, failed-candidate status and independent native verification remain explicit. No diagram implies that a protocol reply proves provider completion or that the target is formally verified.
Validation: Tracked Markdown inventory, existing-diagram review, GitHub Mermaid compatibility, focused SVG/PNG render and visual review, deterministic STL/SVG regeneration, 296 nondegenerate closed-mesh facets, opening and rotated STL views, generated consistency, local links and metadata, and git diff --check passed. No runtime, native provider, QEMU, Pi or assembled-release gate was run for this documentation task.
Deliverables: Two as-built user flowcharts, one native GitHub ASCII STL cutaway with labelled SVG companion and source, and a focused documentation validation record; no new release-acceptance evidence.
Title/ID: m28g-issue-templates-1-2-alignment
Milestone: 28g / m28g-issue-templates-1-2-alignment
Status: Complete — documentation-only owner request, 27 September 2026.
Goal: Make public Cohesix 1.2 bug and feature reports easy to file while capturing enough context to reproduce a problem or assess a user need.
Inputs: .github/ISSUE_TEMPLATE/bug_report.md; .github/ISSUE_TEMPLATE/feature_request.md; docs/SECURITY.md; docs/HOST_TOOLS.md; docs/GLOSSARY.md; CONTRIBUTING.md; selected 28g documentation and evidence boundaries.
Changes: AI-assisted review replaces generic browser/mobile prompts with concise host/target, reproduction, and evidence questions in the bug template; the feature template asks for user need, desired behavior, observable success, and optional context. This task record retains scope and validation.
Commands: scripts/check-generated.sh; git diff --check; focused front-matter, metadata, link, and visible-body review.
Checks: Templates remain valid GitHub issue templates; public reports direct vulnerabilities to private reporting and prompt redaction; job recovery asks for the original identity without treating a lost reply as proof of success. No runtime or release-acceptance claim changes.
Validation: Generated outputs matched; YAML front matter parsed with the five GitHub template keys; local metadata, security-link target/anchor, and body with hidden hints removed were reviewed; git diff --check passed. No runtime, target, or release gate was run for this documentation task.
Deliverables: Two updated issue templates and this documentation validation record.
Title/ID: m28g-community-docs-1-2-stable-alignment
Milestone: 28g / m28g-community-docs-1-2-stable-alignment
Status: Complete — documentation-only owner request, 27 September 2026.
Goal: Give 1.2.0 readers a current starting path and keep user guides focused on workflows, architecture and evidence rather than milestone chronology.
Inputs: Current Markdown inventory; README.md; docs/QUICKSTART.md; docs/STATUS.md; docs/GLOSSARY.md; docs/USE_CASES.md; docs/ADOPTION.md; tools/cohesix-py/README.md; demo/README.md and demo/peft_adapter/README.md; release naming in scripts/release_bundle.sh; selected manifest and component contracts; historical 1.1.0-beta records.
Changes: AI-assisted audit updates active 1.2.0 entry points and archive examples, identifies older demos and Python/component packages as historical or selected-scope, and turns STATUS into a concise workflow/evidence map. Historical release archives, audit records, generated files, product behavior and milestone acceptance remain untouched.
Commands: scripts/check-generated.sh; git diff --check; focused Markdown metadata, local-link, archive-name and source-claim review.
Checks: Current user paths say 1.2.0 without a beta suffix; historical 1.1.0-beta identifiers retain their meaning; host and target boundaries, selected protocol profiles and native proof limits remain accurate. No new runtime or release-acceptance claim is inferred from this documentation audit.
Validation: Generated outputs matched; metadata and 261 local Markdown paths across the changed files passed; current-release beta references were removed; bundle names were checked against release_bundle.sh; git diff --check passed. Exact 1.2.0 bundle bytes were unavailable for extraction checks. No runtime, native provider, QEMU, Pi or assembled-release gate was run for this documentation task.
Deliverables: Community-facing 1.2.0 documentation corrections and this task record.
Title/ID: m28g-readme-release-status
Milestone: 28g / m28g-readme-release-status
Status: Complete — documentation-only owner request, 30 September 2026.
Goal: Identify 1.2.0 as the latest published release and present the videos without release-specific framing.
Inputs: README.md; published 1.2.0 release notes; owner correction; CONTRIBUTING.md and TEST_PLAN.md.
Changes: AI-assisted README edits replace obsolete candidate and publication wording, update the video introduction, and keep earlier release links with the release overview. Host tools, Python, benchmarks, generated contracts and release artifacts are unaffected.
Commands: scripts/check-generated.sh; scripts/ci/check_mermaid_github.sh --markdown-list <(printf '%s\n' README.md docs/BUILD_PLAN.md); focused Markdown metadata, fence, local-link and copy review; git diff --check.
Checks: README consistently identifies 1.2.0 as the latest published release, installation instructions use published archives, and videos describe Cohesix without a release label. Generated consistency and Test Plan contracts passed; metadata and fences passed for both changed files; 72 local README links resolved; Mermaid compatibility and git diff --check passed. Video links and workflow descriptions are unchanged. No runtime, QEMU, physical Pi or release-acceptance gate was run.
Deliverables: Corrected README and this scoped documentation task record.
Title/ID: m28g-huggingface-static-space
Milestone: 28g / m28g-huggingface-static-space
Status: Complete — documentation and static presentation publication authorized by Lukas Bower, 18 October 2026.
Goal: Publish a public static Hugging Face introduction to Cohesix 1.2.0 with the existing tour, a clearly labelled historical replay, and release and quickstart links.
Inputs: Published v1.2.0 release; existing public tour; native SwarmUI reference captures and their owning gallery; Hugging Face static-Space contract; direct owner request.
Changes: Maintain the standalone Space source in /Users/lukasbower/GitHub/cohesix-huggingface and publish it as lukeb-aidev/cohesix; retain source provenance, licensing and a publication record there. Correct obsolete candidate/publication wording in the current docs/QUICKSTART.md so the linked guide agrees with the published release; preserve immutable bundled guides. No runtime, protocol, Python SDK, host-tool, benchmark, generated contract or immutable release artifact changes.
Commands: Focused static asset, metadata and external-link checks; JavaScript syntax and replay-control browser checks; desktop/mobile visual and keyboard checks; independent source/claim review; scripts/check-generated.sh; git diff --check; anonymous public Space and deployed-file readback.
Checks: Tour uses the existing public video; replay is historical and disconnected with original source references and no fresh-execution or current-readiness claim; links resolve to the published release and versioned quickstart; no credentials or private captures enter the public source. Browser checks establish presentation behavior only, with no QEMU, Pi, native-provider or release-acceptance claim. Material AI assistance is recorded in the Space publication record.
Validation: Public static Space https://huggingface.co/spaces/lukeb-aidev/cohesix is running with private=false and sdk=static. Initial presentation source commit a963838d99d23af68fa56fcdf374fb1fada7566f passed anonymous byte-for-byte readback of all 17 uploaded files. Deployed JavaScript, CSS, icon, captures and fonts match local source; deployed HTML differs only by Hugging Face's injected public creator-ID variable. Local and public browser checks passed all seven phase selections, failed-canary/rollback semantics, bounds, previous/next/reset, play/pause/completion/restart, hidden-page pause, keyboard/skip link, 1440/768/390/320 widths, reduced-motion mode, native capture and opt-in video/fallback; the existing tour player loaded with its correct title. Desktop/mobile visual review, no-JavaScript fallback, source-asset/notices equality, external-link and YouTube identity checks, independent technical/claim review, generated consistency, Markdown metadata/fences and git diff --check passed. Styling reuses released SwarmUI tokens, bundled fonts/licenses and its Cohesix mark at the owner's request. The linked quickstart receives only current-publication status corrections. Host-tool, Python, generated-interface and benchmark inventories were reviewed as unaffected. No runtime, target, provider, performance or assembled-release gate was run for this static publication.
Deliverables: Public static Space, maintainable source and provenance in its Hugging Face repository, local source at /Users/lukasbower/GitHub/cohesix-huggingface, corrected current quickstart and the Space's PUBLICATION.md record.
Title/ID: m28g-pages-swarmui-theme
Milestone: 28g / m28g-pages-swarmui-theme
Status: Complete — documentation-site presentation and automatic publishing repair authorized by Lukas Bower, 19 October 2026.
Goal: Apply SwarmUI styling to GitHub Pages documentation on every automatic republish and render Mermaid diagrams without changing the GitHub Markdown sources.
Inputs: Current main-root GitHub Pages/Jekyll publishing configuration; README.md and docs Markdown; SwarmUI workbench palette, tokens, bundled fonts and mark; direct owner request.
Changes: Repository-owned Jekyll layout, semantic documentation styles and progressive enhancement; Pages configuration and maintainer guidance; focused rendering checks. Repair a README table boundary and split inline code in Hardware Bring-up that caused Jekyll to swallow later Markdown. Keep the host guide's pinned FUSE source link on GitHub when build/vendor trees are excluded from the site. The new maintainer guide adds one current-document inventory row; regenerate its dependent graph/catalogue identities and Rust/Python provider bindings together. Material AI assistance: theme implementation and independent technical review. Host commands, Python schemas, provider execution, benchmark workloads, target manifests and immutable releases are unchanged.
Commands: Local GitHub Pages-compatible Jekyll build; focused document/link and browser rendering checks including Mermaid, failed loading, keyboard navigation and narrow screens; scripts/check-generated.sh; git diff --check; scoped publication and deployed-file readback.
Checks: README and nested documentation inherit the same layout without per-file front matter; relative links and anchors survive the project base path; Mermaid renders from ordinary fenced source with readable fallback on failure; code, tables, images and navigation remain usable; existing automatic Pages trigger persists. Local and deployed presentation checks supply no runtime, target or release-acceptance evidence.
Validation: GitHub Pages 232/Jekyll 3.10.0 local build and static checks passed for 47 current pages and 10 exact retained Mermaid blocks. Fourteen Python publication checks and nine label-normalization tests passed. Browser checks rendered all ten current diagrams, preserved source for a deliberately malformed block while rendering the next block, retained readable fallbacks with the renderer blocked and JavaScript disabled, and checked 320/768/1440 widths, native dialog Escape/focus restoration and keyboard navigation. Existing anchors on the homepage, Quickstart, Architecture, Host Tools and Private LoRA Release were preserved. Independent review corrected generic page titles and retained Mermaid's protected parser bounds. Generated consistency passed after the documentation inventory update; the generated Rust and Python bindings differ only in the dependent graph identity. Sixteen authority tests, nine host-integration tests and nineteen Python provider-registry tests passed with the isolated source selected explicitly. Metadata, fences, changed Mermaid compatibility and whitespace checks passed. The existing root/main Pages deployment owns public promotion; its completed result and deployed-file readback are retained with the task's publication receipt. No target, provider-live, benchmark or release-acceptance gate was run.
Deliverables: Published documentation theme, maintained publishing contract and this scoped task record.
Title/ID: m28g-pages-table-layout
Milestone: 28g / m28g-pages-table-layout
Status: Complete — scoped documentation-site correction authorized by Lukas Bower, 19 October 2026.
Goal: Keep Markdown table columns readable on the homepage and reference guides through every automatic Pages republish.
Inputs: Published SwarmUI Pages theme; current Markdown table inventory; owner request; CONTRIBUTING.md and TEST_PLAN.md.
Changes: AI-assisted shared CSS correction for table intrinsic sizing; repair Markdown boundaries and command spans that hid existing tables; generate valid table boundaries from the Test Plan catalog; enable Markdown inside HTML disclosure blocks while retaining the current heading IDs; add table-preservation regression checks. Document the repeatable rules and independently review representative browser checks. Host tools, Python SDK, benchmarks, generated contracts and immutable release artifacts are unaffected.
Commands: Local Pages-compatible Jekyll build; python3 scripts/ci/check_pages.py --site out/pages-preview/cohesix; python3 -m unittest discover -s tests -p test_pages.py; browser column, wrapping, overflow and keyboard-scroll checks; scripts/check-generated.sh; Markdown metadata/link checks; git diff --check; scoped publication and deployed-file readback.
Checks: Short labels retain natural word widths; prose columns use available space; wide reference tables scroll within their own region; desktop and narrow layouts retain all table content without page overflow. Presentation checks make no runtime or release-acceptance claim.
Validation: The local Pages-compatible build retains every current source pipe table, including the restored Test Plan and audit registers; 47 current layout checks and 10 exact Mermaid source blocks pass. Twenty-six publication tests, twelve catalog tests, nine Mermaid adapter tests, generated consistency, Markdown metadata/fences, changed Mermaid compatibility and whitespace checks pass. Browser checks cover two through eleven columns on seven guides at 1223 and 390 pixels, homepage layouts at 320 and 1440 pixels, keyboard horizontal scrolling, and three script-free page variants. All 1301 previously rendered heading IDs remain present, with no new broken local fragment links; sixteen previously missing link targets are restored. Independent review corrected print wrapping. Host-tool, Python SDK and benchmark compatibility inventories were reviewed as unchanged; generated Test Plan rows differ only in blank block boundaries. Public promotion uses the existing Pages deployment, with completed deployment and public readback retained in the publication receipt. No runtime, target, provider-live, benchmark or assembled-release gate was run.
Deliverables: Shared table styling, maintainer guidance, browser evidence and this scoped task record.
Title/ID: m28g-pages-search-indexing
Milestone: 28g / m28g-pages-search-indexing
Status: Reopened narrowly — Lukas Bower requested recovery of Google Search Console sitemap fetch failures on 20 October 2026. Preserve the valid XML sitemap, diagnose exact submitted paths and crawl access, and qualify a generated text-format alternative if needed; Google processing and completed indexing remain external acceptance gates.
Goal: Make all retained public content pages discoverable through an automatically regenerated canonical sitemap and submit it in Google Search Console.
Inputs: Current Pages publication at ed7946923; _config.yml; docs/PAGES.md; Google Search Console property https://lukeb-aidev.github.io/cohesix/; owner request; CONTRIBUTING.md and TEST_PLAN.md.
Changes: AI-assisted audit of crawl availability, canonical links, publication scope and existing Search Console coverage. Enable the supported sitemap producer without restoring excluded pages or listing verification/error endpoints; add exact sitemap-coverage regression checks and maintainer guidance. Review the host-tool, Python SDK and benchmark inventories as unaffected by static search-discovery metadata. Recovery on 20 October 2026: Preserve the official XML producer and its current content coverage; add a supported plain-text alternative generated from the same Jekyll objects on every automatic Pages build, with exact XML/text/publication-set checks and malformed-output regressions. No literal URL list, target behavior, provider workflow, Python SDK or benchmark contract changes. Host-tool, SDK and benchmark inventory review finds these execution surfaces unaffected; this change is static discovery metadata only. A single identical-XML query submission did not resolve the processing failure and is retained as failed diagnostic evidence, not a successful repair.
Commands: Public HTTP/metadata and route-graph checks; Pages-compatible local Jekyll build; focused publication-checker Python tests; scripts/ci/check_pages.py; scripts/check-generated.sh; git diff --check; independent review; scoped publication; public sitemap readback; Search Console sitemap submission and URL inspection as applicable.
Checks: Every retained content URL is canonical, publicly fetchable and represented once; no deleted page, error page, verification endpoint, non-HTML artifact or wrong-origin URL appears. The sitemap regenerates through the existing Pages workflow. Submission receipts and indexing observations remain distinct from Google's eventual indexing decision. Recovery on 20 October 2026: Exact submitted HTTPS property/path, current crawl rules, manual actions, official XML schema, HTTP/compression and cache validators; Pages-compatible preview; focused sitemap/checker tests; scripts/check-generated.sh; independent review; whitespace; successful Pages deployment and exact public XML/text readback. Record Google live-fetch, submission and processing results separately; leave Google processing unaccepted while it still fails.
Validation: The official GitHub Pages-compatible producer emits exactly 108 unique canonical content URLs from the unchanged 111-page publication, including the standalone native walkthrough. The 404 page and both verification files are absent from the sitemap; verification bytes, nine release archives and all publication exclusions remain intact. All 53 focused Python tests pass, including nine sitemap regression tests; the full publication checker retains 108 shared-layout pages and nine Mermaid source blocks and verifies dynamic sitemap coverage. Generated consistency including Test Plan integrity and whitespace checks pass. A fresh public audit found all 108 content URLs fetchable and reachable without noindex directives. Search Console's aggregate coverage is dated 12 October; fresh URL inspection and accepted priority-queue requests are recorded separately without asserting every page is indexed. Publication acceptance requires successful Pages deployment, exact public sitemap readback and a verified Search Console submission receipt under out/pages-indexing-20261020. No runtime, target, provider-live, benchmark or assembled-release gate was run; host tools, Python SDK and benchmark contracts are unchanged. Recovery on 20 October 2026: All 59 focused publication tests pass. The pinned GitHub Pages 232/Jekyll build and publication checker retain 108 shared-layout pages and nine Mermaid source blocks, with exact unique XML/text/current-HTML coverage. An independent small real-producer probe passes initial/add/remove URL sets of 5/7/5, including a nonempty output collection, processed HTML, a directory index, static gallery and excluded error/verification/content pages at a different origin/base path. Generated consistency, Test Plan integrity, NIST smoke checks and whitespace pass with no generated-output changes. These are source/publication checks only; no runtime, provider-live, Python SDK, benchmark or assembled-release claim is made. Public deployment, readback, independent review and Google processing outcomes are retained in the recovery receipt; Google processing remains unaccepted unless that receipt records a successful result.
Deliverables: Automatic sitemap generation, maintained regression checks and guidance, plus publication/Search Console evidence under out/pages-indexing-20261020. Recovery evidence is retained under out/sitemap-recovery-20261020; material AI assistance covers diagnosis, the supported alternate-format implementation and independent review.
Title/ID: m28g-pages-full-audit
Milestone: 28g / m28g-pages-full-audit
Status: Complete — full documentation-site audit and material presentation repairs authorized by Lukas Bower, 19 October 2026; public deployment requires the separate readback receipt below.
Goal: Audit the complete public site, repair confirmed maintained-site defects and retain an explicit record of historical or external limitations.
Inputs: Public site at 0b7383d4d; complete generated route manifest; committed Markdown sources; existing Pages, Mermaid and SwarmUI contracts; owner request.
Changes: AI-assisted link, source/render, browser and independent theme audits; repair repository-directory and heading links, disclosure parsing, fenced examples, page titles, the homepage logo and expanded-diagram printing. Exclude 301 unused standalone HTML outputs while retaining their repository sources, release archives, verification endpoints and linked gallery; add a shared 404 page. Extend publication checks for excluded routes, every published source owner, exact code-fence retention, images and escaped disclosure markup. Repair the CAS template's blank fence boundary in its generator and regenerate the owned snippet and INTERFACES block. Host tools, Python SDK, benchmark contracts, runtime interfaces, immutable release source and unrelated worktree edits remain unaffected; the compatibility inventory was reviewed with no generated contract changes.
Commands: Full public route/resource/fragment crawl; source-to-render comparison; desktop/mobile, keyboard, diagram and print browser checks; local Pages build and publication checks; focused Python/Node and coh-rtc CAS tests; cargo fmt --all -- --check; cargo clippy --workspace --all-targets -- -D warnings; cargo check --workspace; cargo test --workspace; cargo audit; cargo deny check advisories; scripts/check-generated.sh including Test Plan consistency; scripts/ci/test_plan_run.sh --list; Markdown metadata/fence/link and whitespace checks; scoped publication and anonymous public readback.
Checks: Findings identify observed failures and exact affected routes; maintained-site repairs preserve documentation meaning, heading links and native source fallbacks; historical and external failures are reported without inventing target or release acceptance. Repeatable shared fixes and regression checks survive normal Pages publication.
Validation: The rebuilt site contains 111 HTML routes, down from 411. All 201 checked internal destinations and 358 HTML fragment targets pass; 108 shared-layout pages retain their source images, tables, fenced examples and nine Mermaid blocks. All 44 Python, 13 Node and three CAS tests pass. Responsive checks cover every retained non-verification HTML surface at 390 and 1440 pixels without page overflow, broken images or escaped disclosure closures; two renderer fallback events in the concurrent cache-disabled sweep rendered successfully in focused sequential checks. The logo preserves its proportions at 320, 390, 768 and 1200 pixels. Actual PDF printing returns an expanded canvas to its figure and restores its dialog afterwards. Rust formatting, Clippy, check and workspace tests pass (2851 passed, five ignored); generated consistency, Test Plan integrity/catalog, changed Mermaid syntax, headers and whitespace checks pass. Dependency audit/advisory checks fail separately for nine pre-existing vulnerabilities in the unchanged lockfile (five quinn-proto and four rustls). Three external TCG URLs remain rate-limited and one Linux Foundation URL times out; neither establishes a broken destination. Independent technical review found no remaining material website issue. Publication acceptance requires a successful Pages deployment and fresh public readback in out/pages-full-audit/FINAL_REPORT.md; local checks alone do not establish deployment. No QEMU, Pi, provider-live, benchmark or assembled-release gate was run.
Deliverables: Full audit report and evidence under out/pages-full-audit, maintained-site repairs, regression checks, deployment receipt and this scoped task record.
Title/ID: m28g-architecture-boundary-diagram-simplification
Milestone: 28g / m28g-architecture-boundary-diagram-simplification
Status: Complete — documentation-only owner request, 27 September 2026.
Goal: Make the architecture boundary explanation easier to read by retaining the diagram that conveys actual location, authority and communication paths.
Inputs: docs/ARCHITECTURE.md; selected QEMU and Pi manifests; docs/HOST_TOOLS.md; existing Mermaid flowchart and target-host STL cutaway; earlier m28g-user-diagram-as-built-audit record.
Changes: AI-assisted review removes the embedded ASCII STL, its static SVG companion and their single-use generator. The existing Mermaid boundary chart remains the architecture diagram; a short introduction identifies deployment groups, sole target TCP ingress, Queen authority and external native execution. The earlier diagram task record remains historical.
Commands: scripts/check-generated.sh; scripts/ci/check_mermaid_github.sh for docs/ARCHITECTURE.md; local-link, orphan-reference and metadata checks; git diff --check.
Checks: No 3D mesh interrupts the document; the 2D chart and adjacent prose retain host/target separation, target runtime relationships and native provider placement without implying new authority or live qualification.
Validation: Generated consistency and Test Plan cross-file checks passed; the retained Mermaid block passed GitHub syntax checks with zero warnings; Architecture metadata and 35 local links passed; no STL fence, live asset link or single-use generator remains; git diff --check passed. Only the earlier historical task record still names the removed files. No runtime, QEMU, Pi or release gate was run for this documentation task.
Deliverables: Simplified architecture section, removal of unused diagram assets, and this task record.
Title/ID: m28g-community-operator-reference-1-2-audit
Milestone: 28g / m28g-community-operator-reference-1-2-audit
Status: Complete — documentation-only owner request, 27 September 2026.
Goal: Make selected 1.2.0 operator and developer references accurate, readable and discoverable without losing current authority or recovery contracts.
Inputs: Fifteen requested docs; README.md; selected QEMU and Pi manifests; gateway read/delegation code; failover watchdog; host GPU, Worker, identity, field-bus and Mac provider contracts; CONTRIBUTING.md and TEST_PLAN.md.
Changes: AI-assisted review corrects REST read and write credential examples, distinguishes target Workers from external execution, replaces the unsafe older failover recipe with the fenced transaction and its current read-policy limit, and makes the repo map and specialist contracts easier to enter. README links every requested guide. Old beta drill transcripts are removed from the active runbook; current safety and recovery rules remain.
Commands: scripts/check-generated.sh; scripts/ci/check_mermaid_github.sh on changed Markdown; focused metadata, fence, local-link and README-coverage check; git diff --check.
Checks: Guides match selected source and profile boundaries; no old direct-symlink cutover or unauthenticated non-public REST read is offered as a current procedure; all fifteen requested docs are discoverable from README; no generated output or product behavior changes.
Validation: Generated consistency passed; two changed Mermaid blocks passed GitHub compatibility with zero warnings; seventeen changed Markdown files passed metadata, balanced-fence and local-link checks, and README linked all fifteen guides; git diff --check passed. No runtime, QEMU, physical Pi, native provider or assembled-release gate was run for this documentation-only task.
Deliverables: Fifteen focused guide audits, README navigation and this scoped task record.
Title/ID: m28g-macos-native-installer
Milestone: 28g / m28g-macos-native-installer
Goal: Install the exact Release B host candidate as a signed, notarized macOS package with a normal SwarmUI app launch.
Inputs: Accepted 27e signed host/desktop profiles and 28c Apple app/entitlements; exact 28–28f candidate; scripts/install/; scripts/release_bundle.sh; packaging/swarmui/Info.plist; supported Apple Silicon/macOS versions and external signing identities.
Changes:
- scripts/install/build_macos_pkg.sh + packaging/macos/** + scripts/release_bundle.sh + scripts/setup_environment.sh — stage the compiler-registered host payload, offline Python/NeMo kit and selected Mac assets at stable locations without mandatory QEMU setup; select `COHESIX_APP_IDENTITY` and `COHESIX_INSTALLER_IDENTITY` separately, sign nested code before freezing its Cohesix file manifest, then sign/notarize/staple the outer `.pkg`. Supply a receipt-bound removal helper; signing credentials remain outside the payload.
- scripts/install/{qemu_compat,setup_qemu_macos}.py + skills/cohesix-ai-host-setup/** — make guest QEMU optional, select a system binary only after a real four-core HVF startup, and build the pinned upstream 10.1.0 HVF fix in a separate user prefix when necessary. Do not replace Homebrew's binary or imply startup is guest acceptance.
- apps/swarmui/tauri.conf.json + packaging/swarmui/Info.plist + native app resource lookup — ship the accepted 28c App Intents integration, icon, version and required resources in `/Applications/SwarmUI.app`; resolve installed `coh` and gateway without a terminal environment.
- apps/swarmui/icons/swarmui-macos-appicon.png + scripts/install/stage_swarmui.py + tests/test_macos_installer.py + docs/SWARMUI.md — stage a distinct 1024-pixel Mac AppIcon based on the Cohesix circuit silhouette. The raster artwork was drafted with image generation, then checked at Dock sizes; the native icon converter binds the validated PNG bytes to the signed app.
- tests/test_macos_installer.py + scripts/release_qualify.py + docs/TEST_PLAN.md + docs/QUICKSTART.md — add exact installed-payload and GUI-launch checks, clean install, 1.1.0-beta side-by-side migration, interrupted/repeated install, replacement/rollback and uninstall evidence on the advertised Mac support envelope.
Commands:
- python3 -m pytest -q tests/test_macos_installer.py tests/test_host_package_stage.py tests/test_toolchain_setup.py tests/test_qemu_compat.py tests/test_release_qualify.py
- scripts/install/build_macos_pkg.sh --reference-config "${RELEASE_B_REFERENCE}" --out "${RELEASE_B_EVIDENCE}/installers/macos"
- python3 scripts/release_qualify.py installer --reference-config "${RELEASE_B_REFERENCE}" --installer-manifest "${RELEASE_B_EVIDENCE}/installers/macos/installers.json" --output "${RELEASE_B_EVIDENCE}/installers/macos/result.json"
Checks:
- Independently verify Developer ID application and installer signatures, accepted notarization/stapling, exact source/profile/SBOM/file hashes and installed readback; the installer cannot trust a key supplied only by its own payload.
- A clean macOS 27 Apple Silicon session launches SwarmUI from Finder, Spotlight and Dock, with the 28c integration available when supported; macOS 26 base-host use remains operational where advertised. Host-only startup neither installs nor requires QEMU/GPU/model downloads.
- Failed/repeated installation leaves the previous usable version and external state/evidence intact; explicit rollback and receipt-bound uninstall remove owned code/registration and only installer-owned service enrollment without deleting user data or credentials by default.
Deliverables: Reproducible signed/notarized `.pkg`, installer manifest, native launch and lifecycle test reports, and public Mac install/upgrade/removal guidance.
Title/ID: m28g-pypi-1.2.0-publication
Milestone: 28g / m28g-pypi-1.2.0-publication
Status: In Progress — distribution source is prepared; upload requires the accepted release tag and owner-approved publication.
Goal: Publish the matching Cohesix Python SDK wheel and source distribution on PyPI as stable `1.2.0`.
Inputs: Exact accepted Release B source and `v1.2.0` tag; compiler-selected Python inventory; registered `cohesix` PyPI trusted publisher and protected GitHub `pypi` environment; release-owner approval packet.
Changes:
- tools/cohesix-py/README.md and public Python guidance — show the matching pre-release install command and selected source links.
- .github/workflows/release-pypi.yml — build only the annotated Release B tag after verifying it is on main, inspect wheel and sdist contents and metadata, retain exact SHA-256 handoff bytes, then publish through reviewer-gated OIDC. Refuse a partial or different existing PyPI version.
Commands: Validate workflow syntax and permissions; build `scripts/install/build_python_package.py` from the selected inventory; check PEP 440 project/wheel/sdist alignment, Twine metadata and isolated install/CLI smoke; inspect the GitHub artifact and PyPI trusted publisher before approving and dispatching the exact tag; independently compare public PyPI file digests after upload.
Checks: Both PyPI distributions carry `1.2.0`, come from the same approved tagged source as the native release, and have public hashes matching the reviewed workflow artifact. A prepared workflow or local wheel alone is not PyPI publication.
Deliverables: Reviewed trusted-publishing workflow, approved distribution handoff and verified public `1.2.0` PyPI files and provenance.
Title/ID: m28g-ubuntu-arm64-native-installer
Milestone: 28g / m28g-ubuntu-arm64-native-installer
Goal: Install the exact Release B host candidate through Ubuntu ARM64 packages with GNOME launch and headless operation.
Inputs: Accepted 27e Linux signed host/desktop profiles; exact 28–28f candidate; scripts/install/; scripts/release_bundle.sh; selected JetPack 7.2.1 / L4T 39.2.1 ARM64 dependency and service contracts.
Changes:
- scripts/install/build_ubuntu_arm64_deb.py + packaging/debian/** + scripts/release_bundle.sh + scripts/setup_environment.sh — produce versioned controller and optional SwarmUI `.deb` packages from the compiler-registered payload, offline Python/NeMo kit and selected Linux assets without mandatory QEMU setup; declare release-specific dependencies and a separately verifiable publisher identity for downloaded packages without adding a distribution service. The dedicated publisher key is passphrase protected outside the checkout, and the native builder may read its passphrase from inherited standard input without a secret argument or environment value.
- scripts/install/qemu_compat.py + scripts/setup_environment.sh + skills/cohesix-ai-host-setup/** — use Ubuntu's `qemu-system-arm` package for an optional guest and verify the selected Linux KVM startup; offer `--headless` so server setup omits graphical packages. Retain separate boot/authenticated-client proof.
- packaging/debian/com.cohesix.swarmui.desktop + packaging/debian/icons/** + native app resource lookup — install the desktop entry and icon in freedesktop locations with a stable executable path and `Terminal=false`; keep WebKit/GTK dependencies out of the headless controller package.
- tests/test_ubuntu_arm64_installer.py + scripts/release_qualify.py + docs/TEST_PLAN.md + docs/QUICKSTART.md — add exact installed-payload, package-manager lifecycle and GNOME-launch checks on the selected JetPack reference, including 1.1.0-beta side-by-side migration.
Commands:
- python3 -m pytest -q tests/test_ubuntu_arm64_installer.py tests/test_host_package_stage.py tests/test_toolchain_setup.py tests/test_qemu_compat.py tests/test_release_qualify.py
- python3 scripts/install/build_ubuntu_arm64_deb.py --reference-config "${RELEASE_B_REFERENCE}" --out "${RELEASE_B_EVIDENCE}/installers/ubuntu-arm64"
- python3 scripts/release_qualify.py installer --reference-config "${RELEASE_B_REFERENCE}" --installer-manifest "${RELEASE_B_EVIDENCE}/installers/ubuntu-arm64/installers.json" --output "${RELEASE_B_EVIDENCE}/installers/ubuntu-arm64/result.json"
Checks:
- On JetPack 7.2.1 / L4T 39.2.1 ARM64, package-manager install resolves declared dependencies and installed bytes match the exact source/profile/SBOM; independent publisher trust covers each `.deb` and the embedded Cohesix signature is verified without self-enrollment.
- A GNOME user opens SwarmUI from application grid/search with its icon and a useful connect/doctor state, with no Terminal, inherited shell variables or checkout. The controller package installs and runs headlessly without GNOME/WebKit, QEMU or CUDA driver installation.
- Upgrade, failed/repeated install, rollback, remove and purge preserve or remove state/evidence/configuration only as explicitly documented; service enrollment and activation remain opt-in, and no maintainer script downloads models or copies credentials.
Deliverables: Reproducible Ubuntu ARM64 `.deb` set, installer manifest/publisher proof, GNOME and headless lifecycle reports, and public Linux install/upgrade/removal guidance.
Title/ID: m28g-debian-publisher-key-alignment
Milestone: 28g / m28g-debian-publisher-key-alignment; discovery in m28g-ubuntu-arm64-native-installer.
Status: In Progress — signed package and independent Jetson verification pending.
Goal: Give release readers the public key matching the private key used for the 1.2.0 Debian installer manifest.
Inputs: The tracked 2026 Debian publisher key, the dedicated passphrase-protected signing key, installer signing command and public install guidance.
Changes: Replace the tracked public key with the export of the selected publisher key; update its independently checkable fingerprint in the quickstart and release notes; retain the prior key probe as historical evidence. Keep the signing secret outside the checkout.
Commands: `gpg --show-keys --with-colons releases/cohesix-debian-publisher-2026.asc`; independently verify a detached signature with `gpgv` using only the tracked key; `.venv/bin/python -m pytest -q tests/test_ubuntu_arm64_installer.py tests/test_release_bundle.py`; `scripts/check-generated.sh`; build and qualify the exact JetPack 7.2.1 `.deb` set.
Checks: The public fingerprint equals the selected signer's fingerprint, independent verification accepts its detached signature and rejects the earlier key, and the exact signed installer manifest and package bytes pass the native installer gate. A key probe alone does not qualify a `.deb`.
Deliverables: One public verification key, aligned reader guidance and independently verified signed installer evidence at the accepted source.
Title/ID: m28g-host-clients-as-built-alignment
Milestone: 28g / m28g-host-clients-as-built-alignment
Goal: Align every shipped host tool, Python library and SwarmUI operation with the selected code and generated contracts as built.
Inputs: Accepted 28–28f implementation and selected manifests; exact Release B candidate and installed client packages; configs/generated/implementation_surface_inventory.json; 27e host tools/Python and 27f SwarmUI contracts; docs/HOST_TOOLS.md; docs/PYTHON_SUPPORT.md; docs/SWARMUI.md; docs/USERLAND_AND_CLI.md.
Changes:
- apps/{coh,cohsh,hive-gateway,gpu-bridge-host,host-sidecar-bridge,host-ticket-agent,cas-tool}/** + crates/coh-cli/src/** + their tests — review all seven shipped host executables against their selected implementation; reconcile commands, parser/help/manuals, inputs, authority, errors, status and recovery, and clearly gate any advertised operation lacking a reachable implementation.
- tools/cohesix-py/cohesix/** + tools/cohesix-py/tests/** — align typed requests, authentication, identity, bounded inputs, refusal and pending/terminal outcome mapping with the same selected operations in the installed wheel, including selected MLX/CUDA host choice, transfer refs and stage lineage.
- apps/swarmui/src/** + apps/swarmui/frontend/** + apps/swarmui/tests/** — align the `coh --ui-schema` handshake, visible controls, availability/disabled states, job identity and evidence views with the selected contracts in the installed app; fixture/replay content remains labelled as retained evidence.
- docs/HOST_TOOLS.md + docs/PYTHON_SUPPORT.md + docs/SWARMUI.md + docs/USERLAND_AND_CLI.md + docs/TEST_PLAN.md + release evidence index — align public help/examples and record the selected host-tool/Python/benchmark compatibility review.
Commands:
- cargo test --locked -p coh -p cohsh -p hive-gateway -p gpu-bridge-host -p host-sidecar-bridge -p host-ticket-agent -p cas-tool
- cargo test --locked -p swarmui --test workbench --test console_parity
- python3 -m pytest -q tools/cohesix-py/tests/test_parity.py tools/cohesix-py/tests/test_generated_contract.py tools/cohesix-py/tests/test_provider_registry.py tools/cohesix-py/tests/test_selected_jobs.py tools/cohesix-py/tests/test_playbooks.py tools/cohesix-py/tests/test_model_release.py
- cargo test --locked -p coh-rtc implementation_surface && python3 scripts/ci/check_implementation_surfaces.py --inventory configs/generated/implementation_surface_inventory.json
Checks:
- For each advertised selected capability, trace the generated inventory and implementation to installed CLI, Python and SwarmUI entry points where applicable; record supported, unavailable and deliberately client-specific surfaces with reasons. No client claims a selected capability solely from a fixture, planned task, stale package or documentation.
- Shared operations agree on admission/authority, validated inputs and bounds, native job identity, denial/error, cancellation, ambiguous or pending recovery, terminal outcome and evidence. Unsupported or disabled operations refuse visibly and consistently; SwarmUI resource resolution and `coh --ui-schema` match the installed binary without a source checkout.
- For an advertised mixed MLX/CUDA operation, Python and the protocol projections preserve selected provider/host and approved transfer boundaries, original stage identity and the shared verifier's outcome; no Python status, MCP tool result or A2A task state independently promotes success.
- Verify source/profile/generated-policy/package identity for the three installed client surfaces. The owner-evaluated full client walkthrough and focused contract tests support the 1.2.0 selection; component-native outcomes keep their original records.
Deliverables: Corrected shipped surfaces and manuals, focused client tests, owner walkthrough, and a host-tool/Python/benchmark compatibility record in the Release B evidence index. A separate raw capability matrix is optional extended qualification.
Title/ID: m28g-installation-and-integrated-adoption
Milestone: 28g / m28g-installation-and-integrated-adoption
Goal: Make CUDA, PEFT, Apple and NeMo journeys installable and operable from public instructions.
Inputs: Accepted 28–28f artifacts/evidence; both 28g native installer reports; 27e installation; 27f workbench; scripts/install/; docs/HOST_TOOLS.md; selected release matrix below.
Changes:
- scripts/install/{stage_host_package,stage_swarmui,build_python_package}.py + scripts/release_bundle.sh — bind the installed Mac/Linux packages, release-version-aligned Python/NeMo wheels, native Apple integration, client configs and recipes to one exact source/profile/hash inventory.
- apps/coh/src/doctor.rs + apps/swarmui/src/workbench.rs + docs/HOST_TOOLS.md + docs/PYTHON_SUPPORT.md — actionable capability/credential/storage/protocol/Apple diagnostics and one coherent job/evidence view.
- tests/test_host_package_stage.py + tests/test_python_package.py + tests/test_release_bundle.py + matrix/catalog — m28g-adoption-live for clean-install journeys, rollback/uninstall and a named evaluator walkthrough; explicit downloads and private-data/licence choices. For this sole-developer release, Lukas Bower may be the evaluator when recorded as owner-evaluated, without an independence claim. His written manual attestation may satisfy the qualitative walkthrough when its source and installed package identities are verified; record missing measurements explicitly and retain the separate native gates.
Commands:
- python3 -m pytest -q tests/test_host_package_stage.py tests/test_python_package.py tests/test_release_bundle.py
- cargo test --locked -p coh --lib doctor::
- cargo test --locked -p swarmui --lib
- scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --case m28g-adoption-live --reference-config "${M28G_ADOPTION_REFERENCE}" --host-profile mac-apple-m4-macos27 --state-dir "${M28G_EVIDENCE}/m28g-adoption-live"
Checks:
- The selected native component and owner-evaluated installed journeys retain their source, package and proof identities; no hidden credentials, terminal-only SwarmUI launch or developer-only setup is claimed in the walkthrough.
- A named person or agent completes clean installation and useful work; record identity, independence or owner-evaluated scope, assistance, steps/time/downloads and blockers against frozen adoption budgets when measured. Lukas Bower may evaluate this sole-developer release without an independence claim. His full manual PASS can close the qualitative adoption walkthrough with unrecorded metrics; it cannot establish numerical budget compliance or native outcomes.
- Install rollback/uninstall preserves declared user data, disables/removes only installer-owned service registration and retains external credentials unless the operator explicitly selects documented removal; no hidden model downloads or automatic loss of active job evidence.
Deliverables: Installable candidate, newcomer/client guides, exact distribution identities and source/package-bound owner manual adoption evidence.
Title/ID: m28g-a2a-catalogue-release-selection
Milestone: 28g / m28g-a2a-catalogue-release-selection; downstream discovery in m28g-release-b-qualification.
Status: Complete — the exact `b68a2c2a1a38` release preflight passed and both host archives include the generated A2A catalogue.
Goal: Ship the generated A2A catalogue with every Release B host archive so installed agent clients can inspect the same selected skills as the gateway.
Inputs: The exact 1.2.0 release inventory, compiler-generated MCP and A2A catalogues, and the canonical bundle preflight refusal for the omitted A2A file.
Changes: AI-assisted investigation traced the factory refusal to the missing inventory row. Select configs/generated/a2a_catalogue.json in configs/implementation_surfaces.toml; regenerate its inventory, host graph and dependent generated projections; add a focused release inventory assertion. Record the failed preflight and rebind affected release evidence to the repaired source.
Commands: .venv/bin/python -m pytest -q tests/test_release_bundle.py; scripts/check-generated.sh; scripts/release_bundle.sh --check-manifest with exact Mac, Linux and Pi production inputs; git diff --check.
Checks: The bundle factory accepts the exact generated file set and copies the A2A catalogue to both host archives with byte-bound manifests. MCP and A2A remain selected on QEMU and Pi. Regenerated graph/source bindings require renewed affected artifact checks; earlier target results retain their original identities.
Validation: 49 focused release/Python generated-contract tests, 16 cohesix-authority unit tests, generated consistency and git diff --check passed on the repair working tree. At `b68a2c2a1a38`, the exact-source bundle preflight and the Mac, Linux and Pi archive inventory checks passed; both host archives include the generated A2A catalogue.
Deliverables: Corrected release selection, regenerated contracts, focused test result and renewed exact-source candidate evidence.
Title/ID: m28g-release-b-qualification
Milestone: 28g / m28g-release-b-qualification
Goal: Qualify the selected 1.2.0 ecosystem release using the completed target, host, installer, component and owner-evaluated evidence.
Inputs: Exact `869737b03982` archive and installer set; native installer readback and strict five-part release result; accepted component reports; staged QEMU/Pi, SD, pressure and owner-adoption results; TEST_PLAN 1.2.0 selection.
Changes:
- scripts/release_qualify.py + tests/test_release_qualify.py — verify exact source/native-installer/installed-payload/profile/target bindings; a missing selected-gate result cannot promote.
- Existing component cases, focused protocol-control tests and docs/TEST_PLAN.md — retain actual live MCP/A2A/NeMo, native provider and four-effective-mode gateway observations at their original identities.
- docs/BENCHMARKS.md + M28g implementation record + release notes/status — retain measured results, owner-attested unmeasured adoption, exact evidence index and named release-owner approval binding.
Commands:
- python3 -m pytest -q tests/test_release_qualify.py tests/test_release_bundle.py
- cargo test --locked -p hive-gateway --test agent_protocol_controls
- scripts/ci/test_plan_run.sh --list
- scripts/ci/test_plan_run.sh --target qemu --state-dir "${RELEASE_B_EVIDENCE}/qemu"
- scripts/ci/test_plan_run.sh --target pi4 --state-dir "${RELEASE_B_EVIDENCE}/pi4"
Checks:
- The strict five-part verifier passes for the distributed archive and installer hashes; canonical QEMU/Pi staged, physical SD, native host, Jetson pressure, component-live and focused gateway-mode records pass at their stated source and proof class.
- Owner manual adoption attestation names the installed package hashes and full walkthrough. Numerical setup, download and first-job results remain unrecorded.
- Publication-only changes are reviewed against the qualified runtime source; only the named human release owner approves publication of the exact artifact set.
Deliverables: Qualified 1.2.0 artifact set, hash-bound evidence index and plain-English release notes.
Title/ID: m28g-production-tcp-release-proof
Milestone: 28g / m28g-production-tcp-release-proof; discovery in m28g-release-b-qualification.
Status: Complete — native Mac HVF and Jetson KVM strict-production TCP replays passed at `b68a2c2a1a38` with matching selected artifacts.
Goal: Bind each release archive to authenticated TCP from its own strict-production QEMU artifact while retaining the complete development-authority transport plan.
Inputs: The retained 4a469 Pi production Stage 03 refusal of legacy `/queen/ctl`; selected production manifests with `legacy_queen_ctl=false`; canonical native artifact and release factory contracts.
Changes: Give the production-safe base scripts a distinct catalog action and exact script-set check in the release factory. Refuse a development policy, missing default MCP/A2A or standing control, wrong target/group/action, partial script result, and a different artifact. Preserve the full Stage 03 matrix and production authority.
Commands: `bash -n scripts/cohsh/run_regression_batch.sh`; `.venv/bin/python -m pytest -q scripts/ci/test_run_regression_batch.py tests/test_release_inputs.py`; `scripts/ci/test_plan_catalog.py validate`; `scripts/check-generated.sh`; native strict-production smoke on Mac HVF and Jetson KVM.
Checks: Each native smoke boots and authenticates the exact production artifact, passes its fixed response matrix and nine safe scripts, and emits a retained base result with matching action, source, manifest, host and artifact identities. The full development Stage 03, production MCP/A2A live cases and physical Pi acceptance remain separate requirements.
Deliverables: Production TCP records usable by the canonical release factory, focused refusal tests, and explicit profile boundaries in the Test Plan and host guide.
Title/ID: m28g-linux-host-policy-selection
Milestone: 28g / m28g-linux-host-policy-selection; downstream discovery in m28g-production-tcp-release-proof.
Status: Complete — the `b68a2c2a1a38` Jetson native tool build recorded selected policy SHA-256 `f77a645d43347d50eaef1e832b1b729918d1818d1b7f603b4988928036cd321c`; the rebuilt `cohsh` and exact KVM TCP replay passed.
Goal: Build Linux host clients against the same selected production policy as their accepted KVM guest.
Inputs: The retained Jetson KVM production TCP attempt whose response matrix passed but `cohsh` refused the generated policy hash; selected production manifest; native builder and release factory provenance.
Changes: `scripts/linux_host_tools_sync.sh build-tools` accepts a selected manifest, transfers it and its referenced public CAS verification key with independent hashes outside the clean source archive, generates host policies and Python defaults from that profile, places the selected external policy files at their native default paths, checks the compiled `cohsh` against its selected policy, and records manifest/key/policy digests. The release factory forwards its selected manifest and refuses Linux provenance for another manifest. Focused tests and the host guide cover this binding.
Commands: `bash -n scripts/linux_host_tools_sync.sh scripts/release_bundle.sh`; `.venv/bin/python -m pytest -q tests/test_linux_host_tools_sync.py tests/test_release_bundle.py`; `scripts/check-generated.sh`; native Jetson ARM64 host-tool rebuild and strict-production KVM TCP replay with the selected manifest.
Checks: A missing or changed selected manifest or its public verification key fails before publication; the selected external policy digest equals the builder record and the native `cohsh` accepts it before packaging, then completes the fixed strict-production TCP script set from the KVM artifact. Failed attempts remain failures at their original identities; a new source-bound attempt is required.
Deliverables: Selected-manifest native host-tool provenance, passing or explicitly failed new KVM TCP result, and the corrected release-factory contract.
Title/ID: m28g-kvm-pressure-runner-portability
Milestone: 28g / m28g-kvm-pressure-runner-portability; downstream discovery in m28g-release-b-qualification, restoring the selected M26e Conditional B2 runner without reopening M26e runtime scope.
Status: Complete — the corrected collector passed exact-source Jetson KVM
medium and high pressure with 256 READY executable Workers, zero request
errors, strict control errors and no transient retries. The immutable host
replay validator reports PASS for both loads and the native fault evidence.
Goal: Let the canonical pressure runner select pinned Linux QEMU and AArch64 debugger tools, then verify the Linux KVM host-integration rows without treating its own invocation as a competing writer.
Inputs: scripts/m26e_qemu_pressure.sh; configs/host_integration_acceptance.toml; Conditional B2; exact-source Mac guest and Jetson KVM profile; retained failed preflight, toolchain and host-profile attempts.
Changes:
- scripts/m26e_qemu_pressure.sh — exclude only the runner's process ancestry from the existing active-process probe; preserve external writer and output-descriptor refusal. Accept an explicit AArch64 `nm` path when Linux GDB and `nm` use different target-triplet names.
- configs/host_integration_acceptance.toml and compiler-generated graph, provider and protocol projections — permit the three mandatory executable-Worker target rows on Linux AArch64; select that host profile explicitly in the KVM runner.
- tests/test_m26e_qemu_pressure_cli.py and tests/test_host_integration_run.py — exercise self/ancestor false matches, an unrelated active-process match, the documented `nm` option and exactly three Linux AArch64 target rows.
- docs/BENCHMARKS.md and docs/TEST_PLAN.md — document the pinned Linux GDB/`nm` selection, bounded stripped QEMU artifact and selected host profile.
- docs/audit/M28G_IMPLEMENTATION_RECORD.md — retain the failed attempts, focused tests and exact replay result without relabeling earlier pressure evidence.
Commands: bash -n scripts/m26e_qemu_pressure.sh; python3 -m pytest -q tests/test_m26e_qemu_pressure_cli.py tests/test_rest_perf_harness.py -k 'm26e_qemu_pressure or quiescent_probe'; canonical scripts/m26e_qemu_pressure.sh --reuse-artifacts on the selected Jetson KVM host.
Checks: Direct pinned QEMU selection passes quiescence only when no other writer is active; a real competing process or open output writer still blocks; selected GDB and `nm` both read AArch64 ELFs; Linux AArch64 receives only the three mandatory target-runtime rows, with no provider-live promotion; the native KVM replay retains its original source, guest and host identities.
Deliverables: Portable pressure preflight and a separate, exact-identity Jetson pressure record or an explicit failed gate.
Capability and extended-case matrix: Each recorded live result keeps its exact candidate/reference identities, case report and raw evidence. The focused 1.2.0 selection above identifies the release gate; rows below also describe optional extended qualifications. Repeat a journey only where a client, platform or configuration changes its contract. Protocol-control tests cover the four effective modes and generated master settings.
| Required row / owning case | Profile and clients | Deterministic acceptance / retained evidence |
|---|---|---|
User CUDA / m28a-workloads-live, m28a-recovery-live |
Pi Queen + Jetson GPU; installed CLI/Python and Mac-originated SwarmUI | Useful reference and independent adaptation, each advertised execution lane, device/output verification, bounded cancel/lost-response recovery; native IDs and signed outcomes. |
PEFT lifecycle / m28b-peft-live, m28b-serving-live |
Pi Queen + Jetson; installed training/import and real serving client | Both training and independent import, fixed held-out comparison, actual canary, rejected candidate, interrupted promotion and verified incumbent rollback. |
Weight distribution / m28b-weight-distribution-live when advertised |
Mac source, Pi Queen reference path when selected, and each qualified NVIDIA or MLX destination profile | Real weight at least 1 GiB, exact source and destination SHA-256, observed host payload route/byte count, bounded Queen references, interruption/resume under one identity, and separate activation evidence. Reference-only tests do not close this row. |
| Native Apple / focused M28c installed observations | Exact macOS 27/SDK/device/language/region; signed SwarmUI and user-created Shortcuts | Availability/signing evidence, Shortcuts admitted service action and durable result, scoped assistance; unavailable/disabled Intelligence preserves manual operations. |
Local Apple compute / M28c local workbench and m28c1-mlx-live |
Same supported Mac; pinned MLX/Metal model/data/runtime | M28c observes bounded local GPU train/infer/evaluate without admission. The later 28c1 case must prove admitted serve/canary/rollback and bounded cancellation/recovery before deployment claims. |
Ordinary protocols / m28d-mcp-live, m28e-a2a-live |
Standard named/versioned MCP client and A2A peer; Linux-hosted gateway/provider path without Apple | MCP-only and A2A-only complete selected real work; scoped discovery, denial, cancel and reconnect resolve native outcomes. |
| vMLX client composition / separate M28d/M28e compatibility records | Pinned installed vMLX app and model, configured MCP transport; named A2A peer using the selected vMLX model endpoint | vMLX MCP tool execution reaches admitted CUDA/PEFT work with original identity and refusal/recovery; vMLX-backed A2A peer delegates and reconnects without promoting model text or task state to a native outcome. Missing session or peer is recorded as blocked. |
Selected mixed MLX/CUDA / mixed subcases of m28d-mcp-live, m28e-a2a-live |
Supported Mac MLX and compatible NVIDIA CUDA host profiles when both providers are advertised; JetPack where applicable | Each protocol independently projects selected work that uses both providers with explicit host selection, bounded transfer, capacity refusal, original stage identities and verified outcome after disconnect; each advertised NVIDIA platform has its own live qualification. |
NeMo / m28f-nemo-install, m28f-nemo-live |
Clean pinned Toolkit host and configured model endpoint; Pi Queen and qualified NVIDIA CUDA host, JetPack where applicable; Apple absent | Native MCP CUDA and per-user A2A journeys using a real HF PEFT candidate, denied/failed/interrupted cases, task recovery and subject isolation, same-input direct comparison and reproducible configuration. |
| Protocol composition / focused 1.2.0 selection | MCP-only, A2A-only, both, neither in the real gateway process; separate live MCP and A2A component journeys | Focused endpoint/disabled-surface and master-override checks, with earlier live component identity, budget, refusal and recovery records retained at their original sources. |
Client as-built alignment / m28g-host-clients-as-built-alignment |
Installed host CLI tools, Python wheel and SwarmUI from the qualified packages | Generated-contract and focused client tests, installed package identity/readback, and the owner’s full client-composition walkthrough. State only the capabilities and journeys actually exercised. |
Mac installer / m28g-macos-native-installer |
Clean supported Apple Silicon Macs; signed .pkg and installed SwarmUI.app |
Publisher/notary and installed-file verification; Finder, Spotlight and Dock launch without Terminal; supported 1.1.0-beta migration, failed install, upgrade/rollback and uninstall with state/evidence retained. |
Linux installer / m28g-ubuntu-arm64-native-installer |
Clean JetPack 7.2.1 / L4T 39.2.1 ARM64 host; headless and GNOME .deb packages |
Publisher and installed-file verification; GNOME application grid/search launch without Terminal and headless controller use; dependencies, migration, upgrade/rollback, remove/purge and state/evidence behavior. |
Python index / m28g-pypi-1.2.0-publication |
Approved Release B tag and reviewer-gated trusted publisher | Public wheel and sdist version, source, metadata and SHA-256 match the approved exact distributions; isolated install and CLI smoke pass. |
Installation / m28g-adoption-live |
Native installed Mac and Linux host candidates; packaged Python/NeMo/native app | All three published journeys, GUI launch, explicit downloads, doctor remedies, rollback/uninstall and a named evaluator walkthrough. Lukas Bower may record a full owner-attested manual PASS bound to source and installed package receipts when measurements were not retained; numeric budgets remain unverified and must not be claimed. Native outcomes and integrated release cases remain separate. |
Release/target / m28g-release-b-qualification |
Exact assembled QEMU and physical Pi profiles plus supported host packages | Owner-selected 1.2.0 Test Plan gate, staged and physical evidence, native installer readback, Jetson pressure, focused protocol and component-live results, and approval-bound evidence index. |
Checks / definition of done for 1.2.0: The three portable archives,
Developer ID signed/notarized Mac .pkg and publisher-signed JetPack ARM64
.deb set match the strict five-part release verifier’s exact hashes. Native
package-manager receipts and installed-byte readback passed on Mac and the
Jetson reference. The selected Python and NeMo wheels are version 1.2.0.
Canonical QEMU and Pi Stages 01–05, the packaged physical Pi SD boot and TCP
qualification, Mac and Jetson host archive checks, and Jetson medium/high KVM
pressure passed at their recorded identities. The focused gateway test passed
all four effective modes; separate live MCP, A2A, NeMo, CUDA, PEFT and MLX
results retain their native/component scopes. Lukas Bower’s full manual
adoption walkthrough passed against the installed package receipts, with
steps, time and downloads unrecorded. The selected source and publication
delta pass the release-publication bridge, and the named human release owner
approves the assembled artifact hashes before public promotion. After the tag,
the PyPI workflow publishes and verifies the 1.2.0 SDK wheel and source
distribution; record that result separately from release acceptance.
Deferred milestones — preserved designs, separate activation
Milestones 29–43 retain the other ideas in this single build plan. None is a 28x gate or an automatic next implementation obligation. Activation requires a named user/engineering need, bounded remaining tasks and explicit owner instruction. Each expandable design inventory preserves earlier technical constraints, original task IDs and former-number references resolved by the ownership map, not a competing live roadmap.
Retain working behaviour and evidence. Reuse requirements already satisfied by 28x rather than repeat them. Selected-path safety/correctness/recovery defects remain repairs in their actual owner; deferral cannot waive their standards.
Milestone 29 — Extended Formal Assurance and NIST Evidence
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain the claim register, proof-carrying manifest witnesses, bounded Secure9P/HAL/resource checks, state-machine models, CI proof evidence and NIST/OSCAL assessment. Select work for a named assurance claim or consequential defect class; narrow checks required by shipped 28x remain in 28, not here.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 28; current owner 29
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Status: Planned — after the 27g release; preserve existing implementation and evidence.
Delivery posture: Implement all listed assurance deliverables: claim register, generated witnesses, Secure9P/HAL/resource checks, TLA+/PlusCal models, bounded checking, restricted policy IR, CI verification, and NIST mapping. Each claim retains its exact proof class and evidence; a subset cannot close the milestone.
Why now (assurance): 26e supplies the accepted topology. This milestone proves bounded manifest, Secure9P/NineDoor, HAL ABI, grant, confinement, and replay claims; it does not claim whole-OS or hardware correctness. 29 storage work extends the baseline only after matching evidence and is not a base prerequisite.
As-built alignment note: Compiler and runtime verification hooks exist, but not Cohesix machine-checked proofs, generated witnesses, TLA+/Kani/Miri coverage, or CI bindings sufficient for these claims. Accepted evidence must precede formal-verification claims.
Non-negotiable constraints
- No proof claim may exceed the checked artifact. QEMU proof, Pi 4 hardware evidence, static analysis, bounded model checking, TLA+ state exploration, and inherited seL4 kernel assumptions must remain separate.
- Do not claim full seL4-style refinement proof from Cohesix spec to binary unless that proof exists. The accepted claim for this milestone is bounded, machine-checked verification of selected Cohesix contracts plus explicit assumptions.
- Later milestones may cite 28 only through named claim ids and evidence classes. A downstream production, semantic-extraction, AI, inference, MCP/A2A, or AWS task must state whether it depends on inherited seL4 assumptions, Cohesix static/generated checks, bounded model checks, state-model exploration, QEMU/staged evidence, fresh Pi 4 evidence, host-provider evidence, or target-specific AWS evidence. Importing a proof or assurance artifact into a semantic object, Context Capsule, or inference receipt never strengthens its original evidence class.
- Formal models must describe generated/as-built interfaces, not desired future behavior. If a model and generated manifest disagree, the fix is IR/codegen/docs alignment, not weakening the model.
- Verification tooling must be deterministic on macOS ARM64 and CI-friendly; heavyweight tools may be optional locally only if CI has a bounded equivalent or checked artifact.
- No new runtime protocols, namespace roots, ticket semantics, or HAL bypasses are permitted under the banner of verification.
- Verification witnesses are generated artifacts or generated-adjacent evidence; they must not become a hand-maintained second source of truth.
- Physical Pi 4 hardware behavior remains evidence-based. Formal verification can prove the admission/resource/ABI contracts that precede hardware execution, not that a device actually behaves correctly on the board.
- Cohesix checks over MCS manifests, admission arithmetic, Reply/donation lifecycles, and timeout policy must not be described as upstream AArch64 or SMP+MCS kernel verification. The selected architecture remains outside the tag-pinned verified configuration unless upstream proof coverage says otherwise for the exact build.
Prerequisite
- Completed 27g assembled release provides the selected baseline; verification does not gate that earlier release.
- Milestone 26e, including
m26e-mcs-smp-target-acceptance, completed so witnesses describe the one accepted SMP+MCS QEMU/Pi task topology rather than a hypothetical or dual-scheduler design. - Milestone 29 supplies new storage-runtime proof as part of 29, using the complete 28 witness/verifier contract. It is not a dependency of the baseline 28 implementation; non-persistent profiles make no persistence claims.
- Milestones 26a and 26b, plus Milestones 26c and 26d, completed or explicitly scoped where their artifacts are inputs to the proof surface: driver-task substrate, HAL admission, isolated runtime descriptors, 26b benchmark evidence, target-qualified tests, and refreshed seL4 baseline evidence.
Goal
Establish a machine-checkable verification baseline for the highest-value Cohesix contracts:
- manifest/compiler invariants and generated proof witnesses,
- Secure9P codec/session/path/fid/append-only bounds,
- ticket, namespace, and role confinement,
- HAL-only hardware authority and driver-task resource admission,
- pointer-free, bounded Pi 4 driver-task ABI descriptors,
- selected Queen/Worker, policy, audit, replay, and persistence state machines,
- MCS scheduling-context/core ownership, offline admission, Reply/donation return, timeout, cancellation, fault, and revoke invariants,
- explicit proof assumptions, residual gaps, and non-claims,
- a claim ladder that downstream milestones can cite without collapsing static proof, model checking, QEMU evidence, Pi 4 evidence, and AWS target evidence into one assurance label.
- a version-pinned NIST SP 800-53 LOW assessment layer that consumes named Cohesix claims and test-plan evidence without presenting a crosswalk as certification.
- a restricted policy-IR proof foundation whose accepted fragment, consistency/non-vacuity checks, generated solver/evaluator correspondence, verifier identity, and proof terminology can be consumed by Milestone 28c without issuing runtime authority.
Completion requires all eleven goals and every listed task/check. Model exploration remains bounded by the named claims. Milestone 29 owns proofs for its new storage runtime, and 31 owns AWS-specific evidence; 28 supplies their shared witness/verifier contract without depending on future target code.
Deliverables
A) Verification claim register
- Add
docs/FORMAL_VERIFICATION.mdas the canonical register of checked claims, proof assumptions, trusted bases, non-claims, and residual gaps. - Distinguish:
- inherited upstream seL4 assumptions,
- Rust type/memory-safety assumptions,
- Cohesix static checks,
- bounded model-checking results,
- state-model exploration results,
- QEMU/staged evidence,
- fresh Pi 4 hardware evidence.
- Define allowed external wording for Cohesix assurance claims so release docs, audit reports, and operator utilities do not overstate proof scope.
- Define a stable claim-ladder vocabulary and claim-id format. Each claim records
claim_id,evidence_class,trusted_base,assumption_ref,artifact_ref,target_profile, andnon_claimfields so later milestones can cite exactly what was proven and what remains evidence-based.
B) Proof-carrying manifest witnesses
- Extend
coh-rtcto emit a deterministic verification witness for each resolved manifest profile, including:- Secure9P
msize, walk-depth, path, and fid constraints, - namespace roots, mutability, role permissions, and append-only controls,
- ticket inventory and role/path/verb authority matrix,
- HAL storage, MMIO, DMA, IRQ, and driver-task resource grants,
- driver-image ABI bounds, runtime resource windows, and non-overlap checks,
- persistence bounds and data-at-rest identity binding,
- scheduling-context/core ownership, budget/period/refills, per-core admitted demand and reserves, Reply-object cardinality, donation depth, timeout routing, overrun policy, and consumed-time evidence,
- claim ids and evidence-class tags consumed by downstream production, semantic-object, AI, inference, MCP/A2A, Pi 4, and AWS milestone gates.
- Secure9P
- Add a verifier that checks the witness against the resolved manifest and generated Rust tables, failing closed on drift.
- Witnesses must be regenerated from IR; hand-editing witness output is invalid.
C) Secure9P formal and bounded verification
- Add bounded proofs for
secure9p-codecandsecure9p-corecovering:- length-prefix and
msizehandling, - walk depth and path rejection (
.., invalid UTF-8, NUL where rejected), - fid creation, clunk retirement, and no reuse after clunk,
- tag/window/queue limits,
- append-only read/write bound helpers,
- deterministic error mapping for malformed frames.
- length-prefix and
- Use Kani or an equivalent bounded model checker where practical, plus fuzz corpus regression for parser edge cases.
- Keep existing Rust tests as regression evidence; proofs do not replace fixtures.
D) HAL and driver-task authority checks
- Add a static authority checker that rejects direct physical-address discovery, device-untyped retyping, DMA allocation/publish, IRQ binding, cache maintenance, or ad-hoc MMIO outside approved HAL modules.
- Check that driver-task bootstrap grants only declared CSpace, VSpace, endpoint, notification, fault/timeout endpoint, Reply object, scheduling context, stack, IPC, ring, MMIO, DMA, shared-buffer, and IRQ resources from generated manifests; SchedControl remains root-owned.
- Check that driver tasks do not receive Secure9P authority, broad namespace state, ticket secrets, or catch-all
KernelHalauthority. - Verify
pi4-driver-abidescriptors are pointer-free, layout-stable, bounded, and incapable of representing overlapping undeclared resource windows.
E) State-machine models
- Add small TLA+/PlusCal or equivalent models for:
- Secure9P session/fid lifecycle,
- ticket issuance, use, revoke, and denial,
- Queen/Worker lifecycle and namespace visibility,
- policy apply/rollback and audit/replay ordering,
- persistence spool append/read/ack crash behavior,
- driver-task admission and fail-closed service turns,
- MCS Reply/donated-SC return across timeout, cancellation, fault, revoke, and task restart without cross-epoch reuse.
- Model outputs must map back to generated manifest fields and checked Rust fixtures. Models that cannot be tied to as-built fields are design notes, not verification closure.
F) CI verification gate and evidence archive
- Add
scripts/ci/verification_gate.shto run the deterministic verification subset:- generated-artifact drift guard,
- proof-witness generation and verification,
- Secure9P bounded proofs or CI-approved bounded substitutes,
- state-model checks at documented bounds,
- HAL/driver-task authority checker,
- fuzz corpus regression,
- existing Rust tests for touched proof surfaces.
- Emit evidence under
out/verification/<run-id>/with machine-readable summaries and human-readable logs. - Update
docs/TEST_PLAN.mdso formal verification augments, but does not replace, the staged Test Plan and hardware proof gates.
G) NIST assessment-evidence integrity
- Reintegrate
tools/security-nistas an assessment-evidence consumer of the verification claim register, generated manifest witnesses, staged Test Plan, and target-qualified evidence archive. It must not become an independent authority for runtime behavior or proof claims. - Pin the registry to the selected NIST SP 800-53, SP 800-53A, and SP 800-53B releases, including source provenance and digests. Use the official machine-readable OSCAL content to validate identifiers and LOW-baseline membership; builds and release checks must not depend on an unpinned live network fetch.
- Require the tailored registry to account for every selected LOW-baseline
control and enhancement with an implementation disposition of
implemented,inherited,planned, ornot_applicable, plus a separate assessment result ofsatisfied,failed, ornot_assessed. Record explicit tailoring rationale, implementation responsibility, and assessment methods. Absence is an error, not implicit tailoring. - Replace path-existence and documentation-phrase evidence with typed records that identify a verification claim id or Test Plan action, assessment objective, target/profile, manifest or image identity, result artifact, evidence class, and freshness rule. A generic smoke script or existing file cannot by itself satisfy multiple unrelated implemented controls.
- Preserve proof-layer separation: static checks, bounded model checking, QEMU,
Pi 4, host, and inherited-provider evidence are not interchangeable. Missing,
expired, wrong-profile, or identity-mismatched evidence produces
not_assessedor a failed objective without silently changing or validating the separately recorded implementation disposition. - Generate the human-readable NIST report and a machine-readable, OSCAL-compatible component/assessment-results projection from the same registry and reviewed run evidence. Generated reports must be regenerated and compared in CI and must state that the output is a tailored evidence index, not certification or authorization.
- Run fast registry/schema/report-drift checks on affected pull requests and a target-qualified assessment during scheduled or release verification. Physical-hardware objectives require fresh Pi 4 evidence only when the assessed claim requires hardware; routine host/QEMU changes must not fabricate or silently inherit that proof.
H) Restricted policy-IR proof foundation
- Define the accepted bounded policy fragment, policy consistency and non-vacuity checks, and generated solver/evaluator correspondence claims used by later runtime admission.
- Keep decision witnesses, explanation cores, and independently checkable proof artefacts as distinct evidence classes. Record verifier name/version, accepted checker, bounds, assumptions, and claim id for every proof claim.
- Fail CI deterministically when policy source, generated solver constraints, deterministic evaluator, test vectors, verifier identity, or checked artefacts drift.
- This foundation owns static policy and proof vocabulary only. It does not issue tickets, leases, provider actions, grants, or runtime decisions; Milestone 28c consumes it for exact per-intent admission.
Commands
scripts/check-generated.shcargo test -p coh-rtccargo test -p security-nistcargo test -p secure9p-codeccargo test -p secure9p-corecargo test -p pi4-driver-abiscripts/ci/verification_gate.sh
Checks (DoD)
coh-rtcemits verification witnesses for active QEMU and Pi 4 profiles, and the verifier proves they match generated Rust and resolved manifests.- Secure9P codec/core proofs or bounded checks pass for the documented contract set.
- HAL/static authority checker has no bypass findings outside approved HAL modules and documented test fixtures.
- Driver-task ABI/resource checks prove no undeclared resource windows, pointer-bearing descriptors, overlapping arenas, or broad authority grants.
- MCS witnesses and state models prove generated SC/core ownership, per-core admission totals/reserves, bounded donation depth, Reply return, timeout routing, and no donated-SC or Reply-object reuse across revoke/restart.
- State models run at documented bounds and any counterexample is either fixed or recorded as a blocker with a named later milestone.
docs/FORMAL_VERIFICATION.mdstates exact claims, assumptions, and non-claims, including that Pi 4 hardware behavior still requires fresh board evidence.- Verification evidence is reproducible and archived under
out/verification/<run-id>/. - The NIST LOW registry is complete for its pinned baseline, every positive assessment result resolves to current typed evidence for the exact claim/profile/identity, and the Markdown and machine-readable reports are deterministic and drift-checked.
- No NIST output upgrades a documentation phrase, file-existence check, stale run, QEMU result, inherited assertion, or unsigned measurement into stronger proof or a certification claim.
Compiler touchpoints
coh-rtcemits proof witnesses from the same IR used for generated Rust, docs snippets, policies, and manifests.- Manifest schema changes that affect authority, namespace layout, persistence, Secure9P bounds, or driver resources must update the witness schema and verifier in the same change.
- Generated docs may summarize witness contents, but canonical proof truth is the resolved manifest plus generated witness plus verifier output.
Task Breakdown
Title/ID: m28-claim-register
Goal: Define Cohesix formal-verification claims, assumptions, and non-claims before adding proof tooling.
Inputs: AGENTS.md, docs/BUILD_PLAN.md, docs/ARCHITECTURE.md, docs/SECURITY.md, docs/TEST_PLAN.md.
Changes:
- docs/FORMAL_VERIFICATION.md — proof scope, trusted bases, checked claims, non-claims, residual gaps, and acceptable release wording.
Commands:
- git diff --check docs/FORMAL_VERIFICATION.md docs/BUILD_PLAN.md
Checks:
- The document separates inherited seL4 assumptions, Cohesix machine checks, staged evidence, and Pi 4 hardware proof.
Deliverables:
- Canonical assurance-claim register for later verification tasks.
Title/ID: m28-proof-witness-ir
Goal: Generate and verify proof-carrying manifest witnesses from compiler IR.
Inputs: tools/coh-rtc, configs/root_task*.toml, apps/root-task/src/generated, configs/generated/.
Changes:
- tools/coh-rtc/src/verify.rs — witness schema and verifier.
- tools/coh-rtc/src/codegen/* — witness emission beside resolved manifests.
- docs/snippets/* — generated witness summaries where appropriate.
Commands:
- cargo test -p coh-rtc
- scripts/check-generated.sh
Checks:
- Witnesses match resolved manifests and generated Rust; hand-edited or stale witnesses fail closed.
Deliverables:
- Proof-carrying manifest witness pipeline for QEMU and Pi 4 profiles.
Title/ID: m28-secure9p-proofs
Goal: Add bounded machine checks for Secure9P codec/session invariants.
Inputs: crates/secure9p-codec, crates/secure9p-core, scripts/cohsh/*, docs/USERLAND_AND_CLI.md.
Changes:
- crates/secure9p-codec/proofs/ — bounded frame/decoder proof harnesses.
- crates/secure9p-core/proofs/ — fid/session/window/append-only proof harnesses.
- docs/FORMAL_VERIFICATION.md — Secure9P proof claim updates.
Commands:
- cargo test -p secure9p-codec
- cargo test -p secure9p-core
- scripts/ci/verification_gate.sh --secure9p-only
Checks:
- Secure9P red lines are machine-checked and regression fixtures still pass unchanged.
Deliverables:
- Reproducible Secure9P proof evidence.
Title/ID: m28-hal-authority-checker
Goal: Enforce HAL-only device authority and driver-task resource confinement statically.
Inputs: apps/root-task/src/hal, apps/root-task/src/cspace, apps/root-task/src/kernel.rs, crates/pi4-driver-abi.
Changes:
- tools/verify-cohesix/src/hal_authority.rs — static scanner/checker for HAL bypass and broad authority grants.
- crates/pi4-driver-abi/proofs/ — ABI layout/bounds checks.
Commands:
- cargo test -p pi4-driver-abi
- cargo run -p verify-cohesix -- hal-authority --manifest configs/generated/root_task_resolved.json
Checks:
- MMIO/DMA/IRQ/resource grants appear only through approved HAL paths; driver descriptors are pointer-free and bounded.
Deliverables:
- HAL and driver-task authority verification gate.
Title/ID: m28-state-models
Goal: Model and check selected Cohesix authority/state machines.
Inputs: Secure9P session semantics, ticket policy, worker lifecycle, policy/audit/replay, persistence spool, driver-task admission, and the accepted 26e MCS scheduling/IPC topology.
Changes:
- specs/secure9p_session.tla — session/fid lifecycle model.
- specs/ticket_authority.tla — issue/use/revoke/deny model.
- specs/driver_task_admission.tla — generated resource grant and fail-closed service model.
- specs/persistence_spool.tla — crash-safe append/read/ack model.
- specs/mcs_reply_donation.tla — SC/Reply ownership, timeout, cancel, fault, revoke, and restart model.
Commands:
- scripts/ci/verification_gate.sh --models-only
Checks:
- Models run at documented bounds and counterexamples are either fixed or recorded as blockers.
Deliverables:
- State-machine model evidence tied to generated Cohesix fields.
Title/ID: m28-verification-ci
Goal: Add the deterministic formal-verification gate to CI and the staged Test Plan.
Inputs: scripts/ci/, docs/TEST_PLAN.md, proof harnesses, witness verifier, HAL checker, model runner.
Changes:
- scripts/ci/verification_gate.sh — deterministic verification runner.
- docs/TEST_PLAN.md — formal-verification stage and evidence paths.
Commands:
- scripts/ci/verification_gate.sh
Checks:
- The gate emits stable evidence under `out/verification/<run-id>/` and fails closed on drift, proof failures, or unsupported proof claims.
Deliverables:
- CI-ready verification baseline that later milestones can cite.
Title/ID: m28-nist-assessment-evidence-integrity
Milestone: 28 / NIST assessment-evidence integrity
Goal: Reintegrate the dormant NIST harness as a version-pinned, target-qualified assessment-evidence gate over canonical Cohesix claims and Test Plan results.
Inputs: tools/security-nist, docs/nist/controls.toml, docs/nist/REPORT.md, docs/SECURITY_NIST_800_53.md, docs/FORMAL_VERIFICATION.md, configs/test_plan_actions.toml, scripts/ci/test_plan_run.sh, scripts/ci/verification_gate.sh, generated manifest witnesses, pinned official NIST SP 800-53/53A/53B and OSCAL release metadata.
Changes:
- tools/security-nist — validate pinned catalog/baseline provenance, complete tailored LOW-baseline accounting, typed assessment objectives, claim/Test Plan bindings, target/profile and manifest/image identity, evidence freshness, and deterministic Markdown plus OSCAL-compatible output; add unit and negative tests.
- docs/nist/controls.toml — add release metadata, tailoring rationale, implementation responsibility, assessment methods/objectives, typed evidence bindings, target classes, and freshness rules without making it a second source of generated Cohesix behavior.
- scripts/ci/verification_gate.sh + configs/test_plan_actions.toml — add fast structural/report-drift checks and scheduled/release target-qualified assessment actions with bounded archived evidence.
- docs/nist/REPORT.md — regenerate only from the registry and reviewed run artifacts, including explicit gaps, stale/unavailable evidence, non-claims, and the no-certification disclaimer.
- docs/SECURITY_NIST_800_53.md + docs/TEST_PLAN.md — document tailoring, assessment cadence, proof-class separation, inherited-control assumptions, report provenance, and the distinction between automated evidence and human review.
Commands:
- cargo test -p security-nist
- scripts/ci/verification_gate.sh --nist-only --state-dir out/verification/m28-nist
- scripts/check-generated.sh
Checks:
- Every control and enhancement in the pinned tailored LOW baseline is explicitly accounted for; unknown, duplicate, omitted, or release-mismatched identifiers fail closed.
- Every positive automated objective resolves to a passing named claim or Test Plan action for the exact target/profile and manifest/image identity within its freshness window.
- Missing, stale, wrong-profile, inherited-without-provider, documentation-only, and QEMU-for-hardware substitutions remain visible gaps and cannot produce an implemented assessment result.
- Consecutive report generation is byte-stable; committed Markdown and machine-readable outputs drift-fail in CI; tests cover malformed registries, stale artifacts, profile mismatches, incomplete baselines, and evidence-strength downgrades.
- Reports describe a tailored evidence assessment, never certification, accreditation, authorization, or proof beyond the underlying Cohesix claim.
Deliverables:
- Tested NIST assessment harness, complete version-pinned LOW registry, deterministic human and machine-readable reports, and archived target-qualified assessment evidence.
Title/ID: m28-policy-ir-proof-foundation
Milestone: 28 / restricted policy-IR proof foundation
Goal: Define and machine-check the bounded policy fragment and proof vocabulary that Milestone 28c will consume for runtime per-intent admission without issuing runtime authority in 28.
Inputs: tools/coh-rtc/src/{ir.rs,lib.rs,codegen/**}, docs/FORMAL_VERIFICATION.md, scripts/ci/verification_gate.sh, generated manifest witnesses, policy fixtures.
Changes:
- tools/coh-rtc/src/ir.rs + validation/codegen — accepted Boolean, bounded-integer, enum, registry-identifier, bounded-set, linear-comparison, Boolean-composition, and required-fact policy fragment plus deterministic canonicalization and rejection of unsupported constructs.
- verification tooling + canonical fixtures — policy consistency, non-vacuity, counterexample, solver/evaluator correspondence, verifier-version, and generated-output drift checks.
- docs/FORMAL_VERIFICATION.md + docs/TEST_PLAN.md — proof-versus-witness terminology, evidence classes, checked bounds, trusted checker, assumptions, non-claims, and deterministic CI failure contract.
Commands:
- cargo test -p coh-rtc
- scripts/ci/verification_gate.sh --policy-ir-only --state-dir out/verification/m28-policy-ir
- scripts/check-generated.sh
Checks:
- The accepted fragment and verifier identity are versioned; inconsistent, vacuous, unsupported, or drifted policies fail closed; generated solver constraints and deterministic evaluators pass canonical correspondence vectors.
- A decision witness, explanation core, and proof artefact are never conflated, and no 28 output can issue a runtime ticket, lease, provider action, or authority grant.
Deliverables:
- Checked policy-IR and proof-vocabulary foundation consumed by Milestone 28c per-intent admission.
Milestone 30 — Broader Providers, Federation, Deployment and Domain Workflows
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain the wider provider catalogue, enterprise identity, Kubernetes/CEL/DRA, MIG/DCGM/CUPTI, native deployment profiles, federation, portable evidence/exporters/SIEM, industrial protocols and domain playbooks. Qualify a named adopter workflow at a time. Existing CUDA/PEFT/Apple paths from 28a–28c are reused, not reimplemented.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Existing restoration remains unchanged: the retained
m28a-native-provider-discovery-and-actions launchd transitional-observation
repair stays narrowly Reopened for M27g only, with its existing deadline,
single-dispatch, identity checks and parser/native evidence obligations.
This renumbering adds no requirement to 27g and does not defer that repair.
Retained design inventory — former Milestone 28a; current owner 30
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Status: Planned — deferred breadth; existing implementation remains preserved.
The retained launchd observation defect is narrowly Reopened under
m28a-native-provider-discovery-and-actions for M27g restoration only.
Prerequisites: completed 27g and 28. This milestone extends the qualified 27b foundation, 27c recipes, 27d LoRA transaction and 27e packaging. The complete catalogue below belongs here, including Kubernetes/controllers/CEL/DRA, launchd/Xcode/codesign/notary/App Store Connect, Apple ML, MIG/DCGM/CUPTI, enterprise identity, FUSE, federation, exporters/SIEM, industrial providers, deployment shapes and all nine domain playbooks. Reuse working implementation. No item is required retroactively to close 27b–27g.
Delivery posture: Complete each broader provider/use-case conformance lane under its declared native owner. Foundation tasks below extend accepted 27b contracts to this broader catalogue; they do not recreate the executor, registry, verifier or recipe lifecycle. Selected CUDA/HF release acceptance is already owned by 27b–27g. Semantic, advanced AI/NeMo and general inference rows retain their later owner and explicit unavailable status until those owners qualify; 28a does not require those downstream workflows to close.
Why now (coexistence floor): 25g supplies host tickets and adapters; 27a makes writes attributable, replay-safe, fenced, durable, and audit-first. Before semantic, AI, inference, MCP/A2A, or namespace consumers depend on them, this milestone extends the accepted compiler-owned provider/action contract, live ecosystem conformance, and additional installable host bundles without expanding VM authority or dependencies.
Starting state: inspect current code and retained evidence before work. Local 27b implementation already includes native CUDA/systemd/Docker, signed causal evidence, scoped reads, identity, packaging, federation and field-bus work at differing proof levels. Preserve it and its original records. Missing broad conformance remains a task, not a reason to remove working behavior.
Extend the frozen 26e host-integration-dependency/v1 graph, not a parallel
catalog. 26e proves executable Worker control and fixture-backed GPU/PEFT
result-to-Worker receipts. Its worker-runtime release is required wherever a
use-case row names an executable Worker; it does not prove production providers,
data planes, or complete use cases.
Evidence inputs: accepted 26e/27/27a and 27b–27g records. Later VM restart persistence, production Worker binding, semantic and inference claims are qualified by their own owners; no such claim is required for this catalogue’s native/provider acceptance. Host restart recovery remains required here.
Goal Extend the accepted release coexistence contract to the broader catalogue:
- Extend the 26e integration dependency graph with one provider/action and integration-surface registry from compiler IR, and use it everywhere host-side actuation, semantic extraction, inference, or projection is described, validated, displayed, packaged, or exposed.
- Map enterprise, Kubernetes, and host identities into delegated Cohesix tickets without making an identity provider part of the VM TCB.
- Prove provider and external-executor conformance for the broader catalogue beyond the accepted reference slice: Jetson/network state, NVIDIA/CUDA/NVML, real bounded GPU workloads, PEFT/model registry, and the selected inference reload path. Additional providers are independently promoted only with a complete use case and do not enlarge the first release gate.
- Prove only the non-provider surfaces that complete the selected workflow:
direct console/
cohsh, REST/gateway, Python, SwarmUI, CAS, evidence/release, and the Jetson/network sidecars. Other generated surfaces remain explicitly unavailable until accepted. - Package gateway, host-ticket-agent, sidecar bridges, GPU bridge, evidence exporters, exact Worker-compatible schemas, and doctor checks as installable host-side bundles for realistic coexistence deployments.
- Turn every playbook selected for the reference release into a generated
preflight -> admit -> execute -> observe -> verify -> recoverworkflow with explicit node topology and named provider/data-plane owners. Unselected built-in playbooks are retained only as typed unavailable templates and cannot claim ecosystem support. The use-case evidence matrix prevents any public scenario, demo, or runbook from claiming an integration without its executable-Worker tier, external executor/data-plane owner, generated policy, tests, deployment instructions, failure recovery, and evidence-pack reconstruction. Generic schedule/lease/export writes never constitute workflow success. - Classify every ecosystem-facing read projection as public, delegated-ticket scoped, or admin-only before REST, MCP, A2A, FUSE, Python, or UI clients can expose it.
- Make the Cohesix ticket id the shared correlation key across native provider objects, logs, metrics, traces, artifacts, checkpoints, and receipts while preserving the rule that labels, annotations, environment fields, and provider metadata are correlation only and never authority.
- Give operators one generated ticket-centred lifecycle across providers:
plan -> apply -> watch -> explain -> verify -> recover, with evidence-pack reconstruction and compensation using the same provider/action graph rather than ecosystem-specific scripts or client-invented state. - Make each evidence pack a cross-system evidence graph keyed by one Cohesix
ticket. Offline, that ticket must answer: who requested the action; why it
was allowed; what actually ran; which resources it reserved and consumed;
whether it worked; and how an authorized operator can reproduce or reverse
it. Every answer resolves to validator-accepted records and immutable refs,
or to an explicit
missing|unavailable|unverifiedresult—never inference from file presence, native labels, or an apparently successful transcript.
Non-Goals (Explicit)
- No in-VM Kubernetes, Docker, systemd, CUDA/NVML, PEFT, NeMo, Prometheus, OpenTelemetry, DICOM, CCSDS, MODBUS, CAN, DNP3, IEC-104, or other ecosystem runtime.
- No POSIX compatibility layer, libc facade, process supervisor, shell command executor, package manager, or mutable general-purpose filesystem inside Cohesix.
- No direct host executor calls from REST, Python, MCP, A2A, FUSE, or UI code. Side effects still resolve to validated Cohesix control files or
/host/tickets/spec. - No provider-specific schema maintained only in docs, Python, OpenAPI, MCP, or an executor crate. Provider action truth comes from generated manifests and checked registry output.
- No write-capable OT/industry sidecar action until the corresponding read-only evidence, safety policy, failure mapping, and operator approval flow are proven.
- No identity claim, group, service account, or model prompt text is authorization by itself. All authority resolves to delegated Cohesix tickets and manifest-scoped actions.
- No Cohesix replacement for systemd supervision, the Docker Engine, Kubernetes scheduling/controllers, CUDA execution/profiling, PEFT training, NeMo orchestration, or their hot data planes. Native metadata carries correlation; only validated Cohesix ticket/grant and provider-result chains carry Cohesix authority.
Deliverables
Implementation boundary: all broader provider tasks below are required. Reuse accepted release contracts and verify additions on their exact host/profile; evidence cannot promote an unexercised provider or deployment.
1) Generated provider action and integration-surface registry
Purpose: Extend the 26e dependency graph so provider actions and all workflow-facing host surfaces have one compiler-owned contract instead of hand-aligned adapters.
Implementation requirements:
- Extend
coh-rtcwithproviders.*IR for:- provider id, version, enablement profile, action names, target selectors, dry-run/live mode, idempotency requirements, writer-epoch requirements, policy approval requirements, receipt schema, redaction rules, and evidence refs.
- a common provider-adapter lifecycle for
discover,preflight,execute,observe,verify,compensate, andexport_evidence, including the phase owner, timeout, idempotency/fencing rule, expected postcondition, compensation boundary, and typed unavailable behavior. Provider-specific code implements this generated contract; it cannot redefine lifecycle or receipt semantics. - canonical native identity and correlation fields, including provider object UID/generation or invocation/container/job identity, Cohesix ticket and evidence ids, native event cursor/range, artifact digest, selected evidence profile, and observation source/time/TTL. A mutable native label, annotation, environment field, or job name is never sufficient to validate authority or terminal success.
- admission metadata for every side-effecting action:
intent_schema_ref,required_fact_schema_ref,policy_id,decision_requirement,maximum_grant_scope,state_freshness_bound,reservation_or_recheck_mode, anddecision_receipt_schema_ref. Release A live actions explicitly generatedecision_requirement = unavailable,admission_mode = operator_approved, andoperator_approval_required = true; read-only/non-consequential actions may generatedecision_requirement = not_required. Later 28c governed actions generate that owner’s exact requirement when implemented; 28a qualifies operator-approved actions without inventing admission evidence. Callers cannot select or weaken any posture. - supported and selected
observe|recommend|enforcegovernance modes, authority/credential custodian, bypass posture, failure/fallback posture, shadow-evidence requirement, and the exact generated decision/grant/receipt contracts used by each mode. Evidence mode and governance mode remain orthogonal: a live observer is not an enforcing authority. - broader families:
systemd,launchd,docker,k8s,nvidia,cuda,nvml,mig,apple_ml,jetson,network,gpu.lease,gpu.workload,peft,model_registry,mac_release,endpoint_compliance,siem,prometheus,otel,modbus,dnp3,can,iec104,dicom, andccsds. - optional future families, including semantic extractors/stores and inference gateways/providers, may be reserved but must generate unavailable status until their owning Milestone 28b or 28f implementation and tests exist.
- Extend the same IR with
integration_surfaces.*records for:direct_console,cohsh,coh,host_ticket_agent,hive_gateway,rest,fuse_direct,fuse_rest,python_sdk,swarmui,federation,fleet,gpu_bridge,host_sidecar,cas,evidence,release_bundle,siem,prometheus,otel,jetson, andnetwork;- surface owner, transport/topology, read/write posture, required provider actions, required Worker roles and evidence tier, identity/secret requirements, durability owner, package artifacts, conformance runner, and explicit
live,fixture,mock,dry_run,disabled,missing, orunknownobserved mode; jetsonandnetworkhave real host-native read providers when selected: bounded Jetson board/JetPack/power/thermal/clock/CUDA observations and bounded macOS/Linux interface/link/address/route/error-counter snapshots. Unsupported hosts return typed unavailable; no-op success is prohibited.
- Each 27b record extends a stable 26e integration row and preserves its
integration_id; a provider or surface may not silently replace, rename, or weaken the 26e role-required receipt rows. - Generate or check the registry for:
host-ticket-agentvalidators/executors,cohandcohshhost-tool help,- Python SDK integration defaults,
- OpenAPI/REST docs,
- later semantic extractor/object schemas, inference compatibility/provider profiles, MCP tool schemas, and A2A skill schemas,
- docs snippets and test fixtures.
- Generate a language-neutral provider-adapter ABI/conformance vector set plus the Rust and Python bindings required by selected profiles. Kubernetes or other ecosystem-native controllers may consume generated schemas in their implementation language, but no independently maintained action catalogue or receipt vocabulary is permitted.
- Reject provider actions with free-form shell commands, arbitrary host paths, raw provider credentials, unbounded payloads, or target grammars that cannot be validated before executor dispatch.
- Fail generation when a public scenario, playbook, demo, runbook, package, or host binary references an unregistered provider/surface, or when an enabled surface lacks an exact package artifact and conformance owner.
2) Ecosystem conformance matrix
Purpose: Distinguish real coexistence from mock-only or aspirational support.
Implementation requirements:
- Add a checked matrix covering each enabled provider:
- supported host OS/profile,
- provider version bounds or unavailable state,
- auth mode,
- mock, dry-run, and live-safe coverage,
- negative cases,
- expected receipt fields,
- evidence-pack reconstruction path,
- failure and rollback behavior.
- Add the corresponding integration-surface columns for topology/transport, required Worker evidence tier, external executor or data-plane owner, identity/secrets, durability/retention, packaging, recovery/fail-safe behavior, and read projection.
- Minimum acceptance families:
- systemd status/start/stop/restart through the Manager D-Bus API, plus
selected bounded transient-unit execution, exact unit/invocation identity,
hardened resource/sandbox properties, structured journal correlation, and
observed service result;
systemctltext and command exit are not proof, - launchd status/start/stop/kickstart plus macOS package/service identity,
- Docker status/stop/restart through a version-negotiated Engine API, with digest-pinned image/container identity, ticket/evidence labels used only for correlation, filtered event capture, final inspect/health/exit/OOM verification, and bounded log refs. An optional Engine authorization plugin is independently classified and cannot claim enforcement for protocol paths the plugin does not intercept,
- Kubernetes cordon/drain/lease-sync/RBAC-to-ticket translation plus an
optional generated
CohesixActioncustom-resource/controller profile whose immutable spec and status subresource expose the same ticket lifecycle. Prefer native CEL admission for bounded object checks, use webhooks only where native policy is insufficient, and version-gate DRA/ResourceClaim or device-allocation support rather than making it a baseline dependency, - NVIDIA/CUDA/NVML physical and MIG inventory, parent/child topology and generation, GPU lease projection, separately from GPU execution/device isolation,
- bounded GPU workload submit/cancel/observe against an allowlisted host CUDA executor, with exact physical/MIG lease binding and no arbitrary shell/inline code. Use the ticket id as the native GPU job/correlation id; collect bounded NVML/CUDA observations everywhere supported, DCGM job/health data on profiles that provide it, and CUPTI/NVTX traces only in an explicit overhead-bounded deep-evidence profile,
- optional Apple-Silicon MPS/MLX/Metal provider/executor profiles for playbooks that explicitly select local Apple GPU execution; Mac controller/remote-CUDA profiles never probe local NVML,
- PEFT/model registry export/import/activate/rollback receipts, separately from training, evaluation, scanning, and inference-runtime reload,
- SIEM export,
- Prometheus/OpenTelemetry read-only export,
- live MODBUS/DNP3 provider conformance from reopened Milestone 18, with read-only defaults and separately approved write/control actions,
- CAN/IEC-104/DICOM/CCSDS explicitly staged as read-only or not-enabled until their bridge contracts land.
- systemd status/start/stop/restart through the Manager D-Bus API, plus
selected bounded transient-unit execution, exact unit/invocation identity,
hardened resource/sandbox properties, structured journal correlation, and
observed service result;
- Unsupported providers must produce deterministic
not_enabledornot_implementeddiagnostics; silent omission is not acceptable for documented use cases.
2a) External executor and data-plane conformance
Purpose: Ensure a receipt describes an observed external outcome, not merely a successful host-tool call.
Implementation requirements:
- Define generated conformance contracts for external executors/data planes that remain outside the Cohesix TCB:
gpu_executor: selected physical or MIG device identity and topology generation, memory and stream admission, lease epoch/TTL, revoke/preempt behavior, device/context isolation, allowlisted artifact/entrypoint, observed start/finish/failure/cancel, CAS output hashes, and correlation to the exact WorkerGpu/provider receipt;peft_pipeline: artifact export, training/fine-tuning handoff, evaluation thresholds, safety/format scan, content-addressed import, atomic activation, inference-runtime reload/canary, and rollback, correlated to the exact WorkerLora receipt;service_executor: systemd/Docker/Kubernetes target identity, admission/fencing, observed terminal state, timeout, and recovery;federation_relay: WAL-before-forward, enforced timeout, non-evictable pending intent, target terminal receipt return, source correlation, and recovery after process restart.
- Provider discovery and publication are separate from execution. Live NVML/CUDA inventory,
/gpu/models, or a successful lease projection cannot satisfygpu_executor; local PEFT filesystem mutation cannot satisfy training, evaluation, scan, or runtime reload. - Production GPU workload actions are generated
submit|cancel|observerecords over the existing host-ticket authority. They accept bounded CAS/artifact and entrypoint references, never free-form commands or inline arbitrary PTX; directsubprocess.run,echo ok, vadd/matmul descriptor synthesis, and status breadcrumbs remain diagnostics/fixtures and cannot satisfy execution. - A use case may remain
integration_pattern,fixture,mock,dry_run, ornot_enabledwithout a reference executor. It may becomeproduction_provenonly when a named external executor/data-plane implementation, deployment profile, failure/recovery tests, and live evidence are shipped or explicitly supplied and accepted by the conformance runner. - Milestone 28b owns semantic object/extractor/capsule implementation and Milestone 27d owns the production PEFT/training/evaluation/reload transaction. Milestone 28f owns the compatible inference wire, provider adapters, and inference receipts. This milestone extends their common registry floor, system/GPU/provider conformance, federation closure, and the fail-closed classification used by every use case.
2b) Jetson Orin Nano live reference profile
Purpose: Make the physical-GPU and Jetson provider lanes executable on the current ARM64 edge reference without pretending that datacenter-only features exist on the device.
Implementation requirements:
- Add a generated
jetson-orin-nano-jp7host profile whose retained reference is Jetson Orin Nano 8GB, AArch64 Ubuntu 24.04, Jetson Linux/L4T 39.2.1, JetPack 7.2.1, CUDA 13.2.2, compute capability 8.7, and the exact installed NVIDIA package/runtime versions captured by conformance evidence. These values identify this reference, not open-ended compatibility bounds; another JetPack/L4T combination requires its own tested profile or typed unavailable status. - Treat Orin Nano memory as shared system/GPU memory. Discovery records total device-visible memory, current free memory, reserved host headroom, admitted bytes, and the observation time/TTL. Workload admission uses the bounded available budget, never the marketed 8GB module size or a stale inventory value.
- The Orin Nano reference has one physical CUDA device and no MIG, DLA, or PVA.
MIG discovery and execution must return generated
not_supportedfor this profile and cannot block the physical-GPU lane or produce MIG evidence. DLA and PVA are not GPU-workload fallbacks. - NVML feature limitations are expected on this profile. Inventory and doctor must exercise the deterministic NVML-to-CUDA fallback and still report exact driver/runtime, memory, SM count, and device identity. CUDA 13 sonames and the unversioned toolkit symlink must be covered without removing older supported CUDA profiles.
- Record read-only Jetson board identity, L4T/JetPack package versions, active
power mode, clocks, throttling/thermal state, kernel, NVIDIA container
runtime, and NVMe-backed model/cache/runtime roots. Conformance must not
change
nvpmodel, force clocks, restart networking/VNC, or reboot the host unless a separately selected disruptive test profile explicitly authorizes and restores that state. - Run real bounded vector-add and matrix-multiply references from NVMe-backed CAS/build storage. Live negative coverage includes wrong-device, over-budget memory admission, timeout, cancel, revoke, bridge restart, stale inventory, and output-hash mismatch. It must not deliberately exhaust the Nano’s shared RAM; CUDA OOM mapping uses an isolated memory-capped child or deterministic fault injection, while the live oversized request is rejected before allocation.
- Keep native-process and NVIDIA-container execution as separate provider
observations. A selected container lane pins the image digest and proves GPU
access through the installed NVIDIA Container Runtime; container presence or
docker infoalone is not CUDA execution evidence.
3) Read visibility classification
Purpose: Ensure read-only projections do not leak cross-caller state.
Implementation requirements:
- Generate or check a visibility class for every provider, evidence, ticket, audit, replay, telemetry, and
/procread exposed to REST, Python, FUSE, UI, later MCP, or later A2A surfaces:publicfor non-sensitive version/capability summaries,ticket_scopedfor caller-owned tickets, receipts, provider status, run/checkpoint state, and evidence refs,admin_onlyfor global provider state, deadletters, audit/replay internals, identity-mapping diagnostics, and raw conformance snapshots.
- Read-only REST compatibility mode may remain gateway-role scoped only for paths explicitly classified as public or admin-only under the configured gateway role. Ticket-scoped reads require delegated identity before they can be exposed through multi-caller surfaces.
- Negative tests must prove a caller cannot read another caller’s host tickets, provider receipts, evidence artifacts, task state, or identity-mapping diagnostics through REST, Python, FUSE, MCP, A2A, or UI projections.
4) Enterprise identity and subject mapping
Purpose: Let existing identity systems coexist with Cohesix without entering the VM TCB.
Implementation requirements:
- Add host-side subject mappers for OIDC/JWT claims, SPIFFE IDs, Kubernetes service accounts/RBAC, and local host identities where enabled.
- Mappers produce delegated Cohesix ticket requests or ticket references; they do not mint authority outside the existing Cohesix ticket rules.
- Generated policy defines accepted issuer/audience/subject/group mappings, TTL bounds, role scopes, provider action scopes, and audit subject normalization.
- Forged, expired, overbroad, wrong-audience, or unmapped claims fail before any mutation reaches REST,
/queen/ctl, or/host/tickets/spec.
5) Packaging and deployment profiles
Purpose: Make coexistence deployable without bespoke host assembly.
Implementation requirements:
- Add installable host-side profiles for:
- local macOS operator,
- Linux/systemd edge node,
- GPU host/Jetson-compatible host sidecar mode,
- Kubernetes-adjacent gateway/agent deployment using Helm, Kustomize, or plain YAML.
- Each profile has an exact generated artifact manifest rather than a non-empty-directory check. As applicable it names
coh,cohsh,hive-gateway,host-ticket-agent,host-sidecar-bridge,sidecar-bus,gpu-bridge-host, FUSE helpers, CAS/evidence/export tools, Python extras, OpenAPI, generated provider/integration registries, service manifests, and doctor checks; a selected missing or wrong-version artifact fails packaging. - Each artifact is checked for expected type, target architecture, version, digest, feature/provider registry, and signature/SBOM membership; unexpected files are rejected. Python ships from a clean wheel/sdist manifest rather than a recursive source-tree copy. Private fixture keys, placeholder tokens, mock-only data, compiled stub binaries, and unregistered executables are forbidden.
- Systemd units, launchd examples, container manifests, and Kubernetes manifests must run with least privilege, explicit secret refs, loopback-by-default network posture, and documented non-loopback risk overrides.
- FUSE packages must prove the canonical
/shard/<label>/worker/<id>/...namespace through both direct and REST backends on each supported host; a legacy/workerallowlist or documented macOS writeEINVALis not production acceptance. - Kubernetes packages must define service-account/RBAC mapping, secret refs, readiness/liveness, disruption/restart behavior, writer fencing, and exactly-once ticket recovery; systemd and container packages must provide equivalent identity, secret, restart, and state-directory ownership.
- Selected systemd packages use the Manager D-Bus API and hardened persistent or
transient units with explicit credential, device, filesystem, network,
memory/CPU/runtime, notification/watchdog, and journal-correlation posture.
Selected Docker packages use API-version negotiation and least-privilege
socket/proxy access; selected Kubernetes packages ship generated CRD,
controller, status/condition, CEL policy, RBAC, and
kubectl-plugin assets only when that provider row is independently promoted. - Hardened units/manifests exist for every selected gateway, ticket agent, GPU bridge/executor, sidecar, bus provider, and exporter; the current single minimally configured gateway unit cannot satisfy a deployment profile.
- Offline release documentation must not depend on CDN assets. The OpenAPI document and any Swagger/viewer assets are bundled or the offline viewer is disabled with a deterministic local alternative.
coh doctorreports installed provider status, missing optional providers, native API/version and capability negotiation, auth configuration, ticket scope, registry version, evidence export availability, and packaging drift.
6) Observability and compliance projections
Purpose: Fit existing monitoring/compliance systems without replacing them.
Implementation requirements:
- Extend the accepted 27b schema-versioned evidence/receipt validator shared by Rust host tools, the Python SDK, SwarmUI, release checks, CI, and exporters. It verifies the evidence manifest, file hashes, signatures/attestations when configured, identity and manifest bindings, sequence/epoch/TTL, chronology, and the ticket -> admission -> Worker/provider/executor -> terminal-result graph. File presence, non-zero size, a local command transcript, or a client-created JSON object cannot satisfy an authoritative receipt or evidence check.
- Prometheus and OpenTelemetry exporters are host-side read-only projections from
/proc, audit, replay, telemetry, provider receipts, and evidence-pack summaries. - SIEM exports remain bounded, redacted, schema-versioned JSONL/NDJSON with stable field names.
- Exporters consume only records accepted by the shared validator and preserve source identity, cursor, registry/schema version, and authoritative/non- authoritative classification. Malformed, unverifiable, stale, or partially correlated records are rejected or emitted to a bounded diagnostic lane, never silently upgraded.
- SIEM delivery has a generated field allowlist and redaction/hash policy plus a durable bounded cursor/WAL, TLS and credential references, retry/backoff, backpressure, deadletter handling, and destination acknowledgement receipts. A copied local file is fixture evidence, not live SIEM delivery proof.
- Exporters must not expose raw tickets, ticket payloads, secret refs, provider credentials, large payloads, PHI, model weights, gradients, or prompt transcripts unless a documented profile explicitly authorizes the field and redaction policy.
- Evidence packs include provider registry version, conformance matrix snapshot, identity-mapping decision refs, packaging profile, exporter schema version, and provider receipt correlation.
- Preserve the deterministic directory pack, but make its manifest a bounded causal evidence graph over intent, fact snapshot, decision/approval, grant, native execution object, observations, verification, terminal receipt, and compensation/recovery. Large logs, traces, checkpoints, model artifacts, and native event exports remain in NVMe-backed CAS or configured object storage; the pack carries hashes, bounded summaries, cursors, and durable refs.
- Define generated evidence profiles such as
standard,incident,performance, anddeep_gpu. A provider cannot silently escalate capture cost or data sensitivity. Optional host-side in-toto statements, SLSA provenance for genuine build actions only, OpenTelemetry spans, and CloudEvents are derived projections from validator-accepted graph records; they never replace the Cohesix receipt or become authority.
7) OT and industry sidecar staging
Purpose: Keep industrial/health/science integrations as host-side bridges with explicit safety posture.
Implementation requirements:
- MODBUS and DNP3 use the real host-only codecs, transports, durable acknowledgement-aware spool, target maps, and safety allowlists delivered by reopened Milestone 18; 28a registers, packages, and proves those exact implementations instead of adding read-only aliases or a second bridge.
- CAN, IEC-104, DICOM, and CCSDS adapters remain host-side sidecars only and
stay explicitly
not_implementeduntil their real bounded bridge contract, package, and conformance lane land. - Read-only inventory/status/event capture must land before write/control actions for each provider family.
- Any write-capable action requires a separate provider action, explicit policy approval, target grammar, safety interlock description, dry-run fixture, live-safe refusal case, and evidence-pack reconstruction.
- DICOM and other sensitive-domain adapters must default to metadata and evidence refs only; raw PHI or large payload publication is disabled unless a later profile explicitly approves the redaction and retention model.
8) Use-case evidence matrix and release gate
Purpose: Prevent documentation from outrunning implementation.
Implementation requirements:
- Generate stable
use_case_idrows and check every public claim source, includingREADME.md,docs/USE_CASES.md,docs/HOST_TOOLS.md,docs/GPU_NODES.md,docs/PYTHON_SUPPORT.md,docs/HOST_API.md,docs/INTERFACES.md,docs/API_GUIDELINES.md,docs/ARCHITECTURE.md,docs/SECURITY.md,docs/TEST_PLAN.md, every post-Milestone-24 activity/runbook in this plan, release documentation, OpenAPI examples, and all built-in Python playbooks. - The initial inventory must include the six AI Hive scenarios; all nine built-in playbooks (
mac-release-factory,mac-private-peft-grid,mac-endpoint-compliance,jetson-traffic-safety,jetson-manufacturing-safety,jetson-critical-infra,mixed-closed-loop-ai-factory,mixed-medical-edge-ai, andmixed-logistics-digital-twin); the Security Evidence, Operator-First, LeJEPA, and Jetson Gesture Language activities; and Milestone 18 industrial patterns. - Classify each row as exactly one of
current_primitive,integration_pattern,workflow_template,mock_only,read_only,not_enabled,planned, orproduction_proven. A playbook that runs against a mock backend remainsworkflow_templateormock_only, neverproduction_proven. - Each row records milestone prerequisites; target/profile; Worker tier (
model_or_session,m26e_executable, orm28b_production_bundle); topology/transport; required host tools and exact package artifacts; provider actions and read surfaces; external executor/data-plane owner; authority/identity/secret refs; authority/credential custodian and bypass posture; supported and selected governance mode; shadow-evidence/promotion refs where selection or actuation is automated; durability/retention owner; rollback/recovery/fail-safe behavior; observability/evidence; and proof class. - Conditional validation is fail-closed: a row claiming an executable Worker requires accepted 26e target evidence; restart-persistent VM state requires Milestone 29; a production ticket/lease bound to a deployed Worker requires Milestone 28d; a semantic-context claim requires accepted Milestone 28b snapshot/capsule evidence; a PEFT training-to-runtime claim requires the Milestone 27d transaction; and an auditable compatible-inference claim requires accepted Milestone 28f provider/receipt evidence.
- Each production-proven row must link to:
- provider registry action(s),
- delegated authority requirement,
- package/deployment profile,
- identity mapping where relevant,
- observability/export surface,
- failure-mode fixture,
- evidence-pack reconstruction path.
- Every broader built-in playbook must reuse the accepted 27c generated staged lifecycle
with explicit
preflight,admit,execute,observe,verify, andrecovernodes; each node names its host, target hive, Worker role when any, provider action, external data-plane owner, input/output refs, timeout, cancellation/idempotency rule, and authoritative terminal evidence. The Mac controller, remote CUDA/Jetson nodes, optional local Apple GPU executor, and deployment-supplied domain applications must never be inferred from the machine running the CLI. Missing executors or applications yield typed unavailable and cannot be replaced by a successful generic schedule, lease, export, or probe. - Scan commands, YAML, unit files, examples, and runbooks for credentials or tokens in argv, manifests, logs, or evidence; use secret refs, protected files, stdin, or platform secret stores instead.
- Release gates fail if any public surface claims production coexistence without the exact integration graph rows, generated policy, executable-Worker tier, live external executor where required, tests, package manifest, identity/security posture, failure recovery, and evidence reconstruction.
9) Provider/exporter performance guard
Purpose: Prove provider conformance, read-visibility checks, identity mapping, and exporter projections remain bounded without turning coexistence validation into a full runtime throughput gate.
Implementation requirements:
- Add a targeted provider/exporter timing mode to the conformance runner for registry lookup, target validation, read-visibility refusal, identity-mapping refusal, receipt rendering, and Prometheus/OpenTelemetry/SIEM export over representative evidence packs.
- Report per-provider p50/p95, refusal counts, exporter row/byte counts, and artifact-size bounds.
- Compare against the accepted 26d rolling baseline only for shared REST/read status context; provider/exporter results are host-side coexistence evidence, not Pi hardware proof.
Commands
cargo test -p coh-rtccargo test -p host-ticket-agentcargo test -p cohcargo test -p cohshcargo test -p hive-gatewaycargo test -p gpu-bridge-host -p host-cuda -p host-sidecar-bridge -p sidecar-buspython -m pytest tools/cohesix-py/tests/test_integrations.pypython -m pytest tools/cohesix-py/tests/test_evidence_receipts.pypython -m pytest tools/cohesix-py/tests/test_playbooks.pyscripts/check-generated.shscripts/ci/check_host_integration_inventory.py --registry configs/generated/host_integration_dependency.jsonscripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28ascripts/ci/provider_conformance_run.sh --native-providers --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28a-nativescripts/ci/provider_conformance_run.sh --provider gpu.workload --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28a-gpu-workloadscripts/ci/provider_conformance_run.sh --provider jetson --host-profile jetson-orin-nano-jp7 --live-reference --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28a-jetson-orinscripts/ci/provider_conformance_run.sh --provider gpu.workload --host-profile jetson-orin-nano-jp7 --live-reference --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28a-jetson-gpuscripts/ci/provider_conformance_run.sh --perf-only --matrix configs/provider_conformance.toml --state-dir out/bench/m28a-provider-overheadscripts/ci/use_case_gate.sh --matrix configs/generated/use_case_evidence.json --state-dir out/use-case-gate/m28ascripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m28a-coexistence
Checks (Definition of Done)
- Broader provider actions, the accepted common adapter lifecycle, native identity/correlation fields, evidence profiles, and integration surfaces extend the 26e dependency graph; host-ticket-agent, REST/OpenAPI docs, FUSE, Python defaults, native controllers, SwarmUI, packages, host tools, and later MCP/A2A schema inputs cannot drift independently.
- Every side-effecting provider action carries the accepted 27b operator-approval and state-recheck contract covering intent/fact schemas, policy, decision requirement, maximum grant scope, freshness, reservation/recheck mode, and decision receipt; Rust, Python, REST, host-ticket-agent, later MCP/A2A, docs, tests, and packages consume the same metadata.
- Every REST/Python/FUSE/UI read projection is classified as public, ticket-scoped, or admin-only; cross-caller ticket, provider, evidence, audit, replay, and identity reads fail deterministic negative tests.
- Invalid provider target, action, argument, auth, writer epoch, idempotency key, dry-run/live-mode, or identity claim fails before executor dispatch.
- Every documented production provider has mock, dry-run, negative, and at least one live-safe conformance path or an explicit not-enabled status.
- GPU discovery/publication and GPU execution/device isolation are separately evidenced; PEFT filesystem lifecycle and the full export/train/evaluate/scan/import/activate/reload transaction are separately evidenced; neither may borrow the other’s proof.
- The
jetson-orin-nano-jp7lane proves the physical CUDA path with exact JetPack/L4T/package/device/power/thermal identity, bounded shared-memory admission, and deterministic NVML fallback. MIG/DLA/PVA remain typed unsupported, and no negative test intentionally exhausts shared system RAM or mutates the operator’s power, network, display, or boot state. - The selected Jetson systemd and Docker lanes bind immutable unit invocation, image/container, CUDA device/job, event cursor, output, and ticket/receipt identities. Kubernetes CRD/controller, webhook, DRA, DCGM, CUPTI, and Docker authorization-plugin capabilities remain independently versioned and cannot be inferred from adjacent provider presence.
- FUSE proves canonical
/shardbehavior and supported-host read/write/error semantics; federation proves WAL-before-forward, enforced timeout, retained pending intent, target terminal receipt return, and restart recovery; selected Jetson/network providers return real bounded host-native observations, while unsupported profiles return typed unavailable and no no-op can report success. - Kubernetes RBAC, OIDC/JWT, SPIFFE, and local-host subject mappings produce bounded delegated ticket scopes and deterministic audit lines.
- Packaging artifacts deploy only host-side tools and preserve loopback defaults, least privilege, secret references, and delegated-ticket write requirements.
- Prometheus/OpenTelemetry/CloudEvents/in-toto/SLSA/SIEM outputs are read-only, bounded, redacted, schema-versioned, source-correlated, and reconstructable from validator-accepted Cohesix evidence without becoming authority; SLSA is emitted only for real build actions, and live SIEM delivery additionally proves durable cursor/WAL, retry/backpressure/deadletter, TLS/credential refs, and destination acknowledgement.
- OT/industry sidecars remain host-only, read-only-first, and profile-gated; write-capable actions are refused unless explicitly admitted by provider policy and approval flow.
- Evidence packs retain their deterministic directory shape and include a validator-checked causal manifest over provider registry, conformance matrix, identity mapping, approval/decision/grant, native execution objects, observations, verification, provider/Worker receipts, recovery, packaging profile, exporter schemas, and content-addressed external refs.
- Given only an evidence pack and ticket id, the offline verifier answers who, why, what ran, reserved/observed resource use, verified outcome, and reproducibility/reversal for that action with exact source refs. A required missing or ambiguous causal node fails acceptance; reproduce and reverse are rendered as bounded authorized plans with exact artifacts, configuration, preconditions, idempotency state, and compensation target, never executed by opening or inspecting the pack.
- One generated ticket-centred host-tool journey can plan, apply, watch, explain, verify, recover, and export the same workflow without parsing native CLI text or inventing ecosystem-specific authority state.
- Every public scenario, playbook, demo, runbook, and example has one stable use-case row. A row can reach
production_provenonly when its Worker tier, provider/surface modes, external executor, package artifacts, authority, recovery, and live evidence all satisfy the generated graph. - Provider/exporter performance evidence shows registry lookup, validation/refusal, identity mapping, receipt rendering, and exporter projection remain bounded; material regressions are classified as host provider overhead, gateway/auth overhead, or evidence-pack size overhead before 28b/28e/28f/28g/30b depend on the coexistence registry.
docs/USE_CASES.md,docs/HOST_TOOLS.md,docs/API_GUIDELINES.md,docs/INTERFACES.md,docs/ARCHITECTURE.md,docs/SECURITY.md, anddocs/TEST_PLAN.mddescribe support levels exactly as proven.
Compiler touchpoints
coh-rtcextendshost-integration-dependency/v1and emits provider registry artifacts, provider-adapter lifecycle/ABI vectors, canonical native identity/correlation/event fields, evidence profiles, integration-surface records, external-executor contracts, stable use-case rows, provider availability snippets, provider action schemas, explicit operator-approval and future-admission availability metadata, supported/selected governance modes, authority-custody and bypass posture, failure/fallback posture, shadow-promotion requirements, read visibility classes, identity-mapping bounds, conformance matrix defaults, exporter schema bounds, and exact package profile metadata.coh-rtcalso emits native discovery-source/TTL contracts, GPU physical/MIG topology and workload-action bounds, authoritative receipt/evidence correlation schemas, exporter delivery/redaction policy, and generated playbook DAG/topology/recovery records; clients may format these records but cannot define parallel truth.- Manifest validation rejects enabled provider actions without target grammar, authority scope, idempotency policy, receipt schema, redaction policy, and evidence mapping. Enforced selection or actuation additionally fails generation without an authority custodian, bypass and failure posture, accepted provider/executor conformance, and the required shadow-promotion reference.
- Generated docs distinguish current primitives, integration patterns, workflow templates, mock-only, read-only, not-enabled, planned, and production-proven integrations without conflating executable Workers with external execution.
Task Breakdown
Title/ID: m28a-provider-action-registry
Milestone: 28a / m28a-provider-action-registry
Goal: Extend the accepted 27b compiler-owned registry to every broader provider family without redefining authority or action semantics.
Inputs: accepted 27b–27g implementation and exact evidence; configs/generated/host_integration_dependency.json, tools/coh-rtc, apps/host-ticket-agent, apps/coh, apps/cohsh, tools/cohesix-py, docs/INTERFACES.md, docs/HOST_API.md.
Changes:
- tools/coh-rtc/src/ir.rs — `providers.*` schema for action names, targets,
evidence modes, supported/selected governance modes, authority and
credential custodian, bypass and failure/fallback posture,
shadow-promotion requirements, receipts, redaction, evidence refs, and the
reserved later-admission `intent_schema_ref`, `required_fact_schema_ref`, `policy_id`,
`decision_requirement`, `maximum_grant_scope`,
`state_freshness_bound`, `reservation_or_recheck_mode`, and
`decision_receipt_schema_ref` fields for side-effecting actions.
Each action additionally generates its
`discover|preflight|execute|observe|verify|compensate|export_evidence`
lifecycle, canonical native target identity, expected postcondition,
native correlation/event-cursor fields, and evidence profile.
- tools/coh-rtc/src/codegen/{docs,rust,cohesix_py}.rs — generated provider
registry artifacts, language-neutral adapter ABI/conformance vectors,
Python defaults, and snippets.
- apps/host-ticket-agent/src/registry.rs — consume generated provider/action metadata before executor dispatch.
- apps/coh/src/provider.rs + apps/cohsh/src/provider.rs — display generated provider action availability without hand-maintained lists.
- tools/cohesix-py/cohesix/integrations.py + tools/cohesix-py/tests/test_integrations.py — consume the coh-rtc-generated Python provider output for action ids, target schemas, modes, bounds, receipt refs, and typed unavailable state; reject any handwritten Python provider-action catalogue, direct edit of `generated.py`, or client-selected promotion to `live`.
Commands: cargo test -p coh-rtc && cargo test -p host-ticket-agent && cargo test -p coh && cargo test -p cohsh && python3 -m pytest -q tools/cohesix-py/tests/test_integrations.py -k provider_registry
Checks: Provider action schemas, adapter lifecycle, native identity/correlation,
evidence profiles, and admission metadata cannot drift between executor
validation, Rust/Python host tools, ecosystem-native controllers, REST, docs,
packages, and future gateway protocol schema inputs; Python exposes the same
generated availability, governance mode, decision requirement, grant ceiling,
freshness/recheck posture, bypass/failure posture, promotion state, and
refusals; no client can promote itself from observe/recommend to enforce,
weaken required admission, or treat mutable native metadata as a grant.
Deliverables: Single source of truth for host-side ecosystem action and adapter
lifecycle semantics across Rust, Python, and selected native-controller
consumers.
Title/ID: m28a-integration-surface-registry
Milestone: 28a / m28a-integration-surface-registry
Goal: Extend the accepted integration inventory with broader provider, platform and deployment surfaces and exact conformance ownership.
Inputs: accepted 27b–27g implementation and exact evidence; m26e-production-surface-truth-and-stub-retirement, m26e-host-integration-dependency-contract, configs/generated/{implementation_surface_inventory,host_integration_dependency}.json, all Cargo targets/features, Python packages/examples, scripts, nested READMEs, canonical/generated docs, release assets, resources/openapi/hive-gateway.yaml, packaging, and scripts/release_bundle.sh.
Changes:
- tools/coh-rtc/src/ir.rs + tools/coh-rtc/src/codegen/{docs,rust}.rs — `integration_surfaces.*` schema and generated surface/package/dependency records.
- configs/host_integration_acceptance.toml — extend stable 26e ids with 27b provider, surface, executor, package, and proof obligations.
- scripts/ci/check_host_integration_inventory.py — consume the 26e implementation-surface inventory and inspect host binaries and libraries exposed as products, projections, packages, Python APIs/examples, scenarios, playbooks, demos, runbooks, generated files, nested READMEs, and release assets; fail on unregistered, silently omitted, production-reachable fixture/stub/no-op, or unowned surfaces.
- docs/HOST_TOOLS.md + docs/INTERFACES.md — generated availability and trust-boundary tables.
Commands: cargo test -p coh-rtc && scripts/ci/check_host_integration_inventory.py --registry configs/generated/host_integration_dependency.json && scripts/check-generated.sh
Checks: Direct console, REST, FUSE, Python, SwarmUI, federation, fleet, CAS, evidence/release, telemetry/exporters, GPU/sidecar bridges, and Jetson/network surfaces have explicit owners, modes, packages, Worker tiers, and conformance lanes; no-op adapters, mock-only examples, retired binaries, or undocumented library entrypoints cannot report live or enter a production package.
Deliverables: Exhaustive compiler-owned host integration inventory extending the 26e graph.
Title/ID: m28a-public-surface-live-mode-gate
Milestone: 28a / m28a-public-surface-live-mode-gate
Goal: Apply the accepted release live/fixture separation to broader commands, domain examples and packages.
Inputs: accepted 27b–27g implementation and exact evidence; m26e-production-surface-truth-and-stub-retirement, m28a-integration-surface-registry, generated implementation/integration inventories, apps/{coh,cohsh,hive-gateway,host-ticket-agent,host-sidecar-bridge,gpu-bridge-host,swarmui}/**, tools/cohesix-py/**, scripts/cohsh/run_demo.coh, demo/**, all public READMEs/docs/examples, service definitions, scripts/release_bundle.sh.
Changes:
- generated surface metadata — project every public entrypoint onto the existing implementation/observed/proof classes, including explicit fixture/host-model/dry-run, live-host, live-QEMU, live-Pi, unavailable, deferred, and retired states; do not invent a second authority or evidence vocabulary.
- host CLI/service selection — production/default invocations require an explicit generated live profile/endpoint or fail typed unavailable. Mock backends require an explicit flag and fixture-capable build/profile; remove `cohsh`'s implicit mock default and environment-only mock switches such as a service silently honoring `HIVE_GATEWAY_MOCK` in a production unit.
- public examples/demos — move queue/status fabrication such as `scripts/cohsh/run_demo.coh` and fake PEFT adapter assets into clearly named fixtures, or replace the public path with the real ticket -> admission -> provider/executor -> Worker terminal flow owned by 27c/27d. Every output/report embeds mode, source identity, graph version, and proof class.
- package/docs gate — exclude fixture keys, placeholder credentials, synthetic topology/artifacts, test-only binaries, retired stubs, and mock-only examples from live packages; nested READMEs/help/current release docs describe the selected implementation mode and exact owner. Historical releases remain immutable and receive current errata only.
- scripts/ci/check_public_surface_modes.py — scan compiled feature closures, CLI defaults/help, environment selection, examples, reports, service manifests, docs, and release contents against the generated inventories.
Commands: cargo test -p coh -p cohsh -p hive-gateway -p host-ticket-agent -p host-sidecar-bridge -p gpu-bridge-host && python -m pytest tools/cohesix-py/tests && python3 scripts/ci/check_public_surface_modes.py --implementation configs/generated/implementation_surface_inventory.json --integrations configs/generated/host_integration_dependency.json && scripts/release_bundle.sh --check-manifest --pi4-stage-dir out/pi4-sd
Checks: No release/default command or service starts a mock backend implicitly; no fixture, fabricated state, client-authored receipt, placeholder credential, mock-only demo, or synthetic artifact can produce a live-host/QEMU/Pi or production-use-case record; explicit fixture/dry-run lanes remain deterministic and useful.
Deliverables: Fail-closed public mode selection and packaging, with retained mocks visibly and mechanically isolated from live Cohesix claims.
Title/ID: m28a-external-executor-conformance
Milestone: 28a / m28a-external-executor-conformance
Goal: Qualify broader native executors and data planes against the accepted 27b result contract.
Inputs: accepted 27b–27g implementation and exact evidence; provider/integration registries, apps/host-ticket-agent, apps/gpu-bridge-host, crates/host-cuda, PEFT/model-registry tools, systemd/Docker/Kubernetes fixtures, scripts/ci/provider_conformance_run.sh, m26e Worker integration evidence.
Changes:
- tools/coh-rtc/src/ir.rs — generated GPU, PEFT pipeline, service executor, and federation relay conformance contracts.
- apps/host-ticket-agent/src/providers/ — strict observed-result correlation for systemd, launchd, Docker, Kubernetes, GPU, and declared external executors; discovery or dispatch success alone is non-terminal.
- apps/gpu-bridge-host/** + crates/host-cuda/** — execute generated bounded workload actions on the exact admitted physical/MIG device and topology generation, and return observed cancellation/revocation/terminal state plus CAS output hashes; GPU hardware access remains in `gpu-bridge-host`.
- scripts/ci/provider_conformance_run.sh — separate discovery/publication, dispatch, terminal outcome, isolation, timeout, revoke, restart, and recovery evidence.
- docs/GPU_NODES.md + docs/HOST_TOOLS.md — distinguish live inventory, lease projection, execution, isolation, and Worker receipt proof.
Commands: cargo test -p host-ticket-agent && cargo test -p gpu-bridge-host && scripts/ci/provider_conformance_run.sh --executors-only --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28a-executors
Checks: Live GPU execution names the device/MIG instance, topology generation, memory/stream admission, isolation, lease epoch/TTL, revoke/cancel, output refs, and observed terminal result; service executors prove fenced terminal state; PEFT pipeline rows remain integration-pattern/not-enabled unless the accepted 27d transaction supplies the full selected pipeline.
Deliverables: Fail-closed external execution evidence tied to exact Worker receipts.
Title/ID: m28a-native-provider-discovery-and-actions
Status: Reopened only for the retained launchd transitional-observation defect found by M27g / m27g-two-hour-pi4-operator-burn-in. All broader provider implementation and qualification remains Planned. Restore observation within the existing native deadline, retain exact identity checks and single dispatch, and require focused parser plus real macOS start/restart/stop evidence.
Milestone: 28a / m28a-native-provider-discovery-and-actions
Goal: Complete and qualify broader macOS, Kubernetes and native-provider discovery/actions while retaining the working CUDA/systemd/Docker paths.
Inputs: accepted 27b–27g implementation and exact evidence; provider/integration registries, apps/host-sidecar-bridge/**, apps/host-ticket-agent/**, tools/cohesix-py/cohesix/integrations.py, apps/gpu-bridge-host/**, macOS launchd/Xcode tooling, Linux systemd/Docker/Kubernetes APIs, Jetson host interfaces, docs/HOST_TOOLS.md, docs/USE_CASES.md.
Changes:
- M27g retained-path restoration: retry only typed transitional observations within the existing caller deadline; preserve single dispatch, native identity and fail-closed parsing. Parser and native macOS lifecycle checks pass. Compatibility review: host-ticket-agent and host-sidecar-bridge consume the repaired observer; coh/coh-status, cohsh, Hive Gateway, SwarmUI, gpu-bridge-host, cas-tool, sidecar-bus, the Python SDK and performance scripts keep their existing authority, grammar, schemas, bounds and result contracts. No other implementation changes are needed.
- host provider implementations — read systemd, launchd, Docker, Kubernetes, NVIDIA/CUDA/NVML, Jetson board/JetPack/power/thermal/clock, and macOS/Linux network interface/link/address/route/error-counter state from the selected host's native bounded APIs or allowlisted structured utilities; never treat target-preseeded `/host` data as discovery input.
- systemd provider — use the Manager D-Bus API for discovery and lifecycle,
support selected hardened transient units for bounded external work, bind
exact unit/invocation identity and properties, consume `sd_notify` state
where provided, and capture a bounded structured-journal cursor range.
`systemctl` display text or zero exit status is never terminal evidence.
- Docker provider — use a version-negotiated Engine API, exact image digest
and container identity, filtered ticket-labelled events, final inspect,
health/exit/OOM state, and bounded log refs. Labels are correlation only;
optional Engine authorization-plugin conformance remains a separately
enabled enforcement surface with its protocol limitations recorded.
- Kubernetes provider — use canonical object UID/resourceVersion/generation,
status conditions, audit identity, and watch cursors. When selected, ship a
generated `CohesixAction` CRD/controller projection and native CEL admission
checks for digest, grant-ref, service-account, and resource bounds; webhook
or version-gated DRA support remains independently enabled and evidenced.
- apps/host-ticket-agent/** — execute only generated allowlisted actions, bind the exact native target and writer/idempotency fence, observe the provider's terminal state, and emit an authoritative provider result; command exit alone is not success.
- macOS providers — add launchd lifecycle, explicit Mac-controller versus remote-CUDA/Jetson versus optional local-Apple-GPU topology, Xcode build/test/archive plus codesign/notary/App Store Connect release steps, and endpoint-compliance observation through generated credential/secret refs. A Mac controller does not probe local NVML unless a local NVIDIA provider is explicitly selected.
- provider snapshot publication — publish authenticated versioned source/sequence/epoch/time/TTL records into the target's generated host snapshot interface; expiry or source failure withdraws state instead of retaining a healthy fixture.
- conformance — run macOS-native, Linux/systemd, Kubernetes, NVIDIA GPU, and Jetson/network live lanes where selected; unsupported provider/host combinations return typed unavailable.
Commands: cargo test -p host-ticket-agent && cargo test -p host-sidecar-bridge && python -m pytest tools/cohesix-py/tests/test_integrations.py && scripts/ci/provider_conformance_run.sh --native-providers --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28a-native
Checks: No selected provider reports success from `Ok(())`, target-preseeded
data, CLI display text, mutable label/annotation state, a fixture, or command
dispatch alone; each live state/action names its native source, immutable target
identity and generation/invocation, event cursor/range, observation time/TTL,
verified postcondition, terminal outcome, and authoritative receipt, and stale
state becomes unavailable.
Deliverables: Real host-native discovery/action providers for the advertised macOS, Linux, Kubernetes, NVIDIA, Jetson, and network profiles.
Title/ID: m28a-gpu-workload-and-mig-executor
Milestone: 28a / m28a-gpu-workload-and-mig-executor
Goal: Extend the accepted physical CUDA executor to exact MIG topology/lease enforcement and bounded optional DCGM/CUPTI evidence.
Inputs: accepted 27b–27g implementation and exact evidence; provider/executor registries, apps/gpu-bridge-host/**, crates/host-cuda/**, apps/host-ticket-agent/**, apps/coh/src/{gpu.rs,run.rs}, CAS tools, accepted WorkerGpu v2 receipt path, live NVIDIA/MIG test hosts, docs/GPU_NODES.md, docs/SECURITY.md.
Changes:
- crates/host-cuda/** + apps/gpu-bridge-host/** — enumerate live NVML MIG GPU/compute instances with parent/child UUIDs, profile, memory, placement, and topology generation; fence stale generations and bind lease/execution to the exact physical device or MIG instance.
- apps/gpu-bridge-host/** — implement generated bounded `gpu.workload.submit|cancel|observe` execution for allowlisted CAS artifacts/entrypoints, including memory/stream admission, context/process isolation, deadline, lease TTL/epoch, revoke/preempt, cancellation, CUDA failure mapping, output CAS hashes, and one correlated terminal provider/WorkerGpu record. CUDA/NVML access remains exclusively in this host tool.
- NVIDIA evidence adapters — use the Cohesix ticket id as the external GPU job
and trace-correlation key; export bounded CUDA/NVML identity and health on
every supported profile, DCGM job/health/energy/utilisation/error summaries
where DCGM is available, and an opt-in CUPTI/NVTX trace hash only for an
explicit `deep_gpu` evidence profile with declared overhead and profiling-
resource coordination. Missing DCGM/CUPTI is typed capability state, not a
failure of a valid Jetson CUDA path.
- apps/host-ticket-agent/** + generated local provider ABI — validate the Cohesix ticket/action and forward the admitted request to `gpu-bridge-host` through a compiler-declared authenticated bounded host-local transport; it cannot submit raw commands, inline PTX, arbitrary paths, or bypass lease/MIG fencing.
- apps/coh/src/{gpu.rs,run.rs} — expose the generated workload lifecycle and classify plain local subprocess execution separately as a non-authoritative host operation report; `echo ok`, vadd/matmul descriptors, breadcrumbs, or a successful lease cannot satisfy GPU execution.
- conformance/evidence — prove real vector-add and matrix-multiply reference workloads plus cancel, timeout, revoke, over-budget admission, CUDA OOM mapping, stale-MIG-generation, wrong-device, bridge restart, and output-hash cases on physical and MIG-capable profiles where advertised. Shared-memory Jetson profiles reject oversized live requests before allocation and test CUDA OOM mapping only through an isolated memory-capped child or deterministic fault injection.
Commands: cargo test -p host-cuda && cargo test -p gpu-bridge-host && cargo test -p host-ticket-agent && cargo test -p coh --test gpu_workload && scripts/ci/provider_conformance_run.sh --provider gpu.workload --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28a-gpu-workload
Checks: A live GPU result is impossible without observed CUDA execution on the
exact lease-bound physical/MIG target and generation, and reconstructs
admission, native job identity, isolation, cancellation/revoke, outputs,
bounded health/resource observations, terminal status, and exact WorkerGpu
correlation; fixture descriptors remain test-only, DCGM cannot substitute for
execution, and CUPTI capture is never silently enabled.
Deliverables: Real CUDA/MIG workload execution and evidence, distinct from discovery, model publication, and lease projection.
Title/ID: m28a-jetson-orin-nano-live-conformance
Milestone: 28a / m28a-jetson-orin-nano-live-conformance
Goal: Preserve and requalify the accepted Jetson foundation only for broader-provider changes affecting its native execution or evidence contract.
Inputs: accepted 27b–27g implementation and exact evidence; m28a-native-provider-discovery-and-actions, m28a-gpu-workload-and-mig-executor, `jetson-orin-nano-jp7` generated profile, JetPack/L4T package inventory, CUDA driver/runtime APIs, NVIDIA Container Runtime, `/mnt/nvme` reference layout, docs/GPU_NODES.md, docs/HOST_TOOLS.md, docs/TEST_PLAN.md.
Changes:
- configs/provider_conformance.toml + generated provider/profile records — exact AArch64, Ubuntu, L4T, JetPack, CUDA, compute-capability, shared-memory, physical-device, unsupported-MIG/DLA/PVA, power/thermal observation, container-runtime, and NVMe evidence requirements.
- crates/host-cuda/** + apps/gpu-bridge-host/** — CUDA 13-compatible discovery and bounded native physical-device workload execution with live free-memory/headroom admission; retain older supported CUDA/NVML profiles.
- apps/host-sidecar-bridge/** — bounded read-only Jetson board, package, power, clock, thermal/throttle, and storage observations from allowlisted native sources, with typed unavailable fields where the SKU exposes no source.
- scripts/ci/provider_conformance_run.sh — `--host-profile jetson-orin-nano-jp7 --live-reference` routing, exact-host preflight, non-disruptive default, native/container lane separation, safe negative cases, raw log redaction, and evidence capture under the selected NVMe state directory.
- systemd/Docker reference execution — launch the accepted bounded workload
through a hardened systemd unit and a digest-pinned NVIDIA-container lane,
bind unit invocation, container/image, CUDA device/job, ticket, CAS output,
and receipt identities, and retain large container/journal/trace artifacts
under the selected NVMe evidence root.
- docs/GPU_NODES.md + docs/HOST_TOOLS.md + docs/TEST_PLAN.md — operator prerequisites, non-disruptive default, unsupported-feature behavior, exact commands, and proof boundaries.
Commands: cargo test -p host-cuda && cargo test -p gpu-bridge-host && cargo test -p host-sidecar-bridge && scripts/ci/provider_conformance_run.sh --provider jetson --host-profile jetson-orin-nano-jp7 --live-reference --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28a-jetson-orin && scripts/ci/provider_conformance_run.sh --provider gpu.workload --host-profile jetson-orin-nano-jp7 --live-reference --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28a-jetson-gpu
Checks: Exact live inventory and doctor fallback pass; bounded native vector-add
and matrix-multiply execute on the admitted physical Orin device and produce
verified CAS outputs; the selected systemd and digest-pinned NVIDIA-container
lanes correlate native invocation/container/event identity to the same ticket
and terminal CUDA result; cancel/timeout/revoke/restart/wrong-device/stale-
inventory/over-budget cases fail safely; MIG/DLA/PVA and unsupported DCGM
features report typed unavailable; the run does not reboot, change power mode,
force clocks, restart network/VNC, or consume unsafe shared-memory headroom.
Deliverables: Repeatable, non-disruptive Jetson Orin Nano live provider and physical-GPU conformance evidence that cannot be mistaken for MIG, datacenter-GPU, QEMU, Pi, or NeMo acceptance.
Title/ID: m28a-authoritative-receipt-and-evidence-core
Milestone: 28a / m28a-authoritative-receipt-and-evidence-core
Goal: Extend the accepted 27b shared verifier with broader provider/exporter correlations; never create another receipt authority.
Inputs: accepted 27b–27g implementation and exact evidence; root-admitted ticket/action and Worker v2 records, provider/executor terminal records, apps/coh/src/{gpu.rs,run.rs,evidence.rs,evidence_timeline.rs}, tools/cohesix-py/cohesix/{client.py,receipts.py}, apps/hive-gateway/**, apps/swarmui/**, release/CI evidence checks, schemas/fixtures/docs.
Changes:
- shared host evidence/receipt crate — parse and verify schema/version, canonical bytes, manifest and component hashes, configured signature/attestation chain, source identity, ticket/subject/action/idempotency/writer epoch, target manifest, sequence/epoch/TTL, Worker/provider/executor correlation, terminal uniqueness, and chronology with bounded inputs and typed errors.
- apps/coh/** + tools/cohesix-py/** — consume root-admitted and Worker/provider/executor terminal records as authoritative receipts. Rename locally assembled ACK/argument/snapshot summaries to a versioned non-authoritative operation report; they cannot use a receipt schema, enter an authoritative evidence graph, or promote a use case. Apply the required schema/fixture/docs migration atomically.
- apps/hive-gateway/** + apps/swarmui/** + exporters/release/CI — use the shared Rust implementation or generated language-neutral conformance vectors; reject missing, stale, forged, partially correlated, duplicate-terminal, wrong-manifest, or client-created records consistently.
- apps/coh/src/evidence.rs + evidence timeline — hash every included file, bind the implementation/provider/use-case graph versions, record authoritative versus derived artifacts, and verify the complete graph before an evidence pack is accepted or exported.
Preserve the deterministic directory layout while materialising a bounded
causal graph over intent, facts, approval/decision, grant, native execution
object, observations, verification, terminal receipt, and compensation.
Large journal/container/Kubernetes/CUDA/PEFT artifacts remain in NVMe-backed
CAS or configured object storage and enter the pack only through validated
hashes, summaries, cursors, and refs.
- derived attestation/telemetry projections — generate optional in-toto
statements, SLSA provenance only for genuine build actions, OpenTelemetry
spans, and CloudEvents from validator-accepted graph records. Preserve the
authoritative/derived distinction and never accept an imported projection
as a Cohesix receipt.
Commands: cargo test -p coh --test receipts && cargo test -p coh --test evidence_pack && cargo test -p hive-gateway && cargo test -p swarmui && python -m pytest tools/cohesix-py/tests/test_evidence_receipts.py && scripts/ci/provider_conformance_run.sh --evidence-only
Checks: Rust, Python, REST/UI, CI, release, and exporter vectors agree byte-for-
byte; no local transcript, arguments, file-presence check, client JSON, native
label/annotation, OTel span, CloudEvent, or imported attestation can pass as an
authoritative receipt; every accepted terminal result has one validated causal
chain to admitted authority and exact target/provider/Worker/executor identity,
and missing native evidence is explicit rather than inferred.
Deliverables: One strict authoritative receipt/evidence core, a deterministic
causal evidence manifest with content-addressed external refs, and an honest
separately named local operation-report/derived-export format.
Title/ID: m28a-federation-conformance
Milestone: 28a / m28a-federation-conformance
Goal: Close federation durability and receipt-correlation gaps before multi-hive workflows can be production-proven.
Inputs: apps/host-ticket-agent, its relay/WAL modules, federation manifests/fixtures, provider/integration registries, docs/SECURITY.md, docs/TEST_PLAN.md.
Changes:
- apps/host-ticket-agent/src/relay/** + apps/host-ticket-agent/src/wal/** — WAL-before-forward, enforced deadlines, non-evictable pending intents, target terminal receipt return, source correlation, and restart replay/fencing. `sidecar-bus` remains the Milestone 18 field-bus provider and is not the federation authority owner.
- scripts/ci/provider_conformance_run.sh — federation fault injection for timeout, disconnect, duplicate, target refusal, full queue, and process restart.
- docs/INTERFACES.md + docs/SECURITY.md — terminal receipt, durability, and fail-closed federation contract.
Commands: cargo test -p host-ticket-agent && scripts/ci/provider_conformance_run.sh --provider federation --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28a-federation
Checks: No intent is forwarded before durable WAL, no pending entry is evicted, configured timeout is enforced, and the source receives the uniquely correlated target terminal receipt after normal and restart paths.
Deliverables: Federation may be enabled only with durable, replay-safe, end-to-end receipt evidence.
Title/ID: m28a-live-reference-workflows
Milestone: 28a / m28a-live-reference-workflows
Goal: Implement all nine domain playbooks over the accepted 27c lifecycle and 27d LoRA transaction, with explicit topology and real native owners.
Inputs: accepted 27b–27g implementation and exact evidence; provider/integration/use-case registries, tools/cohesix-py/cohesix/{playbooks.py,playbook_cli.py}, tools/cohesix-py/examples/use_case_playbook.py, all nine built-in playbooks, GPU/MIG executor, native providers, deployment packages, evidence core, docs/USE_CASES.md.
Changes:
- tools/coh-rtc/src/** + generated playbook records — extend the accepted 27c bounded staged recipe nodes for `preflight`, `admit`, `execute`, `observe`, `verify`, and `recover`, including controller host, target hive/node, Worker role, provider action, external application/data-plane owner, refs, deadline, cancellation/idempotency/fencing, compensation, and authoritative evidence.
- apps/coh/** + generated CLI records — reuse the accepted 27c ticket-centred operator
journey equivalent to `plan`, `apply`, `watch`, `explain`, `verify`,
`recover`, and ticket-scoped `evidence pack`. Existing command families may
host the generated subcommands, but every surface must render the same
lifecycle nodes, native identities, refusal reason, expected postcondition,
compensation state, and authoritative/derived evidence classification.
- tools/cohesix-py/cohesix/playbooks.py — implement those generated stages for `mac-release-factory`, `mac-private-peft-grid`, `mac-endpoint-compliance`, all three Jetson workflows, and all three mixed-fleet workflows. Mac release uses launchd/Xcode/codesign/notary/App Store Connect providers; Mac PEFT selects remote CUDA or an explicit Apple provider; Jetson/medical/safety/logistics domain applications are named signed deployment dependencies and return typed unavailable when absent.
- tools/cohesix-py/examples/** — keep mock/dry-run examples as explicit workflow fixtures and add live configuration examples that reference secret stores and deployment manifests, never embedded credentials or synthetic terminal records.
- recovery/evidence tests — inject provider, Worker, gateway, network, executor, and verification failures at each stage and prove bounded cancel/compensate/retry behavior plus one reconstructable terminal result.
Commands: python -m pytest tools/cohesix-py/tests/test_playbooks.py && python -m cohesix.playbook_cli --list && scripts/ci/provider_conformance_run.sh --playbooks --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28a-playbooks && scripts/ci/use_case_gate.sh --matrix configs/generated/use_case_evidence.json --state-dir out/use-case-gate/m28a-playbooks
Checks: Every shipped playbook traverses the generated stages in live mode,
names every node and external owner, is inspectable through one ticket-centred
host-tool timeline, and fails closed when a provider/application/evidence
dependency is missing; schedule, lease, export, probe, native-object creation,
or local mock success cannot become workflow success.
Deliverables: Nine complete, topology-explicit, fail-closed host workflows with
mock fixtures and real-provider acceptance lanes kept distinct, plus one shared
operator lifecycle for planning, following, explaining, verifying, recovering,
and exporting evidence for them.
Title/ID: m28a-ecosystem-conformance-matrix
Milestone: 28a / m28a-ecosystem-conformance-matrix
Goal: Complete the wider provider matrix beyond the accepted release profiles with independent native evidence.
Inputs: accepted 27b–27g implementation and exact evidence; configs/provider_conformance.toml, scripts/ci/, docs/TEST_PLAN.md, docs/USE_CASES.md.
Changes:
- configs/provider_conformance.toml — provider version, profile, auth, mock/dry-run/live-safe, negative, receipt, and evidence requirements.
- scripts/ci/provider_conformance_run.sh — deterministic matrix runner.
- docs/TEST_PLAN.md — provider conformance stage and evidence paths.
- docs/USE_CASES.md — support-level mapping for each documented ecosystem integration.
Commands: scripts/ci/provider_conformance_run.sh --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28a
Checks: Every claimed production provider has passing conformance evidence or an explicit not-enabled status.
Deliverables: Production coexistence matrix tied to release evidence.
Title/ID: m28a-read-visibility-classes
Milestone: 28a / m28a-read-visibility-classes
Goal: Extend accepted scoped read enforcement to every newly exposed broader projection.
Inputs: accepted 27b–27g implementation and exact evidence; tools/coh-rtc, apps/hive-gateway, apps/coh, apps/cohsh, apps/swarmui, tools/cohesix-py, docs/SECURITY.md, docs/API_GUIDELINES.md.
Changes:
- tools/coh-rtc/src/ir.rs — read visibility class for provider, evidence, ticket, audit, replay, telemetry, and `/proc` paths.
- apps/hive-gateway/src/auth.rs — enforce delegated identity for ticket-scoped reads and admin-only policy for global reads.
- apps/coh/src/read_scope.rs + apps/cohsh/src/read_scope.rs — preserve read-scope refusals in host tools.
- tools/cohesix-py/cohesix/backends.py + tools/cohesix-py/tests/test_rest_backend_auth.py — propagate delegated caller identity for ticket-scoped REST reads, preserve public/admin-only classification, and prove cross-caller denial before returning bytes.
- docs/SECURITY.md + docs/API_GUIDELINES.md — document public, ticket-scoped, and admin-only read behavior.
Commands: cargo test -p coh-rtc && cargo test -p hive-gateway && cargo test -p coh && cargo test -p cohsh && python3 -m pytest -q tools/cohesix-py/tests/test_rest_backend_auth.py -k read_visibility
Checks: Cross-caller ticket, provider receipt, evidence, audit/replay, task, and identity diagnostics reads fail deterministically before data is returned through Rust, REST, Python, or UI projections.
Deliverables: Read-only ecosystem projections, including Python, are scoped with the same rigor as writes.
Title/ID: m28a-identity-mapping
Milestone: 28a / m28a-identity-mapping
Goal: Qualify broader OIDC, SPIFFE, Kubernetes and host identity mappings under the existing delegated-ticket authority.
Inputs: accepted 27b–27g implementation and exact evidence; apps/hive-gateway, apps/coh, tools/cohesix-py, tools/coh-rtc, docs/SECURITY.md.
Changes:
- apps/hive-gateway/src/identity.rs — validate configured OIDC/JWT, SPIFFE, Kubernetes service account, and local-host subject claims.
- tools/coh-rtc/src/validate.rs — issuer/audience/subject/group/TTL/action-scope mapping validation.
- tools/cohesix-py/cohesix/identity.py — reference host-side subject mapping helpers.
- docs/SECURITY.md + docs/API_GUIDELINES.md — identity-to-ticket mapping and refusal semantics.
Commands: cargo test -p hive-gateway && cargo test -p coh-rtc && python -m pytest tools/cohesix-py/tests/test_identity.py
Checks: Forged, expired, wrong-audience, overbroad, or unmapped claims fail before mutation and emit deterministic audit evidence.
Deliverables: Enterprise identity coexistence without expanding the VM TCB.
Title/ID: m28a-packaging-deployment-profiles
Milestone: 28a / m28a-packaging-deployment-profiles
Goal: Extend accepted 27e packaging to broader native, Kubernetes, container, FUSE and provider profiles.
Inputs: accepted 27b–27g implementation and exact evidence; m28a-public-surface-live-mode-gate, scripts/install/, packaging/, apps/hive-gateway, apps/host-ticket-agent, apps/host-sidecar-bridge, apps/sidecar-bus, apps/gpu-bridge-host, apps/coh, apps/cohsh, FUSE helpers, Python package/extras, resources/openapi/hive-gateway.yaml, scripts/release_bundle.sh, docs/audit/checklists/RELEASE_EVIDENCE_CHECKLIST.md.
Changes:
- packaging/systemd/ — hardened unit templates for gateway, ticket agent, sidecar bridge, GPU bridge, and exporters.
- packaging/launchd/ — macOS operator launchd examples.
- packaging/k8s/ — Helm/Kustomize or plain YAML for gateway/agent sidecar
deployments; selected profiles additionally ship the generated
`CohesixAction` CRD/controller, status conditions, CEL policies, least-
privilege RBAC, `kubectl` plugin, upgrade/version bounds, and deterministic
unavailable behavior for unselected webhook/DRA features.
- packaging/systemd/ + packaging/container/ — selected executor profiles ship
hardened transient/persistent unit properties, credential and device
policy, structured journal fields, Docker Engine API/version policy,
least-privilege socket/proxy access, ticket/evidence correlation labels,
and exact state/CAS ownership under caller-supplied roots.
- packaging/manifests/ — generated exact artifact type/architecture/version/digest/signature/SBOM/config/schema/secret-ref manifests and unexpected-file refusal for every selected deployment profile.
- Python packaging — build and inspect clean wheel/sdist artifacts from an explicit package manifest; never recursively copy the source tree, tests, caches, fixture keys, or local credentials into a release.
- FUSE packaging/tests — canonical `/shard` parity for direct and REST mounts, supported-host read/write/error behavior, and no legacy-only allowlist.
- resources/openapi/ + scripts/release_bundle.sh — self-contained offline OpenAPI and docs assets; selected missing binaries/assets fail closed.
- apps/coh/src/doctor.rs — provider registry, package profile, auth, secret-ref, and exporter health checks.
- docs/HOST_TOOLS.md — install and risk guidance for each deployment profile.
Commands: cargo test -p coh --test doctor && scripts/ci/provider_conformance_run.sh --packaging-only && scripts/release_bundle.sh --check-manifest --pi4-stage-dir out/pi4-sd
Checks: Packages install only the exact registered host-side artifacts, preserve least privilege and loopback defaults, prove direct/REST FUSE `/shard` parity, contain self-hosted docs assets, fail on missing, unexpected, wrong-kind/architecture/version/digest/signature/SBOM artifacts, contain no private fixture key or compiled stub, and report optional missing providers deterministically.
Deliverables: Repeatable host deployment profiles that coexist with existing systems instead of replacing them.
Title/ID: m28a-observability-exporters
Milestone: 28a / m28a-observability-exporters
Goal: Add host-side Prometheus/OpenTelemetry/SIEM projections that consume strictly validated authoritative evidence and provide production delivery semantics without becoming authority.
Inputs: m28a-authoritative-receipt-and-evidence-core, apps/coh, apps/hive-gateway, tools/cohesix-py, release/CI evidence checks, provider/integration registries, docs/HOST_TOOLS.md, docs/SECURITY.md, docs/TEST_PLAN.md.
Changes:
- shared host evidence/receipt core — consume only validator-accepted records and preserve authoritative/derived classification, source identity, cursor, and graph/schema versions across all exporter projections.
- apps/coh/src/export/prometheus.rs — bounded read-only metrics projection.
- apps/coh/src/export/otel.rs — bounded OpenTelemetry projection.
- apps/coh/src/export/cloudevents.rs + attestation export — bounded
CloudEvents and in-toto projections over validated ticket lifecycle nodes;
emit SLSA provenance only for registered actions that actually build an
artifact. All projections preserve source graph/version/ref and remain
non-authoritative.
- apps/coh/src/export/siem.rs — generated field allowlist/redaction/hash policy plus durable cursor/WAL, TLS/credential refs, retry/backoff, backpressure, deadletter, and destination acknowledgement receipts.
- tools/cohesix-py/** + release/CI checks — consume the shared validation vectors and reject file-presence, client-authored JSON, or locally reconstructed transcripts as authoritative proof.
- docs/HOST_TOOLS.md + docs/SECURITY.md — redaction and authority posture.
Commands: cargo test -p coh --test export && scripts/ci/provider_conformance_run.sh --observability-only
Checks: Exporters accept only validator-approved records, are read-only,
bounded, redacted, schema-versioned, and reconstructable from evidence packs;
OTel/CloudEvents/in-toto/SLSA projections cannot be re-imported as authority;
SIEM live mode survives disconnect/restart without loss or unbounded
duplication and proves destination acknowledgement, while raw tickets/payloads
never leave the allowlist.
Deliverables: Observability and portable evidence projection without in-VM
monitoring stacks or a competing receipt format.
Title/ID: m28a-industry-sidecar-contracts
Milestone: 28a / m28a-industry-sidecar-contracts
Goal: Integrate the real Milestone 18 field-bus providers and stage later OT, healthcare, and science sidecars as host-only, read-only-first families without aliases or fake delivery.
Inputs: reopened Milestone 18 live MODBUS/DNP3 evidence, apps/sidecar-bus, apps/host-sidecar-bridge, tools/coh-rtc, docs/USE_CASES.md, docs/SECURITY.md.
Changes:
- apps/sidecar-bus/** + provider registry — package and prove the exact real MODBUS RTU/TCP and DNP3 codecs/transports, generated target maps/allowlists, durable acknowledgement-aware spool, typed protocol failures, and separately approved write/control actions from reopened Milestone 18.
- apps/host-sidecar-bridge/src/providers/ — real bounded read-only contracts for CAN, IEC-104, DICOM metadata, and CCSDS telemetry only when implemented; otherwise emit typed `not_implemented` and ship no alias/no-op provider.
- tools/coh-rtc/src/ir.rs — provider gating and write-action refusal defaults for safety-critical sidecars.
- docs/SECURITY.md + docs/INTERFACES.md — read-only-first and sensitive-data redaction posture.
Commands: cargo test -p host-sidecar-bridge && cargo test -p coh-rtc
Checks: Protocol code stays host-side; a MODBUS/DNP3 `Delivered` result has a remote protocol acknowledgement and durable terminal record; later provider families cannot report live until real I/O, bounded reads, redaction, packaging, and conformance exist; write-capable actions require exact policy admission.
Deliverables: Clear bridge contracts for broader industry coexistence without TCB expansion.
Title/ID: m28a-use-case-release-gate
Milestone: 28a / m28a-use-case-release-gate
Goal: Prevent public use-case claims from exceeding implementation and evidence.
Inputs: m28a-public-surface-live-mode-gate, m28a-live-reference-workflows, m28a-authoritative-receipt-and-evidence-core, README.md, docs/USE_CASES.md, docs/HOST_TOOLS.md, docs/GPU_NODES.md, docs/PYTHON_SUPPORT.md, docs/HOST_API.md, docs/INTERFACES.md, docs/API_GUIDELINES.md, docs/ARCHITECTURE.md, docs/SECURITY.md, docs/TEST_PLAN.md, docs/BUILD_PLAN.md post-M24 activities, tools/cohesix-py/cohesix/playbooks.py, resources/openapi/hive-gateway.yaml, packaging, scripts/release_bundle.sh, provider/integration registries, executable Worker evidence, external-executor evidence, evidence packs.
Changes:
- tools/coh-rtc/src/ir.rs + generated docs — stable use-case rows with proof class, Worker tier, topology, host tools, provider/surface dependencies, external executor/data plane, authority/secrets, authority custodian and bypass posture, supported/selected governance mode, shadow-promotion refs, durability/recovery, package, and evidence obligations.
- docs/USE_CASES.md — checked support-level matrix covering all six scenarios, all nine built-in playbooks, Milestone 18 patterns, and all post-M24 demo/runbook activities.
- scripts/ci/use_case_gate.sh — inventory every public claim source, validate conditional 26e/27/27c/27d and later owner dependencies without making future semantic/inference/production-binding rows prerequisites of 28a, scan examples/manifests for argv or embedded secrets, and require exact integration/evidence/package links.
- generated playbook records — consume the accepted `m28a-live-reference-workflows` DAG/evidence records and reject missing stages, controller/target topology, provider/data-plane ownership, recovery, or authoritative terminal correlation.
- apps/coh/src/evidence.rs — include provider registry and conformance snapshots in evidence packs.
Commands: scripts/ci/use_case_gate.sh --matrix configs/generated/use_case_evidence.json --state-dir out/use-case-gate/m28a && cargo test -p coh --test evidence_pack
Checks: No scenario, playbook, demo, runbook, example, OpenAPI description, or release document can claim production coexistence without the exact Worker tier, provider/surface and governance modes, external executor, node topology, generated policy, authority custodian/bypass posture, required shadow-promotion evidence, tests, deployment profile, authority/recovery posture, and evidence reconstruction; generic control-write or probe success cannot skip workflow stages.
Deliverables: Cohesix adoption claims stay honest and auditable.
Title/ID: m28a-provider-exporter-performance
Milestone: 28a / m28a-provider-exporter-performance
Goal: Add targeted provider/exporter timing evidence without requiring a full Pi/QEMU throughput benchmark.
Inputs: configs/provider_conformance.toml, scripts/ci/provider_conformance_run.sh, docs/BENCHMARKS.md, docs/TEST_PLAN.md.
Changes:
- scripts/ci/provider_conformance_run.sh — perf-only mode for registry lookup, provider validation/refusal, identity mapping, receipt rendering, and exporter projection over representative evidence packs.
- docs/BENCHMARKS.md + docs/TEST_PLAN.md — classify coexistence overhead separately from REST hardware performance.
Commands: scripts/ci/provider_conformance_run.sh --perf-only --matrix configs/provider_conformance.toml --state-dir out/bench/m28a-provider-overhead
Checks: Provider/exporter timing stays bounded by generated limits and reports artifact-size context; failures classify host-provider, gateway/auth, or evidence-pack overhead.
Deliverables: Provider/exporter overhead evidence for downstream semantic,
AI, inference, and gateway protocol work.
Outcome
After Milestone 28a:
- Cohesix has a production coexistence contract, not only individual host adapters.
- Provider actions, integration surfaces, exact package contents, external-executor obligations, and public use-case claims extend one compiler-owned graph shared by host tickets, REST, FUSE, Python, SwarmUI, docs, tests, release tooling, and later MCP/A2A schemas.
- A ticket is the shared correlation key across systemd, Docker, optional Kubernetes, CUDA/NVIDIA, artifacts, native event streams, and evidence, while mutable ecosystem metadata remains non-authoritative.
- Operators can follow one generated lifecycle from plan through verified receipt and recovery, and export a portable causal evidence graph without replacing the native execution or monitoring systems.
- Existing ecosystems stay outside the VM TCB while still gaining delegated authority, receipts, evidence, deployment profiles, identity mapping, and observability exports.
- Executable Worker proof remains distinct from CUDA/NVML discovery, real GPU execution/isolation, PEFT training/reload, and service/federation side effects; each production use case names and proves every required layer.
- Semantic extraction, 28c intent admission, AI run control, inference interoperability, and MCP/A2A interop can build on proven provider and integration schemas instead of inventing action catalogs or silently treating mock workflows as live.
Milestone 31 — Semantic Object Fabric and Context Capsules
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain immutable semantic objects/edges, compiler and history views, extractor registry, bounded queries, indexes, visibility/provenance, capsule planning/rendering and the workbench inspector. Activate for a measured retrieval/context problem not solved by existing artifact and evidence references; no current 28x workflow depends on this substrate.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 28b; current owner 31
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Status: Planned — after the 27g release; preserve existing implementation and evidence.
Delivery posture: Implement the complete semantic object fabric and Context Capsules: typed objects/edges, compiler and history views, extractor registry, bounded queries, visibility/provenance, deterministic rendering, host tools, and conformance. All listed deliverables are required; capsule-only work is an intermediate result.
Why now (semantic substrate): Before durable AI runs, immutable content-addressed objects, edges, provenance, and task-selected Context Capsules can avoid repeatedly shipping raw text. Manifests, compilers, tests, and analyzers retain their own authority; semantic records preserve and link their evidence rather than replace it.
As-built alignment note: Content-addressed artifacts, evidence,
generated manifests, provider records, and visibility rules exist. Semantic
objects, snapshot manifests, edges, extractor registry, indexes, capsule schemas,
planner/renderer, and conformance do not. Existing /proc, model, update, evidence,
and Python surfaces do not supply them. This remains host-side work with no VM
parser, graph, or namespace expansion.
Prerequisites
- Completed 28a broader registry/provider contract; reuse 27b verifier and 27e package foundation.
- The Milestone 27b completed for the generated provider/integration rows, visibility classes, identity mapping, package profile, authoritative receipt/evidence core, and use-case maturity rules consumed by the capsule core. Unselected provider rows remain unavailable.
- Milestone 27 completed for deterministic inspect, evidence bundle, timeline, diff, and attestation utilities that semantic provenance extends rather than replaces.
- Milestone 28 claim/evidence vocabulary available for any formal or assurance statement attached to proofs, analyzer results, or generated manifests. Semantic extraction must not strengthen the evidence class of an imported artifact.
Goal Create a persistent host-side knowledge substrate that lets Cohesix select, authorize, render, and audit the semantic working set used by AI and operator workflows:
- Represent source entities, interfaces, tests, documentation, findings, proofs, benchmarks, models, services, devices, and capabilities as typed, immutable semantic objects with explicit provenance.
- Represent callers, callees, ownership, test coverage, documentation, benchmark, security, proof, model, service, and capability relationships as typed, versioned edges.
- Materialize expensive views such as AST, CFG, ownership/borrow summaries, call relationships, test links, benchmark history, and security history once per exact source/toolchain/extractor identity.
- Produce deterministic
context-capsule/v1manifests containing ordered object-view references, selection reasons, omissions, truncations, authority constraints, budgets, and renderer identity. - Reuse Milestone 27b visibility and delegated-identity policy so a derived object or edge never reveals more authority than its inputs.
- Expose local host tooling and generated SDK helpers for snapshot, inspect, query, capsule plan/render, verification, evidence, and health checks without requiring users to learn 9P or a new graph query language.
- Measure semantic paging directly: objects considered/materialized/selected, bytes and estimated tokens submitted or avoided, cache/invalidation reasons, query/capsule latency, and provenance/evidence overhead.
Completion boundary: All goals, deliverables, tasks, and checks below are required, including relationship graphs, compiler views, bounded queries, and history. Input availability still controls which facts an extractor can report; absent data cannot be fabricated.
Non-Goals (Explicit)
- No semantic parsing, repository checkout, graph index, compiler frontend, vector database, embedding model, or LLM inside the VM or root-task.
- No in-VM
/semantic,/functions,/objects, or Context Capsule namespace root in this milestone. - No replacement for Git, compiler IR, rust-analyzer, SCIP, SARIF, test frameworks, benchmark harnesses, SBOMs, proof tools, or Cohesix generated manifests. Imported data retains its original authority and evidence class.
- No public custom graph query protocol, ad-hoc RPC, mutable POSIX-like object tree, or requirement that ecosystem clients speak Secure9P.
- No generic prompt/blob store and no opaque transcript as semantic truth. Prompt text may be rendered transiently under policy but is not the canonical object representation.
- No inference execution, model routing, provider API compatibility, token streaming, or model-result claim. Milestone 28f owns the inference boundary.
- No model-controlled mutation of source, semantic objects, extractor policy, visibility, or capabilities.
- No database engine as an authority source. Any query index is rebuildable from immutable object packs and manifests.
- No automatic promotion from semantic availability to implementation, provider, Worker, security, formal-proof, or use-case acceptance.
Deliverables
1) Canonical semantic objects, views, edges, and snapshots
Purpose: Establish one compiler-owned contract so extractors, host tools, AI runs, inference, MCP, A2A, evidence, and later namespace projections cannot invent incompatible knowledge records.
Implementation requirements:
- Add versioned schemas:
semantic-snapshot/v1semantic-object/v1semantic-view/v1semantic-edge/v1semantic-extractor-receipt/v1context-capsule/v1context-render/v1.
- Each immutable object/view records source snapshot, stable logical key, content digest, object type, source span or artifact ref where applicable, extractor id/version/config hash, toolchain/profile identity, parent inputs, visibility class, required delegated scope, evidence class, and explicit unavailable/partial state.
- Separate stable logical identity from immutable materialization identity. Renames, source edits, extractor upgrades, toolchain changes, generated manifest changes, and policy changes create new versions and never mutate an accepted historical object in place.
- A snapshot records Git tree/commit identity when committed. Dirty worktrees, generated outputs, and external artifact sets use explicit content manifests and may not masquerade as the clean commit.
- Edge records are typed, directed where applicable, provenance-bound, and versioned. An edge may not outlive or silently rebind either endpoint.
2) Extractor registry, immutable object packs, and rebuildable indexes
Purpose: Ingest common ecosystem outputs without requiring bespoke project formats or making the query engine authoritative.
Implementation requirements:
- Provide bounded host extractors for:
- Git repository snapshots and diffs,
- Rust compiler/rust-analyzer and SCIP-compatible symbol/reference data,
- source, signature, documentation, AST, CFG, ownership/borrow, caller, and callee views when the selected extractor can prove them,
- unit/integration/test-result and coverage summaries,
- benchmark history,
- SARIF/security findings,
- SBOM, attestation, verification-claim, Cohesix manifest, provider receipt, and evidence-pack references.
- Every extractor is registered through the 27b integration graph with version, accepted input types, output schema ids, resource limits, secret and redaction posture, package owner, conformance runner, and observed mode.
- Store immutable object packs and manifests using existing CAS/evidence discipline. Maintain a bounded, rebuildable host-side index for lookup and traversal; deleting or corrupting the index must not destroy canonical objects or change their digests.
- Incremental extraction invalidates only objects whose exact source, tool, extractor, configuration, dependency, or policy inputs changed. Cross-snapshot edges and cache reuse require an explicit compatibility proof.
- Missing extractor support returns typed unavailable/partial state; it never fabricates an AST, CFG, ownership graph, test link, finding, or proof.
3) Deterministic Context Capsule planning and rendering
Purpose: Page knowledge by task and authority rather than concatenate whole repositories into every prompt.
Implementation requirements:
- A Context Capsule contains:
- snapshot and dependency-graph identities,
- task-intent hash/ref and requesting run/task/step identity when present,
- ordered object/view refs,
- selection reason and bounded relevance evidence for every selected view,
- candidate-set digest,
- explicitly excluded, unavailable, stale, truncated, or budget-evicted refs,
- byte and estimated-token budgets,
- visibility/delegated-scope decision refs,
- renderer/schema/tool-profile hashes,
- prefix/cache eligibility inputs,
- capsule digest and creation receipt.
- Planning is deterministic for identical objects, policy, task descriptor, budgets, extractor versions, and planner version. Tie-breaking and ordering are explicit and fixture-tested.
- Rendering supports bounded text plus structured JSON/CBOR views for downstream consumers. The rendered payload receives its own digest linked to the capsule; it never replaces the capsule as the source of context provenance.
- Selection may use lexical, graph, compiler, test, finding, and profile-selected embedding-derived signals, but each signal source and score normalization is recorded. Embeddings are derived indexes, not authority.
- Capsule expansion is explicit and produces a successor capsule linked to its predecessor; agents cannot silently widen context or authority.
4) Capability, visibility, provenance, and redaction enforcement
Purpose: Make fine-grained semantic access safer than handing every agent a repository checkout.
Implementation requirements:
- Reuse the Milestone 27b
public,ticket_scoped, andadmin_onlyvisibility classes plus generated delegated scopes for every object and view. - Derived visibility is at least as restrictive as every contributing input. Names, relationships, hashes, scores, omissions, and object existence are treated as potentially sensitive metadata, not automatically public.
- Context planning filters unauthorized candidates before ranking, rendering, token estimation, or payload construction so side channels do not reveal inaccessible objects.
- Evidence records the normalized caller, ticket hash, policy decision, selected capsule/view ids, redaction profile, and refusal reason without raw credentials or secret-bearing payloads.
- A capsule is immutable and transferable only within its recorded audience, TTL, snapshot, and policy constraints. A capsule ref is not itself authority.
5) Host tools, SDK helpers, packaging, and operator workflow
Purpose: Make the semantic substrate usable without exposing its storage implementation or requiring new agent-framework code.
Implementation requirements:
- Add host-only
coh semanticcommands for:snapshotstatusinspectquerycapsule plancapsule renderverify.
- Extend
coh doctorwith generated checks for extractor availability and version, store/index integrity, schema compatibility, source/toolchain identity, visibility policy, evidence export, and profile-selected embedding capability. Disabled or unsupported extractor deployments remain typed unavailable. - Add
cohesixPython read-only helpers for snapshots, object/view inspection, capsule planning/rendering, and receipt verification. Python consumes generated schema ids, bounds, and fixtures and cannot author authoritative semantic objects or receipts. - Add a batch-oriented
semantic-index-hostbinary and sharedcohesix-semantic-corelibrary. The indexer has no VM component or public listener; later gateways consume the same core/store contract rather than a second schema. - Package exact extractor/runtime versions, schema registry, default policy, service/job definitions where applicable, doctor checks, and conformance fixtures in the existing 27b host deployment profiles.
- Update
docs/HOST_TOOLS.md,docs/PYTHON_SUPPORT.md,docs/ARCHITECTURE.md,docs/INTERFACES.md,docs/SECURITY.md,docs/TEST_PLAN.md, anddocs/OPERATOR_WALKTHROUGH.mdwith the host-only topology, canonical commands, trust boundaries, failure recovery, and evidence workflow. cohshgains no semantic command or grammar in this milestone. It remains a consumer of existing target paths; semantic access is host-side until later generated projections are separately accepted.
6) Semantic conformance, evidence, and performance
Purpose: Prove that semantic compression comes from justified selection, not silent omission or lossy untraceable summarization.
Implementation requirements:
- Add checked fixture repositories and imported analyzer/test/benchmark/finding artifacts with stable expected objects, edges, unavailable states, and capsules.
- Conformance covers clean and dirty snapshots, rename/edit/incremental invalidation, extractor/version drift, stale/corrupt index rebuild, path and symlink attacks, unauthorized edge traversal, redaction, deterministic ordering, budget eviction, and capsule expansion.
- Evidence packs and timelines include snapshot, extractor, object-pack, capsule, render, visibility, and refusal receipts while retaining original analyzer/test/proof evidence classes.
- Add benchmarks for cold snapshot extraction, incremental refresh, object/view lookup, bounded graph traversal, capsule planning/rendering, index rebuild, and evidence export. Report object/edge counts, bytes, estimated tokens, cache hits/misses, invalidation reasons, p50/p95 latency, and artifact sizes.
- Semantic benchmarks are host-side. They do not prove Pi/QEMU runtime performance, LLM quality, inference determinism, or provider cache hits.
Commands
cargo test -p cohesix-semantic-corecargo test -p semantic-index-hostcargo test -p coh --test semanticcargo test -p coh --test semantic_evidencecargo test -p coh-rtcpython3 -m pytest -q tools/cohesix-py/tests/test_semantic.pyscripts/ci/semantic_conformance_run.sh --state-dir out/semantic/m28bscripts/ci/semantic_perf_probe.sh --state-dir out/bench/m28b-semanticscripts/check-generated.shscripts/ci/test_plan_run.sh --state-dir out/test-plan/m28b-semantic
Checks (Definition of Done)
- Identical snapshot, extractor, toolchain, configuration, policy, planner, and budget inputs produce byte-identical object packs, indexes after rebuild, capsules, renders, and receipts.
- Dirty, stale, partial, unsupported, mismatched-toolchain, or mismatched-extractor state is explicit and cannot pass as a clean accepted snapshot.
- Source/compiler/analyzer/test/benchmark/finding/proof authority and evidence classes remain distinct; a semantic edge or capsule never upgrades them.
- Unauthorized objects and relationships are removed before ranking or payload construction, and negative tests show no metadata, size, score, or existence disclosure across visibility boundaries.
- An unavailable extractor yields typed unavailable views; no synthetic AST, CFG, ownership, test, security, benchmark, or proof object can enter a production capsule.
- The canonical store survives index deletion/rebuild and detects corrupt, forged, missing, duplicate, or cross-snapshot objects and edges.
- Context Capsules record exact selected and omitted views, reasons, budgets, policy, renderer, and lineage; expansion creates a new linked capsule rather than mutating the original.
coh, Python, evidence tools, generated docs, packages, and future gateway schema inputs consume one schema registry and agree on bounds and receipts.coh doctordistinguishes required failures from disabled or unsupported extractors and reports enough identity to reproduce a snapshot/capsule.- Host performance evidence demonstrates bounded incremental refresh, lookup, planning, rendering, and evidence overhead at representative repository scales. Token/byte avoidance is reported without claiming model-quality or inference-speed improvement that was not measured downstream.
- No VM dependency, listener, namespace root, console verb, Secure9P verb, provider mutation, inference call, or agent-framework authority is added.
Compiler touchpoints
coh-rtcextends the Milestone 27b graph with semantic extractor, store, planner, renderer, host-tool, package, and evidence surfaces. Each record has stable ids, version/profile bounds, visibility, redaction, schema outputs, observed mode, conformance owner, and explicit unavailable behavior.coh-rtcemits the semantic schema registry, object/view/edge type tables, extractor allowlists, snapshot and capsule bounds, visibility rules, renderer profiles, metric/evidence bounds, Python defaults,cohdefaults, doctor checks, package manifests, and documentation snippets.- Validation rejects unknown object/view/edge types, unregistered extractors, mutable accepted objects, unbounded graph walks, visibility weakening, capsule refs without snapshot/policy identity, hand-maintained Python schema catalogs, and enabled public surfaces without packages/conformance evidence.
- Generated semantic records extend, and never fork, the existing
host-integration-dependency/v1and use-case graph.
Task Breakdown
Title/ID: m27c-semantic-ir-and-object-contract
Milestone: 28b / semantic IR and object contract
Goal: Define compiler-owned semantic snapshot, object, view, edge, extractor-receipt, capsule, and render schemas with stable identity and authority rules.
Inputs: Milestone 27b provider/integration/visibility/evidence registries, tools/coh-rtc/src/**, existing CAS and evidence schemas, docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/SECURITY.md.
Changes:
- tools/coh-rtc/src/ir.rs + validation/codegen — semantic types, extractor registry, snapshot/capsule/render bounds, visibility/redaction derivation, and generated Rust/Python/docs outputs.
- crates/cohesix-semantic-core/src/schema.rs — canonical host-side types and strict validators generated or checked against `coh-rtc`.
- tests/fixtures/semantic/** — canonical valid, invalid, partial, stale, cross-snapshot, and visibility fixtures.
- docs/ARCHITECTURE.md + docs/INTERFACES.md + docs/SECURITY.md — object identity, source-of-truth, authority, provenance, redaction, and host/VM boundaries.
Commands:
- cargo test -p coh-rtc
- cargo test -p cohesix-semantic-core
- scripts/check-generated.sh
Checks: Every semantic type and bound is compiler-owned; logical and immutable identities cannot be conflated; unknown, mutable, cross-snapshot, unproven, or visibility-weakened records fail closed.
Deliverables: One generated semantic schema registry shared by all later extractors, host tools, AI runs, inference, MCP/A2A, and evidence consumers.
Title/ID: m28b-extraction-store-and-index
Milestone: 28b / extraction, immutable packs, and rebuildable index
Goal: Materialize common repository and analysis outputs into immutable semantic packs with deterministic incremental invalidation and a non-authoritative rebuildable index.
Inputs: m27c-semantic-ir-and-object-contract, Git/source fixtures, compiler/rust-analyzer/SCIP outputs, test/coverage/benchmark/SARIF/SBOM/verification/evidence fixtures, existing CAS helpers.
Changes:
- crates/cohesix-semantic-core/src/{extract,store,index}.rs — bounded extractor contract, object-pack verification, atomic publication, deterministic index build/rebuild, and incremental invalidation.
- apps/semantic-index-host/src/** — batch snapshot/extraction/index command with exact tool/extractor identity, resource bounds, and typed partial/unavailable results.
- scripts/ci/semantic_conformance_run.sh + fixtures — cross-extractor, corruption, stale-index, symlink/path, rename/edit, and deterministic rebuild coverage.
- docs/HOST_TOOLS.md + docs/TEST_PLAN.md — extractor availability, operation, recovery, and conformance guidance.
Commands:
- cargo test -p cohesix-semantic-core
- cargo test -p semantic-index-host
- scripts/ci/semantic_conformance_run.sh --only extraction,index --state-dir out/semantic/m28b-extraction
Checks: Canonical packs are immutable and content-addressed; index loss is recoverable; changed inputs invalidate exact dependents; unsupported extractors are explicit; no imported evidence class is strengthened.
Deliverables: Persistent host semantic snapshots that can be incrementally refreshed and independently verified.
Title/ID: m28b-context-capsule-planner
Milestone: 28b / deterministic Context Capsule planning and rendering
Goal: Select and render the smallest authorized semantic working set that satisfies explicit task and budget inputs while preserving exact omissions and lineage.
Inputs: m28b-extraction-store-and-index, generated visibility policy, representative repo-analysis task fixtures, token estimators and renderer profiles.
Changes:
- crates/cohesix-semantic-core/src/{planner,capsule,render}.rs — deterministic candidate construction, authority filtering, ranking, budget eviction, expansion lineage, text/JSON/CBOR rendering, and receipt generation.
- tests/fixtures/semantic/capsules/** — stable selection, tie-break, omission, truncation, unavailable, expansion, and renderer fixtures.
- scripts/ci/semantic_perf_probe.sh — capsule planning/render and semantic-paging measurements at representative scales.
- docs/INTERFACES.md + docs/BENCHMARKS.md — capsule contract, semantic paging metrics, and non-claims.
Commands:
- cargo test -p cohesix-semantic-core --test context_capsules
- scripts/ci/semantic_perf_probe.sh --state-dir out/bench/m28b-semantic
Checks: Identical admitted inputs produce byte-identical capsules/renders; unauthorized candidates are filtered before scoring; every inclusion, omission, expansion, and truncation is reconstructable.
Deliverables: Auditable Context Capsules suitable for 28e AI runs and 28f inference without repository-wide prompt assembly.
Title/ID: m28b-host-tools-sdk-and-evidence
Milestone: 28b / host tools, Python helpers, doctor, and evidence
Goal: Make semantic snapshots and Context Capsules operable through existing Cohesix host-tool and evidence workflows without creating new authority.
Inputs: m28b-context-capsule-planner, apps/coh/src/{main.rs,doctor.rs,evidence.rs,evidence_timeline.rs}, tools/cohesix-py/cohesix/**, tools/coh-rtc generated host defaults, packaging profiles, canonical host-tool docs.
Changes:
- apps/coh/src/semantic.rs + CLI wiring — `snapshot`, `status`, `inspect`, `query`, `capsule plan`, `capsule render`, and `verify`.
- apps/coh/src/{doctor,evidence,evidence_timeline}.rs — semantic store/extractor/schema checks plus snapshot/object/capsule/render/refusal evidence reconstruction.
- tools/cohesix-py/cohesix/{semantic.py,context.py,evidence.py} + tests — generated read-only helpers and canonical receipt validation; Python cannot mint authoritative objects/capsules/receipts.
- tools/coh-rtc/src/codegen/{coh,cohesix_py,docs}.rs + package manifests — generated defaults, doctor checks, examples, exact binary/extractor contents, and docs snippets.
- docs/HOST_TOOLS.md + docs/PYTHON_SUPPORT.md + docs/OPERATOR_WALKTHROUGH.md + docs/TEST_PLAN.md — end-to-end operator workflow and failure recovery.
Commands:
- cargo test -p coh --test semantic
- cargo test -p coh --test semantic_evidence
- python3 -m pytest -q tools/cohesix-py/tests/test_semantic.py
- scripts/check-generated.sh
Checks: Rust and Python render the same generated schemas/bounds and verify the same fixtures; doctor distinguishes disabled/unsupported extractors from missing or corrupt required state; evidence reconstruction needs no raw prompt or secret.
Deliverables: Installable, diagnosable semantic host tools and SDK helpers integrated with existing Cohesix evidence workflows.
Title/ID: m28b-semantic-acceptance
Milestone: 28b / conformance, performance, and release acceptance
Goal: Prove the semantic substrate is deterministic, bounded, authority-preserving, package-complete, and ready for 28e/28f consumers.
Inputs: all m28b tasks, generated provider/integration/package records, semantic fixtures, docs/BENCHMARKS.md, docs/TEST_PLAN.md, release evidence checklist.
Changes:
- scripts/ci/semantic_conformance_run.sh — complete extractor/store/index/capsule/visibility/redaction/evidence matrix with archived summaries.
- scripts/ci/semantic_perf_probe.sh — cold/incremental/index-rebuild/query/capsule/render/evidence timing and size ledger.
- scripts/ci/use_case_gate.sh + release packaging — require accepted semantic dependencies only for use cases that claim semantic context; preserve typed unavailable mode elsewhere.
- docs/BENCHMARKS.md + docs/TEST_PLAN.md + release checklist — semantic acceptance lane, thresholds, artifacts, and explicit inference/model-quality non-claims.
Commands:
- scripts/ci/semantic_conformance_run.sh --state-dir out/semantic/m28b
- scripts/ci/semantic_perf_probe.sh --state-dir out/bench/m28b-semantic
- scripts/ci/test_plan_run.sh --state-dir out/test-plan/m28b-semantic
Checks: Conformance, package, authority, evidence, and performance artifacts all bind the same schema/snapshot/toolchain identities; no mock, partial, dirty, stale, or unsupported state is promoted.
Deliverables: Accepted semantic object and Context Capsule substrate for Milestone 28c and Milestones 28e, 28f, 28g, and 30b.
Outcome
After Milestone 28b:
- Cohesix has a persistent host-side semantic object fabric without adding AI runtimes, compiler frontends, graph databases, or listeners to the VM.
- Repository, compiler, analyzer, test, benchmark, finding, proof, provider, and evidence inputs remain distinct and provenance-bound while becoming queryable through one generated object/edge contract.
- Context Capsules make the exact authorized semantic working set, omissions, budgets, renderer, and lineage explicit and reproducible.
coh,coh doctor, Python helpers, evidence packs, timelines, packages, and downstream gateway schemas consume one generated semantic contract.- Milestone 28c can bind semantic refs where relevant without treating capsule contents as authoritative operational facts; Milestone 28e can then build run/checkpoint policy on admitted immutable capsule refs, and Milestone 28f can measure actual inference efficiency and audit receipts without treating text prompts as the semantic source of truth.
Title/ID: m28b-semantic-workbench-inspector
Milestone: 28b / semantic-workbench-inspector
Goal: Expose semantic objects, edges, provenance, Context Capsules, selection and render receipts through the accepted SwarmUI workbench without UI-owned authority.
Inputs: 27f workbench; this milestone's accepted owner schemas, read/verify libraries and evidence.
Changes:
- Rust UI adapters and Spectrum inspectors — bounded immutable reads, exact source/hash/visibility and evidence links; no duplicate schema or direct provider execution.
- UI/native tests and documentation — tamper, stale/missing evidence, denied reads, unknown facts and persistent source/proof modes; no placeholder counts as implementation.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: The inspector verifies the owner records through shared libraries independently of MCP/A2A; UI caches or screenshots cannot strengthen evidence.
Deliverables: Backend-owned, qualified workbench inspector.
Milestone 32 — General Machine-Checked Admission and Proof Artefacts
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain the general restricted-policy IR, authoritative-fact snapshots, seven-verdict engine, solver/evaluator correspondence, decision witnesses, independently checked proof artefacts and richer inspection. Extend the tested narrow admission from 28 only for demonstrated policy needs. Never create a competing grant issuer or weaken current-state checks.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 28c; current owner 32
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Status: Planned — after the 27g release; preserve existing implementation and evidence.
Delivery posture: Implement the complete admission contract and every listed reference action and host-tool integration. Consequential actions require exact facts, policy, grants, stale-state refusal, and receipts. Read-only inspection, dry-run, and capsule rendering remain non-mutating operations, not alternate milestone completion paths.
Why now (authority admission bridge): 28 supplies formal IR, 27a delegation, 27b the action registry, and optional 28b provenance. Bind them into one admission sequence:
untrusted intent
-> typed intent
-> authoritative fact snapshot
-> machine-checked policy decision
-> state-bound authority grant
-> ticket, lease, provider action, or later Worker authority
-> authoritative outcome receipt
Model, operator, workflow, MCP, and A2A requests share this gate: execution requires versioned policy and authoritative current facts.
As-built alignment note: Generated policy rules, one-shot approvals, tickets, allowlists, leases, audits, and receipts do not yet supply typed intents, authoritative fact snapshots, seven-verdict admission, witnesses, or state-bound grants. Model confidence or SMT strings cannot substitute. No LLM, solver, general policy graph, or new protocol enters the VM.
Prerequisites
- Completed 28a provider extensions and 28b semantic contract.
- The Milestone 28, including
m28-policy-ir-proof-foundation, completed for the accepted policy fragment, consistency/non-vacuity checks, generated solver/evaluator correspondence evidence, claim vocabulary, verifier identity, and proof-class separation. - The Milestone 27a completed for delegated identity, strict idempotency, writer-epoch fencing, durable execution, audit/replay, evidence correlation, and production secret discipline.
- The exact Milestone 27b provider/action rows completed for the selected consequential actions, including external-executor and authoritative-receipt contracts, identity mapping, packaging, and conformance evidence.
- Milestone 28b completed for semantic/capsule adapter qualification. At runtime, non-semantic actions require neither snapshot nor capsule refs; optional inputs cannot become a blanket admission requirement.
Goal
- Convert untrusted requests into bounded, versioned typed intents.
- Evaluate each typed intent against compiler-owned policy and an exact authoritative fact snapshot.
- Return exactly one of
proved,refuted,under_specified,inconsistent,indeterminate,invalid_input, orstale_state. - Permit authority issuance only for
proved. - Bind each successful decision to the exact intent, subject, target, policy id/hash, manifest hash, fact snapshot, state epoch, relevant resource generations, requested and granted scopes, expiry, idempotency state, and writer epoch where applicable.
- Issue authority equal to or narrower than the admitted scope and limits.
- Preserve Queen/root authority as the final target-side mutation and authority boundary; host admission never creates a parallel executor or target authority path.
- Produce deterministic evidence reconstructable through audit, replay, evidence packs, timelines, provider receipts, and later Worker receipts.
- Keep static verification, runtime admission, formal proof artefacts, QEMU, Pi 4 hardware evidence, and host-provider evidence as separate proof classes.
Non-negotiable constraints
- No LLM output is authority. Model confidence is never an admission result.
- Caller assertions and model-extracted assertions are not authoritative facts. Context Capsule contents are semantic inputs, not automatically operational facts.
- An admission record is not transferable between intents, targets, policies, manifests, subjects, state epochs, resource generations, scopes, or expiries.
- An SMT
SATorUNSATstring from a host process is not sufficient target authority. An unsat core is an explanation artefact; it is not automatically minimal and is not automatically a proof object. - A decision witness, explanation core, and formal proof artefact are distinct evidence classes. Proof claims may not exceed the exact checked artefact and declared checker.
- Large solver and model runtimes remain host-side. A target path may use a generated bounded deterministic evaluator or verify a genuinely checkable certificate; it must not blindly trust a host verdict string.
- No new console verb, Secure9P verb, in-VM listener, RPC authority path, mutable policy path, or alternate ticket path is introduced. Existing provider, ticket, lease, host-executor, audit, replay, evidence, and Worker authority paths remain canonical.
- Missing data, stale state, contradiction, unsupported policy, verifier
timeout, verifier
unknown, verifier failure, resource exhaustion, and malformed input fail closed. writer_epochidentifies the current writer or authority owner.state_epochand resource generations identify the state against which the decision was made. They remain separate fields with separate validation.- QEMU, Pi 4, host provider, static verifier, bounded model-checking, and inherited seL4 evidence remain separate proof classes.
1) Canonical intent, fact, decision, witness, and grant contracts
Purpose: Establish one compiler-owned contract shared by policies, providers, tickets, leases, host tools, later protocols, evidence, and Worker binding.
Implementation requirements:
- Add versioned schemas or schema families with canonical generated names
equivalent to:
intent-request/v1intent-subject/v1intent-target/v1authoritative-fact/v1authoritative-fact-snapshot/v1policy-evaluation/v1admission-decision/v1decision-witness/v1authority-grant/v1.
- An intent request includes or cryptographically binds
intent_id,intent_schema,intent_hash,subject,requested_action,target,requested_scope,requested_limits,idempotency_key,writer_epoch,deadline,source_protocol, and, when relevant,semantic_snapshot_refandcontext_capsule_ref. - An admission decision includes or binds
admission_id,intent_hash,policy_id,policy_version,policy_hash,manifest_hash,fact_snapshot_hash,state_epoch,resource_generations,verdict,reason_codes,explanation_core,proof_artifact_ref,requested_scope,granted_scope,grant_expiry, andevidence_class. - Non-semantic operations must not be forced to invent a semantic snapshot or Context Capsule reference. Unknown optional refs remain absent, not empty evidence.
2) Restricted policy IR and generated correspondence
Purpose: Generate every checked policy representation from one bounded source rather than hand-maintain solver and runtime logic.
Implementation requirements:
- Initially admit only Booleans, bounded integers, enums, generated registry identifiers, bounded sets, linear comparisons, conjunction, disjunction, negation, and explicit required-fact declarations.
- Exclude or defer unrestricted strings, quantifiers, arbitrary code, user-supplied expressions, arbitrary solver theories, dynamic policy execution, and free-form natural-language policy as runtime truth.
- One policy source generates or checks the canonical policy representation,
host-side solver constraints for consistency checks and counterexamples,
deterministic Rust evaluator, target-compatible
no_stdpolicy tables or evaluator where required, canonical positive/negative vectors, documentation snippets, policy hashes, decision/evidence schemas, and provider-action admission metadata. - Differential/correspondence checks cover every generated representation. Hand-maintained solver logic and runtime evaluator logic may not drift independently.
- Establish base-fact and policy consistency before attempting claim proof or refutation. Reject inconsistent or vacuous policy according to the declared policy class and evidence rules.
3) Authoritative fact snapshots
Purpose: Bind admission to current accepted Cohesix state rather than caller or model assertions.
Implementation requirements:
- Every fact records fields equivalent to
source_id,source_class,subject_or_resource,sequence,state_epoch,resource_generation,observed_at,expires_at,value, andevidence_ref. - Classify authoritative facts, provider-reported facts, caller assertions, model-extracted assertions, derived facts, unknown facts, stale facts, and contradictory facts without silently promoting one class into another.
- Authoritative facts may come from accepted generated manifest state, Worker
lifecycle/generation, tickets and leases, policy approvals, provider registry
state, validator-accepted provider receipts, GPU/resource inventory, target
/procstate, configured attestation evidence, and bounded target/provider counters. - A model may propose an intent or extract candidate fields, but it cannot mark those values authoritative. Provider-reported facts become authoritative only through the exact accepted validator/adapter rule for that policy.
- Snapshot construction detects missing, wrong-source, forged, stale, reordered, duplicate, wrong-generation, and contradictory facts before evaluation.
4) Deterministic verdict engine
Purpose: Make refusal semantics explicit and prevent solver uncertainty or incomplete information from becoming authority.
| Verdict | Required meaning | Authority result |
|---|---|---|
proved |
Available authoritative facts establish the policy predicate. | Grant may proceed. |
refuted |
Available authoritative facts establish the predicate is false. | Deny. |
under_specified |
Available facts permit both acceptance and rejection. | Deny. |
inconsistent |
Base facts or policy assumptions conflict. | Deny. |
indeterminate |
Timeout, unsupported fragment, solver unknown, verifier failure, or resource bound. | Deny. |
invalid_input |
Intent, facts, policy selection, or bounds are malformed. | Deny. |
stale_state |
Relevant state changed or expired before grant or execution. | Deny or re-evaluate. |
Only proved may lead to a grant. The engine first checks base-fact and policy
consistency, then evaluates proof/refutation/under-specification. It must not
collapse results into an incorrect three-state partition.
5) State-bound authority issuance
Purpose: Prevent a correct decision over old state from becoming authority over new state.
Implementation requirements:
- Use an atomic or state-bound pattern appropriate to the action:
evaluate + reserve + issue
evaluate
-> compare-and-swap against state/resource generation
-> issue
evaluate
-> recheck bounded runtime predicates
-> issue or execute
- Enforce invariants equivalent to:
grant.scope <= admitted.scope
grant.target = admitted.target
grant.subject = admitted.subject
grant.policy_hash = admitted.policy_hash
grant.intent_hash = admitted.intent_hash
grant.state_epoch = admitted.state_epoch
grant.resource_generation = admitted.resource_generation
grant.expiry <= admitted.expiry
Here <= means set/subscope containment, not string-prefix matching.
- If relevant state changes, the grant fails, expires, or is re-evaluated. A successful decision cannot be replayed against a different resource generation.
- Queen/root remains the final target-side mutation and authority boundary. Host-side admission authorizes only the existing bounded ticket, lease, or provider-action path selected by the generated registry.
6) Decision evidence, audit, replay, and receipts
Purpose: Extend the existing Cohesix evidence graph instead of creating a second admission ledger.
Terminology is normative:
- Decision witness: canonical facts, policy identity, bindings, result, and state needed to reproduce the decision.
- Explanation core: a bounded subset of relevant assertions or predicates explaining denial, contradiction, or inconsistency. It need not be minimal.
- Proof artefact: an independently machine-checkable derivation accepted by a declared checker.
Do not call every admission result a proof. “Proof-Carrying Intent” may be used as an external description only for policy classes that actually carry an independently checked proof artefact; the normative primitive remains Machine-Checked Intent Admission.
Evidence reconstructs:
caller
-> typed intent
-> authoritative facts
-> policy identity
-> admission decision
-> authority grant
-> provider, executor, or Worker outcome
Integrate admission records with /audit/decisions, /replay/*, evidence
packs, evidence timelines, host-ticket receipts, provider/executor receipts,
inference receipts, later Worker receipts, and applicable NIST/assurance
evidence refs. Secrets, raw tickets, provider credentials, and sensitive
payloads remain redacted. Tamper, proof-reference mismatch, missing predecessor,
and identity mismatch fail verification.
7) Bounded reference admission actions
Purpose: Prove the contract on one resource-allocation action and one host remediation action before later consumers broaden adoption.
GPU lease admission
- Check that the selected Worker or provider is ready; the requested GPU or accelerator exists; inventory generation is current; no conflicting lease exists; memory/capacity and duration are within limits; subject quota is sufficient; model/workload/action class is approved; and ticket/lifecycle scopes are valid.
- Reconstruct
intent -> GPU/Worker/inventory/quota/lease facts -> admission decision -> lease grant -> provider execution or lease observation -> provider and, where applicable, Worker receipt.
Bounded host remediation
- Use the existing allowlisted
systemd.restartprovider action; never accept an arbitrary shell command. - Check that the unit is registered and allowlisted, subject remediation scope is sufficient, provider state is fresh, unit state permits restart, restart budget is not exhausted, maintenance/policy window permits the action, writer epoch is current, and target generation has not changed.
8) Security, performance, and documentation ownership
Purpose: Bound abuse and record exact implementation ownership without promoting planned documentation to as-built state.
Implementation requirements:
- Measure policy evaluation, fact snapshot construction, state recheck or reservation, grant issuance, evidence emission, solver/verifier overhead, and target evaluator overhead separately.
- Do not classify host admission measurements as Pi hardware throughput proof unless the exact Pi target path is exercised with fresh evidence.
- Negative tests cover prompt injection, caller claims marked authoritative, untrusted policy selection, arbitrary expression injection, oversized/fact- count overflow, contradictory/stale/reordered facts, decision replay, grant widening, proof substitution, solver timeout, verifier crash, target/host disagreement, and secret leakage.
- Implementation tasks later update
docs/ARCHITECTURE.md,docs/INTERFACES.md,docs/SECURITY.md,docs/FORMAL_VERIFICATION.md,docs/ROLES_AND_SCHEDULING.md,docs/WORKER_TICKETS.md,docs/TEST_PLAN.md,docs/BENCHMARKS.md,docs/HOST_API.md,docs/HOST_TOOLS.md, anddocs/PYTHON_SUPPORT.mdas their owned surfaces land. This planning edit does not claim those documents are already updated.
Consumer ownership
- Milestone 28e owns admission for AI runs, PEFT, model promotion, checkpoints, prefixes, and agent-supervisor actions.
- Milestone 28f owns inference-request, provider/model routing, and inference-receipt admission.
- Milestone 28g owns MCP/A2A projection of admitted actions.
- Milestone 28d owns production binding from an admission decision to the live Worker ticket/lease, capability bundle, generation, fault lifecycle, and quarantine state. Milestone 28c alone is not production Worker authority proof.
- Milestone 30b owns bounded read-only namespace projections of admission state and adds no AI-specific write path.
Commands
cargo test -p coh-rtccargo test -p host-ticket-agentcargo test -p coh --test admission_evidencepython3 -m pytest -q tools/cohesix-py/tests/test_admission.pyscripts/ci/verification_gate.sh --policy-ir-only --state-dir out/verification/m28c-policyscripts/ci/admission_conformance_run.sh --state-dir out/admission/m28cscripts/ci/admission_perf_probe.sh --state-dir out/bench/m28c-admissionscripts/check-generated.shscripts/ci/test_plan_run.sh --state-dir out/test-plan/m28c-admission
Checks (Definition of Done)
- One compiler-owned intent, fact, policy, decision, witness, and grant contract is consumed by Rust, Python, providers, host tools, evidence, and later protocol projections.
- Identical admitted inputs produce byte-identical decisions and deterministic evidence outputs.
- Unsupported, stale, inconsistent, malformed, unknown, and under-specified
cases fail closed; only
provedcreates a grant. - Grants cannot exceed the admitted action, scope, target, subject, limits, or expiry, and a state/resource generation change prevents stale issuance.
- The target does not blindly trust host verdict text. Solver constraints and runtime evaluators derive from one restricted IR and pass correspondence checks.
- Every authoritative fact has source, sequence, freshness, generation, and evidence metadata. Caller/model assertions remain non-authoritative unless a generated policy explicitly admits that assertion class as a non-operational input; it cannot silently upgrade it to an authoritative fact.
- GPU lease and bounded
systemd.restartadmission pass end to end with exact state-generation binding, provider receipt correlation, deterministic denial, and stale-state cases. - Evidence packs and timelines reconstruct the intent-to-outcome chain without conflating decision witness, explanation core, and proof artefact.
- No new in-VM solver, LLM, listener, protocol, provider runtime, shell executor, mutable policy engine, or alternate authority path is introduced.
- No current or planned feature becomes implemented, accepted, target- qualified, or production-proven merely because this plan exists.
Compiler touchpoints
- Extend the current
tools/coh-rtc/src/ir.rs,lib.rs, andcodegen/{rust,coh,cohesix_py,docs}.rsstructure with the restricted policy, intent, fact, decision, witness, grant, provider-admission metadata, validation, hashes, fixtures, and deterministic generated outputs. A later internal module split must not create a second source of truth. - Generated Rust and target-required tables remain
no_std; host solver and verifier adapters remain host-side. - Validation rejects unknown schemas/facts/policies/actions, unsupported
fragments, caller-selected policy authority, policies whose required-fact
declarations are missing or inconsistent,
decision/grant substitution, scope widening, stale generations, duplicate
authority, hand-edited generated output, and provider actions lacking an
accepted admission policy. At runtime, an absent declared fact produces the
specified fail-closed
under_specified,invalid_input, orstale_stateverdict according to the exact schema/state condition; it is never silently assumed. - Generated admission records extend the existing 27b
host-integration-dependency/v1, provider/action, authoritative-receipt, and evidence graphs. They do not create parallel policy, provider, or evidence registries.
Task Breakdown
Title/ID: m28c-intent-policy-ir
Milestone: 28c / compiler-owned intent and policy contracts
Goal: Define compiler-owned intent, subject, target, fact, policy-evaluation, admission-decision, decision-witness, and authority-grant schemas.
Inputs: accepted m28-policy-ir-proof-foundation, tools/coh-rtc/src/{ir.rs,lib.rs,codegen/**}, 27a authority records, 27b provider/action registry, 28b semantic/capsule schemas, docs/INTERFACES.md, docs/SECURITY.md.
Changes:
- tools/coh-rtc/src/ir.rs + validation/codegen — versioned bounded schema families, canonical hashes, required/optional semantic refs, provider admission metadata, Rust/Python/manifest/docs outputs, and negative validation.
- generated Rust/Python/docs fixtures — canonical valid, malformed, unsupported, cross-policy, cross-target, and cross-subject vectors without hand-edited generated catalogs.
- docs/INTERFACES.md + docs/SECURITY.md — implementation-stage schema, authority, redaction, and refusal contract.
Commands:
- cargo test -p coh-rtc
- scripts/check-generated.sh
Checks:
- All schema ids, fields, bounds, hashes, and provider mappings are compiler-owned; unknown, malformed, overbroad, caller-selected-policy, or drifted records fail closed.
Deliverables:
- One generated intent-to-grant contract for all later consumers.
Title/ID: m28c-authoritative-fact-snapshots
Milestone: 28c / authoritative fact snapshots
Goal: Bind policy inputs to exact source, sequence, state epoch, resource generation, TTL, provenance, and evidence class.
Inputs: m28c-intent-policy-ir, generated manifest/lifecycle/ticket/lease/provider registries, accepted provider receipts, target `/proc` fixtures, attestation and bounded-counter fixtures.
Changes:
- admission core fact modules + generated source registry — canonical fact ingestion, source/sequence/freshness/generation checks, deterministic snapshots, contradiction detection, and evidence refs.
- canonical fixtures — authoritative, asserted, derived, unknown, stale, contradictory, missing, wrong-source, wrong-generation, forged, duplicate, and reordered facts.
- docs/ARCHITECTURE.md + docs/SECURITY.md + docs/TEST_PLAN.md — source authority, freshness, contradiction, redaction, and evidence-class rules.
Commands:
- cargo test -p cohesix-admission-core --test facts
- scripts/ci/admission_conformance_run.sh --only facts --state-dir out/admission/m28c-facts
Checks:
- Only registered accepted sources can supply authoritative facts; every snapshot is deterministic and binds source, sequence, epoch, generation, expiry, and evidence; forged or ambiguous provenance fails closed.
Deliverables:
- Reconstructable authoritative fact snapshots that never promote caller/model assertions.
Title/ID: m28c-policy-compiler-and-evaluator
Milestone: 28c / policy compiler and deterministic evaluator
Goal: Generate host solver constraints, deterministic Rust and target-compatible evaluators, canonical fixtures, policy hashes, and correspondence checks from one restricted IR.
Inputs: m28-policy-ir-proof-foundation, m28c-intent-policy-ir, tools/coh-rtc, verifier adapters, canonical policy fixtures.
Changes:
- tools/coh-rtc/src/ir.rs + codegen — restricted policy AST, required-fact declarations, canonicalization, hashes, host constraints, deterministic Rust/`no_std` tables, docs, and positive/negative vectors.
- verification tooling — consistency, non-vacuity, unsupported-fragment, counterexample, differential, and target/host correspondence checks.
- generated-output guard — reject hand-edited solver constraints, evaluator tables, hashes, docs, and vectors.
Commands:
- cargo test -p coh-rtc
- scripts/ci/verification_gate.sh --policy-ir-only --state-dir out/verification/m28c-policy
- scripts/check-generated.sh
Checks:
- Generated outputs agree for every canonical vector; solver/evaluator disagreement, unsupported fragment, vacuous or inconsistent policy, and hand-edited output fail deterministically.
Deliverables:
- One restricted policy source with checked host and target representations.
Title/ID: m28c-admission-verdict-engine
Milestone: 28c / seven-verdict admission engine
Goal: Implement all seven verdict classes with deterministic fail-closed semantics.
Inputs: m28c-authoritative-fact-snapshots, m28c-policy-compiler-and-evaluator, canonical intent/fact/policy vectors.
Changes:
- crates/cohesix-admission-core/src/{evaluate,verdict}.rs — base consistency, proof, refutation, under-specification, invalid-input, indeterminate, and stale-state evaluation with bounded reason codes.
- host and target evaluator fixtures — deterministic verdict, timeout, unknown, verifier-failure, and resource-bound parity.
- docs/FORMAL_VERIFICATION.md + docs/INTERFACES.md — verdict meaning, checker identity, witness/proof distinction, and non-claims.
Commands:
- cargo test -p cohesix-admission-core --test verdicts
- scripts/ci/admission_conformance_run.sh --only verdicts --state-dir out/admission/m28c-verdicts
Checks:
- Base inconsistency, proof, refutation, under-specification, timeout/unknown, invalid input, and stale state map to exactly the declared verdict; only `proved` can proceed to issuance.
Deliverables:
- Deterministic seven-verdict engine with bounded refusal evidence.
Title/ID: m28c-decision-bound-authority
Milestone: 28c / state-bound grant issuance
Goal: Bind proved decisions to exact tickets, leases, provider actions, targets, scopes, epochs, generations, expiries, idempotency keys, and writer epochs.
Inputs: m28c-admission-verdict-engine, 27a idempotency/fencing/WAL records, 27b provider registry, ticket/lease schemas, Queen/root mutation paths.
Changes:
- admission grant/reservation modules + host-ticket-agent integration — evaluate/reserve/CAS/recheck patterns, scope containment, exact target/subject/policy/intent binding, expiry, idempotency, writer/state epoch separation, and stale-generation refusal.
- canonical race/replay fixtures — evaluation-to-grant races, duplicate requests, writer failover, target/subject substitution, scope widening, expired decisions, and cross-resource replay.
- docs/ROLES_AND_SCHEDULING.md + docs/WORKER_TICKETS.md + docs/SECURITY.md — grant/ticket distinction and final Queen/root authority boundary.
Commands:
- cargo test -p cohesix-admission-core --test grants
- cargo test -p host-ticket-agent
- scripts/ci/admission_conformance_run.sh --only grants --state-dir out/admission/m28c-grants
Checks:
- Scope widening, target/subject substitution, expired decision, stale generation, duplicate request, stale writer, issuance race, and replay against another resource fail before authority is created.
Deliverables:
- State-bound grants that can authorize only existing canonical authority paths.
Title/ID: m28c-evidence-replay-and-proof-claims
Milestone: 28c / evidence, replay, and proof claims
Goal: Add decision witnesses, explanation cores, optional proof references, audit/replay correlation, evidence-pack integration, and exact evidence classifications.
Inputs: m28c-admission-verdict-engine, m28c-decision-bound-authority, 27b receipt/evidence core, apps/coh/src/{evidence.rs,evidence_timeline.rs}, `/audit/decisions`, `/replay/*`, NIST/assurance claim registry.
Changes:
- admission evidence core — canonical witness/explanation/proof-ref records, predecessor hashes, redaction, deterministic rendering, and tamper verification.
- apps/coh/src/{evidence.rs,evidence_timeline.rs} — caller-to-intent-to-facts-to-policy-to-decision-to-grant-to-outcome reconstruction using existing evidence packs/timelines.
- docs/FORMAL_VERIFICATION.md + docs/TEST_PLAN.md + docs/BENCHMARKS.md — evidence classes, proof wording, reconstruction, redaction, and performance/non-claim lanes.
Commands:
- cargo test -p coh --test admission_evidence
- scripts/ci/admission_conformance_run.sh --only evidence --state-dir out/admission/m28c-evidence
Checks:
- Witness reconstruction, tamper detection, proof-reference mismatch, non-minimal explanation-core handling, redaction, and deterministic evidence output pass; no ordinary decision is mislabeled as a formal proof.
Deliverables:
- Admission evidence integrated with the existing audit/replay/evidence graph.
Title/ID: m28c-reference-admission-actions
Milestone: 28c / bounded reference actions
Goal: Prove GPU lease admission and one allowlisted `systemd.restart` remediation action end to end.
Inputs: all prior m28c tasks, 27b `gpu.lease.grant` and `systemd.restart` provider-action records, GPU/Worker/inventory/quota/lease fixtures, host-ticket-agent, provider receipts.
Changes:
- reference policy records and fixtures — exact GPU lease and systemd restart required facts, scopes, quotas, generations, reservations/rechecks, and deterministic denial cases.
- host-ticket-agent/provider integration — admitted existing actions only, with exact decision/grant ids and provider receipt correlation; no direct executor bypass or arbitrary shell.
- evidence acceptance lane — mock/fixture plus host-safe live or dry-run evidence where appropriate, keeping provider and target evidence classes separate.
Commands:
- cargo test -p host-ticket-agent --test admission_actions
- scripts/ci/provider_conformance_run.sh --provider gpu.lease.grant,systemd.restart --admission --state-dir out/provider-conformance/m28c-actions
- scripts/ci/admission_conformance_run.sh --only reference-actions --state-dir out/admission/m28c-actions
Checks:
- Both actions preserve exact state-generation binding, provider receipt correlation, deterministic denial/stale-state behavior, and existing executor paths; no direct provider or Worker bypass exists.
Deliverables:
- Two bounded end-to-end reference flows proving resource and remediation admission.
Title/ID: m28c-admission-security-and-performance
Milestone: 28c / security and performance acceptance
Goal: Add targeted abuse-resistance, correspondence, performance, package, and release gates for machine-checked admission.
Inputs: all m28c tasks, canonical negative corpus, scripts/ci/admission_{conformance_run,perf_probe}.sh, docs/TEST_PLAN.md, docs/BENCHMARKS.md, package/evidence manifests.
Changes:
- admission security corpus — injection, forged authority, untrusted policy selection, arbitrary expression, oversized/overflow/contradictory/reordered facts, replay, widening, proof substitution, timeout/crash, host/target disagreement, and secret leakage.
- scripts/ci/admission_perf_probe.sh — separate fact, evaluation, reservation/recheck, grant, evidence, solver/verifier, and target-evaluator timing/size metrics.
- docs/TEST_PLAN.md + docs/BENCHMARKS.md + package/release checks — acceptance gates, exact evidence paths, thresholds, proof-class separation, and host/Pi non-claims.
Commands:
- scripts/ci/admission_conformance_run.sh --state-dir out/admission/m28c
- scripts/ci/admission_perf_probe.sh --state-dir out/bench/m28c-admission
- scripts/ci/test_plan_run.sh --state-dir out/test-plan/m28c-admission
- scripts/check-generated.sh
Checks:
- Security corpus fails closed, generated host/target decisions correspond, performance stages are separately bounded, packages contain exact generated contracts/checkers, and no host result is promoted to Pi or formal-proof evidence.
Deliverables:
- Accepted, bounded, abuse-resistant admission primitive ready for 28e-28d and 30b consumers.
Outcome After Milestone 28c:
- Untrusted AI and non-AI requests can be converted into typed intents and checked against versioned policy plus authoritative current state.
- Only
proveddecisions can create state-bound grants, and those grants are no broader or longer-lived than the exact admitted intent. - Tickets, leases, provider actions, Queen/root mutation, receipts, audit, replay, and evidence remain the canonical execution and evidence paths.
- Decision witnesses make admission reproducible without pretending every result is a formal proof.
- Later milestones can adopt one admission primitive without inventing AI-specific guardrails, protocol-specific policy evaluators, or parallel authority registries.
Title/ID: m28c-admission-workbench-inspector
Milestone: 28c / admission-workbench-inspector
Goal: Expose typed intents, authoritative facts, decisions, grants, refusals and proof classifications through the accepted SwarmUI workbench without UI-owned authority.
Inputs: 27f workbench; this milestone's accepted owner schemas, read/verify libraries and evidence.
Changes:
- Rust UI adapters and Spectrum inspectors — bounded immutable reads, exact source/hash/visibility and evidence links; no duplicate schema or direct provider execution.
- UI/native tests and documentation — tamper, stale/missing evidence, denied reads, unknown facts and persistent source/proof modes; no placeholder counts as implementation.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: The inspector verifies the owner records through shared libraries independently of MCP/A2A; UI caches or screenshots cannot strengthen evidence.
Deliverables: Backend-owned, qualified workbench inspector.
Milestone 33 — Production Worker Binding, Driver Inventory and Quarantine
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain complete Worker ticket/lease-to-live-bundle binding, ticket-free driver inventory, generation-keyed quarantine, fresh-ticket Worker restart and fresh-generation driver recovery. Reuse 26e containment and the exact current admission contract. Stronger bundle claims require this evidence; basic revoke/generation/fault safety needed by 28x cannot be deferred here.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 28d; current owner 33
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Status: Planned — after the 27g release; preserve existing implementation and evidence.
Delivery posture: Implement and qualify complete production Worker ticket/lease binding, driver-inventory projection, structured quarantine, and fresh-ticket restart. Profile selection controls runtime use; it cannot omit these implementation or acceptance requirements.
Why now (production authority binding): 26e supplies creation, containment, teardown, and recreation of complete Heartbeat/GPU/LoRA Worker bundles plus driver containment; 27a supplies host authority. Bind 28c-admitted actions to the Worker ledger, project the selected driver inventory, and add structured quarantine evidence. Drivers remain ticket-free. This does not retroactively gate the 26e baseline or independent 29 storage containment.
Prerequisites
- Milestone 26e, including
m26e-driver-runtime-mcs-port-and-cyw43-coexistence,m26e-worker-supervisor-child-isolation,m26e-host-worker-integration,m26e-worker-target-evidence-promotion, andm26e-root-tcb-target-proof, completed for Heartbeat/GPU/LoRA with complete instance bundles, live badged telemetry IPC, durable completion, full teardown, fresh supervisor-generation recreation, host integration, and exact QEMU/Pi evidence; linked drivers have complete MCS authority and containment inventories. The inactive historicalm26c-cap-backed-worker-endpointsproposal and current model-only profiles do not satisfy this prerequisite. - Milestone 26e task
m26e-mcs-smp-target-acceptancecompleted; all cap bundles extend the accepted SMP+MCS task topology and may not introduce a second scheduler architecture. - Milestone 29 integrates its new
driver-storagewith the complete 28d ledger/containment contract and supplies generation-keyed inventory, teardown, and fresh-generation readmission evidence in 29. This avoids a 28d/29 dependency cycle; disabled storage has no live ledger row, and configuration or packaging cannot substitute for runtime proof. - Milestone 26d seL4 baseline refresh completed for the selected profiles, so CSpace/VSpace/syscall assumptions match the accepted seL4 generated artifacts.
- Milestone 27a completed, including audit/replay defaults and generated gates that distinguish host authority records from VM cap-backed tickets.
- Milestone 27b completed for the provider/integration dependency graph, external-executor classifications, exact package manifests, and stable use-case rows that will consume production Worker-bundle bindings. Binding conformance uses accepted 27c/27d host workflows and 26e target roles. Later advanced AI/inference consumers qualify their own additional schemas and cannot gate this milestone.
- Milestone 28c completed for any production Worker ticket/lease action, including the accepted admission id, decision witness hash, intent/policy hashes, state epoch, Worker/resource generation facts, and state-bound grant.
Stable generated label: m28b_production_bundle is a legacy schema/evidence
identifier now owned by 28d; this documentation renumbering does not rename it.
Production authority contract: 26e evidence proves matching baseline
Worker/driver bundles and basic containment; 29 owns new storage-runtime
containment evidence. Complete 28d adds ticket/lease-to-bundle binding, full
runtime-inventory projection, quarantine/evidence, and fresh-ticket restart.
Extend host-integration-dependency/v1 and use-case records with
m28b_production_bundle evidence. This does not create a second catalog or prove
external providers. Consumers claim only the authority their evidence supports.
Goal Bind production Worker tickets/leases one-to-one to accepted live seL4 bundles, bind each admitted action to the exact decision and state against which it was approved, project each already-complete driver bundle through manifest runtime-instance, scheduler, supervisor, and cap-generation ledgers without inventing driver tickets; and convert already-contained Worker/driver faults into structured terminal/quarantine evidence with fresh-ticket Worker restart and fresh driver runtime-generation recovery policy. Publish those bindings into the shared integration/use-case evidence graph so host tools can distinguish a 26e executable Worker from a 28d production-bound bundle without inferring either from a ticket, provider receipt, or UI state.
Non-Goals (Explicit)
- No change to REST delegated identity, host-ticket action semantics, MCP/A2A protocol surfaces, or AI run control.
- No change to semantic object/Context Capsule or inference contracts, and no inference receipt, capsule ref, provider receipt, or semantic object implies a VM cap-backed Worker binding.
- No new VM protocol, console grammar, Secure9P verb, or root-owned physical-driver path.
- No claim that host tickets, REST delegated tickets, provider tickets, or PEFT receipts are seL4 cap-backed unless a generated VM projection explicitly maps them to live caps.
- No driver ticket or lease material. Host/provider tickets may authorize a root-projected driver action, but a driver runtime receives only its generated manifest identity, runtime generation, resource descriptors, and MCS/IPC caps.
- No second Worker constructor, CSpace/VSpace loader, scheduler architecture, basic fault endpoint, or revocation path. 28d reuses the accepted 26e supervisor bundle and teardown implementation.
- No CYW43/SDIO timing, retry, state-machine, restart, packaging, ownership, or evidence-classification change. Driver authority may be ledger-bound only as already generated and accepted.
Deliverables
- Generated production binding records map each active Worker ticket/lease,
role, slot, lease epoch, supervisor generation, scheduler generation, and
fault identity to exactly one accepted 26e instance bundle. Each admitted
Worker action additionally correlates
admission_id,decision_witness_hash,intent_hash,policy_hash,state_epoch,worker_generation,ticket_or_lease_id, andcap_bundle_generation. WorkerBus remains model-only and has no production VM bundle. - Generated driver records map manifest runtime identity plus runtime, scheduler, supervisor, and cap-bundle generations to the already accepted endpoint, notification, fault/timeout, SC/Reply, IRQ, shared-ring, data-frame, MMIO, DMA, and shared-buffer authority applicable to each linked runtime. They contain no ticket/lease credential, and SchedControl remains root-only.
- Root-task reuses the sole 26e constructor/teardown and retained origin caps; it never creates a parallel Worker CSpace/VSpace path or hands out catch-all root, namespace, frame, device, or scheduling authority.
- Production fault handling records bounded evidence, invokes the complete 26e Worker teardown or accepted driver containment path, marks the exact Worker ticket/lease or driver manifest-runtime ledger entry terminal or quarantined, and rejects late IPC, timeout events, ring turns, telemetry, and receipts from the old ledger generation.
- Worker restart is allowed only through a new ticket, lease epoch, supervisor generation, and cap-bundle binding. Driver recovery uses a fresh admitted manifest runtime/cap generation and the accepted containment/reconstruction path, never a ticket. Neither may silently reuse a stale TCB, cap, Reply relationship, SC, DMA mapping, shared frame, or ring.
- Milestone 28c proves admission against policy and state. This milestone binds that decision to the actual live Worker bundle, ticket/lease, capability generation, fault lifecycle, and quarantine state. A 28c decision alone is not production Worker authority proof, and any changed Worker or resource generation invalidates it.
- Emit
worker-bundle-bindingintegration evidence for Heartbeat/GPU/LoRA with target/image/manifest hashes, ticket/lease identity, Worker slot, lease epoch, supervisor/scheduler/cap generations, terminal/quarantine state, and the corresponding 26e component/integration evidence refs. Provider/executor results remain separate referenced records. - Re-evaluate only the use-case rows that explicitly require
m28b_production_bundle. A live 28d binding cannot promote a row whose semantic/capsule, inference, CUDA, PEFT, FUSE, Kubernetes, federation, package, identity, recovery, or other host dependency is missing or non-live.
Commands
cargo test -p root-task --tests cap_bundlecargo test -p root-task --tests faultcargo test -p root-task --test fault_recovery_timingcargo test -p pi4-driver-abicargo test -p pi4-driver-runtimecargo test -p worker-heartcargo test -p worker-gpucargo test -p worker-loracargo test -p coh --test evidencecargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.jsonscripts/check-generated.shscripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m28d-qemu-cap-bundlesscripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m28d-pi4-cap-bundles
Checks (DoD)
- Production Worker ticket/lease profiles fail generation if any executable Worker metadata scope lacks the corresponding one-to-one accepted live-bundle binding. Complete driver-inventory profiles fail if any admitted manifest runtime lacks its generation-keyed accepted inventory; no driver ticket is generated or delivered.
- Any admitted Worker action fails before invocation when its
admission_id, decision-witness, intent/policy hash, state epoch, Worker generation, ticket/lease id, or cap-bundle generation is missing, mismatched, expired, or stale. - Production profiles that expose AI, MCP/A2A, provider, or driver-runtime projections may cite matching accepted owner-milestone live authority, but fail if they claim 28d Worker ledger binding, complete driver-inventory projection, or structured quarantine without the corresponding 28d evidence.
- Host tools, REST/FUSE/Python/UI/MCP/A2A projections, release manifests, and use-case rows consume the same generated 28d bundle-binding record and cannot synthesize production Worker state from tickets, semantic objects, Context Capsules, inference receipts, model entries, registry publication, or provider receipts.
- Revoked Worker tickets lose their bound endpoint, notification, scheduling-context, timeout/fault cap, frame, and shared authority. The root-fault-owned Reply lane is not Worker-ticket authority; any association for the faulting generation is resolved separately before reuse. Quarantined driver runtime generations lose endpoint, notification, SC/Reply, timeout/fault, ring, frame, IRQ, MMIO, DMA, and shared-buffer authority; stale invocations, timeout events, and ring turns fail deterministically.
- Recovery reconciles Worker ticket/lease ledgers and ticket-free driver manifest-runtime ledgers with the accepted owner-milestone object state so no active Worker ticket exists without exactly one live Worker bundle, no admitted driver ledger entry lacks its exact live bundle, and neither kind of bundle remains after its ledger entry becomes terminal.
- Fault badges deterministically identify the Worker role/instance/logical lease epoch/cap-bundle generation or the driver role/manifest-runtime instance/ runtime generation/cap-bundle generation, without treating a driver as a ticket subject.
- Fault handling revokes old caps, rejects stale shared-ring turns and telemetry, and requires fresh Worker ticket/lease binding or fresh admitted driver runtime generation before restart/recovery.
- No root-fault or driver-command Reply association, and no donated scheduling context, is stranded or reused across a lease epoch, quarantine, revoke, or restart; SchedControl is never delegated.
- Fault evidence is bounded, redaction-safe where needed, included in evidence packs, and does not alter console grammar or Secure9P framing.
- Within a profile claiming 28d production-ledger authority, an executable Worker has no metadata-only or 26c endpoint-only fallback. A valid 26e-only executable profile remains a distinct supported tier when it makes no 28d ticket/lease-ledger or quarantine claim. The only non-executable state is explicitly model/session-only; it cannot claim live VM caps, faults, or Worker receipts.
- Fault/revoke timing evidence stays bounded for representative worker and driver fault cases; material regressions are classified as cap-revocation, evidence-export, restart-policy, or driver-runtime recovery overhead before production profiles depend on structured fault recovery.
Compiler touchpoints
coh-rtcemits production ticket/lease bindings to accepted 26e Worker bundle templates and separate ticket-free manifest-runtime bindings to complete generated driver inventories including SC/Reply/timeout/MMIO/DMA ownership, scheduler/supervisor/runtime generations, revoke/recovery evidence, production enablement gates, terminal/quarantine policy, and bounded fault evidence paths. SchedControl is never emitted to a child bundle.coh-rtcextends those Worker bindings with the accepted 28c admission and decision-witness correlation fields while keeping provider admission, Worker ticket/lease identity, and live seL4 cap authority as distinct records.coh-rtcemits explicit profile-state distinctions for read-only projection, host-ticket-only actuation, model/session-only roles, 26e isolated-task and linked-driver authority, Milestone 29-owned storage-runtime authority, 28d production Worker ticket/lease binding, complete driver-inventory projection, and structured quarantine. No active profile consumes the inactive 26c endpoint-only proposal as a compatibility floor or treats a driver as a ticket subject.coh-rtcextends the 27b integration/use-case graph with generated 28d Worker-bundle binding and quarantine evidence requirements; it never changes provider/external-executor observed mode or use-case maturity without all other dependency rows passing.- Generated snippets refresh
docs/WORKER_TICKETS.md,docs/SECURITY.md,docs/HARDWARE_BRINGUP.md,docs/INTERFACES.md, anddocs/TEST_PLAN.md.
Task Breakdown
Title/ID: m28b-production-worker-ticket-driver-inventory
Milestone: 28d / production live-bundle ledger binding
Goal: Bind each production Worker ticket/lease to exactly one accepted 26e live bundle and project each selected accepted driver bundle through a ticket-free manifest-runtime ledger without reconstructing either task path or retaining metadata-only compatibility authority.
Inputs: accepted 26e Worker and linked-driver bundle/inventory/integration evidence records, Milestone 29-owned storage-runtime bundle/inventory evidence, accepted 28c decision/grant/witness records, 27b host-integration and use-case registries, apps/root-task/src/lifecycle.rs, apps/root-task/src/hal/**, apps/root-task/src/generated/**, apps/root-task/src/ninedoor.rs, tools/coh-rtc/src/**, scripts/ci/use_case_gate.sh, docs/WORKER_TICKETS.md, docs/SECURITY.md, docs/HARDWARE_BRINGUP.md, docs/TEST_PLAN.md
Changes:
- tools/coh-rtc/src/** — bind production Worker tickets/leases to the exact accepted 28c admission id, decision-witness hash, intent/policy hashes, state epoch, Worker generation, ticket/lease id, cap-bundle generation, and complete accepted 26e endpoint, lifecycle/completion notification, active SC, standard/timeout fault, frame, image, supervisor-generation, and revoke inventory. Separately project each selected accepted driver endpoint/notification/SC/Reply/fault/ring/frame/IRQ/MMIO/DMA/shared-buffer inventory, with extension points consumed by Milestone 29 later, by owner milestone, manifest runtime identity, and generation; generate no driver ticket/lease field and keep SchedControl root-only.
- apps/root-task/src/lifecycle.rs + apps/root-task/src/hal/** — reuse the sole 26e Worker constructor and accepted driver admission/containment contract, origin caps, and complete teardown for baseline runtimes; Milestone 29 integrates storage later; attach Worker live-bundle identity to the production ticket ledger and driver live-bundle identity to the manifest-runtime ledger without creating a second CSpace/VSpace, runtime descriptor, or scheduler path.
- apps/root-task/src/ninedoor.rs + apps/root-task/src/event/** — reconcile Worker ticket ledgers and driver manifest-runtime ledgers with accepted live bundle state, refuse metadata-only production authority, and ensure host/provider tickets authorize only root-projected driver actions rather than entering a driver descriptor.
- tools/coh-rtc/src/codegen/** + scripts/ci/use_case_gate.sh — emit and consume 28d `worker-bundle-binding` integration evidence and promote only use-case rows whose remaining host/provider/executor/package dependencies also pass.
- docs/WORKER_TICKETS.md + docs/SECURITY.md + docs/HARDWARE_BRINGUP.md + docs/TEST_PLAN.md — document separate Worker-ticket and ticket-free driver-ledger semantics, production profile gates, revoke/recovery behavior, and negative tests. `pi4-driver-abi`, `pi4-driver-runtime`, and Worker source are regression inputs only and are not changed by this task.
Commands:
- cargo test -p root-task --tests cap_bundle
- cargo test -p pi4-driver-abi
- cargo test -p pi4-driver-runtime
- cargo test -p worker-heart
- cargo test -p worker-gpu
- cargo test -p worker-lora
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- scripts/check-generated.sh
- scripts/ci/use_case_gate.sh --promote-milestone 28d --matrix configs/generated/use_case_evidence.json --state-dir out/use-case-gate/m28g
Checks:
- Production Worker ticket profiles fail if any executable Worker lacks a one-to-one accepted live-bundle binding; driver-inventory profiles fail if any admitted manifest runtime lacks its generation-keyed complete accepted inventory; any generated/delivered driver ticket field fails validation.
- A decision whose Worker/resource, ticket/lease, state, or cap-bundle generation changed is rejected; 28c admission evidence alone cannot satisfy live-bundle or quarantine proof.
- Revoked Worker tickets lose their exact bound authority; quarantined driver runtime generations lose their exact endpoint/notification/SC/Reply/fault/ring/frame/IRQ/MMIO/DMA/shared authority; stale invocations, timeout events, and ring turns fail deterministically.
- Recovery reconciles both ledger kinds with existing object state so no active Worker ticket or admitted driver generation lacks exactly one live bundle and no terminal entry retains one.
- Host projections consume the exact binding record, and no use case is promoted by a Worker binding when any independent host integration row is missing, fixture, mock, dry-run, disabled, unknown, or otherwise below its required mode.
Deliverables:
- Production-grade Worker cap-backed ticket authority plus a complete
ticket-free driver inventory projection bound to each runtime's accepted
owner-milestone seL4 bundle.
Title/ID: m28d-structured-fault-lifecycle
Milestone: 28d / structured quarantine and fresh-generation restart
Goal: Project already-contained Worker and driver seL4 faults into Worker ticket/lease quarantine or ticket-free driver runtime quarantine, bounded evidence, fresh-ticket Worker restart, and fresh-generation driver recovery without duplicating 26e containment.
Inputs: accepted 26e Worker teardown and baseline-driver containment interfaces/evidence, accepted baseline-driver containment evidence (29 adds its storage evidence later), apps/root-task/src/lifecycle.rs, apps/root-task/src/event/**, apps/root-task/src/hal/**, apps/root-task/src/generated/**, apps/coh/src/evidence.rs, tools/coh-rtc/src/**, docs/SECURITY.md, docs/INTERFACES.md, docs/TEST_PLAN.md
Changes:
- tools/coh-rtc/src/** — extend accepted 26e Worker fault/timeout identity with production ticket, logical lease epoch, scheduler/supervisor/cap-bundle generation, and extend driver identity separately with manifest runtime instance/runtime generation/scheduler/supervisor/cap-bundle generation; generate terminal/quarantine policy and bounded evidence paths without a driver ticket field.
- apps/root-task/src/lifecycle.rs + apps/root-task/src/event/** — consume existing worker/driver fault and timeout IPC, record bounded production evidence, invoke the existing complete Worker teardown or accepted driver containment, resolve fault/driver Reply ownership, and transition the exact Worker-ticket or driver-runtime ledger entry to terminal/quarantined state.
- apps/root-task/src/hal/** — invoke the accepted driver containment cut-off for IRQ, shared-ring, MMIO, DMA/shared-buffer, fault, and old-generation authority, then admit recovery only through a fresh manifest runtime generation. Do not edit the driver ABI/runtime or CYW43 behavior.
- apps/root-task/tests/fault_recovery_timing.rs — bounded timing checks for revoke, evidence export, stale-turn refusal, and fresh restart admission under representative worker/driver faults.
- apps/coh/src/evidence.rs + docs/SECURITY.md + docs/INTERFACES.md + docs/TEST_PLAN.md — include bounded fault lifecycle records in evidence exports and document restart/quarantine semantics.
Commands:
- cargo test -p root-task --tests fault
- cargo test -p root-task --test fault_recovery_timing
- cargo test -p pi4-driver-runtime
- cargo test -p worker-heart
- cargo test -p worker-gpu
- cargo test -p worker-lora
- cargo test -p coh --test evidence
- cargo run -p coh-rtc -- configs/root_task.toml --out apps/root-task/src/generated --manifest configs/generated/root_task_resolved.json
- scripts/check-generated.sh
Checks:
- Fault badges deterministically identify either the faulting Worker role/instance/logical lease epoch/cap-bundle generation or driver role/manifest-runtime instance/runtime generation/cap-bundle generation.
- Fault/timeout handling completes the applicable existing containment,
rejects stale Reply/donation, timeout, shared-ring, telemetry, and receipt
events, and requires a fresh Worker ticket/lease/supervisor-generation/
bundle binding or fresh admitted driver runtime generation before recovery.
- Fault evidence is bounded, redaction-safe where needed, included in evidence packs, and does not alter console grammar or Secure9P framing.
- Fault/revoke timing remains bounded and is reported as VM authority recovery evidence, not Pi/QEMU network throughput proof.
Deliverables:
- Production fault lifecycle evidence that lets seL4 reviewers audit Worker ticket quarantine and ticket-free driver runtime quarantine/recovery separately.
Title/ID: m28d-python-production-bundle-parity
Milestone: 28d / Python production projection parity
Goal: Make the Python SDK consume generated Worker-bundle binding and Worker/driver quarantine evidence without synthesizing production authority or treating drivers as ticket subjects.
Inputs: `m27b-authoritative-receipt-and-evidence-core`, `m28b-production-worker-ticket-driver-inventory`, `m28d-structured-fault-lifecycle`, generated 28d integration/use-case records and canonical evidence fixtures, tools/cohesix-py/cohesix/{generated.py,worker.py,orchestration.py,receipts.py,evidence.py}, tools/cohesix-py/tests/**, docs/PYTHON_SUPPORT.md.
Changes:
- tools/cohesix-py/cohesix/{worker.py,orchestration.py,evidence.py} — consume coh-rtc-generated Worker binding, ticket/lease epoch, scheduler/supervisor/cap generation, terminal/quarantine, recovery, and evidence-reference fields while preserving the separate ticket-free driver manifest-runtime identity and the 26e-only versus 28d-production profile distinction; do not hand-edit `generated.py`.
- tools/cohesix-py/cohesix/receipts.py + focused fixtures — reuse the authoritative 27b receipt/evidence validators and conformance vectors to validate the shared binding/fault records and refuse missing, forged, duplicate, stale-generation, wrong-target, wrong-role, driver-ticket-bearing, client-authored, or incompletely correlated inputs; keep provider/executor receipts separate and add no parallel Python validator or receipt format.
- tools/cohesix-py/tests/{test_worker_compatibility.py,test_orchestration.py,test_evidence_receipts.py} — cover live, revoked, quarantined, stale-generation, missing-binding, fresh-generation recovery, 26e-only, and WorkerBus model-only cases using the canonical Rust/generated vectors.
- docs/PYTHON_SUPPORT.md — document read/projection behavior and explicitly deny any Python-created production-bundle, quarantine, restart, or driver-ticket authority.
Commands:
- python3 -m pytest -q tools/cohesix-py/tests/test_worker_compatibility.py tools/cohesix-py/tests/test_orchestration.py tools/cohesix-py/tests/test_evidence_receipts.py
- scripts/check-generated.sh
Checks: A ticket, lease, provider receipt, model publication, local file, or client-created JSON cannot become a 28d production-bundle claim; stale generations and incomplete correlations fail closed; no driver ticket is accepted or emitted; 26e-only profiles remain distinct; fresh recovery requires the generated new identity; WorkerBus remains model-only.
Deliverables: Python projects the same generated production-binding and quarantine truth as other host tools without creating a parallel lifecycle or authority model.
Title/ID: m28d-production-binding-workbench-inspector
Milestone: 28d / production-binding-workbench-inspector
Goal: Expose production Worker binding, ticket-free driver inventory, quarantine and fresh-generation recovery through the accepted SwarmUI workbench without UI-owned authority.
Inputs: 27f workbench; this milestone's accepted owner schemas, read/verify libraries and evidence.
Changes:
- Rust UI adapters and Spectrum inspectors — bounded immutable reads, exact source/hash/visibility and evidence links; no duplicate schema or direct provider execution.
- UI/native tests and documentation — tamper, stale/missing evidence, denied reads, unknown facts and persistent source/proof modes; no placeholder counts as implementation.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: The inspector verifies the owner records through shared libraries independently of MCP/A2A; UI caches or screenshots cannot strengthen evidence.
Deliverables: Backend-owned, qualified workbench inspector.
Milestone 34 — Advanced Agents, Context Optimisation and Broader NeMo Families
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain task graphs/handoffs, durable semantic context, experiments, attention/prefix/hotset policies, broader framework/PEFT adapters, NeMo Run/customisation, Guardrails, evaluation, retrieval and serving families. Reuse 28b/28c transactions and the 28f NeMo Agent Toolkit kit. Add only a named capability the external framework and standard protocols do not already supply.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 28e; current owner 34
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Status: Planned — after the 27g release; preserve existing implementation and evidence.
Delivery posture: Implement the complete AI/PEFT substrate: delegated and governed runs, durable context, task graphs/handoffs, inference strategies, prefix/hotset reuse, all listed framework/NeMo adapters, and provider parity. The Verified Private LoRA Release remains the Jetson reference journey, binding provenance, training/evaluation, systemd/Docker/CUDA execution, scan/import, reload/canary/rollback, WorkerLora, and one evidence graph. Operator-directed and autonomous modes are both required; selected policy controls human approval, and governed effects require accepted 28c decisions.
Why now (bridge): 27a supplies host authority, 27b provider conformance, and 28b Context Capsules; 28c supplies decision-bound grants before governed actions are qualified. This host-only run substrate keeps durable run state, capsule refs, retrieval, approvals, and evidence outside the live prompt to reduce repeated prefill and lossy summaries. Ticketed inference reuses REST, host tickets, the provider registry, capsule core, GPU telemetry, Python, and Worker receipts without adding VM roots.
As-built alignment note: Python has typed schedule, lease, export, host-ticket, federation, and Kubernetes helpers; PEFT files and Worker LoRA receipts also exist. These do not supply AI run/task graphs, checkpoints, context budgets, prefix hotsets, NeMo integration, or complete PEFT transactions. 28b supplies context, not admission, provider selection, inference, or training. Mocks, local registries, GPU/model publication, receipts, and capsules do not prove training, evaluation, scanning, reload, or rollback.
Prerequisites
- Completed 27c/27d recipe and private LoRA release contracts, 28a broader providers and 28d production Worker binding. Reuse their lifecycle/executor; this milestone owns advanced consumers and broader framework/NeMo qualification only.
- The Milestone 27a completed for delegated REST identity, idempotency, selected-profile writer safety, host-ticket durable execution, audit/replay defaults, and production secret/debug gates.
- Milestone 26e completed for executable WorkerLora and strict, crash-safe version-2 PEFT result-to-Worker receipts on QEMU and Pi 4.
- The Milestone 27b completed for the selected external executor, read visibility, identity, package, conformance, and use-case evidence.
- The Milestone 28b completed for immutable snapshot/artifact refs, provenance/redaction, deterministic Context Capsules, render/verify tooling, and selected semantic evidence. All listed semantic/capsule contracts are required.
- Milestone 28c completed for the governed action families. It precedes 28e in numerical implementation order. Operator approval
remains a selected-policy requirement;
admission_id=unavailablecannot satisfy governed execution or full milestone acceptance.
Goal Add a host-side AI run substrate that lets external supervisors and agent frameworks coordinate long-context workflows through delegated tickets and existing host-ticket flows while preserving Cohesix’s single-writer, append-only, audit-first discipline:
- Make run/task/step identity and context budget explicit.
- Keep checkpoints, exact constraints, Context Capsule and semantic snapshot references, retrieved spans, and tool receipts durable outside the prompt.
- Route workloads to host-side inference backends by recall/cost policy rather than one fixed attention strategy.
- Reuse warmed prefixes and hotsets across related runs within bounded quotas and TTLs.
- Expose TTFT, decode, cache-hit, and resume metrics as first-class evidence.
- Represent multi-agent work as explicit task graphs and handoffs, not as an opaque shared transcript or hidden message bus.
- Consume the accepted 26e executable WorkerHeart/WorkerGpu/WorkerLora contracts without weakening their image, capability, notification, MCS scheduling, fault, revocation, QEMU, or Pi evidence requirements;
ATTACHremains session-only and is never substituted for task creation. - Deliver the complete host-side PEFT lifecycle—export, data/base-model provenance, train/fine-tune, evaluate, scan, import, activate, inference-runtime reload/canary, and rollback—with crash-safe transactions and exact WorkerLora receipt correlation before AI run control treats it as dependable actuation.
- Re-evaluate and promote the 27b AI/PEFT use-case rows only from live external-provider, executable-Worker, package, recovery, and evidence records; mock/dry-run playbooks remain workflow templates.
- Keep provider strategy, run admission, and PEFT actuation in this milestone, while Milestone 28f owns the public OpenAI-compatible wire contract, streaming behavior, provider-neutral inference receipts, and compatibility conformance.
- Map every governed live AI effect to a 28c typed intent and exact accepted
admission_id. Support operator-approved and autonomous workflows under selected policy through existing host tickets. AI proposals cannot activate policy, declare extracted facts authoritative, or turn confidence into a decision; required human approval remains enforceable. - Make the Verified Private LoRA Release operable through the 27b
ticket-centred
plan -> apply -> watch -> explain -> verify -> recoverlifecycle and emit a SwarmUI-ready causal graph projection without making the UI, Python callback, training framework, native label, or observability export authoritative.
Completion boundary: Reuse 27c/27d for the baseline CUDA/HF/LoRA journey; complete every advanced extension task and prove run/task/step identity, streams, cancellation/resume, checkpoints, task graphs, attention strategies, prefix/hotset policies, framework/NeMo adapters, provider parity, and the full PEFT transaction. Qualify required capabilities on suitable local or remote hosts; deployment disablement cannot substitute for their implementation and live conformance.
Non-Goals (Explicit)
- No in-VM transformer kernels, sparse-attention implementations, KV-compression implementations, or CUDA/NVML changes.
- No in-VM model weights, datasets, training/evaluation/scanning frameworks, inference runtime, or adapter-byte transfer. WorkerLora validates bounded lifecycle work and records correlated receipts; all PEFT data-plane work remains in the declared host executor.
- No direct many-agent writes to raw
/queen/ctl; multi-agent host automation writes through delegated REST and/or/host/tickets/spec. - No active/active multi-queen control for one logical hive.
- No live AI, PEFT, NeMo, Kubernetes, Docker, systemd, CUDA/NVML, or model-registry mutation from Python, adapters, playbooks, or framework integrations unless it appends a validated host ticket and is executed by
host-ticket-agentunder the generated provider action registry. - No live effect without its generated action policy, delegated authority, idempotent durable ticket, required approval/admission, and authoritative receipt. Governed effects require accepted 28c admission; operator approval cannot replace that decision. Dry-run creates no authority grant.
- No AI activation or modification of policy, no model self-classification of extracted facts as authoritative, and no use of model confidence as an admission verdict.
- No generic mutable
/store, vector database, or prompt blob sink divorced from existing evidence/CAS discipline. - No reimplementation of the 28b semantic store, extractor registry, object graph, capsule planner, or renderer inside AI orchestration.
- No public OpenAI-compatible endpoint, SDK compatibility claim, or provider-neutral streaming/usage contract in this milestone; those belong to Milestone 28f.
- No new 9P verbs, no console grammar changes, and no hidden RPC behind file names.
- No claim that Cohesix replaces agent planners/orchestrators; it remains the authority, evidence, and actuation layer beneath them.
- No opaque prompt transcript as the source of truth for agent state, approvals, retrieval, or tool output.
- No hidden inter-agent mailbox or side-channel coordination surface outside delegated tickets, durable artifacts, and existing evidence flows.
- No NeMo-specific control plane, namespace grammar, or provider lock-in semantics; NeMo support remains a manifest-selectable host-side provider family under the same Cohesix authority/evidence contract as other backends.
- No framework callback, NeMo rail/action, Kubernetes status condition, Docker label, systemd notification, CUDA trace, or locally assembled model card may mint a Cohesix grant or authoritative terminal receipt. These are bounded provider observations consumed by the shared verifier.
- No claim that VM worker-gpu, worker-lora, or worker-heart kernel binaries are
full task implementations unless their selected executable contracts and
exact QEMU/Pi task evidence are accepted under 26e.
ATTACHremains session-only and does not instantiate a task. Claims that a production ticket or lease is bound one-to-one to that live bundle additionally require 28d.
Deliverables
1) AI run/task graph envelope and context-budget contract (host-only)
Purpose: Make long-context cost, dependency ordering, and handoff policy explicit instead of burying them inside prompts.
Implementation requirements:
- Extend accepted 27c host-run envelope fields for AI ticket/playbook flows:
run_id,parent_run_id,task_id,step_id,attemptcontext_budget_tokens,latency_slo_ms,recall_mode,loss_toleranceprefix_group,dataset_refs,artifact_refs,deadline_unix_ms,human_owner
- Add advanced task-graph, experiment and handoff fields:
depends_on,handoff_ref,instruction_ref,retrieval_manifest_refsemantic_snapshot_ref,context_capsule_ref,context_render_profile_refprovider_profile_hash,prefix_cache_keymax_parallel_agents,human_attention_budget
- Live mutating AI flows inherit Milestone 27a safety requirements: delegated ticket,
id,idempotency_key, andwriter_epochwhere applicable. - Every governed live AI side effect carries the accepted 28c
admission_id,intent_hash,policy_hash,state_epoch, resource generations, granted scope, and decision expiry required by its generated provider action. Operator-approved actions also record authenticated subject, approval, exact action/target, and idempotency/writer state; an absent 28c decision must be explicit and cannot satisfy a governed action. - Dry-run and mock playbooks validate budget/policy mismatches before any host side effect. They may render a proposed intent and simulated decision but cannot mint or reserve a grant.
As-built leverage:
- Reuse
cohesixPython orchestration APIs and/host/tickets/specidempotent lifecycle.
2) Durable checkpoints instead of prompt-only memory
Purpose: Reduce prompt bloat and resume cost without relying on lossy summarization.
Implementation requirements:
- Record structured checkpoints containing:
- exact constraints/instructions,
- immutable semantic snapshot, Context Capsule, render-profile, retrieval manifest, and selected-span references,
- approvals/policy receipts,
- tool receipts/artifact refs,
- resume cursor and prior-step linkage.
- Retrieval manifests remain first-class artifacts, but are inputs to or subrecords of the accepted 28b Context Capsule contract rather than a competing context source of truth. They record what was considered or retrieved, while the capsule and render receipt record what was selected and delivered.
- Large tool outputs and retrieved corpora are offloaded into bounded host-side artifacts with hashes, redacted previews, and exact refs instead of being re-inlined into every prompt.
- Checkpoints are host-side artifacts and evidence inputs, not a new VM filesystem or opaque prompt cache.
- Evidence/timeline tooling can reconstruct why a run acted without replaying the entire prompt transcript.
As-built leverage:
- Reuse existing evidence pack/timeline flows, audit redaction, and telemetry ingest.
3) Attention routing and prefix/hotset reuse
Purpose: Let operators choose the right long-context strategy per workload instead of paying full attention cost by default, while making cache eligibility and invalidation explainable.
Implementation requirements:
- Host-only provider policy classifies requests as bounded strategy hints, for example:
fullretrieval-firstsparse-preferredcompression-preserveneedle-sensitive
- Prefix groups and hotsets can be warmed, leased, resumed, and evicted through bounded host tickets with TTL/quota enforcement.
- Prefix reuse eligibility and miss reasons are recorded using bounded evidence fields such as model/provider profile hash, instruction hash/ref, semantic snapshot hash/ref, Context Capsule hash/ref, render-profile hash/ref, retrieval-manifest hash/ref, tool-schema hash, TTL expiry, and quota eviction cause.
- GPU lease and provider selection remain host-side and reuse existing lease/publish flows.
As-built leverage:
- Reuse GPU lease control, host-ticket executor model, and telemetry/evidence surfaces.
4) AI run metrics and guardrails
Purpose: Make long-context efficiency measurable and auditable.
Implementation requirements:
- Collect bounded per-run metrics:
- TTFT,
- decode tokens/sec,
- prompt bytes/tokens submitted,
- prompt bytes/tokens avoided via checkpoint/prefix reuse,
- semantic objects selected/omitted and estimated prompt tokens avoided by capsule selection,
- prefix hit/miss counts,
- prefix invalidation/miss reasons,
- retrieval miss rate,
- resume count,
- GPU lease pressure/provider queue wait,
- handoff count and checkpoint restart count.
- Metrics remain read-only exports and evidence inputs; they do not become a second source of truth for control.
- Policy gating remains mandatory for high-risk live mutations initiated by AI supervisors.
- Add a targeted advanced AI run-cost benchmark for dry-run/mock playbooks that records checkpoint/resume overhead, prefix/hotset hit/miss behavior, prompt bytes avoided, receipt/evidence export cost, and provider queue-wait simulation. This is host-side AI evidence, not a full Pi/QEMU runtime benchmark.
As-built leverage:
- Reuse
/queen/telemetry/*, existing evidence packs, and host snapshots.
5) Framework coexistence, not framework replacement
Purpose: Make Cohesix usable beneath agent supervisors without inventing another agent framework.
Implementation requirements:
- Provide Python-side adapters/examples for long-context supervisors to submit delegated host tickets and consume receipts/checkpoints plus immutable Context Capsule references and render receipts.
- Provide a common Python run context and framework callback contract that maps framework-native run, checkpoint, evaluation, artifact, cancellation, and terminal events onto generated ticket/checkpoint observations. Callbacks may request an allowlisted ticket or stop a local loop after refusal, but cannot call a provider directly, mint authority, or author an authoritative receipt.
- Ship at least one reference playbook that coordinates repo-scale analysis or closed-loop AI factory work in dry-run/mock mode before any live actuation.
- Reference adapters and playbooks must model explicit delegation/handoff chains over the run envelope and checkpoint model; they must not rely on implicit shared transcript state.
- Export receipts/checkpoints in derived, host-side forms suitable for downstream observability tooling; exports remain non-authoritative.
As-built leverage:
- Reuse
cohesix-playbook, mock backend, and host-only REST/filesystem backends.
6) Worker Boundary and Documentation Closure
Purpose: Prevent host-side AI orchestration from depending on stronger worker claims than the VM implementation and generated evidence actually support.
Implementation requirements:
- Audit worker-heart, worker-gpu, and worker-lora kernel entrypoints against README, GPU, worker-ticket, role/scheduling, and interface docs.
- Verify each Heartbeat/GPU/LoRA role against its accepted 26e executable
image/READY/IPC or durable-completion, lifecycle notification, complete
teardown/revoke, cap-backed endpoint, applied MCS scheduling, fault, and
exact-target evidence. Model/session helpers remain separately classified,
WorkerBus remains model-only, and task creation is never inferred from
ATTACH. - If a host-side AI flow claims production ticket/lease-to-bundle authority, require 28d production ledger evidence as an additional gate; otherwise it may consume accepted 26e task behavior only as explicitly classified target evidence.
- Add tests that prevent future docs from claiming worker spawn/lease semantics not backed by code and generated manifest truth.
- Host-side AI run envelopes must reference host-ticket/provider receipts, not undocumented VM worker behavior.
As-built leverage:
- Reuse role-scoped ticket docs, worker crates, host-ticket receipts, and evidence-pack schemas.
7) Broader PEFT Framework and Provider Qualification
Purpose: Extend the accepted 27d transaction to broader providers and domain use cases; never create a second executor, lifecycle or evaluator.
Implementation requirements:
- Extend the accepted 27c/27d generated, phase-journaled transaction for
export,train,evaluate,scan,import,activate,runtime_reload,canary, androllback. Every phase has an idempotency key, input/output CAS refs, provider/executor identity, deadline, terminal receipt, recovery rule, and exact run/task/WorkerLora correlation. - Bind each selected phase to the 27b native execution identity: systemd unit and invocation, Docker image digest/container/events, profile-selected Kubernetes object UID/generation/conditions, CUDA device/job, provider event cursor, and ticket/evidence id. Native metadata remains correlation only until the shared verifier proves the phase postcondition.
- Validate base-model identity/license ref, dataset snapshot/provenance/consent refs, adapter/LoRA configuration, framework/provider profile, model and LoRA ids, artifact formats and hashes, training/evaluation metrics, threshold policy, safety/format scan, source job refs, signatures/attestations where configured, and target inference-runtime compatibility before promotion.
- For the Hugging Face reference adapter, record read-only Trainer callback
observations at train begin, checkpoint save, evaluation, and train end;
hash and validate
adapter_model.safetensors,adapter_config.json, the base model id/revision/digest, tokenizer/config, PEFT/Transformers/PyTorch/CUDA versions, resolved training configuration, dataset manifest, measured metrics, and model-card ref. Pickle-backed adapter artifacts are rejected by the live profile unless a separately approved migration path converts and verifies them before import. - Reuse accepted 27d registry locking, canonical-path confinement, symlink rejection, unique same-filesystem temp files, file and directory fsync/rename ordering, compare-and-swap activation generation, and rollback-safe activation records. Crash/restart recovery resumes or compensates from the phase journal without duplicating training, import, activation, or Worker receipts.
- Ship bounded host executor adapters for the open PEFT reference path, Hugging Face PEFT/TRL, and NeMo customization under the generic generated provider contract and shared receipt schema. No adapter may accept arbitrary shell, unrestricted paths, raw credentials, or unvalidated framework arguments.
- Ship a real CUDA reference profile using a supported open PEFT training stack and a real compatible inference runtime. If a use case advertises local Apple Silicon training or inference, ship an equivalent bounded MPS/MLX/Metal profile and conformance lane; otherwise that use case must name a remote CUDA/Jetson executor explicitly and local Apple execution remains unavailable. Provider selection is topology, not an implicit property of the CLI host.
- Training/evaluation/scanning outputs are content-addressed host artifacts. Only bounded metadata, hashes, metrics summaries, status, and refs cross Cohesix control surfaces; adapter bytes, datasets, gradients, weights, and prompt/training corpora never enter the VM or general telemetry.
- Activation records host-registry generation,
/gpu/models/*publication/ack, inference-runtime reload/canary observation, WorkerLora receipt, and rollback target as one recoverable transaction. Publication alone is not activation; activation alone is not a successful runtime reload. - Negative/live tests cover bad provenance, unsupported base/runtime combinations, path traversal/symlink races, corrupt or oversized artifacts, failed training/evaluation/scan, lost ticket agent, duplicate result, host crash at every phase boundary, partial publish, failed reload/canary, lease expiry/revocation, and rollback after process restart.
- Evidence packs include the bounded phase journal, registry generations, provider/executor receipts, evaluation/scan decisions, activation/canary/rollback results, CAS refs, and exact WorkerLora correlation, redacted where needed.
- The PEFT evidence manifest presents the transaction as one causal graph from operator approval and GPU admission through native launch, framework callbacks, adapter artifact, evaluation/scan, activation/reload/canary, and rollback. Full logs, checkpoints, CUDA traces, and adapter bytes remain in NVMe-backed CAS or configured object storage; the pack carries bounded hashes, summaries, cursors, and refs.
- Public examples and live playbooks must obtain adapter artifacts from the
declared executor and verify their framework/base-model compatibility,
provenance, signature/hash, evaluation, scan, and runtime behavior. Literal
adapter-bytes, synthetic metrics, fabricated job ids, and local client- authored receipts are permitted only in explicitly named test fixtures and cannot enter a live package or use-case proof. - Update the 27b integration and use-case rows for Model Rollout, Private LoRA Foundry,
mac-private-peft-grid, closed-loop AI factory, medical/Jetson demos, Operator-First, LeJEPA, Gesture Language, and any other PEFT consumer. A row remains non-production until its named executor/framework, target runtime, package, secrets, recovery, and live evidence pass. - Direct PEFT/NeMo/provider activation remains host-side and ticket-scoped; Cohesix records authority/evidence and bounded lifecycle state, not training internals.
As-built leverage:
- Reuse
coh peft,/gpu/models, host-ticket-agent, evidence timeline, and Milestone 27a audit/replay defaults.
8) Manifest-selectable NeMo runtime family (host-only, governed, cross-provider)
Purpose: Support NVIDIA NeMo where it creates clear operational leverage over simpler direct-serving alternatives, while keeping Cohesix as the authority, evidence, and policy layer.
Implementation requirements:
- Implement NeMo as a manifest-selectable host-side provider family under the Milestone 28e run-envelope contract, not as a new runtime plane:
nemo.inferfor NIM / NeMo Export-Deploy / Triton / TensorRT-LLM-backed inferencenemo.guardrailsfor safety policy evaluation and refusal receiptsnemo.evaluatefor model / RAG / agent evaluation jobs and score receiptsnemo.retrieveandnemo.customize, both host-side and ticket-scoped
- Add host capability probes that discover NeMo endpoints, deployed model profiles, guardrail policy ids, evaluator availability, and deployment state without making NeMo the source of truth.
- Add a NeMo Run executor adapter that binds the resolved experiment/config, executor/cluster identity, image and source digests, model/data/artifact refs, checkpoints, cancellation/recovery, evaluations, and terminal state to the same generated run/ticket/evidence envelope as the baseline provider.
- Add a NeMo Guardrails execution-rail adapter for consequential custom action and tool invocations: the before-action rail requests or validates the exact Cohesix ticket/grant and refuses on missing/stale/widened authority; the after-action rail records the bounded native result for shared verification. A guardrail verdict is policy evidence, not itself a Cohesix authority grant or provider-success receipt.
- Live NeMo-backed actuation remains ticketed and fenced:
- all mutating NeMo actions flow through delegated host tickets,
- all actions carry
id,idempotency_key, andwriter_epochwhere applicable, - unsupported or unauthorised NeMo actions fail deterministically with no side effects.
- Guardrail and evaluator outputs become first-class receipts and evidence inputs:
guardrail_policy_hash,guardrail_decision,evaluation_profile_hash,evaluation_job_ref,evaluation_summary_ref,deployment_config_hash.
- Cohesix must remain more valuable than direct NeMo or direct vLLM use:
- the same run envelope, delegated ticket model, evidence pack, and policy gates must work against NeMo and at least one alternate provider family,
- NeMo support must not introduce NeMo-only authoritative state or bypasses that other providers cannot satisfy.
- NeMo execution in this milestone remains a generated host-ticket provider action. Milestone 28f later normalizes it behind the same public compatibility API and provider-neutral inference receipt contract as every other accepted backend.
- NeMo Agent Toolkit, MCP, or A2A features may be consumed only as downstream host integrations behind existing Cohesix auth and evidence boundaries; they must not become public control surfaces or authoritative coordination channels.
8a) Jetson Orin Nano NeMo reference topology
Purpose: Make manifest-selectable NeMo support testable on the maintained 8GB Jetson without assuming that every NeMo component, container, or model is available on AArch64 or fits in shared memory.
Implementation requirements:
- Extend the generated
jetson-orin-nano-jp7profile with independently selected capabilities forlocal_infer,remote_infer,guardrails,evaluate,retrieve, andcustomize. A profile may legitimately enable only local edge inference while using remote guardrail/evaluator/customization services; missing capabilities return typednot_enabled,not_installed,incompatible, orunreachable, never an inferred healthy aggregate. - Probe NeMo Framework/Export-Deploy, NIM, Triton, TensorRT/TensorRT-LLM, Guardrails, Evaluator, and alternate providers separately. Do not assume a datacenter NIM or NeMo container supports Jetson AArch64 merely because Docker and the NVIDIA runtime are installed. Capture package or OCI digest, API and model-profile version, architecture, JetPack/L4T/CUDA compatibility, endpoint identity, auth-ref presence, deployment config hash, and observed capability.
- The local Jetson reference uses an isolated, reproducible venv or digest-pinned NVIDIA-container profile under the generated NVMe storage root; it never mutates the system Python environment or stores raw credentials in argv, manifests, logs, or evidence. Model, engine, tokenizer, adapter, and evaluation artifacts are content-addressed and include license/provenance metadata.
- Live local acceptance requires at least one selected licensable quantized reference model and engine whose weights, runtime workspace, KV/cache budget, and bounded batch-1 request fit beneath the live 27b Jetson GPU admission ceiling with reserved OS headroom. An 8B 4-bit edge model may be selected only after this measured preflight; model size or quantization labels alone are not proof that the workload fits or completes.
- A full NeMo training stack is not mandatory on the 8GB Nano. The generated topology explicitly identifies training/customization as local, remote, or unavailable. A remote training/PEFT transaction may promote a Jetson use case only when the returned artifact is provenance-checked and the exact Jetson inference runtime completes reload, canary, rollback, and WorkerLora receipt correlation.
- Live inference evidence records cold model load, peak device-visible and system memory, engine/workspace identity, request bounds, TTFT, bounded completion, output digest/summary, temperature/throttling observations, and cleanup. The run fails safely before allocation when the selected model or context budget exceeds current shared-memory headroom; no test deliberately drives the host into system OOM or changes power/network/display state.
- The currently unconfigured Jetson is a mandatory negative reference: with no NeMo/PyTorch/Transformers/Triton package, image, process, or endpoint selected, capability probes must return the complete stable unavailable shape and issue no pulls, installs, model downloads, provider calls, or host mutations.
As-built leverage:
- Reuse
host-ticket-agent,cohesix-pyorchestration/playbooks, evidence packs, telemetry exports, GPU lease flows, and production audit/replay defaults from Milestone 27a.
Commands
cargo test -p host-ticket-agentcargo test -p cohpython -m pytest tools/cohesix-py/tests/test_orchestration.pypython -m pytest tools/cohesix-py/tests/test_playbooks.pypython -m pytest tools/cohesix-py/tests/test_evidence_receipts.pypython -m pytest tools/cohesix-py/tests/test_integrations.py -k nemopython -m pytest tools/cohesix-py/tests/test_playbooks.py -k nemocargo test -p tests --test host_ticket_agent -- nemocohesix-playbook --playbook long-context-agent-factory --dry-run --mockcohesix-playbook --playbook long-context-agent-factory --dry-run --mock --metrics-out out/bench/m28e-ai-run-cost.jsoncargo test -p worker-gpu && cargo test -p worker-lora && cargo test -p worker-heartcargo test -p coh --test peft && cargo test -p coh --test peft_registry_transactionsscripts/ci/provider_conformance_run.sh --provider peft --live-reference --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28e-peft-livescripts/ci/use_case_gate.sh --promote-milestone 28e --only peft --matrix configs/generated/use_case_evidence.json --state-dir out/use-case-gate/m28e-peft-livescripts/ci/provider_conformance_run.sh --provider nemo --host-profile jetson-orin-nano-jp7 --capability-only --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28e-nemo-jetson-unavailablescripts/ci/provider_conformance_run.sh --provider nemo --host-profile jetson-orin-nano-jp7 --live-reference --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28e-nemo-jetson-livescripts/ci/use_case_gate.sh --promote-milestone 28e --only nemo-jetson --matrix configs/generated/use_case_evidence.json --state-dir out/use-case-gate/m28e-nemo-jetson
Checks (Definition of Done)
- Multi-agent host workflows never require an undifferentiated shared Queen writer.
- A run can restart from checkpoint/evidence with the same authoritative constraints and receipts, without reconstructing a full prompt transcript.
- Evidence-only reconstruction preserves task graph ordering, handoff lineage, semantic snapshot, Context Capsule, render-profile, retrieval-manifest identity, native execution and framework-callback correlation, verification, recovery, and offloaded tool-artifact references.
- AI orchestration consumes accepted 28b semantic artifacts by immutable reference; it cannot silently rebuild, mutate, or substitute an unreceipted capsule.
- Prefix/hotset reuse is bounded by TTL/quota, attributable to a caller, and visible in evidence.
- Prefix cache hits and misses are explainable from bounded semantic-snapshot/capsule/render/provider eligibility and invalidation fields rather than hidden provider behavior.
- Strategy selection and long-context cost metrics are observable per run/step.
- High-risk live AI mutations remain policy-gated and ticket-scoped.
- Worker-role documentation and generated snippets consume the accepted 26e executable contracts and match actual kernel/host implementation boundaries; no AI task depends on undocumented VM Worker behavior or a session-only
ATTACH. - PEFT export, train, evaluate, scan, import, activation, inference-runtime reload/canary, and rollback are one idempotent, crash-recoverable, provenance-complete host transaction with exact systemd/Docker/CUDA, framework-callback, artifact/base-model, and WorkerLora correlation; publication, a callback, a native label/notification, or a registry rename alone cannot pass.
- At least one open PEFT executor and target inference runtime pass live end-to-end conformance. Other framework/provider families remain explicitly integration-pattern, mock, dry-run, or not-enabled until they pass the same generated contract.
- Every declared PEFT/LoRA consumer resolves to a named live reference topology and complete transaction; CUDA is shipped as the baseline real provider, local Apple execution is real and packaged wherever advertised, and otherwise the Mac playbook names a remote CUDA/Jetson executor. Literal adapter bytes, synthetic metrics/job ids, and client-authored receipts remain fixture-only and cannot pass.
- Every AI/PEFT scenario, playbook, and post-M24 activity is reclassified in the 27b use-case matrix from actual executor, Worker, package, recovery, and evidence records; no mock workflow is promoted by documentation alone.
- The Verified Private LoRA Release passes as one ticket-centred Jetson journey that an operator can plan, apply, watch, explain, verify, recover, and export; its SwarmUI-ready graph is derived from the same validated evidence manifest and cannot create or promote proof.
- Manifest-selectable NeMo support remains host-side, ticket-scoped, writer-fenced, and evidence-backed; disabling NeMo leaves the baseline 28e substrate intact.
- The same Cohesix run envelope and evidence model works against NeMo and at least one alternate provider family, proving NeMo support adds governed lifecycle value rather than vendor-specific lock-in.
- A selected NeMo Run executor preserves resolved experiment/executor/artifact, checkpoint, cancel/recovery, evaluation, and terminal identity; Guardrails before/after execution rails fail closed around consequential tools and remain policy observations rather than Cohesix grants or provider receipts.
- The
jetson-orin-nano-jp7NeMo profile passes both the mutation-free unconfigured capability lane and a separately provisioned live-reference lane before any Jetson NeMo use case is promoted. Local inference, remote services, guardrails, evaluation, retrieval, and customization remain independent capabilities; Docker/NVIDIA runtime presence, a downloaded model, or a successful generic CUDA job cannot promote any of them. - Guardrail and evaluator receipts can gate live promotion or actuation decisions deterministically in dry-run/mock tests before any real provider mutation is allowed.
- AI run-cost evidence records checkpoint/resume, semantic-object selection, capsule rendering, prefix/hotset reuse, prompt bytes avoided, provider queue-wait simulation, and evidence export overhead for the dry-run/mock playbook; material regressions are classified as semantic selection, host orchestration, provider adapter, evidence-pack, or gateway overhead before 28f or 30b depends on the run model. Actual provider TTFT, streaming, usage, cache, and completion evidence is accepted only under 28f.
- No new in-VM listeners, runtime, or control protocols are introduced.
Compiler touchpoints
coh-rtcemits generated host-tool defaults for AI run envelope limits, task-graph/handoff bounds, context budget ceilings, accepted 28b semantic snapshot/Context Capsule/render-profile reference bounds, retrieval-manifest and artifact-ref bounds, prefix/hotset TTLs, metrics bounds, and the phase-journaled PEFT executor/transaction contract under the existing host policy/codegen path. It consumes and references the 28b schemas; it does not redefine them.coh-rtcalso emits framework-callback event bounds, native execution correlation requirements, PEFT safetensors/config/base-model bindings, evidence-profile/ref limits, and manifest-selectable NeMo Run/Guardrails execution-rail mappings under the 27b provider-adapter contract.- Manifest validation rejects AI host-control enablement when Milestone 27a delegated identity or audit/replay requirements are disabled in the target profile.
- Manifest validation rejects AI host-control enablement when Milestone 27b provider registry, read visibility, identity mapping, provider conformance, or use-case evidence requirements are missing for a side-effecting provider action.
- Selected live-provider mutation tests prove that the Python,
inference, PEFT, and model-registry adapters cannot bypass
/host/tickets/spec,host-ticket-agent, generated provider action validation, delegated ticket scope, idempotency, writer epoch, and evidence receipts. NeMo, Kubernetes, Docker, systemd, and other unselected helpers prove typed unavailable behavior until their own provider rows are promoted. - Manifest/docs validation rejects worker-role claims that exceed the current code/generated worker implementation boundary.
coh-rtcemits PEFT/model registry transaction/provenance bounds, allowed framework/provider profiles, artifact/ref formats, evaluation/scan gates, runtime reload/canary requirements, recovery rules, WorkerLora correlation, and use-case promotion obligations consumed by host tools and evidence exports.- Generated PEFT profiles also declare execution topology, CUDA or Apple provider/runtime compatibility, exact package extras, live-reference dataset/base-model licences and hashes, and whether a use case is unavailable when its external domain application is absent.
coh-rtcadditionally emits manifest-controlled provider-family policy for NeMo capability probes, action allowlists, endpoint/auth refs, deployment/evaluation/guardrail bounds, and alternate-provider parity requirements.- Canonical interface/architecture docs refreshed in:
docs/INTERFACES.mddocs/ARCHITECTURE.md
- Generated host-tool/docs snippets refreshed in:
docs/PYTHON_SUPPORT.mddocs/HOST_TOOLS.mddocs/SECURITY.mddocs/TEST_PLAN.md
Task Breakdown
Title/ID: m28e-ai-intent-adapter
Milestone: 28e / AI intent adapter
Delivery: Required for complete 28e acceptance.
Goal: Convert AI-supervisor proposals into 28c typed intents and require accepted decision-bound grants for every governed live AI side effect without creating an AI-specific guardrail path.
Inputs: accepted 28b semantic/capsule schemas, accepted 28c intent/fact/decision/grant contracts, 27b provider/action admission metadata, 27a host-ticket identity/idempotency/fencing/WAL, AI run/PEFT/checkpoint/prefix action schemas.
Changes:
- tools/coh-rtc/src/ir.rs + codegen — generated mappings from AI run, checkpoint, prefix, PEFT, model-promotion, and supervisor action records to exact 28c intent schemas, required fact sources, policy ids, grant ceilings, freshness/recheck modes, and receipt fields.
- host AI adapters and host-ticket-agent integration — accept model-drafted bounded fields as untrusted intent input, resolve authoritative facts through registered sources, attach the accepted `admission_id`, and refuse policy activation/modification, self-authoritative model facts, confidence-as-verdict, grant widening, or stale decisions.
- dry-run/evidence fixtures — show proposed intent plus predicted/simulated outcome without reservation or grant; bind every governed live side effect and high-risk PEFT promotion to the accepted 28c decision in addition to existing 28e transaction evidence.
- docs/ARCHITECTURE.md + docs/INTERFACES.md + docs/SECURITY.md + docs/PYTHON_SUPPORT.md — AI proposal/admission boundary and exact live versus dry-run semantics.
Commands:
- cargo test -p coh-rtc
- cargo test -p host-ticket-agent --test ai_admission
- python3 -m pytest -q tools/cohesix-py/tests/test_integrations.py -k ai_intent
- scripts/check-generated.sh
Checks:
- AI can draft only schema-valid intent fields; it cannot select/modify policy or promote assertions; model confidence is never a verdict; dry-run creates no grant; every governed live AI/PEFT/model-promotion side effect carries an accepted non-stale `admission_id` and uses the existing host-ticket/provider executor path.
Deliverables:
- One 28c-backed AI intent adapter shared by all 28e live action families.
Title/ID: m28e-ai-run-envelopes
Milestone: 28e / m28e-ai-run-envelopes
Goal: Extend accepted 27c operation/stage identity with advanced AI run/task/step envelopes with explicit handoff, dependency, and context-budget contracts.
Inputs: accepted Milestone 28b semantic snapshot, Context Capsule, and render
receipt contracts; tools/cohesix-py/cohesix/orchestration.py,
tools/cohesix-py/cohesix/playbooks.py, docs/PYTHON_SUPPORT.md,
docs/SECURITY.md
Changes:
- tools/cohesix-py/cohesix/orchestration.py — RunRequest, RunTask, RunStep,
HandoffRef, SemanticSnapshotRef, ContextCapsuleRef,
ContextRenderProfileRef, RetrievalManifestRef, and ContextBudget validators
for delegated AI ticket flows.
- tools/cohesix-py/cohesix/playbooks.py — `long-context-agent-factory` dry-run/mock playbook with explicit task graph, delegation, and handoff receipts.
- tools/cohesix-py/cohesix/receipts.py — typed derived receipts for run/task/step/handoff identity.
- tools/cohesix-py/tests/test_orchestration.py + tools/cohesix-py/tests/test_playbooks.py — budget, idempotency, and dry-run coverage.
Commands: python -m pytest tools/cohesix-py/tests/test_orchestration.py && python -m pytest tools/cohesix-py/tests/test_playbooks.py
Checks: Invalid budget/policy/reference combinations fail before writes; dry-run
outputs show run/task/step identity, dependencies, handoffs, capsule/render
identity, and budgets deterministically.
Deliverables: Host-side AI runs become explicit, typed, replay-addressable, and suitable for delegated multi-agent coordination without hidden state.
Title/ID: m28e-host-ticket-ai-actions
Milestone: 28e / m28e-host-ticket-ai-actions
Goal: Extend the host ticket plane with bounded AI control actions for inference runs, checkpoints, and prefix lifecycle.
Inputs: accepted Milestone 27a operator-approval/identity/idempotency/WAL
contracts, accepted m28e-ai-intent-adapter for governed mode, apps/host-ticket-agent, docs/ARCHITECTURE.md, docs/INTERFACES.md,
docs/HOST_TOOLS.md
Changes:
- apps/host-ticket-agent/src/lib.rs — allowlist and schema validation for `infer.run|resume|abort`, `context.checkpoint|resume|evict`, and `prefix.warm|evict`; support authenticated operator approval and governed mode with exact 28c `admission_id` and immutable intent/policy/state/grant bindings. Policy selects the required checks; neither mode adds an AI-specific evaluator or treats unavailable admission as a governed decision.
- apps/host-ticket-agent/src/status.rs — bounded lifecycle/state counters for AI run, checkpoint, and prefix operations.
- apps/host-ticket-agent/src/executors/infer.rs — host-only provider adapter contract; no VM-side model runtime.
- docs/INTERFACES.md — canonical host-ticket AI action envelopes, receipt
fields, semantic snapshot/Context Capsule/render/retrieval refs, and refusal
semantics.
- docs/ARCHITECTURE.md — authority flow for delegated AI runs, checkpoints, prefix lifecycle, task handoffs, and evidence correlation.
Commands: cargo test -p host-ticket-agent && cargo test -p tests --test host_ticket_agent
Checks: AI host tickets stay idempotent, allowlist-gated, stale-writer safe,
and bound to policy-required authenticated operator approval and, in governed
mode, non-stale accepted 28c admission; unsupported or ambiguous
mode, missing approval/admission, widened grant, or stale-state actions fail
deterministically with no side effects; handoff/checkpoint references remain
bounded and attributable.
Deliverables: `/host/tickets/spec` becomes the canonical AI actuation path before 30b VM roots exist.
Title/ID: m28e-ai-evidence-checkpoints
Milestone: 28e / m28e-ai-evidence-checkpoints
Goal: Extend accepted 27b/27c evidence pack/timeline flows to reconstruct AI runs from checkpoints, receipts, and cost telemetry.
Inputs: apps/coh/src/evidence.rs, apps/coh/src/evidence_timeline.rs, apps/coh/tests/evidence_pack.rs, apps/coh/tests/evidence_timeline.rs, docs/TEST_PLAN.md
Changes:
- apps/coh/src/evidence.rs — include run envelopes, checkpoint manifests,
immutable semantic snapshot/Context Capsule/render receipts, retrieval
manifests, offloaded tool-artifact refs, prefix reuse stats, and provider
receipts with redaction.
- apps/coh/src/evidence_timeline.rs — correlate run/task/step/handoff/checkpoint/prefix events into a deterministic operator timeline.
- evidence graph projection — join approval/decision/grant, native
systemd/Docker/Kubernetes/CUDA execution identities, framework callbacks,
artifacts, verification, terminal receipts, and recovery into the 27b
causal manifest; expose a bounded SwarmUI-ready graph projection while
retaining the evidence core as authority.
- apps/coh/tests/evidence_pack.rs + apps/coh/tests/evidence_timeline.rs — restart/resume reconstruction tests from evidence-only inputs.
Commands: cargo test -p coh --test evidence_pack && cargo test -p coh --test evidence_timeline
Checks: Evidence-only reconstruction preserves authoritative constraints,
handoff lineage, semantic snapshot/capsule/render/retrieval identity, native
execution/callback correlation, verification, recovery, and receipts;
sensitive keys stay redacted, omitted external artifacts remain explicitly
missing, and UI/OTel/CloudEvents/attestation projections cannot become
authority.
Deliverables: Long-context AI runs become auditable and resumable without prompt archaeology or transcript dependence.
Title/ID: m28e-ai-policy-and-metrics
Milestone: 28e / m28e-ai-policy-and-metrics
Goal: Generate host defaults and bounded metrics for AI context budgets, prefix reuse, and run efficiency.
Inputs: accepted Milestone 28b bounds and generated schemas; tools/coh-rtc,
configs/root_task.toml, apps/coh/src/telemetry.rs,
tools/cohesix-py/cohesix/generated.py, docs/PYTHON_SUPPORT.md,
docs/TEST_PLAN.md
Changes:
- tools/coh-rtc/src/ir.rs + tools/coh-rtc/src/validate.rs — host AI
budget/TTL/metrics bounds, 28b semantic snapshot/capsule/render reference
use, retrieval/offload bounds, task-graph/handoff bounds, and dependency on
27a safety gates without redefining the 28b object schemas.
- apps/coh/src/telemetry.rs — bounded run-efficiency metric export helpers.
- tools/cohesix-py/cohesix/generated.py — generated defaults consumed by Python orchestration/playbooks.
Commands:
- cargo test -p coh-rtc
- cargo test -p coh
- python -m pytest tools/cohesix-py/tests/test_evidence_receipts.py
- cohesix-playbook --playbook long-context-agent-factory --dry-run --mock --metrics-out out/bench/m28e-ai-run-cost.json
Checks: Generated defaults bind accepted 28b references and bound AI runs
consistently across CLI/Python flows; cache eligibility/invalidation fields and
metrics stay bounded and byte-stable; dry-run/mock run-cost evidence reports
semantic selection, capsule rendering, checkpoint/resume, prefix reuse, prompt
bytes avoided, and evidence export overhead without invoking live providers.
Deliverables: Context budgets, retrieval/offload bounds, and efficiency metrics are compiler-aligned rather than ad hoc.
Title/ID: m27d-framework-adapters
Milestone: 28e / m27d-framework-adapters
Goal: Provide host-side reference adapters that let external supervisors coexist with Cohesix through delegated tickets, Context Capsules, checkpoints, and evidence exports.
Inputs: accepted Milestone 28b Python helpers and Context Capsule contract;
tools/cohesix-py/cohesix/integrations.py, tools/cohesix-py/examples/,
docs/PYTHON_SUPPORT.md, docs/HOST_TOOLS.md
Changes:
- tools/cohesix-py/cohesix/integrations.py — reference supervisor adapter
helpers for immutable capsule selection/inspection, delegated submission,
receipt polling, checkpoint lookup, and evidence export.
Include a generated `ticketed_run` context and read-only framework callback
interface for run/checkpoint/evaluation/artifact/cancel/terminal
observations; callbacks submit only validated ticket requests and cannot
call native providers or author authoritative receipts.
- tools/cohesix-py/examples/ — bounded examples for repo-scale analysis and dry-run delegated handoff flows.
- docs/PYTHON_SUPPORT.md + docs/HOST_TOOLS.md — integration contract for external supervisors over delegated tickets and evidence receipts.
Commands: python -m pytest tools/cohesix-py/tests/test_integrations.py && python -m pytest tools/cohesix-py/tests/test_examples_ci_siem.py
Checks: Reference adapters use accepted semantic/capsule refs, delegated
tickets, explicit handoff/checkpoint refs, generated provider actions, and
evidence exports only; no hidden side-channel state, direct `/queen/ctl`
mutation, direct provider API mutation, or direct host executor call is
required or accepted.
Deliverables: Cohesix remains the authority/evidence layer beneath supervisor frameworks instead of becoming one.
Title/ID: m28e-worker-boundary-closure
Milestone: 28e / m28e-worker-boundary-closure
Goal: Verify Worker role documentation, generated snippets, and AI run references consume the accepted 26e executable Worker boundary without replacing it with session/model state.
Inputs: accepted 26e Worker image/ABI/QEMU/Pi component and integration records, the 27b provider/integration/use-case graph, and, only for production ticket/lease-to-bundle claims, accepted 28d ledger evidence; apps/worker-heart, apps/worker-gpu, apps/worker-lora, docs/GPU_NODES.md, docs/WORKER_TICKETS.md, docs/ROLES_AND_SCHEDULING.md, docs/INTERFACES.md
Changes:
- apps/worker-heart/src/kernel.rs + apps/worker-gpu/src/kernel.rs + apps/worker-lora/src/lib.rs — verify every enabled executable target contract against the accepted capability, notification, MCS scheduling, fault, revocation, and exact-target evidence; keep model/session helpers clearly non-authoritative.
- docs/GPU_NODES.md + docs/WORKER_TICKETS.md + docs/ROLES_AND_SCHEDULING.md — describe executable Worker roles exactly as built while separating Worker lifecycle/receipts from host GPU/PEFT execution and session-only `ATTACH`.
- tools/coh-rtc/src/validate.rs — reject generated worker-spawn claims that do not match enabled worker implementation status.
- apps/root-task/tests/worker_docs_alignment.rs — guard documented worker paths and generated role state against implementation drift.
Commands: cargo test -p worker-heart && cargo test -p worker-gpu && cargo test -p worker-lora && cargo test -p root-task --test worker_docs_alignment
Checks: Docs neither overclaim nor undercut Worker behavior; executable roles and session-only `ATTACH` remain explicit; every executable-task claim used by AI run control is backed by code, generated manifest state, target-created objects, cap-backed authority, durable completion/notification lifecycle, applied MCS scheduling, complete fault/revocation evidence, exact QEMU/Pi records, and tests; only production ticket/lease-to-bundle claims require and cite 28d.
Deliverables: Host-side AI orchestration has an honest worker boundary and cannot cite undocumented or stale worker semantics.
Title/ID: m28e-broader-peft-provider-transactions
Milestone: 28e / m28e-broader-peft-provider-transactions
Goal: Extend the accepted 27d PEFT transaction to NeMo, Apple and broader native providers, retaining its evaluation comparison, generation recheck and rollback semantics.
Inputs: accepted 27c lifecycle and 27d HF/private-LoRA transaction, accepted 26e WorkerLora receipt path, m27b-authoritative-receipt-and-evidence-core, 27b PEFT/external-executor/use-case rows, apps/coh/src/peft, apps/coh/src/evidence.rs, apps/host-ticket-agent, apps/gpu-bridge-host, tools/cohesix-py, CAS/evidence tools, docs/GPU_NODES.md, docs/SECURITY.md, docs/TEST_PLAN.md
Changes:
- tools/coh-rtc/src/ir.rs + generated provider/integration records — bounded PEFT phase schemas, artifact/provenance refs, provider/framework profiles, evaluation/scan gates, runtime compatibility, recovery, WorkerLora correlation, explicit operator-approval policy and 28c decision requirements for governed promotion and high-risk live phases.
- apps/coh/src/peft/mod.rs — extend the accepted 27d phase journal, registry lock, canonical-path/symlink confinement, unique same-filesystem temp files, file/directory fsync and rename ordering, CAS artifacts, metadata validation, compare-and-swap generations, and rollback-safe transaction records.
- apps/coh/src/peft/activate.rs — extend accepted 27d generation/evaluation checks and correlate registry generation, `/gpu/models/*` publish/ack, inference-runtime reload/canary observation, WorkerLora receipt, and rollback target as one recoverable activation transaction.
- apps/host-ticket-agent/src/executors/peft.rs — execute generated `peft.export|train|evaluate|scan|import|activate|runtime_reload|canary|rollback` phases through named host providers with crash-safe idempotency and exact 26e WorkerLora result delivery.
- tools/cohesix-py/cohesix/integrations.py — bounded reference adapter for at
least one open PEFT executor plus Hugging Face PEFT/TRL and NeMo
provider profiles under the same schema; never arbitrary shell or paths.
The Hugging Face profile provides a read-only Trainer callback for train-
begin, checkpoint-save, evaluation, and train-end observations and binds
genuine `adapter_model.safetensors`, `adapter_config.json`, base-model
revision/digest, tokenizer/config, framework/CUDA versions, dataset manifest,
resolved training configuration, measured metrics, and model-card ref.
- apps/coh/src/evidence.rs + apps/coh/src/evidence_timeline.rs — include
bounded phase journal, native execution and framework-callback correlation,
provenance, evaluation/scan, activation/reload/canary/rollback, CAS,
provider, and WorkerLora receipts as one causal evidence graph.
- docs/GPU_NODES.md + docs/HOST_TOOLS.md + docs/PYTHON_SUPPORT.md + docs/USE_CASES.md + docs/SECURITY.md + docs/TEST_PLAN.md — document the full transaction, host/VM data boundary, package/provider requirements, failure recovery, and use-case promotion.
Commands: cargo test -p coh --test peft && cargo test -p coh --test peft_registry_transactions && cargo test -p host-ticket-agent && python -m pytest tools/cohesix-py/tests/test_integrations.py -k peft && scripts/ci/provider_conformance_run.sh --provider peft --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28e-peft
Checks: A live reference path completes every phase with verified provenance,
native systemd/Docker/CUDA identity, callback/checkpoint correlation,
safetensors/config/base-model compatibility, thresholds, scan, CAS refs,
runtime observation, exact WorkerLora receipt, and evidence; injected crash/
timeout/duplicate/revocation/partial-publish/reload failure at every phase
boundary resumes or compensates without duplicate effects; unsupported
providers stay non-production, and callback or native metadata alone never
satisfies a phase.
Deliverables: Complete PEFT/LoRA transactions support operator-approved and
governed execution, consuming 28c grants wherever the action policy requires
admission, with independent evidence for both modes.
Title/ID: m28e-broader-peft-reference-paths
Milestone: 28e / m28e-broader-peft-reference-paths
Goal: Qualify broader PEFT/provider profiles and domain consumers over the accepted 27d release recipe, without repeating or redefining its base acceptance.
Inputs: m28e-broader-peft-provider-transactions, m28a-public-surface-live-mode-gate, m28a-gpu-workload-and-mig-executor, m27c-recipe-lifecycle-and-identity, tools/cohesix-py/examples/peft_roundtrip.py, tools/cohesix-py/cohesix/{integrations.py,playbooks.py}, provider/package registries, CUDA and Apple ML provider hosts, reference base models/dataset manifests, supported inference runtimes, accepted WorkerLora evidence.
Changes:
- CUDA reference profile — package and pin a bounded open PEFT training/evaluation stack, base-model and dataset manifest, adapter format, scanner, and compatible inference runtime; execute the full export/train/evaluate/scan/import/activate/reload/canary/rollback transaction through generated host tickets and the live GPU executor.
- systemd/Docker launch profile — run the selected training/evaluation and
runtime canary through a hardened systemd unit and digest-pinned NVIDIA
container, correlating unit invocation, image/container/events, CUDA
device/job, callback checkpoints, artifacts, and terminal receipts. The Kubernetes profile substitutes its accepted CRD/controller execution shape
without changing the workflow or receipt schema.
- Apple and other declared reference profiles — implement and qualify each
named local MPS/MLX/Metal or remote use case with its package, phase/receipt
contract, and live evidence. Unsupported deployment capabilities return
typed unavailable; they cannot satisfy that profile's acceptance.
- tools/cohesix-py/examples/peft_roundtrip.py — separate explicit mock fixture mode from live mode. Live mode consumes a genuine executor-produced adapter and measured metrics, validates provenance/signature/hash/framework/base/runtime compatibility, and never writes literal adapter bytes or authors its own authoritative receipt.
- tools/cohesix-py/cohesix/playbooks.py + use-case graph — bind the selected
reference **Verified Private LoRA Release** walkthrough to its Jetson
executor/framework/runtime/package/recovery/evidence profile and the 27b
ticket-centred plan/watch/explain/verify/recover lifecycle. Model Rollout,
Private LoRA Foundry, `mac-private-peft-grid`, closed-loop factory,
medical/Jetson, Operator-First, LeJEPA, Gesture Language, and other declared
PEFT consumers use the same transaction; qualify their required provider
profiles. Disabled or unsupported deployments return typed unavailable.
- packages/tests/evidence — ship exact Python/provider extras and model/runtime compatibility metadata; use small licensable reference inputs for deterministic functional tests, plus selected live-provider acceptance evidence and crash/failure injection at every phase.
Commands: python -m pytest tools/cohesix-py/tests/test_integrations.py -k peft && python -m pytest tools/cohesix-py/tests/test_playbooks.py -k peft && scripts/ci/provider_conformance_run.sh --provider peft --live-reference --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28e-peft-live && scripts/ci/use_case_gate.sh --promote-milestone 28e --only peft --matrix configs/generated/use_case_evidence.json --state-dir out/use-case-gate/m28e-peft-live
Checks: The selected reference PEFT/LoRA row resolves to and passes a complete
genuine adapter lifecycle on Jetson; systemd/Docker/CUDA execution identity,
callback checkpoints, safetensors/config/base-model binding, measured metrics,
evaluation/scan results, reload/canary, rollback, CAS hashes, provider identity,
and WorkerLora terminal record are observed and correlated in one ticket graph.
Mock artifacts and synthetic metrics remain isolated fixtures. Qualify declared
Kubernetes, NeMo, Apple, and other provider rows independently; deployment
unavailability cannot replace their required implementation evidence.
Deliverables: One real packaged Verified Private LoRA Release on Jetson with a
live CUDA/PEFT/systemd/Docker execution and evidence path; additional provider
shapes remain independent future promotions over the same envelope.
Title/ID: m28e-ai-use-case-promotion
Milestone: 28e / m28e-ai-use-case-promotion
Goal: Promote selected AI and PEFT scenarios only when their complete
executable-Worker, provider, data-plane, package, recovery, and evidence chains
are live.
Inputs: m28e-broader-peft-provider-transactions, m28e-broader-peft-reference-paths, AI run/checkpoint/provider tasks, configs/generated/use_case_evidence.json, all 27b AI/PEFT rows, live conformance records, release manifests.
Changes:
- scripts/ci/use_case_gate.sh — 28e promotion mode for AI run and PEFT pipeline dependencies, including reference executor/runtime and exact WorkerLora receipt evidence.
- docs/USE_CASES.md + post-M24 activity blocks — generated maturity
classifications that promote only the selected reference inference/PEFT
walkthroughs and leave every other AI/PEFT consumer unavailable or at its
previously proven lower tier.
- apps/coh/src/evidence.rs — bind use-case id and dependency-graph hash to AI/PEFT evidence packs.
Commands: scripts/ci/use_case_gate.sh --promote-milestone 28e --matrix configs/generated/use_case_evidence.json --state-dir out/use-case-gate/m28d && cargo test -p coh --test evidence_pack
Checks: A mock/dry-run workflow, registry-only mutation, model publication, or Worker receipt alone cannot promote a use case; each production row reconstructs the full live chain and exact failure recovery.
Deliverables: Public AI/PEFT claims are machine-gated by actual end-to-end implementation.
Title/ID: m28e-nemo-capability-probes
Milestone: 28e / m28e-nemo-capability-probes
Goal: Detect and classify manifest-selectable NeMo runtime capabilities without making NeMo the source of truth.
Inputs: tools/cohesix-py/cohesix/integrations.py, tools/cohesix-py/cohesix/generated.py, docs/PYTHON_SUPPORT.md, docs/HOST_TOOLS.md
Changes:
- tools/cohesix-py/cohesix/integrations.py — `probe_nemo_runtime`, `probe_nemo_guardrails`, and `probe_nemo_evaluator` helpers that resolve configured local packages/containers and remote endpoints/auth refs, deployed model profiles, architecture/runtime compatibility, and independent capability summaries without pulling images, downloading models, or mutating the host.
- tools/cohesix-py/cohesix/generated.py — generated NeMo capability defaults and bounded endpoint/profile limits from `coh-rtc`.
- docs/PYTHON_SUPPORT.md + docs/HOST_TOOLS.md — operator-visible NeMo capability probe contract and failure semantics.
Commands: python -m pytest tools/cohesix-py/tests/test_integrations.py -k nemo_probe
Checks: Capability probes are read-only, bounded, deterministic, and return the same shape whether NeMo is unavailable, partially configured, or fully available.
Deliverables: Cohesix can reason about NeMo availability and profile shape before choosing provider strategy or issuing any host-ticket mutation.
Title/ID: m27d-nemo-provider-family
Milestone: 28e / m27d-nemo-provider-family
Goal: Add NeMo-backed provider adapters under the same delegated ticket, checkpoint, and evidence contract as other AI backends.
Inputs: accepted Milestone 28b Context Capsule contract;
apps/host-ticket-agent/src/executors/infer.rs,
tools/cohesix-py/cohesix/orchestration.py, docs/ARCHITECTURE.md,
docs/INTERFACES.md
Changes:
- apps/host-ticket-agent/src/executors/infer.rs — manifest-selectable NeMo provider
adapters for `nemo.infer`, `nemo.guardrails`, and `nemo.evaluate`, plus a
NeMo Run executor binding resolved experiment/config, executor/cluster,
source/image/model/data/artifact identity, checkpoints, cancel/recovery,
evaluations, and terminal state to the common run/ticket envelope; include
Context Capsule refs, deterministic refusal mapping, and bounded provider-
action receipt fields.
- tools/cohesix-py/cohesix/orchestration.py — provider-family selection hints
and host-ticket provider receipt normalization for NeMo vs alternate
backends.
- docs/INTERFACES.md + docs/ARCHITECTURE.md — host-ticket NeMo action
envelopes, receipt fields, and authority mapping back to delegated tickets,
capsules, and checkpoints; reserve public compatibility and
provider-neutral inference receipt semantics for Milestone 28f.
Commands: cargo test -p host-ticket-agent && cargo test -p tests --test host_ticket_agent -- nemo_provider
Checks: NeMo-backed actions are idempotent, allowlist-gated, writer-fenced, and
produce the same internal host-ticket provider receipt contract as alternate
providers; unsupported NeMo features fail deterministically with no side
effects; no public API compatibility claim is made before 28f.
Deliverables: NeMo is a manifest-selectable provider family beneath Cohesix rather than a special-case control plane.
Title/ID: m28e-nemo-guardrails-and-eval
Milestone: 28e / m28e-nemo-guardrails-and-eval
Goal: Make NeMo guardrail and evaluator results first-class policy receipts that can gate live AI actions.
Inputs: apps/coh/src/evidence.rs, apps/coh/src/evidence_timeline.rs, tools/cohesix-py/cohesix/playbooks.py, docs/SECURITY.md, docs/TEST_PLAN.md
Changes:
- apps/coh/src/evidence.rs + apps/coh/src/evidence_timeline.rs — include guardrail policy hashes, decisions, evaluation refs/summaries, and deployment config hashes in evidence and timeline correlation.
- NeMo Guardrails integration — add a bounded execution-rail adapter for
consequential custom actions/tools. The before-action rail validates the
exact ticket/grant and the after-action rail submits a bounded native result
for shared verification; neither rail can mint authority or terminal proof.
- tools/cohesix-py/cohesix/playbooks.py — dry-run/mock playbooks that require successful NeMo guardrail/evaluator receipts before promotion or live mutation steps become admissible.
- docs/SECURITY.md + docs/TEST_PLAN.md — policy-gating contract for NeMo-backed guardrails/evaluations and additive regression expectations.
Commands: cargo test -p coh --test evidence_pack && cargo test -p coh --test evidence_timeline && python -m pytest tools/cohesix-py/tests/test_playbooks.py -k nemo_gate
Checks: Guardrail/evaluator receipts are durable, redacted where needed,
correlated to run/task/step and exact tool-action identity, and can
deterministically block promotion or actuation in mock and evidence-only
reconstruction paths; before/after rail ordering, timeout, refusal, duplicate,
and missing-after-action cases fail closed, and a guardrail decision never
substitutes for provider verification.
Deliverables: NeMo safety and evaluation add operational value to Cohesix instead of existing as unaudited provider-side metadata.
Title/ID: m28e-nemo-policy-and-parity
Milestone: 28e / m28e-nemo-policy-and-parity
Goal: Enforce that manifest-selectable NeMo support remains governed, bounded, and more valuable than direct backend-specific alternatives.
Inputs: tools/coh-rtc/src/ir.rs, tools/coh-rtc/src/validate.rs, tools/cohesix-py/cohesix/generated.py, docs/BUILD_PLAN.md, docs/HOST_TOOLS.md
Changes:
- tools/coh-rtc/src/ir.rs + tools/coh-rtc/src/validate.rs — manifest-selectable NeMo endpoint/auth refs, action allowlists, receipt-field bounds, and alternate-provider parity requirements under the host AI policy path.
- tools/cohesix-py/cohesix/generated.py — compiler-aligned NeMo policy defaults consumed by orchestration and probes.
- docs/HOST_TOOLS.md — operational guidance stating that NeMo implementation is required, host-side, and governed by the same Cohesix authority/evidence model as other providers.
Commands: cargo test -p coh-rtc && python -m pytest tools/cohesix-py/tests/test_integrations.py -k nemo_policy
Checks: Invalid NeMo policy, missing delegated-authority prerequisites, or NeMo-only authoritative semantics are rejected at validation time; the same run envelope/evidence contract remains valid with NeMo disabled or replaced by another provider family.
Deliverables: NeMo support is compiler-governed, manifest-selectable, and cross-provider rather than a lock-in path.
Title/ID: m28e-nemo-jetson-reference-profile
Milestone: 28e / m28e-nemo-jetson-reference-profile
Goal: Prove manifest-selectable NeMo capabilities on the maintained Jetson Orin Nano 8GB topology with exact resource, package, model, runtime, authority, and evidence boundaries.
Inputs: accepted m27b-jetson-orin-nano-live-conformance evidence, accepted 28b Context Capsule and 28c admission contracts, m28e-nemo-capability-probes, m27d-nemo-provider-family, m28e-nemo-guardrails-and-eval, m28e-nemo-policy-and-parity, generated `jetson-orin-nano-jp7` profile, NVIDIA runtime/package compatibility metadata, NVMe model/runtime storage, docs/HOST_TOOLS.md, docs/GPU_NODES.md, docs/TEST_PLAN.md.
Changes:
- configs/provider_conformance.toml + generated NeMo policy/profile records — independent local/remote inference, guardrail, evaluator, retrieval, and customization capability selection; exact AArch64/JetPack/L4T/CUDA/package-or-image compatibility; shared-memory/context ceilings; endpoint/auth refs; artifact/license/provenance requirements; and stable unavailable reasons.
- tools/cohesix-py/cohesix/integrations.py — mutation-free Jetson unavailable probe plus configured local-container/venv and remote-endpoint probes with bounded timeouts, redaction, version negotiation, and no ambient credential discovery.
- apps/host-ticket-agent/src/executors/infer.rs — admitted Jetson NeMo dispatch through the generated provider record, exact 27b GPU lease/executor and model-engine identity, bounded request/context, deterministic refusal mapping, cancellation/deadline, and normalized terminal receipt.
- packaging/reference assets — one digest-pinned, licensable quantized edge model/runtime profile that passes measured 8GB admission, and a remote-service profile for guardrail/evaluator/customization capabilities that are not selected locally. Artifacts and caches use the generated NVMe root; no model or mutable image layer enters a release bundle unintentionally.
- scripts/ci/provider_conformance_run.sh + scripts/ci/use_case_gate.sh — `--host-profile jetson-orin-nano-jp7` capability-only and live-reference lanes, exact-host preflight, model/runtime compatibility checks, safe memory refusal, cold/warm inference, cancel/timeout/restart, guardrail/evaluator refusal and success, evidence reconstruction, and promotion gating.
- docs/HOST_TOOLS.md + docs/GPU_NODES.md + docs/TEST_PLAN.md + docs/USE_CASES.md — exact setup, storage, topology, resource ceilings, supported/unavailable capabilities, test commands, recovery, and proof boundaries.
Commands: python -m pytest tools/cohesix-py/tests/test_integrations.py -k 'nemo and jetson' && cargo test -p host-ticket-agent -- nemo_provider && scripts/ci/provider_conformance_run.sh --provider nemo --host-profile jetson-orin-nano-jp7 --capability-only --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28e-nemo-jetson-unavailable && scripts/ci/provider_conformance_run.sh --provider nemo --host-profile jetson-orin-nano-jp7 --live-reference --matrix configs/provider_conformance.toml --state-dir out/provider-conformance/m28e-nemo-jetson-live && scripts/ci/use_case_gate.sh --promote-milestone 28e --only nemo-jetson --matrix configs/generated/use_case_evidence.json --state-dir out/use-case-gate/m28e-nemo-jetson
Checks: The unconfigured host produces a complete mutation-free unavailable record; the configured profile proves one real bounded inference and its exact model/engine/GPU/ticket/Worker/evidence chain; selected guardrail/evaluator capabilities gate promotion with durable receipts; remote services are identified separately from local execution; over-budget, incompatible, unauthorised, stale, timeout, cancellation, restart, and rollback cases fail safely; full local training, NIM, Triton, TensorRT-LLM, retrieval, or customization remain unavailable unless that exact component passes its own profile and live evidence.
Deliverables: A repeatable Jetson NeMo conformance lane that is useful on 8GB hardware, honest about unsupported components, and interchangeable with the same governed alternate-provider run envelope.
Outcome
After Milestone 28e:
- Cohesix is positioned as the trusted actuation, evidence, and governance layer beneath agent frameworks.
- Operator-directed and autonomous live workflows use allowlisted durable tickets, authoritative receipts, selected-policy approval, and exact 28c admission for governed effects. Model confidence, extracted assertions, and dry-run predictions remain non-authoritative.
- WorkerLora participates as an executable, MCS-scheduled, receipt-bearing Cohesix task while datasets, frameworks, training/evaluation, adapters, weights, and inference runtimes remain in named host executors outside the TCB.
- Every declared PEFT lifecycle is covered by one crash-safe export/train/evaluate/scan/import/activate/runtime-reload/canary/rollback transaction, and public AI/PEFT use-case maturity is generated from its live evidence rather than examples.
- The Verified Private LoRA Release is the concrete flagship: one operator- directed ticket joins Jetson systemd/Docker/CUDA execution, genuine PEFT callbacks and artifacts, evaluation/scan, activation/reload/canary, rollback, WorkerLora, and a portable causal evidence graph through one host-tool lifecycle.
- Long-context AI runs stop treating the prompt as the sole system of record.
- Attention strategy becomes a schedulable, measurable host-side concern instead of a hidden model-side accident.
- Delegation, retrieval admission, cache eligibility, and handoff lineage become explicit artifacts rather than implicit prompt behavior.
- Manifest-selectable NeMo capabilities can be used where they materially improve guardrails, evaluation, deployment, or retrieval workflows, without becoming a second control plane or displacing Cohesix authority.
- NeMo Run and Guardrails execution rails reuse the same provider-adapter, ticket, verification, and evidence contracts as alternate providers; Kubernetes can later substitute its accepted native controller execution shape without changing the workflow’s authority or receipt semantics.
- Milestone 28f can expose a provider-neutral, auditable inference boundary over the accepted run, capsule, ticket, and receipt semantics.
- Milestone 30b can expose stable AI namespace roots based on proven host-side semantics rather than speculation.
Milestone 35 — General Inference Gateway, Compatibility and Routing
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain broad Models/Chat Completions/Responses/Embeddings compatibility, provider-neutral streaming/receipts, context/cache policies, routing aliases, shadow promotion, telemetry and general SDK conformance. Activate for a client that native runtime endpoints cannot serve. The real application endpoint, canary and rollback required by 28b are already release work, not deferred.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 28f; current owner 35
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Status: Planned — after the 27g release; preserve existing implementation and evidence.
Delivery posture: Implement the complete pinned inference contract: Models, Chat Completions, Responses, Embeddings, streaming/cancellation, Context Capsule refs, receipts, policy aliases/routing, SDK conformance, telemetry, and host integration. Fixed-model and governed requests are both required; deployment policy selects their use and 28c admission governs consequential actions.
Why now (inference ecosystem boundary): A host-side OpenAI-compatible boundary lets existing clients use a base-URL change or thin SDK adapter for HTTP, streaming, tool-result, embedding, and error contracts. Cohesix retains admission, context/cache selection, provider-output, and receipt semantics. Providers remain external; this boundary adds neither credential authority nor a second action plane.
As-built alignment note: hive-gateway provides REST file access;
28e plans infer.run|resume|abort and manifest-selectable NeMo actions. Neither supplies a
compatible wire endpoint, stream proxy, provider compatibility matrix,
request-level receipts/effective parameters, capsule transport, or inference
OTLP. coh run, GPU/model/PEFT publication, mock Python receipts, and provider
logs are not inference-gateway proof.
Prerequisites
- Completed 28a broader providers and 28e advanced run/NeMo contract; 27d already owns the native HF serving-release transaction.
- The Milestone 27a completed for delegated caller identity, request authentication, idempotency, writer-epoch fencing, durable execution WAL, audit/replay defaults, and production secret/debug policy.
- The exact Milestone 27b completed for the selected provider/action, external executor, visibility, identity, host package, and authoritative evidence rules.
- The Milestone 28b completed for accepted snapshot/artifact refs, Context Capsules, render receipts, visibility enforcement, host tools, and selected conformance/performance evidence.
- Milestone 28c completed for governed inference, policy aliases, enforced routing, and autonomous callers, all required for full 28f qualification. Fixed-model/operator-approved requests retain their explicit policy and cannot claim a 28c decision they did not receive.
- The Milestone 28e completed for delegated AI run/task/step envelopes,
infer.run|resume|aborthost actions, checkpoint and prefix lifecycle, selected provider policy, and the reference PEFT activation/reload evidence.
Goal Provide a frictionless, provider-neutral inference interface that makes efficiency and audit evidence first-class without moving models into Cohesix:
- Accept a generated, pinned OpenAI-compatible subset for Models discovery, Chat Completions, Responses, streaming, tool-call results, and Embeddings.
- Preserve compatible SDK behavior while mapping every request to an accepted 28e run/task/step and allowlisted host-ticket action; governed requests also require an accepted 28c admission.
- Accept an optional Context Capsule reference through a generated, backwards-compatible header or metadata extension; requests without one remain transcript-input calls and cannot claim semantic selection.
- Render only admitted capsule views, record the exact rendered-request digest, and never silently expand context or rewrite client messages.
- Produce canonical inference receipts binding caller, authority, capsule, render, provider/model, effective parameters, cache decisions, stream/output digests, usage, timing, errors, and downstream verification/action refs.
- Preserve token streaming with bounded gateway overhead and explicit cancellation, partial-stream, ambiguous-completion, retry, and backpressure semantics.
- Export OpenTelemetry-compatible traces/metrics from receipt data while keeping telemetry read-only, redacted, and non-authoritative.
- Ship
coh,coh doctor, Python, package, provider-conformance, and operator tooling so the boundary is installable and diagnosable on supported host profiles. - Preserve explicit model requests as fixed-selection compatibility calls,
and stage policy-selected aliases through generated
observe,recommend, andenforcemodes with measurable promotion evidence. - Bind every governed provider call or enforced routing decision to the
accepted
admission_id, intent/policy hashes, exact provider/model or alias decision, Context Capsule or transcript-input identity, state and provider- profile generations, deadline, and requested/granted limits.
Completion boundary: Complete every listed protocol family, provider adapter, routing/cache policy, SDK matrix, OpenTelemetry projection, host tool, and acceptance task. Pinned protocol limits and unsupported provider/deployment capabilities return stable typed errors; they cannot be used to omit a listed implementation.
Non-Goals (Explicit)
- No transformer, embedding, reranking, guardrail, training, CUDA/NVML, KV cache, tokenizer, or model runtime inside the VM or Cohesix TCB.
- No in-VM inference HTTP listener,
/v1endpoint, TLS stack, model weights, prompt store, or provider credentials. - No claim that the OpenAI API is Cohesix’s canonical internal schema. It is a pinned compatibility projection over generated Cohesix records.
- No direct provider call before Cohesix admission in governed mode.
inference-gateway-hostis a declared host executor and may contact only the provider/profile authorized by the exact admitted request digest. - No generic or host-local multi-request routing grant in governed mode. Exact per-request 28c admission remains mandatory for governed calls; a later grant optimization requires the separately versioned, single-spender, bounded-accounting contract and measured justification defined by the cross-cutting Milestone 27 governance value contract.
- No forwarding of caller API keys, OAuth tokens, capability tickets, or MCP credentials to inference providers. Provider credentials resolve separately from generated secret refs.
- No arbitrary provider URL, model path, shell command, filesystem path, extension field, generation configuration, or tool executor supplied by the inference request.
- No execution of model-produced tool calls. Tool calls are untrusted outputs; any real action requires a separate typed intent, accepted 28c admission, and existing Cohesix ticket/provider path.
- No silent prompt summarization, semantic expansion, provider fallback, model substitution, output reuse, or cache sharing across identity/tenant/ ticket boundaries.
- No promise of deterministic model output from an audit receipt. A receipt can prove the admitted inputs and observed output; reproducibility additionally requires a provider/model/mode that actually guarantees it.
- No provider, inference, semantic, Worker, PEFT, or use-case promotion from wire compatibility, a successful HTTP status, or client-authored telemetry.
- No new
cohshor.cohgrammar. Target-visible inference control remains owned by Milestone 30b and uses existing verbs only.
Deliverables
1) Generated compatibility and provider contract
Purpose: Prevent client compatibility, provider adapters, Cohesix host actions, and receipts from drifting into separate inference APIs.
Implementation requirements:
- Add versioned generated schemas:
inference-client-request/v1inference-admission/v1inference-routing-decision/v1inference-provider-profile/v1inference-receipt/v1inference-stream-receipt/v1inference-cache-decision/v1.
- Each governed request and routing record binds the 28c
admission_id,intent_hash,policy_hash, exact fixed-model or alias selection, Context Capsule/render identity or transcript-input identity,state_epoch, provider-profile generation, deadline, limits, and grant expiry. - Pin the accepted OpenAI-compatible Models, Chat Completions, Responses, and Embeddings paths, fields, streaming event forms, tool-call/result shapes, usage fields, cancellation behavior, error mapping, JSON Schema dialect, and optional provider-extension allowlists in generated policy and compatibility fixtures.
- Preserve an explicit client model identifier as a fixed-selection request: it may resolve only to a conforming deployment of that model unless the request names a generated policy alias. Require each generated policy alias to resolve through a versioned policy id/hash, supported governance modes, candidate provider/model classes, data-handling and cost/resource bounds, compatibility requirements, fallback/refusal posture, endpoint secret refs, tokenizer/profile identity, context/output limits, supported modalities/features, extension allowlist, and observed conformance mode. Alias spelling is not authority and cannot select an undeclared provider.
- Provider/model profiles separately record or type unknown the runtime build/image/region, accelerator class, model revision/weight digest, quantization, adapter chain, tokenizer/chat-template identity, determinism mode, and supply-chain attestation refs. Provider-reported fields never become Cohesix-observed facts without a verified adapter signal.
- Canonical request hashing preserves ordered messages, content parts, tools, response formats, and sampling parameters. Canonicalization is for identity and evidence; forwarding must preserve accepted client semantics.
- Sensitive transcript-input identities use a generated keyed/blinded digest profile so receipt correlation does not create a low-entropy prompt hash oracle. Unkeyed content hashes are emitted only when their visibility and disclosure policy explicitly permits them.
- Unknown or unsupported fields fail or follow an explicitly generated pass-through rule. A provider-specific extension can never widen authority, choose an undeclared endpoint, or bypass receipt fields.
2) Host gateway, admission, streaming, and provider execution
Purpose: Make one base-URL change sufficient while preserving the existing host-ticket authority and executor boundary.
Implementation requirements:
- Add
inference-gateway-hostas a manifest-controlled host process with loopback-only default, bounded queues/body sizes/concurrency/deadlines, explicit non-loopback exposure policy, and compatible streaming responses. - Accept the conventional SDK base URL plus bearer/API-key-shaped gateway authentication configuration so existing clients need no request rewrite; the presented value authenticates only to Cohesix and is never reused as a provider credential.
- Implement generated routing governance modes:
observepreserves the existing explicit provider/model route and records the policy-selected candidate plus reasons, compatibility, predicted bounds, and uncertainty without provider substitution;recommendreturns or records the same non-authoritative recommendation through a bounded opt-in surface while the caller’s existing selection remains in control;enforcepermits a generated policy alias to select only a conforming provider/model candidate after an accepted machine-checked 28c decision.
observeandrecommendcannot change the route, reserve a resource, create a grant, or satisfy execution-authority evidence. Explicit fixed-model requests remain fixed-selection admissions.- An explicit model request and a policy-alias request remain distinguishable in request identity, admission, receipt, metrics, errors, and evidence.
- Authenticate the client at the gateway, normalize it through 27a delegated
identity mapping, and append or resolve the exact 28e
infer.runhost-ticket record with request id, idempotency key, writer epoch, run/task/step, capsule/render refs, provider profile, model alias, limits, and deadline. - The gateway may contact a provider only after
host-ticket-agentadmits the exact request/provider digest and returns the generated execution grant/state. The gateway is the registered streaming executor for that action; it does not decide authority or call a different provider after admission. - Provider, model, endpoint, effective parameters, tools, Context Capsule or transcript-input identity, state/provider generation, deadline, and limits cannot change after admission. Any change requires a new typed intent and decision.
- Stream forwarding is incremental and bounded. Record a digest chain and byte/ event counters without retaining full content unless an explicit encrypted content-retention profile authorizes it.
- Cancellation, client disconnect, provider disconnect, timeout, retryable refusal, partial output, and ambiguous completion reconcile through the execution WAL. No blind replay may duplicate a possibly completed inference.
- SDK middleware may record a direct-provider call as
client_observation_only, but that record is non-authoritative and cannot satisfy governed inference, provider, cache, action, or use-case evidence.
3) Context compilation and inference efficiency
Purpose: Turn semantic selection into measurable prefill and cache savings without making unverified provider behavior authoritative.
Implementation requirements:
- Compatibility requests without a capsule preserve client messages and record a transcript-input manifest. They receive no semantic-selection or omitted- repository claim.
- Capsule mode verifies snapshot, audience, TTL, policy, renderer, tool schema, model/tokenizer profile, and run/task/step before rendering.
- Record prompt bytes/tokens submitted, semantic bytes/tokens considered and avoided, selected/omitted object counts, render latency, provider queue wait, TTFT, decode rate, total latency, and usage source.
- Prefix/cache keys bind provider/model profile, capsule/render digest, instruction and tool-schema hashes, authority scope, tokenizer identity, and TTL/quota. Cache reuse across callers or tenants is prohibited unless a generated sharing policy proves equivalent authority and data classification.
- Provider-reported prefix/KV hits, cached-token counts, or effective defaults are evidence only when the adapter can capture and normalize them. Otherwise the receipt records unknown/unverified rather than inferring a hit.
- Exact-result reuse is implemented, tested, and disabled by default and requires an explicit generated policy, deterministic-compatible provider mode, exact dependency hash, audience equivalence, TTL, and a receipt that clearly marks reuse.
4) Inference receipts, evidence, and OpenTelemetry
Purpose: Reconstruct exactly what was admitted, sent, observed, and acted upon without requiring raw prompt retention.
Implementation requirements:
- Each authoritative receipt binds:
- receipt/request/run/task/step/attempt ids,
- normalized caller and delegated-ticket hash,
- admission, idempotency, writer-epoch, and policy decision refs,
- capsule and render ids or transcript-input manifest,
- provider profile, endpoint identity, model alias and returned model id,
- routing governance mode, requested fixed model or policy id/hash, considered candidate set digest, selected/recommended provider/model, selection reasons, shadow comparison refs, and fallback/refusal outcome,
- runtime/build/region/accelerator, weight revision/digest, quantization, adapter, tokenizer/template, determinism, batching/speculation, and supply-chain identities with a fact source or explicit unknown state,
- accepted and effective parameter/tool/response-format hashes,
- prefix/cache eligibility, decision, hit/miss source, and invalidation reason,
- request, stream-chain, output, and optional content-retention digests,
- token/byte usage and provenance of those counts,
- queue, admission, render, TTFT, decode, total, cancellation, and retry timing,
- terminal class (
completed,partial,failed,refused,cancelled, orambiguous), - verification, guardrail/evaluation, artifact, and later action refs,
- trace/span ids, redaction profile, evidence class, and explicit non-claims.
- Receipts reuse the accepted 27b authoritative receipt signing/verification core and bind schema version, signing key id/attestation ref, predecessor or stream-chain digest, and verification status without inventing an inference-only trust root.
- Full input/output/tool content is excluded from general logs, metrics, and evidence by default. Hashes, bounded redacted previews, or encrypted retained content require distinct policy.
- Emit OpenTelemetry-compatible GenAI spans/metrics using bounded normalized attributes plus Cohesix receipt/capsule refs. OTLP is a projection and cannot create or modify a receipt.
- Evidence packs and timelines can verify request-to-admission-to-provider-to- terminal-output lineage and distinguish gateway observation, provider claims, Cohesix authority, verification, and downstream actions.
5) Host tools, SDK compatibility, packaging, and operations
Purpose: Make the new boundary easy to install, inspect, and support without turning SDK wrappers into authority.
Implementation requirements:
- Add host-only
coh inferencecommands for:providersstatusreceipt showreceipt verifyrequest inspectconformance.
- Extend
coh doctorwith generated checks for gateway version, bind/exposure posture, client auth, identity-to-ticket mapping, semantic store/capsule availability, host-ticket agent, provider/model profile, secret refs, streaming capability, OTLP delivery, receipt verification, and package drift. - Add Python helpers for configuring the compatible base URL, supplying an optional capsule ref, reading the returned receipt id/trace context, polling status, and verifying receipts. Helpers consume generated schemas and never mint authority or authoritative provider results.
- Add a generated read-only discovery record so
hive-gateway, later MCP/A2A,coh doctor, and packaging can locate the selected inference gateway and receipt surface without duplicating provider/model catalogs. - Package
inference-gateway-host, exact provider adapters, generated compatibility fixtures, launchd/systemd definitions, signed host binaries and/or OCI/Helm artifacts for the selected profile, doctor checks, secret-ref templates, and conformance metadata for supported macOS/Linux/Kubernetes host profiles. No inference component enters VM packages. - Update
docs/HOST_API.md,docs/API_GUIDELINES.md,docs/HOST_TOOLS.md,docs/PYTHON_SUPPORT.md,docs/ARCHITECTURE.md,docs/INTERFACES.md,docs/SECURITY.md,docs/BENCHMARKS.md,docs/TEST_PLAN.md, anddocs/OPERATOR_WALKTHROUGH.md. cohshremains unchanged. Later namespace reads may display bounded receipt projections through existingLS/CAT/TAIL; no host inference command is tunneled through new console grammar.
6) Provider/client conformance, security, and performance
Purpose: Prove compatibility and bounded overhead without converting a protocol smoke test into provider-quality or production-use-case proof.
Implementation requirements:
- Ship at least one packaged open local reference profile, such as vLLM, for live compatible request, streaming, cancellation, tool-call output, usage, model identity, error, and receipt tests. Other providers remain fixture, dry-run, not-enabled, or separately live-proven according to the generated matrix.
- Test common official-compatible Python/HTTP client behavior without custom forks. Provider-specific extras require explicit generated fixtures.
- Conformance covers conventional base-URL/API-key environment configuration,
/v1/modelsdiscovery, non-streaming and streaming calls, cancellation, error shapes, usage, tool-call output, and receipt/trace response metadata. - Adoption conformance covers fixed-selection compatibility plus policy-alias
observe,recommend, andenforcemodes. Promotion evidence compares the recommendation with the unchanged actual route over a declared representative window and reports compatibility mismatches, false refusals, policy findings, latency/cost deltas, and workload-specific quality or verification outcomes without treating estimates as observed facts. - Negative tests cover oversized/malformed bodies, unknown fields, arbitrary endpoints/models, credential/token passthrough, context-scope widening, forged/stale capsules, duplicate ids, stale writer epochs, provider fallback, prompt/tool injection, cross-tenant cache keys, stream truncation, ambiguous completion, receipt tampering, telemetry content leakage, and direct provider-executor bypass.
- Add performance probes for admission, capsule verification/rendering, streaming proxy overhead, TTFT delta, sustained stream throughput, cancellation, queue/backpressure, prefix/cache evidence, receipt signing/ export, and OTLP delivery.
- Report gateway overhead separately from provider/model compute, semantic extraction, VM runtime, and network topology. A compatible response is not a quality, safety, determinism, cache-hit, or production-use-case claim.
Commands
cargo test -p cohesix-inference-corecargo test -p inference-gateway-hostcargo test -p host-ticket-agentcargo test -p coh --test inference_receiptscargo test -p coh --test inference_doctorcargo test -p coh-rtcpython3 -m pytest -q tools/cohesix-py/tests/test_inference.pyscripts/ci/inference_conformance_run.sh --matrix configs/inference_conformance.toml --state-dir out/inference/m28escripts/ci/inference_perf_probe.sh --state-dir out/bench/m28f-inferencescripts/check-generated.shscripts/ci/test_plan_run.sh --state-dir out/test-plan/m28f-inference
Checks (Definition of Done)
- Compatible clients can change only their base URL/auth configuration and complete admitted non-streaming and streaming reference requests with standards-shaped responses plus a bounded Cohesix receipt reference.
- Every governed provider call has a prior exact Cohesix admission record and execution grant; provider, model, request, capsule/render, authority, and deadline cannot change after admission.
- An operator-approved request record includes authenticated subject,
approval, fixed model/provider profile, host-ticket identity, transcript or
capsule identity, deadline, limits, and
admission_id=unavailable. A governed admission record instead includes the 28cadmission_id, intent/policy hashes, fixed-model or alias decision, state/provider-profile generations, deadline, limits, and grant expiry. Any mismatch or stale generation in the selected mode fails before provider contact. - Observe/recommend modes cannot change provider execution, mint authority, or satisfy governed-execution proof. Enforce mode is unavailable until its generated alias/policy, provider conformance, bypass posture, failure posture, and representative shadow-promotion evidence are accepted.
- Explicit model requests cannot be silently converted into policy-selected routing; policy aliases record the exact policy and considered/selected candidate identities.
- Client credentials and delegated tickets are never passed to providers; provider secrets never enter request bodies, receipts, telemetry, or client responses.
- Requests without a Context Capsule are not described as semantically selected. Capsule requests fail before provider contact when snapshot, audience, TTL, policy, renderer, tokenizer/model profile, or tool schema is stale or wrong.
- Model-produced tool calls are returned as untrusted output only and cause no host/VM action without a separate admitted Cohesix ticket.
- Receipts distinguish admitted facts, provider-reported facts, observed facts, unknown values, partial/ambiguous completion, and non-claims. A successful HTTP status alone cannot produce a terminal authoritative receipt.
- Full prompt/output/tool content is absent from default logs, OTLP, evidence, and error messages; content retention and redacted previews obey generated policy and negative tests.
- Prefix/KV/cache hits and effective provider defaults are reported only from verified adapter evidence. No cross-authority cache reuse, silent fallback, or unrecorded output reuse occurs.
coh, Python,coh doctor, gateway discovery, evidence/timeline tools, provider adapters, packages, and future MCP/A2A inputs agree on the generated inference schemas, profiles, bounds, and receipt fixtures.- Conformance passes for the packaged open reference runtime and records exact unsupported differences for every other selected provider; no provider is promoted from fixture or protocol-shape success.
- Performance evidence reports admission/render/proxy/receipt/OTLP overhead and actual prompt-token/TTFT/cache measurements separately. It does not substitute for Pi/QEMU, model-quality, safety, or production workflow evidence.
- No VM package, root-task code, console/9P grammar, model runtime, provider credential, or second provider/action registry is introduced.
Compiler touchpoints
coh-rtcextends the 27b graph with inference client, gateway, provider, model, semantic-capsule, receipt, OTLP, host-tool, package, and conformance surfaces while preserving stable integration/use-case ids.coh-rtcemits compatibility paths/fields/events, provider/model profiles, Context Capsule transport extension, request/admission/receipt schemas, client/auth/secret mappings, streaming/body/queue/deadline bounds, cache/prefix policy, content-retention/redaction policy, OTLP fields, Python defaults,cohdefaults, doctor checks, package manifests, and docs snippets.- Validation rejects unregistered endpoints/models/extensions, provider credentials in client inputs, missing 27a/27b/28b/28e prerequisites, authority-changing fallback, provider calls without exact admission, cross-scope cache reuse, client-authored authoritative receipts, content leakage, and compatibility claims without conformance evidence.
- The generated compatibility model is a projection. Canonical authority remains in the existing provider/action graph, host-ticket records, Context Capsules, run/checkpoint state, and evidence receipts.
Task Breakdown
Title/ID: m27e-inference-ir-and-compatibility-contract
Milestone: 28f / inference IR and compatibility contract
Goal: Define one generated request, provider-profile, admission, stream, cache-decision, and receipt contract plus a pinned OpenAI-compatible projection.
Inputs: accepted 27b provider/integration graph, 28b Context Capsule schemas, 28c intent/fact/decision/grant contracts, 28e run/host-ticket/provider contracts, tools/coh-rtc/src/**, docs/HOST_API.md, docs/INTERFACES.md, docs/SECURITY.md.
Changes:
- tools/coh-rtc/src/ir.rs + validation/codegen — Models/Chat
Completions/Responses/Embeddings endpoint/field/event schemas,
fixed-selection and policy-alias routing modes, versioned routing decisions,
provider/model/runtime/weight/tokenizer profiles, capsule extension,
caller/provider auth separation, 28c admission bindings, keyed digest policy, bounds,
cache/content policy, shadow-promotion evidence, receipts,
Python/coh/docs outputs.
- crates/cohesix-inference-core/src/schema.rs — strict generated or checked host-side request/admission/receipt types.
- tests/fixtures/inference/** — model discovery, valid, unsupported,
provider-extension, keyed/unkeyed identity, streaming, tool-call, partial,
ambiguous, cache, runtime/model fact-source, and tamper fixtures.
- docs/HOST_API.md + docs/INTERFACES.md + docs/SECURITY.md — compatibility, authority, provider, receipt, content, and non-claim contract.
Commands:
- cargo test -p coh-rtc
- cargo test -p cohesix-inference-core
- scripts/check-generated.sh
Checks: Client compatibility cannot redefine provider actions or receipts; unknown endpoints/models/extensions, credential passthrough, authority widening, or schema drift fail generation and fixtures.
Deliverables: Compiler-owned inference compatibility and receipt contract shared by gateway, providers, host tools, SDK helpers, OTLP, and later MCP/A2A.
Title/ID: m28f-gateway-admission-and-streaming
Milestone: 28f / host gateway admission and streaming
Goal: Serve the compatible host API with bounded streaming while every governed provider call remains bound to an exact 28c admission decision and the existing 28e host-ticket execution path.
Inputs: m27e-inference-ir-and-compatibility-contract, accepted 28c decision/grant contracts, apps/host-ticket-agent, 28e `infer.run|resume|abort` actions, accepted 27a gateway identity/fencing/WAL behavior, provider fixtures.
Changes:
- apps/inference-gateway-host/src/** — compatible Models/request/stream
handling, conventional base-URL/bearer configuration, explicit fixed-model
versus policy-alias requests, generated observe/recommend/enforce behavior,
loopback/exposure policy, bounded queues, cancellation, digest chaining,
backpressure, and response headers carrying receipt/trace refs.
- apps/host-ticket-agent/src/executors/infer.rs — exact 28c request/provider admission reference, fixed-model or enforced-alias grant validation, state/provider-generation recheck, execution WAL reconciliation, idempotency, writer fencing, cancellation, and terminal/ambiguous state.
- crates/cohesix-inference-core/src/{canonical,stream,errors}.rs — stable request identity, incremental stream digest, and deterministic client/provider/Cohesix error mapping.
- apps/inference-gateway-host/tests/** — non-streaming, streaming, cancellation, disconnect, ambiguous completion, duplicate, stale-writer, and provider-substitution fixtures.
Commands:
- cargo test -p inference-gateway-host
- cargo test -p host-ticket-agent
- cargo test -p cohesix-inference-core
Checks: Every provider request has exact current authority: fixed-model operator-approved requests retain the 27a/27b checks, while governed requests require accepted non-stale 28c admission; observe/recommend cannot change the existing route or create authority; enforce requires an accepted generated alias, machine-checked decision, and shadow-promotion evidence; explicit model requests are never silently substituted; any provider/model/endpoint/parameter/tool/context/generation/limit change requires a new intent; stream state reconciles durably; retries cannot duplicate ambiguous work; client/provider credentials and authority remain separate.
Deliverables: Drop-in compatible host inference endpoint that preserves Cohesix ticket, fencing, durability, and executor discipline.
Title/ID: m28f-context-efficiency-and-cache-evidence
Milestone: 28f / capsule compilation and cache evidence
Goal: Compile admitted Context Capsules into exact provider inputs and measure semantic/prefix/cache efficiency without unverified reuse claims.
Inputs: m28f-gateway-admission-and-streaming, accepted 28b capsule/store/renderer, 28e prefix/hotset policy, provider tokenizer/cache adapters, docs/BENCHMARKS.md.
Changes:
- crates/cohesix-inference-core/src/{context,cache,metrics}.rs — capsule verification, provider rendering, transcript-input manifests, exact cache keys, eligibility/invalidation, usage-source normalization, and bounded metrics.
- apps/inference-gateway-host/src/context.rs + provider adapters — capsule/header/metadata handling, message-preserving compatibility mode, verified provider cache/default evidence, and no silent fallback.
- scripts/ci/inference_perf_probe.sh — prompt bytes/tokens, objects selected/omitted, render cost, provider queue, TTFT, decode, cache, streaming, and receipt overhead.
- docs/BENCHMARKS.md + docs/TEST_PLAN.md — inference efficiency lanes and model-quality/cache non-claims.
Commands:
- cargo test -p cohesix-inference-core --test context_cache
- cargo test -p inference-gateway-host --test context
- scripts/ci/inference_perf_probe.sh --state-dir out/bench/m28f-inference
Checks: Transcript and capsule modes are explicit; capsule inputs cannot widen after admission; cache keys bind all authority/model/context/tool inputs; only verified provider evidence can claim hits/defaults.
Deliverables: Measured semantic paging and prefix/cache behavior at the actual inference boundary.
Title/ID: m27e-inference-receipts-otel-and-evidence
Milestone: 28f / authoritative inference receipts and telemetry
Goal: Bind each request, stream, output, provider fact, timing, and downstream verification/action reference into redaction-safe evidence and OTLP projections.
Inputs: m28f-gateway-admission-and-streaming, m28f-context-efficiency-and-cache-evidence, m27b-authoritative-receipt-and-evidence-core, apps/coh/src/{evidence.rs,evidence_timeline.rs}, OTLP exporter contract.
Changes:
- crates/cohesix-inference-core/src/receipt.rs — authoritative receipt construction/verification, stream-chain digest, fact-source classification, terminal/non-claim states, and content-retention policy.
- apps/coh/src/{evidence.rs,evidence_timeline.rs} — request-to-admission-to-provider-to-output-to-verification/action reconstruction.
- host OTLP exporter integration — bounded GenAI trace/metric projection with receipt/capsule refs and no default prompt/output content.
- apps/coh/tests/inference_receipts.rs + canonical Rust/Python fixtures — tamper, partial, ambiguous, provider-claim, redaction, and telemetry-reconstruction cases.
Commands:
- cargo test -p cohesix-inference-core --test receipts
- cargo test -p coh --test inference_receipts
- python3 -m pytest -q tools/cohesix-py/tests/test_inference.py -k receipt
Checks: Receipts distinguish Cohesix, provider, observed, unknown, and client-only facts; default telemetry/evidence contains no raw prompt/output/tool content; OTLP cannot author authority.
Deliverables: Portable, verifiable inference evidence suitable for audits, MCP/A2A artifacts, and later namespace receipts.
Title/ID: m28f-host-tools-provider-conformance-and-packaging
Milestone: 28f / host tools, conformance, packaging, and operator acceptance
Goal: Ship and prove the inference boundary through Cohesix host tools, Python helpers, doctor, provider/client matrices, supported deployment profiles, and operator evidence.
Inputs: all m28f tasks, apps/coh/src/{main.rs,doctor.rs}, tools/cohesix-py/cohesix/**, hive-gateway generated metadata, 27b package/provider registries, open reference runtime, docs/OPERATOR_WALKTHROUGH.md.
Changes:
- apps/coh/src/inference.rs + CLI wiring — provider/status/receipt/request/conformance inspection and offline receipt verification.
- apps/coh/src/doctor.rs + tools/coh-rtc generated checks — gateway/auth/identity/ticket/store/provider/model/secret/stream/OTLP/receipt/package diagnostics.
- tools/cohesix-py/cohesix/inference.py + tests/examples — compatible base URL, optional capsule ref, receipt/trace lookup, status, and verification helpers with no authority minting.
- apps/hive-gateway metadata + release packaging/service profiles —
read-only discovery of the selected inference surface and exact signed
binary/OCI/Helm, launchd/systemd, adapter, fixture, and secret-ref contents.
- scripts/ci/inference_conformance_run.sh — conventional base-URL/API-key
client plus provider/security/receipt matrix with a packaged open live
reference profile, fixed-selection and alias-routing
observe/recommend/enforce lanes, shadow-promotion evidence, and explicit
evidence modes for every alternate provider.
- docs/HOST_TOOLS.md + docs/PYTHON_SUPPORT.md + docs/API_GUIDELINES.md + docs/OPERATOR_WALKTHROUGH.md + docs/TEST_PLAN.md — installation, one-base-URL adoption, diagnostics, refusal, recovery, evidence, and non-claims.
Commands:
- cargo test -p coh --test inference_doctor
- python3 -m pytest -q tools/cohesix-py/tests/test_inference.py
- scripts/ci/inference_conformance_run.sh --matrix configs/inference_conformance.toml --state-dir out/inference/m28e
- scripts/ci/test_plan_run.sh --state-dir out/test-plan/m28f-inference
- scripts/check-generated.sh
Checks: A supported client and live open reference runtime interoperate without a client fork; fixed model requests retain their route; observe/recommend produce bounded non-authoritative comparisons; enforce remains unavailable until its promotion gate passes; doctor and packages expose exact prerequisites; alternate providers retain honest modes; `cohsh` and VM packages remain unchanged.
Deliverables: Installable, diagnosable, provider-conformant host inference boundary ready for MCP/A2A projection.
Outcome
After Milestone 28f:
- Existing inference applications can adopt Cohesix through a familiar host API while model runtimes and credentials remain outside the VM and Cohesix TCB.
- Every governed request is bound to delegated identity, an exact host-ticket action, an accepted 28c admission id, exact intent/policy/state/provider bindings, a provider/model profile, and a durable terminal or ambiguous receipt.
- Existing fixed-model clients can adopt the compatible boundary without accepting automatic routing; policy aliases progress from observe to recommend to enforce only through generated promotion evidence.
- Context Capsule selection, rendered inputs, prompt savings, prefix/cache evidence, TTFT, streaming, output digests, and downstream verification/action lineage are measurable without default raw-content retention.
coh,coh doctor, Python helpers, gateway discovery, evidence/timeline tools, OTLP, packages, and provider adapters consume one generated contract.- Milestone 28g can expose semantic resources and inference receipts/tools to MCP/A2A clients without defining a second inference protocol or authority path.
Title/ID: m28f-inference-workbench-inspector
Milestone: 28f / inference-workbench-inspector
Goal: Expose inference request/provider/cache/stream receipts and separately authorized submissions through the accepted SwarmUI workbench without UI-owned authority.
Inputs: 27f workbench; this milestone's accepted owner schemas, read/verify libraries and evidence.
Changes:
- Rust UI adapters and Spectrum inspectors — bounded immutable reads, exact source/hash/visibility and evidence links; no duplicate schema or direct provider execution.
- UI/native tests and documentation — tamper, stale/missing evidence, denied reads, unknown facts and persistent source/proof modes; no placeholder counts as implementation.
Commands: Select focused owner tests and exact host/target builds under TEST_PLAN; run scripts/check-generated.sh and scripts/ci/check_test_plan.sh before merge.
Checks: The inspector verifies the owner records through shared libraries independently of MCP/A2A; UI caches or screenshots cannot strengthen evidence.
Deliverables: Backend-owned, qualified workbench inspector.
Milestone 36 — Extended MCP/A2A Coverage and Resource Mounts
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain exhaustive administrative/operation coverage, richer discovery/prompt catalogues, additional protocol bindings, push callbacks and the read-only MCP resource/FUSE mount. Reuse the independently usable 28d/28e services and shared standing authority from 28. No second task scheduler, authority evaluator or protocol-specific budget ledger.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Selected Release B manifest controls are owned by 28
(m28-agent-protocol-controls) and exercised against real endpoints in 28d/28e.
The retained m28g-manifest-protocol-controls task below is historical design
input; at activation reuse those accepted controls and scope only remaining
extended-protocol gaps. It cannot defer or duplicate Release B safety controls.
Retained design inventory — former Milestone 28g; current owner 36
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Status: Planned — after the 27g release; preserve existing implementation and evidence.
Delivery posture: Implement and independently qualify both MCP and A2A across the selected profile’s complete admitted gateway operations and use cases, including consequential unattended execution, observation, recovery, and correct-use guidance. The read-only checkpoint cannot close the milestone. Qualify A2A with a named standard peer within this milestone, without a separate demand or delivery decision. Both protocols and the read-only MCP resource mount are required implementations. Manifest switches still disable either protocol or both globally, and A2A-only operation remains independent of MCP.
Planning scope: Future requirements only; this section neither
activates runtime work nor claims protocol support, manifest switches, standing
authority, or 28c admission exists. Host tools, tools/cohesix-py, generated
interfaces, and raw/REST benchmarks retain as-built behavior; implementation
tasks own their compatibility review and atomic updates.
Why now (ecosystem boundary):
Project the accepted 27a authority, 27b registry/visibility, 28b semantic/capsule,
28e run/PEFT/provider, 28f inference-receipt, and 28c admission contracts through
standard agent protocols. MCP exposes tools, resources, and prompts; A2A exposes
delegated tasks, progress, and artifacts. Both belong in or beside the host-only
hive-gateway multiplexer, reusing LS, CAT, TAIL, ECHO, accepted read-only
artifact libraries, and /host/tickets/spec without a second authority plane,
inference API, semantic store, evaluator, VM grammar, or opaque agent bus.
As-built alignment note: Neither protocol exists in hive-gateway.
REST/OpenAPI, bounded host providers, and /host/tickets/* are the substrate.
The accepted 28f inference endpoint stays a separate service: 28g discovers and
references it, never proxies or redefines its wire contract. coh mount --rest-url
remains the primary live-namespace FUSE path. Protocol support claims require
the relevant lifecycle, discovery, execution, authorization, and conformance
evidence.
Sequencing note: Phase 1 proves each selected protocol’s manifest controls, discovery/guidance, bounded read-only visibility, and authorization; A2A qualification is independent of MCP. Apply 27b visibility to every resource and include accepted 28b/28f artifacts where selected.
Phase 2 admits mutations only after their exact 27a/27b/28c prerequisites and applicable 28b context, 28e run/execution, and 28f inference contracts pass. Missing policy, provider, surface, executor, Worker tier, package, or artifact evidence requires omission or typed unavailable with a coverage-ledger reason. Complete selected-profile coverage and prove unattended execution and failure recovery for each enabled protocol. Enablement, discovery, prior approval, or read-only acceptance never grants broader authority.
Worker/driver live claims require matching 26e evidence; production ticket/lease binding, complete driver inventory, or structured quarantine/restart additionally require 28d. Host-ticket-only and read-only projections imply neither.
Prerequisites
- Completed 28a–28f owner contracts, including production binding only where claimed; 27b–27g remain accepted earlier foundations.
- Milestone 28c completed for every mutating tool/skill, including the generated typed-intent mapping, accepted policy, authoritative fact sources, decision receipt, state-bound grant, and stale-state refusal. Read-only protocol conformance does not require a mutating admission decision.
- Milestones 27a, 27b, 28b, 28e, and 28f completed for the exact delegated-authority, registry, artifact, run/action, and inference surfaces projected by the selected profile.
Goal Expose every admitted gateway operation and use case through standard MCP and A2A primitives under existing Cohesix authority:
- MCP resources/tools provide bounded namespace, semantic/capsule, inference, and evidence reads; mutating tools submit existing tickets/control writes. Prompts guide CUDA/GPU, PEFT, NeMo, K8s, systemd, Docker, and context/inference audits without granting authority.
- A2A Cards, skills, messages, tasks, artifacts, and streams project accepted 28b/28e/28f and host-ticket records without a new scheduler or agent memory.
- Each mutation follows
MCP tool call or A2A task -> generated typed intent -> 28c admission -> existing host-ticket or control action, retaining 27a delegated identity, idempotency, writer epoch, audit/replay, and request auth. Protocol adapters neither evaluate policy nor mint grants. - The shared coverage ledger accounts for every function, typed composition, missing prerequisite, and justified protocol limit. Generated 27b rows determine availability; protocol success cannot promote mock, dry-run, integration-pattern, or disabled workflows. Live Worker/driver claims require 26e and applicable 28d evidence.
- Native discovery and tested fallbacks teach all supported use cases, inputs/ outputs, appropriate use, authority, lifecycle, refusal, recovery, and evidence without private repository knowledge or client patches.
- Standing authorization permits unattended work within revocable limits, with current per-action admission. Humans participate only where policy or escalation requires them.
- False-default master/per-protocol manifest switches bound every launch,
transport, discovery surface, and client.
cohsh-coregrammar, NineDoor semantics, and manifest bounds remain byte-stable. coh mount --rest-urlremains the canonical namespace mount; a read-only MCP mount exposes only read-only MCP-admitted context/catalogs.
Detailed contract The archived M28g agent protocol contract is normative for manifest controls, coverage, guidance, protocol/security requirements, implementation commands, definition of done, and compiler touchpoints. BUILD_PLAN retains task records and milestone authority. The specification is preserved at that revision outside the 1.1.0-beta documentation set; restore and reconcile it when this milestone is activated.
Acceptance gates
- Manifest master and independent MCP/A2A switches default to disabled and dominate every CLI/environment override, launch mode, route, discovery surface, stream, and callback. Qualify both-disabled, MCP-only, A2A-only, and both-enabled configurations and preserve accepted work on disable.
- The full gateway inventory has no unaccounted operations. Every admitted function and supported use case has a native mapping or typed composition in each enabled protocol, with explicit readiness and visibility limits.
- Native discovery, schemas, descriptions, examples, guidance, and tested limited-client fallbacks explain appropriate use, authority, approval, lifecycle, refusal, recovery, and evidence without private repository context.
- Standing authorization supports unattended work within revocable, shared durable limits. Each effect retains exact current 28c admission, identity, fencing, and receipts; escalation cannot widen its own authority.
- Both MCP and A2A prove a consequential unattended workflow in enabled acceptance profiles, including real execution, observation, and recovery. Read-only/mock/dry-run success cannot close it. Preserve revocation, attenuation, cross-protocol budget, reconnect/restart, cancellation, and ambiguous-outcome evidence.
- Preserve every additional conformance, security, grammar, visibility, provenance, performance, and as-built documentation check in the complete definition of done. Host, QEMU, Pi, and external-provider evidence retain their distinct authority.
Task Breakdown
Title/ID: m28g-manifest-protocol-controls
Milestone: 28g / m28g-manifest-protocol-controls
Goal: Make global and independent protocol disable authoritative for every launch and discovery path.
Inputs: tools/coh-rtc, configs/root_task*.toml, generated gateway/profile consumers, apps/hive-gateway, apps/coh/src/doctor.rs.
Changes:
- tools/coh-rtc/src/ir.rs + tools/coh-rtc/src/lib.rs + codegen — schema bump, false-default master/MCP/A2A flags, effective conjunctions, manifest binding, and disabled-profile dependency rules.
- configs/root_task*.toml + generated outputs — explicit selected enablement and propagated host defaults, fixtures, and docs.
- apps/hive-gateway startup/transport lifecycle — enforce generated ceiling before credential resolution, handlers, discovery, streams, callbacks, or background work; refuse CLI/env widening.
- apps/coh/src/doctor.rs + operator docs — report effective flags, safe configuration/restart, and existing-work handling on disable.
- apps/hive-gateway/tests/agent_protocol_controls.rs + compiler tests — master dominance, missing/invalid config, all flag combinations, stdio/HTTP/mount/alternate-route attempts, no disabled work, REST independence, and disable-transition fixtures.
Commands: cargo test -p coh-rtc && cargo test -p hive-gateway --test agent_protocol_controls && scripts/check-generated.sh
Checks: Disabled protocols have no active surface or callback work; no override widens manifest policy; A2A-only works; accepted tickets retain exact underlying lifecycle and are neither silently canceled nor replayed.
Deliverables: Generated protocol controls, operational guidance, and deterministic enablement/disable evidence.
Title/ID: m28g-standing-authority-integration
Milestone: 28g / m28g-standing-authority-integration
Goal: Run complete workflows unattended inside standing authorization while retaining fresh per-action admission and shared durable limits.
Inputs: accepted 27a delegation/replay, 27b action policies, 28e run/executor state, 28c intent/decision/grant contracts, selected workflow and host-tool consumers.
Changes:
- shared authority/policy/compiler and run/executor owners — represent standing subject/run/action/target/expiry/revocation bounds, attenuation, cumulative budgets, concurrency, cooldowns, and approval/escalation modes without reusing a decision across intents.
- gateway REST/MCP/A2A admission adapters — bind authenticated identity and the same workflow accounting to exact action intents; keep policy evaluation and grant issuance in 28c.
- host-ticket-agent journal/executor integration — preserve accounting and identity across retry, resume, restart, and ambiguous outcomes; recheck current authority before dispatch.
- focused shared-owner tests + apps/hive-gateway/tests/agent_autonomy.rs — unattended authorization, required-human-policy retention, stale state, revocation, attenuation, cross-protocol budget exhaustion, administrative separation, and reconciliation.
- complete host-tool suite + tools/cohesix-py + benchmark contracts/docs — atomically update affected consumers and record unaffected surfaces; no implicit legacy-path or raw-append bypass.
Commands: cargo test -p coh-rtc && cargo test -p hive-gateway --test agent_autonomy && cargo test -p host-ticket-agent
Checks: No repeated human approval inside a valid standing policy; every effect has its own exact accepted 28c decision and receipt; escalation or missing shared enforcement refuses execution; adapters cannot mint grants or reset budgets.
Deliverables: Shared standing-authority integration, bounded failure/recovery semantics, and attributable unattended-execution evidence.
Title/ID: m28g-agent-usage-contract
Milestone: 28g / m28g-agent-usage-contract
Goal: Let ordinary agents discover every admitted Cohesix use case and use it securely and correctly from protocol guidance alone.
Inputs: complete 27b operation/use-case registry, accepted owner schemas/policies and walkthroughs, pinned protocol revisions, selected client/peer capability matrix.
Changes:
- tools/coh-rtc registry/codegen + checked guidance source — one versioned usage contract with appropriate/unsupported uses, schemas, examples/counterexamples, authority, bounds, workflow steps, lifecycle, errors, recovery, and evidence.
- apps/hive-gateway MCP catalogs/tools/prompts + A2A Cards/skills/messages/artifacts — richest useful native projection, read-only help fallback, progressive discovery, visibility/freshness, and A2A-only access.
- apps/hive-gateway/tests/agent_usage_contract.rs — source/schema/example parity, missing guidance, stale cache and identity changes, public/private disclosure, limited-client fallback, and complete-use-case coverage.
- docs/OPERATOR_WALKTHROUGH.md + docs/HOST_API.md + docs/HOST_TOOLS.md + docs/API_GUIDELINES.md + docs/TEST_PLAN.md — installed guide, ordinary-client discovery walkthroughs, pinned feature matrix and exact conformance claims.
Commands: cargo test -p coh-rtc && cargo test -p hive-gateway --test agent_usage_contract && scripts/check-generated.sh
Checks: No admitted use case lacks required usage guidance; standard MCP and A2A clients can select valid inputs, understand authority, complete a workflow, handle refusal/recovery, and inspect evidence without private repository context or client patches.
Deliverables: Generated agent-facing usage contract, validated examples, and archived native/fallback client walkthroughs.
Title/ID: m28c-mcp-policy-ir
Milestone: 28g / stable generated task identifier
Goal: Admit MCP gateway policy in compiler IR without changing Cohesix console or NineDoor grammar.
Inputs: tools/coh-rtc, configs/root_task.toml, accepted 28b semantic/capsule
schemas, accepted 28f inference receipt/action schemas, docs/HOST_API.md,
docs/SECURITY.md.
Changes:
- tools/coh-rtc/src/ir.rs — `gateway.mcp.*` schema for revision, JSON Schema
dialect, authorization mode, transports, endpoint, namespace and
host-artifact resource roots, tool allowlists, prompt ids, owner-schema
refs, bounds, and prerequisite gates.
- tools/coh-rtc/src/lib.rs — reject mutating MCP tools without delegated identity, audit/replay, and provider action prerequisites, and reject non-loopback production profiles whose authorization mode does not satisfy the pinned revision.
- tools/coh-rtc/src/codegen/* — generated gateway MCP defaults and docs snippets.
Commands: cargo test -p coh-rtc && scripts/check-generated.sh
Checks: MCP revision/schema/auth policy is compiler-owned, profile-gated, conformance claims match the selected mode, and `cohsh-core` grammar specs remain untouched.
Deliverables: Generated MCP gateway policy and validation gates.
Title/ID: m28c-a2a-policy-ir
Milestone: 28g / stable generated task identifier
Goal: Admit A2A gateway policy in compiler IR without changing Cohesix console or NineDoor grammar.
Inputs: tools/coh-rtc, configs/root_task.toml, accepted 28b
semantic/capsule schemas, accepted 28e/28f run/inference schemas,
docs/HOST_API.md, docs/SECURITY.md, docs/TEST_PLAN.md.
Changes:
- tools/coh-rtc/src/ir.rs — `gateway.a2a.*` schema for endpoint/binding, accepted revision, binding-specific operation mappings, Agent Card path, skill ids, task/artifact/stream/push bounds, callback allowlists, and prerequisite gates.
- tools/coh-rtc/src/lib.rs — reject mixed-revision or mixed-binding
operation names and reject mutating skills without their generated 28c
intent/policy/fact/grant mapping, required 27a delegated authority and
27b action registry; require 28e durable state for tasks, and 28b/28f
context/inference contracts where used, plus the applicable audit/replay,
evidence and provider prerequisites. A2A must work with MCP disabled.
- tools/coh-rtc/src/codegen/* — generated A2A gateway defaults, Agent Card metadata, and docs snippets.
Commands: cargo test -p coh-rtc && scripts/check-generated.sh
Checks: A2A revision/binding mappings are compiler-owned and internally consistent, profile gates hold, and `cohsh-core` grammar specs and NineDoor semantics remain untouched.
Deliverables: Generated A2A gateway policy, Agent Card metadata, and validation gates.
Title/ID: m28g-provider-action-registry-projection
Milestone: 28g / m28g-provider-action-registry-projection
Goal: Consume the Milestone 27b provider/integration and use-case graph plus
28b/28f owner schemas so MCP tools and A2A skills cannot define independent
schemas or availability claims.
Inputs: tools/coh-rtc, apps/hive-gateway, apps/host-ticket-agent,
crates/host-cuda, accepted 28b semantic/capsule outputs, accepted 28f
inference outputs, configs/generated/host_integration_dependency.json,
configs/generated/use_case_evidence.json, docs/INTERFACES.md, docs/HOST_API.md.
Changes:
- tools/coh-rtc/src/lib.rs — reject MCP/A2A projections that reference
undeclared 27b actions/surfaces, duplicate 28b/28f owner schemas, or
drift from target, semantic/capsule/inference receipt, read-visibility,
Worker, executor, package, use-case, or observed-mode records.
- apps/hive-gateway/src/actions/registry.rs — complete generated 27b gateway-operation/use-case view consumed by MCP tools/resources, A2A skills, evidence, availability, usage guidance, and security checks; include control/administrative/recovery and metadata functions as well as providers.
- generated coverage ledger — map every inventory row to native operations or typed compositions, with explicit blocked/future status and justified protocol limitations; missing adapters cannot shrink the inventory.
- apps/hive-gateway/tests/gateway_action_registry.rs — parity fixtures proving MCP and A2A expose the same allowed actions, bounds, dependency availability, receipt refs, and refusal semantics where the same provider operation exists.
Commands: cargo test -p coh-rtc && cargo test -p hive-gateway --test gateway_action_registry && scripts/check-generated.sh
Checks: Provider/integration metadata is generated once by 27b, owner schemas
remain owned by 28b/28f, projections stay protocol-neutral, missing
dependencies are omitted or typed unavailable, and drift between MCP tools,
A2A skills, host-ticket lines, context/receipt refs, read visibility, use-case
maturity, and evidence receipts is rejected. Every admitted operation has a
mapping in each enabled protocol; exclusions cannot conceal supported functions.
Deliverables: Gateway protocol projection and parity tests for
semantic/context, inference, CUDA/GPU, PEFT, NeMo, K8s, systemd, Docker,
federation, FUSE/read surfaces, and evidence operations without a second
registry.
Title/ID: m28g-gateway-mcp-transport
Goal: Implement MCP lifecycle and stdio/Streamable HTTP transport in `hive-gateway`.
Inputs: apps/hive-gateway/src/main.rs, gateway auth/broker code, docs/HOST_API.md.
Changes:
- apps/hive-gateway/src/mcp/protocol.rs — MCP JSON-RPC lifecycle, capability negotiation, pagination, and error mapping.
- apps/hive-gateway/src/mcp/transport.rs — stdio and Streamable HTTP endpoint handling with stdout/stderr separation and Origin validation.
- apps/hive-gateway/src/main.rs — CLI/env transport and endpoint selection bounded by the generated master/per-protocol enablement ceiling.
Commands: cargo test -p hive-gateway --test mcp_protocol
Checks: Standard lifecycle and discovery requests work over both transports; invalid JSON-RPC, bad Origin, missing auth, and oversize messages fail deterministically.
Deliverables: MCP-capable gateway process with safe defaults.
Title/ID: m28g-mcp-resource-catalog
Goal: Expose Cohesix namespace state and accepted semantic/capsule/inference
artifacts as MCP resources backed only by bounded read-only projections.
Inputs: apps/hive-gateway, apps/coh/src/evidence.rs,
crates/cohesix-semantic-core, crates/cohesix-inference-core, generated path and
visibility defaults, accepted 28b/28f fixtures.
Changes:
- apps/hive-gateway/src/mcp/resources.rs — typed `cohesix://namespace`,
`cohesix://semantic`, `cohesix://context`, and
`cohesix://inference/receipt` and `cohesix://guide` catalogs, templates, id/path validation,
namespace dispatch through existing `LS`/`CAT`/`TAIL`, and host-artifact
dispatch through accepted read-only owner libraries.
- apps/hive-gateway/tests/mcp_resources.rs — resource list/read fixtures for
`/proc`, `/gpu`, `/host`, semantic objects, capsules, inference receipts,
visibility refusal, tamper refusal, and evidence summaries.
Commands: cargo test -p hive-gateway --test mcp_resources
Checks: Resource reads enforce manifest bounds, reject undeclared paths or ids,
redact secrets/content, match REST/console output for namespace fixtures, and
verify exact 28b/28f hashes/schemas for host artifacts without claiming a VM
path.
Deliverables: MCP resource catalog that faithfully projects Cohesix namespace
state and accepted immutable host artifacts.
Title/ID: m28g-mcp-prompts
Goal: Project the shared usage contract as MCP prompts for governed operator and unattended workflows.
Inputs: apps/hive-gateway/src/mcp, docs/HOST_TOOLS.md, docs/SECURITY.md.
Changes:
- apps/hive-gateway/src/mcp/prompts.rs — prompt templates for semantic impact
review, inference receipt audit, CUDA triage, PEFT promotion, NeMo
readiness, K8s drain, systemd recovery, and Docker remediation.
- docs/HOST_TOOLS.md — operator guidance for MCP prompt use, approval expectations, and non-authority status.
Commands: cargo test -p hive-gateway --test mcp_prompts
Checks: Prompts contain no secrets, name exact actions and expected receipts, honor standing authorization, and request approval only when the underlying policy requires it or additional authority is needed; descriptions/help tools retain essential guidance when prompts are unavailable.
Deliverables: MCP prompt catalog that improves operator ergonomics without becoming control state.
Title/ID: m28g-readonly-mcp-acceptance-gate
Goal: Prove the intermediate read-only MCP transport, resources, prompts, and conformance checkpoint before mutating MCP acceptance; it cannot close the unattended-workflow gate.
Inputs: apps/hive-gateway, generated MCP policy, docs/HOST_API.md, docs/TEST_PLAN.md.
Changes:
- apps/hive-gateway/tests/mcp_readonly_acceptance.rs — lifecycle, namespace
and host-artifact resources, templates, prompts, visibility, hash/schema
verification, redaction, auth, Origin, and oversize negative fixtures with
mutating tools disabled.
- docs/TEST_PLAN.md — record read-only MCP acceptance as the intermediate MCP evidence gate.
Commands: cargo test -p hive-gateway --test mcp_readonly_acceptance && scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m28g-qemu-mcp-readonly
Checks: Standard MCP clients can discover and read admitted context, but mutating tools are unavailable or deterministically refused until provider action registry and delegated-authority gates pass.
Deliverables: Archived read-only MCP evidence for mutating MCP acceptance; A2A supplies its own discovery/visibility/auth evidence independently.
Title/ID: m28g-mcp-tool-catalog
Goal: Expose real Cohesix operations as MCP tools without direct host execution.
Inputs: apps/hive-gateway, apps/host-ticket-agent, apps/coh,
crates/cohesix-semantic-core, crates/cohesix-inference-core, crates/host-cuda,
accepted 28b/28e/28f schemas, docs/INTERFACES.md.
Changes:
- apps/hive-gateway/src/mcp/tools.rs — schema-defined tools for file reads,
semantic/capsule inspect/query/render/verify, inference
submit/status/receipt, CUDA/GPU inventory, host-ticket submission, GPU
leases, PEFT, NeMo, K8s, systemd, Docker, and evidence summaries, plus every
other admitted gateway operation in the coverage ledger; each
mutating call is first converted into its generated 28c typed intent.
- apps/hive-gateway/src/mcp/tickets.rs — 28c admission-reference validator and host-ticket builder with id/idempotency/writer-epoch validation, provider action mapping, and generated v1/v2 selection from the required receipt mode; it contains no policy evaluator and cannot mint a grant.
- apps/hive-gateway/tests/mcp_tools.rs — success and refusal fixtures for read-only, delegated mutating, duplicate, and unauthorized calls.
Commands: cargo test -p hive-gateway --test mcp_tools && cargo test -p host-ticket-agent
Checks: Mutating tools require an accepted non-stale 28c decision, then append only validated Cohesix ticket/control lines and
cannot downgrade a receipt-bearing v2 action to v1 or synthesize Worker binding
fields;
inference submission uses 28c admission, the 28e host-ticket action, and 28f receipts; provider executors
and model-produced tool calls are never invoked directly by the MCP server;
read-only MCP acceptance and provider action registry parity evidence already
exists; missing admission policy makes the mutating tool typed unavailable.
Deliverables: Tool catalog covering semantic/context, inference, CUDA/GPU,
PEFT, NeMo, K8s, systemd, and Docker under existing Cohesix authority.
Title/ID: m28g-a2a-agent-facade
Goal: Implement A2A Agent Card discovery and task/message/artifact projection
over existing Cohesix semantic/capsule, run, inference receipt, and ticket
state.
Inputs: apps/hive-gateway, apps/host-ticket-agent,
apps/coh/src/evidence.rs, accepted 28b/28e/28f owner schemas, generated
provider action registry, docs/HOST_API.md, docs/API_GUIDELINES.md, accepted A2A
protocol revision.
Changes:
- apps/hive-gateway/src/a2a/agent_card.rs — manifest-gated generated Card with complete admitted skills/use cases, descriptions/examples/media/security/docs metadata, native capability claims, and public/authenticated visibility separation.
- apps/hive-gateway/src/a2a/tasks.rs — generated `SendMessage`, streaming,
task query/list/cancel/subscribe, push-notification, status, idempotency,
and refusal mappings for the pinned A2A binding/revision, backed by 28b
immutable context refs, 28e run/checkpoint/evidence records, and 28f
inference receipts.
- apps/hive-gateway/src/a2a/artifacts.rs — bounded redacted artifact
references for semantic objects, Context Capsules, inference receipts,
evidence packs, timelines, checkpoints, provider receipts, and Cohesix
resource refs.
- apps/hive-gateway/src/a2a/push.rs — disabled-by-default push notification config with allowlist, SSRF validation, per-task auth material, bounded retry, and audit evidence.
- apps/hive-gateway/tests/a2a_protocol.rs + apps/hive-gateway/tests/a2a_tasks.rs — Agent Card, message, stream, task, artifact, cancel, push-refusal, duplicate, and unauthorized fixtures.
Commands: cargo test -p hive-gateway --test a2a_protocol && cargo test -p hive-gateway --test a2a_tasks
Checks: A2A clients can discover complete admitted use cases and correct-use
guidance, submit dry-run or standing-authorized tasks, observe
semantic/capsule/inference refs and status/artifacts, and receive deterministic
refusals; no A2A path bypasses Cohesix tickets, 28c admission, applicable
28b/28e/28f context/run/receipt contracts, gateway auth, or provider allowlists; provider action
registry parity and A2A read-only discovery/visibility/auth acceptance evidence
already exists; MCP enablement or conformance is not an A2A prerequisite.
Deliverables: A2A-compatible gateway facade for bounded Cohesix delegation and observation.
Title/ID: m28g-coh-mount-mcp-resource-view
Goal: Add a read-only `coh mount --mcp-url` mode for MCP-admitted resources, schemas, prompts, and evidence links without replacing the existing REST-backed Cohesix namespace mount.
Inputs: apps/coh/src/mount.rs, apps/coh/src/doctor.rs,
apps/hive-gateway/src/mcp/resources.rs,
apps/hive-gateway/src/mcp/tools.rs, crates/cohesix-semantic-core,
crates/cohesix-inference-core, docs/HOST_TOOLS.md,
docs/API_GUIDELINES.md.
Changes:
- apps/coh/src/mount.rs — read-only MCP resource/catalog FUSE adapter with bounded readdir/read, no write-to-tool translation, no symlink/rename/chmod support, and explicit stale-cache markers.
- apps/coh/src/main.rs — `coh mount --mcp-url <endpoint> --read-only --at <path>` flags that are mutually exclusive with write-capable REST/console mount modes.
- apps/coh/src/doctor.rs — report REST mount availability separately from MCP
resource-mount protocol/FUSE availability and report namespace,
semantic/capsule, and inference-receipt resource readiness independently.
- apps/coh/tests/mount_mcp.rs — fixtures for resource reads, tool schema files, prompt template files, cache invalidation, write denial, and parity with MCP `resources/read`.
- docs/HOST_TOOLS.md + docs/API_GUIDELINES.md — document when to use REST mount versus MCP resource mount and why MCP mount is read-only by default.
Commands: cargo test -p coh --test mount_mcp && cargo test -p hive-gateway --test mcp_resources
Checks: Existing `coh mount --rest-url` behavior is unchanged; MCP mount reads
only MCP-admitted context, refuses all filesystem mutations by default, never
calls MCP tools from FUSE operations, and traces every mounted file back to a
Cohesix path/action, verified 28b/28f artifact, or generated 27b/28g usage contract.
Deliverables: Agent- and filesystem-friendly MCP context mount that adds discovery/schema/prompt value without adding a new Cohesix write path.
Title/ID: m28g-operator-docs-as-built-audit
Goal: Audit and update the Operator Walkthrough plus related canonical docs so gateway, MCP, A2A, mount, provider, and evidence guidance matches the as-built implementation.
Inputs: docs/OPERATOR_WALKTHROUGH.md, docs/HOST_API.md, docs/HOST_TOOLS.md, docs/API_GUIDELINES.md, docs/USERLAND_AND_CLI.md, docs/INTERFACES.md, docs/ARCHITECTURE.md, docs/SECURITY.md, docs/TEST_PLAN.md, resources/openapi/hive-gateway.yaml, apps/hive-gateway/src/**, apps/coh/src/mount.rs, apps/coh/src/doctor.rs, apps/host-ticket-agent/src/executors/**, docs/snippets/**.
Changes:
- docs/OPERATOR_WALKTHROUGH.md — operator sequence for direct TCP,
REST/gateway, the separate OpenAI-compatible inference endpoint,
`coh mount --rest-url`, semantic/capsule/inference MCP
resources/tools/prompts, A2A Agent Card/task flow, read-only MCP
resource mount, evidence capture, and deterministic failure handling.
- docs/HOST_API.md + docs/API_GUIDELINES.md — MCP and A2A endpoint/auth/error semantics and transport-choice guidance aligned with the REST gateway contract.
- generated usage contract + operator walkthroughs — master/per-protocol configuration, complete operation/use-case coverage, standing-authorization setup, secure credential provisioning, native discovery/help, approval/escalation, recovery and evidence instructions; preserve supported client capability fallbacks.
- docs/HOST_TOOLS.md + docs/USERLAND_AND_CLI.md — command references and prerequisites for `hive-gateway`, `coh mount`, MCP resource mount, A2A task facade, host-ticket-agent, GPU bridge, sidecar bridge, and grammar-stability constraints.
- docs/INTERFACES.md + docs/ARCHITECTURE.md + docs/SECURITY.md + docs/TEST_PLAN.md — as-built path/action/task/artifact mappings, VM/host boundary, delegated ticket/security posture, and evidence matrix.
- resources/openapi/hive-gateway.yaml — keep REST/OpenAPI routes aligned with any gateway endpoint additions and document that MCP/A2A are adjacent protocol surfaces, not REST authority replacements.
Commands: git diff --check -- docs/OPERATOR_WALKTHROUGH.md docs/HOST_API.md docs/HOST_TOOLS.md docs/API_GUIDELINES.md docs/USERLAND_AND_CLI.md docs/INTERFACES.md docs/ARCHITECTURE.md docs/SECURITY.md docs/TEST_PLAN.md && scripts/check-generated.sh
Checks: Documentation distinguishes direct TCP proof, REST gateway proof, 28f
inference proof, gateway-backed FUSE mount, read-only MCP resource
mount, namespace versus host-artifact resources, MCP ticket-submission tools,
and A2A task/artifact/status behavior; no doc claims MCP, A2A, semantic,
inference, mount, provider, or host-ticket behavior that lacks
code/tests/generated evidence.
Deliverables: Operator-facing documentation that is coherent with as-built 28g behavior and usable for live, mock, and dry-run workflows.
Title/ID: m28g-gateway-protocol-performance
Goal: Prove MCP/A2A gateway protocol projections remain bounded relative to the 27a gateway authority baseline.
Inputs: apps/hive-gateway, scripts/ci/gateway_perf_probe.sh, docs/BENCHMARKS.md, docs/TEST_PLAN.md, accepted 27a gateway authority artifacts.
Changes:
- scripts/ci/gateway_perf_probe.sh — add namespace, semantic/capsule, and
inference-receipt MCP resource reads, MCP ticket-submitting tool call, A2A
task create/status stream, artifact read, complete-catalog discovery/help,
standing-authority accounting, and backpressure/refusal scenarios.
- docs/BENCHMARKS.md + docs/TEST_PLAN.md — record protocol-projection performance as gateway evidence, separate from Pi/QEMU runtime throughput proof.
Commands:
- scripts/ci/gateway_perf_probe.sh --scenario mcp-a2a-protocols --state-dir out/bench/m28g-gateway-protocols
Checks:
- MCP/A2A protocol paths stay bounded relative to the 27a gateway authority
baseline, with 28b/28f host-artifact adapter cost separated from protocol
cost and queue depth, refusal counts, auth checks, and evidence/audit
emission cost recorded.
- A full REST/Pi/QEMU benchmark is triggered only if gateway protocol evidence shows an upstream runtime-path regression.
Deliverables:
- Gateway protocol performance ledger for MCP/A2A clients and downstream AI namespace work.
Title/ID: m28g-gateway-agent-security-conformance
Goal: Prove MCP/A2A ecosystem compatibility and preserve Cohesix security boundaries.
Inputs: apps/hive-gateway, docs/SECURITY.md, docs/TEST_PLAN.md, accepted MCP protocol revision, accepted A2A protocol revision.
Changes:
- apps/hive-gateway/tests/mcp_security.rs — confused-deputy,
prompt-injection, semantic/capsule/inference visibility and tamper, returned
tool-call inertness, auth, Origin, backpressure, duplicate, and redaction
negative tests.
- apps/hive-gateway/tests/a2a_security.rs — Agent Card disclosure, message
injection, semantic/capsule/inference ref substitution, returned tool-call
inertness, task idempotency, artifact redaction, push callback,
cancellation, auth, Origin, and backpressure negative tests.
- docs/TEST_PLAN.md — MCP/A2A conformance and security evidence stage.
- docs/HOST_API.md + docs/API_GUIDELINES.md — MCP/A2A endpoint, transport, auth, error, and client configuration guidance.
Commands: cargo test -p hive-gateway --test mcp_security && cargo test -p hive-gateway --test a2a_security && scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m28g-qemu-gateway-agents
Checks: Standard MCP clients and A2A peers can discover and call allowed
read-only, dry-run, and standing-authorized flows; unauthorized, prompt-injected,
tampered-artifact,
provider-direct, model-returned, forged callback, duplicate, or overbroad calls
cannot bypass delegated tickets, exact 28c action admission, the existing
host-ticket/control path, or Cohesix policy.
Deliverables: Archived MCP/A2A conformance and security evidence.
Title/ID: m28g-unattended-workflow-acceptance
Milestone: 28g / m28g-unattended-workflow-acceptance
Goal: Prove both MCP and A2A complete a consequential workflow in enabled acceptance profiles using published guidance and bounded standing authority.
Inputs: accepted controls/coverage/usage/autonomy tasks, exact 27a/27b/28c action evidence, named standard client or peer, selected target/provider profile and authoritative facts/receipts.
Changes:
- docs/TEST_PLAN.md + canonical catalog/evidence integration — intermediate read-only gates, enabled-protocol coverage and guidance gates, and unattended workflow acceptance with exact source/manifest/protocol/client/provider identity.
- apps/hive-gateway/tests/agent_autonomy.rs + shared-owner fixtures — deterministic injected failure/reconnect/restart, stale state, expiration/revocation, denied escalation, attenuated delegation, cross-protocol cumulative limits, cancellation, and ambiguous-outcome reconciliation.
- docs/OPERATOR_WALKTHROUGH.md + accepted use-case evidence rows — at least one real consequential workflow per enabled protocol, such as bounded service remediation or GPU/PEFT lifecycle, from native discovery through preflight/admission/execute/observe/recovery to authoritative outcome receipt with no per-action human prompt inside policy.
- evidence/timeline consumers + complete host-tool, tools/cohesix-py, and benchmark compatibility review — preserve original subject/run/intent/decision/grant/action/outcome correlation and record changed or unaffected surfaces.
Commands: cargo test -p hive-gateway --test agent_usage_contract && cargo test -p hive-gateway --test agent_autonomy && scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m28g-qemu-gateway-agents
Checks: Archive ordinary-client live workflow transcripts and independently verified provider outcome evidence separately from deterministic host fixtures and target qualification. Injected target/provider behavior uses its owning Test Plan layer. Read-only/mock/dry-run or an ACK without confirmed execution cannot close the gate. Disabled protocols are recorded disabled, never conformant by inference.
Deliverables: Exact-profile coverage report, native/fallback guidance evidence, accepted unattended workflow and failure/recovery records, and reproducible evidence-pack/replay instructions.
Outcome Qualified protocols expose the selected profile’s complete admitted gateway functions, use cases, and evidence through standard clients under delegated authority. Native guidance and tested fallbacks support correct input selection, refusal, lifecycle, and recovery; registry checks establish coverage.
Standing-authorized workflows execute and recover unattended with fresh 28c decisions, shared durable budgets, revocation, and attributable receipts. Administrative actions require separate authority; human involvement follows policy or escalation. All effects retain existing ticket/control, audit, and evidence paths; inference retains the separate 28f boundary.
Manifest-disabled protocols expose nothing. MCP-only and A2A-only deployments are independently usable and qualified. VM grammar, Secure9P semantics, and generated manifest authority remain unchanged.
Milestone 37 — VM-Local Persistence and Reboot Recovery
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain bounded spool/settings semantics, QEMU block evidence, isolated Pi EMMC2 storage, safe media layout, power-loss/reboot recovery, and CYW43/shared-IRQ coexistence. Activate for a deployment that needs durable disconnected/reboot operation. Host checkpoints and safe reconciliation after Queen loss do not establish VM persistence.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 29; current owner 37
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Status: Planned as one complete QEMU and Pi persistence milestone.
Implement both target backends, bounded spool/settings semantics, containment,
recovery, and acceptance. No user-demand or host-storage-insufficiency decision
is required. Pi work consumes the exact SMP+MCS topology, current-image CYW43
coexistence record, and same-harness performance/repeatability baseline from
m26e-mcs-smp-target-acceptance.
Why now (resilience): Edge deployments need bounded store/forward and settings across reboots/outages without a general filesystem or Pi Wi-Fi regression.
Completion boundary: Completion requires independent QEMU and Pi EMMC2/raw-region, CYW43 coexistence, containment, reboot, and media evidence. A deployment may disable persistence, but that does not close this milestone. Models, datasets, checkpoints, semantic objects, inference caches, and PEFT artifacts remain host-side on configurable NVMe paths.
Current as-built and platform truth: Cohesix has host-side sidecar buffering,
telemetry snapshots, and U-Boot-owned cohesix.env, but no VM-local persistent
spool/settings store, persistence manifest IR, storage runtime, block backend,
or persistent NineDoor providers. The selected Pi manifest currently declares
seven physical runtimes and gives the CYW43-linked sdio-host runtime the
SDHCI controller at 0xfe300000, the Wi-Fi power/DMA resources, GIC IRQ 158,
and DMA IRQ 116. The boot microSD card is a different device on BCM2711 EMMC2
at 0xfe340000. The pinned Pi DTB and captured Linux topology also show that
mmc0 EMMC2 and mmc1 CYW43 SDIO multiplex the same physical GIC IRQ 158.
Existing coh-rtc validation rejects duplicate physical IRQ owners.
The canonical QEMU launcher currently attaches virtio networking but no block
device. Both the pinned QEMU 10.1.0 lane and the current host diagnostic QEMU
advertise sdhci-pci plus sd-card, but that is a PCI SDHCI model, not BCM2711
EMMC2. It does not represent Pi pin/card wiring, the shared IRQ-158 topology,
the Pi DMA/cache path, or CYW43 coexistence.
Objective and closure boundary
The Pi acceptance record is complete only when the same bounded persistence semantics:
- work deterministically on QEMU through
virtio-blk; - work on the Pi 4 boot microSD through the EMMC2 controller and a manifest-bounded raw region;
- coexist on real Pi hardware with the accepted CYW43/SDIO path without a semantic regression;
- introduce no material CYW43 performance regression outside the accepted same-harness repeatability envelope; and
- preserve compiler/HAL-enforced storage/CYW43 authority, containment, and restart separation.
The target implementations need not be superficially symmetric. Root owns
the bounded spool/settings semantics. QEMU may use the smallest direct virtual
block HAL path. Pi physical I/O must use a separate isolated driver-storage
runtime and the accepted 26e driver-supervisor contract.
Non-negotiable scope and authority
- No POSIX VFS, general filesystem, C-FFI filesystem, generic storage framework, generic SDIO framework, scheduler redesign, or new testing framework.
- Persistence is distinct from the in-memory host-side
sidecars.*.adapters[].spooland/bus/<adapter>/spoolcontract. /procremains read-only. Mutating spool/settings operations use documented role-scoped NineDoor control roots; M29 does not change console framing, Secure9P bounds, or TCP grammar.- QEMU uses a deterministic per-run raw image behind
virtio-blk. QEMU proves the virtual block contract and persistence integration only; it proves no Pi EMMC2, physical-media, DMA/cache, shared-IRQ, or Wi-Fi behavior. - Pi persistence uses only a manifest-declared raw partition/range outside the
FAT boot assets and
cohesix.env. Routine reflashing continues to replace only the exact existing FAT child. Creating or changing the two-partition boot-plus-raw topology remains an explicit--initialize-diskoperation after whole-device size and identity checks; it is never an automatic fallback. - The Pi storage runtime owns only EMMC2 MMIO at
0xfe340000, its private block queue/buffers, generated endpoint/notification/SC/Reply/fault caps, and any later explicitly admitted storage-only DMA frames. It receives no CYW43/SDIO bus link, Wi-Fi shared aperture, Wi-Fi power-sequence page, BCM2835 SDIO DMA channel/page, IRQ 116, or IRQ 158 capability. - Existing generated uniqueness, range, badge, CSpace, temporal-admission, descriptor-seal, and containment checks must prove the storage endpoint, notifications, queues/buffers, mappings, SC/Reply, fault records, restart generation, and any DMA frames are disjoint from CYW43/SDIO. Storage may use the common driver-supervisor mechanism, but a storage fault or recovery can revoke/restart only its own generation and EMMC2 controller; it cannot quarantine, reset, wake, or otherwise act on the CYW43/SDIO pair.
- Because EMMC2 and CYW43 SDIO share physical IRQ 158, initial Pi storage uses bounded PIO/status-driven service turns with EMMC2 interrupt signalling disabled. Each turn has a generated operation bound and virtual-counter deadline; no background poller or unbounded wait is allowed. Retain this simpler path if it satisfies M29. Add controller-local DMA only if early Pi evidence shows it is necessary, and then only with disjoint generated buffers and the existing bounded-no-IOMMU truth. If reliable storage would require sharing IRQ 158, changing its accepted owner, or touching the CYW43/SDIO runtime, M29 stops for an explicit authority redesign and full CYW43 requalification.
- Storage uses the accepted 26e constructor, MCS admission, driver supervisor, generation, containment, teardown, and fresh readmission mechanisms. Its CPU, service priority, core, budget/period, operation size, and recovery work are derived from the smallest admitted bounds that pass the early target canaries; this plan does not preselect a core or invent a new scheduler.
- Every issue, completion, flush, scan, retry, recovery, and fault path is
bounded. Storage pressure or recovery cannot monopolize root-control,
driver-storage, the driver supervisor, or the CYW43/SDIO hot path.
Protected CYW43/SDIO baseline
The exact accepted pre-M29 CYW43/SDIO implementation and evidence contract are frozen inputs. Ordinary M29 work must not refactor, generalize, deduplicate, clean up, or otherwise modify:
- CYW43 or SDIO runtime code and images;
- the CYW43-SDIO ABI, shared aperture, notifications, CARD_INT/DPC path, IRQ ownership, or completion rings;
- Wi-Fi scheduling, deadlines, retry ceilings, restart/recovery order, error classification, or operator proof semantics; or
- the accepted Wi-Fi harness, counters, and repeatability classification, except for the smallest evidence consumer needed to correlate an unchanged counter with an M29 run.
Generated source/configuration review must show whether these surfaces are
byte-identical. Adding driver-storage may change the aggregate driver-archive
hash, but the embedded CYW43 and SDIO component bytes and hashes must remain
identical to the frozen inputs. A demonstrated need to touch one moves the
change out of the ordinary storage lane and requires an explicit task revision,
causal Pi evidence, and complete CYW43 requalification. Storage adapts to the
accepted Wi-Fi boundary.
QEMU SDHCI decision
sdhci-pci plus sd-card is not a mandatory M29 lane. In the current
architecture it would require a new QEMU PCI storage attachment/admission path
and exercise a different controller integration while leaving the decisive Pi
EMMC2/shared-IRQ/CYW43 risks untouched. That work is not justified merely to
claim SD parity.
A bounded non-acceptance experiment may be run after the virtio raw-block
canary. Promote it to a supplemental QEMU acceptance lane only if the Pi work
has already produced a controller-independent SD/MMC command/block core and
the remaining QEMU adapter is a thin, low-risk reuse with no new generic PCI
or storage framework. Otherwise record the experiment or rationale and stop.
A macOS /dev/rdiskN backend is likewise optional manual diagnostics only,
after exact removable-media verification and unmount; it is never CI,
canonical QEMU, or acceptance evidence and its absence cannot block M29.
Persistent semantics
- Telemetry spool: fixed-size append-only ring; versioned bounded records
magic | version | kind | seq | ts | len | crc | payload; incomplete or invalid tails are ignored; deterministic scan budget; explicit refuse-when- full or overwrite-only-acked policy. - Settings: two fixed A/B pages with generation and checksum; write and validate the inactive page before its generation becomes current; strict byte/UTF-8/key/value bounds.
- Identity: store metadata binds to the selected manifest fingerprint without adding a trust root.
- Namespace:
/proc/spool/{status,read}is read-only;/queen/spool/{append,ack}is Queen-controlled; settings use the smallest role-scoped control/read surface agreed inARCHITECTURE.mdandINTERFACES.md. Worker telemetry continues through its existing path. - Policy separation: settings cannot contain or override U-Boot-owned
network mode/interface/static-IP/Wi-Fi credentials in
cohesix.env, or manifest-authored boot policy mirrored through/chosen/cohesix,*.
Target-first evidence ladder
- Freeze the exact accepted pre-M29 CYW43 artifact/evidence baseline and add only cheap deterministic tests for persistence encoding, bounds, A/B commit selection, block ABI/layout, and manifest rejection.
- Boot the smallest raw read/write/flush/reopen canary on QEMU
virtio-blk; do not build the spool/settings stack first. - Add the smallest EMMC2 PIO/no-signal
driver-storagepath and prove one raw-region write/flush/reboot/read on Pi 4 as soon as it is buildable. - On that same early Pi candidate, prove existing CYW43 association, DHCP, raw TCP, bounded storage activity, no shared-IRQ assertion, and no Wi-Fi or SDIO reset/restart before adding higher persistence semantics.
- Add spool semantics, repeat the cheap QEMU and Pi roundtrip/coexistence gates, then add settings semantics and repeat them. Add a regression after a target defect only when the cause is an independently testable deterministic contract.
- After the feature set converges, run the complete exact-artifact QEMU and Pi acceptance, storage fault/recovery, Wi-Fi repeatability, and same-harness performance comparisons. Intermediate canaries remain non-claiming.
Do not require exhaustive unit, fuzz, crash, or broad workspace testing before the first QEMU and Pi canaries. Deterministic tests cover semantic commit cuts, malformed input, and observed target defects; they do not simulate Pi IRQ, DMA/cache, scheduling, or media truth.
Commands
cargo test -p coh-rtc persistencecargo test -p root-task --test persistencecargo test -p pi4-driver-abi blockcargo test -p pi4-driver-runtime storagescripts/ci/test_plan_converge.sh --target qemu --focus ninedoor --operation-script scripts/cohsh/spool_roundtrip.cohscripts/ci/test_plan_converge.sh --target pi4 --focus pi4-driver --operation-script scripts/cohsh/spool_roundtrip.coh --pi4-target-evidence <current-target-evidence.json> --pi4-readback-image <current-readback.img> --pi4-identity-metadata <current-readback.identity.json> --pi4-serial-log <current-nonempty-uart.log> --pi4-host <pi-address>scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m29-qemuscripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m29-pi4- the exact accepted CYW43 repeatability and performance commands named by the frozen pre-M29 baseline; do not substitute a new M29-only harness
Checks (DoD)
- QEMU proves deterministic raw-block, spool, settings, reboot/reopen, invalid-
tail, and selected fault/recovery behavior through
virtio-blkon the exact named image and initial disk bytes. It makes no Pi claim. - Pi proves the manifest-declared raw region through the isolated EMMC2 runtime,
with no root-owned storage MMIO and no storage cap or link for IRQ 158,
IRQ 116,
0xfe300000, the Wi-Fi power/DMA pages, or CYW43 shared state. - Generated admission and the observed runtime inventory agree for MMIO, endpoints, notifications, SC/Reply, faults, queues/buffers, DMA if present, generation, containment anchors, and restart domain. Existing duplicate-IRQ and resource-ownership evidence is reused rather than restated by a second M29 proof system.
- Storage completion, flush, scan, fault, teardown, and recovery remain within declared service/deadline bounds. Fault injection leaves no stale caps, mappings, ring work, Reply/SC association, DMA/shared buffer, or old runtime generation; fresh service requires fresh generated readmission.
- Spool append/read/ack and settings A/B semantics are deterministic and bounded; offline store/forward and reboot recovery work on both targets; malformed and partial state fails closed.
/procstays read-only; U-Boot policy, FAT boot assets, sidecar spool semantics, console/TCP behavior, and the absence of a general filesystem are preserved.- On fresh exact-image Pi runs, persistence-disabled/pre-M29, M29-enabled-idle,
M29-under-load, and one meaningful storage fault/recovery case retain
comparable environmental and harness conditions. Every counted M29 Wi-Fi
boot reaches association, host EAPOL, DHCP, raw TCP, authenticated
cohsh, and the accepted focused workloads with no semantic error, CYW43/SDIO reset or restart caused by storage, hidden timeout/retry success, authority leak, unresolved storage/driver fault, or operator-liveness regression. - Compare exact pre-M29 baseline -> M29 idle and M29 idle -> representative storage load using the existing accepted workload and counters. No arbitrary percentage allowance is introduced. A material delta outside the established same-harness repeatability envelope is investigated and blocks closure until explained and resolved or explicitly requalified.
Compiler touchpoints
coh-rtcemits persistence limits, settings bounds, backend and raw-region selection, the Pi storage-runtime descriptor, temporal admission, and the existing generation-keyed driver authority inventory.- Pi validation admits
pi4-emmc2-rawonly with EMMC20xfe340000, a bounded raw region, an isolated MCS runtime, no physical IRQ row, no CYW43 bus link, and disjoint runtime/shared/DMA resources. The existing duplicate-physical- IRQ validator continues to reject any attempt to grant IRQ 158 twice. - Validation rejects CYW43,
sdio-host, USB/local-seat, FAT,cohesix.env, root-owned physical MMIO, or an undeclared region as a storage backend. Persistence IR and generated clients remain distinct from sidecar spool IR.
Task Breakdown
Title/ID: m29-contract-baseline-admission
Milestone: 29 / pre-M29 freeze and generated persistence admission
Goal: Freeze the exact accepted CYW43 comparator and admit only the minimum target-specific persistence resources and semantics.
Inputs: accepted `m26e-mcs-smp-target-acceptance` QEMU/Pi records and benchmark artifacts, configs/root_task.toml, configs/root_task_pi4_uboot_aarch64.toml, tools/coh-rtc/src/**, apps/root-task/src/hal/**, tools/cohesix-py/**, docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/BENCHMARKS.md.
Changes:
- docs/BENCHMARKS.md + M29 evidence record — reference, without copying or reclassifying, the exact accepted pre-M29 CYW43 image, manifest, driver archive, repeatability set, workload, counters, and environmental notes used for final comparison.
- tools/coh-rtc/src/** + configs/root_task*.toml — add bounded `persistence.*` semantics/backend/region fields and the Pi `driver-storage` image/task record; QEMU selects `virtio-blk`, Pi selects `pi4-emmc2-raw`; generated paths remain distinct from host sidecar spool paths.
- compiler/HAL validation — Pi storage is exactly EMMC2 `0xfe340000`, has no physical IRQ row or CYW43 bus link, and cannot name or receive IRQ 158, IRQ 116, `sdio-host`, `cyw43455`, Wi-Fi MMIO/power/DMA/shared resources, USB/local-seat, FAT, `cohesix.env`, or root-owned physical MMIO. Reuse the existing duplicate-IRQ, image/hot-path uniqueness, temporal admission, cap-layout, descriptor-seal, generation, and containment invariants.
- compatibility review — record required generated/document changes for `cohsh`, `coh`, `.coh` fixtures, `hive-gateway`, `tools/cohesix-py`, release packaging, and performance scripts; do not add an independent client-side persistence authority.
Commands:
- cargo test -p coh-rtc persistence
- scripts/check-generated.sh
Checks:
- The comparator names immutable accepted M26e evidence, not historical M26b data or a newly selected favorable sample.
- Invalid/overlapping resources, a second IRQ-158 owner, non-MCS Pi storage, sidecar-spool aliasing, and forbidden settings keys fail generation.
- No CYW43/SDIO source, ABI, manifest resources, scheduling semantics, restart logic, harness, or evidence classification changes.
Deliverables:
- Minimal generated persistence contract, exact pre-M29 comparison input, and compatibility-review record.
Title/ID: m29-qemu-virtio-raw-canary
Milestone: 29 / first target integration
Goal: Prove the bounded raw-block contract on QEMU before implementing spool/settings or Pi controller detail.
Inputs: `m29-contract-baseline-admission`, apps/root-task/src/hal/**, apps/root-task/src/drivers/virtio/**, scripts/qemu-run.sh, scripts/lib/qemu_launch_artifacts.py, canonical QEMU profiles.
Changes:
- apps/root-task/src/hal/block.rs + apps/root-task/src/storage/layout.rs — the smallest role-selected bounded read/write/flush/reopen contract and raw-region bounds used by both target semantics.
- apps/root-task/src/drivers/virtio/** — `virtio-blk` backend for QEMU only; no Pi or physical-driver claim.
- QEMU launch/evidence tooling — create a deterministic initial raw disk image, copy it to one mutable per-run image, attach it to the canonical `virt` launch, and bind initial/final image identity and geometry without making a mutated disk invalidate immutable kernel/root launch evidence.
- optional diagnostic only — try `sdhci-pci` + `sd-card` only under the promotion rule above; do not create a PCI/storage framework or block this task on the result.
Commands:
- cargo test -p root-task --test block_contract
- python3 -m pytest -q tests/test_qemu_launcher_profile.py tests/test_qemu_launch_artifacts.py
- scripts/ci/test_plan_converge.sh --target qemu --focus root-mcs --operation-script scripts/cohsh/storage_raw_roundtrip.coh
Checks:
- One exact QEMU boot writes, flushes, reopens after reboot, and reads the expected bounded raw blocks with stable typed errors for bounds and injected I/O failure.
- No spool/settings implementation, Pi emulation claim, broad regression suite, or mandatory SDHCI lane precedes this canary.
Deliverables:
- Non-claiming QEMU raw-block canary and an explicit retained/rejected QEMU-SDHCI decision.
Title/ID: m29-pi4-emmc2-raw-canary
Milestone: 29 / early physical storage and Wi-Fi coexistence
Goal: Prove the smallest isolated EMMC2 raw-block path on Pi 4 and immediately test it beside accepted CYW43.
Inputs: `m29-qemu-virtio-raw-canary`, accepted 26e Pi driver constructor/supervisor, configs/root_task_pi4_uboot_aarch64.toml, pinned Pi DTB and Linux topology capture, crates/pi4-driver-abi/**, apps/pi4-driver-runtime/**, apps/root-task/src/hal/**, scripts/pi4-image-build.sh, docs/HARDWARE_BRINGUP.md.
Changes:
- scripts/pi4-image-build.sh — extend only explicit `--initialize-disk` to create and verify the manifest-sized FAT boot plus unformatted raw persistence topology after exact whole-device identity/size checks; add a non-destructive planner test; leave routine exact-FAT-child reflashing, policy preservation, stage-only behavior, and U-Boot `mmc 0:1` loading unchanged.
- crates/pi4-driver-abi/** + apps/pi4-driver-runtime/** + HAL — add fixed pointer-free block request/completion records and isolated `driver-storage` service over EMMC2 `0xfe340000`; begin with bounded PIO/status completion, EMMC2 signal-enable clear, no physical IRQ cap, explicit device deadlines, and the accepted 26e MCS/supervisor/Reply/fault/generation lifecycle.
- selected Pi manifest/generated output — declare only storage-private ring/shared buffers and the derived temporal/resource budget; retain the existing three-entry physical IRQ topology and the complete existing CYW43-SDIO link unchanged.
- bounded fallback decision — retain PIO if it meets the canary. Consider controller-local DMA only after same-image evidence demonstrates a need; never borrow the accepted SDIO DMA page/channel, IRQ 116, or buffers.
Commands:
- bash -n scripts/pi4-image-build.sh
- python3 -m pytest -q tests/test_pi4_image_build.py <focused-partition-planner-test>
- cargo test -p pi4-driver-abi block
- cargo test -p pi4-driver-runtime storage
- scripts/cohesix-build-run.sh --clean --no-run --cargo-target aarch64-unknown-none
- scripts/pi4-image-build.sh --manifest configs/root_task_pi4_uboot_aarch64.toml --clean
- scripts/ci/test_plan_converge.sh --target pi4 --focus pi4-driver --operation-script scripts/cohsh/storage_raw_roundtrip.coh --pi4-target-evidence <current-target-evidence.json> --pi4-readback-image <current-readback.img> --pi4-identity-metadata <current-readback.identity.json> --pi4-serial-log <current-nonempty-uart.log> --pi4-host <pi-address>
Checks:
- A fresh exact Pi image performs one raw-region write/flush/reboot/read through `driver-storage` with no root EMMC2 mapping, out-of-region access, unbounded wait, or stale generation.
- The same early candidate reaches accepted CYW43 association, DHCP, raw TCP, and authenticated `cohsh` while storage is idle and during a bounded raw-block burst; EMMC2 does not signal shared IRQ 158 and no CYW43/SDIO reset, restart, timeout masking, or semantic error occurs.
- Any failure that requires IRQ sharing or CYW43/SDIO edits stops this task; it is not patched as ordinary storage bring-up.
Deliverables:
- Earliest useful boot-bound Pi EMMC2 proof and a go/no-go decision before higher persistence semantics.
Title/ID: m29-persistence-semantics-increments
Milestone: 29 / incremental stores and namespace
Goal: Add demonstrated spool then settings semantics, repeating the cheapest meaningful QEMU and Pi gate after each increment.
Inputs: `m29-pi4-emmc2-raw-canary`, apps/root-task/src/storage/**, apps/root-task/src/ninedoor.rs, apps/nine-door/**, scripts/cohsh/**, tools/cohesix-py/**, docs/ARCHITECTURE.md, docs/INTERFACES.md, docs/SECURITY.md, docs/SECURITY_NIST_800_53.md.
Changes:
- spool increment — implement bounded ring records, partial-tail rejection, deterministic scan/ack/full policy, manifest binding, `/proc/spool/{status,read}`, and `/queen/spool/{append,ack}`; then rerun focused QEMU and same-boot Pi roundtrip/CYW43 coexistence before settings work.
- settings increment — implement bounded A/B generation/checksum selection for runtime-owned local settings, explicitly rejecting U-Boot network/Wi-Fi and manifest boot-policy keys; then repeat both target gates.
- deterministic guards — cover semantic commit cuts, malformed/bounded decoders, a known block-image fixture, authorization, and disabled/missing profiles. Use a host `nine-door` mirror only where it is the smallest fixture adapter; root-target semantics remain authoritative.
- compatibility and docs — add focused `.coh` roundtrips and generated Python availability/bounds, update security/data-at-rest/retention/erase posture and canonical interfaces, and keep sidecar spool names and behavior unchanged.
Commands:
- cargo test -p root-task --test persistence
- cargo test -p nine-door --test persistence
- cohsh --script scripts/cohsh/spool_roundtrip.coh
- cohsh --script scripts/cohsh/settings_roundtrip.coh
- python3 -m pytest -q tools/cohesix-py/tests/test_persistence.py
- scripts/ci/test_plan_converge.sh --target qemu --focus ninedoor --operation-script scripts/cohsh/spool_roundtrip.coh
- scripts/ci/test_plan_converge.sh --target pi4 --focus pi4-driver --operation-script scripts/cohsh/spool_roundtrip.coh --pi4-target-evidence <current-target-evidence.json> --pi4-readback-image <current-readback.img> --pi4-identity-metadata <current-readback.identity.json> --pi4-serial-log <current-nonempty-uart.log> --pi4-host <pi-address>
Checks:
- Each store's deterministic contract passes before and after reboot on QEMU and Pi; target evidence, not a host model, establishes physical persistence.
- Each material increment retains the early Pi CYW43 functional/coexistence gate without broad reruns or speculative hardware simulations.
Deliverables:
- Bounded target-authoritative spool/settings namespace plus the smallest useful host/client regression surfaces.
Title/ID: m29-target-acceptance
Milestone: 29 / frozen-artifact QEMU and Pi acceptance
Goal: Accept deterministic persistence on both targets and prove Pi storage authority, failure containment, and CYW43 functional/performance non-regression.
Inputs: all preceding M29 tasks, exact accepted pre-M29 comparator, frozen QEMU/Pi images and manifests, initial/final disk identities, fresh Pi readback/serial/capture evidence, existing CYW43 repeatability and performance harness, docs/TEST_PLAN.md, docs/BENCHMARKS.md.
Changes:
- verification-only gate — make no runtime, manifest, generated-policy, harness, or image change; drift returns to the owning implementation task and invalidates affected evidence.
- QEMU acceptance — run deterministic raw-block/spool/settings/reboot/crash-cut/fault cases through `virtio-blk` and the applicable staged Test Plan. Any supplemental SDHCI result remains separately typed and cannot strengthen the Pi claim.
- Pi authority/fault acceptance — bind storage region, EMMC2 MMIO, absence of IRQ/DMA/CYW43 authority, generated/observed cap and runtime inventory, bounded MCS service, teardown, and fresh-generation recovery; exercise one meaningful storage failure/recovery while Wi-Fi stays live.
- Pi CYW43 acceptance — using comparable environmental conditions and the established workload/counters, compare exact pre-M29 baseline -> exact M29 persistence-enabled idle, then M29 idle -> representative sustained storage load. Preserve every run, error, timeout, retry, reset/restart, loss, reconnect, latency, throughput, DPC/IRQ, deadline, queue, fault, and operator-liveness classification already emitted by the accepted harness. Add instrumentation only if an observed delta cannot be decided or diagnosed from existing evidence.
Commands:
- scripts/check-generated.sh
- scripts/ci/check_test_plan.sh
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m29-qemu
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m29-pi4
- the exact frozen pre-M29 CYW43 repeatability and same-harness performance commands for baseline, M29 idle, and M29 storage-load runs
Checks:
- QEMU and fresh Pi independently pass their applicable persistence and staged acceptance; neither target's record substitutes for the other.
- Wi-Fi is repeatably healthy with persistence enabled idle, under representative sustained storage, and through one storage fault/recovery; storage causes no CYW43/SDIO reset/restart, semantic/traffic error, authority leak, hidden timeout/retry success, or operator-liveness loss.
- Baseline-to-idle and idle-to-load results remain inside the established repeatability envelope. Any material delta is investigated from same-boot evidence rather than waived with a new percentage allowance.
- Complete storage fault containment and readmission are accepted in M29; later production-ledger projection cannot be used to defer basic safety.
Deliverables:
- Separate exact-artifact QEMU and Pi M29 acceptance records plus a reviewable CYW43 non-regression comparison bound to the accepted pre-M29 baseline.
Shared assurance and runtime inventory
M29 supplies the storage-specific witnesses, generation-keyed inventory, and fault/recovery evidence consumed by the generic 28/28d contracts. Its compiler, lifecycle, and acceptance tasks register those records with the shared verifier and driver ledger. Reuse the existing schemas and proofs; 28/28d baseline implementation does not wait for a future storage runtime, and their baseline evidence cannot establish storage behavior.
Rabbit-hole review
The following are non-goals or optional engineering diagnostics, not deferred M29 features or completion requirements:
- mandatory QEMU
sdhci-pciparity, a QEMU hardware-emulation project, and a canonical macOS raw-device dependency; - a generic filesystem, generic block/storage framework, generic SDIO layer, USB mass-storage profile, scheduler redesign, or CYW43 cleanup;
- a fixed storage CPU/core/priority topology or controller DMA before the early Pi PIO canary establishes a need;
- exhaustive byte-by-byte power-loss campaigns before target integration; tests cover the store’s defined commit cuts and observed failure contracts;
- a new percentage performance allowance, a broad new Wi-Fi metric suite, or full QEMU/Pi acceptance after every small edit; and
- duplicate M29 resource proofs where the generated manifest, existing duplicate-IRQ validator, sealed runtime descriptor, and 26e supervisor evidence already establish the invariant.
The questions intentionally left to early M29 experiments are whether bounded PIO with EMMC2 interrupt signalling disabled meets the needed persistence rate, whether controller-local DMA is therefore necessary, which existing storage fault injection gives the most decision-rich recovery case, and whether an already-factored SD/MMC core ever makes the optional QEMU SDHCI lane cheap enough to promote. None is a reason to design around Pi behavior before the first physical canary.
Milestone 38 — Core-Local Service-Turn Scheduling
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain generated service buckets, queue/locality optimisation, sharded telemetry/spool drains, observability and exact-target pressure evidence. Activate from a measured useful-workload bottleneck. Preserve the accepted SMP+MCS topology and independent admission/reserve bounds; no speculative scheduler replacement.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 29a; current owner 38
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Delivery posture: Implement and qualify core-local service-turn scheduling on QEMU and Pi. Establish the same-harness baseline and demonstrate bounded locality, contention, throughput, and tail latency; an existing SLO miss is not required to start or complete this work.
Why now (core-local performance with proof): 25 established isolated tasks and affinity without SMP thread pools or work stealing; 26b requires the same benchmark harness. 26c/26d/26e/28 and applicable 29 evidence supply generated temporal, proof, and persistence contracts. Consume their scheduling-context/core baseline without reopening scheduler selection.
As-built alignment note: Manifest affinity, smp activity, active
slots, bounded service turns, and host pressure tests exist. Compiler-owned
service buckets, per-core turn budgets, drain rules, IRQ locality, and mixed-load
QEMU/Pi evidence do not.
Non-negotiable constraints
- No POSIX threads, general SMP runtime, async executor, shared work-stealing queue, or bulky SMP library inside the VM.
- No new in-VM protocols, console grammar, Secure9P verbs, namespace authority, or root-owned physical-driver hot paths.
- Authoritative state remains serialized through the authority path; parallelism is only at bounded, manifest-declared service edges.
- Physical hardware driver service remains restricted to manifest-declared isolated driver runtimes. Root-task may admit HAL resources, publish descriptors, and observe counters; it must not regain steady-state device ownership.
- Backpressure is explicit and deterministic: saturated service buckets return bounded busy/overrun evidence, not unbounded queue growth.
- Physical Pi 4 multicore throughput claims require fresh target evidence and must stay separate from shell transport, USB keyboard, Wi-Fi, HDMI, and flash proof lanes.
Prerequisite
- Before executable Worker service buckets may be enabled, Milestone 26e task
m26e-worker-supervisor-child-isolation,m26e-host-worker-integration, andm26e-worker-target-evidence-promotionmust be complete for the selected profile, including applied Worker scheduling, coalesced-notification, complete-teardown, host-receipt, and exact-target evidence. WorkerBus remains model-only and excluded. - Milestone 26e task
m26e-mcs-smp-target-acceptancemust be complete for both QEMU and Pi 4. Milestone 29a consumes that single SMP+MCS architecture and may not add a scheduler switch, classic compatibility profile, or fallback path. - Milestone 26e completed for the selected service topology so NineDoor, console/network, Worker, and root-task bucket ownership is assigned to real as-built tasks rather than the superseded root-owned/model-only layout.
- The Milestone 28 completed for the selected scheduling claims, including proof witnesses, HAL/driver-task authority checks, and verification-gate evidence. Milestone 29 persistence is required only when the measured hot path includes a selected persistent-spool drain.
- Milestones 26a and 26b, plus Milestones 26c and 26d, completed or explicitly scoped where their artifacts are inputs to Pi 4 driver-runtime, isolated runtime benchmark evidence, affinity, seL4 baseline, and target-qualified proof.
Goal
Convert existing manifest affinity into core-local, bounded service-turn execution for workers, manifest-declared isolated driver runtimes, NineDoor/provider paths, telemetry drains, and persistent-spool drains while preserving Cohesix’s file-shaped control plane, deterministic ordering, and tiny TCB.
This milestone optimizes the runtime shape; it does not add user-visible capabilities. Its success criteria are lower contention, bounded hot-path latency, deterministic busy/yield evidence, and proof that multicore work stays inside generated authority and scheduling contracts.
Deliverables
A) Compiler-owned core-local service IR
- Extend
coh-rtcwith profile-qualified scheduling fields for:- per-core service buckets,
- per-role and per-driver service-turn budgets,
- bounded burst size,
- queue depth,
- IRQ/locality hints,
- backpressure policy,
- telemetry/spool drain assignment.
- Generated manifests identify which core owns each bucket, which roles/drivers feed it, and which counters prove bounded execution.
- Validation rejects:
- roles assigned to unavailable cores,
- physical-driver hot paths without isolated runtime ownership,
- unbounded queues or bursts,
- a bucket core that differs from its owner’s SchedControl/SC core,
- cross-core donation for IRQ- or locality-bound work,
- overlapping authority that would let a worker or driver bypass its cap bundle or HAL-declared resources.
B) Core-local event pumps
- Root-task, NineDoor/provider adapters, workers, and manifest-declared isolated driver runtimes drain only their assigned bucket unless an explicit manifest rule declares a bounded handoff.
- Each service turn has fixed max work, max bytes, and max completions.
- Authority decisions remain serialized; local buckets may prepare, parse, drain, publish counters, and return deterministic busy/yield status.
- Every service bucket remains inside its admitted MCS budget and exposes scheduling-context binding, consumed-budget, timeout, Reply/donation, and overrun evidence. Per-turn max work/bytes/completions remain independent application bounds rather than being replaced by the SC budget.
C) Core-local linked-driver hot-path integration
- Build on the Milestone 26b bounded batching and counter evidence by binding GENET, CYW43, SDIO, USB, HDMI, serial, and PCIe service loops to generated service buckets.
- Payload-bearing submits continue to use the staged active-slot path: range validation, staged-byte fingerprint, busy-on-conflict, and no overwrite of an in-flight turn.
- Routine successful dataplane turns must not spam UART or corrupt foreground console output; hot counters are exposed through bounded observability instead.
- IRQ notification, DMA/cache maintenance, service turn, and completion publication stay local to the assigned runtime core wherever the platform profile supports it.
D) Sharded telemetry and spool drains
- Per-core telemetry buffers keep producer hot paths local and publish deterministic summaries into the existing namespace.
- Persistent-spool drain policy from Milestone 29 remains authoritative: no general filesystem, no
/procmutation, and append/ack semantics remain role-scoped. - Merge order is deterministic by generated bucket id, sequence, and timestamp fields; lost, dropped, or overwritten records carry explicit bounded evidence.
E) Observability, evidence, and verification
smp activityextends from assignment-bucket diagnostics to service-bucket evidence:- per-core service turns,
- budget exhaustions/yields,
- busy returns,
- max observed turn latency,
- queue depth high-water marks,
- driver/worker bucket membership,
- IRQ/locality proof where available.
/proc/schedule/*, evidence packs, and generated proof witnesses include the same bounded service-bucket records.- Verification checks prove the generated bucket layout matches resolved manifests, generated Rust tables, HAL grants, driver-task resources, and cap-bundle authority where enabled.
F) Pressure and target-qualified proof lanes
- Host-safe pressure tests validate mixed Secure9P, worker telemetry, driver-task, and spool-drain load without claiming Pi hardware throughput.
- QEMU SMP tests prove semantic stability and contention reduction against the generated schedule evidence.
- Pi 4 tests prove hardware throughput only with fresh logs that also separate flash proof, shell transport, USB/local-seat, Wi-Fi/GENET, HDMI, and SMP service-bucket evidence.
- Full same-harness benchmark closure is required in this milestone because the runtime scheduling model changes: QEMU and Pi 4 REST harness evidence must compare 29a results against the accepted 26d rolling baseline, and every claimed improvement or regression must cite service-bucket counters plus target-qualified proof.
Commands
cargo test -p coh-rtccargo test -p root-task --tests schedulecargo test -p pi4-driver-abicargo test -p pi4-driver-runtimescripts/check-generated.shscripts/ci/verification_gate.shpython3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --log-dir out/bench --log-prefix m29a-qemu-service-bucketspython3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --no-qemu --no-gateway --rest-url http://<pi4-gateway-host>:<port> --log-dir out/bench --log-prefix m29a-pi4-service-bucketsscripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m29a-qemu-smpscripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m29a-pi4-smp
Checks (DoD)
- Generated manifests and proof witnesses identify every service bucket, owner core, role/driver membership, budget, burst limit, queue bound, and backpressure rule.
- QEMU and Pi 4 profiles prove scheduling-context/core binding, donation/Reply ownership, timeout-fault routing, consumed-budget evidence, aggregate admission bounds, root/emergency/fault reserves, and absence of a classic scheduling fallback.
- Manifest-declared isolated driver runtimes keep payload-bearing work on staged active-slot APIs, return busy on conflicting payloads, and never overwrite in-flight turns.
- Service-bucket integration preserves the Milestone 26b batching and counter bounds while reducing multicore contention without changing ACK/ERR/END, Secure9P, console, worker namespace, or persistent-spool semantics.
smp activityand/proc/schedule/*report bounded service-bucket counters withcpu_pct=unavailableunless a real kernel-backed utilization source exists.- Host-safe pressure tests pass and remain classified as semantic/regression evidence, not Pi hardware throughput proof.
- QEMU and Pi 4 target-qualified Test Plan runs pass with no undocumented output drift; Pi 4 throughput claims cite fresh target evidence and keep USB/Wi-Fi/HDMI/shell proof lanes separate.
- Same-harness REST benchmark artifacts show whether service buckets improved, preserved, or regressed the 26d rolling baseline; any tuning remains bounded by generated service-bucket policy and cannot relax backpressure or proof-lane separation.
Compiler touchpoints
coh-rtcemits service-bucket tables beside existing affinity, worker/driver scheduling, driver-image, persistence, and proof-witness outputs.- Manifest validation fails closed when service-bucket topology conflicts with authority, HAL resource grants, driver-runtime ownership, cap-bundle records, or persistence bounds.
- Generated docs snippets summarize the service-bucket layout; hand-maintained docs may describe those snippets but must not become the scheduling source of truth.
Task Breakdown
Title/ID: m29a-smp-service-ir
Goal: Add compiler-owned core-local service bucket IR and validation.
Inputs: tools/coh-rtc, configs/root_task*.toml, docs/ROLES_AND_SCHEDULING.md, docs/INTERFACES.md.
Changes:
- tools/coh-rtc/src/ir.rs — service-bucket schema for core, role/driver membership, budget, burst, queue, IRQ-locality, and backpressure fields.
- tools/coh-rtc/src/validate.rs — reject unavailable cores, unbounded queues/bursts, physical-driver ownership drift, and authority conflicts.
- tools/coh-rtc/src/codegen/* — emit generated Rust/docs/proof-witness service-bucket tables.
Commands: cargo test -p coh-rtc && scripts/check-generated.sh
Checks: Service-bucket manifests are generated from IR, invalid topology fails closed, and generated docs match resolved manifests.
Deliverables: Compiler-owned service-bucket topology for QEMU and Pi 4 profiles.
Title/ID: m29a-core-local-event-pumps
Goal: Drain worker, provider, NineDoor, and root-task work through bounded core-local service turns.
Inputs: apps/root-task/src/event, apps/root-task/src/ninedoor.rs, apps/worker-*, apps/root-task/src/generated.
Changes:
- apps/root-task/src/event/** — service-turn dispatcher keyed by generated bucket id.
- apps/root-task/src/ninedoor.rs — bounded provider/session drains using generated bucket membership.
- apps/worker-heart + apps/worker-gpu + apps/worker-lora — keep worker loops within generated service-turn budgets where enabled.
Commands: cargo test -p root-task --tests schedule && cargo test -p worker-heart && cargo test -p worker-gpu && cargo test -p worker-lora
Checks: Each loop respects max work, bytes, completions, and deterministic busy/yield behavior; authority decisions remain serialized.
Deliverables: Core-local event-pump execution without a VM thread pool or work-stealing runtime.
Title/ID: m29a-linked-driver-hotpath-batching
Goal: Bind Milestone 26b manifest-declared isolated driver runtime batching and counters to generated core-local service buckets while preserving staged active-slot semantics.
Inputs: apps/pi4-driver-runtime, crates/pi4-driver-abi, apps/root-task/src/hal/driver_task.rs, docs/DRIVERS.md.
Changes:
- apps/pi4-driver-runtime/src/** — assign GENET, CYW43, SDIO, USB, HDMI, serial, and PCIe bursts/counters to generated service buckets.
- crates/pi4-driver-abi/src/** — expose fixed-layout service-bucket membership, counter, and max-turn evidence.
- apps/root-task/src/hal/driver_task.rs — preserve staged active-slot submit, busy-on-conflict, and completion publication invariants under batching.
Commands: cargo test -p pi4-driver-abi && cargo test -p pi4-driver-runtime && cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib
Checks: Service-bucket integration keeps batching bounded, does not add root-owned physical-driver paths, and cannot overwrite active payload-bearing turns.
Deliverables: Core-local isolated runtime hot paths with contract-local backpressure.
Title/ID: m29a-telemetry-spool-sharded-drain
Goal: Keep telemetry and persistent-spool drains core-local while preserving existing namespace and persistence semantics.
Inputs: apps/root-task/src/storage, apps/root-task/src/ninedoor.rs, docs/ARCHITECTURE.md, docs/INTERFACES.md.
Changes:
- apps/root-task/src/storage/spool.rs — generated bucket assignment for drain/flush work without changing append/ack semantics.
- apps/root-task/src/ninedoor.rs — deterministic merge order for per-core telemetry summaries and spool status reads.
- docs/ARCHITECTURE.md + docs/INTERFACES.md — document per-core drain evidence as observability, not new authority.
Commands: cargo test -p root-task --test spool && cargo test -p nine-door --test spool
Checks: Spool append/read/ack fixtures stay byte-stable; per-core telemetry merge order is deterministic and bounded.
Deliverables: Core-local telemetry/spool drain path that does not become a general filesystem or new protocol.
Title/ID: m29a-smp-observability-and-proof
Milestone: 29a / Python schedule-evidence projection compatibility
Goal: Expose service-bucket proof through `smp activity`, `/proc/schedule/*`, evidence packs, and verification witnesses.
Inputs: apps/root-task/src/event/mod.rs, apps/root-task/src/ninedoor.rs, apps/coh/src/evidence.rs, tools/coh-rtc, tools/cohesix-py/cohesix/evidence.py, tools/cohesix-py/tests/test_evidence_receipts.py, docs/USERLAND_AND_CLI.md, docs/TEST_PLAN.md.
Changes:
- apps/root-task/src/event/mod.rs — extend `smp activity` with service-bucket counters, busy/yield counts, max-turn latency, and IRQ-locality proof rows.
- apps/root-task/src/ninedoor.rs — bounded `/proc/schedule/*` service-bucket summaries.
- apps/coh/src/evidence.rs — include service-bucket snapshots in evidence packs.
- tools/cohesix-py/cohesix/evidence.py + tools/cohesix-py/tests/test_evidence_receipts.py — consume the generated additive service-bucket schedule fields and updated byte bounds without truncation, schema invention, inferred CPU utilization, or promotion to Worker, driver, QEMU, Pi, or hardware acceptance proof.
- tools/coh-rtc/src/verify.rs — verify service-bucket witnesses against resolved manifests and generated Rust tables.
Commands: cargo test -p root-task --tests schedule && cargo test -p coh --test evidence && python3 -m pytest -q tools/cohesix-py/tests/test_evidence_receipts.py -k service_bucket && scripts/ci/verification_gate.sh
Checks: Observability is bounded, read-only, generated-manifest aligned, and keeps `cpu_pct=unavailable` unless real utilization evidence exists; Rust and Python evidence-pack projections agree on service-bucket fixtures and bounds.
Deliverables: Auditable service-bucket proof surface with compatible Rust and Python evidence consumers for operators and verification gates.
Title/ID: m29a-pressure-and-target-proof
Goal: Add host-safe pressure coverage and target-qualified QEMU/Pi proof lanes for core-local service scheduling.
Inputs: scripts/ci/test_plan_run.sh, docs/TEST_PLAN.md, docs/BENCHMARKS.md, scripts/pi4_trace_normalize.py.
Changes:
- scripts/ci/test_plan_run.sh — add m27b QEMU and Pi target stages for service-bucket evidence.
- docs/TEST_PLAN.md — classify host pressure, QEMU semantic proof, and Pi hardware throughput proof separately.
- docs/BENCHMARKS.md — document required fresh-evidence fields before making throughput claims.
- scripts/pi4_trace_normalize.py — parse service-bucket counters only as SMP evidence, not USB/Wi-Fi/HDMI acceptance by itself.
Commands:
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m29a-qemu-smp
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m29a-pi4-smp
- python3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --log-dir out/bench --log-prefix m29a-qemu-service-buckets
- python3 scripts/rest_perf_harness.py --mode perf --suite all --runs 5 --no-qemu --no-gateway --rest-url http://<pi4-gateway-host>:<port> --log-dir out/bench --log-prefix m29a-pi4-service-buckets
Checks: Host pressure stays semantic-only; QEMU proves regression stability; Pi throughput claims require fresh target logs and separated acceptance lanes; same-harness REST artifacts compare service-bucket results to the 26d rolling baseline with service-bucket counters attached.
Deliverables: Repeatable validation and benchmark lanes for core-local SMP optimization.
Milestone 39 — Operator-Lane Scheduling and Multi-Surface Responsiveness
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain bounded fairness, resumable output, backpressure/degradation and pressure evidence across serial, USB, authenticated TCP, HDMI, network, diagnostics and optional persistence. Use 38 only when its service buckets are actually needed. Existing liveness defects remain current repairs, not a reason to wait for this optimisation.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 29b; current owner 39
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Delivery posture: Implement and qualify operator-lane scheduling over the 29a service buckets, covering every listed operator/background surface. Baseline and mixed-load responsiveness evidence are required; a prior latency incident or failed smaller fix is not an activation prerequisite.
Why now (operator concurrency without a larger TCB): Extend 29a service buckets with fairness for serial, USB, authenticated TCP, HDMI, emergency diagnostics, network, telemetry, and persistence lanes while preserving bounded single-owner execution.
As-built alignment note: The cooperative event pump, isolated
drivers, bounded turns, smp activity, and pressure hooks do not prove
compiler-declared lanes, starvation deadlines, resumable large output, or target
responsiveness. They support no Linux-like parallelism claim.
Non-negotiable constraints
- No POSIX threads, in-VM async executor, shared work-stealing queue, or bulky runtime library.
- No new in-VM protocol, unaudited RPC path, console grammar drift, Secure9P verb change, namespace authority change, or unbounded queue.
- Authoritative command execution remains serialized through the existing authority path; 29b improves concurrent I/O progress, buffering, response flush, and resumable work around that serialized command boundary.
- Physical hardware service remains restricted to manifest-declared isolated driver runtimes. Root-task may schedule bounded service turns and observe evidence; it must not regain steady-state device ownership.
- Operator priority is conditional on authenticated TCP-console state, not one static ranking. With no authenticated TCP session, service serial input, then USB local-seat input, then HDMI feedback. With an authenticated TCP session, make TCP command/response progress primary while preserving bounded serial/local-seat, emergency-diagnostic, and fatal-status service.
- Under load, active operator input and emergency/fatal status must not be hidden behind HDMI redraws, verbose diagnostics, large tails, telemetry spam, storage drains, or network proof traffic.
- A “100x better” claim must be grounded in accepted 26d/29a baseline evidence: either worst-observed operator input stall improves by two orders of magnitude under the same pressure harness, or the milestone records a manifest-declared hard latency bound with hardware reasons why a ratio claim is invalid.
Prerequisite
- Milestone 29a completed for the generated service buckets consumed by every 29b lane. There is one implementation and acceptance path over the accepted 26e SMP+MCS topology.
- Milestone 26e SMP+MCS target acceptance remains the sole scheduler architecture consumed by lane policy; 29b may tune generated admitted values but may not introduce a classic or runtime-selectable scheduler mode.
- Milestones 26c/26d, 29, and 28 completed for target profiles, persistence drains, formal witnesses, and the rolling performance baseline. Runtime lane selection still follows the deployment’s enabled services.
Goal
Convert the 29a service-bucket substrate into an operator-lane scheduler that preserves Cohesix’s single-authority command model while making serial, USB local-seat, authenticated TCP, HDMI, diagnostics, network, telemetry, and persistence work progress fairly and observably under mixed load.
Deliverables
A) Compiler-owned operator lane IR
- Extend
coh-rtcwith generated lane records for:serial-inputusb-local-seattcp-console-rxtcp-console-txnetwork-controlnetwork-datahdmi-displaydiagnosticstelemetry-spool
- Each lane declares priority class, starvation deadline, max work per turn, max bytes per turn, bounded queue depth, backpressure policy, degradation policy, owning task/SC/service bucket, admitted budget demand, and its generated behavior for TCP-authenticated versus no-TCP operator modes. Runtime session state selects only between statically admitted modes; it cannot inflate a budget, period, refill supply, MCP, or aggregate per-core demand, and clients cannot supply or raise lane priority.
- Validation rejects unbounded lanes, authority overlap, physical-driver lane ownership drift, and any lane that can bypass generated service-bucket or HAL resource limits.
B) Deterministic lane scheduler
- Root-task drains generated lanes using bounded deterministic policy over the 29a service buckets and within the owning MCS scheduling contexts.
- With no authenticated TCP session, serial input precedes USB local-seat input, which precedes HDMI feedback; all three stay above routine network data, verbose diagnostics, telemetry, and storage drains.
- With an authenticated TCP session, TCP receive and response flush become the
primary control-plane shell lanes for bounded
ACK/ERR/ENDliveness, but cannot starve serial/local-seat input, emergency diagnostics, or fatal status. - Saturated lanes return explicit busy/yield/drop evidence rather than growing queues.
C) Serialized authority with parallel I/O progress
- The console command parser and authority decisions remain single-writer and deterministic.
- Serial, local-seat, and TCP input arbitration records which surface supplied each command and how conflicting partial lines were handled.
- Long commands, diagnostics, transcript flushes, large
tailoutput, and HDMI redraws become resumable bounded work items so input polling and response flushing can interleave.
D) Backpressure and degradation policy
- HDMI redraws coalesce or drop superseded frames before physical input or TCP
ACK/ENDliveness is affected. - Verbose telemetry, routine progress breadcrumbs, network mirroring, and large tails degrade before command liveness.
- Storage/spool drains inherit Milestone 29 persistence semantics and must not preempt USB local-seat or serial input.
- Serial and local-seat output includes rate-limited
idle,busy,high-load, oroverloadsummaries plus the strongest known blocker; these summaries are bounded lane work and cannot create a new output backlog. - Network proof traffic remains classified separately from production TCP or REST throughput; proof-mode overrides must be explicit and lane-visible.
E) Observability and evidence
smp activityadds operator-lane rows: per-lane turns, ready/backlog state, max observed latency, starvation yields, busy returns, drops, coalesces, and suppression counts./proc/pressure/*exposes the same bounded read-only lane-pressure summary.- Evidence packs include lane snapshots so Milestone 27 tools can explain pressure without reconstructing scheduler internals.
scripts/pi4_trace_normalize.pytreats lane proof as responsiveness evidence only; it must not convert lane counters into USB, Wi-Fi, HDMI, TCP, or flash acceptance by itself.
F) Target-qualified pressure proof
- Host-safe tests simulate mixed serial, USB, TCP, HDMI, diagnostics, network, telemetry, and persistence pressure without making Pi throughput claims.
- QEMU proves transcript stability, bounded lane latency, and no ACK/ERR/END drift.
- Pi 4 proof, when claimed, requires fresh logs that keep serial responsiveness,
USB local-seat, TCP/
cohsh, Wi-Fi/GENET, HDMI, persistence, and flash proof lanes separate.
Commands
cargo test -p coh-rtccargo test -p root-task --tests schedulecargo test -p root-task --test operator_lanescargo test -p pi4-driver-abicargo test -p pi4-driver-runtimescripts/check-generated.shscripts/ci/verification_gate.shscripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m29b-qemu-lanesscripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m29b-pi4-lanespython3 scripts/rest_perf_harness.py --mode perf --suite console-pressure --runs 5 --log-dir out/bench --log-prefix m29b-qemu-lanes
Checks (DoD)
- Generated manifests and docs identify every operator lane, priority, deadline, max work, queue bound, degradation policy, owning SC/core, and admitted demand.
- Both authenticated-TCP and no-TCP static modes preserve generated per-core admission plus independent root/emergency/fault reserves; mode changes cannot mint or enlarge CPU-time authority.
- Serial and USB local-seat input have bounded key/line-to-echo and line-to-dispatch latency under mixed TCP/HDMI/network/diagnostic/storage pressure.
- Authenticated TCP console responses preserve bounded
ACK/ERR/ENDliveness without starving physical input or fatal/emergency status. - No-TCP and authenticated-TCP pressure fixtures prove the generated priority transition: serial -> USB local-seat -> HDMI feedback without TCP, and TCP as the primary shell with bounded physical/emergency progress when authenticated.
- Serial and local-seat load summaries are rate-limited, bounded, and report
only
idle,busy,high-load, oroverloadplus the strongest blocker. - Long diagnostics, large tails, HDMI redraws, telemetry drains, and persistence drains are resumable and cannot monopolize an event-pump turn.
- Console grammar, Secure9P semantics, worker namespace paths, persistence append/ack behavior, and driver-runtime authority remain byte-stable unless a separately versioned breaking-change process is followed.
- QEMU and Pi 4 target-qualified Test Plan runs pass with no undocumented output drift; Pi 4 claims cite fresh target logs and separated proof lanes.
- Any 100x responsiveness claim cites the accepted 26d/29a baseline, the exact pressure harness, and the lane counters that prove the improvement.
Compiler touchpoints
coh-rtcemits operator-lane tables beside service-bucket, affinity, persistence, proof-witness, and cap-bundle outputs.- Manifest validation fails closed when lane policy conflicts with generated authority, HAL grants, driver-runtime ownership, Secure9P bounds, or persistence drain semantics.
- Generated docs snippets summarize lane policy; hand-maintained docs may explain those snippets but must not become the scheduling source of truth.
Task Breakdown
Title/ID: m29b-operator-lane-ir
Goal: Add generated operator-lane policy and validation.
Inputs: tools/coh-rtc, configs/root_task*.toml, docs/ROLES_AND_SCHEDULING.md, docs/USERLAND_AND_CLI.md.
Changes:
- tools/coh-rtc/src/ir.rs — lane schema for TCP-authenticated/no-TCP priority modes, owning task/SC/core, admitted demand, deadline, work/byte bounds, queue depth, and degradation policy.
- tools/coh-rtc/src/validate.rs — reject unbounded lanes, admission overflow, authority overlap, physical-driver ownership drift, incompatible service-bucket references, and session modes that enlarge CPU-time authority.
- tools/coh-rtc/src/codegen/* — emit Rust/docs/proof-witness lane tables.
Commands: cargo test -p coh-rtc && scripts/check-generated.sh
Checks: Lane policy and authenticated-session mode transitions are compiler-owned, generated docs match resolved manifests, both modes fit the accepted SMP+MCS admission totals and reserves, clients cannot raise priority or budget, and invalid topology fails closed.
Deliverables: Generated operator-lane contract for QEMU and Pi 4 profiles.
Title/ID: m29b-event-pump-qos
Goal: Schedule serial, USB local-seat, TCP, HDMI, diagnostics, network, telemetry, and spool work through bounded lanes.
Inputs: apps/root-task/src/event/**, apps/root-task/src/local_seat.rs, apps/root-task/src/net/**, apps/root-task/src/storage/**.
Changes:
- apps/root-task/src/event/** — deterministic lane scheduler over generated service buckets.
- apps/root-task/src/local_seat.rs — lane-aware keyboard drain, echo, and HDMI coalescing policy.
- apps/root-task/src/net/** — lane-aware TCP response flush and network-control/data polling.
- apps/root-task/src/storage/** — persistence drain scheduling that cannot preempt physical input.
Commands: cargo test -p root-task --tests schedule && cargo test -p root-task --test operator_lanes
Checks: No-TCP and authenticated-TCP priority modes match the charter, physical input and TCP response liveness stay bounded, and saturated lanes report busy/yield/drop evidence.
Deliverables: Bounded operator-lane scheduler without a thread pool or new protocol.
Title/ID: m29b-resumable-output-and-diagnostics
Goal: Prevent diagnostics, large tails, HDMI redraws, and transcript flushes from monopolizing turns.
Inputs: apps/root-task/src/event/mod.rs, apps/root-task/src/ninedoor.rs, docs/USERLAND_AND_CLI.md, tests/fixtures/transcripts/.
Changes:
- apps/root-task/src/event/mod.rs — resumable diagnostic and output jobs with stable ACK/ERR/END behavior.
- apps/root-task/src/ninedoor.rs — bounded tail/log/read output chunks with lane-visible continuation.
- tests/fixtures/transcripts/ — pressure transcripts proving byte-stable command results.
Commands: cargo test -p root-task --test operator_lanes && cargo test -p nine-door
Checks: Existing command output remains byte-stable where semantics do not change; large outputs yield between bounded chunks.
Deliverables: Long-running console-visible work that remains responsive under input pressure.
Title/ID: m29b-pressure-observability
Goal: Expose lane pressure through `smp activity`, `/proc/pressure/*`, evidence packs, and trace normalization.
Inputs: apps/root-task/src/event/mod.rs, apps/root-task/src/ninedoor.rs, apps/coh/src/evidence.rs, scripts/pi4_trace_normalize.py.
Changes:
- apps/root-task/src/event/mod.rs — operator-lane rows in `smp activity`.
- apps/root-task/src/ninedoor.rs — bounded read-only `/proc/pressure/*` summaries.
- apps/coh/src/evidence.rs — lane snapshots in evidence packs.
- scripts/pi4_trace_normalize.py — parse lane proof without treating it as device acceptance.
Commands: cargo test -p root-task --tests schedule && cargo test -p coh --test evidence && pytest tests/test_pi4_trace_normalize.py
Checks: Pressure evidence is bounded, read-only, manifest-aligned, and separated from USB/Wi-Fi/HDMI/TCP acceptance gates.
Deliverables: Operator-visible pressure proof ready for Milestone 27 tooling.
Title/ID: m29b-pressure-and-target-proof
Goal: Add host-safe, QEMU, and Pi 4 pressure gates for multi-surface responsiveness.
Inputs: scripts/ci/test_plan_run.sh, scripts/rest_perf_harness.py, docs/TEST_PLAN.md, docs/BENCHMARKS.md.
Changes:
- scripts/ci/test_plan_run.sh — m29b QEMU and Pi target stages.
- scripts/rest_perf_harness.py — console-pressure suite or equivalent bounded pressure harness.
- docs/TEST_PLAN.md + docs/BENCHMARKS.md — classify lane responsiveness, throughput, and target proof separately.
Commands:
- scripts/ci/test_plan_run.sh --target qemu --state-dir out/test-plan/m29b-qemu-lanes
- scripts/ci/test_plan_run.sh --target pi4 --state-dir out/test-plan/m29b-pi4-lanes
- python3 scripts/rest_perf_harness.py --mode perf --suite console-pressure --runs 5 --log-dir out/bench --log-prefix m29b-qemu-lanes
Checks: QEMU proves semantic stability, timeout/overrun behavior, and latency bounds; Pi 4 claims require fresh target logs, preserved MCS admission/reserve evidence, and separated serial, USB, TCP, Wi-Fi/GENET, HDMI, persistence, and flash proof lanes.
Deliverables: Repeatable validation for Cohesix multi-surface responsiveness.
Milestone 40 — Read-Only Edge Status and Attestation Tool
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain the standalone read-only coh-status workflow, shared inspect/attest/snapshot core, offline replay and latency checks. Activate for a field workflow not met by current doctor/CLI/SwarmUI. Reuse existing verifiers; distinguish historical evidence, measurements and genuinely authenticated live attestation.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 30; current owner 40
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Delivery posture: Deliver the standalone coh-status binary and its complete
read-only field workflow. Reuse 27/27f snapshot, trace, status, and attestation
internals; no separate field-demand decision is required.
Why now (compiler): Field technicians need offline host status from the same read-only 9P surfaces and boot attestation.
As-built alignment note: apps/coh-status is a library with trace
replay fixtures, not a standalone CLI. Replace its /queen/ctl fixture writes
with explicit read-only status actions.
Prerequisite
- Milestone 27 completed for the shared read-only inspect/attest/evidence-pack internals that
coh-statusreuses. Milestone 30 must not fork a second status parser, attestation verifier, trace reader, or snapshot schema when the Milestone 27 host-tool core already owns that behavior.
Goal
Promote coh-status into a small read-only CLI for local field inspection of boot/attest data using the existing TCP console transport and offline artifacts, without adding any in-VM 9P/TCP listener and without introducing a second UI stack.
Non-Goals
- Repo-wide SPDX/NOTICE header sweeps (track separately; not required for the status tool).
- A separate Tauri/UI variant; SwarmUI already occupies the UI role.
- Generic shell verbs (
echo,spawn, arbitrary writes) or any write-capable façade over/queen/ctl.
Deliverables
coh-statusbinary with:- default read-only status summary
attestsubcommand for manifest/evidence verification- offline replay/snapshot mode for field diagnostics
- Shared read-only status/snapshot core reused by
coh inspect,coh attest, SwarmUI, andcoh-status. - Shared offline snapshot/CBOR parsing code extracted from existing SwarmUI logic so grammar stays aligned.
- Status-specific fixtures proving read-only behavior; no
/queen/ctlwrites in the canonicalcoh-statustest flows. - Bounded command-latency fixture for offline and live-read status paths. This is field-tool latency evidence, not a full runtime or hardware throughput benchmark.
Commands
cargo build -p coh-statuscargo run -p coh-status -- --helpcargo run -p coh-status -- offline --trace tests/fixtures/traces/trace_v0.tracecargo run -p coh-status -- attest --helpcargo test -p coh-status --test latency
Checks (DoD)
- Works offline; wrong/expired ticket → deterministic
ERR reason=Permissionsurfaced to user. - Shared snapshot/CBOR parsing identical to SwarmUI for overlapping flows.
- Abuse case: attempt to write via
coh-statusreturns deterministic denial and does not mutate state. - UI/CLI/console equivalence MUST be preserved: ACK/ERR/END sequences must remain byte-stable relative to the 7c baseline.
coh-statuslatency evidence stays bounded on representative offline traces and live-read fixtures; regressions are classified as snapshot parsing, attestation verification, transport, or artifact-size overhead before 30a/30b field surfaces reuse the status core.
Compiler touchpoints
coh-rtcemits localhost binding guidance and attestation paths for Pi 4 boot profile intodocs/HARDWARE_BRINGUP.mdanddocs/USERLAND_AND_CLI.md.
Task Breakdown
Title/ID: m30-status-tool
Goal: Build a real read-only `coh-status` CLI on top of shared inspect/attest internals.
Inputs: apps/coh-status/, shared host-tool status core, Pi 4 boot profile manifest outputs, attestation nodes.
Changes:
- apps/coh-status/src/main.rs — status CLI entrypoint with read-only subcommands only.
- apps/coh-status/src/lib.rs — preserve trace replay helpers while exposing only read-only status/attestation operations to the CLI.
- apps/coh-status/tests/offline.rs — simulate offline read and expired ticket.
- apps/coh-status/tests/transcript.rs — remove the current generic `/queen/ctl` convergence flow from the canonical status transcript.
Commands:
- cargo build -p coh-status
- cargo run -p coh-status -- --help
Checks:
- Expired ticket returns ERR; offline cache used when transport unavailable.
Deliverables:
- Tool usage documented in docs/HARDWARE_BRINGUP.md and docs/USERLAND_AND_CLI.md.
Title/ID: m30-shared-snapshot-core
Goal: Extract shared read-only snapshot/CBOR parsing for SwarmUI and `coh-status`.
Inputs: apps/swarmui snapshot/cache code, apps/coh-status, shared host-tool internals.
Changes:
- shared status/snapshot module — read-only offline artifact decoding.
- apps/coh-status/src/lib.rs — consume shared snapshot/trace helpers.
Commands:
- cargo test -p coh-status --test offline
- cargo test -p swarmui --test trace
Checks:
- Shared offline parsing stays byte-stable across SwarmUI and `coh-status`.
Deliverables:
- Shared read-only snapshot core with no duplicate parsers.
Title/ID: m30-attest-verify
Goal: Verify nonce-bound TPM2 Quote or DICE evidence with the same trust policy as the shared host-tool stack; never treat a manifest hash as attestation.
Inputs: accepted m26-device-identity-attestation-closure evidence, `/proc/attest/{capabilities,status,challenge,evidence}`, trust anchors/reference measurements/revocation policy, shared attestation helpers, cached offline evidence.
Changes:
- apps/coh-status/src/attest.rs — generate/consume a bounded challenge and verify evidence type, signature/certificate or DICE chain, nonce freshness, device identity, selected target/manifest/component measurements, policy/profile, clock/reset/restart state where present, and revocation/expiry against configured trust material.
- shared attestation verifier reused by `coh inspect` / `coh attest` where applicable; measurement-only and unavailable modes remain explicit and cannot satisfy an authenticated-device gate.
- offline mode — verify a previously captured evidence/challenge/reference bundle without implying current freshness; label it historical with capture identity/time.
Commands:
- cargo test -p coh-status --test attest
Checks:
- Forged signatures/chains, replayed or wrong nonces, wrong device/manifest/measurement/profile, expired/revoked trust, unsupported evidence, and measurement-only input are rejected identically by `coh-status`, `coh inspect`, and `coh attest`; valid TPM2/DICE evidence is identity- and freshness-bound, and offline results are never presented as live.
Deliverables:
- Verified live and clearly labelled offline attestation workflows documented; regression outputs stored.
Title/ID: m30-readonly-regressions
Goal: Replace generic convergence fixtures with `coh-status`-specific read-only flows.
Inputs: apps/coh-status/tests/, tests/fixtures/transcripts/, docs/TEST_PLAN.md.
Changes:
- apps/coh-status/tests/transcript.rs — read-only status transcript only.
- apps/coh-status/tests/latency.rs — bounded offline/live-read status latency fixtures over representative artifacts.
- tests/fixtures/transcripts/ — `coh-status` fixtures with no `/queen/ctl` writes.
Commands:
- cargo test -p coh-status --test transcript
- cargo test -p coh-status --test latency
Checks:
- Canonical `coh-status` flows read `/proc/boot`, `/proc/attest/*`, and selected telemetry without mutating state.
- Offline/live-read status latency stays bounded and is reported as field-tool evidence, not REST/Pi throughput proof.
Deliverables:
- Field-tech read-only transcript fixtures and explicit docs.
Milestone 41 — Pi 4 Root-Shell Hardware Status
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain the passive Pi-only hw-status command, HAL-mediated allowlisted firmware queries, shared field vocabulary and fresh serial/latency evidence. Activate for a real local diagnostic need. No firmware writes, driver ownership changes or implied Wi-Fi/USB/display acceptance.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 30a; current owner 41
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Delivery posture: Deliver hw-status, the shared read-only status projection,
and all listed Pi field diagnostics with exact target evidence. No separate
field-demand decision is required.
Why now (field diagnostics): Complement 30 host status with bounded,
serial-local hw-status at cohesix> on the Pi 4 U-Boot profile when TCP, host
tooling, or storage is unavailable. Keep it observational, with no device
mutation or root-owned driver path.
As-built alignment note: hw-status is absent. Boot framebuffer,
driver-progress, and timer diagnostics are not a firmware-property snapshot;
that claim requires its own transcript.
Prerequisite
- Milestone 26a/26b owner-state and isolated runtime proof restored for the selected Pi 4 profile.
- Milestone 27 completed for shared read-only snapshot/evidence conventions.
- Milestone 30 completed so
hw-statusfield names can be reused bycoh-statusrather than creating a second status vocabulary.
Goal
Add a Pi 4-build-only hw-status command on the root shell that prints bounded, stable, read-only board status:
- firmware-reported power-state flags,
- selected clock rates,
- selected voltage domains,
- SoC temperature and throttle/undervoltage flags when exposed,
- framebuffer geometry plus ARM/GPU memory split,
- bounded firmware-managed device notification counters or last-notification summaries.
Non-Goals
- No firmware writes, power-state changes, clock changes, voltage changes, turbo/overclock controls, reboot policy changes, or recovery actions.
- No root-owned HDMI, USB, Wi-Fi, GENET, SDIO, PCIe, or GPU driver path; isolated runtimes remain the hardware owners for steady service.
- No new in-VM TCP listener, 9P provider requirement, host RPC, or
cohsh-coregrammar expansion beyond the documented root-console command. - No direct physical-address probing or mailbox/MMIO access outside HAL-admitted Pi 4 resources.
Deliverables
hw-statusroot-shell command available only for the Pi 4 U-Boot profile. Other profiles must omit it or return deterministicERR reason=unsupportedper generated grammar/docs.- HAL-mediated Pi 4 firmware-property/status helper with an explicit allowlist of read-only property tags, bounded buffers, timeout evidence, and failure rows.
- Stable serial transcript format using sectioned rows such as
hw power,hw clock,hw voltage,hw thermal,hw memory,hw framebuffer, andhw firmware-notify. - Read-only status mirror for
coh-status, reusing the same field names without adding authority or a second parser. - Documentation and regression fixtures proving the command is passive, Pi 4-profile gated, and does not count as isolated runtime hardware acceptance.
- Bounded serial-local command-latency evidence for
hw-statusso passive diagnostics stay quick without reopening runtime throughput gates.
Commands
cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hw_status -- --test-threads=1cargo test -p cohsh-coreSEL4_BUILD_DIR=$REPO/seL4/build_UBOOT cargo check -p root-task --target aarch64-unknown-none --no-default-features --features release-pi4scripts/check-generated.shscripts/ci/test_plan_run.sh --state-dir out/test-plan/m30a-hw-statuscargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hw_status_latency -- --test-threads=1
Checks (DoD)
helpanddocs/USERLAND_AND_CLI.mdlisthw-statusonly for the Pi 4 root-console surface; TCP/cohshshared grammar does not accidentally accept undocumented raw hardware commands.- Mocked firmware-property tests cover success, unsupported tag, timeout, malformed response, and partial data without panics or unbounded waits.
- Live Pi 4 acceptance, when claimed, includes a fresh serial transcript showing
hw-statusreturning bounded rows while USB/local-seat, Wi-Fi/GENET, HDMI, and shell proof lanes remain separate. - No
hw-statuspath writes firmware state, changes clocks/voltage/power domains, clears notifications, or touches isolated runtime device state. - Generated docs, fixtures, and trace-normalizer expectations remain aligned; command output drift is intentional only with matching docs/tests.
hw-statuslatency evidence stays bounded in mocked tests and, when live Pi evidence is claimed, is reported as serial-local passive diagnostic timing rather than hardware runtime throughput proof.
Compiler touchpoints
coh-rtcowns the profile gate and generated command/help snippets forhw-status.- Manifest validation rejects enabling
hw-statusoutside Pi 4 hardware profiles or without the HAL firmware-property resource declared.
Task Breakdown
Title/ID: m30a-hw-status-ir
Goal: Add the Pi 4-only generated command gate and status field vocabulary.
Inputs: tools/coh-rtc, configs/root_task_pi4_uboot_aarch64.toml, docs/USERLAND_AND_CLI.md.
Changes:
- tools/coh-rtc/src/** — profile-gated `hw-status` command/help generation and field-name constants.
- configs/root_task_pi4_uboot_aarch64.toml — declare read-only Pi 4 firmware-status capability for the root diagnostics surface.
- docs/snippets/* + docs/USERLAND_AND_CLI.md — generated and hand-maintained command reference updates.
Commands: cargo test -p coh-rtc && scripts/check-generated.sh
Checks: Non-Pi profiles reject the command gate; generated help/docs match resolved Pi 4 manifest truth.
Deliverables: Compiler-owned `hw-status` profile gate and stable field vocabulary.
Title/ID: m30a-hw-status-hal
Goal: Implement bounded read-only Pi 4 firmware-property status queries behind HAL.
Inputs: apps/root-task/src/hal/**, apps/root-task/src/arch/aarch64/**, seL4/build_UBOOT generated headers.
Changes:
- apps/root-task/src/hal/** — Pi 4 firmware-property read helper with tag allowlist, bounded mailbox buffers, timeout/fault evidence, and no write/control tags.
- apps/root-task/src/arch/aarch64/** — reuse existing cache/MMIO primitives only through HAL-approved mappings.
Commands: cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hw_status -- --test-threads=1
Checks: Success, timeout, malformed response, unsupported tag, and partial-data fixtures return typed status rows without panics or unbounded waits.
Deliverables: HAL-owned passive Pi 4 hardware-status snapshot provider.
Title/ID: m30a-hw-status-shell
Goal: Add the `hw-status` root-shell command and stable serial transcript.
Inputs: apps/root-task/src/console, apps/root-task/src/event/mod.rs, docs/USERLAND_AND_CLI.md.
Changes:
- apps/root-task/src/console/** + apps/root-task/src/event/mod.rs — parse and dispatch `hw-status` only on the Pi 4 root-console diagnostics surface.
- apps/root-task/src/event/mod.rs — emit bounded `hw ...` rows for power, clocks, voltage, thermal, framebuffer/GPU memory, and firmware notifications.
- docs/USERLAND_AND_CLI.md — document serial/local-only behavior and unsupported-profile result.
Commands:
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hw_status -- --test-threads=1
- SEL4_BUILD_DIR=$REPO/seL4/build_UBOOT cargo check -p root-task --target aarch64-unknown-none --no-default-features --features release-pi4
Checks: Output is stable, bounded, read-only, and does not change ACK/ERR/END semantics for existing commands.
Deliverables: Pi 4 serial `cohesix> hw-status` command.
Title/ID: m30a-hw-status-regressions
Goal: Add fixtures and Pi 4 evidence parsing for passive hardware-status diagnostics.
Inputs: docs/TEST_PLAN.md, scripts/pi4_trace_normalize.py, tests/fixtures/transcripts/.
Changes:
- docs/TEST_PLAN.md — classify `hw-status` as passive Pi 4 diagnostics, not hardware acceptance for USB/Wi-Fi/GENET/HDMI.
- scripts/pi4_trace_normalize.py — parse optional `HW_STATUS_*` fields from captured transcripts without making them gate blockers.
- apps/root-task/tests/hw_status_latency.rs — mocked bounded timing checks for HAL firmware-property status rows and unsupported-profile refusal.
- tests/fixtures/transcripts/ — add serial-local `hw-status` success and unsupported-profile fixtures.
Commands:
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hw_status -- --test-threads=1
- cargo test -p root-task --no-default-features --features driver-tests-pi4 --lib hw_status_latency -- --test-threads=1
- pytest tests/test_pi4_trace_normalize.py
Checks: Transcript, latency, and normalizer coverage prove passive behavior, bounded command timing, stable field extraction, and no regression in existing Pi 4 gates.
Deliverables: Repeatable host and Pi 4 validation for `hw-status`.
Milestone 42 — Additional AI-Native Namespace Projections
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain bounded job/dataset/experiment/inference/metrics and admission read projections when their actual owner contracts exist. Activate for a namespace consumer that current APIs cannot adequately serve. Use existing role-scoped grammar and canonical host-ticket effects; no semantic store, inference data plane or new authority path enters the VM.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 30b; current owner 42
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Delivery posture: Implement the complete listed AI control namespace, host/UI projections, and conformance after its owner contracts. No adoption study or separate namespace-demand decision is required.
Why now (positioning): Expose accepted 27b provider rows, 28b semantic/capsule references, 28c admission, 28e AI/PEFT state, 28f inference receipts, and 28g workflows through bounded namespace controls and evidence. Semantic graphs and inference data planes stay host-side, with no second executor or paths lacking required dependencies.
Goal
Add a manifest-defined, role-scoped AI control namespace that lets operators and automation inspect and drive AI lifecycle state through existing Secure9P semantics. This milestone is limited to control-plane surfaces only: no in-VM application runtime, no general UI stack, no mutable POSIX-like filesystem, and no new transport or RPC model.
As-built alignment note: The 26c planning audit found no
ecosystem.ai.* IR or /jobs, /datasets, /experiments, /infer, /metrics,
or /proc/admission/* provider in host or VM NineDoor. Add projections only
after the prerequisites below prove their owner contracts without grammar drift.
Prerequisites
- Milestone 27a completed (delegated REST identity, idempotent queen intents, writer-epoch fencing, audit/replay baseline).
- The exact Milestone 27b provider/integration rows completed for the namespace use case; unselected catalogue breadth is not a prerequisite.
- The Milestone 28b completed for immutable snapshot/artifact refs, Context Capsules, render receipts, visibility/provenance, host tools, and selected conformance evidence; the complete semantic/capsule implementation is required.
- Milestone 28c completed (typed intent, authoritative fact snapshot, policy decision, state-bound grant, witness, audit/replay, and reference action evidence).
- Milestone 28e completed (host-side AI run envelopes, checkpoint/evidence model, complete PEFT pipeline transaction, use-case promotion, and
/host/tickets/specAI actuation semantics). - Milestone 28f completed (compatible host inference admission, provider-neutral receipts, cache/stream evidence, content policy, host tools, and provider/client conformance).
- Milestone 28g MCP coverage, usage guidance, and the exact governed workflow used by the namespace case completed over existing Cohesix grammar. A2A is not required; read-only protocol conformance alone does not prove the workflow.
- Production profiles may claim matching accepted 26e Worker/driver live authority for AI namespace projections. Claims of one-to-one Worker ticket/lease binding, complete driver-inventory ledger projection, or structured quarantine/restart additionally require Milestone 28d evidence. Read-model-only or host-ticket-only profiles may remain gated by 27a/27b/28b/28e/28f/28g without either live-task or 28d production-ledger claims.
Non-Goals
- No app runtime, package manager, bundle loader, or process model beyond the existing Queen/worker control model.
- No in-VM GUI, mutable
/uiruntime surface, or second operator protocol. - No generic
/netservice API, sockets-by-file, or hidden request/response RPC behind file names. - No mutable general-purpose
/store; existing CAS, models, telemetry, and spool semantics remain authoritative and distinct. - No in-VM semantic graph, object pack, rebuildable index, extractor, capsule planner/renderer, vector store, raw source tree, prompt archive, model output archive, tokenizer, or provider client. The namespace exposes bounded immutable refs/status/receipts, not the host semantic or inference data plane.
- No OpenAI-compatible API over NineDoor and no claim that
/infer/*replaces or proxies the accepted 28f host endpoint. - No new 9P verbs, no console grammar changes, and no deviation from
ERR = no side effects. - No second host-execution plane parallel to
/host/tickets/spec; VM-visible AI paths do not bypass delegated host-ticket authority or Milestone 27a fencing/idempotency rules. - No create, unlink, rename, chmod, symlink, dynamic prompt/blob tree, arbitrary path component, or general directory mutation semantics. AI namespace writes target fixed generated control files only.
- No opaque inter-agent mailbox or prompt-transcript tree exposed as a first-class namespace primitive.
Deliverables
- AI namespace roots are the VM-visible control-plane projection of the host-side semantics proven in 28b, 28e, and 28f.
- Every enabled root/control file names the stable 27b
use_case_id, required provider/integration rows, minimum Worker tier, and accepted host receipt schema. Generation fails or the path is deterministically absent when required dependencies are unavailable; a namespace projection never promotes their observed mode. - Any AI path whose write can cause host-side side effects MUST resolve to documented host-ticket actions and inherit delegated identity, idempotency, writer epoch, and audit/replay guarantees.
- Read-only AI paths (
/metrics/*and read views of/jobs/*,/datasets/*,/experiments/*, and/infer/*) do not become a second source of truth for semantic provenance, context admission, inference facts, or execution authority. - Add only bounded read-only admission projections using the established
namespace families:
/proc/admission/statusfor current bounded gate/version/state summaries,/proc/admission/recentfor a bounded redacted recent-decision view,/policy/admission/versionfor the generated policy/schema/checker identity, and- existing
/audit/decisionsfor append-only decision evidence. These are projections of accepted 28c records, not a new AI-specific write, policy mutation, grant, ticket, or replay path.
- Manifest-gated AI control roots under the Secure9P namespace, with paths aligned to current authority rules:
/jobs/*for bounded job submission, queue state, completion records, checkpoint refs, and handoff lineage views/datasets/*for dataset metadata, lineage pointers, and policy-visible readiness state/experiments/*for append-only run metadata, semantic snapshot refs, Context Capsule/render/retrieval-manifest refs, selection summaries, and result summaries/infer/*for bounded inference request/admission/receipt control surfaces where explicitly enabled, including capsule refs, prefix-group read views, provider-fact classification, and output digests but no raw prompt/output content/metrics/*for read-only fleet, semantic-paging, context-render, inference, cache, and model metrics summaries with fact source and owner receipt refs
- Queen-only control files remain append-only; worker and observer views remain role-filtered and read-only where appropriate.
- Host tools (
cohsh,coh, REST projection, SwarmUI read models where relevant) discover and render the new paths without introducing new verbs.cohshuses only existingLS/CAT/TAIL/ECHO; full semantic traversal and compatible inference remain on the accepted host CLI/SDK/gateway surfaces. - FUSE, Python, MCP/A2A, and UI views remain projections of the same admitted paths and 27b visibility classes; each is independently conformance-tested and cannot synthesize jobs, Workers, models, or successful PEFT/GPU execution from client state.
- Canonical schemas for all new paths documented in
docs/INTERFACES.mdand emitted fromcoh-rtc. - Namespace state remains a projection of 28b immutable snapshot/capsule/render refs, 28c admission decisions/grants, 28e run envelopes/checkpoints/retrieval manifests, and 28f inference receipts; it does not introduce an independent semantic store, inference protocol, scheduler, or executor.
- Namespace-scale microbenchmark evidence for representative job/run/checkpoint counts proves
ls,cat,tail, and fixed-control-file writes remain bounded. This is a namespace/provider microbenchmark, not a full Pi hardware throughput gate, unless high-churn AI namespace paths change the root-task hot runtime path.
Commands
cargo test -p coh-rtccargo test -p nine-doorcargo test -p root-taskcargo test -p cohshcargo test -p coh --test ai_namespacepython3 -m pytest -q tools/cohesix-py/tests/test_ai_namespace.pycohsh --script scripts/cohsh/ai_namespace_roundtrip.cohcohsh --script scripts/cohsh/ai_namespace_scale.coh
Checks (DoD)
- All new AI namespace paths are manifest-gated, bounded, and role-scoped.
- Write-capable AI paths are fixed generated control files with declared target grammar; no dynamic file creation, unlink, rename, chmod, symlink, arbitrary path expansion, prompt/blob tree, or hidden request/response RPC is accepted.
- Writes remain append-only and auditable; reads stay within declared
msizeand path bounds. - Existing ACK/ERR/END grammar, Secure9P transport behavior, and host-tool semantics remain byte-stable unless intentionally versioned in the same change.
- Missing AI paths are treated as gate state, not client bugs.
- Enabled AI paths have accepted semantic/capsule, inference, provider/integration, package, external-executor, Worker-tier, and use-case records for the selected profile; missing dependencies yield generated absence or typed not-enabled status before mutation.
- Read views expose verified 28b snapshot/object-summary/capsule/render refs, 28e task/handoff/checkpoint/prefix evidence, and 28f admission/provider/cache/stream/output-digest receipt refs without becoming a second source of authority.
- Admission read views expose only redacted, bounded, generated 28c status, recent-decision, policy-version, and audit refs; they cannot accept an intent, select policy, issue a grant, or trigger execution.
/infer/*writes map through accepted 28c admission to the existing 28e host-ticket action and 28f gateway contract; no provider call occurs from NineDoor, and no raw prompt/output or model-produced tool call is stored or executed by the namespace provider.- No new in-VM listener, runtime, or hidden RPC behavior is introduced.
- AI namespace scale evidence shows bounded path walk/list/read/write behavior at representative job/run counts; material regressions are classified as namespace-provider overhead, host-tool projection overhead, or runtime hot-path regression before downstream profiles depend on the new roots.
Compiler touchpoints
coh-rtcadmitsecosystem.ai.*IR fields for path gating, quotas, and per-surface limits.coh-rtcemits bounded read-only/proc/admission/status,/proc/admission/recent,/policy/admission/version, and existing/audit/decisionsprojection metadata from the accepted 28c schemas and visibility/redaction policy; no admission write field or AI-specific authority path is generated.- Each
ecosystem.ai.*entry references stable 27b integration/use-case ids, accepted 28b semantic/capsule schema refs, accepted 28e run/action refs, accepted 28c admission plus 28f receipt refs, and generated Worker/executor prerequisites; validation rejects independent schemas, availability, facts, or maturity declarations. coh-rtcrejects AI namespace definitions that require dynamic path creation, unconstrained components, directory mutation, prompt/blob-tree storage, or side effects outside generated host-ticket-backed receipt mappings.- Generated snippets refresh
docs/INTERFACES.md,docs/ARCHITECTURE.md, anddocs/USERLAND_AND_CLI.mdso host tools consume authoritative bounds and namespace roots. - Validation and generated docs make the authority mapping explicit: AI namespace writes that trigger external execution are projections over the 28c decision, 28e host-ticket action, and 28f receipt model, not an independent inference endpoint or executor.
- Validation rejects configurations that overload existing
/updates,/models, telemetry, or spool semantics.
Task Breakdown
Title/ID: m30b-ai-ir
Milestone: 30b / generated Python AI namespace contract
Goal: Admit AI namespace surfaces in compiler IR without changing Cohesix transport or runtime boundaries.
Inputs: accepted 28b semantic/capsule schemas, accepted 28c admission schemas,
accepted 28e run/action schemas, accepted 28f inference receipt schemas, tools/coh-rtc,
tools/cohesix-py/cohesix/generated.py, docs/ARCHITECTURE.md,
docs/INTERFACES.md, docs/USERLAND_AND_CLI.md.
Changes:
- tools/coh-rtc/src/ir.rs — `ecosystem.ai.*` schema, gating,
semantic/capsule/run/inference owner-ref mappings, receipt-projection
mapping, content-retention policy, bounded read-only admission projection
mappings, and bounds validation.
- tools/coh-rtc/src/codegen/{docs,rust,cohsh,cohesix_py}.rs — generated AI namespace snippets and Rust, cohsh, and Python client defaults.
Commands:
- cargo test -p coh-rtc
- scripts/check-generated.sh
Checks:
- AI namespace admission is compiler-defined, rejects overlap with existing
semantic/CAS/model/spool and inference endpoint surfaces, and preserves the
28b artifact, 28c decision/grant, 28e host-ticket action, and 28f receipt mappings for
side-effecting flows and read-model projections.
- Generated Python roots, fixed control files, gates, and bounds match the selected resolved manifest and cannot be hand-maintained independently.
Deliverables:
- Authoritative manifest + docs snippets for AI namespace roots.
Title/ID: m30b-ninedoor-ai-providers
Goal: Add bounded NineDoor providers for AI control-plane paths.
Inputs: apps/nine-door, apps/root-task/src/ninedoor.rs, generated manifest outputs.
Changes:
- apps/nine-door/src/host/namespace.rs — host-mode AI namespace providers for tests.
- apps/root-task/src/ninedoor.rs — in-VM AI namespace provider wiring and policy enforcement plus bounded read-only `/proc/admission/status`, `/proc/admission/recent`, `/policy/admission/version`, and existing `/audit/decisions` projections over accepted 28c records.
Commands:
- cargo test -p nine-door
- cargo test -p root-task
Checks:
- Paths enforce append-only/read-only semantics, role filters, deterministic
refusals, fixed generated control files, and documented handoff to
host-ticket-backed actuation where side effects are involved;
semantic/capsule/checkpoint/handoff/prefix/inference read views remain
bounded verified-ref projections only.
- Dynamic create/unlink/rename/chmod/symlink/path-component expansion and prompt/blob-tree storage are refused before any state mutation.
- Admission projections refuse every write and cannot evaluate policy, issue a
grant, append an intent, or create an alternate audit/replay path.
- NineDoor never parses a repository, plans/renders a capsule, speaks a
provider API, retains raw prompt/output content, or executes a
model-produced tool call.
Deliverables:
- AI control-plane namespace available in host and VM implementations with matching semantics.
Title/ID: m30b-host-tool-discovery
Milestone: 30b / Python and host-tool discovery compatibility
Goal: Extend host-tool discovery and read models for AI namespace paths without adding verbs.
Inputs: apps/cohsh, apps/coh, apps/swarmui, tools/cohesix-py/cohesix/{generated.py,backends.py,orchestration.py}, tools/cohesix-py/tests/, coh-rtc-generated enabled/disabled AI namespace profile fixtures and client defaults.
Changes:
- apps/cohsh — existing list/cat/tail/echo flows for `/jobs`, `/datasets`,
`/experiments`, `/infer`, `/metrics`, including immutable
semantic/capsule/render, checkpoint/handoff/prefix-status, and inference
receipt refs; no new verb.
- apps/coh — host-side helpers correlate namespace refs with the existing
28b semantic and 28f inference commands without treating the VM read
model as owner truth.
- apps/swarmui — read-only views backed by existing `/proc` and AI
namespace tails, correlated through the accepted 27f semantic/inference
inspector when available.
- tools/cohesix-py/cohesix/{backends.py,orchestration.py} + tools/cohesix-py/tests/test_ai_namespace.py — consume the coh-rtc-generated enabled/disabled profile fixtures to discover and access only generated `/jobs`, `/datasets`, `/experiments`, `/infer`, and `/metrics` roots and fixed control files through existing bounded backend operations; prove MockBackend as explicit non-proof `host-model` plus filesystem, TCP, and REST missing/disabled/denied/enabled behavior; preserve the 28b owner refs, 28c admission refs, 28e host-ticket actions, and 28f receipt mappings without hand-editing `generated.py`.
Commands:
- cargo test -p cohsh
- python3 -m pytest -q tools/cohesix-py/tests/test_ai_namespace.py
Checks:
- Host tools discover AI paths using existing grammar and deterministic error
handling, with read models aligned to accepted 28b/28e/28f artifacts and
receipts rather than inferred hidden state.
- Python matches coh/cohsh fixtures, cannot create dynamic paths or translate arbitrary data into host execution, and cannot bypass generated dependency, visibility, receipt, or fixed-control-file gates.
Deliverables:
- Operator-facing Rust, UI, and Python tooling parity for AI namespace surfaces.
Title/ID: m30b-ai-regressions
Goal: Add deterministic regression coverage for AI namespace semantics.
Inputs: scripts/cohsh/, tests/fixtures/, docs/TEST_PLAN.md.
Changes:
- scripts/cohsh/ai_namespace_roundtrip.coh — canonical AI namespace script
using existing verbs only, including semantic snapshot/capsule/render refs
and inference admission/receipt refs without raw prompt/output content.
- scripts/cohsh/ai_namespace_scale.coh — representative namespace-scale listing, read, tail, and fixed-control-file write probe for high-churn job/run roots.
- tests/fixtures/transcripts/ — stable transcript fixtures for
gated/missing/enabled AI paths, owner-ref mismatch, wrong visibility,
unavailable capsule/inference dependencies, and raw-content refusal.
Commands:
- cohsh --script scripts/cohsh/ai_namespace_roundtrip.coh
- cohsh --script scripts/cohsh/ai_namespace_scale.coh
Checks:
- Missing paths, denied writes, successful reads/writes, semantic/capsule and
inference receipt refs, and representative high-churn namespace listings
all preserve existing grammar, owner identity, refusal semantics, content
policy, and bounded runtime behavior.
Deliverables:
- Canonical AI namespace regression pack and test-plan coverage.
Milestone 43 — AWS Native Deployment and ENA
Status: Deferred — explicit activation; not part of Release B.
Preserved scope: Retain EC2 Arm64 feasibility/boot-resource mapping, UEFI packaging, isolated ENA, bounded outbound bootstrap/TLS/HTTP/IMDSv2, 9door mounts, AMI tooling and target-qualified recovery/performance. Validate exact platform support and cost before dependent work. Cloud proof, deliberate TCB expansion and boot-media persistence remain separate from Pi/QEMU claims.
Activation and completion: Identify the concrete need, inspect retained implementation/evidence, and specify only the unfulfilled tasks and exact acceptance claims. Preserve the safety constraints below, but reconcile its former-number references and superseded breadth before implementation. No whole-catalogue or later prerequisite is inherited by 28x.
Retained design inventory — former Milestone 31; current owner 43
The following records preserve the previous detailed proposal. Their numeric cross-references use the former-number mapping, and their former status/completion wording is subordinate to the current deferred scope above. They neither reactivate work nor duplicate accepted 28x requirements.
Status: Planned as one complete AWS milestone, including platform bring-up, isolated ENA, outbound bootstrap, bounded TLS/HTTP/IMDSv2 support, 9door mount, AMI tooling, recovery, and performance qualification. No separate funding, demand, or feasibility-only authorization limits its scope. Validate the selected EC2 platform and boot/hardware handoff first as implementation prerequisites; unsupported hardware remains a real blocker, not acceptance.
Why now (native cloud target): Add a native EC2 Arm64 target alongside the Linux-hosted tools and accepted QEMU/Pi control plane. The work includes seL4 platform support, UEFI/ACPI, PCIe, mandatory Nitro ENA, network bootstrap, bounded client TLS/HTTP/IMDSv2, registration, recovery, and performance evidence. No Linux, agents, or general filesystem enters the guest.
An EBS-backed AMI derives from an immutable ESP/kernel/rootserver/manifest snapshot but launches with a persistent root EBS volume. “Diskless” means no Cohesix runtime block service, no volume mounts/writes after firmware handoff, and runtime reconstruction from signed boot/fabric inputs; boot media is neither physically absent nor inherently read-only.
Goal
Boot Cohesix on AWS EC2 (Arm64) via UEFI -> elfloader.efi -> seL4 -> root-task, then bring up ENA networking through a manifest-declared isolated AWS network runtime admitted by root-task and mount the Cohesix 9door namespace over the network with no local filesystem, no Linux, and no virtio.
Milestone 31 first reconciles the generic UEFI ESP/QEMU baseline currently described by the repo with the newer Pi 4 U-Boot path, then adds the AWS-specific delta: AWS profile admission, ENA, outbound bootstrap, manifest-controlled IMDSv2, and AMI registration.
As-built alignment note: UEFI profiles, a shim crate, and
scripts/uefi/* exist; AWS admission, scripts/aws/*, isolated ENA descriptors/
images, outbound 9door mounts, and approved root-task TLS/HTTP/IMDS do not.
Reconcile boot-chain and TCB contracts before depending on them.
The former AWS status placeholder
is archived outside the 1.1.0-beta documentation set. References to
docs/AWS_AMI.md below name a future implementation deliverable; create that
guide with the accepted AWS behavior when this milestone is activated.
Prerequisites
- Milestone 26d completed for the accepted seL4 16 provenance and timer/syscall baseline. Milestone 31 must still create and validate a separate AWS-selected seL4 build; Pi 4 or QEMU artifacts are not AWS boot proof.
- Milestone 28 completed before production AWS assurance claims so generated witnesses, HAL authority checks, and claim-class separation cover the AWS profile.
- Milestone 29a completed before D2 peak-performance work so ENA queue affinity and service-bucket evidence consume the generated core-local scheduling substrate rather than inventing a parallel scheduler.
- Milestone 28d completed before any production profile claims complete ENA runtime-inventory ledger projection or structured quarantine/recovery. Milestone 28d supplies the generic ticket-free driver-ledger and quarantine machinery, not evidence for a future ENA runtime. Milestone 31 must emit new ENA-specific bundle, ledger, fault, teardown, and fresh-generation recovery evidence under that contract. A pre-28d EC2 boot/first-link probe is permitted only as explicitly non-production feasibility evidence.
Non-negotiable constraints
- Start by validating current EC2 Arm64 custom-OS support, AMI registration, UEFI/serial entry, selected seL4 platform support, and the memory, GIC/timer, PCIe and interrupt handoff (ACPI, DT, or documented conversion). Resolve platform gaps before dependent ENA/bootstrap work; feasibility evidence alone cannot close this milestone.
- Milestone 31 may not assume the UEFI/ESP baseline is authoritative until the first AWS task reconciles it against the current Pi 4 U-Boot pivot,
scripts/uefi/esp-build.sh,docs/BOOT_REFERENCE.md,docs/HARDWARE_BRINGUP.md, and the charter rule for UEFI tooling. If the baseline is stale, AWS work starts by refreshing or reintroducing it under this milestone with docs and tests. - AWS boot work must produce a boot-resource map before ENA, TLS/HTTP, IMDS, or outbound fabric code depends on the profile. The map records AMI snapshot/root-volume geometry, ESP contents, kernel/root-task/rootserver artifacts, manifest hash, signed bootstrap manifest, trust anchors, seL4 handoff and ACPI/DT assumptions, attestation evidence, firmware-managed persistent state, and explicit non-claims.
- The AWS diskless profile disables Milestone 29 VM-local persistence and rejects the EC2 root EBS device, ESP, or any other local block device as a spool/settings backend. The immutable AMI snapshot is build provenance; the launched root EBS volume is persistent platform boot media that Cohesix treats as read-only and outside runtime authority.
- Implement bounded client-only TLS/HTTP/IMDSv2 and their manifest controls.
They are a deliberate TCB expansion: document and validate the threat model,
dependency closure, bounds, and disabled behavior in
docs/ARCHITECTURE.md,docs/NETWORK_CONFIG.md,docs/SECURITY.md,docs/SECURITY_NIST_800_53.md, anddocs/AWS_AMI.mdas required milestone work. IMDS remains disabled by default; runtime enablement never bypasses those controls. - AWS VM profiles require dependency-closure evidence before runtime code lands: no
std, libc, POSIX filesystem/process API, DNS resolver, web framework, unapproved TLS/HTTP stack, or host-only ecosystem dependency may enter the root-task or isolated runtime closure. - No listener is introduced in the VM. AWS networking is outbound-only after seL4, and any Secure9P fabric mount must preserve existing frame bounds, role-scoped authority, and deterministic error behavior.
- Cloud adapters, observability, deployment automation, and policy workflows
remain host/fabric-side and reuse
/host/tickets/*and provider evidence. Support signed bootstrap inputs and host/fabric termination as deployment choices alongside the bounded client path, with explicit trust boundaries. - ENA is PCIe/MMIO/DMA-backed physical hardware. Steady ENA admin queue, IO queue, interrupt/poll, RX/TX descriptor, and DMA/cache service must live in a manifest-declared isolated AWS network runtime over the fixed driver-task ABI after HAL admission. Root-task remains the HAL/resource admitter, descriptor publisher, bounded service-turn client, network stack owner, and diagnostics publisher; it must not contain a root-owned steady ENA driver.
- AWS ENA records must extend the existing fixed driver-task ABI without forking a second incompatible contract. A platform-neutral ABI extraction is allowed only with byte-layout/version compatibility tests for existing Pi 4 descriptors, generated migration, and no change to accepted Pi evidence by implication.
- Production ENA profiles must extend the accepted 28d ticket-free manifest-runtime ledger and structured quarantine contract with ENA-specific generation-keyed endpoint, notification, SC/Reply, fault/timeout, queue/ring, PCIe/BAR, IRQ/MSI-X, DMA, and shared-buffer inventory. Prior Pi/storage runtime records prove schema/logic compatibility, not ENA authority or recovery.
- The initial single TX/RX queue polling path is bootstrap evidence only. Peak-performance AWS claims require a later generated multi-queue, MSI-X or equivalent notification, queue-affinity, and core-local service-bucket evidence phase.
Deliverables
A0) Boot-chain / TCB reconciliation and boot-resource map
- Reconcile the current UEFI/ESP builder, Pi 4 U-Boot pivot, selected EC2 instance family, seL4 platform/handoff assumptions, and AWS profile requirements before runtime AWS code lands.
- Prove a bounded EC2 Arm64 feasibility chain before ENA work: register an EBS-backed UEFI AMI, reach a deterministic UEFI/serial marker, identify the selected seL4 platform gap or reach root-task, and capture the ACPI/DT, memory, GIC/timer, PCIe, interrupt, and console inputs the port must consume.
- Produce a boot-resource map covering AMI snapshot/root-volume geometry, ESP layout, elfloader, kernel, root task/rootserver, optional initrd, resolved manifest hash, signed fabric bootstrap manifest, root trust anchors, selected attestation inputs, hardware-description handoff, firmware-managed persistent state, and explicit non-claims.
- Specify and verify the bounded client TLS/HTTP/IMDS and signed-bootstrap/ fabric-termination contracts, including enablement, trust inputs, and failures.
A) AWS compiler + profile admission
- Dedicated AWS Arm64 profile and manifest vocabulary for:
enaas a network backend- ENA queue bounds
- bootstrap retry limits
- signed fabric bootstrap manifest requirements
- IMDSv2 allowlist, enablement, and bounded response sizes
- explicit diskless state that disables
persistence.*and rejects local block backends
B) EFI System Partition integration for AWS
- Reuse the existing deterministic ESP builder as the canonical packager and produce an AWS-consumable EBS root image whose firmware-visible ESP contains:
EFI/BOOT/BOOTAA64.EFI(elfloader EFI)kernel.elfrootserver(root task ELF)- optional
initrd.cpio manifest.jsonandmanifest.sha256- embedded, signed fabric bootstrap manifest (≥2 endpoints, root trust anchors)
C) ENA isolated network runtime (adminq + single TX/RX queue bootstrap)
- ENA PCIe discovery, BAR admission, adminq, completion path, and single TX/RX queue pair run in a manifest-declared isolated AWS network runtime using HAL-declared PCIe/MMIO/DMA/shared-buffer resources.
- ENA command/completion records consume the single fixed driver-task ABI contract; any platform-neutral extraction preserves existing Pi 4 ABI layout/version behavior through explicit compatibility fixtures.
- Root-task owns only generated descriptor publication, bounded ENA service turns, net-stack integration, and diagnostics.
- Minimal polling dataplane with single TX/RX queue pair is accepted only as first-link/bootstrap evidence, not as peak AWS throughput closure.
- Before production promotion, the ENA runtime must publish an owner-milestone, generation-keyed 28d-compatible inventory and pass injected admin/data queue, timeout, interrupt, DMA, and process-fault containment, quarantine, complete teardown, stale-turn refusal, and fresh-generation recovery tests on the selected EC2 profile.
D) Outbound bootstrap core after seL4
- Reuse the Milestone 26b
no_stdDHCP core over the root-task net stack fed by isolated ENA runtime RX/TX service turns - Add bounded outbound TCP connection management
- Add bounded TLS client support only after the AWS security/TCB expansion gate accepts it for the selected profile
- Add a minimal outbound Secure9P/9door mount client
- Diskless bootstrap path after seL4: HAL-admitted isolated ENA runtime -> DHCP (26b core) -> outbound TCP -> approved security/session layer -> 9door mount
D2) AWS ENA performance closure (post-bootstrap)
- Add generated queue-count, queue-affinity, notification/MSI-X or poll-budget policy, burst, and backpressure bounds after first-link smoke passes.
- Map ENA queues into core-local service buckets from Milestone 29a without changing Secure9P, console, or namespace semantics.
- Keep root-task as the serialized authority/net-stack client; isolated runtime owns queue service and DMA/cache maintenance.
- Produce archived EC2 performance evidence for first-link single-queue bootstrap and later multi-queue/notification-backed ENA closure. Benchmark evidence must include instance type, ENA feature set, generated queue policy, service-bucket mapping, request suite, error-budget policy, and hostile-fabric/refusal context. Single-queue polling results are bootstrap/link evidence only and cannot be promoted to peak-performance claims.
E) Manifest-controlled IMDSv2 bootstrap
- Implement and test bounded IMDSv2 identity/config bootstrap. Keep it disabled by default, with signed manifest bootstrap available without metadata access.
- No listeners; no background refresh loop
F) AMI registration tooling
- AWS scripts for ESP image registration and smoke tests for Arm64 (
uefi/uefi-preferred) - Documentation in
docs/AWS_AMI.mdcovering boot path, failure modes, and recovery - Dependency-closure and hostile-fabric evidence for every AWS-enabled VM profile before production claims.
Commands
cmake --build "$SEL4_BUILD_DIR" --target rootserver_imagescripts/uefi/esp-build.sh --manifest configs/generated/root_task_resolved.json --sel4-build-dir "$SEL4_BUILD_DIR"scripts/aws/platform-feasibility.sh --state-dir out/aws/m31-platform-feasibilityscripts/aws/build-esp.shscripts/aws/register-ami.shscripts/aws/launch-smoke.shscripts/aws/ena-bench.sh --mode bootstrap --state-dir out/bench/m31-ena-bootstrapscripts/aws/ena-bench.sh --mode peak --state-dir out/bench/m31-ena-peakcargo test -p root-task --test ena_fault_recoverycargo tree -p root-task --target aarch64-unknown-none --no-default-featurescargo deny check bans
Checks (DoD)
- EC2 instance boots directly into Cohesix with no intermediate OS.
- EC2 Arm64 feasibility evidence identifies the supported instance family, AMI registration path, UEFI/serial result, selected seL4 platform status, and authoritative ACPI/DT hardware-description path before ENA runtime work is accepted.
- Boot-chain reconciliation and the boot-resource map are complete before AWS runtime code cites UEFI, TLS/HTTP, IMDS, ENA, or outbound fabric assumptions.
- AWS dependency-closure gate proves the VM profile remains
no_stdand excludes libc, POSIX filesystem/process APIs, DNS resolver, web framework, and unapproved TLS/HTTP dependencies. - ENA link comes up deterministically; DHCP lease acquired within bounded time.
- ENA hardware service must use a manifest-declared isolated ENA runtime; root-task direct ENA MMIO/DMA paths fail profile validation outside explicitly named QEMU/host compatibility tests.
- ENA runtime records use the fixed shared driver-task ABI, and any platform-neutral extraction proves existing Pi 4 descriptor layout/version compatibility.
- A production ENA profile has new target-specific 28d-compatible manifest-runtime ledger and structured fault/quarantine evidence; no Pi 4, storage-runtime, schema-only, or bootstrap-link record can substitute for the exact ENA generation and EC2 target.
- ENA fault recovery revokes BAR/MMIO, IRQ/MSI-X, DMA/shared-buffer, queue/ring, endpoint, notification, SC/Reply, and timeout/fault authority, rejects stale completions and service turns, and requires fresh generated admission before network service resumes.
- 9door namespace mounts successfully and control plane is reachable.
- Single-queue polling evidence is classified as bootstrap/link proof. Peak AWS performance claims require the D2 multi-queue/core-local evidence lane.
- ENA benchmark artifacts are archived for bootstrap and multi-queue or notification-backed service-bucket runs. EC2 results are compared against the latest accepted rolling benchmark baseline only for capacity/context; AWS target evidence is its own lane and must not overwrite Pi/QEMU proof.
- IMDSv2 is implemented and tested enabled and disabled. Absence, timeout, or denial preserves safe boot with deterministic diagnostics and bounded retries.
- TLS/HTTP proof shows it remains client-only and non-persistent: no listener, no background refresh loop, bounded trust-anchor/cert storage from signed manifest inputs, bounded handshake/input parsing, and deterministic boot behavior when fabric, TLS, or IMDS is unavailable.
- Cohesix never mounts or writes the root EBS volume after boot handoff, the AWS profile exposes no Milestone 29 persistence backend, and reboot/stop-start restores runtime state only from signed inputs. Any firmware-managed UEFI-variable persistence is inventoried separately and cannot be described as Cohesix control-plane persistence.
- Failure cases (no fabric, hostile fabric, forged remote manifest, auth failure, ticket widening attempt, Secure9P-bound relaxation attempt, replay, malformed frame, link down) fail terminally or refuse boundedly with explicit console diagnostics, no local policy mutation, no widened authority, and no partial trust state.
- AWS security docs record the accepted posture for any root-task TLS/HTTP code, or explicitly state that TLS/HTTP termination remains outside the VM.
Compiler touchpoints
coh-rtcemits:- AWS profile / backend admission for
ena - boot-resource map schema, AMI/root-volume geometry, artifact hashes, hardware-description handoff, signed-bootstrap manifest references, trust-anchor references, selected attestation inputs, firmware-state inventory, and generated non-claim summaries for AWS profiles.
- isolated ENA runtime descriptors, ENA queue bounds, bootstrap retry limits, and later multi-queue/core-local performance gates.
- ENA-specific extensions to the accepted 28d ticket-free driver manifest-runtime ledger, structured quarantine policy, bounded fault evidence, and fresh-generation recovery gates.
- explicit diskless-profile validation that disables
persistence.*and rejects the root EBS/ESP or other local block devices as runtime persistence backends. - the single fixed driver-task ABI version and any generated AWS extension records, with compatibility evidence for existing Pi 4 descriptors.
- Fabric bootstrap manifest schema and signature requirements.
- dependency-closure allow/deny lists for AWS VM profile crates.
- IMDSv2 allowlist, max response bytes, and retry bounds and disabled-by-default policy.
- AWS profile / backend admission for
- Regeneration guard verifies EFI binary hash against recorded compiler output.
Task Breakdown
Title/ID: m31-uefi-and-tcb-reconciliation
Goal: Reconcile AWS platform, boot, and security assumptions with the current Cohesix UEFI baseline and tiny-TCB networking posture before runtime work starts.
Inputs: scripts/uefi/esp-build.sh, docs/BOOT_REFERENCE.md, docs/HARDWARE_BRINGUP.md, docs/NETWORK_CONFIG.md, docs/SECURITY.md, docs/SECURITY_NIST_800_53.md, docs/AWS_AMI.md, AGENTS.md.
Changes:
- docs/AWS_AMI.md — state the selected EC2 Arm64/custom-OS support posture, accepted AWS boot chain, whether the UEFI/ESP builder is current, the boot-resource map fields, EBS root-volume truth, hardware-description handoff, and what evidence proves them.
- docs/NETWORK_CONFIG.md + docs/SECURITY.md + docs/SECURITY_NIST_800_53.md — define and verify the bounded client TLS/HTTP/IMDS threat model and signed-bootstrap/fabric-termination contracts.
- docs/BUILD_PLAN.md — keep Milestone 31 subtasks synchronized with the accepted TCB posture.
Commands:
- scripts/uefi/esp-build.sh --help
- scripts/ci/check_test_plan.sh
Checks:
- AWS work has an explicit platform-support decision, boot-chain baseline, boot-resource map, hardware-description path, and documented and validated TLS/HTTP/IMDS contract before ENA bootstrap code depends on those assumptions.
Deliverables:
- EC2 platform/UEFI and AWS TCB reconciliation note, including a boot-resource map, that blocks unsupported platform assumptions and accidental import of web/TLS stacks into the VM.
Title/ID: m31-uefi-esp
Goal: Validate or refresh the deterministic ESP builder and selected seL4 UEFI build before EC2 feasibility work.
Inputs: upstream elfloader EFI build, selected `SEL4_BUILD_DIR`, `scripts/uefi/esp-build.sh`, manifest outputs, accepted m30 UEFI/TCB reconciliation.
Changes:
- scripts/uefi/esp-build.sh — remain the canonical ESP builder for Cohesix only if `m31-uefi-and-tcb-reconciliation` accepts it as current; otherwise refresh or replace it under the same documented contract.
- scripts/aws/build-esp.sh — thin AWS wrapper producing an AMI-ready EBS root/ESP image from the canonical builder output.
Commands:
- cmake --build "$SEL4_BUILD_DIR" --target rootserver_image
- scripts/uefi/esp-build.sh --manifest configs/generated/root_task_resolved.json --sel4-build-dir "$SEL4_BUILD_DIR"
Checks:
- The selected build directory supplies the UEFI elfloader, kernel, and embedded rootserver truth; the ESP reaches the deterministic UEFI/root-task marker required by the platform-feasibility probe.
Deliverables:
- Documented ESP layout and build recipe for the selected Arm64 UEFI profile.
Title/ID: m31-ec2-arm64-platform-feasibility
Goal: Prove the selected EC2 Arm64 family can launch a custom Cohesix UEFI/seL4 payload and expose the platform inputs required before ENA implementation.
Inputs: accepted m30 UEFI/TCB reconciliation, selected `SEL4_BUILD_DIR`, scripts/uefi/esp-build.sh, AWS account/region/instance-family test profile, docs/AWS_AMI.md.
Changes:
- scripts/aws/platform-feasibility.sh — register a disposable EBS-backed Arm64 UEFI probe image, launch the selected instance family, capture console/serial and lifecycle evidence, and clean up bounded test resources.
- docs/audit/M30_EC2_PLATFORM_FEASIBILITY.md — record AMI registration, UEFI marker, seL4/root-task reachability or exact platform blocker, ACPI/DT handoff, GIC/timer, memory, PCIe/interrupt, console, root-volume, and unsupported-feature evidence.
- docs/AWS_AMI.md — classify the selected family as supported for further implementation, experimental with a named blocker, or unsupported.
Commands:
- scripts/aws/platform-feasibility.sh --state-dir out/aws/m31-platform-feasibility
Checks:
- AMI registration and UEFI entry are proven on the named instance family, and the selected seL4 platform either reaches root-task or has a bounded, explicit porting task before ENA work.
- The evidence identifies the authoritative ACPI/DT and PCIe/interrupt discovery path; QEMU `virt` addresses or Pi DT assumptions are not reused implicitly.
Deliverables:
- Go/no-go EC2 Arm64 platform evidence that gates every later AWS runtime task.
Title/ID: m31-aws-profile
Goal: Admit AWS/ENA/IMDS bootstrap in compiler IR and profile selection before runtime implementation.
Inputs: tools/coh-rtc, configs/, docs/AWS_AMI.md.
Changes:
- tools/coh-rtc/src/ir.rs — AWS profile, selected hardware-description path, `ena` backend, isolated ENA runtime descriptor schema, bounded bootstrap schema, explicit diskless/no-persistence state, and later performance-gate fields.
- tools/coh-rtc/src/codegen/{docs,rust}.rs — generated AWS/profile snippets and dependency allow/deny policy summaries.
Commands:
- cargo test -p coh-rtc
Checks:
- Runtime code can consume authoritative AWS/ENA/IMDS limits from generated outputs, and physical AWS profiles cannot enable root-owned ENA MMIO/DMA paths.
- AWS profiles cannot enable TLS/HTTP/IMDS/fabric support without matching TCB posture and dependency-closure gates.
- AWS diskless profiles reject `persistence.*`, the root EBS/ESP, and all local block backends as runtime spool/settings storage.
Deliverables:
- Compiler-defined AWS admission with docs snippets updated.
Title/ID: m31-vm-dependency-closure
Goal: Prove AWS VM profiles do not import unapproved host, POSIX, web, or TLS/HTTP dependencies into root-task or isolated runtimes.
Inputs: Cargo.toml workspace metadata, apps/root-task, apps/aws-driver-runtime, tools/coh-rtc, deny configuration, docs/AWS_AMI.md.
Changes:
- tools/coh-rtc/src/validate.rs — generated AWS dependency allow/deny policy for selected VM profiles.
- scripts/ci/aws_dependency_closure.sh — target-qualified `cargo tree`/deny check for root-task and isolated AWS runtime closure.
- docs/AWS_AMI.md + docs/SECURITY.md — accepted dependency posture and approved exceptions, if any.
Commands:
- scripts/ci/aws_dependency_closure.sh
- cargo tree -p root-task --target aarch64-unknown-none --no-default-features
- cargo deny check bans
Checks:
- `std`, libc, POSIX filesystem/process APIs, DNS resolver crates, web frameworks, host-only ecosystem crates, and unapproved TLS/HTTP dependencies are absent from AWS VM artifacts.
Deliverables:
- Reproducible AWS VM dependency-closure evidence before runtime code can cite TLS/HTTP/IMDS or outbound fabric support.
Title/ID: m31-shared-driver-task-abi
Goal: Extend one fixed driver-task ABI for AWS without cloning or silently changing the accepted Pi 4 contract.
Inputs: crates/pi4-driver-abi, apps/pi4-driver-runtime, apps/root-task/src/hal/driver_task.rs, tools/coh-rtc, accepted Pi 4 ABI fixtures and proof evidence.
Changes:
- crates/driver-task-abi/src/** — extract only platform-neutral versioned headers, resource descriptors, command/completion framing, and proof fields needed by both Pi 4 and AWS runtimes.
- crates/pi4-driver-abi/src/** — consume or re-export the shared records while preserving existing Pi 4 wire layout, version behavior, and profile-generated descriptors.
- tools/coh-rtc/src/** — emit one ABI version/family plus platform-specific extension records; reject conflicting Pi/AWS layouts.
- tests/fixtures/driver_task_abi/** — byte-layout, version, bounds, and old-Pi-fixture compatibility tests.
Commands:
- cargo test -p driver-task-abi
- cargo test -p pi4-driver-abi
- cargo test -p pi4-driver-runtime
- scripts/check-generated.sh
Checks:
- Existing Pi 4 descriptors and accepted fixtures remain byte-compatible, AWS extensions are versioned and bounded, and no second incompatible ring/service-turn contract is introduced.
Deliverables:
- One compiler-declared fixed driver-task ABI family ready for isolated ENA records.
Title/ID: m31-ena-runtime-adminq
Goal: Implement ENA PCIe discovery and admin queue in a manifest-declared isolated AWS network runtime.
Inputs: accepted m30 platform-feasibility evidence, apps/root-task HAL admission, m30 shared driver-task ABI, apps/aws-driver-runtime, docs/AWS_AMI.md.
Changes:
- apps/root-task/src/hal/aws_ena.rs — HAL admission for ENA PCIe BARs, IRQ/notification policy, DMA/shared-buffer descriptors, and runtime image selection.
- crates/driver-task-abi/src/** — fixed-layout ENA init/adminq command records and completion evidence, preserving compatibility with the Pi 4 driver-task ABI shape.
- apps/aws-driver-runtime/src/** — isolated ENA runtime adminq and completion queue service.
- apps/root-task/src/net/ena.rs — root-side ENA ring-client/net-stack wiring only.
Commands:
- cargo test -p root-task --test ena_adminq
- cargo test -p driver-task-abi
- cargo test -p aws-driver-runtime
Checks:
- Feature negotiation succeeds with minimal feature set.
- ENA BAR/MMIO/DMA access occurs only in the isolated runtime after HAL admission; root-task remains a bounded client.
- ENA records use the generated shared ABI version and cannot alter existing Pi descriptor layout or evidence classification.
Deliverables:
- AdminQ protocol notes in docs/AWS_AMI.md.
Title/ID: m31-ena-runtime-io-bootstrap
Goal: Bring up minimal isolated runtime ENA dataplane for first-link bootstrap.
Inputs: manifest-declared isolated AWS network runtime, root-task net stack abstractions, generated ENA descriptors.
Changes:
- apps/aws-driver-runtime/src/** — single TX/RX SQ + CQ and polling dataplane service turns.
- crates/driver-task-abi/src/** — fixed-layout RX/TX descriptor service records, queue bounds, and completion counters.
- apps/root-task/src/net/mod.rs — integrate isolated ENA runtime RX/TX service into the root-task net stack.
Commands:
- cargo test -p root-task --test ena_ioq
- cargo test -p driver-task-abi
- cargo test -p aws-driver-runtime
Checks:
- TX reclaim and RX refill invariants hold under sustained traffic, root-owned ENA dataplane paths are absent from physical AWS profiles, and single-queue polling evidence is labeled bootstrap-only.
Deliverables:
- Deterministic dataplane invariants documented.
Title/ID: m31-ena-production-ledger-and-recovery
Milestone: 31 / ENA production ledger and structured recovery
Goal: Bind the new ENA runtime to the accepted ticket-free production driver ledger and prove target-specific quarantine, teardown, and fresh-generation recovery.
Inputs: accepted Milestone 28d driver-ledger/quarantine schemas and implementation, m30 ENA admin/data queue runtime, selected AWS profile and EC2 target evidence, apps/root-task/src/hal/**, apps/root-task/src/event/**, apps/aws-driver-runtime, tools/coh-rtc, docs/AWS_AMI.md, docs/TEST_PLAN.md.
Changes:
- tools/coh-rtc/src/** — emit ENA owner-milestone and manifest-runtime identity plus generation-keyed endpoint, notification, SC/Reply, fault/timeout, queue/ring, PCIe/BAR, IRQ/MSI-X, DMA, shared-buffer, quarantine, and recovery records under the accepted 28d ticket-free driver schema.
- apps/root-task/src/hal/aws_ena.rs + apps/root-task/src/event/** — attach each admitted ENA bundle to the manifest-runtime ledger, invoke the accepted containment/teardown path on construction, admin/data queue, timeout, interrupt, DMA, and process faults, and reject all old-generation completions or service turns.
- apps/aws-driver-runtime/src/** — preserve the fixed driver-task ABI while exposing only the bounded generation/fault evidence needed by root-owned ledger validation; no driver ticket, SchedControl, or recovery authority enters the runtime.
- apps/root-task/tests/ena_fault_recovery.rs + EC2 fault-injection lane — cover faults at every admitted resource and queue phase, complete BAR/MMIO/IRQ/DMA/ring/cap teardown, quarantine evidence, stale-generation refusal, and fresh generated readmission.
- configs/test_plan_actions.toml + scripts/ci/test_plan_run.sh — add the bounded
AWS ENA ledger/recovery stage and target selector with explicit account,
region, instance-family, cleanup, and archived-evidence requirements.
- docs/AWS_AMI.md + docs/SECURITY.md + docs/TEST_PLAN.md — distinguish generic 28d machinery, ENA-specific target evidence, bootstrap-only link proof, and production recovery claims.
Commands:
- cargo test -p root-task --test ena_fault_recovery
- cargo test -p aws-driver-runtime
- cargo test -p coh-rtc
- scripts/check-generated.sh
- scripts/ci/test_plan_run.sh --target aws --state-dir out/test-plan/m31-ena-ledger-recovery
Checks:
- A production AWS profile cannot enable ENA without exactly one live generation-keyed manifest-runtime ledger entry and matching EC2 evidence for every admitted ENA bundle.
- Quarantine removes all ENA endpoint/notification/SC/Reply/fault/timeout/queue/ring/BAR/MMIO/IRQ/MSI-X/DMA/shared authority, stale work fails deterministically, and recovery requires a fresh generated runtime generation.
- Existing Pi 4 and Milestone 29 storage-runtime records prove only shared schema/logic compatibility and cannot satisfy ENA target authority, fault, or recovery evidence.
Deliverables:
- ENA-specific production ledger and structured recovery evidence over the accepted 28d machinery.
Title/ID: m31-ena-performance-closure
Goal: Add peak-performance AWS ENA evidence after first-link bootstrap without changing the authority model.
Inputs: accepted m30 ENA production-ledger/recovery evidence, generated ENA queue policy, Milestone 29a service-bucket outputs, manifest-declared isolated AWS network runtime, docs/BENCHMARKS.md, docs/AWS_AMI.md.
Changes:
- tools/coh-rtc/src/ir.rs — generated ENA queue-count, queue-affinity, notification/MSI-X or poll-budget, burst, and backpressure limits.
- apps/aws-driver-runtime/src/** — bounded multi-queue service turns and queue-local counters where the platform profile admits them.
- apps/root-task/src/net/ena.rs — deterministic merge/backpressure handling for isolated runtime queue completions.
- scripts/aws/ena-bench.sh — archived EC2 benchmark runner for bootstrap and peak ENA lanes, including target metadata, queue policy, service-bucket evidence, and error-budget summary.
- docs/BENCHMARKS.md + docs/AWS_AMI.md — classify bootstrap link proof separately from peak-throughput proof.
Commands:
- cargo test -p coh-rtc
- cargo test -p root-task --test ena_ioq
- cargo test -p aws-driver-runtime
- scripts/aws/ena-bench.sh --mode bootstrap --state-dir out/bench/m31-ena-bootstrap
- scripts/aws/ena-bench.sh --mode peak --state-dir out/bench/m31-ena-peak
Checks:
- Multi-queue or notification-backed claims cite generated bounds and archived EC2 evidence; single-queue polling cannot be described as peak performance.
- Benchmark artifacts preserve target metadata, generated queue policy, service-bucket counters, error-budget results, and hostile-fabric/refusal context; AWS performance is recorded as a target-specific lane, not substituted for Pi/QEMU evidence.
Deliverables:
- AWS ENA performance lane aligned to Cohesix service-bucket proof rather than root-owned driver shortcuts.
Title/ID: m31-outbound-bootstrap-core
Goal: Add bounded outbound TCP/session primitives and only the approved security primitive required before fabric mount.
Inputs: apps/root-task net stack, approved TLS or fabric-termination helpers, docs/AWS_AMI.md.
Changes:
- apps/root-task/src/net/dhcp.rs — adapt/reuse Milestone 26b DHCP core for ENA link and AWS-specific bounds.
- apps/root-task/src/net/tcp.rs — outbound TCP session support for long-lived sessions.
- apps/root-task/src/net/tls.rs — bounded fabric-auth TLS client handshake; also wire the documented signed-bootstrap/host-fabric termination profile.
- apps/root-task/src/net/bootstrap.rs — deterministic sequencing and retries.
Commands:
- cargo test -p root-task --test net_bootstrap
Checks:
- Network reaches "fabric-ready" state within defined bounds.
- TLS/HTTP is client-only, non-persistent, bounded, and deterministic when fabric/TLS/IMDS is unavailable; no listener or background refresh loop is introduced.
Deliverables:
- Bootstrap timing guarantees recorded.
Title/ID: m31-imdsv2-bootstrap
Goal: Implement bounded, manifest-controlled IMDSv2 metadata reads for boot policy.
Inputs: apps/root-task net stack, docs/AWS_AMI.md.
Changes:
- apps/root-task/src/net/http.rs — bounded client HTTP request/response parsing, with no chunked encoding.
- apps/root-task/src/net/imdsv2.rs — token fetch + allowlisted metadata queries, disabled by default and profile-gated.
- apps/root-task/src/boot/policy.rs — consume optional IMDS fields (instance-id, region, az, tags if enabled).
Commands:
- cargo test -p root-task --test imdsv2
Checks:
- Enabled and disabled IMDSv2 profiles pass; absence, timeout, or denial preserves safe boot with deterministic diagnostics.
Deliverables:
- IMDSv2 bootstrap flow documented with explicit bounds and allowlist.
Title/ID: m31-fabric-mount
Goal: Mount 9door namespace and enter steady state (post-seL4).
Inputs: root-task net stack, Secure9P client, docs/AWS_AMI.md.
Changes:
- apps/root-task/src/net/door9p_client.rs — minimal 9P client for fabric mounts.
- apps/root-task/src/net/bootstrap.rs — signed manifest verification.
- apps/root-task/src/net/mount.rs — mount orchestration and error handling.
Commands:
- cargo test -p root-task --test fabric_mount
Checks:
- Namespace mount preserves Secure9P frame/path/fid/ticket bounds and read/write semantics.
- Hostile fabric, forged manifest, auth failure, ticket widening, Secure9P-bound relaxation, replay, and malformed-frame cases are terminal or bounded refusals that leave no local policy mutation, widened authority, or partial trust state.
Deliverables:
- Fabric bootstrap flow documented.
Title/ID: m31-ami-pipeline
Goal: Produce and validate AWS AMI.
Inputs: scripts/aws/, docs/AWS_AMI.md.
Changes:
- scripts/aws/build-esp.sh — ESP image creation.
- scripts/aws/register-ami.sh — snapshot + AMI registration.
- scripts/aws/launch-smoke.sh — EC2 smoke test.
Commands:
- scripts/aws/register-ami.sh
Checks:
- AMI launches on supported Nitro instance family and passes smoke test.
Deliverables:
- Reproducible AMI build pipeline.
Docs-as-Built Alignment (applies to Milestone 8 onward)
To prevent drift:
- Docs → IR → Code
- Any new behaviour MUST land as IR fields with validation and codegen.
- Build fails if IR references disabled gates, violates Secure9P bounds, or forces
stdwhere the runtime isno_std.
- Autogenerated Snippets
coh-rtcrefreshes embedded snippets inSECURE9P.md,INTERFACES.md, andARCHITECTURE.md(CBOR schema,/proctree, concurrency knobs, hardware tables) during release prep.
- As-Built Guard
- Script compares generated file hashes, manifest fingerprints, and doc excerpts against committed versions. Drift fails CI and blocks release notes.
- Rule: Documentation must describe the system “as built” (post-codegen), not only “as intended”.
- Red Lines
- Enforced in the compiler and restated here: 9P2000.L,
msize ≤ 8192, walk depth ≤ 8, no.., no fid reuse after clunk, no in-VM TCP listeners except the authenticated root-task console, CPIO < 4 MiB, no POSIX façade, maintainno_stdfor VM artefacts.
- Enforced in the compiler and restated here: 9P2000.L,
- Regression Pack (post–Milestone 7c)
- From Milestone 8 onward,
docs/TEST_PLAN.mdand the declarative test catalog determine development convergence and applicable acceptance closure. Non-claiming convergence may precede the shared regression pack, but never satisfies or replaces final staged acceptance. - Note:
.cohscripts live inscripts/cohsh/and followdocs/USERLAND_AND_CLI.md. - The regression pack includes at minimum:
tests/integration/qemu_tcp_console.rs(Milestone 7 TCP console flow).scripts/cohsh/boot_v0.coh(baseline help/attach/log/quit script from the manifest compiler).tests/cli/tracefs_script.sh(TraceFS JSONL flows).scripts/cohsh/9p_batch.coh(Secure9P batching).scripts/cohsh/telemetry_ring.coh(telemetry rings & cursor resumption).scripts/cohsh/observe_watch.coh(observability/procgrammar).scripts/cohsh/cas_roundtrip.coh(CAS update round-trip).
- CI for each Milestone ≥ 8 must:
- Run the applicable canonical regression pack and fail on unexplained output drift (including ACK/ERR/END lines,
/procgrammars, and telemetry formats). - Only permit intentional behaviour changes when the relevant CLI scripts, doc snippets, and manifest fields are updated in the same change.
- Run the applicable canonical regression pack and fail on unexplained output drift (including ACK/ERR/END lines,
- Canonical protocol/as-built fixtures remain authoritative unless their
governing contract intentionally changes. Tests may be added, simplified,
consolidated, replaced, or removed under
AGENTS.mdTest Discipline; test count is not a compatibility guarantee.
- From Milestone 8 onward,
- Cross-Milestone Stability Rules
- Changes to console ACK/ERR/END grammar, NineDoor error codes, or
/procnode formats MUST be treated as breaking changes and require:- (a) matching updates to all CLI fixtures under
scripts/cohsh/*, - (b) regeneration of manifest-derived snippets,
- (c) explicit doc updates in
INTERFACES.md, and - (d) a version bump of the manifest schema.
- (a) matching updates to all CLI fixtures under
- Milestones ≥ 9 MUST NOT introduce new 9P verbs or extend grammars unless routed through the manifest compiler and validated by IR red lines.
- Networking cadence and event-pump tick pacing MUST NOT shift across milestones unless the change is documented in
SECURITY.mdwith updated bounds.
- Changes to console ACK/ERR/END grammar, NineDoor error codes, or