Rust Flight Framework

This repository is an experiment in building a small, Rust-native framework for host-based flight-software research. It studies responsibilities also addressed by NASA's Core Flight System (cFS), while independently choosing designs that fit Rust's ownership, type, error, and testing models.

Safety and affiliation notice: This project is not flight-qualified, safety-certified, a NASA product, or NASA-endorsed. It has no demonstrated Technology Readiness Level and is not suitable for operational spacecraft, safety-critical systems, or human-rated systems. It does not claim automatic compatibility with cFS, cFE, OSAL, PSP, CCSDS, or any RTOS.

Current status

The experimental serial host v0.1 milestone is accepted by the 2026-10-09 Codex review, including scope entry points, resource/failure contracts, and architecture. This completes Stage 4 for the recorded host target. The package stays unpublished at 0.0.0; APIs remain provisional and consequential release/scope gates remain separate.

The repository contains an initial research and architecture baseline, five bounded Rust lifecycle/work increments, three Stage 2 messaging increments, two structured-event increments, an injected manual-time increment, and a finite scheduled-work increment, plus standalone and runtime-integrated configuration lifecycle increments. A no-dependency LifecycleRegistry verifies the logical LC1 transition table. A finite-capacity Runtime owns statically composed application values and executes start, caller-selected work, stop, and in-place restart synchronously. Successful lifecycle operations enter Running, Stopped, and Running; successful work retains Running. Restart and work retain application-owned state, while a returned concrete operation error enters terminal Failed without mutating peer records. The lifecycle construction review adds exact capacity-overflow diagnostics for both the standalone registry and unconfigured owned runtime constructors. Those impossible-capacity tests do not claim actual allocator exhaustion or whole-process memory bounds. The checkpoint at 15e4166bbead2d824e732460fa1a67266386f648 has successful hosted CI for 124 workspace tests, both focused host targets, and the sample executable. The application identity scope review now executes the distinct caller-discipline boundary: equal-position keys from separate owners compare equal and select the corresponding local record. They do not carry issuer provenance, and callers must not mix them across owners. Checkpoint 9ea7f48f827031fcbeb63f712c97dfbe14cc629c has successful hosted CI for 126 workspace tests and the configured host/sample evidence.

The standalone MessageBus uses mission-selected topics and inline const-bounded payloads. It copies immutable positive-capacity inbox topology, preserves FIFO order across topics, applies reject-newest saturation, continues fan-out to unaffected subscribers, and returns stable ordered outcomes. The detached-message identity review executes its caller-scoped boundary: a same-position foreign key passes registration-order validation and addresses the configured inbox because the key carries no issuer provenance. This is not permission to mix identities. Checkpoint f6786d0ada7812bc10b2d7aec03a0f4b8f48b4b3 has successful hosted CI for 127 workspace tests and the configured host/sample evidence. The owning MessagingRuntime now consumes a fully composed still-registered runtime, constructs exactly one fresh inbox per application, derives delivery availability from lifecycle state, clears queues after successful stop or a returned callback error with an exact discarded-delivery count, and reconnects an empty inbox after successful restart. A separate MessagingApplication callback now receives one oldest in-flight delivery plus a publish-only context. It can self-publish through the same bounded bus without gaining lifecycle, dequeue, or nested-dispatch access. Routing-core, runtime-messaging, and message-dispatch tests cover these boundaries; the dispatch availability review extends callback publication through a peer's running, stopped, and restarted states. The stopped snapshot must be refreshed before the next publisher callback; only its new reply reaches the reconnected peer inbox. Checkpoint 44709878005d8b91df8411f9e2ccc8179d21ddde has successful hosted CI for the strengthened regression, 141 workspace tests, and configured host/sample evidence. Production behavior and public APIs remain unchanged. The returned-message failure review records the complete retained peer FIFO and post-failure availability boundary. The returned-stop failure review adds the corresponding stop-specific scenario: exact full-inbox clearing, terminal callback suppression, retained peer FIFO dispatch, and later peer work. Its verification record distinguishes cooperative queue cleanup from application-internal cleanup or recovery. The copied topology review adds caller-storage mutation and destruction regressions through both public constructors. Original capacities and routing remain intact; the standalone test consumes the exact retained FIFO and the runtime test preserves lifecycle availability, saturation, stop clearing, and restart reconnection. Plain-enum topic copying does not establish deep isolation of arbitrary shared referents. Checkpoint ab9914618a739d4b7c8a46f0e14d7e12c55b6649 has successful hosted CI for both regressions, 137 workspace tests, and configured host/sample evidence. The inline payload review adds source-vector overwrite and destruction observations for empty, short, and exact-limit messages. Standalone fan-out retains exact FIFO values after publisher binding replacement and scope exit; consuming and replacing one returned message preserves its peer's queued copies. This supplements the existing inline-copy contract without adding runtime-specific dispatch claims. Checkpoint 97e590f25d8a9845bb40452a50741639beea3999 has successful hosted CI for both new regressions, 139 workspace tests, and configured host/sample evidence. The messaging-construction diagnostics review also executes the nested standard source chain for a later-inbox capacity overflow while retaining the existing returned-runtime recovery path. This is diagnostic evidence for one deterministic constructor failure, not allocator- exhaustion injection or automatic recovery. Checkpoint 70beaedd8c315baeea3e399bb6a7cbf0a8ded9a9 has successful hosted CI for the strengthened regression and configured host/sample evidence.

