@htilabs/platform-common-models 0.4.0-beta.1 → 0.5.1-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 (51) hide show
  1. package/dist/constants/index.cjs +18 -9
  2. package/dist/constants/index.cjs.map +1 -1
  3. package/dist/constants/index.d.cts +1 -1
  4. package/dist/constants/index.d.ts +1 -1
  5. package/dist/constants/index.js +18 -9
  6. package/dist/constants/index.js.map +1 -1
  7. package/dist/cvcs/index.cjs +316 -1
  8. package/dist/cvcs/index.cjs.map +1 -1
  9. package/dist/cvcs/index.d.cts +368 -26
  10. package/dist/cvcs/index.d.ts +368 -26
  11. package/dist/cvcs/index.js +314 -1
  12. package/dist/cvcs/index.js.map +1 -1
  13. package/dist/index.cjs +373 -12
  14. package/dist/index.cjs.map +1 -1
  15. package/dist/index.d.cts +50 -5
  16. package/dist/index.d.ts +50 -5
  17. package/dist/index.js +369 -12
  18. package/dist/index.js.map +1 -1
  19. package/dist/models/index.cjs +2 -2
  20. package/dist/models/index.cjs.map +1 -1
  21. package/dist/models/index.js +2 -2
  22. package/dist/models/index.js.map +1 -1
  23. package/dist/{platform-auth-C-G2qeGM.d.cts → platform-auth-CjC57132.d.cts} +10 -7
  24. package/dist/{platform-auth-C-G2qeGM.d.ts → platform-auth-CjC57132.d.ts} +10 -7
  25. package/dist/schemas/index.cjs +16 -7
  26. package/dist/schemas/index.cjs.map +1 -1
  27. package/dist/schemas/index.js +16 -7
  28. package/dist/schemas/index.js.map +1 -1
  29. package/dist/services/index.cjs +2 -2
  30. package/dist/services/index.cjs.map +1 -1
  31. package/dist/services/index.js +2 -2
  32. package/dist/services/index.js.map +1 -1
  33. package/dist/types/index.d.cts +2 -2
  34. package/dist/types/index.d.ts +2 -2
  35. package/dist/validation/index.cjs.map +1 -1
  36. package/dist/validation/index.d.cts +2 -2
  37. package/dist/validation/index.d.ts +2 -2
  38. package/dist/validation/index.js.map +1 -1
  39. package/package.json +1 -1
  40. package/src/__tests__/__snapshots__/cvc-sot.snap +10 -2
  41. package/src/__tests__/cvc-sot-snapshot.test.ts +13 -1
  42. package/src/__tests__/cvc-structural.test.ts +1 -1
  43. package/src/constants/ic.ts +24 -14
  44. package/src/cvcs/incidentInvolvementRoles.v1.0.0.json +105 -0
  45. package/src/cvcs/incidentParticipationRoles.v1.0.0.json +202 -0
  46. package/src/cvcs/index.ts +4 -0
  47. package/src/cvcs/serviceStates.v1.0.0.json +1 -1
  48. package/src/generated/cvc-enums.ts +51 -2
  49. package/src/models/cvcEntryModel.ts +1 -1
  50. package/src/models/cvcRegistryModel.ts +1 -1
  51. package/src/validation/cvc.ts +6 -3
@@ -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 * 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_state (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_state\"`,\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 (typeof mechKey !== \"string\" || !options.mechanismKeys.has(mechKey)) {\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/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":[]}
@@ -19,7 +19,7 @@ import { z } from 'zod';
19
19
  * segment). Segment 1 is the Notion-aligned domain prefix:
20
20
  * `022` service_categories (CVC-22)
21
21
  * `025` service_mechanisms (CVC-25)
22
- * `049` service_state (CVC-49)
22
+ * `049` service_states (CVC-49)
23
23
  * - Missingness entries are embedded per-domain (synthetic `missingness_root`
24
24
  * at `<prefix>-000-000-000-000-000-000` plus three values at segment 7 =
25
25
  * `001`/`002`/`003`). The shared `missingness.v1.0.0.json` file was
