docs: record the EMF implementation and the parity contract binding it - #79
Merged
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
0105and a newThe parity contractsection indocs/architecture.mdsay how the two are held equal: committed oracle files underspec/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 ADRs0106to0114(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 isclaim: openwith 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, andemf/docs/architecture.mdlists 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
emfjob removed. The grade alone could delete the only complete implementation.Amended in place, not superseded:
0065,0066,0100and0102are 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
0106onward, and a new test fails when a number is used in both.Gates
The existing ADR lint gains an
emfdomain and runs a second time withemfas its root, as anADR contract (emf)step in theContractsjob.REQ-001now covers both registers. No new npm script, so the pipeline-wiring test is unaffected.Verification
Each claim broken and restored:
emf/docs/architecture.md:emf/0114-model-behaviours-have-a-java-witness.md: normative anchor '#witness' not found in docs/architecture.mdemf/0112-qvto-derives-the-resolved-deployment.md: rests-on 0107 is not a premiseexpected [ '0104' ] to deeply equal []npm run lint:adrsreports92 files clean,node scripts/lint-adrs.ts emfreports9 files clean,npm run lint:linksreports158 files clean.npm run verifyexit 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.