@htilabs/platform-common-models 0.12.0 → 0.12.2

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.
Files changed (99) hide show
  1. package/dist/config/index.cjs +0 -81
  2. package/dist/config/index.cjs.map +1 -1
  3. package/dist/config/index.d.cts +4 -79
  4. package/dist/config/index.d.ts +4 -79
  5. package/dist/config/index.js +1 -79
  6. package/dist/config/index.js.map +1 -1
  7. package/dist/constants/index.cjs +18 -2
  8. package/dist/constants/index.cjs.map +1 -1
  9. package/dist/constants/index.d.cts +1 -1
  10. package/dist/constants/index.d.ts +1 -1
  11. package/dist/constants/index.js +18 -2
  12. package/dist/constants/index.js.map +1 -1
  13. package/dist/cvc-Cp4uWnAa.d.cts +298 -0
  14. package/dist/cvc-Cp4uWnAa.d.ts +298 -0
  15. package/dist/{cvcEntry-BCj1OWqL.d.cts → cvcEntry-ctHTp2df.d.cts} +44 -44
  16. package/dist/{cvcEntry-BCj1OWqL.d.ts → cvcEntry-ctHTp2df.d.ts} +44 -44
  17. package/dist/cvcs/index.cjs +8065 -1384
  18. package/dist/cvcs/index.cjs.map +1 -1
  19. package/dist/cvcs/index.d.cts +15287 -8079
  20. package/dist/cvcs/index.d.ts +15287 -8079
  21. package/dist/cvcs/index.js +8052 -1384
  22. package/dist/cvcs/index.js.map +1 -1
  23. package/dist/enums/index.cjs +4573 -0
  24. package/dist/enums/index.cjs.map +1 -0
  25. package/dist/enums/index.d.cts +5277 -0
  26. package/dist/enums/index.d.ts +5277 -0
  27. package/dist/enums/index.js +4369 -0
  28. package/dist/enums/index.js.map +1 -0
  29. package/dist/{index-I-DiX9eQ.d.ts → index-4DiJrn7y.d.ts} +1 -1
  30. package/dist/{index-CoVr1jIV.d.cts → index-qreOzXYS.d.cts} +1 -1
  31. package/dist/index.cjs +8616 -1389
  32. package/dist/index.cjs.map +1 -1
  33. package/dist/index.d.cts +7 -4700
  34. package/dist/index.d.ts +7 -4700
  35. package/dist/index.js +8590 -1389
  36. package/dist/index.js.map +1 -1
  37. package/dist/models/index.d.cts +2 -2
  38. package/dist/models/index.d.ts +2 -2
  39. package/dist/mongo/index.cjs +0 -1
  40. package/dist/mongo/index.cjs.map +1 -1
  41. package/dist/mongo/index.js +1 -2
  42. package/dist/mongo/index.js.map +1 -1
  43. package/dist/{platform-auth-v53r3BhN.d.cts → platform-auth-Dv5fu0Fh.d.cts} +5 -4
  44. package/dist/{platform-auth-v53r3BhN.d.ts → platform-auth-Dv5fu0Fh.d.ts} +5 -4
  45. package/dist/schemas/index.cjs +5 -1
  46. package/dist/schemas/index.cjs.map +1 -1
  47. package/dist/schemas/index.d.cts +35 -35
  48. package/dist/schemas/index.d.ts +35 -35
  49. package/dist/schemas/index.js +5 -1
  50. package/dist/schemas/index.js.map +1 -1
  51. package/dist/types/index.d.cts +2 -2
  52. package/dist/types/index.d.ts +2 -2
  53. package/dist/validation/index.cjs +58 -0
  54. package/dist/validation/index.cjs.map +1 -1
  55. package/dist/validation/index.d.cts +82 -283
  56. package/dist/validation/index.d.ts +82 -283
  57. package/dist/validation/index.js +57 -0
  58. package/dist/validation/index.js.map +1 -1
  59. package/package.json +32 -22
  60. package/src/__sot__/README.md +36 -1
  61. package/src/__sot__/coreIndicatorFields.ts +331 -0
  62. package/src/__sot__/coreIndicators.pin.json +1936 -2
  63. package/src/__sot__/cvcIndex.pin.json +8 -4
  64. package/src/__tests__/__snapshots__/cvc-sot.snap +45 -13
  65. package/src/__tests__/core-information-scope-invariant.test.ts +134 -0
  66. package/src/__tests__/cvc-136-scoring-invariant.test.ts +8 -3
  67. package/src/__tests__/cvc-181-182-country-parity.test.ts +163 -0
  68. package/src/__tests__/cvc-drift-gate.test.ts +463 -12
  69. package/src/__tests__/cvc-sot-snapshot.test.ts +81 -11
  70. package/src/__tests__/cvc-status-parser.test.ts +150 -0
  71. package/src/__tests__/cvc-structural.test.ts +16 -0
  72. package/src/__tests__/runtime-contract-validator.test.ts +1 -325
  73. package/src/__tests__/share-response-reason-invariant.test.ts +167 -0
  74. package/src/config/index.ts +4 -189
  75. package/src/constants/ic.ts +120 -3
  76. package/src/cvcs/assertionDomain.v1.1.0.json +19 -1
  77. package/src/cvcs/assertionStatus.v1.0.0.json +80 -0
  78. package/src/cvcs/carCorrectionReason.v1.0.0.json +89 -0
  79. package/src/cvcs/caseShareState.v1.0.0.json +62 -0
  80. package/src/cvcs/coreIndicators.v1.0.0.json +83 -5
  81. package/src/cvcs/coreInformationScope.v1.0.0.json +1165 -0
  82. package/src/cvcs/countries.v1.0.0.json +3077 -0
  83. package/src/cvcs/createdBySystem.v1.0.0.json +89 -0
  84. package/src/cvcs/criminalOrgCategory.v1.0.0.json +116 -0
  85. package/src/cvcs/determinationHelperCategories.v1.0.0.json +1166 -0
  86. package/src/cvcs/incidentParticipationRoles.v1.0.0.json +11 -1
  87. package/src/cvcs/index.ts +36 -0
  88. package/src/cvcs/minorAdultStatus.v1.0.0.json +80 -0
  89. package/src/cvcs/personRelationships.v1.0.0.json +67 -2
  90. package/src/cvcs/referralOrigin.v1.0.0.json +26 -0
  91. package/src/cvcs/relationshipConcern.v1.0.0.json +28 -19
  92. package/src/cvcs/riskIdentificationMilestone.v1.0.0.json +109 -0
  93. package/src/cvcs/sessionTemplate.v1.0.0.json +22 -0
  94. package/src/cvcs/sharePurpose.v1.0.0.json +80 -12
  95. package/src/cvcs/shareResponseReason.v1.0.0.json +220 -0
  96. package/src/cvcs/subjectType.v1.0.0.json +80 -0
  97. package/src/generated/cvc-enums.ts +628 -20
  98. package/src/validation/cvcStatus.ts +209 -0
  99. package/src/validation/index.ts +1 -0