@@ -187,7 +187,7 @@ type CvcEntry = z.infer<typeof CvcEntrySchema>;
187
187
  type ServiceCategoryEntry = z.infer<typeof ServiceCategoryEntrySchema>;
188
188
  type CvcEnvelope = z.infer<typeof CvcEnvelopeSchema>;
189
189
  /**
190
- * SOT family identifier (e.g. `"service_categories"`, `"service_state"`,
190
+ * SOT family identifier (e.g. `"service_categories"`, `"service_states"`,
191
191
  * `"service_mechanisms"`, `"missingness"`). The canonical list of domains is
192
192
  * enumerated by the SOT JSON files in `src/cvcs/`. Typed as `string` rather
193
193
  * than a closed union so adding a new SOT file does not require touching this
@@ -19,7 +19,7 @@ import { z } from 'zod';
19
19
  * segment). Segment 1 is the Notion-aligned domain prefix:
20
20
  * `022` service_categories (CVC-22)
21
21
  * `025` service_mechanisms (CVC-25)
22
- * `049` service_state (CVC-49)
22
+ * `049` service_states (CVC-49)
23
23
  * - Missingness entries are embedded per-domain (synthetic `missingness_root`
24
24
  * at `<prefix>-000-000-000-000-000-000` plus three values at segment 7 =
25
25
  * `001`/`002`/`003`). The shared `missingness.v1.0.0.json` file was
@@ -187,7 +187,7 @@ type CvcEntry = z.infer<typeof CvcEntrySchema>;
187
187
  type ServiceCategoryEntry = z.infer<typeof ServiceCategoryEntrySchema>;
188
188
  type CvcEnvelope = z.infer<typeof CvcEnvelopeSchema>;
189
189
  /**
190
- * SOT family identifier (e.g. `"service_categories"`, `"service_state"`,
190
+ * SOT family identifier (e.g. `"service_categories"`, `"service_states"`,
191
191
  * `"service_mechanisms"`, `"missingness"`). The canonical list of domains is
192
192
  * enumerated by the SOT JSON files in `src/cvcs/`. Typed as `string` rather
193
193
  * than a closed union so adding a new SOT file does not require touching this
@@ -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 * 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_state (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_state\"`,\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 (typeof mechKey !== \"string\" || !options.mechanismKeys.has(mechKey)) {\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.4.0-beta.1",
3
+ "version": "0.5.1-beta.2",
4
4
  "description": "Shared constants, types, and models for HTI Labs applications",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -6,13 +6,21 @@
6
6
  "count": 8,
7
7
  "hash": "d50072fd907c64496508282036790f320d659ce4756bd48ad25487442e8997af"
8
8
  },
9
- "service_state": {
9
+ "service_states": {
10
10
  "count": 14,
11
- "hash": "754c74959a2182a93f4500d12df46029ebbd09c2c52a56eb260e1ca089911c73"
11
+ "hash": "bf2703581fcf0cd9f604836ad2ab4a43fe85c340cffb747f806c82a821411789"
12
12
  },
13
13
  "service_categories": {
14
14
  "count": 151,
15
15
  "hash": "a7c7a9b09d46c5ba8f5608d3e44331b862b07d67fac969f4bf204dca82b5fbd5"
16
+ },
17
+ "incident_participation_roles": {
18
+ "count": 19,
19
+ "hash": "b183edbd968bf827a607b9ebc08a1388600e9c7d8a72ee47d261830d845988fa"
20
+ },
21
+ "incident_involvement_roles": {
22
+ "count": 10,
23
+ "hash": "82cab90656a08ddd2c4730dbf37e9d0545f9243c74a6f4e919e014e35516d698"
16
24
  }
17
25
  }
18
26
  }
@@ -61,9 +61,21 @@ const SOT_SPECS: readonly SotSpec[] = [
61
61
  // Spec §8.3 — "Entries: 4" + 4 missingness = 8
62
62
  { file: "serviceMechanisms.v1.0.0.json", domain: "service_mechanisms", expectedCount: 8 },
63
63
  // Spec §8.2 — "Entries: 10" + 4 missingness = 14
64
- { file: "serviceStates.v1.0.0.json", domain: "service_state", expectedCount: 14 },
64
+ { file: "serviceStates.v1.0.0.json", domain: "service_states", expectedCount: 14 },
65
65
  // Spec §8.1 — "Entries: 147" + 4 missingness = 151
66
66
  { file: "serviceCategories.v1.0.0.json", domain: "service_categories", expectedCount: 151 },
67
+ // CVC-69 — 4 group parents + 11 role leaves + 4 missingness = 19
68
+ {
69
+ file: "incidentParticipationRoles.v1.0.0.json",
70
+ domain: "incident_participation_roles",
71
+ expectedCount: 19,
72
+ },
73
+ // CVC-130 — 6 flat role leaves + 4 missingness = 10
74
+ {
75
+ file: "incidentInvolvementRoles.v1.0.0.json",
76
+ domain: "incident_involvement_roles",
77
+ expectedCount: 10,
78
+ },
67
79
  ] as const;
68
80
 
69
81
  // ─── Helpers ────────────────────────────────────────────────────────────────
@@ -48,7 +48,7 @@ interface SotFile {
48
48
 
49
49
  const SOT_FILES: readonly SotFile[] = [
50
50
  { file: "serviceMechanisms.v1.0.0.json", expectedDomain: "service_mechanisms" },
51
- { file: "serviceStates.v1.0.0.json", expectedDomain: "service_state" },
51
+ { file: "serviceStates.v1.0.0.json", expectedDomain: "service_states" },
52
52
  { file: "serviceCategories.v1.0.0.json", expectedDomain: "service_categories" },
53
53
  ] as const;
54
54
 
@@ -1203,7 +1203,7 @@ export const INCIDENT_INVOLVEMENT_ROLE = {
1203
1203
  OFFENDER: "offender",
1204
1204
  UNKNOWN: "unknown",
1205
1205
  ANONYMOUS: "anonymous",
1206
- NOT_COLLECTED: "not_collected",
1206
+ DATA_NOT_COLLECTED: "data_not_collected",
1207
1207
  } as const;
1208
1208
 
1209
1209
  export type IncidentInvolvementRoleValue =
@@ -1221,10 +1221,10 @@ export const INCIDENT_INVOLVEMENT_ROLE_LABELS: Record<
1221
1221
  [INCIDENT_INVOLVEMENT_ROLE.OFFENDER]: "Offender",
1222
1222
  [INCIDENT_INVOLVEMENT_ROLE.UNKNOWN]: "Unknown",
1223
1223
  [INCIDENT_INVOLVEMENT_ROLE.ANONYMOUS]: "Anonymous",
1224
- [INCIDENT_INVOLVEMENT_ROLE.NOT_COLLECTED]: "Not Collected",
1224
+ [INCIDENT_INVOLVEMENT_ROLE.DATA_NOT_COLLECTED]: "Not Collected",
1225
1225
  };
1226
1226
 
1227
- /** Involvement roles available for selection in Thread UI (excludes victim_other and not_collected). */
1227
+ /** Involvement roles available for selection in Thread UI (excludes victim_other and data_not_collected). */
1228
1228
  export const THREAD_INVOLVEMENT_ROLES = [
1229
1229
  INCIDENT_INVOLVEMENT_ROLE.VICTIM_PRIMARY,
1230
1230
  INCIDENT_INVOLVEMENT_ROLE.VICTIM_SECONDARY,
@@ -1273,7 +1273,7 @@ export const INCIDENT_INVOLVEMENT_ROLE_TO_PERSON_ROLE: Record<
1273
1273
  [INCIDENT_INVOLVEMENT_ROLE.OFFENDER]: PERSON_ROLES.OFFENDER,
1274
1274
  [INCIDENT_INVOLVEMENT_ROLE.UNKNOWN]: PERSON_ROLES.OTHER,
1275
1275
  [INCIDENT_INVOLVEMENT_ROLE.ANONYMOUS]: PERSON_ROLES.OTHER,
1276
- [INCIDENT_INVOLVEMENT_ROLE.NOT_COLLECTED]: PERSON_ROLES.OTHER,
1276
+ [INCIDENT_INVOLVEMENT_ROLE.DATA_NOT_COLLECTED]: PERSON_ROLES.OTHER,
1277
1277
  };
