@konneal/engine 0.1.0

package/docs/identity-onboarding-rag.md

@@ -0,0 +1,65 @@
+# The RAG service's identity onboarding — what to fix now
+
+The companion to docs/identity-service.md (the general guide): the
+RAG-specific fix-and-verify list. The OP side is done — the
+`oiml-rag` client is registered and ACTIVE (public PKCE client;
+`claims_policy: { "claims": ["roles"] }`); the authorize path answers
+302→sign-in for it (verified 2026-08-24).
+
+## Turn it on
+
+1. Set `OIDC_CLIENT_ID=oiml-rag` + `OIDC_ISSUER=https://id.oimlsmart.org`
+   and flip the feature flag. No OP-side act remains.
+
+## The sign-in flow (your half — verify each)
+
+2. The authorize URL carries `scope=openid profile email roles`,
+   `state` AND `nonce` (both unguessable, both one-time), PKCE S256.
+   (Your state handling is confirmed one-time; add the nonce check if
+   absent — the ID token's `nonce` must match what you issued.)
+3. The callback validates the ID token against the OP's JWKS — iss
+   exact, aud = oiml-rag, exp with ≤ 60 s leeway, the nonce — and the
+   JWKS is cached briefly with NO hard-pinned kid (the OP rotates with
+   overlap; a pinned kid breaks on rotation day).
+4. Map the OP's error taxonomy (`access_denied` and friends) to plain
+   language; fail closed, never a stack trace.
+5. Your session cookie: `Secure`, `HttpOnly`, `SameSite=Lax` — Strict
+   breaks the callback's top-level navigation back from the OP. State
+   the lifetime; renew sliding; logout clears it.
+6. Logout today is LOCAL-ONLY by necessity: the OP does not yet declare
+   `end_session_endpoint` (it lands with the identity-service cutover
+   wave — TODO.identity-sso wave A). When the discovery document gains
+   it, add the OP-side call so sign-out also ends the OP session (the
+   reference implementation in oimlsmart/smart
+   `browser/server/auth/oidc.ts` already implements RP-initiated
+   logout; copy it).
+7. The OP's sign-in page today renders in the platform's shell on the
+   identity host (works, and your users see it). After the
+   identity-service cutover it becomes the identity-native sign-in page
+   — you change NOTHING: the authorize URL is frozen by the OP's
+   contract gate.
+8. Your edge (Turnstile/WAF/rate limits): the `/auth/login` start and
+   `/auth/callback` must not be challenged, or the challenge must
+   survive the redirect chain — verify the round-trip under your edge
+   rules before announcing.
+9. `/auth/me` serves the session's cached claims — the ID token never
+   reaches the browser (your HMAC-cookie pattern already does this;
+   keep it).
+
+## The claims policy (the joint decision)
+
+10. The token may carry the estate role vocabulary: `applicant`,
+    `ia_officer`, `tl_operator`, `biml_officer`, `cs_admin`,
+    `mc_member`, `rc_member`, `executive_secretary`, `admin`, `viewer`,
+    plus `case_officer`, `certification_officer`, `signatory`,
+    `org_admin`.
+11. DECIDE NOW: which estate roles map to your member tier — every
+    signed-in user, or a bounded set? And which roles map to the
+    INTERNAL audience (the ISO corpus)? Once you declare the sets, the
+    OP bounds the policy's role allowlist to exactly them (one console
+    act — least privilege). Until then the policy is unbounded by
+    design; treat an absent/empty roles claim as the anonymous tier,
+    honestly.
+12. Key your users by `sub` (stable), never by email. Honor
+    `email_verified` before any email-keyed behavior. Erasure: a
+    deleted account's `sub` stops resolving — treat that as anonymous.

package/docs/identity-service.md

