From d534b814adfe66b671861d53ea2d32c7b7f7c03d Mon Sep 17 00:00:00 2001 From: Jeremi Joslin Date: Fri, 21 Aug 2026 07:14:12 +0200 Subject: [PATCH 1/3] docs: describe both Evidence source transports architecture.mdx and boundaries-and-map.mdx presented a fixed HTTP JSON request as the only way an Evidence source reaches its data. The frozen contract set has carried two coequal transports since the SQLite extract source was added: products/evidence/contracts/source-contract.yaml and products/evidence/contracts/sqlite-extract-source-contract.yaml, selected by the closed http-json and sqlite-extract variants in bundle.schema.yaml. Describe both on the architecture page, its diagram alt text, the diagram's , and the Evidence "source access as a general capability" boundary, and anchor each new claim in the frozen contract that carries it. Replace the TODO[evidence] on the Solmara Lab source mapping: that configuration is now citable from the pinned solmara-lab commit already linked in src/data/projects.yaml, so the page states which cells use which transport instead of weakening the claim. Bump last_reviewed on both pages, which are read against source here. That reading also turned up three citations that had drifted off their line numbers and one wrong list of the registry patterns the demo simulates; cite those by symbol name instead, and correct the list. Signed-off-by: Jeremi Joslin --- .../images/registry-architecture-flow.svg | 2 +- .../content/docs/explanation/architecture.mdx | 59 +++++++++++-------- .../content/docs/map/boundaries-and-map.mdx | 41 +++++++------ 3 files changed, 61 insertions(+), 41 deletions(-) diff --git a/docs/site/public/images/registry-architecture-flow.svg b/docs/site/public/images/registry-architecture-flow.svg index f18018552..537dc6cfd 100644 --- a/docs/site/public/images/registry-architecture-flow.svg +++ b/docs/site/public/images/registry-architecture-flow.svg @@ -2,7 +2,7 @@ font-family="'Public Sans', system-ui, -apple-system, BlinkMacSystemFont, sans-serif" text-rendering="geometricPrecision"> Registry architecture flow - Registry Platform provides shared primitives to both runtime services. Registry Manifest produces portable metadata contracts describing what a registry exposes. Registry Relay independently compiles a reviewed registry contract and serves protected read-only operations over one local read-only SQLite source; it does not read a Registry Manifest document. Evidence Gateway independently answers one bounded question about one subject from its own configured authoritative HTTP sources and returns a signed assertion carrying the answer and not the record. Registry Mint is a supporting service that issues the short-lived access tokens Evidence Gateway verifies, for deployments with no identity provider. The external Solmara Lab adopter demo provides synthetic registry data. + Registry Platform provides shared primitives to both runtime services. Registry Manifest produces portable metadata contracts describing what a registry exposes. Registry Relay independently compiles a reviewed registry contract and serves protected read-only operations over one local read-only SQLite source; it does not read a Registry Manifest document. Evidence Gateway independently answers one bounded question about one subject from its own configured authoritative sources, reached over a fixed HTTP JSON request or one reviewed SQL statement against a read-only SQLite extract, and returns a signed assertion carrying the answer and not the record. Registry Mint is a supporting service that issues the short-lived access tokens Evidence Gateway verifies, for deployments with no identity provider. The external Solmara Lab adopter demo provides synthetic registry data. SHARED PRIMITIVES diff --git a/docs/site/src/content/docs/explanation/architecture.mdx b/docs/site/src/content/docs/explanation/architecture.mdx index 04a842f48..a466b533f 100644 --- a/docs/site/src/content/docs/explanation/architecture.mdx +++ b/docs/site/src/content/docs/explanation/architecture.mdx @@ -10,7 +10,7 @@ source_repos: - registry-evidence - registry-mint - solmara-lab -last_reviewed: "2026-08-11" +last_reviewed: "2026-08-21" doc_type: explanation locale: en standards_referenced: @@ -33,7 +33,7 @@ The metadata layer (Registry Manifest) compiles and renders discovery artifacts registry exposes, without touching production sources. The runtime services layer enforces access against real data. Registry Relay compiles a governed registry contract into a fixed set of read-only operations over a read-only SQLite source. Evidence -Gateway uses its own governed bundle and authoritative HTTP sources to answer bounded questions with +Gateway uses its own governed bundle and authoritative sources to answer bounded questions with signed assertions. Registry Platform provides shared Rust primitives consumed by both runtime services. Registry Mint is a supporting service rather than a fifth product: it issues the short-lived access @@ -49,18 +49,25 @@ At runtime, Registry Stack exposes source data through two patterns: - Minimum-disclosure assertions: one bounded question about one subject, answered with a signed assertion that carries the answer and not the record. Evidence Gateway implements this runtime surface. -The two patterns are independent. Evidence Gateway contacts its configured authoritative HTTP -sources directly. It does not require Registry Relay or inherit Relay authorization. A deployment -can configure a Relay-protected API as a fixed HTTP source, but Relay remains an ordinary source -rather than part of the Evidence Gateway product boundary. The separate Solmara Lab demo makes that -choice for some of its requirements: an authority's Evidence Gateway cell reads a named Relay -lookup as one of its sources, and inherits no Relay authorization from it. - -{/* TODO[evidence]: which Solmara Lab requirements read a Relay lookup cannot be anchored from -this repository. That mapping lives with the deployment configuration in the separate -registrystack/solmara-lab project, described in the README pinned from src/data/projects.yaml. -The claim above is weakened to match: some requirements, not a named set. Restore the enumeration -once that configuration is citable from here. */} +The two patterns are independent. Evidence Gateway reaches its configured authoritative sources +directly, over one of two coequal transports: a fixed HTTP JSON request to a fixed HTTPS origin, or +one reviewed SQL statement against a read-only SQLite extract file mounted beside the process. It +does not require Registry Relay or inherit Relay authorization. A deployment can configure a +Relay-protected API as a fixed HTTP source, but Relay remains an ordinary source rather than part of +the Evidence Gateway product boundary. + +The separate Solmara Lab demo uses both transports. Among its +[Evidence cell definitions](https://github.com/registrystack/solmara-lab/tree/3d5c492ea50c6fdcefd5978df6f036422096421c/evidence/cells), +the MoSD, NAgDI, and SIPF cells reach a Relay-protected API over a fixed HTTP JSON request, the NIA +and SRO cells run a reviewed SQL statement against a published extract, and the CRA cell does both. +A cell that reaches a Relay-protected API inherits no Relay authorization from it. + +{/* Evidence: two coequal source transports, products/evidence/CONCEPT.md, "A fixed source request + reaches its source over one of two coequal transports"; the closed source variants + http-json-source and sqlite-extract-source under `source` in + products/evidence/contracts/bundle.schema.yaml (frozen). Solmara Lab transport per cell, + the bundle/evidence.yaml file under each directory in evidence/cells at the commit linked + above. */} This split matters because it separates the obligation to describe (what a registry declares it can expose and under what policy) from the obligation to enforce (what a running service will actually return to an @@ -76,8 +83,9 @@ updated policy documents without touching deployment config. registry contract and serves protected read-only APIs over a read-only SQLite source. Evidence Gateway answers one bounded question about one subject and returns a signed assertion carrying the answer and not the record, using its own configured authoritative - HTTP sources. Registry Mint is a supporting service issuing the short-lived access tokens - Evidence Gateway verifies. The separate Solmara Lab adopter project provides synthetic + sources, reached over a fixed HTTP JSON request or one reviewed SQL statement against a + read-only SQLite extract. Registry Mint is a supporting service issuing the + short-lived access tokens Evidence Gateway verifies. The separate Solmara Lab adopter project provides synthetic registry data for demonstrations." /> @@ -155,16 +163,21 @@ decision. properties a disclosure profile declares. The one runtime file (`runtime.yaml`, `kind: RelayRuntime`) binds local paths, the audit sink, secret references, limits, and an optional OIDC issuer, and cannot widen anything the package sealed. - {/* Evidence: RelayRuntime is a closed deny_unknown_fields schema over server, packagePath, - sources, authentication, audit, cursor, limits, quotas, and shutdown only, - crates/registry-relay-v2/src/contract.rs:1062-1079; startup verifies the package before + {/* Evidence: the RelayRuntime struct is a closed deny_unknown_fields schema over server, + packagePath, sources, authentication, audit, cursor, limits, quotas, and shutdown only, + crates/registry-relay-v2/src/contract.rs; startup verifies the package before opening any other resource, crates/registry-relay-v2/src/startup.rs:96-104. */} 6. Evidence Gateway evaluates one predefined, versioned requirement per request, aligned with CCCEV through - its frozen field mapping. Rust owns authentication, authorization, the one fixed bounded HTTP JSON - source request, output validation, assertion construction, signing, and audit; trusted Rhai + its frozen field mapping. Rust owns authentication, authorization, the one fixed bounded source + request, output validation, assertion construction, signing, and audit; trusted Rhai scripts prepare that request and extract typed facts. Caller identity and authorization details - can authorize or parameterize a request but cannot supply facts. Its fixed HTTP source is configured - directly for the authoritative system. + can authorize or parameterize a request but cannot supply facts. That request reaches either a + fixed HTTPS origin configured directly for the authoritative system, or a read-only SQLite extract + file that the bundle names by logical profile and the runtime binds to an exact path. + {/* Evidence: the closed http-json and sqlite-extract source variants, and the extractProfile + logical name, products/evidence/contracts/bundle.schema.yaml (frozen); the runtime binds + each logical name to a process-local path under sourceExtracts, + products/evidence/contracts/runtime.schema.yaml (frozen). */} 7. Evidence Gateway returns the assertion as a flattened JWS JSON response (`application/jose+json`) by default. Where the immutable bundle and the one matched authority grant both permit it, the same stateless assertion may instead be serialized as a visibly unsigned JSON envelope or as an SD-JWT diff --git a/docs/site/src/content/docs/map/boundaries-and-map.mdx b/docs/site/src/content/docs/map/boundaries-and-map.mdx index 0cc37fcba..fe412841a 100644 --- a/docs/site/src/content/docs/map/boundaries-and-map.mdx +++ b/docs/site/src/content/docs/map/boundaries-and-map.mdx @@ -11,7 +11,7 @@ source_repos: - registry-evidence - registry-mint - solmara-lab -last_reviewed: "2026-08-11" +last_reviewed: "2026-08-21" doc_type: explanation locale: en standards_referenced: @@ -126,8 +126,8 @@ disclosure profile shapes each response, and what its audit record says. Everyth decided before the process starts, sealed into a package, and re-derived and byte-compared at startup. -{/* Evidence: RelayRuntime is a closed deny_unknown_fields schema and cannot widen the package, - crates/registry-relay-v2/src/contract.rs:1062-1079; startup verifies the package before +{/* Evidence: the RelayRuntime struct is a closed deny_unknown_fields schema and cannot widen the + package, crates/registry-relay-v2/src/contract.rs; startup verifies the package before opening any other resource, crates/registry-relay-v2/src/startup.rs:96-104; the runtime re-runs the compiler and generator and compares bytes, crates/registry-relay-v2/src/package.rs. */} @@ -142,8 +142,8 @@ It does not own: speaks no source protocol, holds no source credential, and makes no outbound call to a source, so a CSV, spreadsheet, Parquet, PostgreSQL, or HTTP registry has to be turned into SQLite by something else before Relay can serve it. - {/* Evidence: SourceProfile has exactly two variants, Snapshot and LiveReadOnly, - crates/registry-relay-v2/src/contract.rs:323-325. */} + {/* Evidence: the SourceProfile enum has exactly two variants, Snapshot and LiveReadOnly, + crates/registry-relay-v2/src/contract.rs. */} - Portable metadata schema ownership. The `metadata.yaml` manifest format and its renderers are owned by Registry Manifest. Relay does not consume a manifest and does not emit one: its artifact generator produces no `registry-manifest.yaml`, and a test holds that. @@ -175,21 +175,28 @@ response, by selecting fewer fields or filtering on a declared filterable field, filter the contract did not declare is a stable 400 rather than a wider read. {/* Evidence: the closed ProblemCode set includes request.fields_invalid, filter.unknown_field, and - filter.invalid_value, crates/registry-relay-v2/src/problem.rs:14-45. */} + filter.invalid_value, in the define_problem_codes! set in + crates/registry-relay-http-contract/src/lib.rs, which crates/registry-relay-v2/src/problem.rs + re-exports. */} ## Evidence Gateway Evidence Gateway answers one bounded question about one subject and returns a signed assertion carrying the answer rather than the record. It does not own: -- Source access as a general capability. Each evaluation uses one closed acquisition: one fixed, - bounded HTTP JSON request, or one fixed search followed after a unique schema-valid match by one - fixed fetch. Every stage has a fixed method, a fixed or tagged selector or prior-fact-bound path, - fixed non-secret headers, denied redirects, and a client-side response projection. Pagination, - transport retry, response-led routing, general multi-source fulfillment, and source-planning scripts - are outside the Version 1 contract. - {/* Evidence: contract registry.evidence.fixed-http-json-source/v1, - products/evidence/contracts/source-contract.yaml (frozen). */} +- Source access as a general capability. Each evaluation uses one closed acquisition: one fixed + bounded request, or one fixed search followed after a unique schema-valid match by one fixed + fetch. A source reaches its data over one of two coequal transports. An HTTP JSON stage has a + fixed method, a fixed or tagged selector or prior-fact-bound path, fixed non-secret headers, + denied redirects, and a client-side response projection. A statement stage runs one reviewed SQL + statement, with its declared result columns and parameter bindings, against a read-only SQLite + extract file the runtime binds by logical profile, reaching no origin and resolving no credential. + Pagination, transport retry, response-led routing, general multi-source fulfillment, and + source-planning scripts are outside the Version 1 contract. + {/* Evidence: contracts registry.evidence.fixed-http-json-source/v1, + products/evidence/contracts/source-contract.yaml, and + registry.evidence.fixed-sqlite-extract-source/v1, + products/evidence/contracts/sqlite-extract-source-contract.yaml (both frozen). */} - Record lookup and identity resolution. The authoritative provider owns lookup. Evidence Gateway accepts only `match`, `no_match`, or `ambiguous`, and does not score candidates, choose a provider record, or expose counts, near-match hints, or per-field diagnostics. @@ -250,9 +257,9 @@ Registry Stack product. It does not own: - Normative API or metadata contracts. API contracts are owned by the runtime services; metadata contracts are owned by Registry Manifest. {/* Evidence: src/data/projects.yaml, solmara-lab does_not_own. */} -- Real product integrations. The services simulate civil, social protection, and health - registry patterns but are not real integrations with OpenCRVS, OpenSPP, DHIS2, OpenIMIS, - MOSIP, or other systems. +- Real product integrations. The services simulate civil registration, population, social + protection, pension, and agriculture registry patterns but are not real integrations with + OpenCRVS, OpenSPP, DHIS2, OpenIMIS, MOSIP, or other systems. {/* Evidence: the pinned Solmara Lab README and src/data/projects.yaml. */} ## Where to look From 145c707bf0271930e20172e090f031daaa39c73e Mon Sep 17 00:00:00 2001 From: Jeremi Joslin Date: Fri, 21 Aug 2026 07:20:27 +0200 Subject: [PATCH 2/3] docs: keep the loopback HTTP source in the transport description bundle.schema.yaml accepts a numeric-loopback http origin for a source whose authentication kind is none, so stating HTTPS unconditionally excludes a supported local-assurance deployment. Say that a production bundle must state HTTPS, and anchor the exception. Signed-off-by: Jeremi Joslin --- .../content/docs/explanation/architecture.mdx | 21 +++++++++++-------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/site/src/content/docs/explanation/architecture.mdx b/docs/site/src/content/docs/explanation/architecture.mdx index a466b533f..d49b666bd 100644 --- a/docs/site/src/content/docs/explanation/architecture.mdx +++ b/docs/site/src/content/docs/explanation/architecture.mdx @@ -50,11 +50,11 @@ At runtime, Registry Stack exposes source data through two patterns: assertion that carries the answer and not the record. Evidence Gateway implements this runtime surface. The two patterns are independent. Evidence Gateway reaches its configured authoritative sources -directly, over one of two coequal transports: a fixed HTTP JSON request to a fixed HTTPS origin, or -one reviewed SQL statement against a read-only SQLite extract file mounted beside the process. It -does not require Registry Relay or inherit Relay authorization. A deployment can configure a -Relay-protected API as a fixed HTTP source, but Relay remains an ordinary source rather than part of -the Evidence Gateway product boundary. +directly, over one of two coequal transports: a fixed HTTP JSON request to a fixed origin, which a +production bundle must state as HTTPS, or one reviewed SQL statement against a read-only SQLite +extract file mounted beside the process. It does not require Registry Relay or inherit Relay +authorization. A deployment can configure a Relay-protected API as a fixed HTTP source, but Relay +remains an ordinary source rather than part of the Evidence Gateway product boundary. The separate Solmara Lab demo uses both transports. Among its [Evidence cell definitions](https://github.com/registrystack/solmara-lab/tree/3d5c492ea50c6fdcefd5978df6f036422096421c/evidence/cells), @@ -172,10 +172,13 @@ decision. request, output validation, assertion construction, signing, and audit; trusted Rhai scripts prepare that request and extract typed facts. Caller identity and authorization details can authorize or parameterize a request but cannot supply facts. That request reaches either a - fixed HTTPS origin configured directly for the authoritative system, or a read-only SQLite extract - file that the bundle names by logical profile and the runtime binds to an exact path. - {/* Evidence: the closed http-json and sqlite-extract source variants, and the extractProfile - logical name, products/evidence/contracts/bundle.schema.yaml (frozen); the runtime binds + fixed origin configured directly for the authoritative system, which a production bundle must + state as HTTPS and only a local unauthenticated one may state as numeric loopback, or a read-only + SQLite extract file that the bundle names by logical profile and the runtime binds to an exact + path. + {/* Evidence: the closed http-json and sqlite-extract source variants, the baseUrl pattern pair + admitting an http numeric-loopback origin only when authentication kind is none, and the + extractProfile logical name, products/evidence/contracts/bundle.schema.yaml (frozen); the runtime binds each logical name to a process-local path under sourceExtracts, products/evidence/contracts/runtime.schema.yaml (frozen). */} 7. Evidence Gateway returns the assertion as a flattened JWS JSON response (`application/jose+json`) by From ecfdf8a41331b8fbf4563577f1e69658e42e8ca5 Mon Sep 17 00:00:00 2001 From: Jeremi Joslin Date: Fri, 21 Aug 2026 07:35:36 +0200 Subject: [PATCH 3/3] docs: qualify Rhai request preparation per source transport fixed-request requires prepareScript, but a statement source declares one only alongside a prepared parameter, so a SQLite source whose parameters all name authorized selector fields has Rust bind them and runs no preparation script. Say which transport declares what. Signed-off-by: Jeremi Joslin --- .../content/docs/explanation/architecture.mdx | 24 +++++++++++-------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/site/src/content/docs/explanation/architecture.mdx b/docs/site/src/content/docs/explanation/architecture.mdx index d49b666bd..906343e55 100644 --- a/docs/site/src/content/docs/explanation/architecture.mdx +++ b/docs/site/src/content/docs/explanation/architecture.mdx @@ -169,17 +169,21 @@ decision. opening any other resource, crates/registry-relay-v2/src/startup.rs:96-104. */} 6. Evidence Gateway evaluates one predefined, versioned requirement per request, aligned with CCCEV through its frozen field mapping. Rust owns authentication, authorization, the one fixed bounded source - request, output validation, assertion construction, signing, and audit; trusted Rhai - scripts prepare that request and extract typed facts. Caller identity and authorization details - can authorize or parameterize a request but cannot supply facts. That request reaches either a - fixed origin configured directly for the authoritative system, which a production bundle must - state as HTTPS and only a local unauthenticated one may state as numeric loopback, or a read-only - SQLite extract file that the bundle names by logical profile and the runtime binds to an exact - path. + request, output validation, assertion construction, signing, and audit; a trusted Rhai script + extracts the typed facts, and a second one prepares the request where the source declares one. + An HTTP JSON source always declares a preparation script; a statement source usually declares + none, because most of its parameters name the authorized selector field they come from and Rust + binds those itself. Caller identity and authorization details can authorize or parameterize a + request but cannot supply facts. That request reaches either a fixed origin configured directly + for the authoritative system, which a production bundle must state as HTTPS and only a local + unauthenticated one may state as numeric loopback, or a read-only SQLite extract file that the + bundle names by logical profile and the runtime binds to an exact path. {/* Evidence: the closed http-json and sqlite-extract source variants, the baseUrl pattern pair - admitting an http numeric-loopback origin only when authentication kind is none, and the - extractProfile logical name, products/evidence/contracts/bundle.schema.yaml (frozen); the runtime binds - each logical name to a process-local path under sourceExtracts, + admitting an http numeric-loopback origin only when authentication kind is none, the + extractProfile logical name, prepareScript required on fixed-request, and prepareScript + stated on a statement source only alongside a prepared parameter, + products/evidence/contracts/bundle.schema.yaml (frozen); the runtime binds each logical + name to a process-local path under sourceExtracts, products/evidence/contracts/runtime.schema.yaml (frozen). */} 7. Evidence Gateway returns the assertion as a flattened JWS JSON response (`application/jose+json`) by default. Where the immutable bundle and the one matched authority grant both permit it, the same