1278
1278
 
1279
1279
  // ─── IC-4: Age Type ────────────────────────────────────────────────
@@ -1800,9 +1800,12 @@ export const INCIDENT_PARTICIPATION_ROLE = {
1800
1800
  FRIEND_OR_PEER: "friend_or_peer",
1801
1801
  SERVICE_PROVIDER_STAFF: "service_provider_staff",
1802
1802
  MEDICAL_PROVIDER_STAFF: "medical_provider_staff",
1803
+ DATA_ENTRY: "data_entry",
1804
+ OTHER_INCIDENT_RESPONDER: "other_incident_responder",
1805
+ RESPONDING_OFFICER: "responding_officer",
1803
1806
  UNKNOWN: "unknown",
1804
1807
  ANONYMOUS: "anonymous",
1805
- NOT_COLLECTED: "not_collected",
1808
+ DATA_NOT_COLLECTED: "data_not_collected",
1806
1809
  } as const;
1807
1810
 
1808
1811
  export type IncidentParticipationRoleValue =
@@ -1817,9 +1820,12 @@ export const INCIDENT_PARTICIPATION_ROLE_VALUES = [
1817
1820
  INCIDENT_PARTICIPATION_ROLE.FRIEND_OR_PEER,
1818
1821
  INCIDENT_PARTICIPATION_ROLE.SERVICE_PROVIDER_STAFF,
1819
1822
  INCIDENT_PARTICIPATION_ROLE.MEDICAL_PROVIDER_STAFF,
1823
+ INCIDENT_PARTICIPATION_ROLE.DATA_ENTRY,
1824
+ INCIDENT_PARTICIPATION_ROLE.OTHER_INCIDENT_RESPONDER,
1825
+ INCIDENT_PARTICIPATION_ROLE.RESPONDING_OFFICER,
1820
1826
  INCIDENT_PARTICIPATION_ROLE.UNKNOWN,
1821
1827
  INCIDENT_PARTICIPATION_ROLE.ANONYMOUS,
1822
- INCIDENT_PARTICIPATION_ROLE.NOT_COLLECTED,
1828
+ INCIDENT_PARTICIPATION_ROLE.DATA_NOT_COLLECTED,
1823
1829
  ] as const;
