gnomonlearn
Docs/RFC-0045 host lifecycle contract proposal

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

  1. RFC-0045 §7.2 requires /readyz to return 503 during phases 0–6, and §7.1 requires /healthz to 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.
  2. Health endpoints bind to GNOMON_HTTP_PORT even without an HTTP serve declaration (§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.
  3. GNOMON_SHUTDOWN_TIMEOUT controls the mandatory drain bound (§8.2), but is absent from the §5 environment-variable table. READY_FD appears in Phase 7 but is absent there too; closing an arbitrary descriptor is not a complete host notification protocol.
  4. 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.
  5. Section 11 asks existing deployments to adopt endpoints and env names. The owner confirmed nothing is deployed; first-release validation needs no compatibility migration.
  • Bind a small control HTTP listener immediately after successful Phase 0 environment parsing. It owns /healthz and /readyz for the process lifetime. Bind it to GNOMON_HOST:GNOMON_HTTP_PORT; attach default HTTP serve routes 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, /healthz reports process responsiveness without consulting backends, and /readyz reports 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_TIMEOUT to §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_FD unless 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; /readyz remains 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

  1. A simulated slow backend boot leaves /healthz at 200 and /readyz at 503 after Phase 0; readiness becomes 200 only after server routes and install reconciliation succeed.
  2. A bundle with no HTTP serve still exposes both control endpoints. A default HTTP serve shares the listener without port conflict; a second binding to the same port fails before ready with M45040.
  3. SIGTERM flips readiness immediately, refuses new work, bounds the full drain by the configured deadline, and records the specified exit status.
  4. 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.
  5. Missing bundle path, bad hash, and missing provider exercise the documented fatal codes without a restart loop.