docs(adr): ratify ADR-004 and make step 2 of the emission sequence checkable - #11
Merged
Conversation
…eckable Two changes to one record. Adds an adoption criterion to the emission sequence. Step 2 previously said "wait for adoption" without stating what evidence ends the wait, which left the one genuinely dangerous step in the sequence resting on judgment. It now requires a census of known validate-before-read consumers, recording the validator version each runs and whether that version accepts the optional root key, with an undeterminable entry counting as not accepting. The paragraph also states the limit of the claim rather than overselling it: a census cannot enumerate unknown consumers, so the rule is bounded to not emitting while a known consumer is known to break. A fixed waiting interval is explicitly ruled out as a substitute, because an interval measures elapsed time and not adoption. Moves Status from Proposed to Accepted with a 2026-07-28 decision date, and updates the index row to match. Per the status vocabulary, Accepted means the record is in force and this repository conforms to it; the record remains unimplemented, and the schema, types and fixture work follows separately under the ordering in section 8.
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
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
Ratifies ADR-004 and closes the one gap in it that was cheaper to fix before
acceptance than after.
The §8 gap. Step 2 of the emission sequence said "wait for adoption" without
stating what evidence ends the wait. That left the only genuinely dangerous step
in the sequence — the one that produces artifacts older validators reject —
resting on judgment rather than a check. Step 2 is now an evidence requirement:
a census of known validate-before-read consumers, recording for each the
validator version it runs and whether that version accepts the optional root
key, with an undeterminable entry counting as not accepting.
The added text also states the limit of the claim instead of overselling it. A
census cannot enumerate consumers nobody knows about, so the rule is bounded to
what is checkable: do not emit while a known consumer is known to break. A
fixed waiting interval is explicitly ruled out as a substitute, because an
interval measures elapsed time and not adoption.
Ratification. Status moves
Proposed→Acceptedwith a 2026-07-28decision date, and the index row is updated to match. Per the status vocabulary
in
docs/adr/README.md,Acceptedmeans the record is in force and thisrepository conforms to it.
Note that the record is now in force but not implemented. The schema, types,
reference-reader widening and the six §7 fixtures follow separately, under the
ordering §8 sets out. Acceptance is what permits that work to begin — the schema
bytes are a normative surface, so they need an ADR in force, not merely merged.
Verification
pnpm -r typecheck— unaffected, docs-only changepnpm -r build— unaffected, docs-only changepnpm -r test— unaffected, docs-only changepnpm run check:architecture— OKpnpm run check:architecture:test— OKpnpm run check:schema— OKpnpm run check:examples— OKpnpm run check:docs— OKpnpm run release:verify-packs— unaffected, no package content changedBoundary check
OWNERSHIP.md)@marcelle-labs/*, private Vreko source orworkspace.vreko.jsonreferencedeclare modulefor a standard-owned packageRelease impact
bin,exportsandfilesunchangedNotes
Why amend before accepting rather than after. On
maintoday the only pathto change an accepted record is supersession by a new ADR that names it
(
docs/adr/README.md). A one-paragraph correction made now costs a paragraph;the same correction after ratification would cost a superseding record. ADR-003
introduces amendment as a cheaper second path, but it is not merged, so that
path does not yet exist.
Scope of the census requirement. It gates emission, not the acceptance
widening. The reader-preparation release adds no root key to any artifact and is
therefore unaffected by it — no census is required before that work proceeds.
The requirement binds the later release that first emits the field.