@konneal/engine 0.1.0

package/docs/metanorma-for-ai.md

@@ -0,0 +1,270 @@
+# Metanorma for AI — a feature proposal from the RAG trenches
+
+**From:** the OIML RAG service (ai.oimlsmart.org — 875 Metanorma documents,
+~42k indexed clause chunks, live citation-grounded Q&A).
+**Claim:** every item below maps to a concrete cost we paid or a capability
+we could not ship. This is not speculative — it is the wish list of a
+production RAG consumer of Metanorma output.
+
+## Evidence base (2025–26 primary literature)
+
+Each proposal below is now grounded in peer-reviewed/preprint research on
+RAG over standards and structured documents, not only in our production
+experience:
+
+- **[ETSI]** Al Masoud, Arazzi, Germani, Nocera. *Exploring Structural
+  Complexity in Normative RAG with Graph-based approaches: A case study on
+  the ETSI Standards.* arXiv:2604.09868 (2026). The only empirical RAG
+  study on industrial standards (ETSI EN 301 489-X; 800+ Q&A). Findings
+  used below: hierarchical section structure ↑precision/↑MRR;
+  structure-preserving chunking is the "overall best compromise";
+  tables are exempted from chunking (atomic); parthood (P) and citation
+  (C) edges are the core information model; neighbor-expansion re-ranking
+  *failed*; embedding *smoothing* is the lightweight recall lever. Their
+  §II explicitly points at machine-readable standards (IEC Smart
+  Standards) as the intended end state — this document is the Metanorma
+  version of that end state.
+- **[STC]** Guttal et al. *Structure-Aware Chunking for Tabular Data in
+  RAG.* arXiv:2605.00318 (2026). Row-level key-value units, structural
+  boundaries: hybrid MRR 0.36→0.59, BM25-only Recall@1 0.37→0.75,
+  chunk count −40–56%. Quantifies P1-tables.
+- **[RDR2]** Xu et al. *Equipping Retrieval-Augmented LLMs with Document
+  Structure Awareness.* arXiv:2510.04293 (2025). Document structure trees
+  as first-class retrieval input; flattened chunks are the named failure
+  mode. Grounds P0-manifest.
+- **[SF-RAG]** Yu et al. *SF-RAG: Structure-Fidelity RAG for Academic
+  QA.* arXiv:2602.13647 (2026). Native hierarchy as a low-entropy
+  retrieval prior; flattening "destroys the native hierarchical
+  structure". Grounds P0-manifest + P2 stable ids.
+- **[SPIRE]** *Structure-Preserving Interpretable Retrieval of Evidence.*
+  arXiv:2604.20849 (2026). Linearization "obscures section structure,
+  lists, and tables"; wants citation-ready subdocuments. Grounds P0/P1.
+- **[MAHA]** Rashmi & Upadhya. *Modality-Aware Hybrid retrieval
+  Architecture.* arXiv:2510.14592 (2025). Tables→HTML-structured,
+  equations→LaTeX + text description, modality-aware knowledge graph.
+  Grounds P1-tables/equations.
+- **[ANTHROPIC]** Anthropic. *Contextual Retrieval* (2024): contextual
+  preambles cut top-20 retrieval failures 35%→67% (with BM25+rerank).
+  Grounds the manifest's role: preamble generation needs typed units,
+  not scraped prose.
+- **[LATE]** Günther et al. *Late Chunking.* arXiv:2409.04701 (2024);
+  **[CMP]** Merola & Singh. *Reconstructing Context.*
+  arXiv:2504.19754 (2025): contextual retrieval preserves coherence
+  better; late chunking is cheaper. Both need long-context/typed units —
+  neither works on GUID-anchored scraped HTML.
+
+## The core problem
+
+RAG consumers today scrape the **compiled HTML** — the least machine-shaped
+artifact Metanorma emits. We parse heading text to recover clause numbers
+(because element ids are GUIDs in OCR-derived docs), regex out boilerplate,
+flatten tables into pipe-joined rows, skip equations entirely, and join
+document status from an external bibliography. Every one of those workarounds
+is a proposal in disguise. This is not just our experience: it is the exact
+failure mode the structure-first literature names — flattened chunks lose
+the hierarchy, tables, and cross-references that make a standard a standard
+([ETSI] §I; [RDR2]; [SF-RAG]; [SPIRE]).
+
+## P0 — the unit manifest (sidecar alongside every render)
+
+Emit `document.rag.json` — an array of *addressable semantic units* the
+renderer already understands while building the HTML:
+
+```json
+{
+  "id": "oiml:r60-1:2021#3.9",
+  "type": "term",              // clause | term | table | figure | equation | example | note | bibliography | annex
+  "number": "3.9",
+  "title": "load cell",
+  "text": "measuring transducer which …",
+  "status": "in-force",
+  "parent": "oiml:r60-1:2021#3",
+  "lang": "en",
+  "spans": { "source": "sections/03-terms.adoc:104-112" }
+}
+```
+
+What this replaces, item for item:
+
+| Today (our pipeline) | With the manifest |
+|---|---|
+| BeautifulSoup over `document.html` | read JSON |
+| clause numbers re-derived from heading text | `number` + canonical `id` |
+| GUID anchors dropped by regex | stable canonical ids |
+| boilerplate filtered by regex (© OIML, rue Turgot…) | boilerplate simply absent |
+| OCR-escaped HTML tags stripped from text | clean source text |
+| `type` unknown (tables/definitions found by shape) | `type` drives retrieval specialization (exact term lookup; table-value lookups) |
+| no audit trail | `spans` point back to source |
+
+The HTML remains for humans; the manifest is the machine truth. Embedding
+one inside the HTML (`<script type="application/json" id="rag-manifest">`)
+also works and keeps a single artifact.
+
+**Evidence:** [ETSI] builds exactly this model (InfoUnits with title+body
+in a parthood/citation graph) by *recovering* it from PDFs — ToC parsing,
+section-code prefix geometry, reference-resolution heuristics — and shows
+structure preservation improves precision and MRR. The manifest emits what
+they recover, for free, from the model the renderer already holds.
+[RDR2]'s structure trees and [SF-RAG]'s structure-fidelity index consume
+the same shape. [SPIRE] shows the payoff is citation-ready evidence
+subdocuments — which is what our answers cite.
+
+## P0 — self-contained identity and status block
+
+JSON front matter in every output:
+
+```json
+{
+  "docidentifier": { "series": "OIML R", "number": "60", "part": "1", "year": "2021" },
+  "edition": "2021",
+  "status": "in-force",             // in-force | superseded | withdrawn | joint
+  "successor": "oiml:r60-1:2021",   // from relaton relation hasSuccessor
+  "relaton_ref": "r60-1_2021",
+  "published": "2021-04", "withdrawn": null,
+  "part_of": "oiml:r60", "translation_of": "oiml:r60-1:2021(E)"
+}
+```
+
+Today we join status and successor from `relaton-data-oiml` at ingest
+(5,707 YAML records; ~37% of editions are superseded or withdrawn). The
+join works but is external state that can diverge — the render should
+carry the bibliographic truth it was built from. Identity parsing is our
+single largest source of dirty-corpus defects (identifiers without the
+series letter, edition fields holding part numbers, slug/identifier
+mismatches); a parsed, structured docid eliminates the whole class.
+
+## P1 — tables as data, not prose
+
+Normative values live in tables (MPE tables, accuracy-class limits). We
+flatten them to `caption + " | "-joined rows` and hope the embedding
+model copes. Instead, emit per table: caption, column headers **with
+quantity and unit** (Metanorma already knows `[q]`uantities in many
+flavors), rows as typed values, and the enclosing clause context. A JSON
+or CSV serialization per table turns "what is the MPE for class III at
+500 g?" from a fuzzy vector match into an exact lookup the serving layer
+can execute and cite (`OIML R 76:2006, Table 3, row 4`).
+
+**Evidence:** [ETSI] §II-A exempts tabular sections from chunking
+entirely — atomic units, never split. [STC] quantifies the payoff of
+row-level key-value structure: MRR +66% hybrid, Recall@1 +106% BM25-only,
+chunk count −40–56%. [MAHA] parses tables into HTML structure and
+equations into LaTeX as first-class modalities. Our own G1 prototype
+(extracting 10,388 tables from adoc `|===` sources) reproduces the shape
+by hand — e.g. R 76-1 §3.5's MPE table with rowspan-merged class columns
+and clean `ClassⅢ = 0≤m≤500` rows — precisely what the manifest should
+emit natively.
+
+## P1 — the glossary layer as first-class output
+
+Term entries (`term:: [preferred,definition]`) should also emit a
+structured per-document glossary: term, grammar info, definition,
+non-preferred terms, symbols, source citation. "What is a load cell?"
+then becomes an exact-match against the glossary before any vector
+search — the single highest-value retrieval specialization for standards
+Q&A, and it aligns with the Glossarist model OIML already uses.
+
+## P1 — equations that survive retrieval
+
+`stem:[...]` (AsciiMath) is invisible to retrieval today; normative
+formulas (MPE = 0.5·e …) are effectively unanswerable. Emit MathML plus a
+generated plain-language fallback ("maximum permissible error equals half
+the verification interval value") in the unit manifest. The fallback is
+what gets indexed; the MathML is what gets rendered.
+
+**Evidence:** [MAHA] treats equations as a distinct modality (LaTeX +
+textual description) and shows retrieval gains from modality-aware
+indexing; our METANORMA-AI-SERIALIZATION conformance rule already requires
+≥2 of {asciimath, latex, described} for exactly this reason.
+
+## P2 — stable unit ids across revisions
+
+Content-hash-derived ids (or editor-stable anchors) so an editorial
+change re-indexes only changed units. Today any text change re-embeds the
+whole document; across a 900-document corpus with weekly revisions this
+is the difference between incremental and full re-index cost.
+
+**Evidence:** [SF-RAG] shows hierarchy-stable indexing is what makes
+structure-fidelity cheap to maintain; [ETSI]'s InfoUnit ids are only as
+stable as their recovered section codes — model-native anchors (what
+Metanorma has) are strictly better. Stability is also prerequisite for
+[ANTHROPIC] contextual preambles to be cacheable across revisions (our
+enrichment cache is keyed by content-hashed unit ids).
+
+## P2 — interlinear translation alignment
+
+Same unit id, `lang` attribute — the renderer knows which French clause
+corresponds to which English clause. That unlocks parallel corpora,
+cross-language retrieval with source-language provenance, and
+English-first indexes that can still cite the user's language edition.
+(We currently ingest English-only because unaligned multilingual chunks
+degrade retrieval; alignment would let us reverse that decision.)
+
+## P2 — requirement metadata
+
+Requirements are the product of legal metrology documents. Tag units
+with obligation (`shall`/`should`/`may`) and subject where the markup
+knows them → "list every requirement for load cell marking" becomes a
+filter, not a prayer.
+
+## P2 — a render profile for ingestion
+
+`metanorma compile --profile rag`: boilerplate excluded (or typed as
+such), notes/examples toggleable, source spans on, manifest emitted.
+Consumers stop shipping regexes that guess at these boundaries.
+
+## Anti-goals (keep the contract clean)
+
+- No embeddings, no model output, no opinions inside Metanorma
+  artifacts — deterministic renders only. AI-layer choices stay with
+  consumers.
+- Metanorma should not own chunking **policy**. Emit semantic units;
+  consumers compose units into chunks for their model. What Metanorma
+  owns is **addressability** (stable ids, types, clean text, spans).
+  ([ETSI]'s own taxonomy supports this split: their "Structured +
+  Chunks" winner is a *consumer-side* composition over
+  producer-emitted structure — the producer's job is the structure.)
+
+## Sequencing
+
+1. Manifest + identity/status block (P0) — unblocks every RAG consumer,
+   mostly exporter work in existing render code paths.
+2. Tables + glossary (P1) — the two biggest answer-quality wins.
+3. Equations, stable ids, alignment, requirement flags, profiles (P2).
+
+## Beyond RAG — who else needs this
+
+The unit manifest is not a chatbot feature; it is **addressability for
+documents**, which unlocks a family of consumers:
+
+- **Agentic conformity assessment.** Certification bodies and, soon,
+  AI agents that draft type-evaluation reports: map measured test results
+  to requirement unit-ids, auto-generate test plans from a Recommendation's
+  requirements, and produce audit trails (result → requirement → source
+  span). OIML R-series test-report annexes are already structured tables —
+  a machine layer turns report preparation from copywork into assembly.
+- **Regulatory transposition and comparison.** National bodies transpose
+  OIML Recommendations into national law. Requirement-level units +
+  superseded→successor chains make "what changed between the 2000 and
+  2017 edition" and "which national clauses diverge" diffable questions
+  instead of expert reading marathons.
+- **Knowledge graphs / ontologies.** Terms × definitions × symbols ×
+  requirements × documents, emitted per render, compose directly into the
+  semantic layer legal metrology is already building — the glossary layer
+  is the same graph in miniature.
+- **LLM training and evaluation corpora.** Standards are high-quality,
+  normatively precise domain text. Unit manifests make them citable
+  training/eval material (grounded QA benchmarks for legal metrology,
+  like legal benchmarks did for law) — with per-unit provenance.
+- **Cross-publisher standards search.** Canonical unit ids (series,
+  number, part, year, clause) federate search across OIML/ISO/IEC
+  ecosystems instead of each publisher's PDF silo.
+- **Translation QA.** Interlinear alignment turns "is the term set
+  consistent across the E/F/A editions" into a diff.
+- **Accessibility and plain language.** The semantic layer (structured
+  definitions, requirement subjects) is the substrate for plain-language
+  summaries and assistive reading — the same data, different renderer.
+
+The common thread: today all of these consumers re-derive semantics from
+prose. The renderer already holds these semantics in memory while it
+builds the HTML. Emitting them is cheaper than every consumer
+re-guessing them.

package/docs/mirror-plan.md

@@ -0,0 +1,36 @@
+# metanorma-mirror integration — phase 1: inventory and design
+
+> The goal: answers that open the original document at the clause — a
+> citation becomes a door, not a label. This phase inventories what
+> exists and designs the integration; implementation is a follow-up.
+
+## 1. What exists today
+
+| Piece | State |
+|---|---|
+| Clean-corpus sources | `document.xml` (Metanorma XML) per document — the rendering input mirror-js consumes |
+| Dirty-corpus sources | Metanorma authoring trees (`metanorma/sections/*.adoc`) — renderable, lower fidelity |
+| mirror-js renderer | lives in the smart repo (`browser/src/metanorma-mirror-js.d.ts` + runtime) — client-side XML→DOM rendering |
+| R2 public bucket | `rag-public-assets` (unit assets only today) — no document renderings |
+| Citation cards | docidentifier + edition + clause + snippet; no in-document link |
+| Architecture note | CLAUDE.md already plans "rendered HTML in R2 for clause-anchored deep links (OIML docs only)" |
+
+## 2. The design (three layers, each valuable alone)
+
+1. **Rendered document per publication (build-time).** Render each clean-corpus `document.xml` to a single self-contained HTML (mirror-js headless, or `metanorma build` HTML) with stable clause anchors (`id="cls-4.2.1"`); upload to R2 under `docs/<doc_id>.html`; never the ISO/IEC internal corpus (copyright — public OIML only, same rule as every R2 public object).
+2. **Citation deep-links (one-line change once (1) exists).** The citation card's clause becomes `<a href="/docs/<doc_id>.html#<anchor>" target="_blank">` — the worker already emits doc_id + clause_anchor in every citation.
+3. **In-context pane (the payoff).** An embedded, scroll-to-clause view inside the answer: clicking a citation opens a slide-over rendering the document AT the anchor with the clause highlighted and its neighbors visible. Load strategy: fetch the R2 HTML and let the browser scroll (`#anchor` + a highlight script), no iframe sandboxing needed if the HTML is same-origin and static.
+
+## 3. Effort and risks
+
+- (1) is a build-script + storage pass over ~36 clean documents; dirty-corpus rendering (880 docs) is a later wave and depends on metanorma build succeeding per tree.
+- Clause-anchor stability: the anchors are the corpus's own (`cls-x.y.z`) — the same keys the retrieval index cites, so no mapping layer.
+- Payload size: single-file HTML per doc with inlined CSS (~100–500 KB); R2 + CDN caching makes this free at read.
+- The figure units interplay: the rendered document embeds its own figures — the pane and the typed-unit blocks will coexist (block = the answer's object; pane = the document's context).
+
+## 4. Follow-up board
+
+- Render + upload the clean corpus (script + R2 layout).
+- Citation deep-links in the site.
+- The slide-over pane (site component).
+- Dirty-corpus rendering pass.

package/docs/multi-sdo-architecture.md

@@ -0,0 +1,191 @@
+# Multi-SDO architecture — one engine, many publishers
+
+> Status: design (2026-09-12). The question this document answers: how does
+> this RAG / Metanorma / Primmel pipeline serve other standards developers,
+> with clean encapsulation, so that each SDO manages its own content and its
+> own deployment? The short answer: the engine becomes publisher-agnostic by
+> construction, every publisher-specific fact moves into a declarative
+> **publisher profile** owned by that SDO, and the engine consumes profiles
+> the same way it already consumes prompts and datasets — as data.
+
+## 1. The principle
+
+The system already learned this principle the hard way, several times:
+
+- Corpus behavior travels with the dataset declaration, not with pipeline
+  code (the `DATASETS` notes injected into prompts).
+- Prompts are data files, never inline strings.
+- The vector adapter is the single door where a **registry**, not an `if`
+  chain, decides which corpora may enter which index.
+- The model plane consumes each publisher's own package repository at a
+  pinned reference, with a freshness gate that detects content drift.
+
+The multi-SDO design extends the same principle to its conclusion: nothing
+in the engine may know which publisher it serves. Every fact that is
+currently true because "this is OIML" becomes a field in a profile.
+
+## 2. The honest audit — what is publisher-specific today
+
+| Surface | Current state | Where it must live |
+|---|---|---|
+| Dataset declarations | `DATASETS` in `config.ts` (ids, labels, permission codes, prompt notes) | profile: `datasets` |
+| Corpus registry | `PRODUCTION_CORPORA` / lane registries in `vector_adapter.py` | profile: `corpora` (registered names + target gates) |
+| System prompt voice | `prompts/system.md` mentions OIML publications and the corpus shape | profile: prompt template variables |
+| Identifier grammar | `OIML R/D/B/G/E` patterns in slugs, the PubID parser, mirror upload | profile: an identifier codec (per-SDO PubID module) |
+| Terminology source | 13 Glossarist datasets under the OIML vocab repo | profile: vocabulary sources |
+| Bibliography | `relaton-data-oiml` (5,707 records) | profile: relaton source (relaton is already one dataset per SDO across the ecosystem — direct leverage) |
+| Document models | `primmel-packages` (oiml-r60, oiml-cs, …) | per-SDO packages repo at a pinned ref (the pattern already exists) |
+| Rendered documents | mirror upload from the clean corpus; public-OIML-only rule | profile: rendering sources + the copyright policy flag per corpus |
+| Access policy | two physically separate indexes; `ai-preview` estate permission | profile: audiences and their index bindings; permission codes map to the SDO's identity provider |
+| Evaluation sets | golden 38 + annealment 18 (OIML content) | profile: per-SDO eval suites; the harness is shared |
+| Branding and nav | OIML branding, the site shell | profile: theme, logo, labels, domain |
+| Identity | RAG is an OIDC relying party of id.oimlsmart.org | profile: the OP per deployment; the role→permission mapping per estate |
+
+The engine-side list — the stages, the retrieval mechanics, the answer
+contract, the verdict engine, the gate harness, the quota and cache
+machinery — is publisher-agnostic today and must stay that way. Where a
+stage reads OIML-shaped assumptions (for example, edition steering's
+family semantics), the assumption is metadata-driven already and travels
+with the corpus.
+
+## 3. The publisher profile
+
+One declarative unit, owned by the SDO, versioned with their content:
+
+```
+publisher/
+  profile.yaml          # id, names, branding, domains, identifier codec id
+  datasets.yaml         # dataset declarations + permission codes + notes
+  corpora.yaml          # corpus registry entries + audience bindings
+  prompts/              # template variables + overrides (rare)
+  evals/                # golden + annealment suites over THEIR corpus
+  sources.yaml          # pinned refs: metanorma repos, relaton, glossarist,
+                        # primmel packages repo, renderings bucket
+  identity.yaml         # the estate OP, role → permission mapping
+  theme/                # logo, colors, nav labels
+```
+
+The engine consumes exactly this at build and deploy time. A deployment
+instance is then `engine@version + profile + content repos`, and the
+profile repository is the only thing an SDO edits in the normal course
+of business. Content repositories (Metanorma sources, relaton data,
+Glossarist datasets, Primmel packages) stay under the SDO's own control
+on their own infrastructure; the pipeline reads them at pinned
+references and never writes to them — the same contract this system
+already keeps with its upstreams.
+
+## 4. Deployment topology
+
+Each SDO runs its own deployment, in its own Cloudflare account, under
+its own domain:
+
+- **Structural isolation per publisher.** One SDO's corpus, indexes,
+  caches and keys physically cannot reach another's, because they are
+  separate accounts with no shared bindings. This is the same
+  two-index isolation discipline applied one level up.
+- **No cross-publisher federation by default.** If an SDO legitimately
+  holds another's content (as this deployment holds ISO/IEC material
+  internally), that relationship is declared in the SDO's own profile
+  with an explicit audience and copyright policy, and it inherits the
+  same structural separation between public and internal indexes.
+- **One engine release train.** The engine is versioned as a package
+  (workers + stages + site shell + ingest CLI + gate harness).
+  Publisher deployments pin a version and upgrade deliberately, the way
+  they would adopt any dependency. Breaking changes carry migration
+  notes for profiles.
+
+## 5. What already generalizes (the leverage list)
+
+The ecosystem was multi-SDO before this system was:
+
+- **Metanorma** renders documents for many SDO flavors; the rendering
+  input and clause-anchor structure are common.
+- **Relaton** bibliographies are one dataset per SDO; the registry
+  logic (families, editions, supersession-derived currency) is generic.
+- **Glossarist** terminology datasets carry the same shape for any SDO;
+  the vocabulary lane is dataset-agnostic.
+- **Primmel** packages are per-publisher repositories by design; the
+  model plane and verdict engine consume them through the projection,
+  not through OIML names.
+- **The site shell** is already a package (`@oimlsmart/site-shell`)
+  consumed by this site — the same boundary serves other themes.
+- **The evaluation harness** grades declarative expectations; only the
+  cases are content.
+
+## 6. Content governance per SDO
+
+- **Single source of truth.** Each SDO's authoritative content lives in
+  their own repositories. The pipeline derives chunks, indexes, models
+  and renderings from them, and the derivation is reproducible from
+  pinned refs.
+- **The freshness gate.** The model plane already fails its gate when a
+  package's source hash moves (CI re-indexes on content change). The
+  same mechanism watches every profile-declared source, so an SDO's
+  content update flows to their deployment through their own CI, with
+  their own gates.
+- **Their own evaluation bar.** The promotion gate (golden ×N +
+  annealment ×M against their deployment) runs on the SDO's cases. An
+  SDO cannot ship a regression against their own corpus silently, and
+  the engine cannot ship one against any profile in a reference matrix
+  (engine CI runs the reference profiles' suites against fixture
+  corpora).
+
+> Migration status: **step 1 shipped** (2026-09-12) — `profile/` exists,
+> datasets and corpora registries are consumed from it by both the
+> TypeScript and Python sides, with a drift test. See
+> TODO.impl/70-profile-extraction.md for the board.
+
+## 7. Migration path (incremental, no rewrite)
+
+1. **Profile extraction, no behavior change.** *(done)* Move the OIML-specific
+   tables (`DATASETS`, corpus registries, prompt voice variables) into
+   `profile/` in this repository, consumed at build time. The OIML
+   deployment becomes the first profile; every test stays green because
+   nothing observable changes.
+2. **Identifier codec.** Generalize the slug/PubID surface into a
+   per-profile codec module (this repo already depends on a PubID
+   library for OIML). The mirror upload and the citation deep-link path
+   consume the codec.
+3. **Prompt templates.** Interpolate publisher variables in
+   `prompts/system.md`; overrides live in the profile and are rare.
+4. **Eval suites per profile.** Move the golden and annealment cases
+   under `profile/evals/`; the harness reads them from the declared
+   path. This repo's suites become the OIML profile's suites.
+5. **Engine packaging.** Extract the workers, stages, site shell, CLI
+   and harness into the engine package; keep this repository as
+   `publisher-oiml` — a profile plus deployment configuration — which
+   becomes the reference implementation and the template other SDOs
+   copy.
+6. **Reference matrix.** Engine CI grows a second fixture profile (a
+   small public corpus from another flavor) to prove no OIML assumption
+   leaks into the engine.
+
+Each step ships independently and keeps the production gates green.
+
+## 8. Open questions (named, not hidden)
+
+- **Versioning discipline.** How quickly do SDOs want to track engine
+  releases — pinned with scheduled upgrades, or floating with gates?
+  The gate machinery supports both; the governance choice is theirs.
+- **Shared evaluation of the engine itself.** Content quality is
+  per-SDO, but retrieval mechanics regressions should be caught once,
+  centrally, on the reference matrix rather than re-measured by every
+  SDO.
+- **Localization policy.** The index is English-only today by explicit
+  decision; other SDOs may decide differently, and the language gate
+  (`ingest/langid.py`) is already profile-shaped (a declared language
+  set plus exclusions).
+- **Commercial and licensing terms.** Who may run the engine, under
+  what license, and what support looks like — an organizational
+  question that precedes any technical packaging.
+
+## 9. What this buys each SDO
+
+A publisher with Metanorma-authored documents gets, for the cost of a
+profile and their existing content: hybrid retrieval with clause-level
+citations, contextual enrichment, typed tables and formulas, terminology
+binding, edition-aware answers over their bibliography, conformance
+checking by execution over their Primmel models, citation deep links
+into their own renderings, and a promotion gate that measures the
+result on their own questions — on infrastructure they control, with no
+dependency on any other publisher's deployment.