@@ -0,0 +1,298 @@
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
+ * Format v2 (2026-04-15):
18
+ * - Positional 7-segment codes `XXX-XXX-XXX-XXX-XXX-XXX-XXX` (3 digits per
19
+ * segment). Segment 1 is the Notion-aligned domain prefix:
20
+ * `022` service_categories (CVC-22)
21
+ * `025` service_mechanisms (CVC-25)
22
+ * `049` service_states (CVC-49)
23
+ * - Missingness entries are embedded per-domain (synthetic `missingness_root`
24
+ * at `<prefix>-000-000-000-000-000-000` plus three values at segment 7 =
25
+ * `001`/`002`/`003`). The shared `missingness.v1.0.0.json` file was
26
+ * retired in favor of per-domain missingness.
27
+ * - Envelope `missingness` field and the C7 invariant have been removed; the
28
+ * shared-merge pathway no longer exists.
29
+ */
30
+
31
+ /**
32
+ * 7-segment positional CVC code: `XXX-XXX-XXX-XXX-XXX-XXX-XXX` (three digits
33
+ * per segment). Segment 1 is the Notion-aligned domain prefix. Remaining
34
+ * hierarchy segments are filled left-to-right as levels deepen; unused
35
+ * segments remain `000`. See locked spec §3 (format v2).
36
+ */
37
+ declare const CvcCodeSchema: z.ZodString;
38
+ /**
39
+ * Stable machine key for a CVC entry. Must start with a lowercase letter and
40
+ * contain only lowercase alphanumerics or underscores. Used as a cross-CVC
41
+ * reference target (e.g. `relevantMechanisms` pointing at mechanism keys).
42
+ * See locked spec §3.2.
43
+ */
44
+ declare const CvcKeySchema: z.ZodString;
45
+ /**
46
+ * Base entry shape shared by every CVC domain. Domain-specific extensions
47
+ * (e.g. `ServiceCategoryEntrySchema`) should use `.extend()` to add fields.
48
+ * See locked spec §9.2.
49
+ *
50
+ * Uses `.passthrough()` so that domain-specific fields (like
51
+ * `relevantMechanisms` on service-category entries) survive base parsing
52
+ * unmodified. This keeps cross-CVC reference validation honest: the §4.5
53
+ * structural validator needs to see the raw referenced keys, and a strip-by-
54
+ * default schema would silently hide them.
55
+ */
56
+ declare const CvcEntrySchema: z.ZodObject<{
57
+ code: z.ZodString;
58
+ key: z.ZodString;
59
+ title: z.ZodString;
60
+ selectable: z.ZodBoolean;
61
+ parentCode: z.ZodNullable<z.ZodString>;
62
+ childCodes: z.ZodArray<z.ZodString, "many">;
63
+ definition: z.ZodNullable<z.ZodString>;
64
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
65
+ code: z.ZodString;
66
+ key: z.ZodString;
67
+ title: z.ZodString;
68
+ selectable: z.ZodBoolean;
69
+ parentCode: z.ZodNullable<z.ZodString>;
70
+ childCodes: z.ZodArray<z.ZodString, "many">;
71
+ definition: z.ZodNullable<z.ZodString>;
72
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
73
+ code: z.ZodString;
74
+ key: z.ZodString;
75
+ title: z.ZodString;
76
+ selectable: z.ZodBoolean;
77
+ parentCode: z.ZodNullable<z.ZodString>;
78
+ childCodes: z.ZodArray<z.ZodString, "many">;
79
+ definition: z.ZodNullable<z.ZodString>;
80
+ }, z.ZodTypeAny, "passthrough">>;
81
+ /**
82
+ * Service-category-specific entry. Adds `relevantMechanisms` — a cross-CVC
83
+ * reference into the `service_mechanisms` domain via entry keys. `null` means
84
+ * "not applicable" (e.g. structural L1 topic rows). See locked spec §9.2.
85
+ */
86
+ declare const ServiceCategoryEntrySchema: z.ZodObject<{
87
+ code: z.ZodString;
88
+ key: z.ZodString;
89
+ title: z.ZodString;
90
+ selectable: z.ZodBoolean;
91
+ parentCode: z.ZodNullable<z.ZodString>;
92
+ childCodes: z.ZodArray<z.ZodString, "many">;
93
+ definition: z.ZodNullable<z.ZodString>;
94
+ } & {
95
+ relevantMechanisms: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
96
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
97
+ code: z.ZodString;
98
+ key: z.ZodString;
99
+ title: z.ZodString;
100
+ selectable: z.ZodBoolean;
101
+ parentCode: z.ZodNullable<z.ZodString>;
102
+ childCodes: z.ZodArray<z.ZodString, "many">;
103
+ definition: z.ZodNullable<z.ZodString>;
104
+ } & {
105
+ relevantMechanisms: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
106
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
107
+ code: z.ZodString;
108
+ key: z.ZodString;
109
+ title: z.ZodString;
110
+ selectable: z.ZodBoolean;
111
+ parentCode: z.ZodNullable<z.ZodString>;
112
+ childCodes: z.ZodArray<z.ZodString, "many">;
113
+ definition: z.ZodNullable<z.ZodString>;
114
+ } & {
115
+ relevantMechanisms: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
116
+ }, z.ZodTypeAny, "passthrough">>;
117
+ /**
118
+ * Primary-language-specific entry. Adds:
119
+ * - `iso6391Code` — the ISO 639-1 alpha-2 code for the language, or `null`
120
+ * for entries without an ISO 639-1 code (missingness entries, Chinese
121
+ * varieties Mandarin/Cantonese, `other_language`). ASL is stored as
122
+ * `"ase"` (ISO 639-3) per Notion's convention; the CVC header documents
123
+ * this caveat.
124
+ * - `priority` — `true` for front-end short-list entries (14 total in
125
+ * CVC-122: 13 L1 languages plus the canonical `unknown` missingness
126
+ * entry). See locked spec §9.2.
127
+ */
128
+ declare const PrimaryLanguageEntrySchema: z.ZodObject<{
129
+ code: z.ZodString;
130
+ key: z.ZodString;
131
+ title: z.ZodString;
132
+ selectable: z.ZodBoolean;
133
+ parentCode: z.ZodNullable<z.ZodString>;
134
+ childCodes: z.ZodArray<z.ZodString, "many">;
135
+ definition: z.ZodNullable<z.ZodString>;
136
+ } & {
137
+ iso6391Code: z.ZodNullable<z.ZodString>;
138
+ priority: z.ZodBoolean;
139
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
140
+ code: z.ZodString;
141
+ key: z.ZodString;
142
+ title: z.ZodString;
143
+ selectable: z.ZodBoolean;
144
+ parentCode: z.ZodNullable<z.ZodString>;
145
+ childCodes: z.ZodArray<z.ZodString, "many">;
146
+ definition: z.ZodNullable<z.ZodString>;
147
+ } & {
148
+ iso6391Code: z.ZodNullable<z.ZodString>;
149
+ priority: z.ZodBoolean;
150
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
151
+ code: z.ZodString;
152
+ key: z.ZodString;
153
+ title: z.ZodString;
154
+ selectable: z.ZodBoolean;
155
+ parentCode: z.ZodNullable<z.ZodString>;
156
+ childCodes: z.ZodArray<z.ZodString, "many">;
157
+ definition: z.ZodNullable<z.ZodString>;
158
+ } & {
159
+ iso6391Code: z.ZodNullable<z.ZodString>;
160
+ priority: z.ZodBoolean;
161
+ }, z.ZodTypeAny, "passthrough">>;
162
+ /**
163
+ * Top-level SOT JSON envelope. One envelope per (domain, version) pair.
164
+ *
165
+ * `levels` is a positional map from level number (`"0"`, `"1"`, …) to a human
166
+ * label describing the level. Missingness entries are embedded in `entries`
167
+ * (per-domain) rather than merged in from a shared SOT file; see module
168
+ * header for the v2 format summary.
169
+ */
170
+ declare const CvcEnvelopeSchema: z.ZodObject<{
171
+ domain: z.ZodString;
172
+ name: z.ZodString;
173
+ version: z.ZodString;
174
+ levels: z.ZodRecord<z.ZodString, z.ZodString>;
175
+ entries: z.ZodArray<z.ZodObject<{
176
+ code: z.ZodString;
177
+ key: z.ZodString;
178
+ title: z.ZodString;
179
+ selectable: z.ZodBoolean;
180
+ parentCode: z.ZodNullable<z.ZodString>;
181
+ childCodes: z.ZodArray<z.ZodString, "many">;
182
+ definition: z.ZodNullable<z.ZodString>;
183
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
184
+ code: z.ZodString;
185
+ key: z.ZodString;
186
+ title: z.ZodString;
187
+ selectable: z.ZodBoolean;
188
+ parentCode: z.ZodNullable<z.ZodString>;
189
+ childCodes: z.ZodArray<z.ZodString, "many">;
190
+ definition: z.ZodNullable<z.ZodString>;
191
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
192
+ code: z.ZodString;
193
+ key: z.ZodString;
194
+ title: z.ZodString;
195
+ selectable: z.ZodBoolean;
196
+ parentCode: z.ZodNullable<z.ZodString>;
197
+ childCodes: z.ZodArray<z.ZodString, "many">;
198
+ definition: z.ZodNullable<z.ZodString>;
199
+ }, z.ZodTypeAny, "passthrough">>, "many">;
200
+ }, "strip", z.ZodTypeAny, {
201
+ name: string;
202
+ version: string;
203
+ entries: z.objectOutputType<{
204
+ code: z.ZodString;
205
+ key: z.ZodString;
206
+ title: z.ZodString;
207
+ selectable: z.ZodBoolean;
208
+ parentCode: z.ZodNullable<z.ZodString>;
209
+ childCodes: z.ZodArray<z.ZodString, "many">;
210
+ definition: z.ZodNullable<z.ZodString>;
211
+ }, z.ZodTypeAny, "passthrough">[];
212
+ domain: string;
213
+ levels: Record<string, string>;
214
+ }, {
215
+ name: string;
216
+ version: string;
217
+ entries: z.objectInputType<{
218
+ code: z.ZodString;
219
+ key: z.ZodString;
220
+ title: z.ZodString;
221
+ selectable: z.ZodBoolean;
222
+ parentCode: z.ZodNullable<z.ZodString>;
223
+ childCodes: z.ZodArray<z.ZodString, "many">;
224
+ definition: z.ZodNullable<z.ZodString>;
225
+ }, z.ZodTypeAny, "passthrough">[];
226
+ domain: string;
227
+ levels: Record<string, string>;
228
+ }>;
229
+ type CvcCode = z.infer<typeof CvcCodeSchema>;
230
+ type CvcKey = z.infer<typeof CvcKeySchema>;
231
+ type CvcEntry = z.infer<typeof CvcEntrySchema>;
232
+ type ServiceCategoryEntry = z.infer<typeof ServiceCategoryEntrySchema>;
233
+ type PrimaryLanguageEntry = z.infer<typeof PrimaryLanguageEntrySchema>;
234
+ type CvcEnvelope = z.infer<typeof CvcEnvelopeSchema>;
235
+ /**
236
+ * SOT family identifier (e.g. `"service_categories"`, `"service_states"`,
237
+ * `"service_mechanisms"`, `"missingness"`). The canonical list of domains is
238
+ * enumerated by the SOT JSON files in `src/cvcs/`. Typed as `string` rather
239
+ * than a closed union so adding a new SOT file does not require touching this
240
+ * type. See locked spec §2.
241
+ */
242
+ type CvcDomain = string;
243
+ /**
244
+ * Derive an entry's level from its 7-segment code per locked spec §3.3.
245
+ *
246
+ * - Segment 7 non-zero → level 0 (missingness value entry, e.g. `unknown`).
247
+ * - Otherwise return the index (1..5) of the last non-zero hierarchy segment.
248
+ * - Hierarchy segments 2..7 all zero → level 0 (per-domain missingness root,
249
+ * e.g. `022-000-000-000-000-000-000`). Segment 1 carries the domain prefix
250
+ * and is intentionally not consulted by the level derivation.
251
+ */
252
+ declare function getCvcLevel(code: string): number;
253
+ /**
254
+ * Error collected by {@link validateCvc}. Each error names the invariant it
255
+ * violates (`C1`..`C8`, skipping the retired `C7`) so CI output points
256
+ * straight at the locked spec rule that failed. `code` or `key` narrow the
257
+ * error to a specific entry when the violation is entry-scoped.
258
+ */
259
+ interface CvcValidationError {
260
+ invariant: "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C8";
261
+ message: string;
262
+ code?: string;
263
+ key?: string;
264
+ }
265
+ /**
266
+ * Structural invariants to enforce on every committed SOT file per locked spec
267
+ * §4. Zod's schema `parse()` guarantees the *shape* of the envelope; this
268
+ * function enforces the cross-entry *semantics* that Zod cannot express.
269
+ *
270
+ * Invariants (locked spec §4):
271
+ * - **C1** Code format + uniqueness (§4.1). Format v2 uses 3-digit segments.
272
+ * - **C2** Key format + uniqueness (§4.2).
273
+ * - **C3** Tree: every `parentCode` resolves to an existing entry or null; no
274
+ * cycles (§4.3).
275
+ * - **C4** `childCodes` are the exact bidirectional inverse of `parentCode`
276
+ * (§4.3).
277
+ * - **C5** Selectability is a boolean (§4.4).
278
+ * - **C6** Cross-CVC `relevantMechanisms` references resolve against a
279
+ * provided `service_mechanisms` key set (§4.5, §7). Only checked when the
280
+ * caller supplies `options.mechanismKeys`.
281
+ * - **C7** _Retired in format v2_ (envelope no longer carries the shared
282
+ * `missingness` field; missingness is per-domain and embedded in
283
+ * `entries`). The invariant slot is intentionally left empty to preserve
284
+ * the numbering of C1/C2/C3/C4/C5/C6/C8 in historical references.
285
+ * - **C8** No entry anywhere contains a key `'provided'` (legacy Thread UI
286
+ * label guard; not a canonical state).
287
+ *
288
+ * @param envelope Parsed envelope (typically from `CvcEnvelopeSchema.parse()`).
289
+ * @param options.mechanismKeys Optional set of valid `service_mechanisms`
290
+ * entry keys. If provided and the envelope entries have `relevantMechanisms`
291
+ * fields, each referenced key must be in this set (C6).
292
+ * @returns An array of {@link CvcValidationError}. An empty array means valid.
293
+ */
294
+ declare function validateCvc(envelope: CvcEnvelope, options?: {
295
+ mechanismKeys?: ReadonlySet<string>;
296
+ }): CvcValidationError[];
297
+
298
+ export { type CvcCode as C, type PrimaryLanguageEntry as P, type ServiceCategoryEntry as S, CvcCodeSchema as a, type CvcDomain as b, CvcEntrySchema as c, type CvcEnvelope as d, CvcEnvelopeSchema as e, type CvcKey as f, CvcKeySchema as g, ServiceCategoryEntrySchema as h, type CvcEntry as i, type CvcValidationError as j, PrimaryLanguageEntrySchema as k, getCvcLevel as l, validateCvc as v };
@@ -0,0 +1,298 @@
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
+ * Format v2 (2026-04-15):
18
+ * - Positional 7-segment codes `XXX-XXX-XXX-XXX-XXX-XXX-XXX` (3 digits per
19
+ * segment). Segment 1 is the Notion-aligned domain prefix:
20
+ * `022` service_categories (CVC-22)
21
+ * `025` service_mechanisms (CVC-25)
22
+ * `049` service_states (CVC-49)
23
+ * - Missingness entries are embedded per-domain (synthetic `missingness_root`
24
+ * at `<prefix>-000-000-000-000-000-000` plus three values at segment 7 =
25
+ * `001`/`002`/`003`). The shared `missingness.v1.0.0.json` file was
26
+ * retired in favor of per-domain missingness.
27
+ * - Envelope `missingness` field and the C7 invariant have been removed; the
28
+ * shared-merge pathway no longer exists.
29
+ */
30
+
31
+ /**
32
+ * 7-segment positional CVC code: `XXX-XXX-XXX-XXX-XXX-XXX-XXX` (three digits
33
+ * per segment). Segment 1 is the Notion-aligned domain prefix. Remaining
34
+ * hierarchy segments are filled left-to-right as levels deepen; unused
35
+ * segments remain `000`. See locked spec §3 (format v2).
36
+ */
37
+ declare const CvcCodeSchema: z.ZodString;
38
+ /**
39
+ * Stable machine key for a CVC entry. Must start with a lowercase letter and
40
+ * contain only lowercase alphanumerics or underscores. Used as a cross-CVC
41
+ * reference target (e.g. `relevantMechanisms` pointing at mechanism keys).
42
+ * See locked spec §3.2.
43
+ */
44
+ declare const CvcKeySchema: z.ZodString;
45
+ /**
46
+ * Base entry shape shared by every CVC domain. Domain-specific extensions
47
+ * (e.g. `ServiceCategoryEntrySchema`) should use `.extend()` to add fields.
48
+ * See locked spec §9.2.
49
+ *
50
+ * Uses `.passthrough()` so that domain-specific fields (like
51
+ * `relevantMechanisms` on service-category entries) survive base parsing
52
+ * unmodified. This keeps cross-CVC reference validation honest: the §4.5
53
+ * structural validator needs to see the raw referenced keys, and a strip-by-
54
+ * default schema would silently hide them.
55
+ */
56
+ declare const CvcEntrySchema: z.ZodObject<{
57
+ code: z.ZodString;
58
+ key: z.ZodString;
59
+ title: z.ZodString;
60
+ selectable: z.ZodBoolean;
61
+ parentCode: z.ZodNullable<z.ZodString>;
62
+ childCodes: z.ZodArray<z.ZodString, "many">;
63
+ definition: z.ZodNullable<z.ZodString>;
64
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
65
+ code: z.ZodString;
66
+ key: z.ZodString;
67
+ title: z.ZodString;
68
+ selectable: z.ZodBoolean;
69
+ parentCode: z.ZodNullable<z.ZodString>;
70
+ childCodes: z.ZodArray<z.ZodString, "many">;
71
+ definition: z.ZodNullable<z.ZodString>;
72
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
73
+ code: z.ZodString;
74
+ key: z.ZodString;
75
+ title: z.ZodString;
76
+ selectable: z.ZodBoolean;
77
+ parentCode: z.ZodNullable<z.ZodString>;
78
+ childCodes: z.ZodArray<z.ZodString, "many">;
79
+ definition: z.ZodNullable<z.ZodString>;
80
+ }, z.ZodTypeAny, "passthrough">>;
81
+ /**
82
+ * Service-category-specific entry. Adds `relevantMechanisms` — a cross-CVC
83
+ * reference into the `service_mechanisms` domain via entry keys. `null` means
84
+ * "not applicable" (e.g. structural L1 topic rows). See locked spec §9.2.
85
+ */
86
+ declare const ServiceCategoryEntrySchema: z.ZodObject<{
87
+ code: z.ZodString;
88
+ key: z.ZodString;
89
+ title: z.ZodString;
90
+ selectable: z.ZodBoolean;
91
+ parentCode: z.ZodNullable<z.ZodString>;
92
+ childCodes: z.ZodArray<z.ZodString, "many">;
93
+ definition: z.ZodNullable<z.ZodString>;
94
+ } & {
95
+ relevantMechanisms: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
96
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
97
+ code: z.ZodString;
98
+ key: z.ZodString;
99
+ title: z.ZodString;
100
+ selectable: z.ZodBoolean;
101
+ parentCode: z.ZodNullable<z.ZodString>;
102
+ childCodes: z.ZodArray<z.ZodString, "many">;
103
+ definition: z.ZodNullable<z.ZodString>;
104
+ } & {
105
+ relevantMechanisms: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
106
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
107
+ code: z.ZodString;
108
+ key: z.ZodString;
109
+ title: z.ZodString;
110
+ selectable: z.ZodBoolean;
111
+ parentCode: z.ZodNullable<z.ZodString>;
112
+ childCodes: z.ZodArray<z.ZodString, "many">;
113
+ definition: z.ZodNullable<z.ZodString>;
114
+ } & {
115
+ relevantMechanisms: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
116
+ }, z.ZodTypeAny, "passthrough">>;
117
+ /**
118
+ * Primary-language-specific entry. Adds:
119
+ * - `iso6391Code` — the ISO 639-1 alpha-2 code for the language, or `null`
120
+ * for entries without an ISO 639-1 code (missingness entries, Chinese
121
+ * varieties Mandarin/Cantonese, `other_language`). ASL is stored as
122
+ * `"ase"` (ISO 639-3) per Notion's convention; the CVC header documents
123
+ * this caveat.
124
+ * - `priority` — `true` for front-end short-list entries (14 total in
125
+ * CVC-122: 13 L1 languages plus the canonical `unknown` missingness
126
+ * entry). See locked spec §9.2.
127
+ */
128
+ declare const PrimaryLanguageEntrySchema: z.ZodObject<{
129
+ code: z.ZodString;
130
+ key: z.ZodString;
131
+ title: z.ZodString;
132
+ selectable: z.ZodBoolean;
133
+ parentCode: z.ZodNullable<z.ZodString>;
134
+ childCodes: z.ZodArray<z.ZodString, "many">;
135
+ definition: z.ZodNullable<z.ZodString>;
136
+ } & {
137
+ iso6391Code: z.ZodNullable<z.ZodString>;
138
+ priority: z.ZodBoolean;
139
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
140
+ code: z.ZodString;
141
+ key: z.ZodString;
142
+ title: z.ZodString;
143
+ selectable: z.ZodBoolean;
144
+ parentCode: z.ZodNullable<z.ZodString>;
145
+ childCodes: z.ZodArray<z.ZodString, "many">;
146
+ definition: z.ZodNullable<z.ZodString>;
147
+ } & {
148
+ iso6391Code: z.ZodNullable<z.ZodString>;
149
+ priority: z.ZodBoolean;
150
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
151
+ code: z.ZodString;
152
+ key: z.ZodString;
153
+ title: z.ZodString;
154
+ selectable: z.ZodBoolean;
155
+ parentCode: z.ZodNullable<z.ZodString>;
156
+ childCodes: z.ZodArray<z.ZodString, "many">;
157
+ definition: z.ZodNullable<z.ZodString>;
158
+ } & {
159
+ iso6391Code: z.ZodNullable<z.ZodString>;
160
+ priority: z.ZodBoolean;
161
+ }, z.ZodTypeAny, "passthrough">>;
162
+ /**
163
+ * Top-level SOT JSON envelope. One envelope per (domain, version) pair.
164
+ *
165
+ * `levels` is a positional map from level number (`"0"`, `"1"`, …) to a human
166
+ * label describing the level. Missingness entries are embedded in `entries`
167
+ * (per-domain) rather than merged in from a shared SOT file; see module
168
+ * header for the v2 format summary.
169
+ */
170
+ declare const CvcEnvelopeSchema: z.ZodObject<{
171
+ domain: z.ZodString;
172
+ name: z.ZodString;
173
+ version: z.ZodString;
174
+ levels: z.ZodRecord<z.ZodString, z.ZodString>;
175
+ entries: z.ZodArray<z.ZodObject<{
176
+ code: z.ZodString;
177
+ key: z.ZodString;
178
+ title: z.ZodString;
179
+ selectable: z.ZodBoolean;
180
+ parentCode: z.ZodNullable<z.ZodString>;
181
+ childCodes: z.ZodArray<z.ZodString, "many">;
182
+ definition: z.ZodNullable<z.ZodString>;
183
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
184
+ code: z.ZodString;
185
+ key: z.ZodString;
186
+ title: z.ZodString;
187
+ selectable: z.ZodBoolean;
188
+ parentCode: z.ZodNullable<z.ZodString>;
189
+ childCodes: z.ZodArray<z.ZodString, "many">;
190
+ definition: z.ZodNullable<z.ZodString>;
191
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
192
+ code: z.ZodString;
193
+ key: z.ZodString;
194
+ title: z.ZodString;
195
+ selectable: z.ZodBoolean;
196
+ parentCode: z.ZodNullable<z.ZodString>;
197
+ childCodes: z.ZodArray<z.ZodString, "many">;
198
+ definition: z.ZodNullable<z.ZodString>;
199
+ }, z.ZodTypeAny, "passthrough">>, "many">;
200
+ }, "strip", z.ZodTypeAny, {
201
+ name: string;
202
+ version: string;
203
+ entries: z.objectOutputType<{
204
+ code: z.ZodString;
205
+ key: z.ZodString;
206
+ title: z.ZodString;
207
+ selectable: z.ZodBoolean;
208
+ parentCode: z.ZodNullable<z.ZodString>;
209
+ childCodes: z.ZodArray<z.ZodString, "many">;
210
+ definition: z.ZodNullable<z.ZodString>;
211
+ }, z.ZodTypeAny, "passthrough">[];
212
+ domain: string;
213
+ levels: Record<string, string>;
214
+ }, {
215
+ name: string;
216
+ version: string;
217
+ entries: z.objectInputType<{
218
+ code: z.ZodString;
219
+ key: z.ZodString;
220
+ title: z.ZodString;
221
+ selectable: z.ZodBoolean;
222
+ parentCode: z.ZodNullable<z.ZodString>;
223
+ childCodes: z.ZodArray<z.ZodString, "many">;
224
+ definition: z.ZodNullable<z.ZodString>;
225
+ }, z.ZodTypeAny, "passthrough">[];
226
+ domain: string;
227
+ levels: Record<string, string>;
228
+ }>;
229
+ type CvcCode = z.infer<typeof CvcCodeSchema>;
230
+ type CvcKey = z.infer<typeof CvcKeySchema>;
231
+ type CvcEntry = z.infer<typeof CvcEntrySchema>;
232
+ type ServiceCategoryEntry = z.infer<typeof ServiceCategoryEntrySchema>;
233
+ type PrimaryLanguageEntry = z.infer<typeof PrimaryLanguageEntrySchema>;
234
+ type CvcEnvelope = z.infer<typeof CvcEnvelopeSchema>;
235
+ /**
236
+ * SOT family identifier (e.g. `"service_categories"`, `"service_states"`,
237
+ * `"service_mechanisms"`, `"missingness"`). The canonical list of domains is
238
+ * enumerated by the SOT JSON files in `src/cvcs/`. Typed as `string` rather
239
+ * than a closed union so adding a new SOT file does not require touching this
240
+ * type. See locked spec §2.
241
+ */
242
+ type CvcDomain = string;
243
+ /**
244
+ * Derive an entry's level from its 7-segment code per locked spec §3.3.
245
+ *
246
+ * - Segment 7 non-zero → level 0 (missingness value entry, e.g. `unknown`).
247
+ * - Otherwise return the index (1..5) of the last non-zero hierarchy segment.
248
+ * - Hierarchy segments 2..7 all zero → level 0 (per-domain missingness root,
249
+ * e.g. `022-000-000-000-000-000-000`). Segment 1 carries the domain prefix
250
+ * and is intentionally not consulted by the level derivation.
251
+ */
252
+ declare function getCvcLevel(code: string): number;
253
+ /**
254
+ * Error collected by {@link validateCvc}. Each error names the invariant it
255
+ * violates (`C1`..`C8`, skipping the retired `C7`) so CI output points
256
+ * straight at the locked spec rule that failed. `code` or `key` narrow the
257
+ * error to a specific entry when the violation is entry-scoped.
258
+ */
259
+ interface CvcValidationError {
260
+ invariant: "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C8";
261
+ message: string;
262
+ code?: string;
263
+ key?: string;
264
+ }
265
+ /**
266
+ * Structural invariants to enforce on every committed SOT file per locked spec
267
+ * §4. Zod's schema `parse()` guarantees the *shape* of the envelope; this
268
+ * function enforces the cross-entry *semantics* that Zod cannot express.
269
+ *
270
+ * Invariants (locked spec §4):
271
+ * - **C1** Code format + uniqueness (§4.1). Format v2 uses 3-digit segments.
272
+ * - **C2** Key format + uniqueness (§4.2).
273
+ * - **C3** Tree: every `parentCode` resolves to an existing entry or null; no
274
+ * cycles (§4.3).
275
+ * - **C4** `childCodes` are the exact bidirectional inverse of `parentCode`
276
+ * (§4.3).
277
+ * - **C5** Selectability is a boolean (§4.4).
278
+ * - **C6** Cross-CVC `relevantMechanisms` references resolve against a
279
+ * provided `service_mechanisms` key set (§4.5, §7). Only checked when the
280
+ * caller supplies `options.mechanismKeys`.
281
+ * - **C7** _Retired in format v2_ (envelope no longer carries the shared
282
+ * `missingness` field; missingness is per-domain and embedded in
283
+ * `entries`). The invariant slot is intentionally left empty to preserve
284
+ * the numbering of C1/C2/C3/C4/C5/C6/C8 in historical references.
285
+ * - **C8** No entry anywhere contains a key `'provided'` (legacy Thread UI
286
+ * label guard; not a canonical state).
287
+ *
288
+ * @param envelope Parsed envelope (typically from `CvcEnvelopeSchema.parse()`).
289
+ * @param options.mechanismKeys Optional set of valid `service_mechanisms`
290
+ * entry keys. If provided and the envelope entries have `relevantMechanisms`
291
+ * fields, each referenced key must be in this set (C6).
292
+ * @returns An array of {@link CvcValidationError}. An empty array means valid.
293
+ */
294
+ declare function validateCvc(envelope: CvcEnvelope, options?: {
295
+ mechanismKeys?: ReadonlySet<string>;
296
+ }): CvcValidationError[];
297
+
298
+ export { type CvcCode as C, type PrimaryLanguageEntry as P, type ServiceCategoryEntry as S, CvcCodeSchema as a, type CvcDomain as b, CvcEntrySchema as c, type CvcEnvelope as d, CvcEnvelopeSchema as e, type CvcKey as f, CvcKeySchema as g, ServiceCategoryEntrySchema as h, type CvcEntry as i, type CvcValidationError as j, PrimaryLanguageEntrySchema as k, getCvcLevel as l, validateCvc as v };