docs(adr): ratify ADR-004 — root version compatibility profile for v0.4.x - #10
Merged
Conversation
A document declares its profile in generated.specVersion. At least one external consumer gates on a root `version` key no producer has ever emitted, so that gate has never executed. Repairing the mismatch looks additive and is not. Two measurements taken against the shipped validator and the consumer's public reader decide the record: The root object is `additionalProperties: false`, so adding a root key invalidates every document that carries it. Both shipped examples flip from validate=true to validate=false. The change is additive to the schema and breaking for every deployed reader that validates before reading — which is what docs/conformance.md instructs consumers to do. Section 8 therefore sequences validator widening, adoption, and emission as three changes that must not land together. The external gate compares major components only against a hardcoded set, so every 0.x value passes and 1.0 does not. Emitting 0.4 now is safe and exercises a gate that has never run while the stakes are zero. Section 9 records the 1.0 boundary as a breaking change for that consumer regardless of this profile being additive, so the constraint outlives anyone's memory of the conversation. Also decides the equality invariant, absence and disagreement semantics, specVersion retention, validator widening over a named profile, and the fixture set including the perturbation pair that makes the invariant a test rather than prose.
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
Adds ADR-004, the transition record ratifying how an optional root
versionkeymay be accepted in the v0.4.x line, and the order in which acceptance and
emission are allowed to ship.
This is a decision record only. It changes no schema, no types, no validator
and no producer output. It is the ratification gate that the v0.4.5 reader-widening
work depends on.
Two measurements shaped the record and are reproducible from public materials:
additionalProperties: false, so adding a root key isadditive to the schema as a document and breaking for every already-deployed
reader that validates. Measured against
@workspacejson/spec@0.4.4: both shippedexamples validate today and both fail with a root key added.
component only against a hardcoded supported set, and returns
nullon mismatch —silent, total artifact loss. Every
0.xvalue passes;1.0trips it.Together those invert the assumed risk: emitting
0.4now is safe and exercises agate that has never run while the stakes are zero. The hazard is the 1.0 boundary,
recorded as a standing constraint in §9.
The consequence is §8's forced ordering — widen the validator, wait for adoption,
only then emit. Those are three changes, not one, and collapsing them is the
failure the sequence exists to prevent.
Verification
pnpm -r typecheck— unaffected, docs-only changepnpm -r build— unaffected, docs-only changepnpm -r test— unaffected, docs-only changepnpm run check:architecture— OK, 144 tracked files, 0 violationspnpm run check:architecture:test— 25 passed, 0 failedpnpm run check:schema— OK, canonical schema single-sourced and completepnpm run check:examples— OK, 4/4 examples validatepnpm run check:docs— OK, 125 links resolved, no tracker identifierspnpm 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
Status is
Proposed. Merging this publishes the record; ratification is theseparate act of moving Status to
Acceptedwith a decision date.No behavior change ships here. The schema/types/validator widening, and the
six conformance fixtures enumerated in §7, are the follow-on implementation work.
Index numbering. This adds row
004and skips003, which is drafted on aseparate branch. Whichever merges second will need a trivial
docs/adr/README.mdrebase — same table, adjacent rows.
Producer side.
workspacejson/clialready satisfies the constraints in §5 and§8 without changes: it emits
generated.specVersion: '0.4'and writes no rootversion. Its follow-on work is a receipt proving output shape is unchangedagainst the widened validator, not a producer change.