Skip to content

Four Evidence documentation claims do not match the runtime #810

Description

@jeremi

Four documentation claims in the Evidence explanation pages do not match the
runtime. All four were raised by automated review on #806 and all four verify
against the source. They are recorded here rather than fixed in that PR, because
#806 is a byte-identical re-land of #799 and two of the four sit in files that
already conflict with #802; editing them there would compound that conflict for
no gain. None is a regression introduced by #806. All four predate it.

1. The trust-boundaries diagram marks an unauthenticated path as an authenticated edge

docs/site/public/images/registry-trust-boundaries.svg

The <desc> states "Dashed rules mark authenticated service edges", and
threat-model.mdx repeats it in the image alt. The Evidence-to-source
boundary is drawn in the dashed group (stroke-dasharray="6 4", the
SERVICE EDGE labels), but that boundary carries the statement transport as
well as HTTP. The same <desc> says a statement source has "no origin, no
credential, and no network hop".

So the diagram presents a local read-only file read as an authenticated service
boundary. Either give the source boundary a distinct marker, or split the HTTP
and statement paths.

2. Transport mixing is stated without the fixture-gate limitation

docs/site/src/content/docs/explanation/trusted-context-constraints.mdx:119

The prose restates transport_mixing from
products/evidence/contracts/sqlite-extract-source-contract.yaml: an
acquisition kind places no constraint on which transport a stage uses. True of
the serving runtime. But fixture_status in the same contract says:

The current offline evaluator executes a SQLite statement only when it is the
initial source and refuses a later SQLite stage. It therefore cannot prove
every transport order, and such a project cannot pass the supported
production/evidence-grade build journey even though the serving runtime
accepts the configuration.

A reader designing an HTTP-to-SQLite or SQLite-to-SQLite acquisition follows the
documented capability and discovers the blocker at build time. State the tooling
limitation next to the transport-mixing claim.

3. The extract age bound is publisher-asserted, not an objective freshness guarantee

docs/site/src/content/docs/explanation/trusted-context-constraints.mdx:150

extract_age_within_bound (crates/registry-evidence/src/source_sqlite.rs:201)
computes:

let age = (evaluation_instant - metadata.published_at).num_seconds();

Two consequences. The value comes from extract metadata, not the file's
mtime or any independent observation. And a publishedAt after the evaluation
instant yields a negative age, which can never exceed the bound, so a
future-dated extract always passes however old the file actually is.

The check bounds the lag a publisher claims. It does not bound how stale the
file may be. The text should not present it as a freshness guarantee.

4. The local unauthenticated HTTP source description omits the explicit-port requirement

docs/site/src/content/docs/explanation/integration-patterns.mdx:252

For authentication.kind: none, choosing a numeric loopback origin is not
sufficient. validate_local_unauthenticated_source_origin
(crates/registry-evidence/src/config.rs:4647) builds a canonical form and
requires an exact match:

let canonical = format!("http://{ip}:{port}");
if url.scheme() != "http" || value != canonical { /* rejected */ }

http://127.0.0.1 is rejected, because port_or_known_default() supplies 80
and the canonical form is then http://127.0.0.1:80, which the literal value
does not equal. State the explicit non-zero port and canonical-spelling
requirements.

Note

Items 3 and 4 describe security-relevant behaviour: a freshness control that is
weaker than documented, and a validation rule stricter than documented. Item 3
is the one worth prioritising, since a reader may be relying on the documented
guarantee.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions