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

Destination

deploy-kit with its goals re-established, a spec I would write again from scratch, and a clear order of work from today until every Project is handed over to the estate path and deploy-config-schema is retired. The map produces decisions only; when it clears, /to-spec collapses it into the rewrite plan.

Notes

• Why now. spec/v1 (10,489 lines over 11 chapters) and 98 ADRs (67 model, 15 architecture, 2 deferred, 14 EMF) grew one decision at a time. The latest round (Stable Address, derived Move, Infrastructure Intent; Specify the Stable Address, the derived Move and the Infrastructure model, with their decision records #323) is specified ahead of both implementations. src/ is 12,463 lines and the EMF sources are about 12,000. Only delivery, _canary and _estate are on the estate path; about 30 Applications still deploy through deploy-config-schema.
• Sources to read rather than ask about: CONTEXT.md, spec/v1/00-overview.md, docs/adr/README.md and the 0001 premise, docs/architecture.md, docs/requirements.md, docs/architecture-rules.md, docs/research/, docs/mde/assignment.md, the open epics. The maintainer's local, untracked improve-arch.md and gitignored docs/specs/*.md are input, but they date from 2026-09-28, before the register's rebuild: their ADR numbers no longer resolve, and they describe 3,603 lines of src/.
• Fixed constraints, open only if a ticket argues why: one authored edit, with the compiler deriving everything procedural (never pairing written across files); ADRs justify and the spec is normative, rewritten in place, never superseded; delivery is Flux pulling a pinned render; for each Project, fleet-infra's hand-written objects stay authoritative until that Project hands over, and deploy-config-schema (whose descriptors deploy nothing) retires once no drift check reads it.
• Skills: grilling tickets call grilling and domain-modeling; research tickets call research. Every decision is put to the maintainer as multiple choice, recommendation first. A settled decision becomes an ADR or a CONTEXT.md change only when it is durable; otherwise it lives on its ticket.
• Running alongside, not on the map: the live handover work under Estate delivery: deploy with deploy-kit, pause and roll back, watch it from one dashboard #195 keeps landing (P1 bugs such as A Project on the estate path admits only the declared edge, while the old path's Traefik still serves it #310, A handed-over Project's old route names a port its Service keeps #311, A legacy foundation Project's serving location is stated in the handover ledger #316). The map may later reorder or cut it, but does not freeze it.
• No date. The coursework keeps priority until 30 October.

Decisions so far

• Measure which chapters, terms, ADRs and codes pay their way: 68 of 261 spec sections have no inbound link and 107 ## sections are linked from no code; 42 of 108 codes are pending; 3 ADRs are linked only from their register and 59 by no code; 36% of non-bot PRs since emf/ landed changed both implementations; mutation is 80% of CI minutes, emf 11%.

• Inventory what each live Application needs and what blocks its handover: the deploy-config-schema descriptors deploy nothing (fleet-infra holds every live object); the handover ledger misses four live Projects; seven namespaces and four database names break the derivation rules; ten needs have no chapter; four refusals fire on live shapes; nothing is handed over yet.

• Decide what deploy-kit is for after the course: an estate tool for the maintainer's own estate only, with no thesis riding on it; 0001's scale test binds the whole repository, so course-only artefacts lose their reason at the grade; learning stays off the main path as a no-cost seam that never wires in one cluster or one tenant.

• Re-state the goals and non-goals against the scale premise: render every Application and the foundation, leaving fleet-infra only bootstrap and pins; every live need modelled, with no escape hatch; refusals stay only where the hazard is real at this scale; non-goals are arbitration between people, multi-cluster and tenancy, push delivery and portability; co-testing is left to its own park.

• Decide the model-driven implementation's lifespan and sunset: full parity until Task 3 is submitted (with Navigate an Estate root for cross-file OCL in the model-driven implementation #338 landing as coursework), then tag and delete emf/ right after submission; Implement the Stable Address, the derived Move and Infrastructure Intent #324 lands TypeScript-only after that; the docs/mde reports stay as design history, the course's own text goes at the grade.

• Decide how the model meets the live needs no chapter covers: every need gets a concept (node datasets, L4 exposure via LoadBalancer, derived GPU request and priority class, lifecycle: scheduled, before sidecars, spawn templates, egress: internet, mongo and s3 engines with a bucket catalog, a provider's Service); duplicate host keyed on host and tier, low ports and root stay refused, capabilities and namespaced api admitted by the Platform; VSO is the only secret delivery, rabbitmq joins the grant union; mismatched names change by Move during handover.

• Decide how the model meets soft scheduling, spread, anti-affinity and parked replicas: no soft term enters (0017 stands, the eight preferences drop); gpu gains hard vendor and model; a node dataset binds to its node and derives the pin; replicas stays capacity with an opt-in hard across: node, so adguard-ha becomes one Process behind one VIP; parked: {reason} renders zero or a suspended CronJob and keeps claims.

• Decide how the foundation's HelmReleases are rendered and owned: controllers and servers are declared from their images; host-privileged node agents derive from node facts through a closed Platform catalog, owned by a new node project; Reloader, the Vault injector and CSI provider, and cert-manager retire (Traefik ACME issues the wildcard); no webhook is rendered; prometheus-operator stays.

• Decide how the model meets human access grants and Grafana content: human grants (OIDC group, built-in ClusterRole, cluster-wide) live in the Platform document; a Dashboard is a new concept (JSON beside the project file, folder derived from the Project, grafana.com vendored, uid checked); alert rules sit only on the monitoring stack the Platform names by role; receivers are platform-declared; alertClass is dropped.

• Decide what is cut, merged or deferred from the spec and the register: chapters hold normative content and short rationale only; a code refuses authored hazards (of 42 pending codes, 14 cut, 2 folded, 26 kept); the reconciliation ledgers and 0038 go for a per-handover diff; chapter 50 dissolves into 55 and 40; chapter 60's procedures become a runbook; only resolved, rendered and refusal oracles stay; four ADR folds, and 0068 leaves with emf/.

• Decide between a spec/v2 and reworking v1 in place: in place at spec/v1; each chapter lands with its code, examples, oracles and schemas; additions ship first and one contract pull request carries every removal, releasing package 1.0.0 with schemaVersion 1.0.0, in lockstep from then on (0007 is rewritten); delivery, _canary and _estate republish once.

• Order the Project handovers and what the spec must settle before each: the estate-path fixes and the 1.0.0 contract come before any handover (app first, no 1.x tracer); Applications go first and the foundation last, secrets after the injector retires; ready-first ordering over a seven-step concept build; done means a clean diff, Ready units and a checked value, then one change flips the ledger and deletes the fleet-infra objects and the descriptor; deploy-config-schema is archived after the last drift check.

• Decide the fate of the open work that predates the map: the model-as-code epic and the architecture rework close (residue listed as rewrite inputs); the Moves epic stays, TypeScript only, blocked on this map; decided triage closes; kept model work is blocked until emf/ is deleted; hardening holds except where the Platform admits a deviation.

• Decide the chapter layout of the rewritten spec: a pipeline frame (00, 10, 14, 15, 20, 30, 40, 55, 60) plus end-to-end concept chapters (11 Processes, 12 Exposure, 13 Data, 16 Dependencies, 17 Secrets and access, 18 Placement, 19 Observability), each owning its Platform-side fields; numbers kept and 50 retired; diagrams to spec/v1/diagrams/, procedures to docs/runbooks/; one move-only pull request right after emf/ goes, before any rewrite.

• Decide where the rewritten spec states one cluster or one tenant as an instance: the Cluster is one named instance, its count stated once in chapter 15; Infrastructure Intent declares its name, and the Platform document and the ClusterState snapshot are refused when they name another; the per-cluster env overlay is cut, so Project Intent never names a Cluster; uniqueness is stated within the composed union and the three span-clusters open items move to 0097; Estate enters the glossary as the scope above a Project, with no Tenant class; "Cluster Target" is retired and "tenant" reserved for 0097; the DNS domain, the ExternalName address, the one auth mount, the one Flux root and the API groups stay fixed facts.

• Decide how the decision register is renumbered and rewritten: a number is retired for good and listed in a linted Retired numbers table; in a fold the lowest number survives and the file is renamed (0092 absorbs 0041); 0068 is deleted with emf/ and its oracle clause moves to 0088; the meaning-preserving folds, the numbering rule and a lint:links check on ADR paths in code land in one register pull request after the move-only one; 0001 is rewritten with chapter 00 (first among the rewrites), 0097 with chapter 15, and 0007, 0032 with 0044, 0038 and 0024 in the contract pull request; issue links are not swept; no new ADR.

• Audit the compiler's modules, seams and architecture rules against the scale premise: 89 modules and 12,463 lines, 83 of them younger than two weeks; coverage and mutation score are 100% everywhere and tell no module from another; one concept sits in 7 to 21 modules; four ports the architecture document names are declared nowhere; 11 of 20 gates and 67 of 74 rules were never red in CI, and no compiler test ever failed there; mutation is 79.8% of CI minutes and caught survivors on 7 of 170 pull requests.

• Find the claims behind the settled decisions that no source supports: of 49 third-party and live-estate claims, 22 hold, 21 hold with a condition and 6 fail (the LAN Traefik also serves the wildcard; Alloy holds no host privilege; the Frankfurt node has no address pool; k3s lets a non-root process bind a low port; no workload reads a RabbitMQ dynamic credential; a dashboard without a uid does not collide); the table is docs/research/unsupported-claims.md, and two follow-up tickets carry the failures and the conditions.

• Decide the compiler's structure after the rewrite: stage folders and their rules stay, with one module per concept chapter inside model/, check/ and resolve/; the six mixed modules are split in one move-only code pull request after the register one; adapters are a closed registry by target vocabulary (new objects join kubernetes and prometheus, Dashboards add grafana), and pin sources and the node contract generator get a step of their own; the document follows the code on ports; 0056, 0058 and 0063 are rewritten and the other 11 architecture records stay; no gate is cut, RULE-046 and RULE-047 are enforced, and the Layers table is held to the graph; mutation runs incrementally on a pull request and in full weekly, landing now.

• Decide what each settled decision does about the claim under it that failed: cert-manager still retires and every acme tier issues its own certificate, the LAN one included; Alloy is an ordinary Process and the Node Agent catalog keeps four host-privileged entries; the Platform declares named L4 Addresses, a pool or a node's own address, the second rendering hostPort with a derived pin, and a tier names the one its proxy listens on; E_PRIVILEGED_PORT_UNDER_NONROOT is cut after a drill bound port 80 as non-root, landing with chapter 11; rabbitmq stays a dynamic grant on condition of a rotation drill before chapter 17; both dashboard uid refusals stay, the missing one because its address changes on recreation.

• Decide which conditions on the settled decisions change the model: of sixteen conditions, one adds a refusal (the proxy of an acme tier takes one replica) and one a Platform-authored list (the critical-class Applications); the across: node term is scoped to one revision, a scheduled Process derives a 300-second start deadline, a pool's site derives its announcers and pins its users, static secrets poll every 10 minutes, egress: internet excludes a fixed non-public set, and the GPU share count and the RabbitMQ lease lifetime are catalog facts; loki-canary is dropped, no Vault token is delivered, and a HelmRelease is suspended before it is deleted; two drills confirmed the rollout stall and the catch-up run, and no Process gains a field.

Not yet specified

Nothing: every patch has graduated into a ticket. New fog is added here if a resolution exposes it.

Out of scope

• The coursework deadlines: Task 2 (16 October), the 22 October presentation and Task 3 (30 October, Write the Task 3 code generation report #98). A decision that affects them is flagged on its ticket, not absorbed.
• The live handover bugs and features under Estate delivery: deploy with deploy-kit, pause and roll back, watch it from one dashboard #195, which continue on their own tickets.