gnomonlearn
Docs/Hosting/RFC-0045

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

TermMeaning
Runtime imageThe executable container or binary that hosts an Gnomon runtime. Includes the runtime kernel, its supporting services, and the loader for compiled bundles.
Deployable unitThe pair (runtime image, compiled bundle). Both are versioned, immutable artifacts.
Compiled bundleThe build artifact produced by the Gnomon compiler (RFC-0002): all installed modules, dependency closure, manifest hashes.
Boot sequenceThe deterministic phases the runtime executes from process start to ready-to-serve.
DrainThe process of completing in-flight work, refusing new work, and releasing resources during shutdown.
SupervisorThe 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 /readyz HTTP endpoint (§7) begins returning 200.
  • A runtime.ready audit log entry is emitted (RFC-0047) with the runtime version, bundle version, and phase durations.
  • An optional READY_FD file descriptor is closed (when the host populates READY_FD via 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

VariablePurpose
GNOMON_BUNDLE_PATHPath or URL to the compiled bundle (§3.2).
GNOMON_TENANT_MODEOne of single (single-tenant) or multi (multi-tenant with RLS context).

5.2 Conventional

VariableDefaultPurpose
GNOMON_HOST0.0.0.0Bind host for protocol servers.
GNOMON_HTTP_PORT8080HTTP protocol server port (RFC-0025).
GNOMON_GRPC_PORT9090gRPC protocol server port (RFC-0026).
GNOMON_GRAPHQL_PORT9091GraphQL protocol server port (RFC-0027).
GNOMON_TRPC_PORT9092tRPC protocol server port (RFC-0029).
GNOMON_LOG_LEVELinfoOne of trace, debug, info, warn, error.
GNOMON_LOG_FORMATjsonOne of json, text.
GNOMON_CONFIG_PATH<bundle>/configPath to per-environment configuration overrides (RFC-0046).
GNOMON_SECRETS_BACKENDenvSecrets 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 READY once Phase 7 (ready signal) has completed.
  • 503 with body NOT_READY during 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

  1. The deployable unit is (runtime image, compiled bundle); both are immutable, content-hashed artifacts (§3).
  2. Boot phases 0–7 execute in order; each must succeed before the next runs (§4).
  3. Exit codes 3, 4, 5, 7, 8, 9 indicate fatal misconfiguration or artifact errors and MUST NOT be auto-restarted (§9.1).
  4. /healthz returns 200 whenever the process is alive (§7.1).
  5. /readyz returns 200 only between Phase 7 ready and SIGTERM (§7.2).
  6. Drain MUST complete within GNOMON_SHUTDOWN_TIMEOUT (§8.2).
  7. Cancelled in-flight requests in S4 do NOT mark idempotency keys complete (§8.3).
  8. 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 /healthz and /readyz endpoints 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.