docs: describe both Evidence source transports - #798
Merged
Conversation
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 <desc>, 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 <jeremi@joslin.fr>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d534b814ad
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
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 <jeremi@joslin.fr>
Member
Author
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 145c707bf0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
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 <jeremi@joslin.fr>
Member
Author
|
@codex review |
|
Codex Review: Didn't find any major issues. You're on a roll. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
jeremi
added a commit
that referenced
this pull request
Aug 21, 2026
PR #798 corrected the architecture page's claim that an Evidence Gateway source is always reached over HTTP. The same HTTP-only framing survived on seven more pages and in the trust-boundaries diagram, so a reader could still conclude that Evidence must cross a network boundary to reach a source, and that a source always resolves a credential. Both source transports are frozen and coequal: registry.evidence.fixed-http-json-source/v1 and registry.evidence.fixed-sqlite-extract-source/v1. A statement source has no origin, scheme, host, port, method, path, media type, redirect policy, or header; no connection string, secret reference, or authentication kind; and no network path at all. Every rewritten claim is anchored to those contracts, to bundle.schema.yaml, or to the runtime code that enforces it. Left alone, because HTTP is genuinely correct there: consuming a Relay-served API as a source, the DHIS2 and FHIR examples, source-batch, and the OpenAPI authoring path in evidencectl. Security-sensitive corrections found while re-reading the pages against source: - threat-model: the secret-file bullet claimed mode exactly 0600. The code accepts 0400 or 0600 (validate_file_metadata in crates/registry-platform-config/src/secrets.rs). An operator reading the old text would expect a 0400 secret to be refused. - threat-model: V1-I30 was stated as "every native audit event records the closed response-protection mode". The matrix scopes that to authorized-material events; the minimal authorization-refusal event records neither field. The old text overstated audit completeness. - threat-model: V1-I21 signed-JWS availability is scoped to grants issuing under the audience-scoped subject binding, not to every authorized grant. - threat-model: a cited test, file_secret_uses_open_file_owner_and_exact_mode _checks, does not exist. Replaced with the real file_secret_accepts_only_owner_read_and_optional_owner_write_modes. - trusted-context-constraints: the page said Version 1 has no source freshness family at all. A statement source must declare maximumExtractAgeSeconds, and the runtime compares it against the extract's published-at instant before any row is read, failing as DependencyUnavailable. The section heading now says "record freshness", which is the claim that still holds. - diagram: the arrow label read "one fixed HTTP request per evaluation". The ceiling is one request per acquisition stage; search-then-fetch-set runs up to five stages, so the old label was wrong on both transports. - diagram: "only Evidence Gateway holds a source credential" now reads "ever holds", since a statement source holds none. Twelve drifted path:line-range citations were repointed to the symbol names they name, which do not drift. No production code changes. Verified from docs/site: npm run check (exit 0, Vale 0 errors 0 warnings, astro check 0 errors 0 warnings) and npm test (364 pass, 0 fail). The redrawn SVG was rendered with resvg against the installed Public Sans and IBM Plex Mono and measured: rightmost ink at x=677.5 in a 720-wide viewBox, no collisions. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #796, addressing the three items left open there.
What changed
1. Fix the HTTP-only Evidence source framing (Codex P2 on #796).
architecture.mdxandboundaries-and-map.mdxpresented a fixed HTTP JSONrequest as the only way an Evidence source reaches its data. The frozen
contract set carries two coequal transports:
registry.evidence.fixed-http-json-source/v1(products/evidence/contracts/source-contract.yaml)registry.evidence.fixed-sqlite-extract-source/v1(products/evidence/contracts/sqlite-extract-source-contract.yaml)selected by the closed
http-jsonandsqlite-extractvariants undersourceinbundle.schema.yaml, with the runtime binding each logicalextractProfilename to a process-local path undersourceExtractsinruntime.schema.yaml.Both are now described on the architecture page (prose, "Data and contract
flow" step 6, and the diagram alt text), in the diagram's
<desc>, and in theEvidence "source access as a general capability" boundary. Every new claim is
anchored in the frozen contract that carries it.
2. Address the remaining
TODO[evidence]inarchitecture.mdx.The TODO said the Solmara Lab source mapping could not be anchored from this
repository, so the claim was weakened to "some requirements". That
configuration is citable now from the pinned
solmara-labcommit alreadylinked in
src/data/projects.yaml, so the page states which cells use whichtransport and the TODO is gone. Verified against
evidence/cells/*/bundle/evidence.yamlat3d5c492ea50c6fdcefd5978df6f036422096421c: MoSD, NAgDI, and SIPF areHTTP-only; NIA and SRO are extract-only; CRA uses both.
3. Bump
last_reviewedon both pages.Per
docs/site/docs/style-guide.md:201, that bump means the page was readagainst source. Doing that reading turned up four things the bump obliged me
to fix rather than certify:
contract.rs:1062-1079(RelayRuntime) had drifted to 1235contract.rs:323-325(SourceProfile) had drifted to 373problem.rs:14-45pointed at a re-export; the closed set isdefine_problem_codes!incrates/registry-relay-http-contract/src/lib.rsregistry patterns; there is no health cell, and there are pension and
agriculture cells
The three citations now name the symbol rather than a line range, so they
resist drift.
Not in scope
The HTTP-only Evidence-source framing also appears on ~8 other pages and in
registry-trust-boundaries.svg(which needs a visible label change, not justa
<desc>edit). Those touch a spec page and the threat model, so they areleft for a separate change with the review notes they need.
Verification
From
docs/site/:npm run check(exit 0),npm run build(125 pages),npm test(364 pass, 0 fail).