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..906343e55 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 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), +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,28 @@ 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 - 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. + its frozen field mapping. Rust owns authentication, authorization, the one fixed bounded source + 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, 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 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