Skip to content

docs: record the EMF implementation and the parity contract binding it - #79

Merged
ExtraToast merged 1 commit into
mainfrom
docs/emf-double-implementation
Sep 14, 2026
Merged

ExtraToast merged 1 commit into
mainfrom
docs/emf-double-implementation

Conversation

@ExtraToast

Copy link
Copy Markdown
Contributor

Part of #78 (parent #35)

What this branch does

The course rejected the Task 0 proposal's substitution of TypeScript and Zod for the prescribed toolchain, so the compiler is now built twice: the TypeScript implementation the estate will run, and a hand-written Java implementation on Ecore, Xtext, OCL, QVT-Operational and Acceleo that exists for the length of the course. This branch records how the two coexist. It adds no implementation.

At the root, ADR 0105 and a new The parity contract section in docs/architecture.md say how the two are held equal: committed oracle files under spec/v1/examples/ (canonical JSON for the parsed intent and the Resolved Deployment, the rendered tree byte for byte, a (code, JSON Pointer) set per refused case, one metamodel descriptor), each implementation tested against them on its own, and CI never regenerating an oracle. The contract lives at the root because it outlives the Java side: at the sunset the oracles become the TypeScript compiler's golden files.

Everything else about the Java side lives in a new emf/ tree: a README, emf/docs/architecture.md, and a register of its own with ADRs 0106 to 0114 (the premise that the model fits the toolchain unchanged, scope and sunset, Maven with Tycho, Ecore with build-time genmodel, Complete OCL named by code, Xtext parsing the authored YAML into the imported metamodel, QVTo, Acceleo 4, Java witnesses for model behaviours). Every one is claim: open with an owner, because nothing has been built.

The decisions later tickets inherit

Two hand-written implementations, never generated from each other. The course grades the modelling artefacts as authored work, and a generated side cannot fail independently of its source. Agreement is proven at the three layer boundaries instead, where a run's state is a whole document.

The root stays TypeScript. Every pom, module, check, ledger and decision of the Java side sits under emf/. The root names it only in CI, in the ADR lint's domain list and its test, and in the parity contract, and emf/docs/architecture.md lists every such line so the sunset pull request is mechanical.

The sunset is two conditions, not a date: the course grade is recorded, and the TypeScript suite is green on every parity case with the emf job removed. The grade alone could delete the only complete implementation.

Amended in place, not superseded: 0065, 0066, 0100 and 0102 are scoped to the TypeScript tree. Superseding them would mean writing new ADRs to restore them at the sunset; the scoping sentence is simply removed instead.

One number sequence across both registers. The EMF ADRs take 0106 onward, and a new test fails when a number is used in both.

Gates

The existing ADR lint gains an emf domain and runs a second time with emf as its root, as an ADR contract (emf) step in the Contracts job. REQ-001 now covers both registers. No new npm script, so the pipeline-wiring test is unaffected.

Verification

Each claim broken and restored:

  • A normative anchor that does not exist in emf/docs/architecture.md: emf/0114-model-behaviours-have-a-java-witness.md: normative anchor '#witness' not found in docs/architecture.md
  • An EMF decision resting on a decision: emf/0112-qvto-derives-the-resolved-deployment.md: rests-on 0107 is not a premise
  • An EMF ADR renumbered to a number the root register uses: expected [ '0104' ] to deeply equal []

npm run lint:adrs reports 92 files clean, node scripts/lint-adrs.ts emf reports 9 files clean, npm run lint:links reports 158 files clean. npm run verify exit 0, 305 tests. Coverage unchanged: statements 98.31, branches 92.43, functions 100, lines 98.19.

The 21 open tickets this affects were rewritten on GitHub with a Parity section each; #78 is the spec the Java sub-issues will be cut from.

@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 bd9d865 into main Sep 14, 2026
16 checks passed
@ExtraToast
ExtraToast deleted the docs/emf-double-implementation branch September 14, 2026 11:10
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