# RFC-0002 — Orbit Health Runtime Extraction ## Status PROPOSED ## Document Revision Revision: 2 Revision Date: 2026-08-02 Revision Purpose: Complete the governance, portability, compatibility, release, evidence, dual-target incubation, promotion, and extraction- authorization contract without changing the certified Atlas implementation. ## Canonical ORBIT Identity Product RFC ID: `RFC-ATLAS-0002` Local repository filename: `RFC-0002-ORBIT-HEALTH-RUNTIME.md` The local filename may remain product-local. ORBIT publication must use the globally unique product-qualified identity. ## RFC Identifier RFC-0002-ORBIT-HEALTH-RUNTIME ## Title Orbit Health Runtime — Portable Lifecycle, Acquisition, State, and Presentation Boundary ## Authors Atlas Engineering Orbit-Core Review Required ## Created 2026-07-31 ## Target Review Orbit-Core Architecture Review ## Source Certification BM-3.21B.10 — Cross-Surface Runtime Profile Certification Certified Atlas commit: `c6cd48e5d45c8eb6617c78582b7372192581e81a` ## Decision Type Portable runtime extraction proposal. This RFC defines an extraction boundary. It does not authorize source movement, package publication, consumer migration, or removal of the existing Atlas implementation. --- # 1. Executive Summary Atlas has established and certified a coherent health-runtime architecture built around five explicit responsibilities: 1. Runtime owns lifecycle orchestration. 2. Profile owns snapshot acquisition. 3. State owns health lifecycle state. 4. Renderer owns presentation behavior. 5. Product surfaces retain their own external authorities. The certified implementation currently serves four distinct acquisition models: - live HTTP acquisition; - persisted immutable evidence; - projection snapshots; - registry snapshots. The architecture has been verified across Infrastructure, Observatory, Executive, and Operations surfaces without introducing surface-specific branching into the shared runtime. This RFC proposes that the generic boundary be qualified for extraction into an Orbit-Core JavaScript package that other ZeroTrust products may consume. No extraction will occur until this RFC is adopted and all approval gates are satisfied. --- # 2. Problem Statement Multiple ZeroTrust products require a consistent mechanism for: - acquiring bounded operational snapshots; - expressing loading, ready, degraded, failed, and stopped states; - orchestrating refresh and visibility lifecycle behavior; - projecting evidence into product-owned user interfaces; - supporting live and non-live evidence sources; - avoiding transport, persistence, state, and presentation coupling. Without a portable contract, each product may independently recreate lifecycle orchestration, state transitions, acquisition adapters, and rendering boundaries. Independent implementations increase the risk of: - inconsistent failure semantics; - duplicate polling logic; - transport leakage into user-interface layers; - product-specific branching inside shared runtime code; - incompatible health evidence models; - inaccessible or inconsistent status presentation; - difficult cross-product maintenance. Atlas now contains a certified reference implementation that may provide the foundation for a reusable Orbit-Core package. --- # 3. Goals This RFC defines: - the portable package boundary; - canonical package naming; - public exports; - profile extension rules; - runtime lifecycle responsibilities; - state responsibilities; - renderer responsibilities; - transport abstraction constraints; - consumer integration requirements; - backward compatibility requirements; - forbidden Atlas dependencies; - package release and versioning rules; - testing and evidence requirements; - extraction approval gates. --- # 4. Non-Goals This RFC does not: - move any Atlas source files; - publish an npm package; - modify Atlas imports; - redesign the certified runtime; - add new profile implementations; - define product-specific health schemas; - centralize product authority in Orbit-Core; - move Atlas queries, models, providers, controllers, or Blade components; - require every product to use the same renderer; - authorize immediate adoption by Aloqu, WireShield, Hostiva, or another product; - replace product-specific observability systems; - define persistence storage or database schemas; - define service discovery or provider registration. --- # 5. Canonical Package Identity ## 5.1 Package Name The proposed canonical npm package name is: `@orbit/runtime-health` ## 5.2 Package Responsibility The package provides portable client-side health-runtime primitives. It must not become a general observability platform, monitoring server, persistence service, product registry, or user-interface framework. ## 5.3 JavaScript Namespace The public module namespace is represented through ES module exports from: `@orbit/runtime-health` The package must not create mandatory browser globals. A consumer may create its own product namespace, but the package itself must remain module-first. ## 5.4 Source Package Location The proposed Orbit-Core source location is: `packages/runtime-health` The final Orbit-Core repository location remains subject to Orbit-Core repository governance. ## 5.5 Package Format The package must support: - ECMAScript modules; - modern browser bundlers; - tree-shakeable named exports; - explicit package exports; - source maps for non-production debugging; - documented minimum browser support. CommonJS support is not required unless a confirmed consumer requires it. --- # 6. Portable Runtime Boundary The proposed portable boundary consists of generic equivalents of: - `AtlasHealthRuntime`; - `AtlasHealthRuntimeProfile`; - `AtlasLiveRuntimeProfile`; - `AtlasPersistedRuntimeProfile`; - `AtlasProjectionRuntimeProfile`; - `AtlasRegistryRuntimeProfile`; - `AtlasHealthClient`; - `AtlasHealthState`; - `AtlasHealthRenderer`. Extraction must remove the Atlas product prefix from portable symbols. The proposed portable names are: - `HealthRuntime`; - `HealthRuntimeProfile`; - `LiveRuntimeProfile`; - `PersistedRuntimeProfile`; - `ProjectionRuntimeProfile`; - `RegistryRuntimeProfile`; - `HealthClient`; - `HealthState`; - `HealthRenderer`. The exact rename map must be approved before implementation. --- # 7. Responsibility Model ## 7.1 Runtime `HealthRuntime` owns lifecycle orchestration. It may own: - startup; - shutdown; - refresh scheduling; - refresh serialization; - visibility-aware lifecycle behavior; - bounded retry coordination; - state transitions triggered by acquisition outcomes; - renderer invocation; - cancellation and disposal; - profile invocation. It must not own: - HTTP endpoint construction; - database persistence; - product queries; - provider resolution; - product-specific normalization; - DOM schema discovery for a specific product; - product-specific status rules; - product-specific routing. ## 7.2 Profile `HealthRuntimeProfile` owns acquisition strategy. A profile answers one question: > How does this runtime obtain its next bounded snapshot? A profile may: - call an injected transport client; - return immutable persisted evidence supplied by a consumer; - return an immutable projection snapshot; - return an immutable registry snapshot; - validate that its required acquisition dependency exists. A profile must not: - render user-interface elements; - mutate runtime state directly; - own lifecycle scheduling; - persist snapshots; - resolve product providers; - query product databases; - inspect product DOM structures; - contain product-specific routes. ## 7.3 State `HealthState` owns canonical runtime state. The minimum canonical lifecycle states are: - `idle`; - `loading`; - `ready`; - `degraded`; - `failed`; - `stopped`. State transitions must be explicit and deterministic. State must not: - perform acquisition; - call transport; - persist evidence; - render the DOM; - resolve product authorities. ## 7.4 Renderer `HealthRenderer` owns presentation behavior. A renderer may: - project state into a user interface; - update accessible status regions; - dispatch generic health-state events; - preserve existing content during background refresh; - expose renderer hooks to a consumer. A renderer must not: - perform HTTP requests; - resolve providers; - query databases; - own lifecycle scheduling; - mutate acquisition profiles; - contain product-specific business rules in the portable package. ## 7.5 Surface Authority Product-specific authority remains external. Examples include: - an HTTP health API; - an immutable persisted snapshot repository; - an executive presentation query; - an operations provider registry. Orbit-Core must not absorb these authorities. The portable package consumes bounded snapshots or injected acquisition dependencies supplied by the product. --- # 8. Public Exports The initial proposed public exports are: ```javascript export { HealthRuntime, HealthRuntimeProfile, LiveRuntimeProfile, PersistedRuntimeProfile, ProjectionRuntimeProfile, RegistryRuntimeProfile, HealthClient, HealthState, HealthRenderer, }; ``` The package must use an explicit export map. No internal helper becomes public merely because it exists in the source tree. The final export map must be approved through consumer compatibility review before the first release candidate. --- # 9. Profile Extension Rules A custom profile must implement the canonical `HealthRuntimeProfile` contract. Every concrete profile must implement: ```javascript async loadSnapshot() ``` A profile must: - return one bounded snapshot; - reject missing required dependencies explicitly; - receive dependencies through construction or explicit configuration; - avoid runtime lifecycle scheduling; - avoid renderer invocation; - avoid state mutation; - avoid persistence; - avoid product-global discovery; - remain independently testable; - remain renderer-neutral; - remain product-neutral. Profiles must not silently fall back between authority types. A persisted profile must not fall back to HTTP. A projection profile must not execute a backend query. A registry profile must not resolve product providers. A live profile must not persist its response. Authority selection remains the responsibility of the consumer composition layer. --- # 10. Snapshot Contract The package must not require an Atlas-specific snapshot schema. A runtime snapshot must be: - non-null; - bounded; - serializable; - deterministic; - free of executable functions; - free of raw exceptions; - free of secrets; - free of unbounded provider metadata. Consumers may extend their product-specific payloads. A future ORBIT schema RFC may standardize common health fields. Until then, snapshot interpretation remains consumer-owned. The runtime package must not infer product-specific semantics from arbitrary fields. --- # 11. Transport Abstraction Only live acquisition may require transport. `HealthClient` may own: - endpoint invocation; - timeout enforcement; - response validation; - response normalization; - abort support; - receiver-safe native fetch invocation. The runtime itself must not call: - `fetch`; - Axios; - `XMLHttpRequest`; - WebSocket; - Laravel endpoints; - product routes. Non-live profiles must not import `HealthClient`. The package must not hard-code: - Atlas routes; - Laravel route names; - CSRF conventions; - product authentication tokens; - product hostnames; - product API prefixes. Endpoint construction and authentication remain consumer responsibilities. --- # 12. Consumer Integration Contract A consumer must provide: - an explicit profile or acceptance of the documented default; - a bounded snapshot authority; - a renderer or compatible renderer target; - lifecycle configuration; - timeout configuration where transport is used; - refresh configuration where polling is used; - product-owned status semantics; - product-owned error reporting; - rollback instructions. A consumer must not: - mutate runtime internals; - bypass the profile boundary; - make the renderer authoritative for state; - add product branches to the shared package; - depend on undocumented internal exports; - assume Atlas DOM markers; - assume Laravel; - assume Blade; - assume a specific product URL. Consumers may create product-specific adapters outside the portable package. --- # 13. Dual-Target Package Strategy Revision 2 adopts both package targets. ## 13.1 Option A — Atlas-Incubated Package The first extraction target is: ```text /opt/zerotrust-geocloud/ └── packages/ └── orbit-runtime-health/ ``` Option A exists to support: - low-risk extraction; - side-by-side parity testing; - immediate Atlas compatibility validation; - deterministic rollback; - package-boundary qualification; - evidence collection before repository promotion. Option A is an incubation and qualification location. It is not the permanent release authority. It must not publish production releases independently. ## 13.2 Option B — Independent Orbit-Core Repository The permanent package target is: ```text /opt/zerotrust-orbit-core/ └── packages/ └── runtime-health/ ``` Option B owns: - canonical package source; - package releases; - semantic versioning; - package signing; - public exports; - security review; - compatibility policy; - distribution; - long-term maintenance. ## 13.3 Promotion Direction The permanent promotion direction is: ```text Atlas-certified implementation | v Atlas-incubated package | v Parity and boundary certification | v Orbit-Core package | v Internal pre-release | v Atlas compatibility adoption | v Second-product qualification | v Stable ORBIT release ``` Code must not be independently edited in both Option A and Option B after promotion begins. Orbit-Core becomes authoritative after the promotion gate. ## 13.4 Source-of-Truth Transition Before promotion: ```text Atlas implementation = source authority Option A package = extraction candidate ``` After Orbit-Core adoption: ```text Orbit-Core package = source authority Atlas adapter = consumer integration Atlas local copy = rollback-only compatibility evidence ``` The authority transition requires explicit approval. --- # 14. Backward Compatibility The first extracted version must preserve Atlas observable behavior. Compatibility includes: - lifecycle startup; - lifecycle shutdown; - refresh scheduling; - visibility handling; - refresh serialization; - background refresh rendering; - state transition semantics; - event semantics; - timeout behavior; - live profile defaults; - snapshot normalization; - failure behavior; - existing Infrastructure behavior; - native fetch receiver binding. Atlas must be able to adopt the package through imports or a compatibility adapter without changing user-visible behavior. The existing Atlas implementation remains available during the first adoption phase. No source deletion is permitted in the first package-adoption batch. --- # 15. Atlas Dependencies That Must Not Cross the Boundary The portable package must not contain or import: - `AtlasExecutivePresentationQuery`; - `ObservatoryHealthPanelQuery`; - `LatestSpatialHealthSnapshotQuery`; - `AtlasHealthSnapshot`; - `AtlasHealthSnapshotRepository`; - `UnifiedOperationsRegistry`; - `GeoCloudOperationsProvider`; - Laravel controllers; - Laravel models; - Laravel service providers; - Laravel routes; - Blade templates; - Atlas CSS selectors; - Atlas application-frame components; - Atlas navigation registries; - Atlas workspace registries; - Atlas endpoint paths; - Atlas-specific service identifiers; - Atlas-specific evidence metadata; - geospatial domain behavior; - publishing behavior; - workspace behavior. Atlas-specific integration remains in Atlas or in a separately governed Atlas adapter. --- # 16. Renderer Portability The renderer contract must permit: - a default DOM renderer; - a consumer-specific DOM renderer; - a headless renderer; - an event-only renderer; - a test renderer. The runtime must depend on a renderer contract, not Atlas markup. Any default renderer distributed by Orbit-Core must use: - explicit element references; - configurable selectors; - bounded event contracts; - accessible status communication. The portable renderer must not contain: - Atlas CSS classes; - Atlas routes; - Atlas text labels; - Atlas service names; - product business rules; - product-specific normalization. --- # 17. State Contract The state authority must expose deterministic state. At minimum: - current phase; - current snapshot; - current error; - last refresh result; - last successful acquisition time where available; - stopped state. The minimum lifecycle phases are: - `idle`; - `loading`; - `ready`; - `degraded`; - `failed`; - `stopped`. State mutation must occur through explicit methods. Consumers must not mutate internal state fields. State must not perform: - acquisition; - transport; - persistence; - rendering; - provider resolution. --- # 18. Error Contract Errors crossing the package boundary must be normalized. The package must not expose: - raw server traces; - framework exception objects; - database details; - secrets; - authentication tokens; - unbounded response bodies. A normalized error should support bounded fields such as: - code; - category; - message; - retryable status; - timestamp; - cause classification; - consumer-supplied correlation identifier. A platform-wide ORBIT error contract may be defined by a separate RFC. --- # 19. Security and Supply-Chain Requirements The package must: - avoid dynamic code evaluation; - avoid `eval`; - avoid constructing executable functions from strings; - avoid unsafe HTML insertion by default; - support abortable live requests; - enforce configurable timeouts; - avoid logging secrets; - avoid browser persistence by default; - avoid hidden global dependencies; - accept endpoint and credentials through explicit configuration; - expose no raw exception details to renderers; - use a reviewed dependency set; - produce a dependency lock or integrity record; - produce package checksums; - use controlled release automation. Security review is mandatory before Orbit-Core publication. --- # 20. Versioning The package uses Semantic Versioning. Initial qualification versions may use: ```text 0.x.y ``` The first stable release is: ```text 1.0.0 ``` Version meaning: - patch: compatible fixes; - minor: backward-compatible public additions; - major: breaking contract or behavior change. Pre-release identifiers may include: ```text alpha beta rc ``` Example: ```text 1.0.0-rc.1 ``` --- # 21. Release Requirements Every Orbit-Core release must include: - package manifest; - explicit export map; - source build; - type declarations or equivalent API documentation; - changelog; - migration notes; - unit tests; - browser integration tests; - package integrity checksum; - dependency audit; - license declaration; - release evidence; - consumer compatibility matrix; - rollback documentation. Publication must be owned by Orbit-Core release automation. Production releases must not be published directly from a developer workstation or from the Atlas repository. --- # 22. Test Requirements ## 22.1 Contract Tests Required tests include: - profile inheritance; - required `loadSnapshot`; - invalid profile rejection; - state contract; - renderer contract; - export-map contract. ## 22.2 Lifecycle Tests Required tests include: - start; - stop; - refresh; - repeated refresh; - concurrent refresh; - visibility change; - disposal; - timeout; - acquisition failure; - recovery after failure. ## 22.3 Profile Tests Required tests include: - live transport invocation; - persisted snapshot return; - projection snapshot return; - registry snapshot return; - missing dependency errors; - non-live transport prohibition; - renderer neutrality; - persistence prohibition. ## 22.4 Atlas Parity Tests Required tests include: - live runtime behavior; - Infrastructure runtime markers; - state transition parity; - event parity; - rendering parity; - timeout parity; - background-refresh parity; - native fetch receiver binding. ## 22.5 Security Tests Required tests include: - no dynamic evaluation; - no unsafe persistence; - bounded error output; - timeout enforcement; - abort behavior; - dependency vulnerability review. --- # 23. Evidence Requirements Every extraction, promotion, or release batch must preserve: - Atlas source commit; - Option A package commit; - Option B package commit; - runtime inventory; - public export inventory; - dependency inventory; - test totals; - build output; - parity results; - security results; - checksum manifest; - consumer compatibility matrix; - rollback instructions; - migration diff; - approval record. Evidence remains separate from staged production source unless the governing repository explicitly tracks certification artifacts. --- # 24. Consumer Qualification Before adoption, a consumer must prove: - it has a real snapshot authority; - it supplies bounded evidence; - it does not require Atlas imports; - it can supply or accept a renderer; - it supports the package browser target; - it passes package contract tests; - it passes product regression tests; - it has rollback instructions; - it has an identified package integration owner. Initial candidate consumers may include: - Atlas; - Aloqu; - WireShield; - Hostiva; - VoIP Shield. Candidate status does not imply approval. --- # 25. Extraction and Promotion Sequence The approved sequence is: 1. Adopt this RFC. 2. Freeze the certified Atlas boundary. 3. Create Option A package skeleton. 4. Copy, not move, generic implementation into Option A. 5. Remove Atlas naming from the package copy. 6. Add package-owned tests. 7. Run Atlas parity tests. 8. Certify the Option A boundary. 9. Create the Option B Orbit-Core package. 10. Promote the certified package into Option B. 11. Run Orbit-Core package certification. 12. Publish an internal pre-release. 13. Add an Atlas compatibility adapter. 14. Run dual-path parity tests. 15. Migrate Atlas imports in a separate milestone. 16. Retain the original implementation for rollback. 17. Qualify a second ZeroTrust product. 18. Approve stable release. 19. Remove duplicate Atlas code only through a later milestone. No step may be skipped because the source appears generic. --- # 26. Rollback Requirements The first Atlas adoption must support immediate rollback. Rollback must require: - no database migration; - no data conversion; - no route changes; - no user-visible schema change. The original Atlas runtime remains available until: - package parity passes; - production observation completes; - rollback rehearsal passes; - second-consumer qualification succeeds; - Orbit-Core approves removal. Package adoption must be reversible through imports and composition changes. --- # 27. Ownership and Support ## 27.1 Orbit-Core Ownership Orbit-Core owns: - portable package contracts; - Option B source; - releases; - security review; - compatibility policy; - exports; - versioning; - signing; - distribution; - deprecation policy. ## 27.2 Atlas Ownership Atlas owns: - Option A incubation; - Atlas adapters; - Atlas authorities; - endpoint configuration; - Atlas renderer integration; - parity evidence; - Atlas migration; - Atlas rollback. ## 27.3 Consumer Ownership Each consuming product owns: - its integration adapter; - its product authority; - its product regression tests; - its rollback; - its operational adoption decision. ## 27.4 Support Policy Orbit-Core supports published package contracts. Product teams support product-specific adapters. No product adapter becomes an undocumented Orbit-Core public contract. --- # 28. Extraction Approval Gates Extraction may begin only when all gates pass. ## Gate 1 — RFC Adoption The RFC status changes from `PROPOSED` to `ADOPTED` by the authorized Orbit-Core architecture authority. ## Gate 2 — Boundary Certification BM-3.21B.10 remains green against its certified Atlas commit. ## Gate 3 — Public API Approval Names, exports, constructors, snapshot expectations, and error contracts are approved. ## Gate 4 — Dual-Target Approval Option A incubation and Option B permanent ownership are approved. ## Gate 5 — Dependency Review All Atlas-specific dependencies are identified and excluded. ## Gate 6 — Consumer Review Atlas is confirmed as the qualified initial consumer. ## Gate 7 — Compatibility and Rollback Plan Atlas parity, migration, dual-path operation, and rollback are approved. ## Gate 8 — Security Review Transport, rendering, errors, dependencies, and publication workflow pass security review. ## Gate 9 — Test and Evidence Plan Package tests, parity tests, browser tests, consumer tests, and evidence requirements are approved. ## Gate 10 — Release Governance Ownership, package registry, versioning, signing, release automation, and support policy are approved. ## Gate 11 — Promotion Authorization Promotion from Option A to Option B is explicitly authorized. ## Gate 12 — Extraction Authorization A separate implementation milestone is authorized. Passing RFC review alone does not authorize extraction. --- # 29. Adoption Outcomes Reviewers must record one outcome. ## ADOPT The contract and extraction sequence are approved. ## ADAPT The proposal is accepted subject to enumerated revisions. ## EXPERIMENT Only an Option A non-production prototype is authorized. ## REJECT Extraction is not approved. Atlas retains the certified local implementation. --- # 30. Open Review Questions Reviewers must resolve: 1. Should the package preserve the implicit live-profile default? 2. Should the default renderer ship in the base package? 3. Is `@orbit/runtime-health` the approved package name? 4. Is `packages/runtime-health` the approved Option B path? 5. Is `packages/orbit-runtime-health` the approved Option A path? 6. Are TypeScript declarations mandatory for `1.0.0`? 7. Which browsers form the minimum compatibility matrix? 8. Should the snapshot contract remain structural? 9. Should normalized errors use a separate ORBIT RFC? 10. What observation period is required before duplicate Atlas code can be removed? 11. Which product is the required second consumer? 12. What event or condition transfers source authority from Option A to Option B? --- # 31. Revision History ## Revision 1 Created the initial extraction proposal and defined Sections 1 through 8. Revision 1 was incomplete and did not constitute a complete ORBIT extraction contract. ## Revision 2 Adds: - canonical ORBIT identity; - profile extension governance; - snapshot contract; - transport constraints; - consumer integration contract; - dual-target Option A and Option B strategy; - compatibility requirements; - forbidden Atlas dependencies; - renderer and state contracts; - error and security requirements; - versioning; - release governance; - test requirements; - evidence requirements; - consumer qualification; - extraction and promotion sequence; - rollback requirements; - ownership and support; - twelve approval gates; - formal adoption outcomes; - open review questions. Revision 2 changes no certified Atlas runtime implementation. --- # 32. Current Disposition Status: `PROPOSED` Revision: `2` Implementation authorization: `NOT GRANTED` Option A package creation: `NOT GRANTED` Option B package creation: `NOT GRANTED` Production source movement: `PROHIBITED` Package publication: `PROHIBITED` Consumer migration: `PROHIBITED` Next permitted action: Orbit-Core architecture review and adoption decision.