Skip to main content

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;