@htilabs/platform-common-models 0.3.0-beta.5 → 0.4.0-beta.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 (43) hide show
  1. package/dist/cvcs/index.cjs +633 -467
  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 +633 -466
  6. package/dist/cvcs/index.js.map +1 -1
  7. package/dist/index.cjs +811 -641
  8. package/dist/index.cjs.map +1 -1
  9. package/dist/index.d.cts +178 -178
  10. package/dist/index.d.ts +178 -178
  11. package/dist/index.js +811 -639
  12. package/dist/index.js.map +1 -1
  13. package/dist/models/index.cjs +4 -3
  14. package/dist/models/index.cjs.map +1 -1
  15. package/dist/models/index.js +4 -3
  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 +4 -3
  22. package/dist/services/index.cjs.map +1 -1
  23. package/dist/services/index.js +4 -3
  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 +31 -30
  28. package/dist/validation/index.d.ts +31 -30
  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 +6 -10
  33. package/src/__tests__/cvc-sot-snapshot.test.ts +8 -8
  34. package/src/__tests__/cvc-structural.test.ts +0 -1
  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 +57 -17
  39. package/src/generated/cvc-enums.ts +176 -178
  40. package/src/schemas/cvcEntry.ts +3 -2
  41. package/src/schemas/cvcRegistry.ts +3 -2
  42. package/src/validation/cvc.ts +36 -50
  43. package/src/cvcs/missingness.v1.0.0.json +0 -50