A standalone EventQueue<EventId> stores typed source, severity, mission-defined copied identifier, and explicit elapsed EventTimestamp values. It pre-reserves a positive record limit, preserves emission-order FIFO, rejects the newest event at saturation with a caller-visible outcome, and frees one slot on dequeue. Eight public tests cover its fields, exact reservation-error diagnostics, storage boundary, and repeated saturation/reuse; the event-queue review records their resource and failure limits. The event-record ownership review adds exact FIFO after producer binding replacement and retained full metadata after slot reuse and destruction of a nonempty queue. Plain enum identifiers do not establish deep isolation of arbitrary copied referents. EventTimestamp can now capture an injected Clock reading. The manually advanced implementation starts at zero by default or at one explicit controlled instant, changes only on explicit nonnegative advances, and rejects representational overflow without mutation. Five public tests prove zero and repeated reads, cumulative and replayed traces, typed overflow, object-safe injection, and event timestamp capture.

Runtime::work_with_failure_event now composes those boundaries for one opt-in direct work operation. Success and lifecycle rejection read no clock and emit nothing. After an application returns a work error and its record enters terminal Failed, the operation reads the injected clock once and attempts one application-sourced error event. Its returned error retains the complete RuntimeWorkError, exact event, and Recorded or QueueFull outcome. A full queue preserves its older event and returns the rejected event for explicit retry while leaving a healthy peer operable for later work. Five public tests cover exact fields, the error-source chain, single emission, lifecycle suppression, saturation, retry, and peer progress. Runtime still does not permanently own the clock or event queue.

MessagingRuntime::work_with_failure_event adds the same opt-in reporting to ordinary work under the inbox owner. It delegates to MessagingRuntime::work first, so terminal failure and exact selected-inbox clearing finish before the single clock read and event attempt. The existing MessagingOperationError retains the discard count around the existing RuntimeWorkEventError; success and lifecycle rejection emit nothing. Direct and messaging-owned operations share event construction while preserving separate ownership responsibilities. The failure-event identity review executes both owners' caller-scoped attribution boundary: a same-position key from another live owner fails the receiving local application and is copied into its event while the foreign owner remains unchanged. Five direct and seven messaging-owned tests cover the event paths. This does not authorize cross- owner key mixing or add events to message dispatch or scheduled work. The checkpoint has successful hosted CI for both regressions and the configured host/sample evidence.

A WorkSchedule copies a finite agenda of one-shot application work items in nondecreasing elapsed-time order. Runtime::run_next_scheduled_work reads an injected clock once while an item remains, waits without mutation before its instant, and consumes at most one due or overdue item per caller request. Equal- time items retain configuration order. Success returns the lifecycle state; lifecycle rejection or a returned work error preserves the exact runtime error and consumes only the attempted item so a due peer can still progress. Ten public tests cover order validation, exact clock-read counts, inclusive and overdue work, lifecycle/error handling, and replay-equivalent work, lifecycle, and structured-event timestamp traces under manual time.

