Ownership Matrix¶
Type: Reference The single source for "where does X live?" — every contract surface in re-frame2 has exactly one canonical home; other docs may reference the surface, but those references are informational and must not redefine the contract. Use this matrix to navigate, and to detect drift if a definition ever appears in a non-owning doc.
Every contract surface in re-frame2 has exactly one canonical home. Most canonical homes live in the /spec tree — that is the language-agnostic pattern. A small, deliberate set of contract surfaces has an external canonical home outside /spec, sanctioned by README §Canonical homes outside /spec): a tool-shared contract whose home stays with the tool artefact (tools/<tool>/spec/), or a CLJS-reference binding of a pattern-level obligation that ships in the implementation tree (implementation/...). External-home rows are flagged in the table below; they are indexed from this matrix even though they live elsewhere.
Other docs may reference any surface, but those references are non-normative — they cite the canonical home rather than redefining the contract. The "Referenced in" column lists those informational mentions.
Host scope. The pattern itself is scoped to the eight in-scope JS-cross-compile hosts defined in 000 §The pattern. Companion-doc rows below describe pattern-level contracts; non-target server-side hosts (Python, Ruby, Rust, server-side Kotlin / Java / Swift) are out of scope as first-class implementation targets, and surfaces that look "host-specific" are scoped to those eight.
The Artefact column names the Maven artefact that ships the surface in the CLJS reference. Surfaces marked core (split pending: <bead>) are currently in day8/re-frame2 and will move to day8/re-frame2-<feature-id> under the named bead (the concrete id is in the Artefact cell of each such row). The packaging architecture (artefact tiers, naming, independence rule) is normative in Conventions §Packaging conventions.
| Contract surface | Canonical home spec | Artefact | Referenced in (informational) |
|---|---|---|---|
| Goals, hard constraints, host-profile matrix, identity primitive, minimal-core contract | 000-Vision | spec-only (no runtime artefact) | Principles, Implementor-Checklist, API |
Registration grammar (reg-* shape, metadata map, two-form middle slot) |
001-Registration | day8/re-frame2 (core) |
API, Spec-Schemas §:rf/registration-metadata, Construction-Prompts |
Registry kind taxonomy (the canonical kind keyword set) |
001-Registration | day8/re-frame2 (core) |
API, Spec-Schemas |
| Source-coordinate capture (macro-driven, CLJS reference) | 001-Registration | day8/re-frame2 (core) |
Tool-Pair, 009-Instrumentation (trace events carry coords) |
| Hot-reload semantics for registrations | 001-Registration | day8/re-frame2 (core) |
002-Frames (sub-cache invalidation) |
Registry query API (registrations, handler-meta, frame-ids, frame-meta — registrar contract) |
001-Registration | day8/re-frame2 (core) |
002-Frames §The public registrar query API (re-tabulates alongside frame-runtime queries), Tool-Pair, 007-Stories |
Frame-runtime queries (app-db-value, snapshot-of, sub-topology, sub-cache) |
002-Frames | day8/re-frame2 (core) |
Tool-Pair, 008-Testing |
Frame model, identity, lifecycle, :rf/default fallback |
002-Frames | day8/re-frame2 (core) |
API, Spec-Schemas |
Event handlers (reg-event-fx, reg-event-db, the (state, event) → effects-map contract) |
002-Frames | day8/re-frame2 (core) |
API, Construction-Prompts CP-1, Pattern-AsyncEffect |
Dispatch envelope (dispatch, dispatch-sync, explicit-frame addressing, two-arg form) |
002-Frames | day8/re-frame2 (core) |
API, Tool-Pair |
subscribe (frame-bound and global forms; reg-sub registration surface) |
002-Frames | day8/re-frame2 (core) |
006-ReactiveSubstrate (the runtime cache & derivation graph the surface consumes), API, Construction-Prompts CP-2 |
| Subscription runtime — derivation graph, sub-cache, invalidation, change tracking, layer-1/2/3 semantics | 006-ReactiveSubstrate | day8/re-frame2 (core) |
002-Frames (registration & call-site surface), 008-Testing (compute-sub) |
subscribe-once (one-shot, non-reactive read; subscribe + deref + immediate unsubscribe) |
006-ReactiveSubstrate | day8/re-frame2 (core) |
API, 002-Frames (call-site surface), 008-Testing (compute-sub for the cache-bypassing pure equivalent) |
unsubscribe (explicit teardown; ref-count decrement; pairs with imperative subscribe) |
006-ReactiveSubstrate | day8/re-frame2 (core) |
API, 002-Frames (call-site surface) |
frame-provider (CLJS reference; React-context plumbing of frame keyword to subtree) |
002-Frames | day8/re-frame2 (core) |
004-Views, 007-Stories |
Effect-map shape (closed :db + :fx at top level) |
002-Frames | day8/re-frame2 (core) |
Spec-Schemas §:rf/effect-map, API |
Effects (reg-fx) and coeffects (reg-cofx) |
002-Frames | day8/re-frame2 (core) |
API, Pattern-AsyncEffect, 011-SSR (:platforms) |
| Run-to-completion drain semantics | 002-Frames | day8/re-frame2 (core) |
005-StateMachines (drain interaction), 008-Testing (synchronous triggers) |
Per-frame and per-call overrides (:fx-overrides, :interceptor-overrides, :interceptors) |
002-Frames | day8/re-frame2 (core) |
008-Testing, 007-Stories |
| Machines-as-event-handlers foundation hooks | 002-Frames | day8/re-frame2 (core) |
005-StateMachines (full grammar) |
View contract and reg-view (pure (state, props) → render-tree, Form-1/2/3) |
004-Views | day8/re-frame2 (core) |
API, 011-SSR, Construction-Prompts CP-4 |
State machine grammar and reg-machine (transition table, :always, :after, :spawn, :spawn-all, hierarchical states, :tags, :type :parallel + :regions, snapshot shape) |
005-StateMachines | day8/re-frame2-machines (rf2-xbtj) |
CP-5-MachineGuide, Pattern-NineStates, Pattern-WebSocket, Pattern-Boot, Pattern-LongRunningWork |
| Reactive substrate contract + reference adapters (Reagent default, plain-atom for JVM) | 006-ReactiveSubstrate | day8/re-frame2 (core) — substrate contract + plain-atom adapter; the Reagent adapter ships in day8/re-frame2-reagent |
008-Testing, 011-SSR |
UIx adapter (use-subscribe hook, flush-views! test flush, source-coord wrapping component, UIx-side frame-provider) |
006-ReactiveSubstrate | day8/re-frame2-uix (rf2-3yij) |
API, Conventions (adapter shipping convention) |
Helix adapter (use-subscribe hook, flush-views! test flush, source-coord wrapping component, Helix-side frame-provider) |
006-ReactiveSubstrate | day8/re-frame2-helix (rf2-2qit) |
API, Conventions (adapter shipping convention) |
Shared React frame Context (factored out so every React-shaped adapter consumes the same createContext object) |
002-Frames, 006-ReactiveSubstrate | day8/re-frame2 (core) — re-frame.adapter.context, CLJS-only; consumed by day8/re-frame2-reagent, day8/re-frame2-uix, and day8/re-frame2-helix |
API |
| Stories / Variants / Workspaces | 007-Stories | post-v1 | 008-Testing (portable-stories-as-tests) |
Testing infrastructure (fixtures, synchronous triggers, per-test stubs, headless evaluation, framework adapters, JVM-runnable suites; the two test-only namespaces ship in the same artefact as siblings split on the assertion axis per 008-Testing §Audience-split (rf2-v7kjq) — re-frame.test-support is the runtime-state axis (registrar, frames, app-db, drain, in-flight requests): fixture machinery (snapshot-registrar, restore-registrar!, with-fresh-registrar, make-reset-runtime-fixture), event sequencing (dispatch-sequence), the assert-*-equals fn-family (assert-path-equals, assert-db-equals — mirrors the :rf.assert/* Story event-family per rf2-8j9m6), bounded-deadline polling (poll-until); re-frame.test-helpers is the view-tree axis (hiccup data, :data-testid selectors, attached handlers) — hiccup-walk finders (find-by-testid / find-all-by-testid / find-by-testid-prefix, find-by-attr / find-all-by-attr / find-by-attr-prefix), tree readers (expand-tree, attrs, children, text-content), handler reach (extract-handler, invoke-handler), single-frame e2e fixture trio (with-app-fixture, expect-text, wait-until, per rf2-wy1ac), authoring helper (testid)) |
008-Testing | day8/re-frame2 (core) — re-frame.test-support and re-frame.test-helpers ship in the core artefact |
API, 007-Stories, 011-SSR (render-to-string as the HTML-string view-test sibling of hiccup-walk), conformance/ |
| Trace event model (envelope, ids, listener API) | 009-Instrumentation | day8/re-frame2 (core) |
Tool-Pair, API |
:rf.cascade/captured emit shape — focused-event-only per-epoch cascade-DAG aggregator; end-of-epoch emit via the :trace.cascade/capture-for-epoch! late-bind hook when the installed focus predicate matches |
009-Instrumentation §Trace event emission catalogue | day8/re-frame2 (core) |
Tool-Pair, 006-ReactiveSubstrate (memo skip interaction) |
Always-on event-emit substrate — register-event-listener! / unregister-event-listener!; one tight record per processed event ({:event :event-id :frame :time :outcome :elapsed-ms}); post-elision; survives goog.DEBUG=false and -Dre-frame.debug=false; per-listener exceptions isolated |
009-Instrumentation §What is available in production builds | day8/re-frame2 (core) |
API §Event-emit, Security §Production gates, Tool-Pair |
Always-on error-emit substrate — register-error-listener! / unregister-error-listener! AND the per-frame :on-error policy fn fan-out; shared substrate, independent fan-out paths, mutual isolation; one tight record per :rf.error/* event ({:error :event :event-id :frame :time :exception :elapsed-ms}); post-elision; survives goog.DEBUG=false and -Dre-frame.debug=false; per-listener / per-policy exceptions isolated |
009-Instrumentation §What is available in production builds | day8/re-frame2 (core) |
API §Error-emit, 002-Frames §:on-error, Security §Production gates, 013-Flows §Failure semantics (flow-eval-exception path) |
Error contract (structured trace events, per-frame :on-error policy); the §Error event catalogue is the single source of truth for every :rf.error/*, :rf.warning/*, :rf.fx/*, :rf.cofx/*, :rf.ssr/*, :rf.epoch/*, :rf.http/*, :rf.frame/*, :rf.route.nav-token/* category — id · :op-type · trigger · default :recovery · :tags (per rf2-wfbn3) |
009-Instrumentation | day8/re-frame2 (core) |
API, all Specs that emit errors cite this section |
Schema attachment (:schema, reg-app-schema), validation timing, dev-vs-prod elision, validator-fn extension point |
010-Schemas | core (split pending: rf2-p7va → day8/re-frame2-schemas) |
001-Registration §Schema integration, Spec-Schemas |
SSR flow (server frame lifecycle, hydration payload, :rf/hydrate, hydration-mismatch detection) |
011-SSR | day8/re-frame2-ssr (rf2-uo7v) |
004-Views, 008-Testing, 012-Routing |
Streaming SSR (:rf/suspense-boundary hiccup marker, per-request continuations registry, per-subtree hydration deltas, chunk-ordering contract, inline-fallback failure semantics) |
011-SSR §Streaming SSR | day8/re-frame2-ssr (re-frame.ssr.streaming ns — primitive) + day8/re-frame2-ssr-ring (re-frame.ssr.ring.streaming ns — chunked-HTTP host adapter); per rf2-ojakd / rf2-olb64 (a) |
011-SSR, API, Conventions (:rf/suspense-boundary reserved hiccup head) |
:platforms metadata on reg-fx/reg-cofx; pure hiccup → HTML emitter |
011-SSR | day8/re-frame2 (core) — :platforms metadata; the hiccup→HTML emitter ships in day8/re-frame2-ssr (rf2-uo7v) |
002-Frames, API |
Route grammar, :route sub, navigation events, route-not-found, navigation-blocking, fragments, scroll restoration |
012-Routing | day8/re-frame2-routing (rf2-k682) |
011-SSR, API |
Flows (reg-flow / :rf.fx/reg-flow / :rf.fx/clear-flow, computed-state declarations materialised into app-db) |
013-Flows | day8/re-frame2-flows (rf2-tfw3) |
API, Conventions (:rf.fx/* reserved) |
Managed HTTP requests (:rf.http/managed fx, args-map shape, decode pipeline, :accept normalisation, retry-with-backoff, abort surface, frame-aware reply addressing, eight-category :rf.http/* failure taxonomy, schema-reflection metadata, canned stubs, with-managed-request-stubs) |
014-HTTPRequests | day8/re-frame2-http (rf2-5kpd) — production fx surface in re-frame.http-managed; canned-stub fxs and the with-managed-request-stubs family of macros / fns in the sibling re-frame.http-test-support (rf2-lwmgw) |
API, Spec-Schemas, Conventions (:rf.http/* reserved), Pattern-AsyncEffect, Pattern-RemoteData, Pattern-StaleDetection, 009-Instrumentation (:rf.http/retry-attempt trace) |
Data classification — opt-in path-marked sensitive + large declarations on every dataflow-participating reg-* plus dedicated add-marks / set-marks for app-db; :rf/redacted / :rf/large {:bytes N :head "..."} display sentinels; auto-propagation across event-arg → app-db → subs → flows → fx → cofx → machine :data boundaries; whole-output override (:sensitive? false/true); union with schema-attached :sensitive? / :large? per-slot metadata |
015-Data-Classification | day8/re-frame2 (core) |
001-Registration (registration metadata-map shape), 002-Frames (event-arg shape), 005-StateMachines (snapshot :data slot), 006-ReactiveSubstrate (sub-output propagation), 009-Instrumentation (trace-bus emission of sentinels), 010-Schemas (schema-attached marks; this row's source unions with 010's), 013-Flows (flow :output propagation), Conventions (reserved sentinel keywords), Security (pattern-level privacy posture this Spec grounds), tools/mcp-base/spec/sensitive.md, tools/mcp-base/spec/elision.md (cross-MCP wire-elision walker consumers) |
Runtime shapes (Malli, CLJS reference) — :rf/effect-map, :rf/registration-metadata, :rf/hydration-payload, :rf/trace-event, etc. |
the per-Spec owner of each shape; Spec-Schemas is the projection (collected EDN forms) — non-canonical | per-surface (matches the owning Spec's row) | every Spec that owns a shape |
| API signatures (consolidated) | the per-Spec owner of each surface; API is the projection — non-canonical | per-surface (matches the owning Spec's row) | per-Spec owners |
| Migration rules (re-frame v1.x → re-frame2, CLJS reference) | MIGRATION | spec-only (no runtime artefact) | per-Spec owners (contract content); Migration owns the rules |
| Pair-tool runtime contract (inspect, dispatch, hot-swap, time-travel, fx-stub, source-map) | Tool-Pair | core for the inspect / dispatch / hot-swap / fx-stub / source-map slices (which ride the registrar / dispatch / trace surfaces in day8/re-frame2); the time-travel slice — the re-frame.epoch namespace, :rf/epoch-record ring buffer, register-epoch-listener! / unregister-epoch-listener! listener API, restore-epoch rewind, and the :rf.epoch/* trace ops — ships in day8/re-frame2-epoch (rf2-lt4e) |
001-Registration, 009-Instrumentation |
Cross-MCP shared primitives (:rf.mcp/* + :rf.size/* wire-marker keys + JSON-RPC error codes; spec/009 §Privacy default-suppress filter; :rf.size/large-elided walker; arg coercion; path-keyed structural diff; overflow-marker payload builder; token-budget cap pipeline) — external canonical home (per README §Canonical homes outside /spec; tool-shared contract, ships with the artefact). Indexed by tools/mcp-base/spec/README.md, with per-namespace contracts in: vocab.md, sensitive.md, elision.md, args.md, diff-encode.md, overflow.md, cap.md. |
tools/mcp-base/spec/ (external: tool-shared, downstream of /spec; per-namespace docs indexed above) |
day8/re-frame2-mcp-base (rf2-vw4sq) — consumed by tools/re-frame2-pair-mcp/ and tools/story-mcp/ |
Tool-Pair, 009-Instrumentation (§Privacy filter, :rf.size/large-elided) |
| Security posture, threat model, behavioural MUSTs, pragmatic stance, decisions log — language-agnostic pattern-level coordination layer naming what is defended, where the defense's contract lives, and why the call was made. Threat model + scope, the eight categories (input validation, XSS, CRLF, privacy, DoS, MCP authority, editor URI allowlist, file-path boundaries, production gates), the catalogue references into Conventions.md / 009 / 010 / 011 / 014, the four-proposition pragmatic stance, and the 38-decision bead log. The mirror to this matrix — Security names what is defended; Ownership names where the defense's contract lives. | Security | spec-only (no runtime artefact) | Conventions, Principles, per-spec owners of each named defense (009 / 010 / 011 / 014 / Tool-Pair / API / Implementor-Checklist / 007-Stories) |
CLJS-reference security specifics — named functions (re-frame.core/elide-wire-value, re-frame.interop/debug-enabled?), numeric defaults (:rf.http/max-decoded-keys 10000, :timeout-ms 30000, drain-depth ceiling, :rf.size/threshold-bytes 16384), JVM-vs-CLJS stub semantics, the exact :rf.error/* keywords each safety check emits, and the full 38-bead audit trail — external canonical home (per README §Canonical homes outside /spec; CLJS-reference binding of the pattern-level MUSTs in Security.md; split executed by (A).3 (a)) |
implementation/SECURITY.md (external: CLJS-reference binding, downstream of /spec) |
spec-only (no runtime artefact); the named functions ship in the artefacts named on their respective rows above | Security (pattern-level companion); per-spec owners of each named fn / numeric default |
Reserved-namespace policy, reserved fx-ids and app-db keys |
Conventions | spec-only (no runtime artefact) | every Spec that uses a reserved id cites the Conventions list |
| Construction-prompt scaffolding templates | Construction-Prompts | spec-only (no runtime artefact) | per-Spec owners (contract content); Construction-Prompts owns the scaffolding shape |
| Conformance fixtures (canonical interactions and expected emissions, in EDN) | conformance/ | spec-only (no runtime artefact) | per-Spec owners (contract content); conformance owns the fixture corpus |
Xray event-spine architecture — the 4-layer chrome (ribbon · event list · tab bar · detail panel), the spine sub :rf.xray/focus collapsing two-axis selection into single-axis, the 6-tab inventory (Event / App-db / Views / Trace / Machines / Routing — the Issues tab was removed per rf2-gbz39 Option (c); issues surface inline in the Epoch panel + the L2 event-row pink-wash + the always-on issues ribbon signal), the IN/OUT filter pills + edit popup, the Settings modal popup, the Causality popover (c-key transient overlay), the frame-observation isolation invariants (I1–I4) with browser-feature test gate, and the data-classification rendering contract that consumes spec/015 — external canonical home (per README §Canonical homes outside /spec; tool-shared contract, ships with the Xray artefact tree under tools/xray/spec/). |
tools/xray/spec/018-Event-Spine.md (external: tool-spec, downstream of /spec) |
day8/re-frame2-xray (the Xray tool artefact) |
tools/xray/spec/000-Vision.md (6-tab inventory), tools/xray/spec/007-UX-IA.md (typography + colour tokens + keyboard map), tools/xray/spec/003-Machine-Inspector.md (Machines tab content), tools/xray/spec/012-Views.md (Views tab content), tools/xray/spec/016-Auxiliary-Panels.md (per-tab content), tools/xray/spec/017-Test-Coverage-Matrix.md (test gates) |
Drift rule: if a contract surface acquires a second normative definition (a redefinition rather than a citation), that is a corpus bug. File it as a spec-review bead and resolve by collapsing back to the listed owner.