@@ -1 +1 @@
1
- {"version":3,"sources":["../../src/validation/index.ts","../../src/validation/cvc.ts"],"sourcesContent":["/**\n * @htilabs/platform-common-models — Validation barrel\n *\n * Public entry point for the Zod validation surface. Consumers that want\n * the canonical Zod-inferred `CvcEntry` (rather than the Mongoose persistence\n * shape exported from the package root) should import from here:\n *\n * ```ts\n * import { CvcEntry, CvcEntrySchema } from '@htilabs/platform-common-models/validation';\n * ```\n *\n * See `./cvc.ts` for the schema and type definitions.\n */\n\nexport * from \"./cvc.js\";\n","/**\n * @htilabs/platform-common-models — Controlled Vocabulary (CVC) Validation\n *\n * Zod schemas for validating CVC Source-of-Truth (SOT) JSON files and\n * individual CVC entries. Implements the locked spec §9.2 shapes.\n *\n * Used by:\n * - CI structural tests that parse every committed SOT file.\n * - The generalized seed CLI (`seedCvc`) prior to persistence.\n * - Downstream consumers that need to validate CVC payloads.\n *\n * Canonical spec:\n * /gt/docs/data/cvcs/CVC Implementation Spec 2780449faf8045258c67daab0f1c5569.md\n *\n * Locked decisions (2026-04-10):\n * - Positional 7-segment codes `XX-XX-XX-XX-XX-XX-XX` (§3).\n * - `missingness` envelope field is an optional `string[]`; `[\"all\"]` is the\n * sentinel meaning \"merge all missingness values\" (§2.1, §5.2).\n * - `missingness.v1.0.0.json` wraps its values under a synthetic root\n * (`missingness_root`) which is the one sanctioned parent-child exception\n * for level-consistency, scoped by segment-1 domain prefix (§5.1).\n */\n\nimport { z } from \"zod\";\n\n// ─── Primitive schemas ───────────────────────────────────────────────────────\n\n/**\n * 7-segment positional CVC code: `XX-XX-XX-XX-XX-XX-XX` (two digits per\n * segment). Segments are filled left-to-right as levels deepen; unused\n * segments remain `00`. See locked spec §3.\n */\nexport const CvcCodeSchema = z.string().regex(/^\\d{2}(-\\d{2}){6}$/);\n\n/**\n * Stable machine key for a CVC entry. Must start with a lowercase letter and\n * contain only lowercase alphanumerics or underscores. Used as a cross-CVC\n * reference target (e.g. `relevantMechanisms` pointing at mechanism keys).\n * See locked spec §3.2.\n */\nexport const CvcKeySchema = z.string().regex(/^[a-z][a-z0-9_]*$/);\n\n// ─── Entry schemas ───────────────────────────────────────────────────────────\n\n/**\n * Base entry shape shared by every CVC domain. Domain-specific extensions\n * (e.g. `ServiceCategoryEntrySchema`) should use `.extend()` to add fields.\n * See locked spec §9.2.\n *\n * Uses `.passthrough()` so that domain-specific fields (like\n * `relevantMechanisms` on service-category entries) survive base parsing\n * unmodified. This keeps cross-CVC reference validation honest: the §4.5\n * structural validator needs to see the raw referenced keys, and a strip-by-\n * default schema would silently hide them.\n */\nexport const CvcEntrySchema = z\n .object({\n code: CvcCodeSchema,\n key: CvcKeySchema,\n title: z.string().min(1),\n selectable: z.boolean(),\n parentCode: CvcCodeSchema.nullable(),\n childCodes: z.array(CvcCodeSchema),\n definition: z.string().nullable(),\n })\n .passthrough();\n\n/**\n * Service-category-specific entry. Adds `relevantMechanisms` — a cross-CVC\n * reference into the `service_mechanisms` domain via entry keys. `null` means\n * \"not applicable\" (e.g. structural L1 topic rows). See locked spec §9.2.\n */\nexport const ServiceCategoryEntrySchema = CvcEntrySchema.extend({\n relevantMechanisms: z.array(CvcKeySchema).nullable(),\n});\n\n// ─── Envelope schema ─────────────────────────────────────────────────────────\n\n/**\n * Top-level SOT JSON envelope. One envelope per (domain, version) pair.\n *\n * `missingness` is an optional array of missingness keys to merge into this\n * CVC at seed time. `[\"all\"]` is the sentinel meaning \"merge the missingness\n * root plus all three value entries\". Individual keys merge only those.\n * Absent, empty, or null means \"skip missingness merge\". The missingness CVC\n * file itself omits this field because merging missingness into itself is\n * nonsensical. See locked spec §2.1 and §5.2.\n *\n * `levels` is a positional map from level number (`\"0\"`, `\"1\"`, …) to a human\n * label describing the level.\n */\nexport const CvcEnvelopeSchema = z.object({\n domain: z.string().min(1),\n name: z.string().min(1),\n version: z.string().min(1),\n missingness: z.array(z.string()).optional(),\n levels: z.record(z.string(), z.string()),\n entries: z.array(CvcEntrySchema),\n});\n\n// ─── Inferred types ──────────────────────────────────────────────────────────\n\nexport type CvcCode = z.infer<typeof CvcCodeSchema>;\nexport type CvcKey = z.infer<typeof CvcKeySchema>;\nexport type CvcEntry = z.infer<typeof CvcEntrySchema>;\nexport type ServiceCategoryEntry = z.infer<typeof ServiceCategoryEntrySchema>;\nexport type CvcEnvelope = z.infer<typeof CvcEnvelopeSchema>;\n\n/**\n * SOT family identifier (e.g. `\"service_categories\"`, `\"service_states\"`,\n * `\"service_mechanisms\"`, `\"missingness\"`). The canonical list of domains is\n * enumerated by the SOT JSON files in `src/cvcs/`. Typed as `string` rather\n * than a closed union so adding a new SOT file does not require touching this\n * type. See locked spec §2.\n */\nexport type CvcDomain = string;\n\n// ─── Structural validator (locked spec §4 / §9.3) ───────────────────────────\n\n/**\n * Derive an entry's level from its 7-segment code per locked spec §3.3.\n *\n * - Segment 7 non-zero → level 0 (missingness value entry, e.g. `unknown`).\n * - Otherwise return the index (1..5) of the last non-zero hierarchy segment.\n * - All segments zero → level 0 (missingness root, `00-00-00-00-00-00-00`).\n */\nexport function getCvcLevel(code: string): number {\n const segments = code.split(\"-\");\n // segments[6] is the missingness slot (positional segment 7).\n if (segments[6] !== \"00\") return 0;\n // Walk hierarchy segments 6..2 (indices 5..1) looking for the deepest\n // populated level.\n for (let i = 5; i >= 1; i -= 1) {\n if (segments[i] !== \"00\") return i;\n }\n return 0;\n}\n\n/**\n * Error collected by {@link validateCvc}. Each error names the invariant it\n * violates (`C1`..`C8`) so CI output points straight at the locked spec rule\n * that failed. `code` or `key` narrow the error to a specific entry when the\n * violation is entry-scoped.\n */\nexport interface CvcValidationError {\n invariant: \"C1\" | \"C2\" | \"C3\" | \"C4\" | \"C5\" | \"C6\" | \"C7\" | \"C8\";\n message: string;\n code?: string;\n key?: string;\n}\n\n/**\n * Structural invariants to enforce on every committed SOT file per locked spec\n * §4. Zod's schema `parse()` guarantees the *shape* of the envelope; this\n * function enforces the cross-entry *semantics* that Zod cannot express.\n *\n * Invariants (locked spec §4):\n * - **C1** Code format + uniqueness (§4.1).\n * - **C2** Key format + uniqueness (§4.2).\n * - **C3** Tree: every `parentCode` resolves to an existing entry or null; no\n * cycles (§4.3).\n * - **C4** `childCodes` are the exact bidirectional inverse of `parentCode`\n * (§4.3).\n * - **C5** Selectability is a boolean (§4.4).\n * - **C6** Cross-CVC `relevantMechanisms` references resolve against a\n * provided `service_mechanisms` key set (§4.5, §7). Only checked when the\n * caller supplies `options.mechanismKeys`.\n * - **C7** Envelope has all 6 required fields (`domain`, `name`, `version`,\n * `missingness`, `levels`, `entries`) — treating the optional-in-Zod\n * `missingness` as required at CI time (§4.6).\n * - **C8** No entry anywhere contains a key `'provided'` (legacy Thread UI\n * label guard; not a canonical state).\n *\n * @param envelope Parsed envelope (typically from `CvcEnvelopeSchema.parse()`).\n * @param options.mechanismKeys Optional set of valid `service_mechanisms`\n * entry keys. If provided and the envelope entries have `relevantMechanisms`\n * fields, each referenced key must be in this set (C6).\n * @returns An array of {@link CvcValidationError}. An empty array means valid.\n */\nexport function validateCvc(\n envelope: CvcEnvelope,\n options: { mechanismKeys?: ReadonlySet<string> } = {},\n): CvcValidationError[] {\n const errors: CvcValidationError[] = [];\n const { entries } = envelope;\n\n // C7: envelope-level required fields. Zod already rejects missing `domain`,\n // `name`, `version`, `levels`, and `entries`. We additionally require\n // `missingness` to be present (even as an empty array) at CI time so the\n // seed CLI sees an explicit \"opt-out\" rather than an undefined field.\n //\n // Exemption: the `missingness` CVC file itself legitimately omits this\n // field because merging missingness into itself is nonsensical (locked spec\n // §9.2). This is the one sanctioned omission.\n if (envelope.domain !== \"missingness\" && envelope.missingness === undefined) {\n errors.push({\n invariant: \"C7\",\n message:\n \"envelope is missing required field `missingness` (must be an array, \" +\n \"use `[]` to opt out of the missingness merge)\",\n });\n }\n\n // ── C1: code format + uniqueness ──────────────────────────────────────────\n const codeRe = /^\\d{2}(-\\d{2}){6}$/;\n const seenCodes = new Set<string>();\n for (const entry of entries) {\n if (!codeRe.test(entry.code)) {\n errors.push({\n invariant: \"C1\",\n message: `code does not match /^\\\\d{2}(-\\\\d{2}){6}$/`,\n code: entry.code,\n key: entry.key,\n });\n }\n if (seenCodes.has(entry.code)) {\n errors.push({\n invariant: \"C1\",\n message: `duplicate code`,\n code: entry.code,\n key: entry.key,\n });\n }\n seenCodes.add(entry.code);\n }\n\n // ── C2: key format + uniqueness ───────────────────────────────────────────\n const keyRe = /^[a-z][a-z0-9_]*$/;\n const seenKeys = new Set<string>();\n for (const entry of entries) {\n if (!keyRe.test(entry.key)) {\n errors.push({\n invariant: \"C2\",\n message: `key does not match /^[a-z][a-z0-9_]*$/`,\n code: entry.code,\n key: entry.key,\n });\n }\n if (seenKeys.has(entry.key)) {\n errors.push({\n invariant: \"C2\",\n message: `duplicate key`,\n code: entry.code,\n key: entry.key,\n });\n }\n seenKeys.add(entry.key);\n }\n\n // Build a lookup by code for the remaining tree checks. Skip entries whose\n // code we already know is malformed — their index would be meaningless.\n const byCode = new Map<string, CvcEntry>();\n for (const entry of entries) {\n if (codeRe.test(entry.code)) byCode.set(entry.code, entry);\n }\n\n // ── C3: tree — parents resolve, no cycles ─────────────────────────────────\n for (const entry of entries) {\n if (entry.parentCode === null) continue;\n if (!byCode.has(entry.parentCode)) {\n errors.push({\n invariant: \"C3\",\n message: `parentCode ${entry.parentCode} does not resolve to any entry in this CVC`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n // Cycle detection: walk parent chain from each entry, bail if we revisit.\n for (const entry of entries) {\n const visited = new Set<string>();\n let cursor: CvcEntry | undefined = entry;\n while (cursor && cursor.parentCode !== null) {\n if (visited.has(cursor.code)) {\n errors.push({\n invariant: \"C3\",\n message: `cycle detected in parentCode chain starting from ${entry.code}`,\n code: entry.code,\n key: entry.key,\n });\n break;\n }\n visited.add(cursor.code);\n cursor = byCode.get(cursor.parentCode);\n }\n }\n\n // ── C4: childCodes are exact inverse of parentCode ────────────────────────\n // Build the set of (parent, child) edges from parentCode, then from\n // childCodes, and require they match exactly.\n const parentToChildrenFromParent = new Map<string, Set<string>>();\n for (const entry of entries) {\n if (entry.parentCode !== null) {\n let set = parentToChildrenFromParent.get(entry.parentCode);\n if (!set) {\n set = new Set();\n parentToChildrenFromParent.set(entry.parentCode, set);\n }\n set.add(entry.code);\n }\n }\n\n for (const entry of entries) {\n const declared = new Set(entry.childCodes);\n const derived = parentToChildrenFromParent.get(entry.code) ?? new Set();\n\n for (const child of declared) {\n if (!derived.has(child)) {\n errors.push({\n invariant: \"C4\",\n message: `entry lists ${child} in childCodes but that entry's parentCode is not ${entry.code}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n for (const child of derived) {\n if (!declared.has(child)) {\n errors.push({\n invariant: \"C4\",\n message: `entry ${child} has parentCode ${entry.code} but is missing from its childCodes`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n }\n\n // ── C5: selectability per §4.4 ────────────────────────────────────────────\n // Zod already enforces `selectable: boolean`; we make the invariant explicit\n // at validator level so a future schema loosening cannot silently bypass it.\n for (const entry of entries) {\n if (typeof entry.selectable !== \"boolean\") {\n errors.push({\n invariant: \"C5\",\n message: `selectable must be a boolean, got ${typeof entry.selectable}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n // ── C6: cross-CVC refs — `relevantMechanisms` resolves against provided set\n if (options.mechanismKeys) {\n for (const entry of entries) {\n const raw = (entry as unknown as Record<string, unknown>)[\n \"relevantMechanisms\"\n ];\n if (raw === undefined || raw === null) continue;\n if (!Array.isArray(raw)) {\n errors.push({\n invariant: \"C6\",\n message: `relevantMechanisms must be an array or null`,\n code: entry.code,\n key: entry.key,\n });\n continue;\n }\n for (const mechKey of raw) {\n if (\n typeof mechKey !== \"string\" ||\n !options.mechanismKeys.has(mechKey)\n ) {\n errors.push({\n invariant: \"C6\",\n message: `relevantMechanisms references unknown service_mechanisms key: ${String(mechKey)}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n }\n }\n\n // ── C8: legacy `'provided'` key guard ─────────────────────────────────────\n // Walk every property of every entry (including nested arrays) looking for\n // a key named `'provided'`. It is a Thread UI label, not a canonical state.\n const walkForProvided = (value: unknown, entry: CvcEntry): void => {\n if (value === null || value === undefined) return;\n if (Array.isArray(value)) {\n for (const item of value) walkForProvided(item, entry);\n return;\n }\n if (typeof value === \"object\") {\n for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n if (k === \"provided\") {\n errors.push({\n invariant: \"C8\",\n message: `entry contains forbidden legacy key 'provided' (see locked spec §4)`,\n code: entry.code,\n key: entry.key,\n });\n }\n walkForProvided(v, entry);\n }\n }\n };\n for (const entry of entries) {\n walkForProvided(entry, entry);\n // Also guard against a literal string value of 'provided' appearing as an\n // entry's `key`, which would be an obvious smuggling attempt.\n if (entry.key === \"provided\") {\n errors.push({\n invariant: \"C8\",\n message: `entry key must not be the legacy label 'provided'`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n return errors;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACuBA,iBAAkB;AASX,IAAM,gBAAgB,aAAE,OAAO,EAAE,MAAM,oBAAoB;AAQ3D,IAAM,eAAe,aAAE,OAAO,EAAE,MAAM,mBAAmB;AAezD,IAAM,iBAAiB,aAC3B,OAAO;AAAA,EACN,MAAM;AAAA,EACN,KAAK;AAAA,EACL,OAAO,aAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACvB,YAAY,aAAE,QAAQ;AAAA,EACtB,YAAY,cAAc,SAAS;AAAA,EACnC,YAAY,aAAE,MAAM,aAAa;AAAA,EACjC,YAAY,aAAE,OAAO,EAAE,SAAS;AAClC,CAAC,EACA,YAAY;AAOR,IAAM,6BAA6B,eAAe,OAAO;AAAA,EAC9D,oBAAoB,aAAE,MAAM,YAAY,EAAE,SAAS;AACrD,CAAC;AAiBM,IAAM,oBAAoB,aAAE,OAAO;AAAA,EACxC,QAAQ,aAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACxB,MAAM,aAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACtB,SAAS,aAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACzB,aAAa,aAAE,MAAM,aAAE,OAAO,CAAC,EAAE,SAAS;AAAA,EAC1C,QAAQ,aAAE,OAAO,aAAE,OAAO,GAAG,aAAE,OAAO,CAAC;AAAA,EACvC,SAAS,aAAE,MAAM,cAAc;AACjC,CAAC;AA4BM,SAAS,YAAY,MAAsB;AAChD,QAAM,WAAW,KAAK,MAAM,GAAG;AAE/B,MAAI,SAAS,CAAC,MAAM,KAAM,QAAO;AAGjC,WAAS,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG;AAC9B,QAAI,SAAS,CAAC,MAAM,KAAM,QAAO;AAAA,EACnC;AACA,SAAO;AACT;AA2CO,SAAS,YACd,UACA,UAAmD,CAAC,GAC9B;AACtB,QAAM,SAA+B,CAAC;AACtC,QAAM,EAAE,QAAQ,IAAI;AAUpB,MAAI,SAAS,WAAW,iBAAiB,SAAS,gBAAgB,QAAW;AAC3E,WAAO,KAAK;AAAA,MACV,WAAW;AAAA,MACX,SACE;AAAA,IAEJ,CAAC;AAAA,EACH;AAGA,QAAM,SAAS;AACf,QAAM,YAAY,oBAAI,IAAY;AAClC,aAAW,SAAS,SAAS;AAC3B,QAAI,CAAC,OAAO,KAAK,MAAM,IAAI,GAAG;AAC5B,aAAO,KAAK;AAAA,QACV,WAAW;AAAA,QACX,SAAS;AAAA,QACT,MAAM,MAAM;AAAA,QACZ,KAAK,MAAM;AAAA,MACb,CAAC;AAAA,IACH;AACA,QAAI,UAAU,IAAI,MAAM,IAAI,GAAG;AAC7B,aAAO,KAAK;AAAA,QACV,WAAW;AAAA,QACX,SAAS;AAAA,QACT,MAAM,MAAM;AAAA,QACZ,KAAK,MAAM;AAAA,MACb,CAAC;AAAA,IACH;AACA,cAAU,IAAI,MAAM,IAAI;AAAA,EAC1B;AAGA,QAAM,QAAQ;AACd,QAAM,WAAW,oBAAI,IAAY;AACjC,aAAW,SAAS,SAAS;AAC3B,QAAI,CAAC,MAAM,KAAK,MAAM,GAAG,GAAG;AAC1B,aAAO,KAAK;AAAA,QACV,WAAW;AAAA,QACX,SAAS;AAAA,QACT,MAAM,MAAM;AAAA,QACZ,KAAK,MAAM;AAAA,MACb,CAAC;AAAA,IACH;AACA,QAAI,SAAS,IAAI,MAAM,GAAG,GAAG;AAC3B,aAAO,KAAK;AAAA,QACV,WAAW;AAAA,QACX,SAAS;AAAA,QACT,MAAM,MAAM;AAAA,QACZ,KAAK,MAAM;AAAA,MACb,CAAC;AAAA,IACH;AACA,aAAS,IAAI,MAAM,GAAG;AAAA,EACxB;AAIA,QAAM,SAAS,oBAAI,IAAsB;AACzC,aAAW,SAAS,SAAS;AAC3B,QAAI,OAAO,KAAK,MAAM,IAAI,EAAG,QAAO,IAAI,MAAM,MAAM,KAAK;AAAA,EAC3D;AAGA,aAAW,SAAS,SAAS;AAC3B,QAAI,MAAM,eAAe,KAAM;AAC/B,QAAI,CAAC,OAAO,IAAI,MAAM,UAAU,GAAG;AACjC,aAAO,KAAK;AAAA,QACV,WAAW;AAAA,QACX,SAAS,cAAc,MAAM,UAAU;AAAA,QACvC,MAAM,MAAM;AAAA,QACZ,KAAK,MAAM;AAAA,MACb,CAAC;AAAA,IACH;AAAA,EACF;AAGA,aAAW,SAAS,SAAS;AAC3B,UAAM,UAAU,oBAAI,IAAY;AAChC,QAAI,SAA+B;AACnC,WAAO,UAAU,OAAO,eAAe,MAAM;AAC3C,UAAI,QAAQ,IAAI,OAAO,IAAI,GAAG;AAC5B,eAAO,KAAK;AAAA,UACV,WAAW;AAAA,UACX,SAAS,oDAAoD,MAAM,IAAI;AAAA,UACvE,MAAM,MAAM;AAAA,UACZ,KAAK,MAAM;AAAA,QACb,CAAC;AACD;AAAA,MACF;AACA,cAAQ,IAAI,OAAO,IAAI;AACvB,eAAS,OAAO,IAAI,OAAO,UAAU;AAAA,IACvC;AAAA,EACF;AAKA,QAAM,6BAA6B,oBAAI,IAAyB;AAChE,aAAW,SAAS,SAAS;AAC3B,QAAI,MAAM,eAAe,MAAM;AAC7B,UAAI,MAAM,2BAA2B,IAAI,MAAM,UAAU;AACzD,UAAI,CAAC,KAAK;AACR,cAAM,oBAAI,IAAI;AACd,mCAA2B,IAAI,MAAM,YAAY,GAAG;AAAA,MACtD;AACA,UAAI,IAAI,MAAM,IAAI;AAAA,IACpB;AAAA,EACF;AAEA,aAAW,SAAS,SAAS;AAC3B,UAAM,WAAW,IAAI,IAAI,MAAM,UAAU;AACzC,UAAM,UAAU,2BAA2B,IAAI,MAAM,IAAI,KAAK,oBAAI,IAAI;AAEtE,eAAW,SAAS,UAAU;AAC5B,UAAI,CAAC,QAAQ,IAAI,KAAK,GAAG;AACvB,eAAO,KAAK;AAAA,UACV,WAAW;AAAA,UACX,SAAS,eAAe,KAAK,qDAAqD,MAAM,IAAI;AAAA,UAC5F,MAAM,MAAM;AAAA,UACZ,KAAK,MAAM;AAAA,QACb,CAAC;AAAA,MACH;AAAA,IACF;AACA,eAAW,SAAS,SAAS;AAC3B,UAAI,CAAC,SAAS,IAAI,KAAK,GAAG;AACxB,eAAO,KAAK;AAAA,UACV,WAAW;AAAA,UACX,SAAS,SAAS,KAAK,mBAAmB,MAAM,IAAI;AAAA,UACpD,MAAM,MAAM;AAAA,UACZ,KAAK,MAAM;AAAA,QACb,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AAKA,aAAW,SAAS,SAAS;AAC3B,QAAI,OAAO,MAAM,eAAe,WAAW;AACzC,aAAO,KAAK;AAAA,QACV,WAAW;AAAA,QACX,SAAS,qCAAqC,OAAO,MAAM,UAAU;AAAA,QACrE,MAAM,MAAM;AAAA,QACZ,KAAK,MAAM;AAAA,MACb,CAAC;AAAA,IACH;AAAA,EACF;AAGA,MAAI,QAAQ,eAAe;AACzB,eAAW,SAAS,SAAS;AAC3B,YAAM,MAAO,MACX,oBACF;AACA,UAAI,QAAQ,UAAa,QAAQ,KAAM;AACvC,UAAI,CAAC,MAAM,QAAQ,GAAG,GAAG;AACvB,eAAO,KAAK;AAAA,UACV,WAAW;AAAA,UACX,SAAS;AAAA,UACT,MAAM,MAAM;AAAA,UACZ,KAAK,MAAM;AAAA,QACb,CAAC;AACD;AAAA,MACF;AACA,iBAAW,WAAW,KAAK;AACzB,YACE,OAAO,YAAY,YACnB,CAAC,QAAQ,cAAc,IAAI,OAAO,GAClC;AACA,iBAAO,KAAK;AAAA,YACV,WAAW;AAAA,YACX,SAAS,iEAAiE,OAAO,OAAO,CAAC;AAAA,YACzF,MAAM,MAAM;AAAA,YACZ,KAAK,MAAM;AAAA,UACb,CAAC;AAAA,QACH;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAKA,QAAM,kBAAkB,CAAC,OAAgB,UAA0B;AACjE,QAAI,UAAU,QAAQ,UAAU,OAAW;AAC3C,QAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,iBAAW,QAAQ,MAAO,iBAAgB,MAAM,KAAK;AACrD;AAAA,IACF;AACA,QAAI,OAAO,UAAU,UAAU;AAC7B,iBAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,KAAgC,GAAG;AACrE,YAAI,MAAM,YAAY;AACpB,iBAAO,KAAK;AAAA,YACV,WAAW;AAAA,YACX,SAAS;AAAA,YACT,MAAM,MAAM;AAAA,YACZ,KAAK,MAAM;AAAA,UACb,CAAC;AAAA,QACH;AACA,wBAAgB,GAAG,KAAK;AAAA,MAC1B;AAAA,IACF;AAAA,EACF;AACA,aAAW,SAAS,SAAS;AAC3B,oBAAgB,OAAO,KAAK;AAG5B,QAAI,MAAM,QAAQ,YAAY;AAC5B,aAAO,KAAK;AAAA,QACV,WAAW;AAAA,QACX,SAAS;AAAA,QACT,MAAM,MAAM;AAAA,QACZ,KAAK,MAAM;AAAA,MACb,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AACT;","names":[]}
1
+ {"version":3,"sources":["../../src/validation/index.ts","../../src/validation/cvc.ts"],"sourcesContent":["/**\n * @htilabs/platform-common-models — Validation barrel\n *\n * Public entry point for the Zod validation surface. Consumers that want\n * the canonical Zod-inferred `CvcEntry` (rather than the Mongoose persistence\n * shape exported from the package root) should import from here:\n *\n * ```ts\n * import { CvcEntry, CvcEntrySchema } from '@htilabs/platform-common-models/validation';\n * ```\n *\n * See `./cvc.ts` for the schema and type definitions.\n */\n\nexport * from \"./cvc.js\";\n","/**\n * @htilabs/platform-common-models — Controlled Vocabulary (CVC) Validation\n *\n * Zod schemas for validating CVC Source-of-Truth (SOT) JSON files and\n * individual CVC entries. Implements the locked spec §9.2 shapes.\n *\n * Used by:\n * - CI structural tests that parse every committed SOT file.\n * - The generalized seed CLI (`seedCvc`) prior to persistence.\n * - Downstream consumers that need to validate CVC payloads.\n *\n * Canonical spec:\n * /gt/docs/data/cvcs/CVC Implementation Spec 2780449faf8045258c67daab0f1c5569.md\n *\n * Format v2 (2026-04-15):\n * - Positional 7-segment codes `XXX-XXX-XXX-XXX-XXX-XXX-XXX` (3 digits per\n * segment). Segment 1 is the Notion-aligned domain prefix:\n * `022` service_categories (CVC-22)\n * `025` service_mechanisms (CVC-25)\n * `049` service_states (CVC-49)\n * - Missingness entries are embedded per-domain (synthetic `missingness_root`\n * at `<prefix>-000-000-000-000-000-000` plus three values at segment 7 =\n * `001`/`002`/`003`). The shared `missingness.v1.0.0.json` file was\n * retired in favor of per-domain missingness.\n * - Envelope `missingness` field and the C7 invariant have been removed; the\n * shared-merge pathway no longer exists.\n */\n\nimport { z } from \"zod\";\n\n// ─── Primitive schemas ───────────────────────────────────────────────────────\n\n/**\n * 7-segment positional CVC code: `XXX-XXX-XXX-XXX-XXX-XXX-XXX` (three digits\n * per segment). Segment 1 is the Notion-aligned domain prefix. Remaining\n * hierarchy segments are filled left-to-right as levels deepen; unused\n * segments remain `000`. See locked spec §3 (format v2).\n */\nexport const CvcCodeSchema = z.string().regex(/^\\d{3}(-\\d{3}){6}$/);\n\n/**\n * Stable machine key for a CVC entry. Must start with a lowercase letter and\n * contain only lowercase alphanumerics or underscores. Used as a cross-CVC\n * reference target (e.g. `relevantMechanisms` pointing at mechanism keys).\n * See locked spec §3.2.\n */\nexport const CvcKeySchema = z.string().regex(/^[a-z][a-z0-9_]*$/);\n\n// ─── Entry schemas ───────────────────────────────────────────────────────────\n\n/**\n * Base entry shape shared by every CVC domain. Domain-specific extensions\n * (e.g. `ServiceCategoryEntrySchema`) should use `.extend()` to add fields.\n * See locked spec §9.2.\n *\n * Uses `.passthrough()` so that domain-specific fields (like\n * `relevantMechanisms` on service-category entries) survive base parsing\n * unmodified. This keeps cross-CVC reference validation honest: the §4.5\n * structural validator needs to see the raw referenced keys, and a strip-by-\n * default schema would silently hide them.\n */\nexport const CvcEntrySchema = z\n .object({\n code: CvcCodeSchema,\n key: CvcKeySchema,\n title: z.string().min(1),\n selectable: z.boolean(),\n parentCode: CvcCodeSchema.nullable(),\n childCodes: z.array(CvcCodeSchema),\n definition: z.string().nullable(),\n })\n .passthrough();\n\n/**\n * Service-category-specific entry. Adds `relevantMechanisms` — a cross-CVC\n * reference into the `service_mechanisms` domain via entry keys. `null` means\n * \"not applicable\" (e.g. structural L1 topic rows). See locked spec §9.2.\n */\nexport const ServiceCategoryEntrySchema = CvcEntrySchema.extend({\n relevantMechanisms: z.array(CvcKeySchema).nullable(),\n});\n\n// ─── Envelope schema ─────────────────────────────────────────────────────────\n\n/**\n * Top-level SOT JSON envelope. One envelope per (domain, version) pair.\n *\n * `levels` is a positional map from level number (`\"0\"`, `\"1\"`, …) to a human\n * label describing the level. Missingness entries are embedded in `entries`\n * (per-domain) rather than merged in from a shared SOT file; see module\n * header for the v2 format summary.\n */\nexport const CvcEnvelopeSchema = z.object({\n domain: z.string().min(1),\n name: z.string().min(1),\n version: z.string().min(1),\n levels: z.record(z.string(), z.string()),\n entries: z.array(CvcEntrySchema),\n});\n\n// ─── Inferred types ──────────────────────────────────────────────────────────\n\nexport type CvcCode = z.infer<typeof CvcCodeSchema>;\nexport type CvcKey = z.infer<typeof CvcKeySchema>;\nexport type CvcEntry = z.infer<typeof CvcEntrySchema>;\nexport type ServiceCategoryEntry = z.infer<typeof ServiceCategoryEntrySchema>;\nexport type CvcEnvelope = z.infer<typeof CvcEnvelopeSchema>;\n\n/**\n * SOT family identifier (e.g. `\"service_categories\"`, `\"service_states\"`,\n * `\"service_mechanisms\"`, `\"missingness\"`). The canonical list of domains is\n * enumerated by the SOT JSON files in `src/cvcs/`. Typed as `string` rather\n * than a closed union so adding a new SOT file does not require touching this\n * type. See locked spec §2.\n */\nexport type CvcDomain = string;\n\n// ─── Structural validator (locked spec §4 / §9.3) ───────────────────────────\n\n/**\n * Derive an entry's level from its 7-segment code per locked spec §3.3.\n *\n * - Segment 7 non-zero → level 0 (missingness value entry, e.g. `unknown`).\n * - Otherwise return the index (1..5) of the last non-zero hierarchy segment.\n * - Hierarchy segments 2..7 all zero → level 0 (per-domain missingness root,\n * e.g. `022-000-000-000-000-000-000`). Segment 1 carries the domain prefix\n * and is intentionally not consulted by the level derivation.\n */\nexport function getCvcLevel(code: string): number {\n const segments = code.split(\"-\");\n // segments[6] is the missingness slot (positional segment 7).\n if (segments[6] !== \"000\") return 0;\n // Walk hierarchy segments 6..2 (indices 5..1) looking for the deepest\n // populated level.\n for (let i = 5; i >= 1; i -= 1) {\n if (segments[i] !== \"000\") return i;\n }\n return 0;\n}\n\n/**\n * Error collected by {@link validateCvc}. Each error names the invariant it\n * violates (`C1`..`C8`, skipping the retired `C7`) so CI output points\n * straight at the locked spec rule that failed. `code` or `key` narrow the\n * error to a specific entry when the violation is entry-scoped.\n */\nexport interface CvcValidationError {\n invariant: \"C1\" | \"C2\" | \"C3\" | \"C4\" | \"C5\" | \"C6\" | \"C8\";\n message: string;\n code?: string;\n key?: string;\n}\n\n/**\n * Structural invariants to enforce on every committed SOT file per locked spec\n * §4. Zod's schema `parse()` guarantees the *shape* of the envelope; this\n * function enforces the cross-entry *semantics* that Zod cannot express.\n *\n * Invariants (locked spec §4):\n * - **C1** Code format + uniqueness (§4.1). Format v2 uses 3-digit segments.\n * - **C2** Key format + uniqueness (§4.2).\n * - **C3** Tree: every `parentCode` resolves to an existing entry or null; no\n * cycles (§4.3).\n * - **C4** `childCodes` are the exact bidirectional inverse of `parentCode`\n * (§4.3).\n * - **C5** Selectability is a boolean (§4.4).\n * - **C6** Cross-CVC `relevantMechanisms` references resolve against a\n * provided `service_mechanisms` key set (§4.5, §7). Only checked when the\n * caller supplies `options.mechanismKeys`.\n * - **C7** _Retired in format v2_ (envelope no longer carries the shared\n * `missingness` field; missingness is per-domain and embedded in\n * `entries`). The invariant slot is intentionally left empty to preserve\n * the numbering of C1/C2/C3/C4/C5/C6/C8 in historical references.\n * - **C8** No entry anywhere contains a key `'provided'` (legacy Thread UI\n * label guard; not a canonical state).\n *\n * @param envelope Parsed envelope (typically from `CvcEnvelopeSchema.parse()`).\n * @param options.mechanismKeys Optional set of valid `service_mechanisms`\n * entry keys. If provided and the envelope entries have `relevantMechanisms`\n * fields, each referenced key must be in this set (C6).\n * @returns An array of {@link CvcValidationError}. An empty array means valid.\n */\nexport function validateCvc(\n envelope: CvcEnvelope,\n options: { mechanismKeys?: ReadonlySet<string> } = {},\n): CvcValidationError[] {\n const errors: CvcValidationError[] = [];\n const { entries } = envelope;\n\n // ── C1: code format + uniqueness ──────────────────────────────────────────\n const codeRe = /^\\d{3}(-\\d{3}){6}$/;\n const seenCodes = new Set<string>();\n for (const entry of entries) {\n if (!codeRe.test(entry.code)) {\n errors.push({\n invariant: \"C1\",\n message: `code does not match /^\\\\d{3}(-\\\\d{3}){6}$/`,\n code: entry.code,\n key: entry.key,\n });\n }\n if (seenCodes.has(entry.code)) {\n errors.push({\n invariant: \"C1\",\n message: `duplicate code`,\n code: entry.code,\n key: entry.key,\n });\n }\n seenCodes.add(entry.code);\n }\n\n // ── C2: key format + uniqueness ───────────────────────────────────────────\n const keyRe = /^[a-z][a-z0-9_]*$/;\n const seenKeys = new Set<string>();\n for (const entry of entries) {\n if (!keyRe.test(entry.key)) {\n errors.push({\n invariant: \"C2\",\n message: `key does not match /^[a-z][a-z0-9_]*$/`,\n code: entry.code,\n key: entry.key,\n });\n }\n if (seenKeys.has(entry.key)) {\n errors.push({\n invariant: \"C2\",\n message: `duplicate key`,\n code: entry.code,\n key: entry.key,\n });\n }\n seenKeys.add(entry.key);\n }\n\n // Build a lookup by code for the remaining tree checks. Skip entries whose\n // code we already know is malformed — their index would be meaningless.\n const byCode = new Map<string, CvcEntry>();\n for (const entry of entries) {\n if (codeRe.test(entry.code)) byCode.set(entry.code, entry);\n }\n\n // ── C3: tree — parents resolve, no cycles ─────────────────────────────────\n for (const entry of entries) {\n if (entry.parentCode === null) continue;\n if (!byCode.has(entry.parentCode)) {\n errors.push({\n invariant: \"C3\",\n message: `parentCode ${entry.parentCode} does not resolve to any entry in this CVC`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n // Cycle detection: walk parent chain from each entry, bail if we revisit.\n for (const entry of entries) {\n const visited = new Set<string>();\n let cursor: CvcEntry | undefined = entry;\n while (cursor && cursor.parentCode !== null) {\n if (visited.has(cursor.code)) {\n errors.push({\n invariant: \"C3\",\n message: `cycle detected in parentCode chain starting from ${entry.code}`,\n code: entry.code,\n key: entry.key,\n });\n break;\n }\n visited.add(cursor.code);\n cursor = byCode.get(cursor.parentCode);\n }\n }\n\n // ── C4: childCodes are exact inverse of parentCode ────────────────────────\n // Build the set of (parent, child) edges from parentCode, then from\n // childCodes, and require they match exactly.\n const parentToChildrenFromParent = new Map<string, Set<string>>();\n for (const entry of entries) {\n if (entry.parentCode !== null) {\n let set = parentToChildrenFromParent.get(entry.parentCode);\n if (!set) {\n set = new Set();\n parentToChildrenFromParent.set(entry.parentCode, set);\n }\n set.add(entry.code);\n }\n }\n\n for (const entry of entries) {\n const declared = new Set(entry.childCodes);\n const derived = parentToChildrenFromParent.get(entry.code) ?? new Set();\n\n for (const child of declared) {\n if (!derived.has(child)) {\n errors.push({\n invariant: \"C4\",\n message: `entry lists ${child} in childCodes but that entry's parentCode is not ${entry.code}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n for (const child of derived) {\n if (!declared.has(child)) {\n errors.push({\n invariant: \"C4\",\n message: `entry ${child} has parentCode ${entry.code} but is missing from its childCodes`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n }\n\n // ── C5: selectability per §4.4 ────────────────────────────────────────────\n // Zod already enforces `selectable: boolean`; we make the invariant explicit\n // at validator level so a future schema loosening cannot silently bypass it.\n for (const entry of entries) {\n if (typeof entry.selectable !== \"boolean\") {\n errors.push({\n invariant: \"C5\",\n message: `selectable must be a boolean, got ${typeof entry.selectable}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n // ── C6: cross-CVC refs — `relevantMechanisms` resolves against provided set\n if (options.mechanismKeys) {\n for (const entry of entries) {\n const raw = (entry as unknown as Record<string, unknown>)[\n \"relevantMechanisms\"\n ];\n if (raw === undefined || raw === null) continue;\n if (!Array.isArray(raw)) {\n errors.push({\n invariant: \"C6\",\n message: `relevantMechanisms must be an array or null`,\n code: entry.code,\n key: entry.key,\n });\n continue;\n }\n for (const mechKey of raw) {\n if (\n typeof mechKey !== \"string\" ||\n !options.mechanismKeys.has(mechKey)\n ) {\n errors.push({\n invariant: \"C6\",\n message: `relevantMechanisms references unknown service_mechanisms key: ${String(mechKey)}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n }\n }\n\n // ── C8: legacy `'provided'` key guard ─────────────────────────────────────\n // Walk every property of every entry (including nested arrays) looking for\n // a key named `'provided'`. It is a Thread UI label, not a canonical state.\n const walkForProvided = (value: unknown, entry: CvcEntry): void => {\n if (value === null || value === undefined) return;\n if (Array.isArray(value)) {\n for (const item of value) walkForProvided(item, entry);\n return;\n }\n if (typeof value === \"object\") {\n for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n if (k === \"provided\") {\n errors.push({\n invariant: \"C8\",\n message: `entry contains forbidden legacy key 'provided' (see locked spec §4)`,\n code: entry.code,\n key: entry.key,\n });\n }\n walkForProvided(v, entry);\n }\n }\n };\n for (const entry of entries) {\n walkForProvided(entry, entry);\n // Also guard against a literal string value of 'provided' appearing as an\n // entry's `key`, which would be an obvious smuggling attempt.\n if (entry.key === \"provided\") {\n errors.push({\n invariant: \"C8\",\n message: `entry key must not be the legacy label 'provided'`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n return errors;\n}\n"],"mappings":"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","names":[]}
@@ -14,19 +14,25 @@ import { z } from 'zod';
14
14
  * Canonical spec:
15
15
  * /gt/docs/data/cvcs/CVC Implementation Spec 2780449faf8045258c67daab0f1c5569.md
16
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).
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.
24
29
  */
