Skip to content

feat(model): refuse a fragment written at a model version the toolkit does not read - #670

Merged
ExtraToast merged 1 commit into
mainfrom
feat/665-schema-version-mismatch
Oct 27, 2026
Merged

ExtraToast merged 1 commit into
mainfrom
feat/665-schema-version-mismatch

Conversation

@ExtraToast

Copy link
Copy Markdown
Contributor

Summary

Composition now refuses a fragment written at a model version the toolkit cannot read, so a newer fragment can no longer compose with its new fields silently dropped.

  • The range from chapter 40: a fragment at another major (either direction), or at a newer minor than the toolkit's, is E_SCHEMA_VERSION_MISMATCH. A patch difference never gates.
  • A participant's own error: the Project is held at the fragment it last composed at, even when the digest didn't change, and dormancy doesn't exempt it. The issue body names the rule that fired, the fragment's reference and the version it was written at.
  • The Platform document at such a version stops the run, and the message names the rule and the reference.
  • Nothing readable left to hold at: if the fragment a Project would be held at, or the one a Rollback names, is itself unreadable, the run stops and names the Project and the fragment. Composing it would drop exactly the fields this check protects.
  • The toolkit's model version follows releases: SCHEMA_VERSION carries x-release-please-version, and src/cli/main.ts is listed in extra-files, so release-please writes it beside package.json. chore(main): release 1.0.0 #631 writes 1.0.0 (the cut's Release-As), so nothing changes before 1.0.0.
  • Docs: chapter 40's isolation paragraph, the REQ-050 row, and the code removed from the Slice 7: every refusal through check/, the pending codes included #204 pending list in lint-codes.

Decided here

  • Ships in 1.0.0 (the maintainer, 2026-10-27). The composer that has to refuse a newer-minor fragment is the older toolkit, so 1.0.0 must carry the check itself.
  • Chapter 40 changed meaning in one sentence (the maintainer, 2026-10-27). It used to say a toolkit that no participant's version accepts "holds every Project still and fails nothing". Holding a Project still without composing it would leave its consumers refused. So the run now stops instead, and the version rollout (republish before bumping the estate's pin) avoids it.
  • Release-please sets the model version (the maintainer, 2026-10-27), rather than a constant nobody bumps.

Test plan

  • npm run verify (2480 tests)
  • Compose runs: newer minor, other major in both directions, older minor and other patch admitted, dormant participant, Platform document, unreadable fallback, unreadable Rollback, and the hint
  • The CLI test asserts the lock against SCHEMA_VERSION, not a literal, so a 1.1.0 release PR stays green

Part of #195.
Closes #665

… does not read

Composition admitted every fragment whatever schemaVersion it was written
at, so a fragment at a newer minor composed with the fields the toolkit
could not read dropped, and the run exited zero. A participant whose
fragment is at another major, or at a newer minor than the toolkit's, is
now E_SCHEMA_VERSION_MISMATCH: isolated at the fragment it last composed
at, dormant or not, and a Platform document at such a version stops the
run. A patch difference never gates. Where the fragment a Project would be
held or rolled back at is itself one the toolkit cannot read, the run stops
too, since composing it would drop the same fields.

The toolkit's model version is release-please's to set, beside
package.json, so the range moves with every release.

Closes #665
@ExtraToast ExtraToast added type: feature New user-facing or operator-facing capability. area: deploy homelab-deploy, deploy-v2, manifests, and rollout flow. component: deploy Deployment pipeline, manifests, or release rollout. priority: P1 High; important and should be handled in the current iteration. labels Oct 27, 2026
@ExtraToast ExtraToast self-assigned this Oct 27, 2026
@ExtraToast
ExtraToast enabled auto-merge (squash) October 27, 2026 14:02
@github-actions

Copy link
Copy Markdown

Shape

bucket files additions deletions
production code 2 +88 -20
tests 2 +176 -2
specification 1 +8 -3
documentation 1 +1 -1
tooling 2 +1 -1

Coverage

Baseline: main @ 30bc541.

metric this branch main diff
statements 99.74% 99.74% 0.00
branches 98.57% 98.56% +0.01
functions 100.00% 100.00% 0.00
lines 99.72% 99.72% 0.00

Lines this pull request changed: 23/23 covered (100.00%).

@ExtraToast
ExtraToast merged commit 8568aaf into main Oct 27, 2026
36 checks passed
@ExtraToast
ExtraToast deleted the feat/665-schema-version-mismatch branch October 27, 2026 14:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: deploy homelab-deploy, deploy-v2, manifests, and rollout flow. component: deploy Deployment pipeline, manifests, or release rollout. priority: P1 High; important and should be handled in the current iteration. type: feature New user-facing or operator-facing capability.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Raise E_SCHEMA_VERSION_MISMATCH when composing a fragment

1 participant