@htilabs/platform-common-models 0.2.0-beta.4 → 0.3.0-beta.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +38 -0
- package/dist/constants/index.cjs +0 -843
- package/dist/constants/index.cjs.map +1 -1
- package/dist/constants/index.d.cts +146 -5
- package/dist/constants/index.d.ts +146 -5
- package/dist/constants/index.js +0 -786
- package/dist/constants/index.js.map +1 -1
- package/dist/{platform-role-AHv1l5Og.d.cts → cvcEntry-wqktWfzE.d.cts} +231 -37
- package/dist/{platform-role-AHv1l5Og.d.ts → cvcEntry-wqktWfzE.d.ts} +231 -37
- package/dist/cvcs/index.cjs +2184 -0
- package/dist/cvcs/index.cjs.map +1 -0
- package/dist/cvcs/index.d.cts +2384 -0
- package/dist/cvcs/index.d.ts +2384 -0
- package/dist/cvcs/index.js +2154 -0
- package/dist/cvcs/index.js.map +1 -0
- package/dist/index--NCIPluF.d.cts +378 -0
- package/dist/index-CFOrHA8l.d.ts +378 -0
- package/dist/index.cjs +2962 -843
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +217 -3
- package/dist/index.d.ts +217 -3
- package/dist/index.js +2934 -786
- package/dist/index.js.map +1 -1
- package/dist/models/index.cjs +211 -0
- package/dist/models/index.cjs.map +1 -1
- package/dist/models/index.d.cts +3 -292
- package/dist/models/index.d.ts +3 -292
- package/dist/models/index.js +209 -0
- package/dist/models/index.js.map +1 -1
- package/dist/{platform-auth-BTbQIY3b.d.cts → platform-auth-C-G2qeGM.d.cts} +1 -297
- package/dist/{platform-auth-BTbQIY3b.d.ts → platform-auth-C-G2qeGM.d.ts} +1 -297
- package/dist/schemas/index.cjs +195 -729
- package/dist/schemas/index.cjs.map +1 -1
- package/dist/schemas/index.d.cts +11 -11
- package/dist/schemas/index.d.ts +11 -11
- package/dist/schemas/index.js +189 -729
- package/dist/schemas/index.js.map +1 -1
- package/dist/services/index.cjs +1442 -0
- package/dist/services/index.cjs.map +1 -0
- package/dist/services/index.d.cts +305 -0
- package/dist/services/index.d.ts +305 -0
- package/dist/services/index.js +1417 -0
- package/dist/services/index.js.map +1 -0
- package/dist/types/index.d.cts +2 -2
- package/dist/types/index.d.ts +2 -2
- package/dist/validation/index.cjs +261 -0
- package/dist/validation/index.cjs.map +1 -0
- package/dist/validation/index.d.cts +251 -0
- package/dist/validation/index.d.ts +251 -0
- package/dist/validation/index.js +228 -0
- package/dist/validation/index.js.map +1 -0
- package/package.json +36 -12
- package/src/__tests__/__snapshots__/cvc-sot.snap +22 -0
- package/src/__tests__/cvc-sot-snapshot.test.ts +184 -0
- package/src/__tests__/cvc-structural.test.ts +130 -0
- package/src/constants/ic.ts +0 -925
- package/src/constants/service-catalog.ts +146 -4
- package/src/cvcs/index.ts +31 -0
- package/src/cvcs/missingness.v1.0.0.json +50 -0
- package/src/cvcs/serviceCategories.v1.0.0.json +1947 -0
- package/src/cvcs/serviceMechanisms.v1.0.0.json +47 -0
- package/src/cvcs/serviceStates.v1.0.0.json +106 -0
- package/src/generated/cvc-enums.ts +215 -0
- package/src/index.ts +61 -1
- package/src/models/cvcEntryModel.ts +32 -0
- package/src/models/cvcRegistryModel.ts +35 -0
- package/src/models/index.ts +8 -0
- package/src/schemas/cvcEntry.ts +158 -0
- package/src/schemas/cvcRegistry.ts +149 -0
- package/src/schemas/index.ts +16 -0
- package/src/services/__tests__/cvcRegistryService.test.ts +614 -0
- package/src/services/cvcRegistryService.ts +729 -0
- package/src/services/index.ts +21 -0
- package/src/validation/cvc.ts +414 -0
- package/src/validation/index.ts +15 -0
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* @htilabs/platform-common-models — Controlled Vocabulary (CVC) Validation
|
|
5
|
+
*
|
|
6
|
+
* Zod schemas for validating CVC Source-of-Truth (SOT) JSON files and
|
|
7
|
+
* individual CVC entries. Implements the locked spec §9.2 shapes.
|
|
8
|
+
*
|
|
9
|
+
* Used by:
|
|
10
|
+
* - CI structural tests that parse every committed SOT file.
|
|
11
|
+
* - The generalized seed CLI (`seedCvc`) prior to persistence.
|
|
12
|
+
* - Downstream consumers that need to validate CVC payloads.
|
|
13
|
+
*
|
|
14
|
+
* Canonical spec:
|
|
15
|
+
* /gt/docs/data/cvcs/CVC Implementation Spec 2780449faf8045258c67daab0f1c5569.md
|
|
16
|
+
*
|
|
17
|
+
* Locked decisions (2026-04-10):
|
|
18
|
+
* - Positional 7-segment codes `XX-XX-XX-XX-XX-XX-XX` (§3).
|
|
19
|
+
* - `missingness` envelope field is an optional `string[]`; `["all"]` is the
|
|
20
|
+
* sentinel meaning "merge all missingness values" (§2.1, §5.2).
|
|
21
|
+
* - `missingness.v1.0.0.json` wraps its values under a synthetic root
|
|
22
|
+
* (`missingness_root`) which is the one sanctioned parent-child exception
|
|
23
|
+
* for level-consistency, scoped by segment-1 domain prefix (§5.1).
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* 7-segment positional CVC code: `XX-XX-XX-XX-XX-XX-XX` (two digits per
|
|
28
|
+
* segment). Segments are filled left-to-right as levels deepen; unused
|
|
29
|
+
* segments remain `00`. See locked spec §3.
|
|
30
|
+
*/
|
|
31
|
+
declare const CvcCodeSchema: z.ZodString;
|
|
32
|
+
/**
|
|
33
|
+
* Stable machine key for a CVC entry. Must start with a lowercase letter and
|
|
34
|
+
* contain only lowercase alphanumerics or underscores. Used as a cross-CVC
|
|
35
|
+
* reference target (e.g. `relevantMechanisms` pointing at mechanism keys).
|
|
36
|
+
* See locked spec §3.2.
|
|
37
|
+
*/
|
|
38
|
+
declare const CvcKeySchema: z.ZodString;
|
|
39
|
+
/**
|
|
40
|
+
* Base entry shape shared by every CVC domain. Domain-specific extensions
|
|
41
|
+
* (e.g. `ServiceCategoryEntrySchema`) should use `.extend()` to add fields.
|
|
42
|
+
* See locked spec §9.2.
|
|
43
|
+
*
|
|
44
|
+
* Uses `.passthrough()` so that domain-specific fields (like
|
|
45
|
+
* `relevantMechanisms` on service-category entries) survive base parsing
|
|
46
|
+
* unmodified. This keeps cross-CVC reference validation honest: the §4.5
|
|
47
|
+
* structural validator needs to see the raw referenced keys, and a strip-by-
|
|
48
|
+
* default schema would silently hide them.
|
|
49
|
+
*/
|
|
50
|
+
declare const CvcEntrySchema: z.ZodObject<{
|
|
51
|
+
code: z.ZodString;
|
|
52
|
+
key: z.ZodString;
|
|
53
|
+
title: z.ZodString;
|
|
54
|
+
selectable: z.ZodBoolean;
|
|
55
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
56
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
57
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
58
|
+
}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
|
|
59
|
+
code: z.ZodString;
|
|
60
|
+
key: z.ZodString;
|
|
61
|
+
title: z.ZodString;
|
|
62
|
+
selectable: z.ZodBoolean;
|
|
63
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
64
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
65
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
66
|
+
}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
|
|
67
|
+
code: z.ZodString;
|
|
68
|
+
key: z.ZodString;
|
|
69
|
+
title: z.ZodString;
|
|
70
|
+
selectable: z.ZodBoolean;
|
|
71
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
72
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
73
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
74
|
+
}, z.ZodTypeAny, "passthrough">>;
|
|
75
|
+
/**
|
|
76
|
+
* Service-category-specific entry. Adds `relevantMechanisms` — a cross-CVC
|
|
77
|
+
* reference into the `service_mechanisms` domain via entry keys. `null` means
|
|
78
|
+
* "not applicable" (e.g. structural L1 topic rows). See locked spec §9.2.
|
|
79
|
+
*/
|
|
80
|
+
declare const ServiceCategoryEntrySchema: z.ZodObject<{
|
|
81
|
+
code: z.ZodString;
|
|
82
|
+
key: z.ZodString;
|
|
83
|
+
title: z.ZodString;
|
|
84
|
+
selectable: z.ZodBoolean;
|
|
85
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
86
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
87
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
88
|
+
} & {
|
|
89
|
+
relevantMechanisms: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
|
|
90
|
+
}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
|
|
91
|
+
code: z.ZodString;
|
|
92
|
+
key: z.ZodString;
|
|
93
|
+
title: z.ZodString;
|
|
94
|
+
selectable: z.ZodBoolean;
|
|
95
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
96
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
97
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
98
|
+
} & {
|
|
99
|
+
relevantMechanisms: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
|
|
100
|
+
}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
|
|
101
|
+
code: z.ZodString;
|
|
102
|
+
key: z.ZodString;
|
|
103
|
+
title: z.ZodString;
|
|
104
|
+
selectable: z.ZodBoolean;
|
|
105
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
106
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
107
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
108
|
+
} & {
|
|
109
|
+
relevantMechanisms: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
|
|
110
|
+
}, z.ZodTypeAny, "passthrough">>;
|
|
111
|
+
/**
|
|
112
|
+
* Top-level SOT JSON envelope. One envelope per (domain, version) pair.
|
|
113
|
+
*
|
|
114
|
+
* `missingness` is an optional array of missingness keys to merge into this
|
|
115
|
+
* CVC at seed time. `["all"]` is the sentinel meaning "merge the missingness
|
|
116
|
+
* root plus all three value entries". Individual keys merge only those.
|
|
117
|
+
* Absent, empty, or null means "skip missingness merge". The missingness CVC
|
|
118
|
+
* file itself omits this field because merging missingness into itself is
|
|
119
|
+
* nonsensical. See locked spec §2.1 and §5.2.
|
|
120
|
+
*
|
|
121
|
+
* `levels` is a positional map from level number (`"0"`, `"1"`, …) to a human
|
|
122
|
+
* label describing the level.
|
|
123
|
+
*/
|
|
124
|
+
declare const CvcEnvelopeSchema: z.ZodObject<{
|
|
125
|
+
domain: z.ZodString;
|
|
126
|
+
name: z.ZodString;
|
|
127
|
+
version: z.ZodString;
|
|
128
|
+
missingness: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
|
|
129
|
+
levels: z.ZodRecord<z.ZodString, z.ZodString>;
|
|
130
|
+
entries: z.ZodArray<z.ZodObject<{
|
|
131
|
+
code: z.ZodString;
|
|
132
|
+
key: z.ZodString;
|
|
133
|
+
title: z.ZodString;
|
|
134
|
+
selectable: z.ZodBoolean;
|
|
135
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
136
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
137
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
138
|
+
}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
|
|
139
|
+
code: z.ZodString;
|
|
140
|
+
key: z.ZodString;
|
|
141
|
+
title: z.ZodString;
|
|
142
|
+
selectable: z.ZodBoolean;
|
|
143
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
144
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
145
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
146
|
+
}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
|
|
147
|
+
code: z.ZodString;
|
|
148
|
+
key: z.ZodString;
|
|
149
|
+
title: z.ZodString;
|
|
150
|
+
selectable: z.ZodBoolean;
|
|
151
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
152
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
153
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
154
|
+
}, z.ZodTypeAny, "passthrough">>, "many">;
|
|
155
|
+
}, "strip", z.ZodTypeAny, {
|
|
156
|
+
name: string;
|
|
157
|
+
version: string;
|
|
158
|
+
entries: z.objectOutputType<{
|
|
159
|
+
code: z.ZodString;
|
|
160
|
+
key: z.ZodString;
|
|
161
|
+
title: z.ZodString;
|
|
162
|
+
selectable: z.ZodBoolean;
|
|
163
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
164
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
165
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
166
|
+
}, z.ZodTypeAny, "passthrough">[];
|
|
167
|
+
domain: string;
|
|
168
|
+
levels: Record<string, string>;
|
|
169
|
+
missingness?: string[] | undefined;
|
|
170
|
+
}, {
|
|
171
|
+
name: string;
|
|
172
|
+
version: string;
|
|
173
|
+
entries: z.objectInputType<{
|
|
174
|
+
code: z.ZodString;
|
|
175
|
+
key: z.ZodString;
|
|
176
|
+
title: z.ZodString;
|
|
177
|
+
selectable: z.ZodBoolean;
|
|
178
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
179
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
180
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
181
|
+
}, z.ZodTypeAny, "passthrough">[];
|
|
182
|
+
domain: string;
|
|
183
|
+
levels: Record<string, string>;
|
|
184
|
+
missingness?: string[] | undefined;
|
|
185
|
+
}>;
|
|
186
|
+
type CvcCode = z.infer<typeof CvcCodeSchema>;
|
|
187
|
+
type CvcKey = z.infer<typeof CvcKeySchema>;
|
|
188
|
+
type CvcEntry = z.infer<typeof CvcEntrySchema>;
|
|
189
|
+
type ServiceCategoryEntry = z.infer<typeof ServiceCategoryEntrySchema>;
|
|
190
|
+
type CvcEnvelope = z.infer<typeof CvcEnvelopeSchema>;
|
|
191
|
+
/**
|
|
192
|
+
* SOT family identifier (e.g. `"service_categories"`, `"service_states"`,
|
|
193
|
+
* `"service_mechanisms"`, `"missingness"`). The canonical list of domains is
|
|
194
|
+
* enumerated by the SOT JSON files in `src/cvcs/`. Typed as `string` rather
|
|
195
|
+
* than a closed union so adding a new SOT file does not require touching this
|
|
196
|
+
* type. See locked spec §2.
|
|
197
|
+
*/
|
|
198
|
+
type CvcDomain = string;
|
|
199
|
+
/**
|
|
200
|
+
* Derive an entry's level from its 7-segment code per locked spec §3.3.
|
|
201
|
+
*
|
|
202
|
+
* - Segment 7 non-zero → level 0 (missingness value entry, e.g. `unknown`).
|
|
203
|
+
* - Otherwise return the index (1..5) of the last non-zero hierarchy segment.
|
|
204
|
+
* - All segments zero → level 0 (missingness root, `00-00-00-00-00-00-00`).
|
|
205
|
+
*/
|
|
206
|
+
declare function getCvcLevel(code: string): number;
|
|
207
|
+
/**
|
|
208
|
+
* Error collected by {@link validateCvc}. Each error names the invariant it
|
|
209
|
+
* violates (`C1`..`C8`) so CI output points straight at the locked spec rule
|
|
210
|
+
* that failed. `code` or `key` narrow the error to a specific entry when the
|
|
211
|
+
* violation is entry-scoped.
|
|
212
|
+
*/
|
|
213
|
+
interface CvcValidationError {
|
|
214
|
+
invariant: "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8";
|
|
215
|
+
message: string;
|
|
216
|
+
code?: string;
|
|
217
|
+
key?: string;
|
|
218
|
+
}
|
|
219
|
+
/**
|
|
220
|
+
* Structural invariants to enforce on every committed SOT file per locked spec
|
|
221
|
+
* §4. Zod's schema `parse()` guarantees the *shape* of the envelope; this
|
|
222
|
+
* function enforces the cross-entry *semantics* that Zod cannot express.
|
|
223
|
+
*
|
|
224
|
+
* Invariants (locked spec §4):
|
|
225
|
+
* - **C1** Code format + uniqueness (§4.1).
|
|
226
|
+
* - **C2** Key format + uniqueness (§4.2).
|
|
227
|
+
* - **C3** Tree: every `parentCode` resolves to an existing entry or null; no
|
|
228
|
+
* cycles (§4.3).
|
|
229
|
+
* - **C4** `childCodes` are the exact bidirectional inverse of `parentCode`
|
|
230
|
+
* (§4.3).
|
|
231
|
+
* - **C5** Selectability is a boolean (§4.4).
|
|
232
|
+
* - **C6** Cross-CVC `relevantMechanisms` references resolve against a
|
|
233
|
+
* provided `service_mechanisms` key set (§4.5, §7). Only checked when the
|
|
234
|
+
* caller supplies `options.mechanismKeys`.
|
|
235
|
+
* - **C7** Envelope has all 6 required fields (`domain`, `name`, `version`,
|
|
236
|
+
* `missingness`, `levels`, `entries`) — treating the optional-in-Zod
|
|
237
|
+
* `missingness` as required at CI time (§4.6).
|
|
238
|
+
* - **C8** No entry anywhere contains a key `'provided'` (legacy Thread UI
|
|
239
|
+
* label guard; not a canonical state).
|
|
240
|
+
*
|
|
241
|
+
* @param envelope Parsed envelope (typically from `CvcEnvelopeSchema.parse()`).
|
|
242
|
+
* @param options.mechanismKeys Optional set of valid `service_mechanisms`
|
|
243
|
+
* entry keys. If provided and the envelope entries have `relevantMechanisms`
|
|
244
|
+
* fields, each referenced key must be in this set (C6).
|
|
245
|
+
* @returns An array of {@link CvcValidationError}. An empty array means valid.
|
|
246
|
+
*/
|
|
247
|
+
declare function validateCvc(envelope: CvcEnvelope, options?: {
|
|
248
|
+
mechanismKeys?: ReadonlySet<string>;
|
|
249
|
+
}): CvcValidationError[];
|
|
250
|
+
|
|
251
|
+
export { type CvcCode, CvcCodeSchema, type CvcDomain, type CvcEntry, CvcEntrySchema, type CvcEnvelope, CvcEnvelopeSchema, type CvcKey, CvcKeySchema, type CvcValidationError, type ServiceCategoryEntry, ServiceCategoryEntrySchema, getCvcLevel, validateCvc };
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* @htilabs/platform-common-models — Controlled Vocabulary (CVC) Validation
|
|
5
|
+
*
|
|
6
|
+
* Zod schemas for validating CVC Source-of-Truth (SOT) JSON files and
|
|
7
|
+
* individual CVC entries. Implements the locked spec §9.2 shapes.
|
|
8
|
+
*
|
|
9
|
+
* Used by:
|
|
10
|
+
* - CI structural tests that parse every committed SOT file.
|
|
11
|
+
* - The generalized seed CLI (`seedCvc`) prior to persistence.
|
|
12
|
+
* - Downstream consumers that need to validate CVC payloads.
|
|
13
|
+
*
|
|
14
|
+
* Canonical spec:
|
|
15
|
+
* /gt/docs/data/cvcs/CVC Implementation Spec 2780449faf8045258c67daab0f1c5569.md
|
|
16
|
+
*
|
|
17
|
+
* Locked decisions (2026-04-10):
|
|
18
|
+
* - Positional 7-segment codes `XX-XX-XX-XX-XX-XX-XX` (§3).
|
|
19
|
+
* - `missingness` envelope field is an optional `string[]`; `["all"]` is the
|
|
20
|
+
* sentinel meaning "merge all missingness values" (§2.1, §5.2).
|
|
21
|
+
* - `missingness.v1.0.0.json` wraps its values under a synthetic root
|
|
22
|
+
* (`missingness_root`) which is the one sanctioned parent-child exception
|
|
23
|
+
* for level-consistency, scoped by segment-1 domain prefix (§5.1).
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* 7-segment positional CVC code: `XX-XX-XX-XX-XX-XX-XX` (two digits per
|
|
28
|
+
* segment). Segments are filled left-to-right as levels deepen; unused
|
|
29
|
+
* segments remain `00`. See locked spec §3.
|
|
30
|
+
*/
|
|
31
|
+
declare const CvcCodeSchema: z.ZodString;
|
|
32
|
+
/**
|
|
33
|
+
* Stable machine key for a CVC entry. Must start with a lowercase letter and
|
|
34
|
+
* contain only lowercase alphanumerics or underscores. Used as a cross-CVC
|
|
35
|
+
* reference target (e.g. `relevantMechanisms` pointing at mechanism keys).
|
|
36
|
+
* See locked spec §3.2.
|
|
37
|
+
*/
|
|
38
|
+
declare const CvcKeySchema: z.ZodString;
|
|
39
|
+
/**
|
|
40
|
+
* Base entry shape shared by every CVC domain. Domain-specific extensions
|
|
41
|
+
* (e.g. `ServiceCategoryEntrySchema`) should use `.extend()` to add fields.
|
|
42
|
+
* See locked spec §9.2.
|
|
43
|
+
*
|
|
44
|
+
* Uses `.passthrough()` so that domain-specific fields (like
|
|
45
|
+
* `relevantMechanisms` on service-category entries) survive base parsing
|
|
46
|
+
* unmodified. This keeps cross-CVC reference validation honest: the §4.5
|
|
47
|
+
* structural validator needs to see the raw referenced keys, and a strip-by-
|
|
48
|
+
* default schema would silently hide them.
|
|
49
|
+
*/
|
|
50
|
+
declare const CvcEntrySchema: z.ZodObject<{
|
|
51
|
+
code: z.ZodString;
|
|
52
|
+
key: z.ZodString;
|
|
53
|
+
title: z.ZodString;
|
|
54
|
+
selectable: z.ZodBoolean;
|
|
55
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
56
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
57
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
58
|
+
}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
|
|
59
|
+
code: z.ZodString;
|
|
60
|
+
key: z.ZodString;
|
|
61
|
+
title: z.ZodString;
|
|
62
|
+
selectable: z.ZodBoolean;
|
|
63
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
64
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
65
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
66
|
+
}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
|
|
67
|
+
code: z.ZodString;
|
|
68
|
+
key: z.ZodString;
|
|
69
|
+
title: z.ZodString;
|
|
70
|
+
selectable: z.ZodBoolean;
|
|
71
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
72
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
73
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
74
|
+
}, z.ZodTypeAny, "passthrough">>;
|
|
75
|
+
/**
|
|
76
|
+
* Service-category-specific entry. Adds `relevantMechanisms` — a cross-CVC
|
|
77
|
+
* reference into the `service_mechanisms` domain via entry keys. `null` means
|
|
78
|
+
* "not applicable" (e.g. structural L1 topic rows). See locked spec §9.2.
|
|
79
|
+
*/
|
|
80
|
+
declare const ServiceCategoryEntrySchema: z.ZodObject<{
|
|
81
|
+
code: z.ZodString;
|
|
82
|
+
key: z.ZodString;
|
|
83
|
+
title: z.ZodString;
|
|
84
|
+
selectable: z.ZodBoolean;
|
|
85
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
86
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
87
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
88
|
+
} & {
|
|
89
|
+
relevantMechanisms: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
|
|
90
|
+
}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
|
|
91
|
+
code: z.ZodString;
|
|
92
|
+
key: z.ZodString;
|
|
93
|
+
title: z.ZodString;
|
|
94
|
+
selectable: z.ZodBoolean;
|
|
95
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
96
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
97
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
98
|
+
} & {
|
|
99
|
+
relevantMechanisms: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
|
|
100
|
+
}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
|
|
101
|
+
code: z.ZodString;
|
|
102
|
+
key: z.ZodString;
|
|
103
|
+
title: z.ZodString;
|
|
104
|
+
selectable: z.ZodBoolean;
|
|
105
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
106
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
107
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
108
|
+
} & {
|
|
109
|
+
relevantMechanisms: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
|
|
110
|
+
}, z.ZodTypeAny, "passthrough">>;
|
|
111
|
+
/**
|
|
112
|
+
* Top-level SOT JSON envelope. One envelope per (domain, version) pair.
|
|
113
|
+
*
|
|
114
|
+
* `missingness` is an optional array of missingness keys to merge into this
|
|
115
|
+
* CVC at seed time. `["all"]` is the sentinel meaning "merge the missingness
|
|
116
|
+
* root plus all three value entries". Individual keys merge only those.
|
|
117
|
+
* Absent, empty, or null means "skip missingness merge". The missingness CVC
|
|
118
|
+
* file itself omits this field because merging missingness into itself is
|
|
119
|
+
* nonsensical. See locked spec §2.1 and §5.2.
|
|
120
|
+
*
|
|
121
|
+
* `levels` is a positional map from level number (`"0"`, `"1"`, …) to a human
|
|
122
|
+
* label describing the level.
|
|
123
|
+
*/
|
|
124
|
+
declare const CvcEnvelopeSchema: z.ZodObject<{
|
|
125
|
+
domain: z.ZodString;
|
|
126
|
+
name: z.ZodString;
|
|
127
|
+
version: z.ZodString;
|
|
128
|
+
missingness: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
|
|
129
|
+
levels: z.ZodRecord<z.ZodString, z.ZodString>;
|
|
130
|
+
entries: z.ZodArray<z.ZodObject<{
|
|
131
|
+
code: z.ZodString;
|
|
132
|
+
key: z.ZodString;
|
|
133
|
+
title: z.ZodString;
|
|
134
|
+
selectable: z.ZodBoolean;
|
|
135
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
136
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
137
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
138
|
+
}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
|
|
139
|
+
code: z.ZodString;
|
|
140
|
+
key: z.ZodString;
|
|
141
|
+
title: z.ZodString;
|
|
142
|
+
selectable: z.ZodBoolean;
|
|
143
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
144
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
145
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
146
|
+
}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
|
|
147
|
+
code: z.ZodString;
|
|
148
|
+
key: z.ZodString;
|
|
149
|
+
title: z.ZodString;
|
|
150
|
+
selectable: z.ZodBoolean;
|
|
151
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
152
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
153
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
154
|
+
}, z.ZodTypeAny, "passthrough">>, "many">;
|
|
155
|
+
}, "strip", z.ZodTypeAny, {
|
|
156
|
+
name: string;
|
|
157
|
+
version: string;
|
|
158
|
+
entries: z.objectOutputType<{
|
|
159
|
+
code: z.ZodString;
|
|
160
|
+
key: z.ZodString;
|
|
161
|
+
title: z.ZodString;
|
|
162
|
+
selectable: z.ZodBoolean;
|
|
163
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
164
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
165
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
166
|
+
}, z.ZodTypeAny, "passthrough">[];
|
|
167
|
+
domain: string;
|
|
168
|
+
levels: Record<string, string>;
|
|
169
|
+
missingness?: string[] | undefined;
|
|
170
|
+
}, {
|
|
171
|
+
name: string;
|
|
172
|
+
version: string;
|
|
173
|
+
entries: z.objectInputType<{
|
|
174
|
+
code: z.ZodString;
|
|
175
|
+
key: z.ZodString;
|
|
176
|
+
title: z.ZodString;
|
|
177
|
+
selectable: z.ZodBoolean;
|
|
178
|
+
parentCode: z.ZodNullable<z.ZodString>;
|
|
179
|
+
childCodes: z.ZodArray<z.ZodString, "many">;
|
|
180
|
+
definition: z.ZodNullable<z.ZodString>;
|
|
181
|
+
}, z.ZodTypeAny, "passthrough">[];
|
|
182
|
+
domain: string;
|
|
183
|
+
levels: Record<string, string>;
|
|
184
|
+
missingness?: string[] | undefined;
|
|
185
|
+
}>;
|
|
186
|
+
type CvcCode = z.infer<typeof CvcCodeSchema>;
|
|
187
|
+
type CvcKey = z.infer<typeof CvcKeySchema>;
|
|
188
|
+
type CvcEntry = z.infer<typeof CvcEntrySchema>;
|
|
189
|
+
type ServiceCategoryEntry = z.infer<typeof ServiceCategoryEntrySchema>;
|
|
190
|
+
type CvcEnvelope = z.infer<typeof CvcEnvelopeSchema>;
|
|
191
|
+
/**
|
|
192
|
+
* SOT family identifier (e.g. `"service_categories"`, `"service_states"`,
|
|
193
|
+
* `"service_mechanisms"`, `"missingness"`). The canonical list of domains is
|
|
194
|
+
* enumerated by the SOT JSON files in `src/cvcs/`. Typed as `string` rather
|
|
195
|
+
* than a closed union so adding a new SOT file does not require touching this
|
|
196
|
+
* type. See locked spec §2.
|
|
197
|
+
*/
|
|
198
|
+
type CvcDomain = string;
|
|
199
|
+
/**
|
|
200
|
+
* Derive an entry's level from its 7-segment code per locked spec §3.3.
|
|
201
|
+
*
|
|
202
|
+
* - Segment 7 non-zero → level 0 (missingness value entry, e.g. `unknown`).
|
|
203
|
+
* - Otherwise return the index (1..5) of the last non-zero hierarchy segment.
|
|
204
|
+
* - All segments zero → level 0 (missingness root, `00-00-00-00-00-00-00`).
|
|
205
|
+
*/
|
|
206
|
+
declare function getCvcLevel(code: string): number;
|
|
207
|
+
/**
|
|
208
|
+
* Error collected by {@link validateCvc}. Each error names the invariant it
|
|
209
|
+
* violates (`C1`..`C8`) so CI output points straight at the locked spec rule
|
|
210
|
+
* that failed. `code` or `key` narrow the error to a specific entry when the
|
|
211
|
+
* violation is entry-scoped.
|
|
212
|
+
*/
|
|
213
|
+
interface CvcValidationError {
|
|
214
|
+
invariant: "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8";
|
|
215
|
+
message: string;
|
|
216
|
+
code?: string;
|
|
217
|
+
key?: string;
|
|
218
|
+
}
|
|
219
|
+
/**
|
|
220
|
+
* Structural invariants to enforce on every committed SOT file per locked spec
|
|
221
|
+
* §4. Zod's schema `parse()` guarantees the *shape* of the envelope; this
|
|
222
|
+
* function enforces the cross-entry *semantics* that Zod cannot express.
|
|
223
|
+
*
|
|
224
|
+
* Invariants (locked spec §4):
|
|
225
|
+
* - **C1** Code format + uniqueness (§4.1).
|
|
226
|
+
* - **C2** Key format + uniqueness (§4.2).
|
|
227
|
+
* - **C3** Tree: every `parentCode` resolves to an existing entry or null; no
|
|
228
|
+
* cycles (§4.3).
|
|
229
|
+
* - **C4** `childCodes` are the exact bidirectional inverse of `parentCode`
|
|
230
|
+
* (§4.3).
|
|
231
|
+
* - **C5** Selectability is a boolean (§4.4).
|
|
232
|
+
* - **C6** Cross-CVC `relevantMechanisms` references resolve against a
|
|
233
|
+
* provided `service_mechanisms` key set (§4.5, §7). Only checked when the
|
|
234
|
+
* caller supplies `options.mechanismKeys`.
|
|
235
|
+
* - **C7** Envelope has all 6 required fields (`domain`, `name`, `version`,
|
|
236
|
+
* `missingness`, `levels`, `entries`) — treating the optional-in-Zod
|
|
237
|
+
* `missingness` as required at CI time (§4.6).
|
|
238
|
+
* - **C8** No entry anywhere contains a key `'provided'` (legacy Thread UI
|
|
239
|
+
* label guard; not a canonical state).
|
|
240
|
+
*
|
|
241
|
+
* @param envelope Parsed envelope (typically from `CvcEnvelopeSchema.parse()`).
|
|
242
|
+
* @param options.mechanismKeys Optional set of valid `service_mechanisms`
|
|
243
|
+
* entry keys. If provided and the envelope entries have `relevantMechanisms`
|
|
244
|
+
* fields, each referenced key must be in this set (C6).
|
|
245
|
+
* @returns An array of {@link CvcValidationError}. An empty array means valid.
|
|
246
|
+
*/
|
|
247
|
+
declare function validateCvc(envelope: CvcEnvelope, options?: {
|
|
248
|
+
mechanismKeys?: ReadonlySet<string>;
|
|
249
|
+
}): CvcValidationError[];
|
|
250
|
+
|
|
251
|
+
export { type CvcCode, CvcCodeSchema, type CvcDomain, type CvcEntry, CvcEntrySchema, type CvcEnvelope, CvcEnvelopeSchema, type CvcKey, CvcKeySchema, type CvcValidationError, type ServiceCategoryEntry, ServiceCategoryEntrySchema, getCvcLevel, validateCvc };
|