Files
LithosAnanke/docs/v4.0.0/ADR-2026-11-19-F18-ARTIFACTS.md
T

7.5 KiB

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.