1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
//! The domain rules of evalhub: what a record must satisfy, what the hub
//! derives from it, and nothing that touches a database or a socket.
//!
//! This crate is pure. Every function takes a value and returns a value. It
//! knows the record types from [`evalhub_schema`] and it knows the rules in
//! the design; it does not know that Postgres exists. That boundary is what
//! makes the rules testable from fixtures alone (steps 1–3 of the build plan
//! run with no database) and what keeps the store from growing opinions
//! about records.
//!
//! # What the hub derives from a record
//!
//! On `POST`, the server calls into this crate in this order:
//!
//! ```text
//! bytes ──▶ validate::structural JSON Schema (closed core), 2^53 check
//! ──▶ validate::semantic counts, attachment paths, metric id form
//! ──▶ canonical::canonicalize RFC 8785 bytes ──▶ content_hash (sha256)
//! ──▶ fingerprint::of_record seven sha256s, one per facet
//! ──▶ badge::compute refs_resolved? harness_registered? env_pinned? redacted?
//! ──▶ (store) one transaction
//! ```
//!
//! All validation errors are collected, not short-circuited, and returned as
//! one `422 { errors[] }` (see `evalhub_schema::error`). The record that
//! reaches the store is the client's bytes, canonicalised; the hub adds
//! facts around it and never rewrites it.
//!
//! # Invariants this crate is responsible for
//!
//! - **Canonical form is total and deterministic.** The same JSON value, in
//! any key order and any whitespace, canonicalises to the same bytes, and
//! therefore the same `content_hash`. This is what makes `POST` idempotent:
//! the store compares the new hash with the latest version's and returns
//! `200` with the existing version if they match.
//! - **A fingerprint depends only on the facet's core keys.** `ext` and keys
//! marked `x-fingerprint: false` in the schema are removed before hashing.
//! The exclusion is read from the schema, so the schema is the single
//! source for what "the same conditions" means.
//! - **Validation is the same everywhere.** The server, a future CLI
//! `evalhub check`, and a harness embedding this crate all reject the same
//! records for the same codes.
//!
//! # What this crate refuses to do
//!
//! - It does not open attachments. `samples_ref` must name an entry in
//! `attachments[]`; whether the file has the rows it claims is not checked
//! (design decision: content validation is out of scope for v0 and, when
//! it comes, it is a separate job, not part of ingest).
//! - It does not decide whether two records are "the same evaluation". It
//! produces per-facet fingerprints; the reader compares them.
//! - It does not resolve relations. Resolution needs the store; this crate
//! only checks the *form* of a reference and reports, via the badge input,
//! whether the store said it resolved.
//!
//! # Modules
//!
//! - [`canonical`] — RFC 8785 serialisation and the content hash.
//! - [`fingerprint`] — per-facet hashing with schema-driven exclusion.
//! - [`mod@validate`] — structural and semantic checks, error collection.
//! - [`badge`] — the badge rules and their inputs.
//! - [`registry`] — the `core/` registry entries (metrics, relation types)
//! that ship with the hub and are read-only.
//! - [`id`] — ULID generation and the version identifier.
pub use ;
pub use ;
pub use ;
pub use ;
pub use validate;