# ADR supersession, done with XLink A small worked example: ten architecture decisions for a billing platform, a technical specification derived from them for any date you choose, and a map of which decision replaced which. Open `index.html` in a browser. Nothing to install, no server needed. The stylesheets run in the page using [SaxonJS](https://www.saxonica.com/saxonjs/) 2.7 (`vendor/saxon-js/`), not the browser's built-in `XSLTProcessor`, which Chrome is removing. They are compiled ahead of time to SEF, SaxonJS's executable format. ## The claim it demonstrates **An accepted decision is never edited.** Not to flip a status field, not to add a "superseded by" line. Every ADR in `adr/` is exactly as it was written on the day it was taken. Everything *about* the relationships between decisions lives out of line, in `linkbase/decision-log.xml`, as XLink arcs. Each arc carries the date it took effect. That is the whole trick: because the standing of a decision is derived rather than stored, the two can never disagree, and "what was in force on 31 March" becomes a question with an answer instead of an archaeology project. Move the date slider. The specification changes. No source file does. ## What is in the bundle ``` adr/ADR-001…010.xml the decisions — immutable, never edited linkbase/decision-log.xml the arcs — supersession, amendment, withdrawal, driver req/requirements.xml the requirement versions that drove each change xsl/effective-spec.xsl the fold: corpus + as-of date → effective spec xsl/supersession-map.xsl the same fold, drawn as an SVG timeline index.html self-contained viewer (generated; see below) vendor/saxon-js/ SaxonJS 2.7 runtime and its licence (Saxonica) build/ corpus assembly, page generation, checks ``` Both stylesheets read the same corpus and take the same `as-of` parameter. The map is not an illustration of the specification; it is a second fold over the same sources, which is why the two can never drift apart. ## What the corpus exercises | Mechanism | Where to see it | |---|---| | Two-hop supersession chain | ADR-002 → ADR-004 → ADR-005. At 2026-03-18 and later, ADR-002's tombstone names ADR-005, not ADR-004: the resolver walks to the head. | | One arc ending several decisions | ADR-010 retires ADR-008 and ADR-009 together. Their two locators share one `xlink:label`, so a single arc reaches both — one requirement change, recorded once. The map draws it as one stem with two arrowheads. | | Clause-level amendment | ADR-007 replaces only the `retention` clause of ADR-001. ADR-001 stays in force; the other two clauses are untouched. Before 2026-09-09 the retention is seven years, after it is five. | | Withdrawal with no replacement | ADR-006 withdraws ADR-003. Nothing replaces it — a distinct outcome from supersession, and one a "superseded by" field cannot express. | | Tombstones | Retired decisions are shown, struck through, with the reason and date. A reader who does not know a decision has been retired will keep honouring it. | | Drivers | Every change carries a `prov:wasInfluencedBy` arc to the requirement version that caused it. The decisions were not wrong; their premises moved. | | Not-yet-decided | Set the date before 2025-01-14 and the specification is empty. Decisions do not exist before they are taken. | ## Vocabulary Borrowed where ratified vocabulary exists, local where it does not — the line is drawn explicitly so a reader can see which is which: - `http://purl.org/dc/terms/replaces` — supersession (Dublin Core Terms) - `http://www.w3.org/ns/prov#wasInfluencedBy` — driver (W3C PROV) - `urn:xenon:arcrole:amends` — clause amendment (local) - `urn:xenon:arcrole:withdraws` — withdrawal (local) Each ADR also carries one `xlink:arcrole="…/properties/linkbase"` simple link pointing at the decision log. That is XLink's own mechanism for telling a reader where to find the arcs, and it is the only thing in an ADR that refers outward. It is written once at birth and never touched again, because it names the log — a project constant — not any particular supersession. ## Running the fold outside the browser ```bash python3 build/compile-xsl.py # compile the stylesheets to SEF (needs Node.js) python3 build/build-corpus.py # assemble build/corpus.xml python3 build/build-corpus.py 2025-06-01 # and run the fold for that date python3 build/make-page.py # regenerate index.html python3 build/preview-map.py 2025-12-01 # rasterise the map, light and dark python3 build/check-page.py # load index.html in a browser and assert # (with XSLTProcessor deleted, as Chrome will) ``` Or with any XSLT processor: ```bash xsltproc --stringparam as-of 2025-06-01 xsl/effective-spec.xsl build/corpus.xml ``` The corpus is simply every document the locators resolve to, gathered into one tree. A production pipeline would do that with an XML catalog and XInclude; the build script does the same thing in fifteen lines so this runs anywhere. ## What is deliberately not here The invariants. A real decision log is gated by rules — every supersession carries a driver, chains are acyclic, each chain terminates in exactly one head, no in-force decision cites a retired one as its basis. Those are Schematron, they run in CI, and they are what turns this from a rendering trick into something a team can rely on. They are the obvious next piece.