Skip to content

docs(adr): ratify ADR-004 and make step 2 of the emission sequence checkable - #11

Merged
qmarcelle merged 1 commit into
mainfrom
docs/adr-004-ratify
Jul 28, 2026
Merged

docs(adr): ratify ADR-004 and make step 2 of the emission sequence checkable#11
qmarcelle merged 1 commit into
mainfrom
docs/adr-004-ratify

Conversation

@qmarcelle

Copy link
Copy Markdown
Contributor

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 ProposedAccepted with a 2026-07-28
decision date, and the index row is updated to match. Per the status vocabulary
in docs/adr/README.md, Accepted means the record is in force and this
repository 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 change
  • pnpm -r build — unaffected, docs-only change
  • pnpm -r test — unaffected, docs-only change
  • pnpm run check:architecture — OK
  • pnpm run check:architecture:test — OK
  • pnpm run check:schema — OK
  • pnpm run check:examples — OK
  • pnpm run check:docs — OK
  • pnpm run release:verify-packs — unaffected, no package content changed

Boundary check

  • No producer, host-integration or site code added (see OWNERSHIP.md)
  • No @marcelle-labs/*, private Vreko source or workspace.vreko.json reference
  • No prescriptive policy field and no daemon assumption introduced
  • The four stable read paths are unchanged
  • No new ambient declare module for a standard-owned package

Release impact

  • Schema bytes unchanged — this record permits the change, it does not make it
  • Package name, version, bin, exports and files unchanged
  • No changeset — ratification is not itself release-facing

Notes

Why amend before accepting rather than after. On main today the only path
to 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.

…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.
Copilot AI review requested due to automatic review settings July 28, 2026 17:19

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@qmarcelle
qmarcelle merged commit f6bab96 into main Jul 28, 2026
3 checks passed
@qmarcelle
qmarcelle deleted the docs/adr-004-ratify branch July 28, 2026 17:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants