@htilabs/platform-common-models 0.3.0-beta.5 → 0.4.0-beta.1

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 (45) hide show
  1. package/dist/cvcs/index.cjs +634 -468
  2. package/dist/cvcs/index.cjs.map +1 -1
  3. package/dist/cvcs/index.d.cts +570 -505
  4. package/dist/cvcs/index.d.ts +570 -505
  5. package/dist/cvcs/index.js +634 -467
  6. package/dist/cvcs/index.js.map +1 -1
  7. package/dist/index.cjs +814 -644
  8. package/dist/index.cjs.map +1 -1
  9. package/dist/index.d.cts +179 -179
  10. package/dist/index.d.ts +179 -179
  11. package/dist/index.js +814 -642
  12. package/dist/index.js.map +1 -1
  13. package/dist/models/index.cjs +6 -5
  14. package/dist/models/index.cjs.map +1 -1
  15. package/dist/models/index.js +6 -5
  16. package/dist/models/index.js.map +1 -1
  17. package/dist/schemas/index.cjs +4 -3
  18. package/dist/schemas/index.cjs.map +1 -1
  19. package/dist/schemas/index.js +4 -3
  20. package/dist/schemas/index.js.map +1 -1
  21. package/dist/services/index.cjs +6 -5
  22. package/dist/services/index.cjs.map +1 -1
  23. package/dist/services/index.js +6 -5
  24. package/dist/services/index.js.map +1 -1
  25. package/dist/validation/index.cjs +5 -12
  26. package/dist/validation/index.cjs.map +1 -1
  27. package/dist/validation/index.d.cts +32 -31
  28. package/dist/validation/index.d.ts +32 -31
  29. package/dist/validation/index.js +5 -12
  30. package/dist/validation/index.js.map +1 -1
  31. package/package.json +1 -1
  32. package/src/__tests__/__snapshots__/cvc-sot.snap +7 -11
  33. package/src/__tests__/cvc-sot-snapshot.test.ts +8 -8
  34. package/src/__tests__/cvc-structural.test.ts +1 -2
  35. package/src/cvcs/index.ts +5 -6
  36. package/src/cvcs/serviceCategories.v1.0.0.json +560 -430
  37. package/src/cvcs/serviceMechanisms.v1.0.0.json +45 -5
  38. package/src/cvcs/serviceStates.v1.0.0.json +58 -18
  39. package/src/generated/cvc-enums.ts +177 -179
  40. package/src/models/cvcEntryModel.ts +1 -1
  41. package/src/models/cvcRegistryModel.ts +1 -1
  42. package/src/schemas/cvcEntry.ts +3 -2
  43. package/src/schemas/cvcRegistry.ts +3 -2
  44. package/src/validation/cvc.ts +38 -55
  45. package/src/cvcs/missingness.v1.0.0.json +0 -50
@@ -12,13 +12,18 @@
12
12
  * Canonical spec:
13
13
  * /gt/docs/data/cvcs/CVC Implementation Spec 2780449faf8045258c67daab0f1c5569.md
14
14
  *
15
- * Locked decisions (2026-04-10):
16
- * - Positional 7-segment codes `XX-XX-XX-XX-XX-XX-XX` (§3).
17
- * - `missingness` envelope field is an optional `string[]`; `["all"]` is the
18
- * sentinel meaning "merge all missingness values" (§2.1, §5.2).
19
- * - `missingness.v1.0.0.json` wraps its values under a synthetic root
20
- * (`missingness_root`) which is the one sanctioned parent-child exception
21
- * for level-consistency, scoped by segment-1 domain prefix (§5.1).
15
+ * Format v2 (2026-04-15):
16
+ * - Positional 7-segment codes `XXX-XXX-XXX-XXX-XXX-XXX-XXX` (3 digits per
17
+ * segment). Segment 1 is the Notion-aligned domain prefix:
18
+ * `022` service_categories (CVC-22)
19
+ * `025` service_mechanisms (CVC-25)
20
+ * `049` service_state (CVC-49)
21
+ * - Missingness entries are embedded per-domain (synthetic `missingness_root`
22
+ * at `<prefix>-000-000-000-000-000-000` plus three values at segment 7 =
23
+ * `001`/`002`/`003`). The shared `missingness.v1.0.0.json` file was
24
+ * retired in favor of per-domain missingness.
25
+ * - Envelope `missingness` field and the C7 invariant have been removed; the
26
+ * shared-merge pathway no longer exists.
22
27
  */
23
28
 
24
29
  import { z } from "zod";
@@ -26,11 +31,12 @@ import { z } from "zod";
26
31
  // ─── Primitive schemas ───────────────────────────────────────────────────────
27
32
 
28
33
  /**
29
- * 7-segment positional CVC code: `XX-XX-XX-XX-XX-XX-XX` (two digits per
30
- * segment). Segments are filled left-to-right as levels deepen; unused
31
- * segments remain `00`. See locked spec §3.
34
+ * 7-segment positional CVC code: `XXX-XXX-XXX-XXX-XXX-XXX-XXX` (three digits
35
+ * per segment). Segment 1 is the Notion-aligned domain prefix. Remaining
36
+ * hierarchy segments are filled left-to-right as levels deepen; unused
37
+ * segments remain `000`. See locked spec §3 (format v2).
32
38
  */