MessagingRuntime::run_next_scheduled_work uses that same private timing and consumption decision, then delegates through messaging-owned ordinary work. The existing nested errors retain the item, observed instant, original work error, and exact discarded-delivery count. Failure clears only the selected inbox; later due peers can still work and dispatch their retained messages. This operation leaves successful inboxes intact and emits no failure event. The scheduled-work identity review executes the remaining caller-discipline boundary through both owners: a due same-position key from another runtime invokes the receiving owner's local application. The foreign owner remains unchanged, and successful messaging- owned work preserves the receiving inboxes. This does not authorize mixing identities or clock domains. Checkpoint 9f3aac6947943c3f9affbe38383e5e4ad09f382d has successful hosted CI for both regressions and the configured host/sample evidence. The clock-origin scope review executes the companion time boundary through both scheduling owners. A deadline obtained from one manual clock waits for and is released by an unrelated clock solely according to elapsed value; FrameworkInstant cannot validate clock provenance. This is evidence of the existing caller-discipline limit, not permission to compare unrelated clock domains. Checkpoint 11d9fcde908de38174f70cb4b92fb6d1c1e1f0a0 has successful hosted CI for both regressions and the configured host/sample evidence. The scheduled-failure diagnostics review also executes the direct error-source contract for lifecycle rejection and a cooperative returned application error. Both chains preserve the scheduled item and observed time around the exact runtime and concrete source errors; final item consumption and later peer progress remain unchanged. This does not add scheduled failure events, retry, or broader fault containment. Checkpoint 6eefde2b49c6f4c93a82c97719f4673c93f1babf has successful hosted CI for both direct source-chain observations and the configured host/sample evidence.

ConfigurationTable<E, MAX_BYTES> validates and copies in-memory byte content through one retained mission function. It exposes immutable active snapshots, assigns fresh revisions even to equal content, and retains only the former active snapshot for consume-once rollback. Rejection preserves active content, rollback history, and revision high-water; rollback restores the original revision without reusing numbers. Exact byte bounds, semantic rejection, ownership, history replacement, and checked revision exhaustion have tests. Runtime<A, E, MAX_CONFIGURATION_BYTES> can now take ownership of a complete validated table at construction. Ordinary work receives an ApplicationWorkContext with an optional immutable revision/bytes view; unconfigured work sees explicit absence. Narrow replacement and rollback operations retain the table's validation and revision rules, while construction failure returns the unchanged table. The same configured runtime composes with scheduled work, failure-event reporting, and MessagingRuntime work without a parallel callback. Returned work errors do not roll configuration back, and stop/restart retains the full lineage. The configured attachment review also proves that a failed inbox reservation returns the runtime with active configuration, consume-once rollback, and revision high-water intact. Eleven focused runtime tests plus the standalone table tests verify RFF-REQ-006. No schema, wire format, host loader, or message/lifecycle callback access is selected. Checkpoint b21b59bff68fe6c16b0d153661865a67a28f8df2 has successful hosted CI for the new regression and configured host/sample evidence. The configuration-operation diagnostics review also executes the existing runtime wrapper's standard source shapes for unconfigured operations, semantic validation rejection, and exhausted consume-once rollback. The surrounding regression retains the active, rollback, and revision-allocation lineage. This is diagnostic evidence, not automatic recovery, logging policy, or API stabilization. Checkpoint 5372a52f888b38b0d725b74bbd330f40ef4a0a31 has successful hosted CI for the strengthened regressions and configured host/sample evidence.

The configuration-view refresh review extends ordinary-work observations from exact-capacity content to shorter, empty, and rolled-back snapshots, retaining the complete copied byte/revision log after runtime destruction. Existing tests already cover fixed-length transitions, and borrowing probes reject escaped callback bytes. Focused and full locked checks and source/document/diff review pass. Checkpoint 16fb457f6ee7a49109ef1e245c59ea5ec9588922 has successful hosted CI for 141 workspace tests and configured host/sample evidence. No configuration API or policy changes.

A public integration test runs two independently defined applications through registration, start, work, stop, restart, and work, completing the bounded RFF-REQ-002 lifecycle evidence. The combined routing, lifecycle-availability, and caller-selected dispatch evidence now verifies RFF-REQ-003, including capacity-one self-publication, per-dispatch availability refresh, and exact selected-queue clearing after a returned message error. The runtime still has no automatic or batch dispatch. The private combined sample now composes these services with a fixed caller-driven scenario. Periodic scheduling, application-authored events, other callback event paths, and application configuration access outside ordinary work remain unimplemented. The private host-echo example preserves ADR-0019's two-byte validated echo command and matching telemetry. Its two applications use capacity-one inboxes and a borrowed capacity-one host mailbox drained outside dispatch. The same mission source is exercised by integration tests; no library API is added. ADR-0022 combines the adapters with both applications' lifecycle, finite scheduling at manual time 10 ms, observed configuration activation/rejection/ rollback, and a separate cooperative work-failure event at 20 ms. The binary and sample tests execute the same fixed driver and retain a structured report. The finite scheduling and manual-time evidence verifies RFF-REQ-004. The direct returned-work event and peer-progress evidence, extended through the messaging owner, verifies RFF-REQ-005 and RFF-REQ-008 at those cooperative ordinary-work boundaries. Traceability distinguishes this evidence from event delivery guarantees or containment of panics, hangs, cleanup failures, and other arbitrary faults.

