feat(spec): settle schema identity — bare-host $id, no rename, single-file profile carriage - #14
Merged
Merged
Conversation
…DR-005 (META-272) The schema $id was https://www.workspacejson.dev/schema/v1.json while every package manifest and doc uses https://workspacejson.dev without the www. prefix. Both hosts serve the schema, but the strings disagreed — and versioning.md instructs consumers to hash-check the materialized schema, making $id part of the contract surface. Changed to https://workspacejson.dev/schema/v1.json. Filename v1.json unchanged. Folded into the same release as ADR-004 so consumers experience one schema-byte transition rather than two consecutive pin invalidations. - ADR-005 authored and accepted - $id updated in schema/v1.json and schema.ts - CANONICAL_ID test constant updated - versioning.md, conformance.md, packages/spec/README.md updated - Changeset added (patch, folds with existing ADR-004 changeset into 0.4.5) Verification: - pnpm -r typecheck: OK - pnpm -r build: OK - pnpm -r test: 221 tests passed (48 spec + 173 rules) - pnpm run check:architecture: 145 files, 0 violations - pnpm run check:architecture:test: 25 passed, 0 failed - pnpm run release:verify-packs: both tarballs release-safe - pnpm run check:schema: $id confirmed as bare domain
Two ADR-005 records were authored concurrently against the same branch. This keeps the host reconciliation exactly as implemented and folds in the two decisions that were made alongside it but not recorded, leaving one record. Fixes a stale reference that would have shipped. packages/spec/README.md documented the $id as the www host in a code example while the same file stated the bare host as canonical twelve lines later. README.md is in the package files array, so the published tarball would have told consumers the old string was the value to compare against — the precise use the record calls part of the contract surface. Adds the two decisions: The file is not renamed. Not deferred, decided against: an open question invites a later rename, and a rename is a second byte change and a second invalidated digest. The name is already invisible to consumers, since the export key is ./schema and the filename leaks only through the $id path component. No sibling schema document will be introduced. Profiles continue to ride the generated.specVersion enum with per-profile constraints as conditional subschemas. This is what makes the rename decision hold — a filename only needs to disambiguate when there is something to disambiguate from. Also records the additionalProperties constraint encountered while implementing ADR-004: it considers only properties declared in the same schema object, so a single file must declare the union of every retained profile's root properties. Corrects Depends on, which said Nothing while the release-folding argument rests entirely on ADR-004. check:docs now passes; the superseded draft carried an internal tracker identifier in public prose and was not covered by the earlier verification run.
qmarcelle
changed the title
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
Settles the schema's identity — as distinct from its contents — and makes the
one byte change that follows.
Two commits. The first reconciles the
$idhost. The second consolidates twoconcurrently-authored ADR-005 records into one, folds in the two decisions that
were made alongside the host but not written down, and fixes a stale reference
that would have shipped to npm.
The change
$idmoves fromhttps://www.workspacejson.dev/schema/v1.jsontohttps://workspacejson.dev/schema/v1.json.This is consistency restoration, not a new choice. Three surfaces already treat
the bare domain as canonical — the package manifests, the migration provenance
record, and
workspacejson/cli, whose architecture test has been asserting ahost this repository did not emit. The schema was the outlier.
Both hosts continue to serve the schema. Only a consumer comparing the
$idstring byte-for-byte, or holding a pinned digest, observes anything.
Two decisions recorded, neither changing bytes
The file is not renamed. Decided against, permanently — not deferred. An open
question invites a later rename, and a rename is a second byte change and a
second invalidated digest. The name is already invisible to consumers: the export
key is
./schema, so the filename leaks only through the$idpath component.The misleading
v1is a documentation problemversioning.mdalready solves inprose.
No sibling schema document will be introduced. Profiles continue to ride the
generated.specVersionenum with per-profile constraints as conditionalsubschemas — the mechanism ADR-004 established. This is what makes the rename
decision hold: a filename only needs to disambiguate when there is something to
disambiguate from.
Recording both together is deliberate. The second is load-bearing for the first,
and a reader who finds only one cannot reconstruct why either holds.
Defect fixed
packages/spec/README.md:55documented the$idas thewww.host in a codeexample, while the same file stated the bare host as canonical at line 148.
README.mdis in the packagefilesarray, so the published tarball would havetold consumers the old string was the value to compare against — exactly the use
this record designates part of the contract surface.
Also corrects
Depends on, which readNothingwhile the entire release-foldingargument rests on ADR-004.
Why this ships in 0.4.5
That release has not published. A consumer moving from
0.4.4sees onetransition covering both the ADR-004 widening and the corrected identity.
Publishing 0.4.5 first would make this a second pin invalidation.
It must not ride in v0.5, which carries profile changes. Two independent
byte-changing reasons in one release are indistinguishable to someone debugging
a digest that no longer matches.
Verification
pnpm -r typecheck— clean, both packagespnpm -r buildpnpm -r test— 221 passed (48 spec, 173 rules)pnpm run check:architecturepnpm run check:architecture:test— 25 passedpnpm run check:schema—$idconfirmed barepnpm run check:examples— 4/4pnpm run check:docs— now passing; the superseded draft carried an internal tracker identifier in public prose and was not covered by the earlier verification runpnpm run release:verify-packspnpm run check:conformanceagainst the real producer — 28/28Boundary check
OWNERSHIP.md)@marcelle-labs/*, private Vreko source orworkspace.vreko.jsonreferencedeclare modulefor a standard-owned packageRelease impact
$idhostbin,exportsandfilesunchanged; the./schemaexport key does not moveNotes
Status is
Accepted. Recorded on the basis that both questions were decidedexplicitly before the record was written. Say so and I will move it to
Proposed— it is a one-line change and the index row.
migration/is untouched. Those files record what was true at migration timeand are not rewritten to match a later decision; the remaining
www.stringsthere are correct as history.