33
- export const CvcCodeSchema = z.string().regex(/^\d{2}(-\d{2}){6}$/);
39
+ export const CvcCodeSchema = z.string().regex(/^\d{3}(-\d{3}){6}$/);
34
40
 
35
41
  /**
36
42
  * Stable machine key for a CVC entry. Must start with a lowercase letter and
@@ -79,21 +85,15 @@ export const ServiceCategoryEntrySchema = CvcEntrySchema.extend({
79
85
  /**
80
86
  * Top-level SOT JSON envelope. One envelope per (domain, version) pair.
81
87
  *
82
- * `missingness` is an optional array of missingness keys to merge into this
83
- * CVC at seed time. `["all"]` is the sentinel meaning "merge the missingness
84
- * root plus all three value entries". Individual keys merge only those.
85
- * Absent, empty, or null means "skip missingness merge". The missingness CVC
86
- * file itself omits this field because merging missingness into itself is
87
- * nonsensical. See locked spec §2.1 and §5.2.
88
- *
89
88
  * `levels` is a positional map from level number (`"0"`, `"1"`, …) to a human
90
- * label describing the level.
89
+ * label describing the level. Missingness entries are embedded in `entries`
90
+ * (per-domain) rather than merged in from a shared SOT file; see module
91
+ * header for the v2 format summary.
91
92
  */
92
93
  export const CvcEnvelopeSchema = z.object({
93
94
  domain: z.string().min(1),
94
95
  name: z.string().min(1),
95
96
  version: z.string().min(1),
96
- missingness: z.array(z.string()).optional(),
97
97
  levels: z.record(z.string(), z.string()),
98
98
  entries: z.array(CvcEntrySchema),
99
99
  });
@@ -107,7 +107,7 @@ export type ServiceCategoryEntry = z.infer<typeof ServiceCategoryEntrySchema>;
107
107
  export type CvcEnvelope = z.infer<typeof CvcEnvelopeSchema>;
108
108
 
109
109
  /**
110
- * SOT family identifier (e.g. `"service_categories"`, `"service_states"`,
110
+ * SOT family identifier (e.g. `"service_categories"`, `"service_state"`,
111
111
  * `"service_mechanisms"`, `"missingness"`). The canonical list of domains is
112
112
  * enumerated by the SOT JSON files in `src/cvcs/`. Typed as `string` rather
113
113
  * than a closed union so adding a new SOT file does not require touching this
@@ -122,28 +122,30 @@ export type CvcDomain = string;
122
122
  *
123
123
  * - Segment 7 non-zero → level 0 (missingness value entry, e.g. `unknown`).
124
124
  * - Otherwise return the index (1..5) of the last non-zero hierarchy segment.
125
- * - All segments zero → level 0 (missingness root, `00-00-00-00-00-00-00`).
125
+ * - Hierarchy segments 2..7 all zero → level 0 (per-domain missingness root,
126
+ * e.g. `022-000-000-000-000-000-000`). Segment 1 carries the domain prefix
127
+ * and is intentionally not consulted by the level derivation.
126
128
  */
127
129
  export function getCvcLevel(code: string): number {
128
130
  const segments = code.split("-");
129
131
  // segments[6] is the missingness slot (positional segment 7).
130
- if (segments[6] !== "00") return 0;
132
+ if (segments[6] !== "000") return 0;
131
133
  // Walk hierarchy segments 6..2 (indices 5..1) looking for the deepest
132
134
  // populated level.
133
135
  for (let i = 5; i >= 1; i -= 1) {
134
- if (segments[i] !== "00") return i;
136
+ if (segments[i] !== "000") return i;
135
137
  }
136
138
  return 0;
137
139
  }
138
140
 
139
141
  /**
140
142
  * Error collected by {@link validateCvc}. Each error names the invariant it
141
- * violates (`C1`..`C8`) so CI output points straight at the locked spec rule
142
- * that failed. `code` or `key` narrow the error to a specific entry when the
143
- * violation is entry-scoped.
143
+ * violates (`C1`..`C8`, skipping the retired `C7`) so CI output points
144
+ * straight at the locked spec rule that failed. `code` or `key` narrow the
145
+ * error to a specific entry when the violation is entry-scoped.
144
146
  */
