Skip to content

Privacy & Data-Classification — cross-artefact reference

Type: Reference Normative status: Supporting companion. Defers to 009-Instrumentation, 010-Schemas, 014-HTTPRequests, 015-Data-Classification, Tool-Pair, Conventions, and Security for every contract surface named here. This doc is the discoverability index — one place to land for "where do privacy primitives live across re-frame2's artefacts, what is the composition order, and what do I declare to keep a value out of off-box egress?"

re-frame2's privacy surface is the leak-prevention overlay on observability. Real data flows through events / cofx / handlers / fx / app-db / subs / views unchanged; sentinel substitution happens only at the observation/egress boundary. The contract spans five artefacts (re-frame.core, re-frame.http, re-frame.schemas, re-frame.epoch, tools/mcp-base) and the owner-classification declaration sources the graduated EP-0015 model fixes — frame config (durable frame-wide facts), per-slot schema props (owner-local schema'd data), and registration metadata (transient payloads) — this doc gathers them into one inventory and pins the composition order.

Graduated to the EP-0015 model. This doc was rewritten to the EP-0015 (final) owner-classification + project-egress + :rf.egress/*-profile model that Spec 015 graduates, and reflects the EP-0017 (final) recordable-coeffect secrets-exclusion rule (see §Recordable coeffects must exclude secrets). The pre-EP-0015 framing — the "seven first-class marking sites", the public add-marks / set-marks app-db path-mark API, schema-attached app-db classification, and the positional redact-interceptor — is superseded; those surfaces are removed from the public façade (their underlying fns remain internal / test-only plumbing), and where this index links to a sibling spec that still carries the old framing, the link is kept but its description reconciled here. The normative contract lives in Spec 015; this doc is the cross-artefact index.

Posture (per Spec 015 §Posture). Privacy here is observability hygiene, not authorisation. Apps still own auth, authorisation, encryption-at-rest, and transport security. The classification machinery exists so that the framework's own dev-time observability surfaces (and their downstream consumers — log sinks, AI agents, dashboards) cannot accidentally exfiltrate user secrets or stuff log lines with multi-megabyte blobs. See Security.md §Privacy / secret handling for the pattern-level threat model.

Table of contents

The six observation boundaries

Privacy declarations exist to stop leaks at every framework-mediated observation/egress boundary. Per 015 §Scope the complete set, each with the egress profile Spec 015 projects it under:

# Boundary What sees it Profile / production posture
1 Trace-bus emit — every :rf/trace-event built by emit! / emit-error! Trace listeners, Xray panel, error monitors, log sinks Dev stream gated on re-frame.interop/debug-enabled? (the CLJS mirror of goog.DEBUG); the always-on error-emit substrate (009 §Error-emit substrate) survives production
2 Xray / Story panels — Event Detail, App-DB Diff, Subscriptions, Trace, Causality Graph, Machine Inspector, Flow Panel, Story scenarios The on-box dev tool; CLJS-only :rf.egress/local-redacted by default; dev-only (production-elided)
3 MCP / tool wire transport — tools/re-frame2-pair-mcp, tools/story-mcp, any future MCP server Off-box LLM / tool consumers :rf.egress/off-box-tool; N/A (tooling, not in the production bundle)
4 AI / LLM context lifted by tools — any code path that lifts trace events / app-db / sub outputs / machine :data into an LLM prompt The hosted LLM endpoint :rf.egress/off-box-tool; N/A
5 Hosted log sinks — Datadog, Sentry, LogRocket, Honeybadger, custom fan-outs; routed by frame :observability Off-box ops/monitoring :rf.egress/off-box-observability; the always-on error-emit substrate is the live path here — it survives goog.DEBUG=false, so sensitive-projection MUST work in production builds
6 Epoch export, SSR / hydration, public error responses, HTTP diagnostics, schema-validation failure records Off-box recorders, the browser, hosted dashboards each its own profile — :rf.egress/ssr-hydration (after the §SSR allowlist), :rf.egress/public-error, :rf.egress/off-box-observability

The contract for the off-box boundaries (3 / 4 / 5 / 6) is project before egress: the runtime projects every record under the owning frame's classification and the boundary's :rf.egress/* profile via project-egress before any sink, tool, or wire sees it; a sink never receives a raw record. On the always-on trace/error substrate, a record carrying :sensitive? true at the top level is dropped by the off-box forwarder. Apps opt back in by passing the off-box-wire opt — the MCP tool argument is the unqualified :include-sensitive (the Anthropic tool-input-schema regex rejects a trailing ?; see tools/mcp-base/spec/sensitive.md §Cross-server arg-vocabulary), which resolves to the :rf.egress/local-raw profile — or, for an on-box panel, the {:show-sensitive? true} UI toggle. The off-box-wire verb family is named include-sensitive? (the ? rides the config-knob verb, not the MCP wire key). See Conventions §Privacy config-knob naming.

Inventory by artefact

The complete imperative + declarative surface, grouped by owning namespace. Every entry's normative owner lives in the cited Spec section; this table is the index, not the contract.

re-frame.core (production-survivable subset re-exported from artefacts below)

Surface Kind Purpose Owner
:sensitive reg-meta key Vector of paths into the registration's primary data shape (event arg-map, fx-input map, cofx value, sub output, flow output, machine transition payload) 015 §Registration-owned transient classification
:large reg-meta key Symmetric to :sensitive — paths to slots elided with :rf.size/large-elided 015 §Registration-owned transient classification
:rf.egress/output-sensitivity reg-meta key (reg-sub, reg-flow) Derived-output declassification: closed value set :rf.egress/inherit (default — inherit from inputs) | :rf.egress/sensitive (force-mark) | :rf.egress/public (declassify). Not :sensitive false — :sensitive is a path collection at this layer (EP-0007 rule-3 distinction). 015 §Declassifying a derived output
frame :sensitive / :large / :observability reg-frame meta Durable app-db classification, frame-local HTTP carrier names, and observability sink policy. The durable-frame-state owner; replaces the removed add-marks / set-marks / declare-sensitive-*! surfaces. 015 §Frame-owned durable classification
project-egress record-level boundary primitive (rf/project-egress record opts) → projected record. The public record-level projection primitive (knows app-db-/event-/exception-/HTTP-/summary-shaped slots); the required step before any off-box sink. Delegates per tree-shaped slot to elide-wire-value. New façade export (subject to the facade-export classification rule). 015 §project-egress
register-observability-sink! / unregister-observability-sink! façade fns Register the concrete sink fn against the id a frame's :observability policy names; the sink consumes the already-projected record. New façade exports (subject to the facade-export classification rule). 015 §Frame-owned observability sink policy
sensitive? predicate (rf/sensitive? trace-event) → bool. True iff the event carries :sensitive? true at the top level. The framework-published predicate every forwarder composes against. 009 §Privacy
elide-wire-value walker (rf/elide-wire-value v opts) → walked v. The low-level value walker for tree-shaped values; project-egress delegates to it per tree-shaped slot. Sinks and tools should rarely call it directly. API.md §wire-elision walker, 009 §Size elision
redact-derived-slots composed multi-slot egress helper (rf/redact-derived-slots m slot-keys source-db frame-id wire-opts) → m with the selected derived slot(s) value-redacted. The value-based DUAL of elide-wire-value — collects a frame's declared-:sensitive / :large app-db values ONCE from source-db and substitutes any matching leaf in the derived tree(s) (:rf/redacted / :rf.size/large-elided), since a derived tree re-surfaces those values at non-app-db positions the path walker can't reach. The single façade egress assembler; the granular value-match arms + the [:rf.runtime/elision] declaration readers (re-frame.elision/declarations / sensitive-declarations) it composes live in re-frame.elision (not façade exports). API.md, 015 §Projection
populate-elision-from-schemas! / populate-sensitive-from-schemas! internal migration importer Walk app-schemas and lower :large? / :sensitive? slot props into the runtime-db [:rf.runtime/elision …] registries. Per EP-0015 §8 schema metadata is not the public route for durable app-db classification (the frame owns that); these hydrators survive only as an internal compatibility bridge for migration import, not as a co-equal public façade. Idempotent; no-op when the schemas artefact is absent. 015 §Schemas describe shape
(configure! {:elision ...}) runtime config {:rf.size/threshold-bytes N} — wire-elision size cap. Default 16384. API.md §Configure keys

re-frame.http

HTTP carrier policy. The HTTP fx maps headers + query-strings + the decoded response body into :rf.http/* trace events; their classification surfaces:

Surface Kind Purpose Owner
Built-in header / query-param denylists framework default (immutable) Closed sets of always-sensitive header / query-param names redacted in every :rf.http/* trace event regardless of the request :sensitive? flag — the name is the signal. No frame can remove a built-in name. 014 §1–2
Frame-local carriers declarative (frame config) (rf/reg-frame :app {:sensitive {:http {:headers [..] :query-params [..]}}}) — app-specific carrier names that union onto the immutable built-in defaults for the emitting frame (EP-0015 §3). Replaces the removed process-global declare-sensitive-*! mutators. 014 §Frame-local carriers
Response-body classification declarative (:decode schema) Per-slot :sensitive? / :large? props on the request's :decode Malli schema classify the decoded body (the EP-0005 mechanism). Whole-body root prop redacts everything; an unschematized body fails closed off-box (EP-0015 issue 5). 014 §Response-body classification
:sensitive? (per-call) request arg {:rf.http/managed {:sensitive? true}} — opts a specific request in. When true, the request body is redacted to the sentinel and all query params are scrubbed (broader than the denylist). Sugar form: {:request {:sensitive? true}}. 014 §Privacy

Built-in denylists ship populated with the obvious cross-app names (authorization, cookie, x-api-key, set-cookie, ...; api_key, access_token, auth, token, ...). App-specific carrier names (X-MyApp-Auth, shop_token) are declared on the frame via :sensitive {:http {...}} (EP-0015 §3) — the process-global declare-sensitive-header! / declare-sensitive-query-param! mutators are removed.

re-frame.schemas (declarative — no imperative surface)

Schema-attached slot props. Per EP-0015 these are the one and only classification route for owner-local schema'd data — machine :data-schema, resource :data-schema / :params-schema, an HTTP request's :decode schema (one owner, one route) — and they drive schema-validation error-trace redaction. They are not a public route for durable app-db classification (the frame owns that per 015 §Schemas describe shape); the boot hydrators above survive only as an internal migration importer for the app-db case.

Surface Kind Purpose Owner
:sensitive? true schema slot prop Per-slot Malli property {:sensitive? true} on a :data-schema / :params-schema / :decode schema slot (or, for migration import only, an app-schema slot). The canonical fine-grained surface for schema-owned data; schema-validation error traces consult the prop (:value / :received / :explain / :rf.fx/args / :rf.sub/query-v redaction). 010 §:sensitive?, 015 §Machine-owned
:large? true schema slot prop Symmetric — boot-time populate-elision-from-schemas! writes the slot's path into the runtime-db [:rf.runtime/elision :declarations] registry. The wire-elision walker substitutes :rf.size/large-elided for matching slots at off-box egress. 010 §:large?

re-frame.epoch

Per EP-0015 issue 6 (graduated), epoch records are causal replay material (post-EP-0010) and storage-side mutation is removed — the raw record stays in the ring and every register-epoch-listener! listener receives it unmutated; off-box egress MUST project through projected-record / projected-history (which run project-egress under an off-box profile). The surviving :redact-fn hook is projection-side only (export/egress), not a storage-side record transform; it is an advanced escape for slots the frame's classification cannot prove.

Surface Kind Purpose Owner
(configure! {:epoch-history {:redact-fn fn}}) runtime config Projection-side advanced override. Invoked once per record at the off-box egress boundary — inside the projected-record helper, after the frame/profile project-egress projection — and MUST NOT mutate the record at storage time. The in-process ring + every listener therefore deliver the raw record (mutating replay material at rest corrupts the EP-0010 replay contract). Failures emit :rf.warning/epoch-redact-fn-exception and fall back to the projected record for that egress only. Production-elided (the whole epoch surface rides debug-enabled?). 015 §Epoch projection, Tool-Pair §Redaction hook, API.md §Configure keys
:rf.epoch/sensitive? record-level rollup Top-level boolean on the assembled :rf/epoch-record — true iff any captured trace event / declared-sensitive leaf in the record was sensitive. Computed at build-time from the raw record's schema-declared sensitive leaves, so it stays an accurate off-box-branch signal on the raw ring record. Tool-Pair §Time-travel
projected-record projection fn (rf/projected-record record) — off-box-safe projection of a :rf/epoch-record. Routes each tree slot through project-egress (over elide-wire-value), strips raw :db-before / :db-after, keeps the structured fields (:trigger-event, :fx, :halt-reason, :schema-digest, :rf.epoch/sensitive?, :rf.epoch/redacted-modified-paths-count). The single projection site when shipping epoch data off-box; then applies the :redact-fn advanced override. Idempotent. Tool-Pair §Direct-read privacy
projected-history projection fn (rf/projected-history frame-id) — (mapv projected-record (epoch-history frame-id)). Off-box-safe equivalent of epoch-history. Tool-Pair §Time-travel

tools/mcp-base (cross-MCP wire egress)

The framework-published privacy filter every MCP forwarder composes. Apps don't author against this directly — MCP server implementations do, conforming to the cross-server vocabulary.

Surface Kind Purpose Owner
sensitive-event? predicate Conservative predicate over a trace-event map — true iff (:sensitive? ev) is literal true. Mirror of re-frame.privacy/sensitive?. tools/mcp-base/spec/sensitive.md
strip-sensitive walker (strip-sensitive coll) → [kept dropped-count]. The dropped-count becomes the :dropped-sensitive envelope counter on the MCP response. tools/mcp-base/spec/sensitive.md
scrub-snapshot walker Snapshot-tree walker — descends into nested registration handles and removes :sensitive?-stamped sub-trees (stricter than top-level filtering). tools/mcp-base/spec/sensitive.md
:include-sensitive cross-MCP wire arg Per-call opt-in on every MCP tool surfacing trace-like data. Defaults to false. The wire-key spelling is now uniform across every server — story-mcp and re-frame2-pair-mcp both ship the unqualified :include-sensitive (no trailing ? — the Anthropic tool-input-schema regex ^[a-zA-Z0-9_.-]{1,64}$ rejects ?). The ? is retained only on the internal walker option (:rf.size/include-sensitive?) and the config-knob verb (include-sensitive?), never the MCP wire key. tools/mcp-base/spec/sensitive.md §Cross-server arg-vocabulary, Conventions §Privacy config-knob
:rf.size/large-elided (elision marker) + :include-large? (wire arg) cross-MCP wire vocabulary Size-elision peer of :sensitive?. The walker substitutes :rf.size/large-elided {:bytes N :head "..." :handle ...} at over-threshold or :large?-declared slots; off-box callers opt in with {:include-large? true}. tools/mcp-base/spec/elision.md, 009 §Size elision

Inventory by declaration source

Same surfaces, regrouped by the owner that declares the classification. The graduated EP-0015 model fixes four owners (015 §The ownership split): frame config classifies frame-owned durable state and frame egress; machine / resource / mutation definitions classify owner-local schema'd data; registration metadata classifies transient payloads.

Frame config (durable frame-wide facts + frame egress)

The frame owns durable app-db classification, frame-local HTTP carrier names, observability sink policy, and the SSR hydration allowlist:

  • (rf/reg-frame :app {:sensitive {:app-db [[:auth :token] …]}}) — durable app-db sensitive paths (:rf/path values)
  • (rf/reg-frame :app {:large {:app-db [[:docs :csv-upload] …]}}) — durable app-db large paths
  • (rf/reg-frame :app {:sensitive {:http {:headers […] :query-params […]}}}) — frame-local HTTP carrier names, union onto the immutable built-in defaults
  • (rf/reg-frame :app {:observability {:handled-events […] :errors […]}}) — production sink policy (§Frame-owned observability sink policy)
  • (rf/reg-frame :app {:ssr {:hydrate {:include-app-db […]}}}) — allowlist-first SSR/hydration boundary

Frame classification installs atomically at frame creation (before :on-create); re-registering replaces it wholesale. This replaces the removed add-marks / set-marks app-db path-mark API and the process-global declare-sensitive-header! / declare-sensitive-query-param! mutators (their underlying fns survive as internal/test helpers only — see §Removed surfaces). Per 015 §Frame-owned durable classification.

Per-slot schema props (owner-local schema'd data)

{:sensitive? true} / {:large? true} Malli props on the owner's own schema are the one-and-only route for owner-local schema'd data — machine :data-schema, resource :data-schema / :params-schema, an HTTP request's :decode schema (the shared EP-0005 mechanism; no sibling path-map vocabulary). Whole-shape claims are the degenerate root-prop case; an unschematized HTTP body is whole-sensitive (fail-closed). Per 015 §Machine-owned, §Resource and mutation, §HTTP response bodies. (Schema props on an app-db schema are not a public route — the frame owns app-db; the boot hydrators survive only as an internal migration importer per 015 §Schemas describe shape.)

Registration metadata (transient payloads)

reg-event / reg-sub / reg-fx / reg-cofx / reg-flow accept :sensitive / :large (vectors of paths) into the registration's primary data shape; subs and flows additionally accept :rf.egress/output-sensitivity (:rf.egress/inherit | :rf.egress/sensitive | :rf.egress/public) for derived-output declassification. Empty path [[]] marks the whole shape.

Reg kind Path root Owner
reg-event the event arg-map (second element of [:event-id {arg-map}]) 015 §Registration-owned transient classification
reg-sub the sub's output value; :rf.egress/output-sensitivity declassifies the whole output 015 §Declassifying a derived output
reg-fx the fx-input map 015 §Registration-owned transient classification
reg-cofx the coeffect value ([[]] = the whole value) — see also §Recordable coeffects must exclude secrets 015 §Registration-owned transient classification
reg-flow the flow's :output value; :rf.egress/output-sensitivity declassifies 015 §Declassifying a derived output

Machine transition payloads are transient payloads classified by the transition/registration metadata that introduces them — not by the machine's durable :data policy. Durable runtime-subsystem state (resource/mutation) is owned by its definition (per-slot schema props), not classified as a transient payload merely because it is declared by reg-resource / reg-mutation.

HTTP carriers (frame policy) — quick reference

  • (rf/reg-frame :app {:sensitive {:http {:headers ["X-MyApp-Auth"]}}}) — frame-local header carrier; unions onto the immutable built-in header denylist (EP-0015 §3)
  • (rf/reg-frame :app {:sensitive {:http {:query-params ["my_token"]}}}) — frame-local query-param carrier; unions onto the built-in query-param denylist
  • {:rf.http/managed {:decode <malli-schema-with-:sensitive?-props>}} — per-slot response-body classification (EP-0015 issue 5)
  • {:rf.http/managed {:sensitive? true ...}} — per-call opt-in (body redaction + ALL params scrubbed)

Runtime config — epoch redact hook

  • (rf/configure! {:epoch-history {:redact-fn (fn [record] ...)}}) — single-pass record-in / record-out hook at the epoch boundary.

The composition order (data-flow)

The single most-asked question this doc answers: what runs when, in what order, between handler exit and off-box wire? The order is fixed and documented in pieces across 009 / 014 / 015 / Tool-Pair — this section pins it in one place.

┌─────────────────────────────────────────────────────────────────────────────┐
│  1. HANDLER BODY runs with REAL VALUES                                      │
│     - Event handler sees the raw event arg-map (via :event coeffect)        │
│     - Cofx values, app-db reads, fx args — all unredacted                   │
│     - This is by design — the handler MUST see real values to do its job   │
└─────────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  2. EVENT-PAYLOAD SCRUB during trace-event build                            │
│     - The router's internal redaction interceptor stashes a scrubbed copy   │
│       at :rf/redacted-event for every handler whose registration-owned      │
│       :sensitive paths (or a frame-sensitive app-db path the slice          │
│       overlaps) match the event payload.                                    │
│     - (The public positional `redact-interceptor` is REMOVED per EP-0015    │
│       §7; the underlying re-frame.privacy/redact-interceptor survives as    │
│       internal router plumbing only — registration-owned :sensitive is the  │
│       public route.)                                                        │
│     - Trace assembly reads :rf/redacted-event (not :event) when building    │
│       :rf.event/* and :rf.event/db-changed tag shapes.                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  3. SPEC 015 PATH-MARK PROJECTION (re-frame.marks/project-trace-event)      │
│     - The trace bus chokepoint walks :tags for per-registration marks       │
│       declared at reg-time (`:sensitive [paths]` on the registration meta). │
│     - Substitutes :rf/redacted at sensitive paths, :rf.size/large-elided    │
│       at large paths inside the per-tag shape (events under :event, fxs    │
│       under :fx-args, cofx under :coeffects, subs under :value, machines   │
│       under :before / :after / :snapshot).                                  │
│     - Sub-output propagation table consulted: a sub reading any sensitive   │
│       app-db path yields a sensitive output (footgun prevention).           │
│     - Stamps :sensitive? true at the top level of the trace event.          │
│     - Gated on `re-frame.interop/debug-enabled?` — production CLJS bundles  │
│       DCE this away.                                                        │
└─────────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  4. HTTP-SPECIFIC REDACTION (re-frame.http-privacy/prepare-emit-tags)       │
│     - For :rf.http/* trace events only.                                     │
│     - `redact-headers` walks the :headers map, replaces values whose name   │
│       is in the header denylist with :rf/redacted (unconditional — denyy-  │
│       listed names are the signal).                                         │
│     - `redact-url-query-string` walks the :url string, replaces query-      │
│       param values whose name is in the query-param denylist (unconditional).│
│     - When `:sensitive? true` is the per-call flag: also scrubs :body and   │
│       ALL params (broader than the denylist).                               │
│     - `:sensitive? true` stamped on the trace event when ANY scrub fired    │
│       (denylist hit OR per-call opt-in OR upstream from path-mark).         │
└─────────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  5. TRACE-BUS EMIT — every listener receives the redacted, stamped event    │
│     - Dev-only listeners (Xray, story recorder, dev panels): consult       │
│       :sensitive? at top level; on-box dev panels render an opaque indicator│
│       and require `:trace/show-sensitive? true` to reveal.                  │
│     - Always-on error-emit substrate listeners (production-survivable):     │
│       consult :sensitive? and drop the whole event by default at off-box    │
│       egress (Sentry/Honeybadger/Datadog forwarders).                       │
└─────────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  6. EPOCH ASSEMBLY (re-frame.epoch/build-record)                            │
│     - Per-frame, on drain-settle.                                           │
│     - sensitive-rollup computes :rf.epoch/sensitive? from the raw record's  │
│       schema-declared sensitive leaves at build-time.                       │
│     - The RAW record is appended to the ring and delivered to every         │
│       register-epoch-listener! listener UNMUTATED — storage-side mutation   │
│       is REMOVED (EP-0015 issue 6): epoch records are EP-0010 causal replay │
│       material, mutating them at rest corrupts the replay contract.         │
│     - The :redact-fn runs at step 7 (off-box egress), not here.             │
└─────────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  7. OFF-BOX PROJECTION (rf/project-egress → rf/projected-record →           │
│     rf/elide-wire-value)                                                    │
│     - `project-egress` is the record-level boundary primitive; it           │
│       delegates per tree-shaped slot to `elide-wire-value` (the value       │
│       walker, single emission site for :rf/redacted + :rf.size/large-       │
│       elided) under the frame's classification + the boundary's             │
│       :rf.egress/* profile.                                                 │
│     - `projected-record` (epoch) strips raw :db-before / :db-after; THEN    │
│       applies the projection-side :redact-fn advanced override (after the   │
│       frame/profile projection, never at storage time).                     │
│     - The structured :effects rows' :args (raw fx-handler payload, not      │
│       app-db-rooted so the walker cannot prove it safe) FAIL CLOSED to      │
│       :rf/redacted off-box, lifted only by :include-fx-args? true.          │
│     - `elide-wire-value` walks tree-typed payloads; consults the per-frame  │
│       [:rf.runtime/elision :declarations] +                                 │
│       [:rf.runtime/elision :sensitive-declarations] (frame-sourced, plus    │
│       schema-sourced migration-import entries — union at lookup time).      │
│     - Composition rule: sensitive drop WINS over large elision when both    │
│       apply at the same path (the size marker would otherwise leak :path /  │
│       :bytes / :digest).                                                    │
│     - Default `{:include-sensitive? false :include-large? false}` —         │
│       maximum elision unless the caller explicitly opts in.                 │
└─────────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  8. MCP TOOL EGRESS (tools/mcp-base/sensitive + elision)                    │
│     - Cross-MCP filter that runs on every tool response payload.            │
│     - `strip-sensitive` returns [kept dropped-count]; populates the         │
│       `:dropped-sensitive` envelope counter (omitted when zero).            │
│     - `:elided-large` envelope counter sums the `:rf.size/large-elided`     │
│       substitutions.                                                        │
│     - The counters ride alongside the payload as unqualified keys so the    │
│       calling agent recognises filtering without re-inferring from absence. │
└─────────────────────────────────────────────────────────────────────────────┘

Rule summary

  • Composition is additive at every site. Frame-owned :sensitive {:app-db …} and an owner-local schema :sensitive? prop that resolve to the same path both redact at the same observation surface — they union.
  • Sensitive wins over large at the same path. 015 §:rf/redacted {:bytes N} and 009 §Size elision in traces. The sensitive drop suppresses the size marker because the marker carries :path / :bytes / :digest which would themselves leak.
  • HTTP denylists are upstream of the trace stream. They run inside prepare-emit-tags / prepare-emit-failure before trace/emit! fires — they shape the trace event itself, not its downstream consumers. Per Spec 014 §Privacy.
  • Real values are never redacted mid-handler. The router stashes a scrubbed copy at :rf/redacted-event; the handler body continues to read the unredacted :event coeffect. Projection happens at the observation/egress boundary after the handler returns, never before.
  • Production has one live path: the always-on error-emit substrate. Everything else (dev trace bus, epoch ring, schema-validation traces, Xray) elides via goog.DEBUG. The error substrate honours :sensitive? in production — that's the load-bearing case for substrate-level enforcement.
  • runtime-db is redacted/omitted off-box by default (EP-0001, Mike ruling #14). Off-box egress of frame-state — the epoch projected-record / projected-history pair, Xray-MCP, and pair recorders — redacts or omits the runtime-db side of frame-state by default; the off-box default fails closed. Only the app-db partition (subject to its own :sensitive? / :large? elision) and explicitly allowlisted serializable runtime-db facts cross the wire. The SSR hydration payload likewise ships only the serializable runtime-db facts the client needs to reconstitute (machine snapshots, route slice, elision declarations, SSR metadata — per 011 §The :rf/hydrate event), never transient runtime side-channel state. A trusted-local tool may request richer runtime-db diagnostics explicitly (the same opt-in shape as :include-sensitive? for app-db); off-box / AI / log egress fails closed. This is the runtime-db peer of the app-db :sensitive? default: app-db redacts at marked paths, runtime-db redacts/omits wholesale unless explicitly opted in. The normative statement (including the elision-declarations-live-in-runtime-db corollary) is 009 §Privacy / sensitive data in traces.

Recordable coeffects must exclude secrets

EP-0017 (final) folds host facts into durable frame-state as recordable coeffects — values written into the :rf.cofx envelope map and re-presented verbatim by replay (the discipline: durable state folds facts, never reads; see 002 §The recordable-coeffect rule). A recordable coeffect is durable by design — it lands in every epoch record, replay fixture, and exported trace. That durability is the threat model for credentials:

Crypto-grade randomness, tokens, nonces, session ids, and key material MUST NOT be minted or carried as recordable coeffects. Recording a secret does not make it safe; it makes it durable — copied into every recording, fixture, and exported trace. Secrets are generated at the edge and handled by guarded runtime mechanisms, off the ledger (EP-0010's exclusion, restated at this surface).

The rule is a normative review discipline, not a structural guarantee: app-owned reg-cofx suppliers mint whatever value they return, so the framework cannot prove a value is not a secret. The enforcement surface is this guide's secrets material plus EP-0017's recommended lint (a handler that writes durable state declaring an ambient-grade id — "durable state folds facts, never reads", mechanically checkable). Per EP-0017 §Security Considerations.

Projection composes the same way for cofx values as for event payloads. Each :rf.cofx leaf follows the same EP-0015 projection / redaction rules as event-arg values — classify the cofx's value shape per-slot (reg-cofx :sensitive / :large, or the cofx's registered :schema props), and the off-box projection redacts it like any other transient payload. The framework's one built-in recordable fact, :rf/time-ms, is classified always-safe and never redacted. So the cofx surface has two complementary obligations:

  1. Off-box egress redaction (EP-0015) — a recordable coeffect that is legitimately sensitive (e.g. a non-secret-but-private fact a fold needs) is classified and projected like any transient payload; it is never shipped raw off-box.
  2. The secrets exclusion (EP-0017, above) — a secret must not be a recordable coeffect at all, because redaction does not undo durability: the raw value still lives in the on-box ring, the local epoch, and any trusted-local raw read. The two rules are not substitutes — exclusion is the load-bearing rule for credentials; projection is the safety net for the merely-private.

The analogous obligation already holds for resource scopes / params (classified, projected — but not a place to put a secret) and for HTTP response bodies (fail-closed when unschematized). Recordable coeffects extend that posture to the input-fold side.

Display sentinels

Per 015 §Display contract and API.md §wire-elision walker:

Sentinel When Drillable?
:rf/redacted (opaque keyword) Sensitive content. Carries no information about the underlying value — not its type, not its size, not a hash, not a prefix. No. A tool that offers a "show original" affordance against :rf/redacted is non-conformant.
:rf.size/large-elided {:path [...] :bytes N :type :map :hint "..." :handle [:rf.elision/at path] :digest "sha256:..." (when:include-digests?true)} Large content; size diagnostic without leaking content. The :hint rides from the schema's :hint prop. Yes for on-box panels with size-confirmation modal; no for off-box egress by default.
:rf/redacted at a path also marked large Sensitive + large composed — sensitive wins. The size marker is suppressed entirely (the marker payload would leak :path / :bytes). No. (Per 015 §:rf/redacted {:bytes N} — the Spec contemplates a :rf/redacted {:bytes N} composed form preserving the size diagnostic; the CLJS reference currently suppresses the marker entirely. Both are conformant — readers should not depend on :bytes being present alongside :rf/redacted.)

All three sentinel keywords are framework-reserved per Conventions §Reserved namespaces — apps MUST NOT use them as legitimate payload values.

Config knobs

The two verb families that decide whether a sensitive value passes through a consumer. The verb encodes the trust boundary. Per Conventions §Privacy config-knob naming:

Verb Where Default Trust boundary
:rf.privacy/show-sensitive? On-box devtools panels (Xray, Story trace panel) — set via each tool's configure!, e.g. (xray-config/configure! {:rf.privacy/show-sensitive? true}). Reads back via (re-frame.privacy/get-show-sensitive). Per — the :rf.privacy/* namespace is the cross-tool reservation (every re-frame2 tool that consumes the trace bus reads the same atom; one config flip covers every tool). false (suppress) The panel is for the operator running this process; toggle controls UI visibility, not egress.
:include-sensitive? / :rf.size/include-sensitive? Off-box wire egress (MCP servers, hosted-LLM preload, error monitors, Datadog/Sentry forwarders) false (suppress) The toggle controls whether sensitive values cross the process trust boundary.

Both default to suppress per Spec 009's default-private posture. A sixth consumer adding a knob picks the verb by trust-boundary class — on-box panel → show-sensitive?; off-box wire → include-sensitive?.

Configure-keys that touch privacy

Per API.md §Configure keys and 015:

(rf/configure! {<key> {...}}) Privacy-relevant opt Default Purpose
:elision :rf.size/threshold-bytes N 16384 Wire-elision size cap. Non-negative integer; 0 disables runtime auto-detect (only declared / schema-marked entries elide).
:epoch-history :redact-fn fn nil Projection-side advanced override — runs at off-box egress (inside projected-record, after the frame/profile projection), never at storage (EP-0015 issue 6). See Tool-Pair §Redaction hook.
:epoch-history :depth N / :trace-events-keep N depth 50, trace-events-keep nil Bounds the ring (doesn't redact; bounds the surface).

Indicator slots

Counters that ride alongside MCP tool responses so the calling agent knows the payload was filtered, without re-inferring from absence. Per Conventions §Reserved indicator slots:

Slot Meaning Where Owner
:dropped-sensitive Integer count of leaves the walker dropped because they matched :sensitive? true. Omit when zero. MCP response envelope (unqualified key) Cross-MCP convention
:elided-large Integer count of leaves replaced with the :rf.size/large-elided marker. Omit when zero. MCP response envelope (unqualified key) Cross-MCP convention
[● REDACTED N] / [● ELIDED N] Panel-chrome mirror of the MCP slots for on-box surfaces (Xray, story panel) Panel chrome (not JSON) Conventions §Reserved panel-chrome surface

The walker also emits a top-level :rf.epoch/redacted-modified-paths-count on :rf/epoch-record values when the :redact-fn substituted at non-schema-declared paths — apps can detect "the redact-fn touched these many slots" without re-walking.

Worked example — password in app-db + token header on HTTP

Finding #8's canonical question: "I have a :password field in app-db and a :token header on an HTTP request — what do I declare where to keep both out of off-box egress?"

;; 1. Declare the durable app-db classification ON THE FRAME (EP-0015). The
;;    frame owns durable app-db egress policy; this replaces the removed
;;    add-marks / set-marks API. (App-specific HTTP carriers and the
;;    observability sink policy live on the same frame map — see steps 3.)
(rf/reg-frame :app/main
  {:sensitive
   {:app-db [[:auth :password]
             [:auth :token]
             [:auth :refresh-token]
             [:user :ssn]]
    :http   {:headers ["X-MyApp-Session"]}}})

;; 2. Declare the event-arg-side mark on the login handler — the password
;;    arrives in the event arg-map before it lands in app-db.
(rf/reg-event :auth/log-in
  {:sensitive [[:password] [:totp-code]]}
  (fn [{:keys [db]} [_ {:keys [email password totp-code]}]]
    ;; The handler sees real password / totp-code values.
    ;; The trace event sees [:auth/log-in {:email "..."
    ;;                                     :password :rf/redacted
    ;;                                     :totp-code :rf/redacted}].
    {:fx [[:rf.http/managed
           {:method     :post
            :url        "/api/login"
            :body       {:email email :password password}
            :sensitive? true     ;; per-call opt-in — body + ALL params scrubbed
            :on-success [:auth/log-in-success]
            :on-failure [:auth/log-in-failure]}]]}))

;; 3. The app-specific auth-token header carrier `X-MyApp-Session` was
;;    declared on the same frame map in step 1 (`:sensitive {:http {...}}`).
;;    The built-in defaults already cover `authorization` / `x-api-key` /
;;    `cookie` / `set-cookie`; the frame carrier unions onto those immutable
;;    defaults (EP-0015 §3).

;; 4. The on-success event receives the JWT in the response payload. Mark
;;    its event arg so the trace surface sees :rf/redacted there too.
(rf/reg-event :auth/log-in-success
  {:sensitive [[:jwt] [:refresh-token]]}
  (fn [{:keys [db]} [_ {:keys [jwt refresh-token user]}]]
    ;; Writing the JWT into app-db [:auth :token] — the frame `:sensitive
    ;; {:app-db ...}` declaration in step 1 means downstream Xray renders
    ;; the path as :rf/redacted. The derived-sensitivity propagation rule
    ;; in Spec 015 also marks subscriptions/flows that read it.
    {:db (-> db
             (assoc-in [:auth :token] jwt)
             (assoc-in [:auth :refresh-token] refresh-token)
             (assoc-in [:user :id] (:id user)))}))

;; 5. (Optional) — a subscription reading from a sensitive path inherits
;;    sensitivity by default (EP-0015 derived sensitivity). DECLASSIFY only
;;    if you've sanitised — use :rf.egress/output-sensitivity, NOT
;;    `:sensitive false` (`:sensitive` is a path collection at this layer):
(rf/reg-sub :auth/token-prefix
  {:rf.egress/output-sensitivity :rf.egress/public}  ;; author asserts safe
  :<- [:db/auth]
  (fn [auth _] (str (subs (:token auth) 0 8) "...")))
;;    Xray enumerates every :rf.egress/public claim as a standing audit
;;    surface (the declassification analogue of the global-scope list).

;; 6. (Optional) — install a PROJECTION-SIDE epoch redact-fn for
;;    defence-in-depth redaction of slots no classification covered (raw
;;    exception messages, custom :trace-events slots). EP-0015 issue 6: the
;;    hook runs at off-box EGRESS (inside projected-record, after the
;;    frame/profile projection), NEVER at storage — the in-process ring
;;    stays raw (causal replay material).
(rf/configure! {:epoch-history
  {:redact-fn (fn [record]
                ;; Scrub :exception-message on any captured trace event.
                (update record :trace-events
                        #(mapv (fn [ev]
                                 (cond-> ev
                                   (= :error (:op-type ev))
                                   (update :tags dissoc :exception-message)))
                               %)))}})

What every observation surface sees after the cascade settles:

Surface Observation
Handler body (:auth/log-in) Real password value in :event coeffect (via the regular handler arg)
Trace bus :rf.event/dispatched [:auth/log-in {:email "..." :password :rf/redacted :totp-code :rf/redacted}], top-level :sensitive? true
Trace bus :rf.fx/handled for :rf.http/managed :rf.fx/args body and params scrubbed (per-call :sensitive? true); :headers X-MyApp-Session value :rf/redacted (denylist hit)
Trace bus :rf.event/db-changed [:auth :token] slot renders :rf/redacted (frame :sensitive {:app-db ...}, plus event-arg propagation from :auth/log-in-success)
Xray App-DB Diff panel Same as above (Xray projects via project-egress under :rf.egress/local-redacted, consulting the same frame classification)
MCP get-app-db tool response :rf/redacted at the marked slots (projected under :rf.egress/off-box-tool); :dropped-sensitive N envelope counter set to the count of dropped leaves
Off-box log shipper (Datadog/Sentry) Routed by frame :observability under :rf.egress/off-box-observability; drops the whole :rf.event/dispatched and :rf.fx/handled events (top-level :sensitive? true); ships the structural skeleton only
Always-on error-emit substrate (production survives) The error record carries :sensitive? true and the listener-side projection honours it before egress to Sentry
Epoch projected-record All of the above redactions plus the projection-side :redact-fn's extra scrub (applied at egress, never at storage); the structured :effects rows' :args fail closed to :rf/redacted off-box (lifted only by :include-fx-args? true); the in-process ring + listener fan-out see the RAW record

What's NOT covered by this declaration set:

  • An ex-info message that interpolates the password into the string ((throw (ex-info (str "User " email " failed login") {...}))) — the path walker can't resolve into a string substring. See §Author guidance — the exception-path residual below.
  • An ex-data map whose author-chosen key name ({:user/email "..."}) has no relationship to the path-marked declarations. Substitute :rf/redacted at the assembly site, or omit the key.

Author guidance — the exception-path residual

Classification declarations are projected at the six observation boundaries named above. Projection walks known data shapes; it does NOT walk exception messages or ex-data map keys. The residual surface — the handler read a sensitive value AND threw with that value in ex-message or ex-data — is author responsibility. Per 015 §Author guidance for the exception-path residual and Security §Author guidance for exceptions under path-level :sensitive?:

Anti-pattern Preferred
(throw (ex-info (str "User " email " failed login") {:user/email email :reason :invalid-credentials})) — leaks email into :exception-message and :exception-data (throw (ex-info "Invalid credentials" {:reason :invalid-credentials})) — name the category in the message; correlate via :dispatch-id against the (correctly redacted) :db-before snapshot
Author-named ex-data keys carrying the sensitive value Substitute :rf/redacted at the assembly site, or omit the key entirely

The framework deliberately does NOT ship a safe-throw helper — the call-site knowledge of which ex-data keys correspond to sensitive paths in this specific app is author knowledge, not framework knowledge. A twelve-line per-app safe-throw helper is the recommended shape; worked example at docs/guide §24.08 — Exceptions under :sensitive?.

Removed surfaces

Surfaces that previously lived in this matrix and have been removed. Listed here so readers don't search for them in v1.

Surface Removed by Why
add-marks / set-marks (public app-db path-mark API) EP-0015 §3 Durable app-db egress policy belongs to the frame (reg-frame :sensitive {:app-db …} / :large {:app-db …}), not a post-creation imperative mutation. The underlying fns survive as internal/test/generated-code helpers only; they are not part of the public façade.
declare-sensitive-header! / declare-sensitive-query-param! (and clear-*!) EP-0015 §3 App-specific HTTP carrier names belong on the frame (:sensitive {:http {:headers […] :query-params […]}}), union onto the immutable built-in defaults — not process-global mutation.
redact-interceptor (public positional interceptor) EP-0015 §7 Made privacy depend on interceptor placement rather than payload ownership. Registration-owned :sensitive classifies event payload paths; centralized project-egress projects at egress. re-frame.privacy/redact-interceptor survives as internal router plumbing only (not façade-published).
Schema-attached :sensitive? / :large? as the public app-db classification route EP-0015 §8 Schemas describe shape; the frame owns durable app-db egress policy. Per-slot props remain the one route for owner-local schema'd data (machine / resource / HTTP-body), not a second route for frame-owned app-db. The boot hydrators survive as an internal migration importer.
inject-cofx (public cofx-injection interceptor) EP-0017 Coeffect dependencies are declared with :rf.cofx/requires registration metadata; reg-cofx is value-returning + graded. inject-cofx is removed (calling it is the hard error :rf.error/inject-cofx-removed). Named here because cofx values are a classification surface.
Handler-meta :sensitive? registration flag Coarse (whole-handler scope) when the data was always path-shaped. Replaced by Spec 015 per-path declarations. Handlers that were the unit of sensitivity (the rare "this whole cascade is sensitive" case) re-express by declaring the path-marks that the handler reads / writes.
:rf.fx/sensitive-mode configure key (audit name) never landed Replaced by per-call {:sensitive? true} on :rf.http/managed args; the audit-era name set-trace-redaction-policy was a working-document placeholder that never landed in re-frame.core.
rf/safe-throw framework helper (proposed) declined Author-level concern; per-app helpers conform better to the local convention than a framework default. Worked-example shape lives in the docs/guide.

Cross-references

Primary contract owners

Cross-cutting conventions

Implementation cross-references

  • tools/mcp-base/spec/sensitive.md — cross-MCP sensitive-event? / strip-sensitive / scrub-snapshot walkers and the :include-sensitive arg vocabulary (the unqualified MCP wire key; the ? is retained only on the internal :rf.size/include-sensitive? walker option and the config-knob verb).
  • tools/mcp-base/spec/elision.md — cross-MCP elision walker + the :include-large? arg vocabulary.

API.md projection

Author-side guide