RFC-0045 host lifecycle contract proposal
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Status: first-release proposal. The authored RFC and RDF facts remain unchanged until the owner chooses the public process contract.
Source conflicts and implementation limits
- RFC-0045 §7.2 requires
/readyzto return 503 during phases 0–6, and §7.1 requires/healthzto return 200 whenever the process is alive. The boot sequence binds protocol listeners only in Phase 6. Without an earlier control listener, neither HTTP response exists during phases 0–5. M45070’s stuck-boot diagnostic also cannot observe those phases. - Health endpoints bind to
GNOMON_HTTP_PORTeven without an HTTPservedeclaration (§7), while Phase 6 starts the HTTP protocol server on that same default port (§§4.7, 6). Two separate listeners conflict. The spec needs one shared listener and route mux, or a distinct control port. GNOMON_SHUTDOWN_TIMEOUTcontrols the mandatory drain bound (§8.2), but is absent from the §5 environment-variable table.READY_FDappears in Phase 7 but is absent there too; closing an arbitrary descriptor is not a complete host notification protocol.- Section 9.3 requires the runtime to catch out-of-memory and exit cleanly as code 1. A host can terminate a process for memory exhaustion without executing runtime handlers. The actual safety requirement is durable state integrity after abrupt termination, plus supervisor reporting.
- Section 11 asks existing deployments to adopt endpoints and env names. The owner confirmed nothing is deployed; first-release validation needs no compatibility migration.
Recommended first-release contract
- Bind a small control HTTP listener immediately after successful Phase 0
environment parsing. It owns
/healthzand/readyzfor the process lifetime. Bind it toGNOMON_HOST:GNOMON_HTTP_PORT; attach default HTTPserveroutes to the same listener at Phase 6. Explicit alternate HTTP ports use separate listeners. Detect route and port conflicts before the ready signal. Before the control listener binds, connection failure means unready; do not promise an HTTP status during Phase 0 failure. - Once the control listener binds,
/healthzreports process responsiveness without consulting backends, and/readyzreports 503 until Phase 7, during drain, or after loss of a required serving dependency. The control listener stays available through drain until listener closure. Specify whether M45070 is emitted only while this listener can answer. - Add
GNOMON_SHUTDOWN_TIMEOUTto §5 with a 30-second default and a positive bounded validation range. Use one deadline measured from SIGTERM receipt; record whether S7 audit emission is inside that deadline. State what exit code is returned if audit delivery fails after graph work has drained. - Remove
READY_FDunless a separate, named host protocol defines how the descriptor is passed and what closing it means. A host needing systemd notification can implement the standard systemd notification socket as a host adapter;/readyzremains the portable contract. - Require transactions, install reconciliation, and idempotency persistence to recover safely after abrupt termination, including host OOM kills. Treat exit code 1 as a runtime panic only when the process can emit it; supervisors must also handle signal termination and unknown exit statuses.
- Remove deployed-system migration text and express this as a first-release host conformance contract.
Acceptance fixtures
- A simulated slow backend boot leaves
/healthzat 200 and/readyzat 503 after Phase 0; readiness becomes 200 only after server routes and install reconciliation succeed. - A bundle with no HTTP
servestill exposes both control endpoints. A default HTTPserveshares the listener without port conflict; a second binding to the same port fails before ready with M45040. - SIGTERM flips readiness immediately, refuses new work, bounds the full drain by the configured deadline, and records the specified exit status.
- Force-killing the process during a graph transaction leaves no partial writes and permits a same-key retry according to RFC-0043 idempotency rules. The supervisor reports abnormal termination without assuming code 1.
- Missing bundle path, bad hash, and missing provider exercise the documented fatal codes without a restart loop.