Skip to content

docs: align ADRs and the model-driven implementation with the proposal - #103

Merged
ExtraToast merged 1 commit into
mainfrom
docs/align-with-proposal
Sep 14, 2026
Merged

ExtraToast merged 1 commit into
mainfrom
docs/align-with-proposal

Conversation

@ExtraToast

Copy link
Copy Markdown
Contributor

Part of #78. Follows #102, the revised Task 0 proposal, which is now the leading description of the project.

What this branch does

A review of main against the revised proposal found three kinds of drift, and this branch aligns them. No model decision in spec/v1 changes.

The proposal's shape of the model-driven implementation. The proposal defines two metamodels, not four: Project Intent as source and the Resolved Deployment as target, with the Deliverable Set as the generated files. It names the TypeScript code the production implementation and the EMF code the model-driven implementation, compares the two on validation, dependency resolution, errors and generated resources, and has the Xtext-generated editor run the OCL validators during editing. emf/docs/architecture.md, the model-driven register and ADRs 0108 to 0113 said otherwise; they now match, each changed ADR carrying an amendment note. 0109 changed its decision and is renamed to 0109-source-and-target-metamodels-are-hand-written.md.

The parity contract. docs/architecture.md#the-parity-contract states what binds whom. Parsed intent, diagnostics, generated files and the source metamodel's descriptor bind both implementations. resolved.json binds the production implementation only, and a new oracle, expected/dependencies.json, carries the resolved dependency edges both must agree on. ADR 0105 carries the amendment.

Damage left by #100. The rename turned the ADR sense of "domain" into "project" in CLAUDE.md ("one directory per project", "the project table", "another project", "the emf project in scripts/lint-adrs.ts") and in README.md, and capitalised "Project repository" in 0065. All are restored.

The decisions later tickets inherit

These are judgement calls where the two implementations deliberately differ:

  • The target metamodel is not the production Resolved Deployment. The production implementation keeps layer 2 in model words and builds typed objects separately. The model-driven target metamodel holds both, because an Acceleo template reads one model. This keeps spec/v1's three layers intact while matching the proposal's two metamodels.
  • Dependency resolution is compared as edges, not as a whole model. Per Application: consumer, provider Application and Surface, the address given to the consumer, and the policy peers. It gives Task 2 evidence before any file is rendered.
  • The trace is production only. It stays part of resolved.json (Specify the trace and check chapter 16's three properties on it #48); QVTo does not have to emit it.
  • The Platform document sits in the source metamodel. The proposal lists no platform metamodel, and the transformation resolves a Project against the platform data.
  • Templates are tested from hand-written target models inside emf/ until the transformation covers a case. They are test input, never oracles.
  • Backup and sweep jobs stay in scope. The proposal's generated-resources table is a summary; the specification and the storage row ("how it is recovered") still require them.

Tickets. 18 open issues were aligned on GitHub: #78 (retitled for the production and model-driven names), #41, #42, #48, #56, #80, #82, #85, #86, #87 (now the target metamodel only, retitled), #88, #90, #91 (trace dropped, retitled), #92, #93, #94 (retitled), #95 and #96. #56 records which of its items #101 and #102 already superseded.

Verification

  • npm run verify exit 0: ADR lint: 93 files clean, link lint: 172 files clean, 305 tests passed.
  • node scripts/lint-adrs.ts emf reports 9 files clean.
  • Checked by reading the proposal source on main (Sections/01 to 06) against CLAUDE.md, README.md, CONTEXT.md, docs/architecture.md, emf/, the ADR registers and every open issue that names a metamodel, an oracle, the trace or the editor.

@ExtraToast ExtraToast added type: docs Documentation-only change. area: deploy homelab-deploy, deploy-v2, manifests, and rollout flow. component: docs Runbook, README, API docs, or documentation tooling. labels Sep 14, 2026
@ExtraToast ExtraToast self-assigned this Sep 14, 2026
@ExtraToast
ExtraToast merged commit 3f43692 into main Sep 14, 2026
13 checks passed
@ExtraToast
ExtraToast deleted the docs/align-with-proposal branch September 14, 2026 14:41
ExtraToast added a commit that referenced this pull request Sep 15, 2026
The task table only described each report by subject, not by which of
the two metamodels its task delivers. Name Project Intent and Resolved
Deployment per task, matching emf/docs/architecture.md's task table and
the two-metamodel shape #102 and #103 settled on.
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: docs Runbook, README, API docs, or documentation tooling. type: docs Documentation-only change.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant