ADR 2026-11-19: F18 binary artifacts, ABI/API and live runtime updates -- recorded as given (Captain Bob)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
This commit is contained in:
@@ -0,0 +1,176 @@
|
||||
# StarshipOS Architectural Design Decision
|
||||
|
||||
<!-- Recorded verbatim as given by Captain Bob, 2026-11-19. The conflicts it raises with the existing record
|
||||
are put to him one at a time, and ruled in docs/v4.0.0/plans/2026-11-19-f18-artifacts.md. -->
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user