Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group)

[metadatadriven]

Smartphrase — demonstrate SAP ↔ AC/DC model linkage

Rework note (2026-07-12). This issue body was rewritten to reground the requirements. The original body specified solution choices — an XHTML carrier with bespoke sap:/smartphrase: namespaces, grounding in the TransCelerate SAP template, and a fixed deliverable/file layout — before the requirements were stated, and the first round of work on branch smartphrase_01 followed those choices in the wrong direction. The comment trail below is the record of that first PoC. This body now states requirements only; solution design is a separate, subsequent work product.

Purpose

Produce a tangible demonstration for the AC/DC working group that makes the value of the AC/DC model obvious. The concept being demonstrated is the smartphrase: a link between spans of SAP prose and AC/DC model metadata such that the prose and the model are two views of one thing.

The working group is the primary audience; this is a concept vehicle for them to react to and steer, not production tooling.

Core requirements — the four claims

The demonstration succeeds if it makes these four claims believable:

1. One source of truth. SAP prose and model metadata are co-equal, bidirectional authoring surfaces: edit the model and the prose follows; author the prose and the model instance follows. Both directions are first-class.
2. Traceability to data. Any smartphrase in the SAP can be followed down its full resolution chain to the physical dataset/variable it depends on.
3. Template-level reuse. One standard library building block (transformation template + its phrases) is shown instantiating with different parameters — write once, apply many.
4. Standards alignment. Identifiers ground in existing standards (USDM, ARS, STATO, CDISC/NCIt terminology, the AC/DC model's own artefacts) rather than a private identifier space.

Authoritative grounding

• The model source of truth is the methods_02 branch data artefacts: Transformation Library v0.7 (anchor/placeholder structure), the per-method files (lib/methods/, Method schema v0.9.1), the concept models (lib/concepts/) and vocabularies (lib/vocabulary/).
• Only the data is binding. The eSAP v0.5.0 schema and the acdc:macro authoring-tag dialect on that branch are design inputs to weigh, not constraints.

Scope

• One analysis passage, done deeply — enough prose to carry all four claims. Not a document-scale SAP encoding.
• Reuse is demonstrated at the template level (same building block, different parameterisations); no second full study is required.

Constraints

• Zero-install demos. Static files that run from file:// in any browser — working-group members double-click and it works. No server, no build step.
• Carrier-neutral requirements. No carrier format is mandated here; the carrier is a design decision, to be made with its rationale recorded.
• SAP structure is volatile. A sister project is starting up to define a standard SAP structure (analogous to the ICH M11 initiative for protocols). Any eSAP/SAP document structure used in this workstream must be assumed to change; the smartphrase linking mechanism must not be coupled to a particular SAP document structure.

Assumptions from the original issue that no longer hold

• XHTML + sap:/smartphrase: XML namespaces as the carrier — premature solution language, retired (see smartphrase/spec/format-evaluation.md on the branch for the analysis).
• Grounding in the TransCelerate Common SAP Template — wrong anchor, and superseded by the SAP-structure sister project noted above.
• Transformation Library v0.6 (22 phrases / 8 roles) — superseded by v0.7 (anchors/placeholders) on methods_02.
• Two full worked study SAPs (CDISC Pilot + Breast Cancer) — replaced by the one-passage-deeply + template-level-reuse scope.
• Hover / resolve / trace as the mandated demo set — the four claims are the requirement; the interaction shape is a design decision.

Deliverables

1. A design record — the chosen approach (including the carrier decision and its rationale, and how the eSAP-structure volatility is isolated), kept alongside the implementation.
2. Self-contained interactive demo(s) that make the four claims believable, runnable from file:// with zero install.
3. A short walkthrough the working-group session can follow.

Out of scope

• Exhaustive coverage of every SAP sentence or section
• Integration with a live Neo4j backend
• Formal schema / validation pipeline / production authoring tooling
• The standard SAP document structure itself (owned by the sister project)
• Public release beyond the CDISC AC/DC working group

[metadatadriven]

An example of how smartphrases are defined within the AC/DC model can be found here:

https://github.com/cdisc-org/analysis-concepts/blob/bb4ff5c8bac71f429a0d60a0c68358512a945d42/lib/transformations/ACDC_Transformation_Library_v06.json

Note: this is one example from the transformations part of the model. All other parts of the AC/DC model — Methods, Concepts, Derivations, Slices, DataConcepts, etc. — would have equivalent smartphrase definitions following the same pattern.

[metadatadriven]

Progress update — branch smartphrase_01

Completed

Deliverable 1 — Source documents

• ✅ TransCelerate Common SAP Template (SAP_CoreTEE_v005.docx) added to smartphrase/source-docs/common-sap-template/
• ⬜ CDISC Pilot Study SAP — to be added
• ⬜ Breast Cancer study SAP — to be added

Deliverable 2 — XHTML SAP document structure (sap: namespace)

• ✅ Full tag vocabulary defined in smartphrase/spec/sap-tags.md
• All 9 analytical sections of the TransCelerate template mapped to sap: tags (Sections 10–13 are administrative and left as plain XHTML)
• Structural controls defined: sap:optional (pick-all-that-apply), sap:choice (pick-one), sap:repeat (repeating sections)
• Reusable sap:endpoint-analysis pattern covers primary, secondary, and other-objective analyses

Deliverable 3 — Smartphrase layer specification (smartphrase: namespace)

• ✅ Full specification defined in smartphrase/spec/smartphrase-spec.md
• Grounded in the 22 phrase templates / 8 roles from ACDC_Transformation_Library_v06.json
• Three-level tag hierarchy: smartphrase:analysis (section), smartphrase:sentence (block), smartphrase:phrase + smartphrase:binding (inline), plus smartphrase:ref for direct model references
• Bidirectional semantics documented: model→SAP resolution and SAP→model instantiation
• Full worked ANCOVA example included

Still to do

• ⬜ Add CDISC Pilot Study SAP and Breast Cancer SAP source documents
• ⬜ Encode both SAPs as sap: XHTML with smartphrase: tags (smartphrase/examples/)
• ⬜ Build interactive demos (smartphrase/demo/)

Note: branch smartphrase_01 cannot currently be pushed to cdisc-org — awaiting write access for metadatadriven.

[metadatadriven]

Progress update — branch smartphrase_01 (resolve demo + spec review)

New since last update

Architecture decisions (recorded in spec/format-evaluation.md)
A carrier-format review weighed XHTML + bespoke namespaces against HTML5+JSON-LD/RDFa, Web Annotation, DITA, etc. Decisions taken for this PoC:

• Carrier stays XHTML + sap:/smartphrase: namespaces — treat Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9 as an illustrative PoC, not a re-platform.
• Source-of-truth is co-equal bidirectional — the demo must show model→SAP and SAP→model as first-class, not resolution with an instantiation footnote.
• Identifiers resolve into existing CDISC standards — smartphrase bindings/refs ground in USDM (objectives, populations, estimands), ARS (analyses, methods), STATO and AC/DC LinkML IRIs, rather than a private id space.

Deliverable 5 — Interactive demos

• ✅ Resolve demo (demo/resolve-demo.html) — self-contained single-page app, no server, runs from file://. Built for the CDISC Pilot primary efficacy analysis (AC.PRIMARY.ADASCOG → template T.CFB_ANCOVA, method M.ANCOVA).
  • model → SAP: edit the AC/DC instance (bound concept, render mode short/long/long_with_short, optional grouping / confidence-level / covariate phrases) and the SAP prose resolves live.
  • SAP → model: a Constructed AC instance view rebuilds the model metadata from the same bindings — the two directions share one state, so the bidirectionality is demonstrated rather than asserted.
  • Also exposes a Tagged source view (the live sap:/smartphrase: XML) and grounding IRIs per concept.
• ✅ Canonical model fragment (demo/data/cdisc-pilot-acdc.json) backing the demos; smartphrase + role definitions reproduced from ACDC_Transformation_Library_v06.json.
• ⬜ Hover demo — still a stub.
• ⬜ Trace demo — still a stub (DataConcept → ADaM Class Variable → study variable → physical dataset).

Spec review (spec/review-comments.md)
A pre-expert review of sap-tags.md and smartphrase-spec.md (blockers + ~30 issues across schema/governance/correctness). For this PoC the heavy items (RELAX NG schema, namespace governance, MIME/DOCTYPE rigour, versioning policy) are deferred; the cheap correctness items are being actioned as the demos need them — already applied: the missing grouping role in the worked example (§3.12) and concept-id-over-value binding precedence (§3.4).

Resolved sentence produced by the demo

Change from baseline in Alzheimer's Disease Assessment Scale - Cognitive Subscale (11 items) (ADAS-Cog(11)) at Week 24 in the efficacy (intent-to-treat) population comparing treatment groups using ANCOVA with 95% confidence intervals adjusting for baseline ADAS-Cog(11) will be assessed as the primary analysis.

Still to do

• ⬜ Build trace and hover demos (both reuse the shared data fragment; trace needs a data-layer chain added to it)
• ⬜ Encode the CDISC Pilot SAP as a full sap: + smartphrase: example (examples/)
• ⬜ Breast Cancer SAP deferred until a source document is supplied

[metadatadriven]

Progress update — branch smartphrase_01 (all three demos complete)

Following on from the previous update, Deliverable 5 (interactive demos) is now complete — all three interaction modes are built, self-contained, and run in a browser from file:// with no server. Entry point: smartphrase/demo/index.html.

Demos

Mode	File	What it does
Hover	demo/hover-demo.html	Finished SAP passage; hover/keyboard-focus any smartphrase to reveal the AC/DC metadata behind it — sp-oid, role, phrase template, each smartphrase:binding with its short/long labels and grounding IRI. Section-level smartphrase:analysis chip shows template, method + formula, USDM objective, ARS analysis. Read-only inspection.
Resolve	demo/resolve-demo.html	Bidirectional authoring surface. model→SAP: edit the AC/DC instance (bound concept, render mode, optional phrases) and the prose resolves live. SAP→model: a Constructed AC instance view rebuilds the model metadata from the same bindings. Also exposes the live tagged sap:/smartphrase: source.
Trace	demo/trace-demo.html	Click a phrase to follow its full resolution chain to the data: DataConcept → ADaM Class Variable → study variable (with where-clause) → physical .xpt dataset (e.g. ADAS-Cog change → CHG → ADQSADAS.CHG where PARAMCD='ACTOT' AND AVISITN=24 → adqsadas.xpt).

All three are driven by one worked example: the CDISC Pilot primary efficacy analysis (AC.PRIMARY.ADASCOG → template T.CFB_ANCOVA, method M.ANCOVA).

Shared data architecture

To avoid three divergent copies of the model, all demos load a single source via <script src> (a fetch() of local JSON is blocked by the file:// CORS policy; a <script> is not):

• demo/data/acdc-data.js — the AC/DC model fragment + the trace data layer; smartphrase and role definitions reproduced from ACDC_Transformation_Library v0.6.0.
• demo/data/acdc-render.js — shared smartphrase resolution helpers.
• demo/data/cdisc-pilot-acdc.json — pure-data export, auto-derived from acdc-data.js (kept byte-identical) for tooling that prefers JSON.

Identifiers ground in USDM / ARS / STATO / AC-DC LinkML IRIs; anything not yet authoritative is flagged illustrative.

Verification

All three demo scripts run clean under a headless DOM check; the shared renderer produces the expected sentence with 0 resolution errors; the trace chain renders the full 4-tier path down to adqsadas.xpt.

Status against issue deliverables

• ✅ 1. Source documents — TransCelerate template added; CDISC Pilot covered via the model fragment; Breast Cancer deferred (no source supplied).
• ✅ 2. sap: XHTML structure — spec/sap-tags.md.
• ✅ 3. Smartphrase layer spec — spec/smartphrase-spec.md.
• 🟡 4. Worked examples — CDISC Pilot analysis exercised across all three demos; full SAP-document encoding in examples/cdisc-pilot-sap.xhtml still to do. Breast Cancer deferred.
• ✅ 5. Interactive demos — hover / resolve / trace all complete.

Still to do

• ⬜ Encode the full CDISC Pilot SAP as a sap: + smartphrase: document in examples/cdisc-pilot-sap.xhtml
• ⬜ Breast Cancer SAP — deferred until a source document is supplied

[metadatadriven]

Sprint Demo Script — Smartphrase PoC (issue #9)

Duration: 10 minutes · Format: screen-share walkthrough of the three demos + the architectural fork
Headline: the SAP and the AC/DC model are now two views of one thing — and the link runs both ways.
Subtext: the PoC works; the open question is the carrier, and we have a concrete answer to show.

---

Before you start (2-min prep)

• Open these browser tabs, in order:
  demo/index.html · demo/hover-demo.html · demo/resolve-demo.html · demo/trace-demo.html
  · examples/cdisc-pilot-sap.b1-sketch.html · examples/cdisc-pilot-sap.b1-i18n.html
• Browser zoom ~125–150% so text is legible on the share.
• On resolve-demo, make sure the Resolved prose tab is showing.
• On b1-sketch, have View Source ready (or scroll to the <script type="application/ld+json"> block) so you can show the graph.
• Issue Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9 open in a spare tab for the close.
• One-line reminder of the worked example: change from baseline in ADAS-Cog(11) at Week 24, ANCOVA, efficacy population (CDISC Pilot).

If a demo misbehaves: they're static files — just reload the tab. Nothing is server-backed.

---

Timeline at a glance

Time	Segment	Tab
0:00–1:00	The problem + what we built	index.html
1:00–2:30	Hover — inspect the link	hover-demo.html
2:30–5:00	Resolve — the bidirectional headline	resolve-demo.html
5:00–6:30	Trace — provenance to the data	trace-demo.html
6:30–9:00	Architecture — the honest issues + the HTML5+JSON-LD direction	b1-sketch / b1-i18n
9:00–10:00	The decisions we need + the ask	issue #9

---

0:00 — The problem (60s) · index.html

"A Statistical Analysis Plan is prose written for humans. The AC/DC model is metadata written for machines. Today those live in separate worlds — someone writes the SAP, and separately someone encodes the analyses as model metadata, and the two drift.

The smartphrase layer closes that gap: it links spans of SAP text to the AC/DC model so the prose and the metadata are the same source of truth. This PoC shows that working three ways — inspect, author both directions, and trace to the data."

Action: point at the three cards — Hover / Resolve / Trace.

---

1:00 — Hover: inspect the link (1m30) · hover-demo.html

"A finished SAP sentence — section 4.1.2. Looks like ordinary prose, but every highlight is a smartphrase bound to the model."

Action: hover "change from baseline in ADAS-Cog(11)".

"Hovering reveals what's underneath: phrase SP_CFB_ENDPOINT, role endpoint, bound to the ADAS-Cog(11) concept — with a real grounding IRI, not a private label."

Action: hover "using ANCOVA", then the dashed smartphrase:analysis chip.

"The method carries its formula and a STATO IRI; the section as a whole ties to its template, its USDM objective, and its ARS analysis. You can interrogate the model behind any sentence without leaving the document."

---

2:30 — Resolve: the bidirectional headline (2m30) · resolve-demo.html

"This is the heart of it. Left: the AC/DC model instance. Right: the SAP prose. Change either side and the other follows."

Action: read the resolved sentence once, then —

Model → SAP (75s)

Action: change parameter from ADAS-Cog(11) → CIBIC+.

"Change the bound concept on the model side, and the prose rewrites itself."

Action: change endpoint render mode long_with_short → short; toggle the confidence-level phrase off/on.

"Render modes control how a concept appears; optional phrases flip in and out. The document is a view of the model."

SAP → Model (75s)

Action: switch to the Constructed AC instance tab; change a binding (e.g. population → safety).

"The other direction: this panel is rebuilt from the same bindings — the model metadata you'd instantiate by authoring this passage. Editing the prose is editing the model. That's the co-equal bidirectionality."

Action: glance at the Tagged source tab.

"And this is the live sap:/smartphrase: XML carrying it."

---

5:00 — Trace: provenance to the data (1m30) · trace-demo.html

"Last mode answers the reviewer's question: where does this number actually come from?"

Action: endpoint chain is pre-loaded — walk the four tiers.

"Four tiers: DataConcept Change from Baseline → ADaM Class Variable CHG → Study variable CHG in ADQSADAS where PARAMCD=ACTOT and AVISITN=24 → physical dataset adqsadas.xpt."

Action: click the population phrase, then the grouping phrase.

"Population traces to ITTFL='Y' in ADSL; treatment to TRTP. From one sentence we follow any concept to the column it lives in."

---

6:30 — Architecture: the honest fork (2m30) · b1-sketch.html → b1-i18n.html

"Now the part I want the group's steer on. The demos work — but they're built on a specific carrier: XHTML with two custom namespaces, sap: and smartphrase:. We chose that to get pixels fast. Reviewing it honestly, it's the weakest of the credible options for anything beyond a demo."

The issues (45s — say, don't show):

• It only parses correctly as application/xhtml+xml. Served as plain text/html, the colon in sap:foo isn't a namespace and parsing breaks. That's fragile for something regulators open in a browser.
• It's a bespoke urn:cdisc: vocabulary we'd have to govern ourselves — and the identifiers are private IDs (S_AC_001) that duplicate concepts USDM and ARS already define.
• The semantics live inline in the prose — no overlapping annotations, and statisticians won't hand-author angle brackets.

"AC/DC is already a graph — LinkML, STATO, Neo4j. So the better question is: what carrier lets the SAP be a projection of that graph, not a private re-encoding of it?"

The answer — sneak-peek (60s):
Action: open b1-sketch.html.

"Same sentence, re-expressed as the recommended target: plain HTML5 prose + a JSON-LD graph fragment. The prose is clean HTML — it renders with no tooling, no namespaces. Lightweight data-sp-ref hooks anchor each span to a node in the graph."

Action: show the <script type="application/ld+json"> block (view source / scroll).

"And the semantic layer is a real RDF graph any standard processor reads — with identifiers as IRIs into USDM, ARS, STATO and the AC/DC LinkML model, not a private namespace. LinkML already emits this JSON-LD context for free."

<!-- carrier: plain HTML5, renders anywhere -->
<span data-sp-ref="#b-endpoint">Change from baseline in ADAS-Cog(11)</span>
<span data-sp-ref="#b-method">using ANCOVA</span> …

<!-- semantic layer: a real graph, not prose a tool must re-parse -->
<script type="application/ld+json">
{ "@id": "acdc:instance/AC-PRIMARY-ADASCOG", "@type": "acdc:AnalysisConcept",
  "acdc:usesMethod": { "@id": "ars:method/MTH-ANCOVA-CFB",
                       "acdc:alignedTo": { "@id": "stato:STATO_0000176" } },
  "sp:hasBinding": [
    { "@id": "#b-endpoint", "sp:role": "endpoint",
      "sp:parameter": { "@id": "ncit:C168804", "label": "ADAS-Cog(11)" } } ] }
</script>

The payoff — i18n (45s):
Action: open b1-i18n.html, click Français, then Deutsch.

"And because the prose is generated from the graph, this falls out almost for free: same model, three languages. Concept labels are language-tagged literals — much of that terminology is inherited from CDISC/NCIt codelists rather than translated per document. Switching language re-generates the sentence; nobody re-authors the SAP. Multilingual SAPs are a real sponsor need, and the model-driven direction is what makes them tractable."

---

9:00 — The decisions we need + the ask (60s) · issue #9

"So the PoC proves the concept. The open decisions are about the foundation:

1. Is issue Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9 a throwaway illustration, or the seed of the real architecture? That decides whether we re-platform off XHTML.
2. Do we accept HTML5 + JSON-LD, grounded in the LinkML model, as the target carrier?
3. Should smartphrase identifiers resolve into USDM/ARS wherever those standards already cover the entity?
4. Source of truth — is the SAP generated from the model, authored then extracted, or co-equal?

Full analysis is in spec/format-evaluation.md, and the B1 sketches you just saw are committed in examples/. What I need from the group is a steer on 1–3 so the next sprint builds on the right foundation."

---

Pocket cheat-sheet (glance during the demo)

• Study: CDISC Pilot (CDISCPILOT01) · Alzheimer's / Xanomeline
• Analysis: primary efficacy — CFB in ADAS-Cog(11) @ Week 24, ANCOVA, efficacy (ITT) pop
• Template / method: T.CFB_ANCOVA / M.ANCOVA · formula CHG ~ TRTP + BASE + SITEGR1
• Trace bottom: adqsadas.xpt, PARAMCD='ACTOT', AVISITN=24
• 3 demos in one breath: inspect · author both ways · trace to data
• Carrier issues: breaks as text/html · bespoke urn:cdisc: namespace · private IDs vs USDM/ARS · inline-only
• B1 target: HTML5 prose + JSON-LD graph · IRIs into USDM/ARS/STATO/LinkML · i18n via language-tagged literals
• Pitch: "The SAP and the model become two views of one thing — and we have a concrete, standards-aligned way to carry that."

Time pressure? The architecture block (6:30) is the most compressible: drop the i18n sub-demo and just mention it, recovering ~45s. The bidirectional resolve demo is the one segment not to cut.

[metadatadriven]

Rework complete — regrounded requirements, new design, integrated demo (branch smartphrase_01, commit ff8c378)

What changed and why

The original issue body specified solution choices before requirements (XHTML + bespoke namespaces, TransCelerate grounding, a fixed deliverable layout), and two of its assumptions no longer held: the Transformation Library moved to v0.7 on methods_02 (anchors/placeholders), and a sister project is starting up to define a standard SAP structure (an M11-analogue), which means any SAP/eSAP document structure used here must be assumed to change. The issue body has been rewritten to state requirements only — the four claims the demo must make believable: one source of truth, traceability to data, template-level reuse, standards alignment.

The design (recorded in smartphrase/DESIGN.md)

• One state, many projections. A single analysis-instance object is the shared state; the SAP prose, the constructed model instance, the authoring tag source and the JSON-LD graph are all pure-function projections of it. Bidirectionality is structural, not synchronised — there is no second copy to drift.
• Standoff semantics, plain-HTML carrier. The semantic layer is a graph fragment anchored to prose spans; nothing depends on document structure, which isolates the SAP-structure volatility by design.
• Identifiers ground into USDM / ARS / STATO / NCIt; AC/DC ids only where nothing exists; unregistered ids are flagged illustrative in the UI.
• Library data is a generated verbatim subset of methods_02@ffee5df (Transformation Library v0.7, Method schema v0.9.1) with provenance recorded in the file and shown in the demo.
• The acdc:macro authoring dialect from the methods_02 experiment appears as the secondary, text-shaped authoring surface (emitted and parsed through a two-pass validator); phrase chips with constrained pickers are the primary surface.

The demo — smartphrase/demo/index.html (double-click; zero install)

One integrated page, four stops, all on the CDISC Pilot primary efficacy analysis (T.CFB_ANCOVA + M.ANCOVA):

1. The passage — hover any smartphrase to inspect the model behind it; click to trace it four tiers down (DC.CHG → CHG → ADQSADAS.CHG where PARAMCD='ACTOT' AND AVISITN=24 → adqsadas.xpt).
2. Two views, one thing — edit the model panel and the prose follows; edit the prose (chips, or the editable tag source through the validator) and the constructed model, JSON-LD and trace all follow.
3. Template reuse — three analyses (primary ADAS-Cog(11)/Wk24, secondary NPI-X, supporting Wk16) instantiating the same v0.7 template, differing bindings highlighted; each opens in the editor.
4. Standards grounding — the full identifier table with what each id resolves into and its status, plus provenance.

Verification

Engine verified under Node (exact known-good sentence, byte-equal tag round-trip, planted faults all caught); 21 headless-Chrome end-to-end checks pass with no console errors, covering both authoring directions, validator accept/reject, reuse cards and trace-follows-state.

For the working-group session

smartphrase/WALKTHROUGH.md is a ~10-minute script ending with the four steers we need: accept one-state/many-projections as the architecture; confirm structured authoring as the SAP→model story; adopt the resolve-into-existing-standards identifier policy; and agree ownership of registering the illustrative ids as the SAP-structure project spins up.

[metadatadriven]

Progress update — documentation set, i18n, and the CDISC Library end-state (branch smartphrase_01)

Three additions since the rework landed (commits f111854, 85207d0, 2c50a73):

1. Documentation set for adopters (f111854)

• smartphrase/GETTING-STARTED.md — two tracks: integrators embedding smartphrases in their own tooling (e.g. a SAP editor: load the three inputs, hold one instance object as document state, render/edit/exchange, plus an integration checklist), and standards managers building reusable phrase libraries (phrase design tests, template membership, a worked SP_SUBGROUP example end-to-end, and the core + therapeutic-area-overlay layering pattern).
• smartphrase/REFERENCE.md — normative reference for the layer as implemented: every library and study structure field-by-field, render modes, the resolution and instantiation algorithms, trace tokens, the acdc:macro dialect grammar and two-pass validation, the JSON-LD projection, engine API, identifier policy, and error catalogue. PoC-local choices are explicitly marked (PoC).

2. Internationalisation, demonstrated (85207d0)

Because the instance stores identifiers and prose is generated, i18n is a renderer concern — but not a free one: concatenating phrase fragments in fixed role order is itself an English assumption. Each language pack now owns a sentence template (word order), per-language phrase templates (English fallback), and label overlays (in production largely inherited from CDISC/NCIt terminology translations).

The demo has an EN / FR / DE switch. The German rendering is the proof — the verb bracket sits as frame text between the smartphrases:

Die Veränderung von … gegenüber dem Ausgangswert in Woche 24 in der Wirksamkeitspopulation (Intention-to-Treat) wird im Vergleich der Behandlungsgruppen mittels ANCOVA mit 95%-Konfidenzintervallen adjustiert für den Ausgangswert von ADAS-Cog(11) als primäre Analyse untersucht.

Switching language re-renders the same instance: the tag source, constructed model view and all identifiers are byte-identical across languages (verified), and the JSON-LD carries the rendered sentence as language-tagged literals per language (sp:resolvesTo) — the RDF-native mechanism. A new language is a rendering pack, not a re-authored document. FR/DE copy is illustrative, not validated translation. Recorded as decision D7 in DESIGN.md; EN output is byte-identical to the pre-i18n renderer, and 15 further headless-browser checks pass alongside the original 21.

3. Distribution — the CDISC Library end-state (2c50a73)

DESIGN.md now records how the design maps onto the intended distribution of the smartphrase library from the CDISC Library (or other shared CDISC repository) once AC/DC is released as a standard. Short version: the architecture already assumes it — the library layer is the distribution boundary, provenance generalises from methods_02@ffee5df to package@version, and the illustrative IRI flags exist precisely to retire on release. What release requires is packaging and governance, not architecture: a normative schema for the phrase entities, versioning/deprecation policy (the CT precedent), the reference-and-pin vs full-copy decision for regulatory self-containment of submitted SAPs (the eSAP full-copy philosophy is the consistent answer), and loader-not-embedder in production tooling. Adjacent CDISC Library content plugs in rather than competes: sliceKeys[].source: "biomedicalConcept" points at CDISC Library BCs, and language-pack labels inherit from CT translations.

Status

All verified (engine round-trips byte-equal; 36 headless-browser end-to-end checks pass, no console errors), committed and pushed. Entry point unchanged: double-click smartphrase/demo/index.html; session script in smartphrase/WALKTHROUGH.md (now with an optional i18n beat).