RFC-0045 · Reference catalog
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.
Generated reference catalog. This page renders structured Lean data for RFC-0045: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0045.This page is generated from the
lean/Gnomon/Spec/module for RFC-0045. Edit that source and regenerate this catalog.
Title: Process and Hosting Model
Status: draft
Owners: Module Platform, Runtime
Diagnostic range: M45000-M45099
Depends on: RFC-0001, RFC-0002, RFC-0005, RFC-0006, RFC-0007, RFC-0008, RFC-0024, RFC-0033, RFC-0034, RFC-0036, RFC-0037, RFC-0038, RFC-0039, RFC-0040, RFC-0041
Proof citations in source: 1 / 1. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Boot sequence | The deterministic phases the runtime executes from process start to ready-to-serve. |
| Compiled bundle | The build artifact produced by the Gnomon compiler (RFC-0002): all installed modules, dependency closure, manifest hashes. |
| Deployable unit | The pair (runtime image, compiled bundle). Both are versioned, immutable artifacts. |
| Drain | The process of completing in-flight work, refusing new work, and releasing resources during shutdown. |
| Runtime image | The executable container or binary that hosts an Gnomon runtime. Includes the runtime kernel, its supporting services, and the loader for compiled bundles. |
| Supervisor | The orchestrator’s component that starts, restarts, and terminates runtime processes. The host’s responsibility, not Gnomon’s. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M45010 | Fatal | Bundle content-hash verification failed; refusing to load |
M45011 | Fatal | Bundle ABI version is incompatible with the runtime image |
M45020 | Fatal | Required environment variable is unset (GNOMON_BUNDLE_PATH, GNOMON_TENANT_MODE) |
M45021 | Warning | Conventional environment variable has an unrecognized value; using default |
M45030 | Fatal | Configuration phase 2 failed: required configuration value missing or invalid |
M45031 | Fatal | Backend phase 3 failed to initialize after retries |
M45040 | Fatal | Port binding conflict: two serve declarations request the same (host, port) |
M45041 | Warning | Protocol server bound to a non-default port; clients must be reconfigured |
M45050 | Fatal | Provider registration phase 4 failed: required token has no provider |
M45051 | Warning | Provider registration phase 4: duplicate provider for token; resolved per RFC-0041 §9.3 |
M45060 | Fatal | Install reconciliation phase 5 failed; see RFC-0041 diagnostics |
M45070 | Warning | /healthz probe returning 200 but /readyz returning 503 for >5 minutes; runtime may be stuck in boot |
M45080 | Warning | Drain timeout exceeded; cancelling in-flight requests |
M45081 | Fatal | Drain failed to complete within GNOMON_SHUTDOWN_TIMEOUT; supervisor escalation expected |
M45090 | Info | Runtime ready (Phase 7) — emitted as audit log entry, not as an error |
Dependency neighborhood
graph LR
nRFC_0045["RFC-0045"]
nRFC_0001["RFC-0001"]
nRFC_0045 --> nRFC_0001
nRFC_0002["RFC-0002"]
nRFC_0045 --> nRFC_0002
nRFC_0005["RFC-0005"]
nRFC_0045 --> nRFC_0005
nRFC_0006["RFC-0006"]
nRFC_0045 --> nRFC_0006
nRFC_0007["RFC-0007"]
nRFC_0045 --> nRFC_0007
nRFC_0008["RFC-0008"]
nRFC_0045 --> nRFC_0008
nRFC_0024["RFC-0024"]
nRFC_0045 --> nRFC_0024
nRFC_0033["RFC-0033"]
nRFC_0045 --> nRFC_0033
nRFC_0034["RFC-0034"]
nRFC_0045 --> nRFC_0034
nRFC_0036["RFC-0036"]
nRFC_0045 --> nRFC_0036
nRFC_0037["RFC-0037"]
nRFC_0045 --> nRFC_0037
nRFC_0038["RFC-0038"]
nRFC_0045 --> nRFC_0038
nRFC_0039["RFC-0039"]
nRFC_0045 --> nRFC_0039
nRFC_0040["RFC-0040"]
nRFC_0045 --> nRFC_0040
nRFC_0041["RFC-0041"]
nRFC_0045 --> nRFC_0041
Invariants
- /healthz returns 200 whenever the process is alive and MUST NOT depend on backend, configuration, or downstream services. (enforced by: runtime)
- /readyz returns 200 only between Phase 7 ready and SIGTERM receipt. (enforced by: runtime)
- Boot phases 0–7 execute in order and each must succeed before the next runs. (enforced by: runtime)
- Cancelled in-flight requests in drain phase S4 do NOT mark idempotency keys complete. (enforced by: runtime)
- Drain MUST complete within GNOMON_SHUTDOWN_TIMEOUT. (enforced by: runtime)
- Exit codes 3, 4, 5, 7, 8, 9 indicate fatal misconfiguration or artifact errors and MUST NOT be auto-restarted. (enforced by: supervisor policy)
- The deployable unit is the (runtime image, compiled bundle) pair; both are immutable, content-hashed artifacts. (enforced by: content-hash verification)
- The runtime MUST NOT corrupt state on resource exhaustion; OOM exits cleanly via panic to exit code 1. (enforced by: runtime)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Boot Sequence
- MUST — Backend retry policy on transient failures MUST be bounded.
- MUST — Host MUST surface install failure diagnostics for operator review. (proof citation:
rfc0045_b22_grounded; verification pending) - MUST — Supervisor MUST treat exit code 3 as a fatal misconfiguration with no automatic restart.
- MUST — Supervisor MUST treat exit code 4 as a fatal artifact error.
Compatibility and Migration
- MUST — Existing deployments MUST adopt /healthz and /readyz endpoints if not already served.
- MUST — Existing deployments MUST honor SIGTERM with the drain semantics defined in section 8.
- SHOULD — Legacy deployments SHOULD migrate to the GNOMON_* environment variable prefix.
Deployable Unit
- MUST — Host MUST refuse to start when bundle ABI version mismatches the runtime image.
- MAY — Multiple bundles MAY be served by the same runtime image and multiple runtime image versions MAY serve the same bundle.
- MUST — Runtime MUST verify the bundle’s content hash against the value embedded in the bundle metadata.
Environment Variables
- MAY — Any module configuration value MAY be overridden via env var using GNOMON_CONFIG__
__ .
Graceful Shutdown
- MUST — Drain MUST be bounded by GNOMON_SHUTDOWN_TIMEOUT (default 30 seconds).
- MUST — Drain phases S3-S6 MUST complete within the timeout bound; otherwise the runtime exits with code 2.
- MUST — Supervisor MUST escalate when drain timeout exceeds the bound.
Health and Readiness
- MUST_NOT — /healthz MUST NOT depend on backend, configuration, or downstream services.
- MUST — Per-protocol health endpoints MUST report the same readiness state as /readyz.
Invariants
- MUST — Drain MUST complete within GNOMON_SHUTDOWN_TIMEOUT.
- MUST_NOT — Exit codes 3, 4, 5, 7, 8, 9 MUST NOT be auto-restarted.
- MUST_NOT — Runtime MUST NOT corrupt state on resource exhaustion.
Port Binding
- MAY — Protocol servers MAY be configured for TLS via per-serve configuration.
- MUST — Runtime MUST honor TLS configuration per protocol server independently.
Supervision
- MUST — Runtime MUST handle out-of-memory by exiting cleanly rather than corrupting state.
- SHOULD_NOT — Supervisor SHOULD NOT auto-restart on exit codes 3, 4, 5, 7, 8, 9 (configuration or artifact errors).
- SHOULD — Supervisor SHOULD restart the runtime on exit code 1 (panic) with exponential backoff capped at 60s.
- SHOULD — Supervisors SHOULD probe /healthz every 10 seconds and /readyz every 5 seconds.
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0002 |
| Depends on | RFC-0005 |
| Depends on | RFC-0006 |
| Depends on | RFC-0007 |
| Depends on | RFC-0008 |
| Depends on | RFC-0024 |
| Depends on | RFC-0033 |
| Depends on | RFC-0034 |
| Depends on | RFC-0036 |
| Depends on | RFC-0037 |
| Depends on | RFC-0038 |
| Depends on | RFC-0039 |
| Depends on | RFC-0040 |
| Depends on | RFC-0041 |