Enhancement proposals (EPs)¶
Enhancement proposals record re-frame2 design decisions and their rationale, following the Python Enhancement Proposal model. Accepted proposals guide changes to the specification and implementation. Resolved proposals remain as historical records, with dated notes for later decisions.
The EP process itself — types, status lifecycle, durability rules, and the EP-worthiness bar — is normative in EP-0009. This README is only the index and summary.
Authoring a new EP¶
Copy EP-template.md to EP-NNNN-<slug>.md, fill it in, and add an index row below. The template encodes the active-process rules so a new EP follows them by construction: Status: is a controlled lifecycle (not free text), and Type: is standards-track or process. Graduation is per-type — standards-track into spec/, process into its named normative home (which may be the active EP itself). The full process — including the EP-worthiness bar, bidirectional successor records, and document conventions — is normative in EP-0009. scripts/check_ep_status_sync.py is the mechanical gate (status/type grammar, lifecycle metadata, supersession targets, and README/header sync).
Index¶
| EP | Title | Status | Summary |
|---|---|---|---|
| EP-0001 | Frame App/Runtime Partitions | final | Separates user-owned app-db from framework-owned runtime-db and commits both coherently. Later event authoring uses EP-0018. |
| EP-0002 | Explicit Frame Target Resolution | final | Requires explicit frame context for frame-scoped operations. EP-0024 later refines the target grammar and lifecycle while preserving this rule. |
| EP-0003 | Resource Queries | final | Introduces declarative resources, caching, invalidation, and lifecycle management. HTTP resources graduated into Spec 016; GraphQL remains deferred. EP-0037 refines route planning. |
| EP-0004 | Parametric Subscription Inputs | final | Declares static or parametric subscription dependencies under the registration metadata key :inputs. |
| EP-0005 | Machine :data Schema |
final | Records the original machine :data-schema decision. EP-0029 replaces it with [:schemas :data], and EP-0025 replaces schema-based durable classification. |
| EP-0006 | Runtime Subsystem Contract | final | Defines the five-clause runtime-subsystem contract and its grading table. The normative home is Runtime Subsystems. |
| EP-0007 | One Name Per Fact | active | Requires one canonical spelling for each fact within a layer, with vocabulary differences between layers documented explicitly. |
| EP-0008 | Production Observability Channels | final | Defines causal, diagnostic, and always-on error channels, including production reporting for teardown failures. The contract lives in Spec 009. |
| EP-0009 | The EP Process | active | Defines the EP lifecycle, when a proposal is warranted, and how decisions and later amendments remain discoverable. |
| EP-0010 | Causal World Inputs | final | Requires host facts that affect durable state to arrive as recorded inputs. EP-0017 later consolidates the delivery surface under :rf.cofx. |
| EP-0011 | Uniform Async Reply Envelope | final | Defines a common reply envelope for managed asynchronous effects, including correlation, stale-reply suppression, and cancellation. The contract lives in Managed Effects. |
| EP-0012 | Path Optics And Canonical Forms | final | Defines shared path optics, canonical EDN identities, and routing parse/print laws. |
| EP-0013 | App Values And Runtime Realms | superseded-by EP-0023 | Records the app-value and runtime-realm design superseded by EP-0023. Its initially retained multi-realm substrate was subsequently removed; current operations target frames. |
| EP-0014 | Derivation And Process Algebra | final | Describes subscriptions, flows, resources, and machine selectors through a common model of inputs, outputs, storage, evaluation, and lifecycle. |
| EP-0015 | Frame-Owned Egress Policy | final | Records the original frame-owned egress policy. EP-0025 retains centralized projection and replaces durable annotations and propagation with definition-site classification. |
| EP-0016 | Resource Mutation Completion, Scoped Invalidation Targets, And Named Scope Resolution | final | Completes mutation replies, scoped invalidation, named scope resolution, and authoritative resource population. EP-0019 supplies the deferred optimistic rollback design. |
| EP-0017 | Recordable Coeffects | final | Unifies recorded coeffects under :rf.cofx, declares required inputs, and makes coeffect registrations return values. Replay and tests enforce the declared input contract. |
| EP-0018 | One Event Registration Surface | final | Makes reg-event the public event registration form: coeffects in, effects out. Full-context processing belongs to interceptors. |
| EP-0019 | Optimistic Mutation Rollback For Resources | final | Adds optimistic resource updates with recorded inverse patches, revision checks, and conflict-aware settlement. The contract lives in Spec 016. |
| EP-0020 | Active-Owner Polling For Resource Revalidation | final | Adds resource-level polling while an owner is active, with suspension on release or a hidden tab. The contract lives in Spec 016. |
| EP-0021 | Infinite Resources And Load-More Feeds | final | Adds infinite resources with accumulated pages, derived page parameters, and explicit load-more events. The contract lives in Spec 016. |
| EP-0022 | Registered Interceptors | final | Makes interceptors registered program facts. Event and frame chains use serializable references; :rf.interceptor/path remains the standard app-db path interceptor. |
| EP-0023 | Images And Frame-Loaded Instruction Sets | final | Introduces image-loaded frames as the public programming model. EP-0024, EP-0026, and EP-0027 refine identity, image authoring, and construction. |
| EP-0024 | Unified Frame Identity And Lifecycle | final | Defines one live frame value, one registry, an explicit target grammar, and view-owned lifecycle. |
| EP-0025 | Data Classification | final | Defines classification at data definition sites and projection at observability boundaries. This is a hygiene aid for sensitive or large data, rather than a security boundary. |
| EP-0026 | Image API Simplification | final | Simplifies image selection and layer composition, reports deterministic shadows, and removes image capabilities. EP-0028 holds the deferred overlay and inline-coordinate proposals. |
| EP-0027 | Frame Initial Events | final | Uses ordered :initial-events for frame setup, including app-db seeding. Construction runs outside handlers and fails if any setup event fails. |
| EP-0028 | Registration Overlays and Inline Image Authoring | deferred | Proposes a shared registration-overlay vocabulary and optional source coordinates for inline registrations. Deferred while replay and authoring choices remain unresolved. |
| EP-0029 | XState v6 Machine Parity | final | Records the machine-parity decisions prompted by XState v6: functions, schemas, timeouts, choice states, internal events, and completion output. The accepted contract lives in Spec 005. |
| EP-0030 | The Compiled-View Substrate Program (re-frame.ui) | superseded-by EP-0036 | Records the compiled-view programme absorbed by EP-0036. Freehand was later withdrawn; EP-0038 records the separate Fresco experiment. |
| EP-0031 | The re-frame.ui Programming Model | final | Records the historical compiled-view authoring model. Its substrate was absorbed into EP-0036 and later removed. |
| EP-0032 | re-frame.ui Reactivity and Ownership | final | Records compiled-view reactivity and ownership decisions. The surviving ownership laws live in Spec 006; the compiled substrate was later removed. |
| EP-0033 | re-frame.ui View Evidence and Debugging | superseded-by EP-0036 | Records the compiled-view evidence contract absorbed by EP-0036, before Freehand was withdrawn and removed. |
| EP-0034 | re-frame.ui Production, SSR, and Testing Posture | superseded-by EP-0036 | Records production, SSR, and testing requirements absorbed by EP-0036, before Freehand was withdrawn and removed. |
| EP-0035 | Component-Library Readiness | final | Records component-library amendments to the compiled-view model. That substrate was later removed; EP-0038 records the Fresco successor experiment. |
| EP-0036 | The Freehand View-Substrate Programme | withdrawn | Records Freehand, withdrawn on 2026-07-30 and removed on 2026-08-16. Its tear-check guarantee survives; EP-0038 records the separate Fresco experiment. |
| EP-0037 | Route Planning and Activation Ownership | accepted | Defines inspectable route planning, activation ownership, resource prefetch, entry decisions, and query carry. Views project route state while existing subsystems own data and asynchronous work. |
| EP-0038 | The Fresco View-Layer Programme | final | Records the Fresco programme and the graduation of its React arm as re-frame2's native view layer, with SSR required and adapters remaining supported. Its decisions are final; v0 completion is tracked as implementation errata. |