gnomonlearn
Docs/RFC-0045/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
Boot sequenceThe deterministic phases the runtime executes from process start to ready-to-serve.
Compiled bundleThe build artifact produced by the Gnomon compiler (RFC-0002): all installed modules, dependency closure, manifest hashes.
Deployable unitThe pair (runtime image, compiled bundle). Both are versioned, immutable artifacts.
DrainThe process of completing in-flight work, refusing new work, and releasing resources during shutdown.
Runtime imageThe executable container or binary that hosts an Gnomon runtime. Includes the runtime kernel, its supporting services, and the loader for compiled bundles.
SupervisorThe orchestrator’s component that starts, restarts, and terminates runtime processes. The host’s responsibility, not Gnomon’s.

Diagnostics

CodeSeverityDescription
M45010FatalBundle content-hash verification failed; refusing to load
M45011FatalBundle ABI version is incompatible with the runtime image
M45020FatalRequired environment variable is unset (GNOMON_BUNDLE_PATH, GNOMON_TENANT_MODE)
M45021WarningConventional environment variable has an unrecognized value; using default
M45030FatalConfiguration phase 2 failed: required configuration value missing or invalid
M45031FatalBackend phase 3 failed to initialize after retries
M45040FatalPort binding conflict: two serve declarations request the same (host, port)
M45041WarningProtocol server bound to a non-default port; clients must be reconfigured
M45050FatalProvider registration phase 4 failed: required token has no provider
M45051WarningProvider registration phase 4: duplicate provider for token; resolved per RFC-0041 §9.3
M45060FatalInstall reconciliation phase 5 failed; see RFC-0041 diagnostics
M45070Warning/healthz probe returning 200 but /readyz returning 503 for >5 minutes; runtime may be stuck in boot
M45080WarningDrain timeout exceeded; cancelling in-flight requests
M45081FatalDrain failed to complete within GNOMON_SHUTDOWN_TIMEOUT; supervisor escalation expected
M45090InfoRuntime 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

  1. /healthz returns 200 whenever the process is alive and MUST NOT depend on backend, configuration, or downstream services. (enforced by: runtime)
  2. /readyz returns 200 only between Phase 7 ready and SIGTERM receipt. (enforced by: runtime)
  3. Boot phases 0–7 execute in order and each must succeed before the next runs. (enforced by: runtime)
  4. Cancelled in-flight requests in drain phase S4 do NOT mark idempotency keys complete. (enforced by: runtime)
  5. Drain MUST complete within GNOMON_SHUTDOWN_TIMEOUT. (enforced by: runtime)
  6. Exit codes 3, 4, 5, 7, 8, 9 indicate fatal misconfiguration or artifact errors and MUST NOT be auto-restarted. (enforced by: supervisor policy)
  7. The deployable unit is the (runtime image, compiled bundle) pair; both are immutable, content-hashed artifacts. (enforced by: content-hash verification)
  8. 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

  1. MUST — Backend retry policy on transient failures MUST be bounded.
  2. MUST — Host MUST surface install failure diagnostics for operator review. (proof citation: rfc0045_b22_grounded; verification pending)
  3. MUST — Supervisor MUST treat exit code 3 as a fatal misconfiguration with no automatic restart.
  4. MUST — Supervisor MUST treat exit code 4 as a fatal artifact error.

Compatibility and Migration

  1. MUST — Existing deployments MUST adopt /healthz and /readyz endpoints if not already served.
  2. MUST — Existing deployments MUST honor SIGTERM with the drain semantics defined in section 8.
  3. SHOULD — Legacy deployments SHOULD migrate to the GNOMON_* environment variable prefix.

Deployable Unit

  1. MUST — Host MUST refuse to start when bundle ABI version mismatches the runtime image.
  2. MAY — Multiple bundles MAY be served by the same runtime image and multiple runtime image versions MAY serve the same bundle.
  3. MUST — Runtime MUST verify the bundle’s content hash against the value embedded in the bundle metadata.

Environment Variables

  1. MAY — Any module configuration value MAY be overridden via env var using GNOMON_CONFIG____.

Graceful Shutdown

  1. MUST — Drain MUST be bounded by GNOMON_SHUTDOWN_TIMEOUT (default 30 seconds).
  2. MUST — Drain phases S3-S6 MUST complete within the timeout bound; otherwise the runtime exits with code 2.
  3. MUST — Supervisor MUST escalate when drain timeout exceeds the bound.

Health and Readiness

  1. MUST_NOT — /healthz MUST NOT depend on backend, configuration, or downstream services.
  2. MUST — Per-protocol health endpoints MUST report the same readiness state as /readyz.

Invariants

  1. MUST — Drain MUST complete within GNOMON_SHUTDOWN_TIMEOUT.
  2. MUST_NOT — Exit codes 3, 4, 5, 7, 8, 9 MUST NOT be auto-restarted.
  3. MUST_NOT — Runtime MUST NOT corrupt state on resource exhaustion.

Port Binding

  1. MAY — Protocol servers MAY be configured for TLS via per-serve configuration.
  2. MUST — Runtime MUST honor TLS configuration per protocol server independently.

Supervision

  1. MUST — Runtime MUST handle out-of-memory by exiting cleanly rather than corrupting state.
  2. SHOULD_NOT — Supervisor SHOULD NOT auto-restart on exit codes 3, 4, 5, 7, 8, 9 (configuration or artifact errors).
  3. SHOULD — Supervisor SHOULD restart the runtime on exit code 1 (panic) with exponential backoff capped at 60s.
  4. SHOULD — Supervisors SHOULD probe /healthz every 10 seconds and /readyz every 5 seconds.

Linked References

DirectionTarget
Depends onRFC-0001
Depends onRFC-0002
Depends onRFC-0005
Depends onRFC-0006
Depends onRFC-0007
Depends onRFC-0008
Depends onRFC-0024
Depends onRFC-0033
Depends onRFC-0034
Depends onRFC-0036
Depends onRFC-0037
Depends onRFC-0038
Depends onRFC-0039
Depends onRFC-0040
Depends onRFC-0041