Decide between a spec/v2 and reworking v1 in place #348

Activity

1. ExtraToast

   added

   type: docsDocumentation-only change.Documentation-only change.

   area: deployhomelab-deploy, deploy-v2, manifests, and rollout flow.homelab-deploy, deploy-v2, manifests, and rollout flow.

   wayfinder:grillingWayfinder ticket resolved by conversation (HITL)Wayfinder ticket resolved by conversation (HITL)

   on Oct 9, 2026
2. ExtraToast

   added a parent issue on Oct 9, 2026

   • Map: re-establish deploy-kit's goals, rewrite its spec, and order the work until the estate is handed over #341
3. ExtraToast

   marked this as blocked on Oct 9, 2026

   • Decide what is cut, merged or deferred from the spec and the register #346
4. ExtraToast

   marked this as blocking on Oct 9, 2026

   • Order the Project handovers and what the spec must settle before each #349
5. ExtraToast

   added

   status: in-progressActively being worked.Actively being worked.

   on Oct 9, 2026
6. ExtraToast

   self-assigned this

   on Oct 9, 2026
7. ExtraToast commented on Oct 9, 2026

   

   ExtraToast

   on Oct 9, 2026

   ContributorAuthor

   More actions

   Resolution

   Settled with the maintainer on 2026-10-09, after Decide what is cut, merged or deferred from the spec and the register. The rewrite starts after Task 3 is submitted on 30 October, and emf/ is deleted right after that (Decide the model-driven implementation's lifespan and sunset), so the rewrite carries no parity cost.

   Where the rewrite lives

   In place, at spec/v1. Chapters are rewritten in their own files, and git is the change log. This is the same rule the register follows: a decision is rewritten, never superseded. There is no spec/v2 beside it and no rename to an unversioned spec/. A second directory would need a rule for which spec wins while both exist. A rename would churn 110 tracked files and break the published path that the delivery services read. Under the lockstep below, v1 in the path means major 1, which is true.

   Pace

   A chapter and its code land together. Each chapter's pull request carries its src/ change, its worked examples, its oracle files and its JSON Schemas. The spec never describes unbuilt behaviour beyond what a pending code tracks. This is unlike #323, which specified ahead of both implementations.

   Break order: expand first, contract once

   • New vocabulary and new concepts (the live needs from Decide how the model meets the live needs no chapter covers #351, Decide how the model meets soft scheduling, spread, anti-affinity and parked replicas #355, Decide how the foundation's HelmReleases are rendered and owned #356 and Decide how the model meets human access grants and Grafana content #357) land first, as additive releases. A fragment written today still composes, and the handover fixes under Estate delivery: deploy with deploy-kit, pause and roll back, watch it from one dashboard #195 keep releasing throughout.
   • Every removal and every change of meaning waits for one contract pull request. That covers what Decide what is cut, merged or deferred from the spec and the register #346 cut and what the live-need tickets dropped or redefined (alertClass, the soft placement preferences, the reconciliation ledgers, secret delivery self, and the rest).

   Versions

   • The contract pull request releases package 1.0.0. release-please is steered there with a Release-As footer, never by hand-editing the version.
   • schemaVersion stays 1.0.0 through the breaking cuts. Nothing is truly deployed yet, so 0044's "major on removal" is waived once rather than producing a 2.0.0.
   • From 1.0.0 on, the package and the model move in lockstep: schemaVersion is exactly the package version a fragment was validated with, patch included. Composition's admission rule is unchanged: same major, and a minor no newer than the toolkit's. The patch is ignored for admission.
   • This reverses 0007 (the data model's version is not the package's). 0007 is rewritten in the contract pull request, and so is the fold of 0032 and 0044 that Decide what is cut, merged or deferred from the spec and the register #346 decided, which takes the lockstep range. The reason for the reversal: one number to reason about, now that the model and the toolkit have one maintainer and one release train.

   The artifacts already carried

   • JSON Schemas stay at spec/v1/schemas, hand-written, with their corpus as the contract (0088). Additions land in the expand pull requests and removals in the contract pull request. The in-cluster delivery services regenerate their types against 1.0.0.
   • Oracle files keep the layers Decide what is cut, merged or deferred from the spec and the register #346 chose (resolved, rendered tree, refusals). They are updated in each chapter's pull request and are never regenerated in CI.
   • Worked examples keep the same set (minimal, auth, data, delivery, edge, knowledge, knowledge-platform, _estate) and are rewritten with their chapters. A live need that no example shows gets one. RENDER-GAPS.md is resolved or cut by the rewrite.
   • The live estate path: delivery, _canary and _estate republish once, on 1.0.0.

   Consequences for other tickets

   • Order the Project handovers and what the spec must settle before each (Order the Project handovers and what the spec must settle before each #349) is unblocked. The 1.0.0 contract release sits before the first handover, because each handover makes a breaking release more expensive.
   • The chapter layout graduates from Not yet specified into its own ticket: both of its prerequisites (the cut list and this question) are settled.
8. ExtraToast

   closed this as completedon Oct 9, 2026
9. ExtraToast

   removed

   status: in-progressActively being worked.Actively being worked.

   on Oct 9, 2026
10. ExtraToast

    marked this as blocking on Oct 9, 2026

    • Test schema migrations as model-to-model steps #54