Enhancement Proposals (EPs)

Design proposals for re-frame2 which follow the Python Enhancement Proposal model. The project goal is to drive the coding work using detailed specifications (which are just really good prompts), and these EPs are an example of such prompts.

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), Type: is standards-track or process, and 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 and the document conventions — is normative in EP-0009. scripts/check_ep_status_sync.py is the mechanical gate (status/Type grammar + README/header sync).

Index

EP	Title	Status	Summary
EP-0001	Frame App/Runtime Partitions	final	A frame owns two durable partitions — user-owned app-db (:db) and framework-owned runtime-db (:rf.db/runtime) — committed coherently by one cascade, removing the footgun where a fresh :db return clobbers runtime state.
EP-0002	Explicit Frame Target Resolution	final	Remove the ambient :rf/default fallback; frame-scoped operations resolve their target from explicit frame context, and missing context fails instead of touching the wrong frame.
EP-0003	Resource Queries	final	An optional day8/re-frame2-resources artefact for declarative server-state — the re-frame2 answer to TanStack Query / RTK Query / SWR — with resource identity, caching, invalidation, a frame work-ledger substrate, lifecycle/GC, and route + SSR preload. HTTP-only scope graduated to the normative spec/016-Resources.md; GraphQL deferred.
EP-0004	Parametric Subscription Inputs	final	Restore v1's two-function reg-sub shape via input functions that return a vector of query vectors, keeping :<- as static-input sugar and dependencies pure, inspectable, JVM-runnable, and Xray-visible.
EP-0005	Machine :data Schema	final	Rename reg-machine's :schema key to :data-schema for the machine's :data context, close the schema→marks redaction bridge, switch machines-viz to declared-over-inferred Context shape, and document XState v5 parity.
EP-0006	Runtime Subsystem Contract	final	Name the five-clause shape every :rf.runtime/* child already implements — reserved sub-tree, write authority, read API, projection policy, teardown contract — as a gradeable contract (the durable-state analogue of Managed-Effects), with a grading table for the existing subsystems and a graduation checklist for EP-0003's. Graduated into spec/Runtime-Subsystems.md; the two derived rules ported there too.
EP-0007	One Name Per Fact	active	The naming rulebook — one canonical spelling per fact per layer, no stable accepted synonyms, cross-layer vocabulary distinctions recorded as rules — plus the finite sweep of current instances (frame stamp, partition prefixes, work-ledger identities, redirect synonyms, reg-*/register-*, the :schema family).
EP-0008	Production Observability Channels	final	Name the three failure-category channels (causal / diagnostic / always-on error) and the promotion criterion for production-survivable failures; audit the error catalogue against it and fix the gaps. Graduated into spec/009-Instrumentation.md (channel contract + catalogue channel column). Frame-teardown failures — previously production-silent — promote to a single always-on :rf.error/frame-teardown-failed report (Open Issue 1, ruled); implementation tracked in the errata ledger.
EP-0009	The EP Process	active	The PEP-1 analogue: EP types (standards-track / process), status/type grammar, the full status lifecycle (incl. rejected / withdrawn / deferred / superseded-by — all kept), the durability rules, the errata-ledger pattern, and the EP-worthiness bar.
EP-0010	Causal World Inputs	final	Make replay determinism literal by requiring time, randomness, UUIDs, and other host facts that affect durable frame-state to arrive on causal envelopes or explicit coeffects, while keeping ambient reads for diagnostics and host-transient scheduling. Core slice graduated into spec/002-Frames.md §Recordable coeffects (the envelope field :rf.world/inputs was later renamed to :rf.cofx by EP-0017); remaining wave steps tracked in the EP's errata ledger.
EP-0011	Uniform Async Reply Envelope	final	Define one normalized continuation/reply shape for managed asynchronous effects so HTTP, resources, timers, routing, and machines can share work-ledger correlation, stale suppression, cancellation, tracing, and causal completion metadata. Canonical contract graduated to spec/Managed-Effects.md §Property 9; all four shipped async families lower onto the one re-frame.reply substrate and the inheritance claim is conformance-proven by a test-only managed-timer probe. Two non-blocking follow-ups (rf2-lohbfg, rf2-mdjzs0) tracked in the implementation-errata ledger.
EP-0012	Path Optics And Canonical Forms	final	Define one lightweight :rf/path vocabulary, canonical EDN identity for params/scopes/work ids, and routing parse/print round-trip laws so path and identity semantics stop being redefined per subsystem.
EP-0013	App Values And Runtime Realms	superseded-by EP-0023	Define the long-term architecture where app programs are composable values installed into runtime realms that own registrar, adapter, capabilities, and host-transient subsystem state, with today's global reg-* calls retained as default-realm sugar. The realm container (D1) and the app-value projection/construction/install surface (D2) shipped and graduated into spec/Runtime-Subsystems.md §Runtime realms; a v1 constructed realm is a static-install + query-isolated container. EP-0023 partially supersedes the public app/realm surface (the image -> frame -> event stream model); EP-0013's isolation decisions and realm machinery are retained as the internal installation substrate, and the live-resolution invariant is realized at the frame boundary.
EP-0014	Derivation And Process Algebra	final	Name the common model behind subscriptions, runtime subscriptions, flows, resources, and machine selectors as declared inputs, output, storage, evaluation, and lifecycle, while keeping existing APIs as source forms.
EP-0015	Frame-Owned Egress Policy	final	Define one public model for sensitive/large classification, trust-boundary projection, and observability sink policy: frame-owned durable policy, registration-owned transient policy, centralized projection, and projected sinks.
EP-0016	Resource Mutation Completion, Scoped Invalidation Targets, And Named Scope Resolution	final	Complete the RealWorld-exposed Spec 016 gaps: mutation reply continuations, mixed-scope invalidation, named scope resolvers, populate-as-authoritative-load, map-form exact targets, and managed-HTTP request-decoration doctrine while deferring optimistic rollback.
EP-0017	Recordable Coeffects	final	Unify the coeffect surface around "durable state folds facts, never reads": rename :rf.world/inputs to a flat :rf.cofx, add :rf.cofx/requires declared-only delivery for both coeffect grades, remove inject-cofx, make reg-cofx a value-returning graded registrar (app-owned generators, provided boundary facts, :rf/time-ms as the one framework registration), and enforce strict replay/test modes.
EP-0018	One Event Registration Surface	final	Collapse the three public event forms to one — reg-event (= today's reg-event-fx, coeffects in / effects out): remove reg-event-db, demote reg-event-ctx to framework-internal (full-context work moves to interceptors), closing the EP-0017 hole where a db handler cannot declare coeffects. Seven design decisions ruled; sequenced behind EP-0017.
EP-0019	Optimistic Mutation Rollback For Resources	final	The optimistic-write follow-on EP-0016 issue 9 defers: a registration-level :optimistic forward plan (the twin of :patches) applied before the server confirms, with a runtime-recorded snapshot inverse + per-entry revision token, a deterministic commit/rollback/reconcile settle protocol, conflict-aware :on-conflict :invalidate (defer to the read path, the divergence from TanStack/SWR's unconditional restore), tag-addressed :optimistic-tags for cross-view consistency, and the reserved instance/trace slots filled. Graduated into spec/016-Resources.md §Optimistic mutations. Closes the most visible TanStack/RTK/SWR parity gap.
EP-0020	Active-Owner Polling For Resource Revalidation	final	Add a declarative :poll-interval-ms resource policy that revalidates an active-owner entry on a fixed interval — owner-driven (not component-driven), pausing on owner release and hidden tab — reusing the landed stale/GC advisory-timer substrate and the focus/reconnect scan-and-refetch core. Graduated into spec/016-Resources.md §Polling; completes the deferred polling slice of Spec 016.
EP-0021	Infinite Resources And Load-More Feeds	final	Add a first-class infinite-resource / load-more primitive to Spec 016 (the reserved :infinite key): one scoped entry per feed with pages accumulated as the ordered durable value, a pure :next-page-param derivation (nil = terminal), a causal :rf.resource/load-more event, and a merged-list + page-metadata subscription family. Aligns to TanStack useInfiniteQuery / SWR useSWRInfinite with three re-frame2 divergences (runtime-owned cursor, single nil terminal, fail-closed scoped feed identity). Graduated into spec/016-Resources.md; seven open questions + the :request signature resolved (see EP Resolved Decisions).
EP-0022	Registered Interceptors	final	Make interceptors first-class registered program facts after EP-0018: application interceptors are authored with reg-interceptor, event/frame chains carry serializable refs only, overrides match exact refs, frame metadata remains the frame-local global mechanism, and :rf.interceptor/path is the sole standard interceptor because it is coupled to app-db commit no-op semantics. unwrap migrates to handler destructuring or project registration.
EP-0023	Images And Frame-Loaded Instruction Sets	final	Replace the public EP-0013 app/realm teaching surface with image-loaded frames: rf/image selects registration sets, frames run sealed image generations, namespace provenance enables same-id examples without clobbering, and public operations target the frame while realms remain internal installation machinery. Graduated 2026-06-16; partially supersedes EP-0013.
EP-0024	Unified Frame Identity And Lifecycle	final	Finish the post-EP-0023 frame collapse: one live frame value, one registry, one public frame-target grammar, explicit UI-owned lifecycle, and named generation reads if registrar tooling needs them.