@@ -0,0 +1,219 @@
+# Integrating with the OIML SMART identity service
+
+**Audience:** an agent or engineer building a service that authenticates
+users via the OIML SMART identity service. This file is self-contained;
+nothing outside it is required reading. The canonical copy lives at
+`docs/integration/identity-service.md` in the `oimlsmart/smart`
+repository — copies into consumer repos are welcome; the canonical copy
+wins on any drift.
+
+> **Repo note (2026-08):** the identity service's code is moving from
+> the smart monorepo to its own repository (`oimlsmart/identity`) — the
+> extraction changes where the code lives, NEVER the public surface:
+> the issuer `https://id.oimlsmart.org`, every endpoint, and the claims
+> contract below are stable across the move. The source paths cited in
+> §6 and §11 are the pre-extraction locations in `oimlsmart/smart`;
+> after the cutover they read as the same relative paths inside
+> `oimlsmart/identity`.
+
+## 1. The cast
+
+- **The OP (OpenID Provider)** — the identity service at
+  `https://id.oimlsmart.org`. It authenticates users and issues OIDC ID
+  tokens (JWT, ES256). It is the ONLY account registry in the estate.
+- **Your service is an RP (Relying Party)** — it trusts the OP. It runs
+  NO login form and holds NO account list of its own.
+- **Upstream IdPs** (GitHub today; member-body providers such as
+  Microsoft Entra next) sit BEHIND the OP as linked login methods. Your
+  service never talks to them; the OP's account links them.
+
+The OP speaks OIDC Core 1.0 (authorization code + PKCE), RFC 8414
+discovery, and OIDC RP-Initiated Logout 1.0.
+
+## 2. The endpoint cheat sheet
+
+Issuer: `https://id.oimlsmart.org`
+
+| What | Where |
+|---|---|
+| Discovery (RFC 8414) | `GET {issuer}/.well-known/openid-configuration` |
+| JWKS (the signing keys) | `GET {issuer}/jwks.json` (the discovery document's `jwks_uri` is authoritative) |
+| Authorization endpoint | `{issuer}/op/authorize` |
+| Token endpoint | `{issuer}/op/token` (authorization_code ONLY) |
+| UserInfo | `{issuer}/op/userinfo` |
+| Account console (your users manage their own profile, linked identities, password, avatar there) | `{issuer}/op/account` |
+
+## 3. Onboarding your service (the client registry)
+
+Your service needs a client registration on the OP. One entry:
+
+```json
+{
+  "client_id": "your-service-name",
+  "name": "Your Service",
+  "secret": "… (confidential clients only)",
+  "redirect_uris": ["https://your-service.example/auth/callback"],
+  "claims_policy": {
+    "claims": ["roles", "groups", "org"],
+    "roles": ["viewer", "mc_member"]
+  }
+}
+```
+
+- **Public client** (no `secret`): browser/SPA/native apps — PKCE is
+  the whole credential. **Confidential client** (with `secret`):
+  server-side apps that can keep a secret.
+- `redirect_uris` are **exact-match**. No wildcards, ever.
+- `claims_policy` (the per-client privilege): `claims` names the claim
+  FAMILIES the ID token may carry for your service (absent = profile +
+  email only); `roles` bounds WHICH roles those claims may carry
+  (absent = unbounded by the policy — declare it). **Least claims by
+  default**: if you need only identity, ask for no claims policy.
+- How to get registered: ask an OP administrator (the admin console at
+  `{issuer}/op/admin` manages clients), or the registry API
+  (`POST /api/op/clients`, admin-held), or — for a self-hosted OP — the
+  `OP_CLIENT_SEED` bootstrap env.
+- Rotation and disable: a client can be disabled without deleting its
+  audit trail; a disabled client's tokens stop at issuance (existing
+  sessions at your service die at YOUR session lifetime — see §8).
+
+## 4. The claims contract (what the ID token carries)
+
+Standard: `iss` (exactly the issuer URL), `sub` (the stable account id —
+THIS is your user key, never the email), `aud` (your client_id), `exp`
+(validate with ≤ 60 s leeway), `email`, `name`, plus the policy-gated
+families:
+
+- `roles` — the account's estate role codes (see §6 for the vocabulary).
+- `groups` — the account's group memberships.
+- `org` — the account's registered organization affiliation.
+
+Claims beyond profile+email arrive ONLY when your client's policy
+allows them. The same user signing into two services can therefore
+carry different claim sets — by design.
+
+**`picture` rides userinfo, not the ID token** — the ID token carries
+the profile contract (name/email + policy families); the avatar URL
+arrives at the userinfo endpoint (declared in discovery). Relying
+parties that want the photo fetch userinfo with the access token,
+sub-checked against the ID token's `sub`.
+
+## 5. The sign-in flow (authorization code + PKCE)
+
+1. Discover: `GET {issuer}/.well-known/openid-configuration`; the
+   `issuer` value in the metadata MUST match the issuer URL exactly.
+2. Build the authorization request: `GET {issuer}/op/authorize` with
+   `response_type=code`, `client_id`, `redirect_uri` (exact), `scope`
+   (`openid profile email` + your policy's families), `state`
+   (unguessable, stored), `nonce` (unguessable, stored), and PKCE
+   (`code_challenge`, S256 — never plain).
+3. The user authenticates at the OP (password and/or a linked upstream
+   IdP) and consents; the OP redirects to your `redirect_uri` with
+   `code` + `state`. Verify `state` before anything else.
+4. Exchange: `POST {issuer}/op/token` with `grant_type=
+   authorization_code`, the code, the same `redirect_uri`, and the PKCE
+   `code_verifier` (plus HTTP-Basic client auth for confidential
+   clients). No other grant type is served today (machine callers: §9).
+5. Validate the ID token (§6), then build YOUR OWN session (your cookie,
+   your lifetime). The ID token is evidence of the sign-in event, not a
+   session.
+6. Logout: end your session; if the metadata declares
+   `end_session_endpoint`, redirect there for the OP-side sign-out.
+
+## 6. Validating tokens (the must-dos)
+
+- Verify the signature against the JWKS (`jwks.json`, cached briefly —
+  the OP rotates keys with JWKS overlap, so never hard-pin a `kid`).
+- Check `iss` (exact), `aud` (your client_id; `azp` when several
+  audiences), `exp` (≤ 60 s leeway), and the `nonce` you issued.
+- Do the validation INSIDE your service. A check at an edge/WAF is UX,
+  never the gate.
+- On any failure: fail closed, in plain language, never a stack trace.
+
+The reference implementation (copy it; ~300 lines, zero dependencies,
+WebCrypto + fetch only, runs on Node ≥ 18 and edge runtimes):
+`browser/server/auth/oidc.ts` in `oimlsmart/smart` — discovery, PKCE,
+the exchange, the validation, the logout URL, and the error taxonomy.
+
+## 7. Who declares what actions are allowed (the authorization division)
+
+This is the question every integrator asks. The division:
+
+- **The OP declares WHO the user is** — identity plus the coarse estate
+  role claims your client's policy allows. The OP's administrator
+  controls which roles exist and which accounts hold them; the OP's
+  per-client claims policy bounds what your service may SEE.
+- **Your service declares WHAT those roles may do** — your action
+  vocabulary, your role→permission map, your enforcement at your own
+  routes. Never invert this (the OP is not a fine-grained policy
+  engine, by design).
+
+The platform's own RBAC is the reference shape (`oimlsmart/smart`):
+`browser/src/auth/permissions.ts` declares the action vocabulary;
+`browser/src/auth/rbac.ts` holds the default role→permission map;
+`browser/server/rbac.ts` resolves the EFFECTIVE map per instance
+(an installed profile map, then the `INSTANCE_RBAC_JSON` env, then the
+shipped default) and the entity routes enforce the write gates. The
+estate role vocabulary today: `applicant`, `ia_officer`, `tl_operator`,
+`biml_officer`, `cs_admin`, `mc_member`, `rc_member`,
+`executive_secretary`, `admin`, `viewer`, plus the NMI split roles
+(`case_officer`, `certification_officer`, `signatory`) and `org_admin`
+(delegated organization administration). Map your service's actions to
+the roles your claims policy receives — or keep your own roles internal
+and map the estate roles into them at your boundary.
+
+## 8. Centralized management or multiple services — both, deliberately
+
+- **Centralized (the estate's shape):** ONE OP, many registered
+  clients. Every service onboards per §3. Users have one account with
+  linked login methods; the admin surface is one console. This is the
+  recommended shape for anything in the oimlsmart.org estate.
+- **Multiple SERVICES on one OP** is the normal case (one client
+  registration each) — nothing extra to do.
+- **Multiple identity PROVIDERS** (a sovereign deployment): a
+  self-hosted platform instance can point its RP side at a DIFFERENT
+  issuer entirely (the instance's `OIDC_ISSUER` configuration) — e.g. a
+  national body's own provider. Supported, with the trade named: that
+  deployment leaves the estate's shared account registry and role
+  coherence. The softer shape for most members: keep trusting the
+  estate OP and link the member's provider as an UPSTREAM login method
+  (users sign in with their national IdP; the account stays the
+  estate's).
+- The OP itself is deployable outside the hosted Cloudflare shape
+  (Node + SQLite / a container image — see
+  `docs/deployment/identity-operations.md` §"Deployment portability"),
+  so a sovereign operator can run the whole OP too.
+
+## 9. Machine callers (today's honest gap)
+
+The OP serves authorization code + PKCE ONLY. There is no
+`client_credentials` grant today: non-human callers (agent pipelines,
+MCP servers) are NOT served yet. The gap is recorded and sized in
+`TODO.identity-ops/07` (service accounts as confidential clients with
+no redirect URIs, audience-bound tokens, scoped claims). If your
+integration needs machine tokens, say so — that is the trigger that
+schedules it. Do NOT work around it by embedding a human's credentials.
+
+## 10. What your service inherits
+
+- **Degraded mode**: when the OP is unreachable, existing sessions at
+  your service ride their own cookies; new sign-ins fail honestly.
+  State your behavior and cache JWKS briefly so validation survives
+  short OP outages.
+- **Offboarding**: an account disabled at the OP stops issuing
+  immediately; its existing session at YOUR service dies at YOUR
+  session lifetime. Re-check the OP on sensitive acts.
+- **Erasure**: a deleted account's `sub` stops resolving; keep your own
+  records keyed by `sub` and treat an unresolvable `sub` as anonymous.
+
+## 11. Development and test posture
+
+- A local OP for development: the platform's node dev stack boots the OP
+  profile locally (see `docs/deployment/identity-operations.md`); point
+  your service's issuer config at it. The demo accounts exist for
+  development only — never a production login path.
+- The test pattern to copy: the identity e2e legs in
+  `oimlsmart/smart` (`browser/e2e/`, the identity-arc legs) boot the OP
+  and an RP in one harness.
+- The OP's failures answer a machine `reason` — map them to plain
+  language; never leak internals to your users.

package/docs/knowledge-annealment.md

@@ -0,0 +1,273 @@
+# The knowledge-annealment ladder v2 — defined by system primitives
+
+**The instrument for the four-corpus comparison** (Bulletin paper #2).
+Annealment = the degree to which knowledge is bound into structure a
+machine can traverse and compute. Each rung is defined by WHICH PRIMITIVES
+it requires; each corpus lane is characterized by the primitives its
+representation carries. A lane's **capability ceiling** = the highest
+consecutive rung at ≥60% witness-checked pass; its **annealment index** =
+the fraction of primitive tiers it materializes. Pass is always
+witness-checked; L8/L9 witnesses are COMPUTED, never judged.
+
+Fixed corpus across lanes: the OIML R 60 family (2021 p1–3 + annexes;
+the 2017 edition package for diachrony).
+
+## The primitive taxonomy (P1–P10) and who carries what
+
+| Tier | Primitive | Metanorma/MKO realizes | Primmel realizes |
+|---|---|---|---|
+| P1 | surface text | adoc prose | prl descriptions |
+| P2 | editorial anchoring | clause/unit/number/title/breadcrumb/cite_as | section + `source: urn#clause` on everything |
+| P3 | object geometry | table payload (cols/rows), figure, formula display | tables with TYPED columns (name/type/unit) |
+| P4 | nomenclature | glossary concepts, designations | terms with vocabulary registers (VIML), multilingual spellings, form types; aspects & behaviors registries |
+| P5 | relation | part_of/cites/defines edges | curated clause-level references; `uses:` package composition (CASCO); requirement↔aspect binding; type↔instance references |
+| P6 | temporality | editions + derived status | edition lifecycle (status/supersedes/validity.from) + FULL edition packages (diffable) |
+| P7 | perception | figure units + assets + captions | figure references (fig-2/fig-3 in sequences) |
+| P8 | quantitative typing | UnitsML in stems — flattened to string suffixes by the export (metanorma-document#55) | **unit register**: stable ids, quantity_kind, dimension vector, SI coherent unit, conversion factor; coherence on KINDS |
+| P9 | computation | formula asciimath+mathml (display-only; no evaluation semantics — metanorma-document#55 GAP-3) | formulas-as-operations (lookup with params); calculations (typed IO); **OCL constraints with violation meaning + on_violation** |
+| P10 | instance & process | — | entity schemas (type vs instance, obligation/cardinality); ordered test sequences (roles, contamination semantics); workflows; execution forms |
+
+Meta-primitive (P★, Primmel only): **self-verification** — the model-linker
+rules (quantity-coherence, requirement-binding-targets) and the
+burned-to-empty allowlist ledger: the model is machine-checked consistent.
+
+**Lane inventories:** A `exp_plain` = P1(+P2 as text) · B `exp_adoc` =
+P1, P2-textual, P3-degraded · C `exp_mko` = P1–P7 (P8 weak strings) ·
+D `exp_primmel` = P1–P10 · **E `exp_primmel_flat`** (diagnostic ablation:
+D's projected prose WITHOUT payloads/edges/typing) — separates "better
+text" from "better structure" inside D; the causal control the paper
+needs.
+
+## The ladder (L0–L9, sub-probes where the systems diverge)
+
+**L0 LOCATE** (P1–P2). *"Where does R 60 address creep?"* Witness: clause
+anchor. All lanes pass — the sanity floor.
+
+**L1 EXTRACT** (P1–P2). Verbatim value from prose. Witness: exact
+string. All lanes pass; small separation.
+
+**L2 NOMENCLATURE** (P4). Colloquial → defined term.
+a) corpus-local ("drift"→durability) b) **cross-register**: the VIML
+clause via vocab_ref c) multilingual spelling resolution (Primmel only).
+Witness: term + register anchor. Expected: C strong at (a), D strong
+(a–c), A/B luck.
+
+**L3 GEOMETRY** (P3+P8). a) cell lookup by row×column (typed block
+required) b) **unit-aware cell**: the value AND its quantity kind (P8:
+is n_LC dimensionless? loads in `v` units?) c) derived cell (needs a
+lookup formula — transitional to L8). Witness: value + row/col keys +
+unit kind. Expected: A ≤40%, B partial, C strong (a), D strong (a–c).
+
+**L4 COMPOSITION** (P2+P5). a) intra-document join (MPE table + doubling
+clause + load bands) b) **cross-part** join (R 60-1 requirement ↔ R 60-2
+test ↔ R 60-3 form). Witness: both anchors + derived relation. Expected:
+C/D strong at both; A/B partial (b near-zero).
+
+**L5 CROSS-STANDARD** (P5). a) cites-edge ("which ISO/IEC test method
+does R 60-2 invoke for humidity?") b) **composition + binding** ("which
+CASCO vocabulary governs the certification activities; which aspects do
+requirements bind?"). Witness: the linked id/clause. **ISOLATION: links
+only in public lanes — ISO/IEC text never appears** (structural rule).
+Expected: D strong, C partial (a), A/B near-zero.
+
+**L6 DIACHRONY** (P6). a) current-edition selection b) **delta
+extraction** 2017→2021 (the 2017 edition PACKAGE makes real diffs
+computable) c) validity windows. Witness: edition pair + delta fact.
+Expected: D strong, C partial (alignment, no diffs), A/B near-zero.
+
+**L7 PERCEPTION** (P7). a) caption/asset b) pixel-only content (labels
+readable only from the drawing) c) user-image grounding (nameplate
+photo). Witness: pixel-only label / classification. Expected: C strong,
+D via figure references, A/B zero. **The visible demo separator — and
+live in production:** the pinned figure's pixels ride the generation
+call (asset readability + message shape are measured invariants; see
+the mechanism reference #12), so pixel-only labels are read from the
+drawing itself, not disclaimed against the caption.
+
+**L8 COMPUTATION** (P9+P8). a) pure calculation (conversion factor f
+from inputs) b) **constraint/conformance verdict with the violation
+meaning** ("is D_max=0.8·E_max acceptable?" → the OCL answer AND the
+recorded violation semantics) c) **unit-coherence judgment** (compare
+3000 kgf vs 30 kN via the register — P8). Witnesses: COMPUTED offline
+from the model (deterministic, no judge). Expected: **D only, by
+construction.**
+
+**L9 INSTANCE & PROCESS** (P10). a) **process order & consequence**
+("what is contaminated if creep runs before MDLO?" — encoded as sequence
+semantics, not prose) b) instance-grounded facts (a specific recorded
+type/instance profile — sample data only) c) execution-form knowledge
+(test report structure). Witnesses: order verdict / instance fact
+(deterministic from entities). Expected: **D only.**
+
+## Rigor rules (v2 additions)
+
+1. **Containment filtering**: every L8/L9 question is checked against
+   the corpus text — if the specific answer string exists in prose, the
+   question cannot separate lanes and is replaced. The instrument must
+   probe structure, not memory of printed answers.
+2. **Ablation lane E** (primmel-flat) is mandatory: without it, D's win
+   is confounded by projection prose quality.
+3. **Deterministic graders** for L8/L9 (computed ground truth); judge
+   only at L4 (synthesis) — the instrument's upper rungs are its most
+   objective.
+4. Sequential measurement windows per lane; ×3 repeats; ranges reported.
+
+## Golden set v2
+
+~66 primary questions (6–7/rung incl. sub-probes) + 2 paraphrases for
+L0–L6; R 60 primary, R 76-1 generality probes at L1/L3/L4 (A/B/C only).
+Headline outputs: the **lane × rung matrix**, per-lane **primitive
+activation radar** (P1–P10), **capability ceiling**, **annealment
+index**, and **cost per correct answer**.
+
+
+---
+
+# The three eras — and the Primmel frontier (F1–F12)
+
+## The era framing
+
+| Era | Representation | Primitives | What the assistant IS | Ceiling |
+|---|---|---|---|---|
+| **1 · LEGACY** | plain text / raw adoc | P1–P2 | an index: find and restate | L1–L3 |
+| **2 · NOW** | MKO (P1–P7) · Primmel-KO (P1–P10) | structure, typing, execution | a grounded instrument: cite, render, verify, compute | MKO L7 · Primmel L9 |
+| **3 · FRONTIER** | Primmel objects (F1–F12 below) | closed world + executability + instances | an OPERATOR: verdict, simulate, prove, personalize, walk processes, verify publications | beyond L9 |
+
+The comparison programme (TODO 15–20) measures Era 2's value per primitive.
+The FRONTIER is Era 3 — capabilities that exist because the corpus is a
+model with a closed world, executable semantics, and recorded instances.
+**No document representation can follow** — these are the special wins
+for D that make Primmel the destination, not just the winner of a test.
+
+## F1 — Verdict as data (conformance-as-a-service)
+`Verdict` data class ("the canonical verdict chain"), OCL constraints
+with `violation_meaning` + `on_violation`, examination reports. Answers
+return a **VERDICT BLOCK**: pass/fail/void + the reason in the
+standard's own words + the full clause chain — produced by EXECUTION,
+verified by execution. The answer contract's strongest artifact class.
+
+## F2 — Counterfactual simulation
+Constraints and table-lookup formulas run on HYPOTHETICAL parameters:
+*"what if D_max were 0.8·E_max?"* → the OCL verdict + violation meaning;
+*"which accuracy class for n_LC = 3000?"* → the lookup INVERTED.
+Documents state facts; models evaluate hypotheses.
+
+## F3 — Exhaustiveness and provable absence
+The closed world (audited: all 60 requirements, 62 tests; forAll
+semantics) → *"list ALL requirements binding marking"* is COMPLETE, and
+*"does R 60 require X? — no, provably"* is a proof, not a refusal.
+Retrieval corpora can only fail to find; the model can show the absence.
+
+## F4 — Instance-grounded, parameterized answers
+Attributes scoped family/instance + load-cell-instance entities + sample
+data → the MPE table becomes a FUNCTION evaluated at the user's
+instrument (Max, e, class): the answer is computed for YOUR device.
+(Member/internal tier.) Input annealment: the unit register normalizes
+any input units first.
+
+## F5 — Certification workflow statefulness
+`evaluation/processes` (layer-composed, `validate_provision` URN
+anchors), gateways, execution forms + checklist → a procedural assistant
+that knows where the evaluation stands, what gates what, what runs next —
+and can advance checklist state. Agentic, not just informative.
+
+## F6 — Impact analysis (committee tooling)
+Requirement↔test↔formula↔table bindings (`formulas-used`, aspect
+bindings) → *"if limit_factor for class C changes, which requirements,
+tests, verdicts and forms change?"* — change impact over the dependency
+graph. Drafting-committee superpower.
+
+## F7 — Semantic edition diffs + temporal jurisdiction
+Full 2017 edition PACKAGES + `validity.from` → edition deltas COMPUTED at
+model level ("what changed in the creep requirement") and retro-jurisdiction
+questions ("which edition governed a 2019 evaluation?").
+
+## F8 — Self-verification as a query (meta-grounding)
+The model-linker rules and the burned-empty allowlist: the corpus is
+machine-checked consistent — so the assistant can VERIFY ITS OWN
+model-grounded claims by execution. The faithfulness judge's successor
+for the D lane.
+
+## F9 — Document-as-projection verification
+`documents/*/presentation.xml`: the model carries its own renders →
+*"does the published Table 4 match the model?"* — QA of PUBLISHING
+itself; the inverse direction (model → document generation) later.
+
+## F10 — Normative notes as overrides
+First-class NOTE/EXAMPLE objects with override semantics ("the MPE for
+creep shall ALWAYS use p_LC = 0.7 regardless of the manufacturer's
+declaration") → notes become queryable RULES that feed computation, not
+buried prose that computation ignores.
+
+## F11 — Composition-aware answers
+`uses:` package composition (ISO/IEC 17000/17065) with layer-overlay
+semantics → questions spanning the composition carry per-layer
+provenance: "core says X; R 60 overlays Y" — co-location is not
+composition, and only the model composes.
+
+## F12 — The machine passport (r60-to-dpp.prm)
+The `.prm` artifact: answers exportable as structured passport DATA, not
+prose — the answer contract's ultimate block type. The Q&A becomes a
+data source for downstream systems.
+
+## Frontier sequencing
+
+**LIVE** (serving the public today): F1 verdicts, F2 counterfactuals, F3
+provable absence, F8 answer verification. **Within reach of the current
+model plane** (deterministic witnesses, no producer dependency): F7
+edition diffs, F10 note overrides. **Programme scale** (instance
+execution and estate data): F4, F5, F6, F9, F11, F12.
+
+## Structural retrieval (the clause tree, adapted from FABLE/BEAR, arXiv:2601.18116)
+
+FABLE/BEAR (arXiv:2601.18116) retrieves over LLM-built semantic forests;
+we adapt its serving techniques to a corpus that already IS a tree —
+Metanorma clause anchors chain parent→child natively, so no index-time
+tree-builder runs at all (the paper's entire offline cost collapses to
+~1,400 synthetic depth-1 summary nodes, ≈$3 one-time). Three techniques
+ship in the serving path (`src/structural.ts`), each gated by the golden
+suite:
+
+1. **Structural propagation** (their TreeExpansion, Eq. 7): a hit's
+   score blends with its ancestors' (topic continuity) and descendants'
+   (subtopic heat) — a section whose clauses are collectively hot rises;
+   a hot section lifts its clauses. Spread-scaled like edition steering,
+   so the cross-encoder's own signal always dominates.
+2. **Position-preserving evidence order** (their NodeFusion): passages
+   are presented in document reading order per publication (publications
+   by best rank) — synthesis quality depends on arrangement, not just
+   set membership. Applied in `buildMessages`, so every consumer (ask,
+   research, lanes) inherits it.
+3. **Ancestor-descendant dedup**: near-duplicate chunks of one clause
+   chain (parent §3.1 vs child §3.1.2 repeating its text) collapse to
+   the stronger one before the window is cut.
+
+Plus the **multi-granularity index** (their internal-node indexing): the
+corpus's chunks start at depth 2 ("3.1") — depth-1 nodes ("§3") did not
+exist as retrievable objects. `/admin/section` (admin-token gated,
+mirrors `/admin/enrich`) generates, embeds (toc-path ⊕ summary style)
+and upserts them; the pipeline descends from a ranked section unit to
+its quotable child clauses and retires the synthetic summary (citations
+must quote source clauses, never our own summaries). Driver:
+`ingest/cli.py sections` (resumable — KV-cached per unit id). And the
+eval harness reports **EIR** (context utilization: cited/retrieved at
+the answer) — the precision-side counterpart to witness recall, after
+their EIR metric.
+
+## Era 3: execution (the frontier is live)
+
+Beyond the ladder, the machine objects are EXECUTED, not retrieved:
+
+- **Verdicts** (`src/verdict.ts`): a question naming a constraint or
+  machine limit gets the check evaluated against its stated values —
+  pass / the standard's own violation word / void naming what is
+  missing — attached as data the answer must present faithfully.
+  Counterfactuals are free (values are values).
+- **Provable absence** (`/v1/absence`): an enumeration certificate
+  over the standard's model plane — absent means "N nodes enumerated,
+  0 matches", never a bare refusal.
+- **Answer verification** (`/v1/verify`): the deterministic contract
+  battery plus a judged faithfulness score, exposed for any answer.
+
+The full mechanism reference — every serving layer with its staircase
+(what the layer below cannot do) — is `docs/sota-mechanisms.md`.