docs(spec): pin :rf.machine/destroyed-on-frame-exit dual-emit shape in spec/009 (rf2-fq2o)#409
Merged
Merged
Conversation
…n spec/009
Rewrite the spec/009 entry for the frame-exit machine teardown trace
events to normatively pin the two-emit shape, with the two op-types
spelled out:
- :op-type :machine, :operation :rf.machine/destroyed-on-frame-exit
— the reason event (machine-substrate observers branch on
:operation to discriminate teardown causes).
- :op-type :rf.machine.lifecycle/destroyed,
:operation :rf.machine.lifecycle/destroyed — the uniform-shape
lifecycle event (mirrors :rf.machine.lifecycle/created at
reg-machine; lifecycle observers see one consistent op-type
across create and destroy regardless of cause).
Document the consumer-intent split: the :machine event answers
'why is this actor going away?'; the :rf.machine.lifecycle/destroyed
event answers 'did an actor's lifecycle just close?'. Both fire from
the same destroy walk so a consumer observing both sees them adjacent
in the stream.
Note that the :rf.machine/destroyed event from fx.cljc carries a
:reason tag, and a future refactor may unify the dual-emit above into
a single :reason-tagged emit. This spec pins the current shape.
Cross-spec updates:
- Spec-Schemas.md §:op-type table — pin
:rf.machine.lifecycle/created / -destroyed as op-types in their
own right; cross-link the :machine op-type entry to the dual-emit.
- skills/.../frames.md — update the destroy-frame gotcha to mention
both emits.
Pure spec edit; no impl or test changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Spec 009's entry for
:rf.machine/destroyed-on-frame-exit(line 109 pre-edit) read ambiguously — the keyword listed could be parsed as both the operation AND the:op-typeit travels under, and the dual-emit shape thatframe.cljcactually produces was only implicitly described. This PR pins the shape normatively.Per active machine snapshot,
destroy-frame!emits two trace events in order, with identical:tags {:frame :machine-id :last-state}, differing only in(:op-type, :operation):The machine-substrate reason event —
:op-type :machine,:operation :rf.machine/destroyed-on-frame-exit. Tells observers why an actor is going away (frame-exit), letting machine-keyed cleanup hooks discriminate teardown causes (sibling reasons::rf.machine/finished,:explicit,:parent-unmount-cascade).The uniform-shape lifecycle event —
:op-type :rf.machine.lifecycle/destroyed,:operation :rf.machine.lifecycle/destroyed. Mirrors:rf.machine.lifecycle/createdatreg-machineso lifecycle observers consume one consistent op-type for create and destroy across every cause and code path.Consumer-intent split: the
:machineevent answers "why?"; the lifecycle event answers "did an actor instance just close?". Both fire from the same destroy walk so an observer subscribing to both sees them adjacent in the stream.Future-direction note inline:
fx.cljc's:rf.machine/destroyedalready carries a:reasontag enumerating cause. A future refactor may unify the dual emit into a single:reason :parent-frame-destroyedemit in the same shape; out of scope here.Files touched
spec/009-Instrumentation.md— primary rewrite of the:rf.machine/destroyed-on-frame-exitbullet.spec/Spec-Schemas.md—:op-typetable: cross-link:machineto the dual-emit; pin:rf.machine.lifecycle/created/-destroyedas op-types in their own right.skills/re-frame2/reference/fundamentals/frames.md— update thedestroy-frame!gotcha to mention both emits.Pure spec edit. No impl, no tests.
Test plan
mkdocs build --strict— 220 warnings (baseline 220; no new warnings introduced).implementation/core/src/re_frame/frame.cljc:257-264(the twotrace/emit!calls).grep -rn "destroyed-on-frame-exit" spec/ docs/ skills/— all hits consistent with the pinned shape.