RFC-0045 · Process and Hosting Model
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.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.
1. Purpose
This RFC defines what it means to deploy and run an Gnomon app: the contract any host (Kubernetes, fly.io, ECS, bare metal) must satisfy. It specifies the deployable unit, the boot sequence, well-known environment variables, port-binding conventions, health and readiness endpoints, graceful shutdown semantics, and supervision expectations.
This RFC explicitly does NOT specify the orchestrator, container format, or runtime image language. It defines the contract; conforming hosts MAY be implemented in any language and packaged in any container or unikernel format.
2. Definitions
| Term | Meaning |
|---|---|
| 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. |
| Deployable unit | The pair (runtime image, compiled bundle). Both are versioned, immutable artifacts. |
| Compiled bundle | The build artifact produced by the Gnomon compiler (RFC-0002): all installed modules, dependency closure, manifest hashes. |
| Boot sequence | The deterministic phases the runtime executes from process start to ready-to-serve. |
| Drain | The process of completing in-flight work, refusing new work, and releasing resources during shutdown. |
| Supervisor | The orchestrator’s component that starts, restarts, and terminates runtime processes. The host’s responsibility, not Gnomon’s. |
3. Deployable Unit
3.1 Components
A deployable unit consists of two artifacts:
- A runtime image — the Gnomon runtime executable, packaged for the host platform.
- A compiled bundle — the modules to be served, in the format defined by RFC-0002.
The two are independently versioned. Multiple bundles MAY be served by the same runtime image; multiple runtime image versions MAY serve the same bundle.
3.2 Bundle resolution
The bundle is loaded at boot from the path identified by the GNOMON_BUNDLE_PATH environment variable (§5.1). The path MAY be local (filesystem) or remote (a registry URL). The runtime MUST verify the bundle’s content hash against the value embedded in the bundle metadata; mismatch is a fatal boot error (M45010).
3.3 Image-bundle compatibility
The runtime image declares the bundle ABI version it supports. Bundles declare the ABI version they require. Mismatch is a fatal boot error (M45011); the host MUST refuse to start.
The bundle ABI version is the major component of the runtime’s release version. Patch and minor compatibility within an ABI is guaranteed.
4. Boot Sequence
The runtime executes the following phases in order at process start. Each phase has a defined success and failure mode:
Phase 0 — Process initialization (env parsing, signal handler install)
Phase 1 — Bundle load and content-hash verification
Phase 2 — Configuration resolution (RFC-0046)
Phase 3 — Backend service initialization (RFC-0037)
Phase 4 — Provider registration (RFC-0040 §5)
Phase 5 — Module install reconciliation (RFC-0041)
Phase 6 — Protocol server bindings (RFC-0034)
Phase 7 — Health/readiness signal: ready
Phase 8 — Serve loop
4.1 Phase 0: process initialization
The runtime parses well-known environment variables (§5), installs SIGTERM and SIGINT handlers, and initializes its log sink.
A failure in this phase exits with code 3 and a startup-error log line. The supervisor MUST treat exit code 3 as a fatal misconfiguration (no automatic restart).
4.2 Phase 1: bundle load
The runtime loads the bundle from GNOMON_BUNDLE_PATH, verifies its content hash, and validates the manifest envelope.
Failure exits with code 4. The supervisor MUST treat exit code 4 as a fatal artifact error.
4.3 Phase 2: configuration resolution
The runtime materializes the layered configuration (RFC-0046): bundle defaults → environment variables → secrets vault. Required-but-missing configuration values exit with code 5.
4.4 Phase 3: backend service initialization
The runtime initializes the graph backend (RFC-0037 §5). For Postgres backends, this includes connection pool startup and migration check; for memory backends, heap initialization.
Backend connection failures exit with code 6. Transient backend failures (network unavailable) MAY trigger a configurable retry loop before exit; the retry policy is an implementation choice but MUST be bounded.
4.5 Phase 4: provider registration
The runtime walks the bundle’s providers: declarations (RFC-0040 §5.2) and registers each implementation in the DI registry. Conflicts (duplicate token, M40041) emit warnings; missing providers for required tokens (M40040) abort boot with exit code 7.
4.6 Phase 5: install reconciliation
The runtime invokes the install engine (RFC-0041) to reconcile the bundle’s module set against installed state in the graph backend. The lifecycle policy (RFC-0041 §5) decides per-module strategy.
Install failures abort boot with exit code 8. The host MUST surface the failure diagnostic (RFC-0041 §15) for operator review.
4.7 Phase 6: protocol server bindings
For each serve declaration in the bundle (RFC-0034), the runtime starts the corresponding protocol server. Default ports are documented per protocol; explicit overrides via configuration are honored.
Port binding failures (port in use, EACCES) abort boot with exit code 9.
4.8 Phase 7: ready signal
When phases 1–6 complete successfully, the runtime emits a ready signal:
- The
/readyzHTTP endpoint (§7) begins returning 200. - A
runtime.readyaudit log entry is emitted (RFC-0047) with the runtime version, bundle version, and phase durations. - An optional
READY_FDfile descriptor is closed (when the host populatesREADY_FDvia systemd notify protocol or similar).
4.9 Phase 8: serve loop
The runtime accepts incoming requests, dispatches them to the operation runtime (RFC-0043), and emits audit/trace data (RFC-0047). The serve loop continues until SIGTERM (§9).
5. Environment Variables
Well-known environment variables. Names use the prefix GNOMON_.
5.1 Required
| Variable | Purpose |
|---|---|
GNOMON_BUNDLE_PATH | Path or URL to the compiled bundle (§3.2). |
GNOMON_TENANT_MODE | One of single (single-tenant) or multi (multi-tenant with RLS context). |
5.2 Conventional
| Variable | Default | Purpose |
|---|---|---|
GNOMON_HOST | 0.0.0.0 | Bind host for protocol servers. |
GNOMON_HTTP_PORT | 8080 | HTTP protocol server port (RFC-0025). |
GNOMON_GRPC_PORT | 9090 | gRPC protocol server port (RFC-0026). |
GNOMON_GRAPHQL_PORT | 9091 | GraphQL protocol server port (RFC-0027). |
GNOMON_TRPC_PORT | 9092 | tRPC protocol server port (RFC-0029). |
GNOMON_LOG_LEVEL | info | One of trace, debug, info, warn, error. |
GNOMON_LOG_FORMAT | json | One of json, text. |
GNOMON_CONFIG_PATH | <bundle>/config | Path to per-environment configuration overrides (RFC-0046). |
GNOMON_SECRETS_BACKEND | env | Secrets backend identifier; one of env, vault, aws-sm, gcp-sm, plus host-specific extensions. |
GNOMON_TENANT_DEFAULT | (none) | Default tenant id when in multi mode (used for system installs). |
5.3 Configuration overrides
Any module configuration value MAY be overridden via env var using the convention:
GNOMON_CONFIG__<module-namespace>__<key> = <value>
The double-underscore separator avoids collision with single-word identifiers. RFC-0046 §3 specifies the full layering and resolution order.
6. Port Binding
6.1 Per-protocol defaults
Each protocol server binds to GNOMON_HOST:<protocol-specific-port>. Defaults from §5.2.
6.2 Multiple bindings
When the bundle declares multiple serve declarations for the same protocol (e.g., a public API and an admin API both over HTTP), each binding requires a unique port. The bundle author specifies the port via a serve-level slot:
serve PublicAPI {
api: ExternalAPI
protocol: http
port: 8080
...
}
serve AdminAPI {
api: InternalAPI
protocol: http
port: 8081
...
}
When port: is omitted, the protocol’s default port from §5.2 is used. Conflicting port assignments at boot abort with exit code 9 (M45040).
6.3 TLS
Protocol servers MAY be configured for TLS via per-serve configuration (tls.cert, tls.key). RFC-0034 covers the per-protocol TLS slot semantics; this RFC specifies that the runtime MUST honor TLS configuration per-protocol-server independently.
7. Health and Readiness
The runtime exposes two HTTP endpoints, regardless of the protocols declared in the bundle. They bind to GNOMON_HOST:GNOMON_HTTP_PORT:
7.1 /healthz
Liveness check. Returns 200 with body OK whenever the runtime process is alive and responsive. Returns nothing if the process is unresponsive (the supervisor’s TCP probe fails).
The /healthz endpoint MUST NOT depend on backend, configuration, or downstream services. It is a pure liveness signal.
7.2 /readyz
Readiness check. Returns:
- 200 with body
READYonce Phase 7 (ready signal) has completed. - 503 with body
NOT_READYduring phases 0–6 and after Phase 9 (drain) has begun.
Body MAY include structured detail in JSON form when the request includes Accept: application/json:
{
"ready": true,
"phase": "serve",
"bundleVersion": "<semver>",
"runtimeVersion": "<semver>",
"uptimeMs": <number>,
"lastError": null
}
7.3 Per-protocol health hooks
Protocol-specific health endpoints (e.g., gRPC Health.Check) MUST be implemented per RFC-0026 et al. They report the same readiness state as /readyz.
8. Graceful Shutdown
8.1 Signal handling
The runtime handles SIGTERM as the canonical shutdown signal. SIGINT is treated identically (for development). SIGKILL bypasses graceful shutdown (the supervisor’s escalation path).
8.2 Drain phases
Upon receiving SIGTERM:
S1 — /readyz starts returning 503 NOT_READY (immediately)
S2 — Stop accepting new connections on protocol servers
S3 — Wait for in-flight requests to complete (bounded by GNOMON_SHUTDOWN_TIMEOUT, default 30s)
S4 — Cancel any remaining in-flight requests; rollback their transactions
S5 — Close protocol server listeners
S6 — Close backend connections (commit any in-flight transactions in S3)
S7 — Final audit log emission (`runtime.shutdown`)
The drain MUST bound at GNOMON_SHUTDOWN_TIMEOUT (default 30 seconds). Phases S3–S6 MUST complete within the bound; if not, the runtime exits with code 2 (uncle shutdown) and the supervisor MUST escalate.
Successful drain exits with code 0.
8.3 In-flight idempotency
When a request is cancelled in S4, its idempotency key (RFC-0043 §6) is NOT marked complete. A retry by the caller with the same key starts fresh and proceeds to completion. This ensures shutdown does not leave half-applied mutations from the caller’s perspective.
9. Supervision
9.1 Restart expectations
The host’s supervisor SHOULD restart the runtime on:
- Exit code 0 (clean shutdown) — only restart on operator request, not automatically.
- Exit code 1 (panic / unhandled exception) — restart with backoff (recommended: exponential, max 60s).
- Exit codes 2, 6 (drain timeout, transient backend failure) — restart with backoff.
- Exit codes 3, 4, 5, 7, 8, 9 (configuration/artifact error) — DO NOT auto-restart; surface to operator.
9.2 Health probe period
Supervisors SHOULD probe /healthz every 10 seconds (liveness) and /readyz every 5 seconds (readiness). Failure thresholds are operator-specific; recommended defaults: 3 consecutive /healthz failures = unhealthy; 1 /readyz failure = unready.
9.3 Resource limits
This RFC does NOT specify resource limits (CPU, memory, file descriptors). Operators set these via the host’s mechanism. The runtime MUST handle out-of-memory by exiting cleanly (panic → exit code 1 → supervisor restart) rather than corrupting state.
10. Invariants
- The deployable unit is
(runtime image, compiled bundle); both are immutable, content-hashed artifacts (§3). - Boot phases 0–7 execute in order; each must succeed before the next runs (§4).
- Exit codes 3, 4, 5, 7, 8, 9 indicate fatal misconfiguration or artifact errors and MUST NOT be auto-restarted (§9.1).
/healthzreturns 200 whenever the process is alive (§7.1)./readyzreturns 200 only between Phase 7 ready and SIGTERM (§7.2).- Drain MUST complete within
GNOMON_SHUTDOWN_TIMEOUT(§8.2). - Cancelled in-flight requests in S4 do NOT mark idempotency keys complete (§8.3).
- The runtime MUST NOT corrupt state on resource exhaustion; OOM exits cleanly (§9.3).
11. Compatibility and Migration
This RFC formalizes contracts that are de-facto in the legacy runtime but not previously specified. There is no legacy field-by-field mapping; the relevant migration is operational:
- Existing deployments MUST adopt
/healthzand/readyzendpoints if they don’t already serve them. - Existing deployments MUST honor SIGTERM with the drain semantics defined in §8.
- The
GNOMON_*environment variable prefix is new; legacy deployments MAY continue using their existing variables but SHOULD migrate.
Diagnostics
The diagnostic catalog for this RFC is authored in the structured Lean module and
rendered in reference catalog § Diagnostics. Inline mentions in
the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog
at render time.
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.