1824
1830
 
1825
1831
  export const INCIDENT_PARTICIPATION_ROLE_LABELS: Record<
@@ -1837,15 +1843,19 @@ export const INCIDENT_PARTICIPATION_ROLE_LABELS: Record<
1837
1843
  "Service Provider Staff",
1838
1844
  [INCIDENT_PARTICIPATION_ROLE.MEDICAL_PROVIDER_STAFF]:
1839
1845
  "Medical Provider Staff",
1846
+ [INCIDENT_PARTICIPATION_ROLE.DATA_ENTRY]: "Data Entry / Editor",
1847
+ [INCIDENT_PARTICIPATION_ROLE.OTHER_INCIDENT_RESPONDER]:
1848
+ "VSP or Other Incident Responder",
1849
+ [INCIDENT_PARTICIPATION_ROLE.RESPONDING_OFFICER]: "LE Responding Officer",
1840
1850
  [INCIDENT_PARTICIPATION_ROLE.UNKNOWN]: "Unknown",
1841
1851
  [INCIDENT_PARTICIPATION_ROLE.ANONYMOUS]: "Anonymous",
1842
- [INCIDENT_PARTICIPATION_ROLE.NOT_COLLECTED]: "Not Collected",
1852
+ [INCIDENT_PARTICIPATION_ROLE.DATA_NOT_COLLECTED]: "Not Collected",
1843
1853
  };