25
30
 
26
31
  /**
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.
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).
30
36
  */
31
37
  declare const CvcCodeSchema: z.ZodString;
32
38
  /**
@@ -111,21 +117,15 @@ declare const ServiceCategoryEntrySchema: z.ZodObject<{
111
117
  /**
112
118
  * Top-level SOT JSON envelope. One envelope per (domain, version) pair.
113
119
  *
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
120
  * `levels` is a positional map from level number (`"0"`, `"1"`, …) to a human
122
- * label describing the level.
121
+ * label describing the level. Missingness entries are embedded in `entries`
122
+ * (per-domain) rather than merged in from a shared SOT file; see module
123
+ * header for the v2 format summary.
123
124
  */
124
125
  declare const CvcEnvelopeSchema: z.ZodObject<{
125
126
  domain: z.ZodString;
126
127
  name: z.ZodString;
127
128
  version: z.ZodString;
128
- missingness: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
129
129
  levels: z.ZodRecord<z.ZodString, z.ZodString>;
130
130
  entries: z.ZodArray<z.ZodObject<{
131
131
  code: z.ZodString;
@@ -166,7 +166,6 @@ declare const CvcEnvelopeSchema: z.ZodObject<{
166
166
  }, z.ZodTypeAny, "passthrough">[];
167
167
  domain: string;
168
168
  levels: Record<string, string>;
169
- missingness?: string[] | undefined;
170
169
  }, {
171
170
  name: string;
172
171
  version: string;
@@ -181,7 +180,6 @@ declare const CvcEnvelopeSchema: z.ZodObject<{
181
180
  }, z.ZodTypeAny, "passthrough">[];
182
181
  domain: string;
183
182
  levels: Record<string, string>;
184
- missingness?: string[] | undefined;
185
183
  }>;
186
184
  type CvcCode = z.infer<typeof CvcCodeSchema>;
187
185
  type CvcKey = z.infer<typeof CvcKeySchema>;
@@ -201,17 +199,19 @@ type CvcDomain = string;
201
199
  *
202
200
  * - Segment 7 non-zero → level 0 (missingness value entry, e.g. `unknown`).
203
201
  * - 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`).
202
+ * - Hierarchy segments 2..7 all zero → level 0 (per-domain missingness root,
203
+ * e.g. `022-000-000-000-000-000-000`). Segment 1 carries the domain prefix
204
+ * and is intentionally not consulted by the level derivation.
205
205
  */
206
206
  declare function getCvcLevel(code: string): number;
207
207
  /**
208
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.
209
+ * violates (`C1`..`C8`, skipping the retired `C7`) so CI output points
210
+ * straight at the locked spec rule that failed. `code` or `key` narrow the
211
+ * error to a specific entry when the violation is entry-scoped.
212
212
  */
213
213
  interface CvcValidationError {
214
- invariant: "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8";
214
+ invariant: "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C8";
215
215
  message: string;
216
216
  code?: string;
217
217
  key?: string;
@@ -222,7 +222,7 @@ interface CvcValidationError {
222
222
  * function enforces the cross-entry *semantics* that Zod cannot express.
223
223
  *
224
224
  * Invariants (locked spec §4):
225
- * - **C1** Code format + uniqueness (§4.1).
225
+ * - **C1** Code format + uniqueness (§4.1). Format v2 uses 3-digit segments.
226
226
  * - **C2** Key format + uniqueness (§4.2).
227
227
  * - **C3** Tree: every `parentCode` resolves to an existing entry or null; no
228
228
  * cycles (§4.3).
@@ -232,9 +232,10 @@ interface CvcValidationError {
232
232
  * - **C6** Cross-CVC `relevantMechanisms` references resolve against a
233
233
  * provided `service_mechanisms` key set (§4.5, §7). Only checked when the
234
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).
235
+ * - **C7** _Retired in format v2_ (envelope no longer carries the shared
236
+ * `missingness` field; missingness is per-domain and embedded in
237
+ * `entries`). The invariant slot is intentionally left empty to preserve
238
+ * the numbering of C1/C2/C3/C4/C5/C6/C8 in historical references.
238
239
  * - **C8** No entry anywhere contains a key `'provided'` (legacy Thread UI
239
240
  * label guard; not a canonical state).
240
241
  *
@@ -14,19 +14,25 @@ import { z } from 'zod';
14
14
  * Canonical spec:
15
15
  * /gt/docs/data/cvcs/CVC Implementation Spec 2780449faf8045258c67daab0f1c5569.md
16
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).
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.
24
29
  */
25
30
 
26
31
  /**
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.
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).
30
36
  */
31
37
  declare const CvcCodeSchema: z.ZodString;
32
38
  /**
@@ -111,21 +117,15 @@ declare const ServiceCategoryEntrySchema: z.ZodObject<{
111
117
  /**
112
118
  * Top-level SOT JSON envelope. One envelope per (domain, version) pair.
113
119
  *
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
120
  * `levels` is a positional map from level number (`"0"`, `"1"`, …) to a human
122
- * label describing the level.
121
+ * label describing the level. Missingness entries are embedded in `entries`
122
+ * (per-domain) rather than merged in from a shared SOT file; see module
123
+ * header for the v2 format summary.
123
124
  */
124
125
  declare const CvcEnvelopeSchema: z.ZodObject<{
125
126
  domain: z.ZodString;
126
127
  name: z.ZodString;
127
128
  version: z.ZodString;
128
- missingness: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
129
129
  levels: z.ZodRecord<z.ZodString, z.ZodString>;
130
130
  entries: z.ZodArray<z.ZodObject<{
131
131
  code: z.ZodString;
@@ -166,7 +166,6 @@ declare const CvcEnvelopeSchema: z.ZodObject<{
166
166
  }, z.ZodTypeAny, "passthrough">[];
167
167
  domain: string;
168
168
  levels: Record<string, string>;
169
- missingness?: string[] | undefined;
170
169
  }, {
171
170
  name: string;
172
171
  version: string;
@@ -181,7 +180,6 @@ declare const CvcEnvelopeSchema: z.ZodObject<{
181
180
  }, z.ZodTypeAny, "passthrough">[];
182
181
  domain: string;
183
182
  levels: Record<string, string>;
184
- missingness?: string[] | undefined;
185
183
  }>;
186
184
  type CvcCode = z.infer<typeof CvcCodeSchema>;
187
185
  type CvcKey = z.infer<typeof CvcKeySchema>;
@@ -201,17 +199,19 @@ type CvcDomain = string;
201
199
  *
202
200
  * - Segment 7 non-zero → level 0 (missingness value entry, e.g. `unknown`).
203
201
  * - 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`).