The first source-quality checkpoint tracks stable rustfmt at 100 columns and denies Clippy functions over a 60-line review threshold across all targets. Three cohesive chronological integration tests carry narrow reasoned expectations; two avoidable expectations were retired through focused test structure. Production code needs no function-length waiver. Source ordering, module cohesion, names, comment prose, and exceptional physical lines remain review responsibilities rather than unsupported automated claims.

Development

The package is unpublished and uses stable Rust with no external Cargo dependencies or package features. The standard library, host environment, toolchain, and CI tooling remain outside that Cargo graph. The dependency and scope review records the exact inventory and autonomous review boundary. Under the user's 2026-10-08 review delegation, routine v0.1 entry-point and architecture acceptance can proceed autonomously. The completed review records the exact input revision, actual Codex reviewers, evidence, findings, and accepted limits.

cargo fmt --all -- --check
cargo check --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo doc --workspace --all-features --no-deps

Run rustdoc with warnings denied; in PowerShell, set $env:RUSTDOCFLAGS = "-D warnings" before the documentation command. Contributor guidance records the remaining structural and document checks.

The host CI workflow encodes these checks with locked dependency resolution, both focused host tests, and the sample on Windows. Its verification record separates local validation from successful exact-revision hosted execution. Verified source pushes to the existing codex/nightly branch are authorized without per-push human review. Autonomous source/document review and automated checks remain required. Routine host milestone reviews are delegated to Codex; publication and completed review remain separate evidence.

Combined host sample

Run cargo run --example host-echo from the repository root. The example entry point prints the experimental scope notice and processes percentages 0, 42, and 100 through the shared mission source:

command [01, 00] -> telemetry [81, 00]
command [01, 2A] -> telemetry [81, 2A]
command [01, 64] -> telemetry [81, 64]

Each input is one complete caller-framed two-byte slice: identifier 0x01, then a percentage in 0..=100. Length, identifier, and value validation precede publication. The host inspects the returned delivery report, explicitly dispatches the echo application once and the telemetry application once, then drains one exact [0x81, percentage] array. Ingress does not execute work or drain output. The local identifiers have no external protocol meaning.

Full inboxes reject the newest delivery and preserve older messages. Full host output preserves the older record but returns a callback error: the telemetry application becomes terminal Failed. Draining that output does not recover the application. Normal example execution drains between commands. No retry, physical delivery, stream framing, authentication, or execution rollback is promised. Diagnostic stdout writes occur after drain and outside callbacks; a write error ends the host example without undoing execution.

The executable then prints the fixed scenario report: both applications' lifecycle states, manual-time schedule outcomes, fresh callback configuration observations, and an injected echo work failure that clears one queued command while preserving the peer's work and queued telemetry. Configuration is one validated observation byte; it does not alter the command grammar.

cargo test --test host_adapters exercises the adapters and fault fixture. cargo test --test host_sample verifies the same combined driver as the binary, including complete fresh-run report equality. See the sample guide for exact expected fields and resource limits. The host review accepts the combined demonstration with separate CI, dependency, scope, and architecture evidence; sample execution alone does not establish those gates.

Start here

• Project charter
• Initial architecture analysis
• v0.1 requirements
• Roadmap
• Current project state
• Caller-driven runtime decision
• Project identity and dual licensing
• Lifecycle and identity decision
• Bounded inbox decision
• Configuration rollback decision
• Initial application ownership decision
• Owned stop boundary decision
• In-place owned restart decision
• Caller-driven owned work decision
• Bounded message-routing core decision
• Runtime-owned message availability decision
• One-message application dispatch decision
• Bounded structured-event queue decision
• Injected manual framework clock decision
• Finite caller-driven scheduling decision
• Returned-work failure-event decision
• Bounded configuration snapshot decision
• Configuration-aware work-context decision
• Host command/telemetry boundary decision
• Messaging-owned work failure-event decision
• Messaging-owned scheduling decision
• Scheduled-work identity scope review
• Clock-origin scope review
• Scheduled-failure diagnostics review
• Messaging-construction diagnostics review
• Configured-runtime construction diagnostics review
• Configuration-operation diagnostics review
• Failure-event identity scope review
• Lifecycle construction review
• Research sources and provenance
• Verification traceability
• Autonomous host v0.1 review
• Source-quality baseline
• Contributor and automation guidance

Licence

This repository is licensed under either the MIT licence or the Apache License, Version 2.0, at your option. The confirmed notice is Copyright 2026 Daniel Smith. Cargo publication remains disabled.