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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
//! HOW an artifact family's addresses END — the `extension` word's six forms, as a model.
//!
//! A blob's address is `<slot>/<seg1>/…/<segN>[.<ext>]`, and the suffix is the one part of it that
//! does not come from the key. It exists for browsability — a human opening the store's directory
//! sees `12.png` rather than `12` — and for the hosts that read a type off a name.
//!
//! # Six forms, four keys, and why the count is what it is
//!
//! ```text
//! extension = "png" static
//! (omitted) extensionless
//! extension(from = "format", any_of = ["png", "jpg"]) a String column, output-fenced
//! extension(from(field = "format", type = "app::Format")) an enum column, full set
//! extension(from(…), variants = ["app::Format::Png", …]) an enum column, a subset
//! extension(from(…), with = "app::suffix_of") the author's own render
//! ```
//!
//! Two spellings were REFUSED in the design and are refused by the parser: a bare array
//! (`extension = ["png", "jpg"]`) cannot answer *which one is entry 42*, so a family with several
//! suffixes has to say what decides; and the parenthesized single value (`extension("png")`) is a
//! single fact, which this grammar writes as a key-value everywhere else.
//!
//! # The two fences point in opposite directions, which is why there are two words
//!
//! [`variants`](ColumnExtension::variants) is an INPUT fence — WHICH values of the column are
//! admitted — and only the enum road has one, a subset of a type's variants being the only input set
//! this grammar can name. [`any_of`](ColumnExtension::any_of) is an OUTPUT fence — which SUFFIXES may
//! be produced — and it is REQUIRED on the string road, where nothing else bounds what a column
//! holds. On the enum road the full variant set already fences the input by construction, so
//! `any_of` there is an extra promise about the rendering rather than the only one there is.
//!
//! Both compose with [`with`](ColumnExtension::with), which is the whole reason they are separate
//! words: a hook takes the column value (fenced by `variants`) and returns a suffix (fenced by
//! `any_of`).
//!
//! # The column is the ENTITY's, and it is a PURE INPUT
//!
//! `from` names a column the locate-field resolver already holds hydrated — `self` — so a dynamic
//! suffix costs no round trip and the zero-I/O pin on `locate` survives intact. What it does NOT
//! survive on its own is the WRITE side: the lane renders the stored name from
//! `upstream(…, extension = "<upstream field>")`, and the framework cannot prove at read time that the
//! two are the same source. That seam is documented law with three mitigations, one of which — a
//! framework-written materialization that is same-source by construction — is reserved and not built.
use crateNodeKind;
/// WHICH column an artifact family reads its suffix out of, and how the column's type is known.
///
/// The type is EXPLICIT on the enum road and absent on the string road, and that asymmetry is the
/// key-即-意图 rule rather than an inference the emitter declined to write: `from = "…"` MEANS a
/// string column, `from(…)` means a column whose type is named. Reading a label tree to guess which
/// one an author meant would make the same two spellings mean different things in different
/// declarations.
/// A suffix decided PER ENTRY — the block form, in all four of its shapes.
/// HOW this artifact family's addresses end.
///
/// [`Option<Extension>`] is the whole vocabulary: `None` is the omitted form — extensionless
/// storage, the zero-tax road a heterogeneous family takes, where a per-entry type travels as
/// metadata or as the host channel's `Content-Type` instead.
/// Whether `suffix` can be the tail of an address at all.
///
/// # A FLOOR rather than a charset, and the difference is deliberate
///
/// What this refuses is what no host can hold: the empty string, a path separator of either family,
/// a NUL, and the two directory names `.` and `..`. Each of those makes the ADDRESS malformed rather
/// than merely ugly — a separator invents a directory level the key never declared, and `..` invents
/// one above the store's own root.
///
/// It does NOT impose the filesystem backend's verbatim charset. That charset decides which
/// rendering a KEY SEGMENT gets — verbatim or escaped — and a segment is never refused for failing
/// it. A suffix has no escape hatch, so a charset here would be a refusal rather than a routing, and
/// which characters an artifact family may end its names with is a question every backend answers
/// differently (an object store's key alphabet is not a filesystem's). The narrow question is
/// settled; the wide one waits for a ruling.
/// The word itself, spelled once.
pub const EXTENSION: &str = "extension";
/// What an author who wrote `extension` on the wrong kind is told.