RFC-036: Atomic runtime activation and graph supervision

[aaltshuler]

Summary

Defines how a complete graph runtime is built away from traffic and activated as one immutable generation.

Key decisions:

• one generation contains engine, accepted catalog, policy, queries, providers, witnesses, admission, and correctness caches;
• every writable candidate uses the RFC-034 no-effect writable-open mode and retains one finalized recovery guard through the activation store;
• activation publishes one fresh RFC-035 serving cell and never mutates a serving engine in place;
• generation-local caches structurally prevent stale asynchronous cache fills from crossing a replacement;
• managed recovery is roll-forward-only; compensation becomes operator-required and remains offline in V1;
• typed transition drain parks blocked graphs without holding global scheduler capacity;
• bounded fair supervisors, hard read-only capabilities, and rolling-safe graph availability status are derived from one runtime state.

This is a design document only. It changes no runtime or storage format.

Scope boundary

RFC-036 owns immutable runtime generations, activation, availability supervision, retry scheduling, and status. RFC-034 owns durable recovery. RFC-035 owns served-operation lifetime and shutdown. PR #491 owns substrate failure classification.

Series

• RFC-034 durable recovery authority: RFC-034: Durable recovery authority and outcomes #496
• RFC-035 served operation ownership: RFC-035: Served operation ownership #498
• Replaces the implementation direction in Supervise configured graph availability, with typed failures #489.
• PR Carry a typed classification on storage failures #491 remains independent and unchanged.

Recommended review and merge order: RFC-034, RFC-035, RFC-036.

Validation

• AGENTS and docs index check
• Markdown whitespace checks
• all external references returned HTTP 200
• independent adversarial and final cross-series reviews; final result: no findings

Greptile Summary

This draft RFC defines immutable graph-runtime generations, atomic activation, and bounded graph availability supervision without changing runtime code or durable formats.

• Builds coherent candidates away from serving and publishes them through one serving-cell activation point.
• Defines recovery-guard ownership, transition draining, generation-local cache isolation, and hard read-only capabilities.
• Specifies bounded supervision, retry behavior, rolling-safe availability status, and required implementation evidence.

Confidence Score: 5/5

The documentation-only PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs/rfcs/0036-atomic-runtime-activation.md	Adds the RFC for coherent runtime generation construction, atomic serving-cell replacement, availability supervision, compatibility, and acceptance evidence.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Applied graph configuration] --> B[Transition drain]
    B -->|Drained proof| C[Recovery disposition]
    C -->|Clean / finalized guard| D[Build fresh immutable generation]
    C -->|Roll forward required| E[Bounded recovery continuation]
    E --> C
    C -->|Blocked or compensation required| F[Blocked graph state]
    D --> G[Validate witness and activation fences]
    G --> H[Close predecessor lanes]
    H --> I[Register fresh serving cell]
    I --> J[Atomic runtime-state store]
    J --> K[Release recovery guard]
    J --> L[Retire predecessor after drain]

Loading

_{Reviews (2): Last reviewed commit: "docs(rfc): define atomic runtime activat..." | Re-trigger Greptile}