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