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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
//! The persistence contract every fitted type declares by implementing it.
//!
//! # Why persistence is a trait rather than an inherent method
//!
//! A fitted type used to declare persistence *twice*: once by writing an
//! inherent `to_artifact`, and again by being added to a hand-maintained list
//! of composition members. Because the second declaration was a separate act of
//! remembering, seven estimators shipped a working, fuzz-tested encoder and were
//! still invisible to the type system — and every composition ending in one of
//! them fell out of the conformance battery, because the battery reaches a
//! composition through its capability declaration and that declaration was
//! gated on the list.
//!
//! Implementing one of the traits below *is* writing the encoder, so the two
//! declarations became one. A new estimator that persists cannot be silently
//! unpersistable, because there is no second place left to omit it from. This
//! follows the rule `crate::api` already states: a concrete method stays
//! inherent until its shape semantics are shared by every implementation, and
//! fourteen estimators sharing one signature exactly is that condition being
//! met.
//!
//! # Two arities, because there are two kinds of schema binding
//!
//! A final estimator is bound to the features it was fitted on: one schema.
//! Anything that *transforms* is bound to what it consumed and what it produced:
//! two schemas. Those are the only two shapes in the crate, and they are the
//! two traits here.
//!
//! # Kinds, tags, and why they are separate numbers
//!
//! [`ModelArtifact::ARTIFACT_KIND`] names the type in the on-disk envelope.
//! [`ModelArtifact::MODEL_TAG`] names it inside a *composed* payload. They are
//! different namespaces, and both are permanent: changing either changes what
//! previously written artifacts decode as.
//!
//! The tag therefore *defaults* to the kind, which is already unique and
//! already permanent. A new estimator gets a composition identity for free and
//! has nothing extra to assign — the failure this whole contract exists to
//! prevent.
//!
//! Six types were tagged before that default existed and their tags do not
//! equal their kinds. Rather than have those six override the default — six
//! chances to write the wrong number, in six files, forever — the exceptions
//! live in the two closed tables below, beside the kinds they translate. No
//! estimator anywhere declares a tag. The tables cannot grow: a type whose tag
//! already equals its kind needs no entry, and every future type gets the
//! default. `tests/artifact_tags.rs` pins every resulting tag by number, and
//! the adversarial corpus records two of the six as frozen bytes.
use ArtifactError;
use ;
/// Composition tags assigned to final estimators before the tag defaulted to
/// the kind. Closed: every other estimator's tag *is* its kind.
const LEGACY_MODEL_TAGS: = ;
/// Composition tags assigned to transform stages before the same default.
/// Closed for the same reason.
const LEGACY_STAGE_TAGS: = ;
const
/// The composition tag a final estimator of this kind carries.
pub const
/// The composition tag a transform stage of this kind carries.
pub const
/// A fitted estimator that persists against the features it was fitted on.
///
/// Implementing this is the *whole* declaration: it supplies the encoder, the
/// envelope identity, and the composition identity together, so none of the
/// three can be present without the others.
///
/// A type implementing this must also declare
/// [`Capabilities::artifact`](crate::api::Capabilities::artifact), and a type
/// declaring that capability must implement this. Neither direction is left to
/// convention — `tests/capability_snapshot.rs` closes them against each other,
/// and `scripts/check_source_layout.py` refuses the inherent form this contract
/// replaced.
/// A fitted type that persists against both an input and an output schema.
///
/// This covers transform stages and the compositions built from them: both
/// consume one feature schema and produce another, and both must refuse bytes
/// written against a different pair.
///
/// The tag identifies a stage inside a composed payload, and carries the same
/// permanence and the same default as [`ModelArtifact::MODEL_TAG`]. A
/// composition implements this too — it is schema-bound in exactly the same
/// shape a stage is — and simply never appears in another payload's tag list.