145
147
  export interface CvcValidationError {
146
- invariant: "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8";
148
+ invariant: "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C8";
147
149
  message: string;
148
150
  code?: string;
149
151
  key?: string;
@@ -155,7 +157,7 @@ export interface CvcValidationError {
155
157
  * function enforces the cross-entry *semantics* that Zod cannot express.
156
158
  *
157
159
  * Invariants (locked spec §4):
158
- * - **C1** Code format + uniqueness (§4.1).
160
+ * - **C1** Code format + uniqueness (§4.1). Format v2 uses 3-digit segments.
159
161
  * - **C2** Key format + uniqueness (§4.2).
160
162
  * - **C3** Tree: every `parentCode` resolves to an existing entry or null; no
161
163
  * cycles (§4.3).
@@ -165,9 +167,10 @@ export interface CvcValidationError {
165
167
  * - **C6** Cross-CVC `relevantMechanisms` references resolve against a
166
168
  * provided `service_mechanisms` key set (§4.5, §7). Only checked when the
167
169
  * caller supplies `options.mechanismKeys`.
168
- * - **C7** Envelope has all 6 required fields (`domain`, `name`, `version`,
169
- * `missingness`, `levels`, `entries`) — treating the optional-in-Zod
170
- * `missingness` as required at CI time (§4.6).
170
+ * - **C7** _Retired in format v2_ (envelope no longer carries the shared
171
+ * `missingness` field; missingness is per-domain and embedded in
172
+ * `entries`). The invariant slot is intentionally left empty to preserve
173
+ * the numbering of C1/C2/C3/C4/C5/C6/C8 in historical references.
171
174
  * - **C8** No entry anywhere contains a key `'provided'` (legacy Thread UI
172
175
  * label guard; not a canonical state).
173
176
  *
@@ -184,31 +187,14 @@ export function validateCvc(
184
187
  const errors: CvcValidationError[] = [];
185
188
  const { entries } = envelope;
186
189
 
187
- // C7: envelope-level required fields. Zod already rejects missing `domain`,
188
- // `name`, `version`, `levels`, and `entries`. We additionally require
189
- // `missingness` to be present (even as an empty array) at CI time so the
190
- // seed CLI sees an explicit "opt-out" rather than an undefined field.
191
- //
192
- // Exemption: the `missingness` CVC file itself legitimately omits this
193
- // field because merging missingness into itself is nonsensical (locked spec
194
- // §9.2). This is the one sanctioned omission.
195
- if (envelope.domain !== "missingness" && envelope.missingness === undefined) {
196
- errors.push({
197
- invariant: "C7",
198
- message:
199
- "envelope is missing required field `missingness` (must be an array, " +
200
- "use `[]` to opt out of the missingness merge)",
201
- });
202
- }
203
-
204
190
  // ── C1: code format + uniqueness ──────────────────────────────────────────
205
- const codeRe = /^\d{2}(-\d{2}){6}$/;
191
+ const codeRe = /^\d{3}(-\d{3}){6}$/;
206
192
  const seenCodes = new Set<string>();
207
193
  for (const entry of entries) {
208
194
  if (!codeRe.test(entry.code)) {
209
195
  errors.push({
210
196
  invariant: "C1",
211
- message: `code does not match /^\\d{2}(-\\d{2}){6}$/`,
197
+ message: `code does not match /^\\d{3}(-\\d{3}){6}$/`,
212
198
  code: entry.code,
213
199
  key: entry.key,
214
200
  });
@@ -358,10 +344,7 @@ export function validateCvc(
358
344
  continue;
359
345
  }
360
346
  for (const mechKey of raw) {
361
- if (
362
- typeof mechKey !== "string" ||
363
- !options.mechanismKeys.has(mechKey)
364
- ) {
347
+ if (typeof mechKey !== "string" || !options.mechanismKeys.has(mechKey)) {
365
348
  errors.push({
366
349
  invariant: "C6",
367
350
  message: `relevantMechanisms references unknown service_mechanisms key: ${String(mechKey)}`,
@@ -1,50 +0,0 @@
1
- {
2
- "domain": "missingness",
3
- "name": "Universal Missingness Values",
4
- "version": "1.0.0",
5
- "levels": {
6
- "0": "Unknown or Missing"
7
- },
8
- "entries": [
9
- {
10
- "code": "00-00-00-00-00-00-00",
11
- "key": "missingness_root",
12
- "title": "Unknown, Redacted, or Missing",
13
- "selectable": false,
14
- "parentCode": null,
15
- "childCodes": [
16
- "00-00-00-00-00-00-01",
17
- "00-00-00-00-00-00-02",
18
- "00-00-00-00-00-00-03"
19
- ],
20
- "definition": "Root group for values indicating absent, withheld, or uncollected data."
21
- },
22
- {
23
- "code": "00-00-00-00-00-00-01",
24
- "key": "unknown",
25
- "title": "Unknown",
26
- "selectable": true,
27
- "parentCode": "00-00-00-00-00-00-00",
28
- "childCodes": [],
29
- "definition": "Value is unknown at time of entry."
30
- },
31
- {
32
- "code": "00-00-00-00-00-00-02",
33
- "key": "anonymous",
34
- "title": "Anonymous",
35
- "selectable": true,
36
- "parentCode": "00-00-00-00-00-00-00",
37
- "childCodes": [],
38
- "definition": "Value is intentionally withheld or redacted."
39
- },
40
- {
41
- "code": "00-00-00-00-00-00-03",
42
- "key": "data_not_collected",
43
- "title": "Data not collected",
44
- "selectable": true,
45
- "parentCode": "00-00-00-00-00-00-00",
46
- "childCodes": [],
47
- "definition": "No attempt was made to collect the value."
48
- }
49
- ]
50
- }