diff --git a/docs/v4.0.0/ADR-2026-11-19-F18-ARTIFACTS.md b/docs/v4.0.0/ADR-2026-11-19-F18-ARTIFACTS.md new file mode 100644 index 00000000..040c4151 --- /dev/null +++ b/docs/v4.0.0/ADR-2026-11-19-F18-ARTIFACTS.md @@ -0,0 +1,176 @@ +# StarshipOS Architectural Design Decision + + + +## F18 Binary Artifacts, ABI/API, and Live Runtime Updates + +Status: ACCEPTED — Immediate Design Decision +Date: 2026-11-19 +Scope: F18 build system, LithosAnanke, StarshipOS runtime +Priority: Architectural foundation + +--- + +### 1. Decision + +StarshipOS shall establish a canonical binary artifact format for compiled F18 code, supported by a minimal, formally specified Application Binary Interface (ABI) and Application Programming Interface (API). + +The ABI shall operate at the word and capsule levels: + +- Words are the units of interface and access control. +- Capsules are the units of packaging, distribution, and deployment. + +The implementation shall preserve the existing StarshipOS architecture without introducing conventional dynamic linking, shared-library infrastructure, or unnecessary runtime machinery. + +### 2. Motivation + +This decision supports four primary objectives: + +1. Performance: Eliminate redundant compilation, dependency resolution, and other avoidable work from build and startup paths. +2. Verification: Provide immutable binary artifacts suitable for Isabelle/HOL verification and reproducible-build validation. +3. Authenticity and provenance: Establish traceability between source, build configuration, compiler, binary artifact, and formal verification evidence. +4. Live updates: Permit verified binary components to be staged and activated within a running StarshipOS instance without requiring a complete system restart. + +Performance improvements must be measured. Binary artifact creation alone does not guarantee reduced startup latency. + +### 3. Architectural Contract + +#### 3.1 F18 Binary Artifacts + +The build system shall compile F18 source into a canonical, versioned binary artifact representation. + +An artifact shall provide sufficient information to establish: + +- Artifact identity and integrity. +- Source and build provenance. +- Target architecture and compatibility constraints. +- Exported and imported word identities. +- Word-level interface contracts. +- Dependencies and required capabilities. +- Verification status and associated proof identity. + +The format may contain individually addressable compiled units. + +Artifacts shall remain independent of final deployment decisions. A compiled unit may be incorporated into kernel ROM or distributed as a runtime-consumable capsule. + +Source files, compiled binaries, and supporting documentation shall retain their individual provenance. + +#### 3.2 Application Binary Interface (ABI) + +The ABI shall define the minimum binary-level contract necessary for independently compiled components to interoperate. + +It shall address: + +- Word identity and resolution. +- Calling conventions and stack effects. +- Memory ownership and access constraints. +- Entry points and dependencies. +- Capability and ACL requirements. +- Binary compatibility. +- Activation and retirement semantics. + +The F18 hardware execution contract and the StarshipOS artifact interoperability contract shall remain conceptually distinct. + +Logical word identity shall not depend on physical memory addresses or processor placement. + +Local execution may resolve to physical addresses. Inter-core communication shall continue to use the established message architecture. + +#### 3.3 Application Programming Interface (API) + +The API shall expose the minimum operations necessary for artifact discovery, verification, staging, activation, retirement, and recovery. + +These operations should be implemented through existing StarshipOS facilities wherever practical. + +They shall not automatically require new kernel primitives. + +The API shall preserve the existing responsibilities of: + +- Hera: System ownership, component creation, and coordination. +- Hermes: Messaging, routing, and communication. +- Artemis: Memory, persistence, and recovery. + +Specific API word names and signatures remain implementation decisions. + +### 4. Live Runtime Updates + +StarshipOS shall support the architectural capability to introduce verified replacement artifacts into a running system. + +The intended lifecycle is: + +1. Build the replacement artifact. +2. Verify integrity, compatibility, and applicable formal properties. +3. Distribute and stage the artifact. +4. Establish a safe activation boundary. +5. Activate the replacement. +6. Retire the previous implementation when safe. +7. Preserve recovery or rollback capability where applicable. + +Heartbeat boundaries may provide logical activation points, but safe replacement must account for outstanding execution, messages, dependencies, and persistent state. + +Multiple artifact versions may coexist during transitions. + +Live replacement shall not violate existing runtime invariants or word-level ACL guarantees. + +### 5. Formal Verification + +The ABI and artifact format shall be suitable for specification in Isabelle/HOL. + +Verification objectives include: + +- Artifact structural validity. +- Interface and stack-effect compatibility. +- Dependency satisfaction. +- Memory and capability constraints. +- Safe activation and retirement. +- Preservation of established invariants across compatible replacements. + +Proof evidence shall be associated with the exact artifact and its applicable assumptions. + +Cryptographic integrity and authenticity shall be distinguished from functional correctness. Hashes alone do not establish correctness or authorship. + +A verified replacement shall not be considered universally compatible merely because its individual components have been verified. + +### 6. Explicit Non-Goals + +This decision does not authorize introducing: + +- ELF-style dynamic linking or shared libraries. +- A conventional process loader. +- A centralized runtime linker. +- A global executable address space. +- A conventional scheduler or memory manager. +- A new execution model. +- Mandatory inclusion of all compiled artifacts in kernel ROM. +- Unnecessary kernel primitives or additional abstraction layers. + +The existing asynchronous, message-driven architecture remains authoritative. + +### 7. Implementation Direction + +Implementation shall proceed incrementally: + +1. Define and document the minimal ABI contract. +2. Establish the canonical binary artifact representation. +3. Integrate artifact production into the existing build system. +4. Add integrity, provenance, and reproducibility checks. +5. Formalize applicable ABI properties in Isabelle/HOL. +6. Implement minimal artifact API operations. +7. Validate staged and live replacement using controlled experiments. +8. Measure build time, startup latency, runtime overhead, and replacement correctness. + +Existing build, POST, CI, and verification gates shall remain in force unless explicitly superseded by independently validated equivalents. + +### 8. Governing Principle + +Words define interfaces. Capsules define deployment. Artifacts establish identity and provenance. The ABI guarantees interoperability. The API exposes operations. Isabelle/HOL verifies the applicable contracts. + +No additional machinery shall be introduced without demonstrated necessity. + +The machine remains the machine. + +--- + +Decision: ACCEPTED +Implementation: Pending incremental design and experimental validation +Architectural impact: Foundational — F18 toolchain, capsule infrastructure, formal verification, and live deployment.