1844
1854
 
1845
1855
  /**
1846
1856
  * Participation role category groupings for UI organization.
1847
1857
  *
1848
- * Note: UNKNOWN, ANONYMOUS, and NOT_COLLECTED are intentionally excluded.
1858
+ * Note: UNKNOWN, ANONYMOUS, and DATA_NOT_COLLECTED are intentionally excluded.
1849
1859
  * These are data quality states, not selectable participation roles.
1850
1860
  * Handle them via separate UI controls (e.g., "Unknown" / "Anonymous" buttons).
1851
1861
  */
@@ -1923,7 +1933,7 @@ export const PERSON_TYPE_VALUES = [
1923
1933
  /**
1924
1934
  * Static mapping from involvement role to person type.
1925
1935
  *
1926
- * Note: Returns `null` for UNKNOWN and NOT_COLLECTED because these roles
1936
+ * Note: Returns `null` for UNKNOWN and DATA_NOT_COLLECTED because these roles
1927
1937
  * require contextual handling. For these cases, use `getPersonTypeForRole()`
1928
1938
  * which applies conditional logic (e.g., preserving Personnel context).
1929
1939
  *
@@ -1942,20 +1952,20 @@ export const INVOLVEMENT_ROLE_TO_PERSON_TYPE: Record<
1942
1952
  // unknown defaults to ThirdParty unless context indicates Personnel
1943
1953
  [INCIDENT_INVOLVEMENT_ROLE.UNKNOWN]: null, // Conditional — use getPersonTypeForRole()
1944
1954
  [INCIDENT_INVOLVEMENT_ROLE.ANONYMOUS]: PERSON_TYPE.THIRD_PARTY,
1945
- [INCIDENT_INVOLVEMENT_ROLE.NOT_COLLECTED]: null,
1955
+ [INCIDENT_INVOLVEMENT_ROLE.DATA_NOT_COLLECTED]: null,
1946
1956
  };
1947
1957
 
1948
1958
  /**
1949
1959
  * Get the person type for an involvement role.
1950
1960
  * For 'unknown', preserves PersonnelPerson if provided as context, otherwise defaults to ThirdPartyPerson.
1951
- * Returns null for 'not_collected' (data quality state — cannot infer person type).
1961
+ * Returns null for 'data_not_collected' (data quality state — cannot infer person type).
1952
1962
  */
1953
1963
  export function getPersonTypeForRole(
1954
1964
  role: IncidentInvolvementRoleValue,
1955
1965
  contextPersonType?: PersonTypeValue,
1956
1966
  ): PersonTypeValue | null {
1957
- // NOT_COLLECTED is a data quality state, not a role — cannot infer person type
1958
- if (role === INCIDENT_INVOLVEMENT_ROLE.NOT_COLLECTED) {
1967
+ // DATA_NOT_COLLECTED is a data quality state, not a role — cannot infer person type
1968
+ if (role === INCIDENT_INVOLVEMENT_ROLE.DATA_NOT_COLLECTED) {
1959
1969
  return null;
1960
1970
  }
1961
1971
  // UNKNOWN: only Personnel context is preserved; all others default to ThirdPartyPerson
@@ -2001,7 +2011,7 @@ export function getDisplayCategoryForRole(
2001
2011
  // Not reachable in Thread, but map to Eligible Family if it occurs
2002
2012
  return PERSON_DISPLAY_CATEGORY.ELIGIBLE_FAMILY;
2003
2013
 
2004
- case INCIDENT_INVOLVEMENT_ROLE.NOT_COLLECTED:
2014
+ case INCIDENT_INVOLVEMENT_ROLE.DATA_NOT_COLLECTED:
2005
2015
  default:
2006
2016
  return PERSON_DISPLAY_CATEGORY.THIRD_PARTY;
2007
2017
  }
@@ -0,0 +1,105 @@
1
+ {
2
+ "domain": "incident_involvement_roles",
3
+ "name": "Core Incident Involvement Role",
4
+ "version": "1.0.0",
5
+ "levels": {
6
+ "0": "Unknown or Missing",
7
+ "1": "Involvement Role"
8
+ },
9
+ "entries": [
10
+ {
11
+ "code": "130-001-000-000-000-000-000",
12
+ "key": "victim_primary",
13
+ "title": "Victim (primary)",
14
+ "selectable": true,
15
+ "parentCode": null,
16
+ "childCodes": [],
17
+ "definition": "The primary victim/survivor for the incident framing."
18
+ },
19
+ {
20
+ "code": "130-002-000-000-000-000-000",
21
+ "key": "victim_secondary",
22
+ "title": "Victim (secondary)",
23
+ "selectable": true,
24
+ "parentCode": null,
25
+ "childCodes": [],
26
+ "definition": "A secondary victim harmed in the incident context."
27
+ },
28
+ {
29
+ "code": "130-003-000-000-000-000-000",
30
+ "key": "victim_other",
31
+ "title": "Victim (other)",
32
+ "selectable": true,
33
+ "parentCode": null,
34
+ "childCodes": [],
35
+ "definition": "Another victim relevant to the case when primary vs secondary is not meaningful."
36
+ },
37
+ {
38
+ "code": "130-004-000-000-000-000-000",
39
+ "key": "offender",
40
+ "title": "Offender",
41
+ "selectable": true,
42
+ "parentCode": null,
43
+ "childCodes": [],
44
+ "definition": "The person who caused harm."
45
+ },
46
+ {
47
+ "code": "130-005-000-000-000-000-000",
48
+ "key": "witness",
49
+ "title": "Witness",
50
+ "selectable": true,
51
+ "parentCode": null,
52
+ "childCodes": [],
53
+ "definition": "A person who witnessed relevant events."
54
+ },
55
+ {
56
+ "code": "130-006-000-000-000-000-000",
57
+ "key": "dependent",
58
+ "title": "Dependent",
59
+ "selectable": true,
60
+ "parentCode": null,
61
+ "childCodes": [],
62
+ "definition": "A relevant dependent (often a child) involved in the situation, not necessarily asserted harmed."
63
+ },
64
+ {
65
+ "code": "130-000-000-000-000-000-000",
66
+ "key": "missingness_root",
67
+ "title": "Unknown, Redacted, or Missing",
68
+ "selectable": false,
69
+ "parentCode": null,
70
+ "childCodes": [
71
+ "130-000-000-000-000-000-001",
72
+ "130-000-000-000-000-000-002",
73
+ "130-000-000-000-000-000-003"
74
+ ],
75
+ "definition": "Root group for values indicating absent, withheld, or uncollected data."
76
+ },
77
+ {
78
+ "code": "130-000-000-000-000-000-001",
79
+ "key": "unknown",
80
+ "title": "Unknown",
81
+ "selectable": true,
82
+ "parentCode": "130-000-000-000-000-000-000",
83
+ "childCodes": [],
84
+ "definition": "Value is unknown at time of entry."
85
+ },
86
+ {
87
+ "code": "130-000-000-000-000-000-002",
88
+ "key": "anonymous",
89
+ "title": "Anonymous",
90
+ "selectable": true,
91
+ "parentCode": "130-000-000-000-000-000-000",
92
+ "childCodes": [],
93
+ "definition": "Value is intentionally withheld or redacted."
94
+ },
95
+ {
96
+ "code": "130-000-000-000-000-000-003",
97
+ "key": "data_not_collected",
98
+ "title": "Data not collected",
99
+ "selectable": true,
100
+ "parentCode": "130-000-000-000-000-000-000",
101
+ "childCodes": [],
102
+ "definition": "No attempt was made to collect the value."
103
+ }
104
+ ]
105
+ }