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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
//! Pieces shared by Card, Eval and Run: producer, attachments, relations, `ext`.
//!
//! # Producer
//!
//! `producer { name, version }` identifies the software that wrote the
//! record. It is informational and is not a facet: two harnesses can produce
//! comparable records, and one harness can produce incomparable ones.
//!
//! # Attachments
//!
//! ```text
//! attachments[] { path, sha256, size, media_type }
//! ```
//!
//! An attachment is a file in object storage, addressed by its sha256. The
//! record refers to it by `path`, a relative, `..`-free, unique-within-record
//! name that other fields (a Card's `results[].samples_ref`, a run's
//! `calls`, `artifacts[]` and `error.log`) point at. A run has its own
//! `attachments[]` and its pointers name paths there, not in the Eval
//! header's (see `crate::run`). The hub checks that referenced paths
//! exist in `attachments[]` and that every `sha256` has been uploaded and
//! confirmed (see `evalhub_store::objects`); it does not open the file.
//! `media_type` is a hint for display and download, nothing more.
//!
//! Content addressing means two records attaching the same file share one
//! object, and a record cannot be published against an object that does not
//! exist. It also means the record commits to the exact bytes: a different
//! file is a different sha256 and therefore a different record.
//!
//! # Relations
//!
//! ```text
//! relations[] { type, to, attrs }
//! ```
//!
//! `type` is a registry id (`core/uses_eval`, `core/retry_of`, …). `to` is a
//! pinned reference, `{ns}/{name}@{seq}`, which the hub resolves to a
//! `version_id` on ingest; an unresolvable reference is accepted and simply
//! does not earn the `refs_resolved` badge. Targets outside the hub are
//! written `external:https://…` or `hf:org/repo@sha` and stored with no
//! `version_id`. `attrs` is free-form per relation type.
//!
//! For `core/uses_eval`, `attrs.runs` is a list of `run_id`s: the runs of
//! the cited Eval this Card used. It feeds the Card's *used set*: per Eval
//! record, the union of `attrs.runs` over the Card's `core/uses_eval`
//! relations resolved to that record, or, when none of them carries
//! `attrs.runs`, every run of that record that is neither archived nor
//! deleted when the Card is posted. The used set bounds the Card's
//! `run_results` and is defined in full in `crate::card` ("The used set").
//! `attrs.runs` names runs of the *record*, not of the pinned version:
//! runs are not versioned with the Eval header.
//!
//! Relations are edges between *versions*. Publishing a new version of a
//! Card does not move its edges; a reader who wants "the latest Card that
//! used this Eval" asks the API with `follow_latest=true`.
//!
//! # `ext`
//!
//! The one open door. `ext` is a map from namespace (`{ns}/{name}`) to an
//! arbitrary JSON object. Namespacing is mandatory so that two producers'
//! extensions cannot collide, and so that a namespace can later register an
//! `ext_schema` to make its keys typed and indexable. Until it does, `ext`
//! values can be searched with `eq` and `exists` only. The hub checks the
//! key form on every write, at the top level and inside each facet, and
//! refuses a key that is not `{ns}/{name}` with `ext_key_invalid`
//! (`evalhub_core::validate`); the values are not looked into.
use BTreeMap;
use JsonSchema;
use ;
/// Producer-private extensions, keyed by namespace (`{ns}/{name}`). Each value
/// is an arbitrary JSON object owned by that namespace.
pub type Ext = ;
/// Free-form attributes carried by a relation, keyed by attribute name.
pub type Attrs = Map;
/// True when an extension map is empty; used to omit it on output.
pub
/// The software that wrote the record. Informational; not a facet.
/// A file in object storage that the record refers to by `path`.
/// An edge from this version to another record version or an external target.
/// The producer's statement about what it removed before publishing.