202
+ * - Hierarchy segments 2..7 all zero → level 0 (per-domain missingness root,
203
+ * e.g. `022-000-000-000-000-000-000`). Segment 1 carries the domain prefix
204
+ * and is intentionally not consulted by the level derivation.
205
205
  */
206
206
  declare function getCvcLevel(code: string): number;
207
207
  /**
208
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.
209
+ * violates (`C1`..`C8`, skipping the retired `C7`) so CI output points
210
+ * straight at the locked spec rule that failed. `code` or `key` narrow the
211
+ * error to a specific entry when the violation is entry-scoped.
212
212
  */
213
213
  interface CvcValidationError {
214
- invariant: "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8";
214
+ invariant: "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C8";
215
215
  message: string;
216
216
  code?: string;
217
217
  key?: string;
@@ -222,7 +222,7 @@ interface CvcValidationError {
222
222
  * function enforces the cross-entry *semantics* that Zod cannot express.
223
223
  *
224
224
  * Invariants (locked spec §4):
225
- * - **C1** Code format + uniqueness (§4.1).
225
+ * - **C1** Code format + uniqueness (§4.1). Format v2 uses 3-digit segments.
226
226
  * - **C2** Key format + uniqueness (§4.2).
227
227
  * - **C3** Tree: every `parentCode` resolves to an existing entry or null; no
228
228
  * cycles (§4.3).
@@ -232,9 +232,10 @@ interface CvcValidationError {
232
232
  * - **C6** Cross-CVC `relevantMechanisms` references resolve against a
233
233
  * provided `service_mechanisms` key set (§4.5, §7). Only checked when the
234
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).
235
+ * - **C7** _Retired in format v2_ (envelope no longer carries the shared
236
+ * `missingness` field; missingness is per-domain and embedded in
237
+ * `entries`). The invariant slot is intentionally left empty to preserve
238
+ * the numbering of C1/C2/C3/C4/C5/C6/C8 in historical references.
238
239
  * - **C8** No entry anywhere contains a key `'provided'` (legacy Thread UI
239
240
  * label guard; not a canonical state).
240
241
  *
@@ -1,6 +1,6 @@
1
1
  // src/validation/cvc.ts
2
2
  import { z } from "zod";
3
- var CvcCodeSchema = z.string().regex(/^\d{2}(-\d{2}){6}$/);
3
+ var CvcCodeSchema = z.string().regex(/^\d{3}(-\d{3}){6}$/);
4
4
  var CvcKeySchema = z.string().regex(/^[a-z][a-z0-9_]*$/);
5
5
  var CvcEntrySchema = z.object({
6
6
  code: CvcCodeSchema,
@@ -18,34 +18,27 @@ var CvcEnvelopeSchema = z.object({
18
18
  domain: z.string().min(1),
19
19
  name: z.string().min(1),
20
20
  version: z.string().min(1),
21
- missingness: z.array(z.string()).optional(),
22
21
  levels: z.record(z.string(), z.string()),
23
22
  entries: z.array(CvcEntrySchema)
24
23
  });
25
24
  function getCvcLevel(code) {
26
25
  const segments = code.split("-");
27
- if (segments[6] !== "00") return 0;
26
+ if (segments[6] !== "000") return 0;
28
27
  for (let i = 5; i >= 1; i -= 1) {
29
- if (segments[i] !== "00") return i;
28
+ if (segments[i] !== "000") return i;
30
29
  }
31
30
  return 0;
32
31
  }
33
32
  function validateCvc(envelope, options = {}) {
34
33
  const errors = [];
35
34
  const { entries } = envelope;
36
- if (envelope.domain !== "missingness" && envelope.missingness === void 0) {
37
- errors.push({
38
- invariant: "C7",
39
- message: "envelope is missing required field `missingness` (must be an array, use `[]` to opt out of the missingness merge)"
40
- });
41
- }
42
- const codeRe = /^\d{2}(-\d{2}){6}$/;
35
+ const codeRe = /^\d{3}(-\d{3}){6}$/;
43
36
  const seenCodes = /* @__PURE__ */ new Set();
44
37
  for (const entry of entries) {
45
38
  if (!codeRe.test(entry.code)) {
46
39
  errors.push({
47
40
  invariant: "C1",
48
- message: `code does not match /^\\d{2}(-\\d{2}){6}$/`,
41
+ message: `code does not match /^\\d{3}(-\\d{3}){6}$/`,
49
42
  code: entry.code,
50
43
  key: entry.key
51
44
  });
@@ -1 +1 @@
1
- {"version":3,"sources":["../../src/validation/cvc.ts"],"sourcesContent":["/**\n * @htilabs/platform-common-models — Controlled Vocabulary (CVC) Validation\n *\n * Zod schemas for validating CVC Source-of-Truth (SOT) JSON files and\n * individual CVC entries. Implements the locked spec §9.2 shapes.\n *\n * Used by:\n * - CI structural tests that parse every committed SOT file.\n * - The generalized seed CLI (`seedCvc`) prior to persistence.\n * - Downstream consumers that need to validate CVC payloads.\n *\n * Canonical spec:\n * /gt/docs/data/cvcs/CVC Implementation Spec 2780449faf8045258c67daab0f1c5569.md\n *\n * Locked decisions (2026-04-10):\n * - Positional 7-segment codes `XX-XX-XX-XX-XX-XX-XX` (§3).\n * - `missingness` envelope field is an optional `string[]`; `[\"all\"]` is the\n * sentinel meaning \"merge all missingness values\" (§2.1, §5.2).\n * - `missingness.v1.0.0.json` wraps its values under a synthetic root\n * (`missingness_root`) which is the one sanctioned parent-child exception\n * for level-consistency, scoped by segment-1 domain prefix (§5.1).\n */\n\nimport { z } from \"zod\";\n\n// ─── Primitive schemas ───────────────────────────────────────────────────────\n\n/**\n * 7-segment positional CVC code: `XX-XX-XX-XX-XX-XX-XX` (two digits per\n * segment). Segments are filled left-to-right as levels deepen; unused\n * segments remain `00`. See locked spec §3.\n */\nexport const CvcCodeSchema = z.string().regex(/^\\d{2}(-\\d{2}){6}$/);\n\n/**\n * Stable machine key for a CVC entry. Must start with a lowercase letter and\n * contain only lowercase alphanumerics or underscores. Used as a cross-CVC\n * reference target (e.g. `relevantMechanisms` pointing at mechanism keys).\n * See locked spec §3.2.\n */\nexport const CvcKeySchema = z.string().regex(/^[a-z][a-z0-9_]*$/);\n\n// ─── Entry schemas ───────────────────────────────────────────────────────────\n\n/**\n * Base entry shape shared by every CVC domain. Domain-specific extensions\n * (e.g. `ServiceCategoryEntrySchema`) should use `.extend()` to add fields.\n * See locked spec §9.2.\n *\n * Uses `.passthrough()` so that domain-specific fields (like\n * `relevantMechanisms` on service-category entries) survive base parsing\n * unmodified. This keeps cross-CVC reference validation honest: the §4.5\n * structural validator needs to see the raw referenced keys, and a strip-by-\n * default schema would silently hide them.\n */\nexport const CvcEntrySchema = z\n .object({\n code: CvcCodeSchema,\n key: CvcKeySchema,\n title: z.string().min(1),\n selectable: z.boolean(),\n parentCode: CvcCodeSchema.nullable(),\n childCodes: z.array(CvcCodeSchema),\n definition: z.string().nullable(),\n })\n .passthrough();\n\n/**\n * Service-category-specific entry. Adds `relevantMechanisms` — a cross-CVC\n * reference into the `service_mechanisms` domain via entry keys. `null` means\n * \"not applicable\" (e.g. structural L1 topic rows). See locked spec §9.2.\n */\nexport const ServiceCategoryEntrySchema = CvcEntrySchema.extend({\n relevantMechanisms: z.array(CvcKeySchema).nullable(),\n});\n\n// ─── Envelope schema ─────────────────────────────────────────────────────────\n\n/**\n * Top-level SOT JSON envelope. One envelope per (domain, version) pair.\n *\n * `missingness` is an optional array of missingness keys to merge into this\n * CVC at seed time. `[\"all\"]` is the sentinel meaning \"merge the missingness\n * root plus all three value entries\". Individual keys merge only those.\n * Absent, empty, or null means \"skip missingness merge\". The missingness CVC\n * file itself omits this field because merging missingness into itself is\n * nonsensical. See locked spec §2.1 and §5.2.\n *\n * `levels` is a positional map from level number (`\"0\"`, `\"1\"`, …) to a human\n * label describing the level.\n */\nexport const CvcEnvelopeSchema = z.object({\n domain: z.string().min(1),\n name: z.string().min(1),\n version: z.string().min(1),\n missingness: z.array(z.string()).optional(),\n levels: z.record(z.string(), z.string()),\n entries: z.array(CvcEntrySchema),\n});\n\n// ─── Inferred types ──────────────────────────────────────────────────────────\n\nexport type CvcCode = z.infer<typeof CvcCodeSchema>;\nexport type CvcKey = z.infer<typeof CvcKeySchema>;\nexport type CvcEntry = z.infer<typeof CvcEntrySchema>;\nexport type ServiceCategoryEntry = z.infer<typeof ServiceCategoryEntrySchema>;\nexport type CvcEnvelope = z.infer<typeof CvcEnvelopeSchema>;\n\n/**\n * SOT family identifier (e.g. `\"service_categories\"`, `\"service_states\"`,\n * `\"service_mechanisms\"`, `\"missingness\"`). The canonical list of domains is\n * enumerated by the SOT JSON files in `src/cvcs/`. Typed as `string` rather\n * than a closed union so adding a new SOT file does not require touching this\n * type. See locked spec §2.\n */\nexport type CvcDomain = string;\n\n// ─── Structural validator (locked spec §4 / §9.3) ───────────────────────────\n\n/**\n * Derive an entry's level from its 7-segment code per locked spec §3.3.\n *\n * - Segment 7 non-zero → level 0 (missingness value entry, e.g. `unknown`).\n * - Otherwise return the index (1..5) of the last non-zero hierarchy segment.\n * - All segments zero → level 0 (missingness root, `00-00-00-00-00-00-00`).\n */\nexport function getCvcLevel(code: string): number {\n const segments = code.split(\"-\");\n // segments[6] is the missingness slot (positional segment 7).\n if (segments[6] !== \"00\") return 0;\n // Walk hierarchy segments 6..2 (indices 5..1) looking for the deepest\n // populated level.\n for (let i = 5; i >= 1; i -= 1) {\n if (segments[i] !== \"00\") return i;\n }\n return 0;\n}\n\n/**\n * Error collected by {@link validateCvc}. Each error names the invariant it\n * violates (`C1`..`C8`) so CI output points straight at the locked spec rule\n * that failed. `code` or `key` narrow the error to a specific entry when the\n * violation is entry-scoped.\n */\nexport interface CvcValidationError {\n invariant: \"C1\" | \"C2\" | \"C3\" | \"C4\" | \"C5\" | \"C6\" | \"C7\" | \"C8\";\n message: string;\n code?: string;\n key?: string;\n}\n\n/**\n * Structural invariants to enforce on every committed SOT file per locked spec\n * §4. Zod's schema `parse()` guarantees the *shape* of the envelope; this\n * function enforces the cross-entry *semantics* that Zod cannot express.\n *\n * Invariants (locked spec §4):\n * - **C1** Code format + uniqueness (§4.1).\n * - **C2** Key format + uniqueness (§4.2).\n * - **C3** Tree: every `parentCode` resolves to an existing entry or null; no\n * cycles (§4.3).\n * - **C4** `childCodes` are the exact bidirectional inverse of `parentCode`\n * (§4.3).\n * - **C5** Selectability is a boolean (§4.4).\n * - **C6** Cross-CVC `relevantMechanisms` references resolve against a\n * provided `service_mechanisms` key set (§4.5, §7). Only checked when the\n * caller supplies `options.mechanismKeys`.\n * - **C7** Envelope has all 6 required fields (`domain`, `name`, `version`,\n * `missingness`, `levels`, `entries`) — treating the optional-in-Zod\n * `missingness` as required at CI time (§4.6).\n * - **C8** No entry anywhere contains a key `'provided'` (legacy Thread UI\n * label guard; not a canonical state).\n *\n * @param envelope Parsed envelope (typically from `CvcEnvelopeSchema.parse()`).\n * @param options.mechanismKeys Optional set of valid `service_mechanisms`\n * entry keys. If provided and the envelope entries have `relevantMechanisms`\n * fields, each referenced key must be in this set (C6).\n * @returns An array of {@link CvcValidationError}. An empty array means valid.\n */\nexport function validateCvc(\n envelope: CvcEnvelope,\n options: { mechanismKeys?: ReadonlySet<string> } = {},\n): CvcValidationError[] {\n const errors: CvcValidationError[] = [];\n const { entries } = envelope;\n\n // C7: envelope-level required fields. Zod already rejects missing `domain`,\n // `name`, `version`, `levels`, and `entries`. We additionally require\n // `missingness` to be present (even as an empty array) at CI time so the\n // seed CLI sees an explicit \"opt-out\" rather than an undefined field.\n //\n // Exemption: the `missingness` CVC file itself legitimately omits this\n // field because merging missingness into itself is nonsensical (locked spec\n // §9.2). This is the one sanctioned omission.\n if (envelope.domain !== \"missingness\" && envelope.missingness === undefined) {\n errors.push({\n invariant: \"C7\",\n message:\n \"envelope is missing required field `missingness` (must be an array, \" +\n \"use `[]` to opt out of the missingness merge)\",\n });\n }\n\n // ── C1: code format + uniqueness ──────────────────────────────────────────\n const codeRe = /^\\d{2}(-\\d{2}){6}$/;\n const seenCodes = new Set<string>();\n for (const entry of entries) {\n if (!codeRe.test(entry.code)) {\n errors.push({\n invariant: \"C1\",\n message: `code does not match /^\\\\d{2}(-\\\\d{2}){6}$/`,\n code: entry.code,\n key: entry.key,\n });\n }\n if (seenCodes.has(entry.code)) {\n errors.push({\n invariant: \"C1\",\n message: `duplicate code`,\n code: entry.code,\n key: entry.key,\n });\n }\n seenCodes.add(entry.code);\n }\n\n // ── C2: key format + uniqueness ───────────────────────────────────────────\n const keyRe = /^[a-z][a-z0-9_]*$/;\n const seenKeys = new Set<string>();\n for (const entry of entries) {\n if (!keyRe.test(entry.key)) {\n errors.push({\n invariant: \"C2\",\n message: `key does not match /^[a-z][a-z0-9_]*$/`,\n code: entry.code,\n key: entry.key,\n });\n }\n if (seenKeys.has(entry.key)) {\n errors.push({\n invariant: \"C2\",\n message: `duplicate key`,\n code: entry.code,\n key: entry.key,\n });\n }\n seenKeys.add(entry.key);\n }\n\n // Build a lookup by code for the remaining tree checks. Skip entries whose\n // code we already know is malformed — their index would be meaningless.\n const byCode = new Map<string, CvcEntry>();\n for (const entry of entries) {\n if (codeRe.test(entry.code)) byCode.set(entry.code, entry);\n }\n\n // ── C3: tree — parents resolve, no cycles ─────────────────────────────────\n for (const entry of entries) {\n if (entry.parentCode === null) continue;\n if (!byCode.has(entry.parentCode)) {\n errors.push({\n invariant: \"C3\",\n message: `parentCode ${entry.parentCode} does not resolve to any entry in this CVC`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n // Cycle detection: walk parent chain from each entry, bail if we revisit.\n for (const entry of entries) {\n const visited = new Set<string>();\n let cursor: CvcEntry | undefined = entry;\n while (cursor && cursor.parentCode !== null) {\n if (visited.has(cursor.code)) {\n errors.push({\n invariant: \"C3\",\n message: `cycle detected in parentCode chain starting from ${entry.code}`,\n code: entry.code,\n key: entry.key,\n });\n break;\n }\n visited.add(cursor.code);\n cursor = byCode.get(cursor.parentCode);\n }\n }\n\n // ── C4: childCodes are exact inverse of parentCode ────────────────────────\n // Build the set of (parent, child) edges from parentCode, then from\n // childCodes, and require they match exactly.\n const parentToChildrenFromParent = new Map<string, Set<string>>();\n for (const entry of entries) {\n if (entry.parentCode !== null) {\n let set = parentToChildrenFromParent.get(entry.parentCode);\n if (!set) {\n set = new Set();\n parentToChildrenFromParent.set(entry.parentCode, set);\n }\n set.add(entry.code);\n }\n }\n\n for (const entry of entries) {\n const declared = new Set(entry.childCodes);\n const derived = parentToChildrenFromParent.get(entry.code) ?? new Set();\n\n for (const child of declared) {\n if (!derived.has(child)) {\n errors.push({\n invariant: \"C4\",\n message: `entry lists ${child} in childCodes but that entry's parentCode is not ${entry.code}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n for (const child of derived) {\n if (!declared.has(child)) {\n errors.push({\n invariant: \"C4\",\n message: `entry ${child} has parentCode ${entry.code} but is missing from its childCodes`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n }\n\n // ── C5: selectability per §4.4 ────────────────────────────────────────────\n // Zod already enforces `selectable: boolean`; we make the invariant explicit\n // at validator level so a future schema loosening cannot silently bypass it.\n for (const entry of entries) {\n if (typeof entry.selectable !== \"boolean\") {\n errors.push({\n invariant: \"C5\",\n message: `selectable must be a boolean, got ${typeof entry.selectable}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n // ── C6: cross-CVC refs — `relevantMechanisms` resolves against provided set\n if (options.mechanismKeys) {\n for (const entry of entries) {\n const raw = (entry as unknown as Record<string, unknown>)[\n \"relevantMechanisms\"\n ];\n if (raw === undefined || raw === null) continue;\n if (!Array.isArray(raw)) {\n errors.push({\n invariant: \"C6\",\n message: `relevantMechanisms must be an array or null`,\n code: entry.code,\n key: entry.key,\n });\n continue;\n }\n for (const mechKey of raw) {\n if (\n typeof mechKey !== \"string\" ||\n !options.mechanismKeys.has(mechKey)\n ) {\n errors.push({\n invariant: \"C6\",\n message: `relevantMechanisms references unknown service_mechanisms key: ${String(mechKey)}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n }\n }\n\n // ── C8: legacy `'provided'` key guard ─────────────────────────────────────\n // Walk every property of every entry (including nested arrays) looking for\n // a key named `'provided'`. It is a Thread UI label, not a canonical state.\n const walkForProvided = (value: unknown, entry: CvcEntry): void => {\n if (value === null || value === undefined) return;\n if (Array.isArray(value)) {\n for (const item of value) walkForProvided(item, entry);\n return;\n }\n if (typeof value === \"object\") {\n for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n if (k === \"provided\") {\n errors.push({\n invariant: \"C8\",\n message: `entry contains forbidden legacy key 'provided' (see locked spec §4)`,\n code: entry.code,\n key: entry.key,\n });\n }\n walkForProvided(v, entry);\n }\n }\n };\n for (const entry of entries) {\n walkForProvided(entry, entry);\n // Also guard against a literal string value of 'provided' appearing as an\n // entry's `key`, which would be an obvious smuggling attempt.\n if (entry.key === \"provided\") {\n errors.push({\n invariant: \"C8\",\n message: `entry key must not be the legacy label 'provided'`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n return errors;\n}\n"],"mappings":"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","names":[]}
1
+ {"version":3,"sources":["../../src/validation/cvc.ts"],"sourcesContent":["/**\n * @htilabs/platform-common-models — Controlled Vocabulary (CVC) Validation\n *\n * Zod schemas for validating CVC Source-of-Truth (SOT) JSON files and\n * individual CVC entries. Implements the locked spec §9.2 shapes.\n *\n * Used by:\n * - CI structural tests that parse every committed SOT file.\n * - The generalized seed CLI (`seedCvc`) prior to persistence.\n * - Downstream consumers that need to validate CVC payloads.\n *\n * Canonical spec:\n * /gt/docs/data/cvcs/CVC Implementation Spec 2780449faf8045258c67daab0f1c5569.md\n *\n * Format v2 (2026-04-15):\n * - Positional 7-segment codes `XXX-XXX-XXX-XXX-XXX-XXX-XXX` (3 digits per\n * segment). Segment 1 is the Notion-aligned domain prefix:\n * `022` service_categories (CVC-22)\n * `025` service_mechanisms (CVC-25)\n * `049` service_states (CVC-49)\n * - Missingness entries are embedded per-domain (synthetic `missingness_root`\n * at `<prefix>-000-000-000-000-000-000` plus three values at segment 7 =\n * `001`/`002`/`003`). The shared `missingness.v1.0.0.json` file was\n * retired in favor of per-domain missingness.\n * - Envelope `missingness` field and the C7 invariant have been removed; the\n * shared-merge pathway no longer exists.\n */\n\nimport { z } from \"zod\";\n\n// ─── Primitive schemas ───────────────────────────────────────────────────────\n\n/**\n * 7-segment positional CVC code: `XXX-XXX-XXX-XXX-XXX-XXX-XXX` (three digits\n * per segment). Segment 1 is the Notion-aligned domain prefix. Remaining\n * hierarchy segments are filled left-to-right as levels deepen; unused\n * segments remain `000`. See locked spec §3 (format v2).\n */\nexport const CvcCodeSchema = z.string().regex(/^\\d{3}(-\\d{3}){6}$/);\n\n/**\n * Stable machine key for a CVC entry. Must start with a lowercase letter and\n * contain only lowercase alphanumerics or underscores. Used as a cross-CVC\n * reference target (e.g. `relevantMechanisms` pointing at mechanism keys).\n * See locked spec §3.2.\n */\nexport const CvcKeySchema = z.string().regex(/^[a-z][a-z0-9_]*$/);\n\n// ─── Entry schemas ───────────────────────────────────────────────────────────\n\n/**\n * Base entry shape shared by every CVC domain. Domain-specific extensions\n * (e.g. `ServiceCategoryEntrySchema`) should use `.extend()` to add fields.\n * See locked spec §9.2.\n *\n * Uses `.passthrough()` so that domain-specific fields (like\n * `relevantMechanisms` on service-category entries) survive base parsing\n * unmodified. This keeps cross-CVC reference validation honest: the §4.5\n * structural validator needs to see the raw referenced keys, and a strip-by-\n * default schema would silently hide them.\n */\nexport const CvcEntrySchema = z\n .object({\n code: CvcCodeSchema,\n key: CvcKeySchema,\n title: z.string().min(1),\n selectable: z.boolean(),\n parentCode: CvcCodeSchema.nullable(),\n childCodes: z.array(CvcCodeSchema),\n definition: z.string().nullable(),\n })\n .passthrough();\n\n/**\n * Service-category-specific entry. Adds `relevantMechanisms` — a cross-CVC\n * reference into the `service_mechanisms` domain via entry keys. `null` means\n * \"not applicable\" (e.g. structural L1 topic rows). See locked spec §9.2.\n */\nexport const ServiceCategoryEntrySchema = CvcEntrySchema.extend({\n relevantMechanisms: z.array(CvcKeySchema).nullable(),\n});\n\n// ─── Envelope schema ─────────────────────────────────────────────────────────\n\n/**\n * Top-level SOT JSON envelope. One envelope per (domain, version) pair.\n *\n * `levels` is a positional map from level number (`\"0\"`, `\"1\"`, …) to a human\n * label describing the level. Missingness entries are embedded in `entries`\n * (per-domain) rather than merged in from a shared SOT file; see module\n * header for the v2 format summary.\n */\nexport const CvcEnvelopeSchema = z.object({\n domain: z.string().min(1),\n name: z.string().min(1),\n version: z.string().min(1),\n levels: z.record(z.string(), z.string()),\n entries: z.array(CvcEntrySchema),\n});\n\n// ─── Inferred types ──────────────────────────────────────────────────────────\n\nexport type CvcCode = z.infer<typeof CvcCodeSchema>;\nexport type CvcKey = z.infer<typeof CvcKeySchema>;\nexport type CvcEntry = z.infer<typeof CvcEntrySchema>;\nexport type ServiceCategoryEntry = z.infer<typeof ServiceCategoryEntrySchema>;\nexport type CvcEnvelope = z.infer<typeof CvcEnvelopeSchema>;\n\n/**\n * SOT family identifier (e.g. `\"service_categories\"`, `\"service_states\"`,\n * `\"service_mechanisms\"`, `\"missingness\"`). The canonical list of domains is\n * enumerated by the SOT JSON files in `src/cvcs/`. Typed as `string` rather\n * than a closed union so adding a new SOT file does not require touching this\n * type. See locked spec §2.\n */\nexport type CvcDomain = string;\n\n// ─── Structural validator (locked spec §4 / §9.3) ───────────────────────────\n\n/**\n * Derive an entry's level from its 7-segment code per locked spec §3.3.\n *\n * - Segment 7 non-zero → level 0 (missingness value entry, e.g. `unknown`).\n * - Otherwise return the index (1..5) of the last non-zero hierarchy segment.\n * - Hierarchy segments 2..7 all zero → level 0 (per-domain missingness root,\n * e.g. `022-000-000-000-000-000-000`). Segment 1 carries the domain prefix\n * and is intentionally not consulted by the level derivation.\n */\nexport function getCvcLevel(code: string): number {\n const segments = code.split(\"-\");\n // segments[6] is the missingness slot (positional segment 7).\n if (segments[6] !== \"000\") return 0;\n // Walk hierarchy segments 6..2 (indices 5..1) looking for the deepest\n // populated level.\n for (let i = 5; i >= 1; i -= 1) {\n if (segments[i] !== \"000\") return i;\n }\n return 0;\n}\n\n/**\n * Error collected by {@link validateCvc}. Each error names the invariant it\n * violates (`C1`..`C8`, skipping the retired `C7`) so CI output points\n * straight at the locked spec rule that failed. `code` or `key` narrow the\n * error to a specific entry when the violation is entry-scoped.\n */\nexport interface CvcValidationError {\n invariant: \"C1\" | \"C2\" | \"C3\" | \"C4\" | \"C5\" | \"C6\" | \"C8\";\n message: string;\n code?: string;\n key?: string;\n}\n\n/**\n * Structural invariants to enforce on every committed SOT file per locked spec\n * §4. Zod's schema `parse()` guarantees the *shape* of the envelope; this\n * function enforces the cross-entry *semantics* that Zod cannot express.\n *\n * Invariants (locked spec §4):\n * - **C1** Code format + uniqueness (§4.1). Format v2 uses 3-digit segments.\n * - **C2** Key format + uniqueness (§4.2).\n * - **C3** Tree: every `parentCode` resolves to an existing entry or null; no\n * cycles (§4.3).\n * - **C4** `childCodes` are the exact bidirectional inverse of `parentCode`\n * (§4.3).\n * - **C5** Selectability is a boolean (§4.4).\n * - **C6** Cross-CVC `relevantMechanisms` references resolve against a\n * provided `service_mechanisms` key set (§4.5, §7). Only checked when the\n * caller supplies `options.mechanismKeys`.\n * - **C7** _Retired in format v2_ (envelope no longer carries the shared\n * `missingness` field; missingness is per-domain and embedded in\n * `entries`). The invariant slot is intentionally left empty to preserve\n * the numbering of C1/C2/C3/C4/C5/C6/C8 in historical references.\n * - **C8** No entry anywhere contains a key `'provided'` (legacy Thread UI\n * label guard; not a canonical state).\n *\n * @param envelope Parsed envelope (typically from `CvcEnvelopeSchema.parse()`).\n * @param options.mechanismKeys Optional set of valid `service_mechanisms`\n * entry keys. If provided and the envelope entries have `relevantMechanisms`\n * fields, each referenced key must be in this set (C6).\n * @returns An array of {@link CvcValidationError}. An empty array means valid.\n */\nexport function validateCvc(\n envelope: CvcEnvelope,\n options: { mechanismKeys?: ReadonlySet<string> } = {},\n): CvcValidationError[] {\n const errors: CvcValidationError[] = [];\n const { entries } = envelope;\n\n // ── C1: code format + uniqueness ──────────────────────────────────────────\n const codeRe = /^\\d{3}(-\\d{3}){6}$/;\n const seenCodes = new Set<string>();\n for (const entry of entries) {\n if (!codeRe.test(entry.code)) {\n errors.push({\n invariant: \"C1\",\n message: `code does not match /^\\\\d{3}(-\\\\d{3}){6}$/`,\n code: entry.code,\n key: entry.key,\n });\n }\n if (seenCodes.has(entry.code)) {\n errors.push({\n invariant: \"C1\",\n message: `duplicate code`,\n code: entry.code,\n key: entry.key,\n });\n }\n seenCodes.add(entry.code);\n }\n\n // ── C2: key format + uniqueness ───────────────────────────────────────────\n const keyRe = /^[a-z][a-z0-9_]*$/;\n const seenKeys = new Set<string>();\n for (const entry of entries) {\n if (!keyRe.test(entry.key)) {\n errors.push({\n invariant: \"C2\",\n message: `key does not match /^[a-z][a-z0-9_]*$/`,\n code: entry.code,\n key: entry.key,\n });\n }\n if (seenKeys.has(entry.key)) {\n errors.push({\n invariant: \"C2\",\n message: `duplicate key`,\n code: entry.code,\n key: entry.key,\n });\n }\n seenKeys.add(entry.key);\n }\n\n // Build a lookup by code for the remaining tree checks. Skip entries whose\n // code we already know is malformed — their index would be meaningless.\n const byCode = new Map<string, CvcEntry>();\n for (const entry of entries) {\n if (codeRe.test(entry.code)) byCode.set(entry.code, entry);\n }\n\n // ── C3: tree — parents resolve, no cycles ─────────────────────────────────\n for (const entry of entries) {\n if (entry.parentCode === null) continue;\n if (!byCode.has(entry.parentCode)) {\n errors.push({\n invariant: \"C3\",\n message: `parentCode ${entry.parentCode} does not resolve to any entry in this CVC`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n // Cycle detection: walk parent chain from each entry, bail if we revisit.\n for (const entry of entries) {\n const visited = new Set<string>();\n let cursor: CvcEntry | undefined = entry;\n while (cursor && cursor.parentCode !== null) {\n if (visited.has(cursor.code)) {\n errors.push({\n invariant: \"C3\",\n message: `cycle detected in parentCode chain starting from ${entry.code}`,\n code: entry.code,\n key: entry.key,\n });\n break;\n }\n visited.add(cursor.code);\n cursor = byCode.get(cursor.parentCode);\n }\n }\n\n // ── C4: childCodes are exact inverse of parentCode ────────────────────────\n // Build the set of (parent, child) edges from parentCode, then from\n // childCodes, and require they match exactly.\n const parentToChildrenFromParent = new Map<string, Set<string>>();\n for (const entry of entries) {\n if (entry.parentCode !== null) {\n let set = parentToChildrenFromParent.get(entry.parentCode);\n if (!set) {\n set = new Set();\n parentToChildrenFromParent.set(entry.parentCode, set);\n }\n set.add(entry.code);\n }\n }\n\n for (const entry of entries) {\n const declared = new Set(entry.childCodes);\n const derived = parentToChildrenFromParent.get(entry.code) ?? new Set();\n\n for (const child of declared) {\n if (!derived.has(child)) {\n errors.push({\n invariant: \"C4\",\n message: `entry lists ${child} in childCodes but that entry's parentCode is not ${entry.code}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n for (const child of derived) {\n if (!declared.has(child)) {\n errors.push({\n invariant: \"C4\",\n message: `entry ${child} has parentCode ${entry.code} but is missing from its childCodes`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n }\n\n // ── C5: selectability per §4.4 ────────────────────────────────────────────\n // Zod already enforces `selectable: boolean`; we make the invariant explicit\n // at validator level so a future schema loosening cannot silently bypass it.\n for (const entry of entries) {\n if (typeof entry.selectable !== \"boolean\") {\n errors.push({\n invariant: \"C5\",\n message: `selectable must be a boolean, got ${typeof entry.selectable}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n // ── C6: cross-CVC refs — `relevantMechanisms` resolves against provided set\n if (options.mechanismKeys) {\n for (const entry of entries) {\n const raw = (entry as unknown as Record<string, unknown>)[\n \"relevantMechanisms\"\n ];\n if (raw === undefined || raw === null) continue;\n if (!Array.isArray(raw)) {\n errors.push({\n invariant: \"C6\",\n message: `relevantMechanisms must be an array or null`,\n code: entry.code,\n key: entry.key,\n });\n continue;\n }\n for (const mechKey of raw) {\n if (\n typeof mechKey !== \"string\" ||\n !options.mechanismKeys.has(mechKey)\n ) {\n errors.push({\n invariant: \"C6\",\n message: `relevantMechanisms references unknown service_mechanisms key: ${String(mechKey)}`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n }\n }\n\n // ── C8: legacy `'provided'` key guard ─────────────────────────────────────\n // Walk every property of every entry (including nested arrays) looking for\n // a key named `'provided'`. It is a Thread UI label, not a canonical state.\n const walkForProvided = (value: unknown, entry: CvcEntry): void => {\n if (value === null || value === undefined) return;\n if (Array.isArray(value)) {\n for (const item of value) walkForProvided(item, entry);\n return;\n }\n if (typeof value === \"object\") {\n for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n if (k === \"provided\") {\n errors.push({\n invariant: \"C8\",\n message: `entry contains forbidden legacy key 'provided' (see locked spec §4)`,\n code: entry.code,\n key: entry.key,\n });\n }\n walkForProvided(v, entry);\n }\n }\n };\n for (const entry of entries) {\n walkForProvided(entry, entry);\n // Also guard against a literal string value of 'provided' appearing as an\n // entry's `key`, which would be an obvious smuggling attempt.\n if (entry.key === \"provided\") {\n errors.push({\n invariant: \"C8\",\n message: `entry key must not be the legacy label 'provided'`,\n code: entry.code,\n key: entry.key,\n });\n }\n }\n\n return errors;\n}\n"],"mappings":"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","names":[]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@htilabs/platform-common-models",
3
- "version": "0.3.0-beta.5",
3
+ "version": "0.4.0-beta.2",
4
4
  "description": "Shared constants, types, and models for HTI Labs applications",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -2,21 +2,17 @@
2
2
  "version": 1,
3
3
  "generated": "run `npm run test:snapshot` to regenerate",
4
4
  "cvcs": {
5
- "missingness": {
6
- "count": 4,
7
- "hash": "bce1ba0b47f4f33ab02db42abd77e29f39def976aed6a5aa8b22b21f4b46566a"
8
- },
9
5
  "service_mechanisms": {
10
- "count": 4,
11
- "hash": "9a1040dff253dd97f05b91dd15d19f9e95543c39a002f8b3faedf5886b080571"
6
+ "count": 8,
7
+ "hash": "d50072fd907c64496508282036790f320d659ce4756bd48ad25487442e8997af"
12
8
  },
13
9
  "service_states": {
14
- "count": 10,
15
- "hash": "f8cee319292546557408eed104b81d7286e2c8ee46bed1620083e9a01c0635cc"
10
+ "count": 14,
11
+ "hash": "bf2703581fcf0cd9f604836ad2ab4a43fe85c340cffb747f806c82a821411789"
16
12
  },
17
13
  "service_categories": {
18
- "count": 147,
19
- "hash": "4829fb73888e7072108020c8716adab16a09bda52a8570a1ded2de23e95d0f51"
14
+ "count": 151,
15
+ "hash": "a7c7a9b09d46c5ba8f5608d3e44331b862b07d67fac969f4bf204dca82b5fbd5"
20
16
  }
21
17
  }
22
18
  }
@@ -56,14 +56,14 @@ interface SotSpec {
56
56
  }
57
57
 
58
58
  const SOT_SPECS: readonly SotSpec[] = [
59
- // Spec §8.4 — "Entries: 4 (1 structural root + 3 values)"
60
- { file: "missingness.v1.0.0.json", domain: "missingness", expectedCount: 4 },
61
- // Spec §8.3 — "Entries: 4"
62
- { file: "serviceMechanisms.v1.0.0.json", domain: "service_mechanisms", expectedCount: 4 },
63
- // Spec §8.2 — "Entries: 10"
64
- { file: "serviceStates.v1.0.0.json", domain: "service_states", expectedCount: 10 },
65
- // Spec §8.1 — "Entries: 147"
66
- { file: "serviceCategories.v1.0.0.json", domain: "service_categories", expectedCount: 147 },
59
+ // Format v2: each domain embeds its own missingness (1 synthetic root + 3
60
+ // values) so expected counts = spec §8 hierarchy count + 4.
61
+ // Spec §8.3 — "Entries: 4" + 4 missingness = 8
62
+ { file: "serviceMechanisms.v1.0.0.json", domain: "service_mechanisms", expectedCount: 8 },
63
+ // Spec §8.2 — "Entries: 10" + 4 missingness = 14
64
+ { file: "serviceStates.v1.0.0.json", domain: "service_states", expectedCount: 14 },
65
+ // Spec §8.1 — "Entries: 147" + 4 missingness = 151
66
+ { file: "serviceCategories.v1.0.0.json", domain: "service_categories", expectedCount: 151 },
67
67
  ] as const;
68
68
 
69
69
  // ─── Helpers ────────────────────────────────────────────────────────────────
@@ -47,7 +47,6 @@ interface SotFile {
47
47
  }
48
48
 
49
49
  const SOT_FILES: readonly SotFile[] = [
50
- { file: "missingness.v1.0.0.json", expectedDomain: "missingness" },
51
50
  { file: "serviceMechanisms.v1.0.0.json", expectedDomain: "service_mechanisms" },
52
51
  { file: "serviceStates.v1.0.0.json", expectedDomain: "service_states" },
53
52
  { file: "serviceCategories.v1.0.0.json", expectedDomain: "service_categories" },
package/src/cvcs/index.ts CHANGED
@@ -10,10 +10,11 @@
10
10
  * consumers (Thread, PAVE, tests) that just need the data.
11
11
  *
12
12
  * Naming convention: `<camelCaseDomain>Sot`. Each constant is the raw envelope
13
- * (`{ domain, name, version, missingness?, levels, entries }`) — validate it
14
- * with `CvcEnvelopeSchema` from `../validation/cvc.ts` before trusting the
15
- * shape, since these JSON files are the source of truth and the import skips
16
- * runtime validation.
13
+ * (`{ domain, name, version, levels, entries }`) — validate it with
14
+ * `CvcEnvelopeSchema` from `../validation/cvc.ts` before trusting the shape,
15
+ * since these JSON files are the source of truth and the import skips runtime
16
+ * validation. Missingness entries live inside each domain's own entry list as
17
+ * of format v2 (segment 1 uses the Notion-aligned domain prefix).
17
18
  *
18
19
  * See locked spec §2 (envelope shape) and §9.2 (entry shape).
19
20
  */
@@ -21,11 +22,9 @@
21
22
  import serviceCategoriesSot from "./serviceCategories.v1.0.0.json" with { type: "json" };
22
23
  import serviceStatesSot from "./serviceStates.v1.0.0.json" with { type: "json" };
23
24
  import serviceMechanismsSot from "./serviceMechanisms.v1.0.0.json" with { type: "json" };
24
- import missingnessSot from "./missingness.v1.0.0.json" with { type: "json" };
25
25
 
26
26
  export {
27
27
  serviceCategoriesSot,
28
28
  serviceStatesSot,
29
29
  serviceMechanismsSot,
30
- missingnessSot,
31
30
  };