@htilabs/platform-common-models 0.2.0-beta.3 → 0.3.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/README.md +38 -0
  2. package/dist/constants/index.cjs +0 -140
  3. package/dist/constants/index.cjs.map +1 -1
  4. package/dist/constants/index.d.cts +146 -5
  5. package/dist/constants/index.d.ts +146 -5
  6. package/dist/constants/index.js +0 -128
  7. package/dist/constants/index.js.map +1 -1
  8. package/dist/{platform-role-AHv1l5Og.d.cts → cvcEntry-wqktWfzE.d.cts} +231 -37
  9. package/dist/{platform-role-AHv1l5Og.d.ts → cvcEntry-wqktWfzE.d.ts} +231 -37
  10. package/dist/cvcs/index.cjs +2184 -0
  11. package/dist/cvcs/index.cjs.map +1 -0
  12. package/dist/cvcs/index.d.cts +2384 -0
  13. package/dist/cvcs/index.d.ts +2384 -0
  14. package/dist/cvcs/index.js +2154 -0
  15. package/dist/cvcs/index.js.map +1 -0
  16. package/dist/index--NCIPluF.d.cts +378 -0
  17. package/dist/index-CFOrHA8l.d.ts +378 -0
  18. package/dist/index.cjs +2962 -140
  19. package/dist/index.cjs.map +1 -1
  20. package/dist/index.d.cts +217 -3
  21. package/dist/index.d.ts +217 -3
  22. package/dist/index.js +2934 -128
  23. package/dist/index.js.map +1 -1
  24. package/dist/models/index.cjs +211 -0
  25. package/dist/models/index.cjs.map +1 -1
  26. package/dist/models/index.d.cts +3 -292
  27. package/dist/models/index.d.ts +3 -292
  28. package/dist/models/index.js +209 -0
  29. package/dist/models/index.js.map +1 -1
  30. package/dist/{platform-auth-DHSJP7XP.d.cts → platform-auth-C-G2qeGM.d.cts} +1 -36
  31. package/dist/{platform-auth-DHSJP7XP.d.ts → platform-auth-C-G2qeGM.d.ts} +1 -36
  32. package/dist/schemas/index.cjs +195 -116
  33. package/dist/schemas/index.cjs.map +1 -1
  34. package/dist/schemas/index.d.cts +11 -11
  35. package/dist/schemas/index.d.ts +11 -11
  36. package/dist/schemas/index.js +189 -116
  37. package/dist/schemas/index.js.map +1 -1
  38. package/dist/services/index.cjs +1442 -0
  39. package/dist/services/index.cjs.map +1 -0
  40. package/dist/services/index.d.cts +305 -0
  41. package/dist/services/index.d.ts +305 -0
  42. package/dist/services/index.js +1417 -0
  43. package/dist/services/index.js.map +1 -0
  44. package/dist/types/index.d.cts +2 -2
  45. package/dist/types/index.d.ts +2 -2
  46. package/dist/validation/index.cjs +261 -0
  47. package/dist/validation/index.cjs.map +1 -0
  48. package/dist/validation/index.d.cts +251 -0
  49. package/dist/validation/index.d.ts +251 -0
  50. package/dist/validation/index.js +228 -0
  51. package/dist/validation/index.js.map +1 -0
  52. package/package.json +36 -12
  53. package/src/__tests__/__snapshots__/cvc-sot.snap +22 -0
  54. package/src/__tests__/cvc-sot-snapshot.test.ts +184 -0
  55. package/src/__tests__/cvc-structural.test.ts +130 -0
  56. package/src/constants/ic.ts +0 -154
  57. package/src/constants/service-catalog.ts +146 -4
  58. package/src/cvcs/index.ts +31 -0
  59. package/src/cvcs/missingness.v1.0.0.json +50 -0
  60. package/src/cvcs/serviceCategories.v1.0.0.json +1947 -0
  61. package/src/cvcs/serviceMechanisms.v1.0.0.json +47 -0
  62. package/src/cvcs/serviceStates.v1.0.0.json +106 -0
  63. package/src/generated/cvc-enums.ts +215 -0
  64. package/src/index.ts +61 -1
  65. package/src/models/cvcEntryModel.ts +32 -0
  66. package/src/models/cvcRegistryModel.ts +35 -0
  67. package/src/models/index.ts +8 -0
  68. package/src/schemas/cvcEntry.ts +158 -0
  69. package/src/schemas/cvcRegistry.ts +149 -0
  70. package/src/schemas/index.ts +16 -0
  71. package/src/services/__tests__/cvcRegistryService.test.ts +614 -0
  72. package/src/services/cvcRegistryService.ts +729 -0
  73. package/src/services/index.ts +21 -0
  74. package/src/validation/cvc.ts +414 -0
  75. package/src/validation/index.ts +15 -0
@@ -0,0 +1,130 @@
1
+ /**
2
+ * CVC Structural CI Test — locked spec §4 invariants
3
+ *
4
+ * For every committed SOT JSON file in `src/cvcs/`, this test:
5
+ * 1. Parses the envelope via `CvcEnvelopeSchema.parse()` — enforces shape
6
+ * (envelope fields, entry field types, code/key regex at entry level).
7
+ * 2. Calls `validateCvc()` — enforces §4 semantic invariants C1-C5, C7, C8
8
+ * (and C6 via the mechanism-key set wired in below).
9
+ *
10
+ * Cross-CVC C6 check: service_categories entries carry `relevantMechanisms`
11
+ * arrays pointing at `service_mechanisms` keys. Before validating the
12
+ * categories file we load the mechanisms file and build the set of valid
13
+ * keys; passing that into `validateCvc()` lights up the cross-ref check.
14
+ *
15
+ * This test is designed to run under vitest (`npm test`) on every PR and
16
+ * fail loud if any SOT file drifts from the locked spec §4 invariants. Each
17
+ * invariant is labeled `C1`..`C8` so CI output points straight at the spec
18
+ * rule that broke.
19
+ */
20
+
21
+ import { readFileSync } from "node:fs";
22
+ import path from "node:path";
23
+ import { fileURLToPath } from "node:url";
24
+
25
+ import { describe, it, expect } from "vitest";
26
+
27
+ import {
28
+ CvcEnvelopeSchema,
29
+ validateCvc,
30
+ type CvcValidationError,
31
+ } from "../validation/cvc.js";
32
+
33
+ // ─── Paths ──────────────────────────────────────────────────────────────────
34
+
35
+ const __filename = fileURLToPath(import.meta.url);
36
+ const __dirname = path.dirname(__filename);
37
+ const CVCS_DIR = path.resolve(__dirname, "..", "cvcs");
38
+
39
+ // ─── SOT files under test ───────────────────────────────────────────────────
40
+ // Ordering matters: load `service_mechanisms` first so we have its key set
41
+ // available before validating `service_categories` (which cross-references
42
+ // mechanism keys).
43
+
44
+ interface SotFile {
45
+ file: string;
46
+ expectedDomain: string;
47
+ }
48
+
49
+ const SOT_FILES: readonly SotFile[] = [
50
+ { file: "missingness.v1.0.0.json", expectedDomain: "missingness" },
51
+ { file: "serviceMechanisms.v1.0.0.json", expectedDomain: "service_mechanisms" },
52
+ { file: "serviceStates.v1.0.0.json", expectedDomain: "service_states" },
53
+ { file: "serviceCategories.v1.0.0.json", expectedDomain: "service_categories" },
54
+ ] as const;
55
+
56
+ function loadSot(file: string): unknown {
57
+ return JSON.parse(readFileSync(path.join(CVCS_DIR, file), "utf-8"));
58
+ }
59
+
60
+ /**
61
+ * Format validator errors as a single string for expect-assertion failure
62
+ * messages. Each line names the violated invariant so developers see which
63
+ * locked spec rule broke without rerunning with verbose flags.
64
+ */
65
+ function formatErrors(errors: readonly CvcValidationError[]): string {
66
+ return errors
67
+ .map((e) => {
68
+ const loc = e.code
69
+ ? ` [${e.code}${e.key ? ` / ${e.key}` : ""}]`
70
+ : "";
71
+ return ` ${e.invariant}${loc}: ${e.message}`;
72
+ })
73
+ .join("\n");
74
+ }
75
+
76
+ // ─── Tests ──────────────────────────────────────────────────────────────────
77
+
78
+ describe("CVC structural invariants (locked spec §4)", () => {
79
+ // Pre-load mechanism keys for the C6 cross-reference check.
80
+ const mechanismsRaw = loadSot("serviceMechanisms.v1.0.0.json");
81
+ const mechanismsEnvelope = CvcEnvelopeSchema.parse(mechanismsRaw);
82
+ const mechanismKeys = new Set(mechanismsEnvelope.entries.map((e) => e.key));
83
+
84
+ for (const { file, expectedDomain } of SOT_FILES) {
85
+ describe(file, () => {
86
+ const raw = loadSot(file);
87
+
88
+ it("parses via CvcEnvelopeSchema (shape contract)", () => {
89
+ // Zod will throw with a detailed error object if shape is wrong;
90
+ // letting it bubble gives vitest a readable failure.
91
+ expect(() => CvcEnvelopeSchema.parse(raw)).not.toThrow();
92
+ });
93
+
94
+ it(`envelope domain matches expected (${expectedDomain})`, () => {
95
+ const envelope = CvcEnvelopeSchema.parse(raw);
96
+ expect(envelope.domain).toBe(expectedDomain);
97
+ });
98
+
99
+ it("passes validateCvc (§4 invariants C1-C8)", () => {
100
+ const envelope = CvcEnvelopeSchema.parse(raw);
101
+
102
+ // Only service_categories needs mechanism cross-refs; other CVCs
103
+ // have no `relevantMechanisms` field so passing the set is harmless.
104
+ const errors = validateCvc(envelope, { mechanismKeys });
105
+
106
+ if (errors.length > 0) {
107
+ throw new Error(
108
+ `${file} violated §4 invariants:\n${formatErrors(errors)}`,
109
+ );
110
+ }
111
+ expect(errors).toHaveLength(0);
112
+ });
113
+ });
114
+ }
115
+
116
+ it("service_categories has at least one entry with relevantMechanisms (sanity: passthrough works)", () => {
117
+ // Guard against a future regression where CvcEntrySchema stops passing
118
+ // domain-specific fields through. Without this, C6 would silently pass
119
+ // on an empty input.
120
+ const raw = loadSot("serviceCategories.v1.0.0.json");
121
+ const envelope = CvcEnvelopeSchema.parse(raw);
122
+ const withRelevant = envelope.entries.filter((e) => {
123
+ const field = (e as unknown as Record<string, unknown>)[
124
+ "relevantMechanisms"
125
+ ];
126
+ return Array.isArray(field) && field.length > 0;
127
+ });
128
+ expect(withRelevant.length).toBeGreaterThan(0);
129
+ });
130
+ });
@@ -1467,18 +1467,6 @@ export function isTransgenderGenderIdentity(value: CVC17Value | null | undefined
1467
1467
  return CVC_17_TRANSGENDER_VALUES.includes(value);
1468
1468
  }
1469
1469
 
1470
- // All CVC-17 values as an array (for Mongoose schema enum validation)
1471
- export const CVC_17_VALUES: CVC17Value[] = [
1472
- CVC_17_CORE_GENDER_IDENTITY.MALE,
1473
- CVC_17_CORE_GENDER_IDENTITY.FEMALE,
1474
- CVC_17_CORE_GENDER_IDENTITY.TRANSGENDER,
1475
- CVC_17_CORE_GENDER_IDENTITY.NON_BINARY,
1476
- CVC_17_CORE_GENDER_IDENTITY.OTHER,
1477
- CVC_17_CORE_GENDER_IDENTITY.UNKNOWN,
1478
- CVC_17_CORE_GENDER_IDENTITY.TRANSGENDER_FTM,
1479
- CVC_17_CORE_GENDER_IDENTITY.TRANSGENDER_MTF,
1480
- ];
1481
-
1482
1470
  // ─── IC-24: Race ───────────────────────────────────────────────────
1483
1471
 
1484
1472
  export const IC_24_RACE = {
@@ -5284,145 +5272,3 @@ export const CVC_67_SELECTABLE_VALUES: CVC67Value[] = [
5284
5272
  export const CVC_67_MISSINGNESS_VALUES: CVC67Value[] = [
5285
5273
  CVC_67_HMIS_SEX.DATA_NOT_COLLECTED,
5286
5274
  ];
5287
-
5288
- // All CVC-67 values as an array (for Mongoose schema enum validation)
5289
- export const CVC_67_VALUES: CVC67Value[] = [
5290
- CVC_67_HMIS_SEX.MALE,
5291
- CVC_67_HMIS_SEX.FEMALE,
5292
- CVC_67_HMIS_SEX.CLIENT_PREFERS_NOT_TO_ANSWER,
5293
- CVC_67_HMIS_SEX.CLIENT_DOESNT_KNOW,
5294
- CVC_67_HMIS_SEX.DATA_NOT_COLLECTED,
5295
- ];
5296
-
5297
- // ─── CVC-137: Recency Band ─────────────────────────────────────────
5298
- // Canonical codeset for capturing when an asserted event happened using
5299
- // categorical time buckets (rather than exact dates).
5300
- // Reference: https://www.notion.so/htilabs/CVC-137-Recency-Band
5301
-
5302
- export const CVC_137_RECENCY_BAND = {
5303
- // Primary recency values
5304
- WITHIN_3_MONTHS: "W3M",
5305
- MONTHS_3_TO_6: "M3_6",
5306
- MONTHS_6_TO_12: "M6_12",
5307
- ONE_YEAR_OR_MORE: "Y1P",
5308
- LESS_THAN_3_YEARS: "YLT3",
5309
- YEARS_3_TO_10: "Y3_10",
5310
- TEN_PLUS_YEARS: "Y10P",
5311
- // Missingness values
5312
- UNKNOWN: "UNK",
5313
- DATA_NOT_COLLECTED: "DNC",
5314
- ANONYMOUS: "ANON",
5315
- PREFERS_NOT_TO_ANSWER: "PNA",
5316
- } as const;
5317
-
5318
- export type CVC137Value =
5319
- (typeof CVC_137_RECENCY_BAND)[keyof typeof CVC_137_RECENCY_BAND];
5320
-
5321
- export const CVC_137_LABELS: Record<CVC137Value, string> = {
5322
- [CVC_137_RECENCY_BAND.WITHIN_3_MONTHS]: "Within past 3 months",
5323
- [CVC_137_RECENCY_BAND.MONTHS_3_TO_6]: "3-6 months ago",
5324
- [CVC_137_RECENCY_BAND.MONTHS_6_TO_12]: "6-12 months ago",
5325
- [CVC_137_RECENCY_BAND.ONE_YEAR_OR_MORE]: "One year or more",
5326
- [CVC_137_RECENCY_BAND.LESS_THAN_3_YEARS]: "Less than 3 years ago",
5327
- [CVC_137_RECENCY_BAND.YEARS_3_TO_10]: "3-10 years ago",
5328
- [CVC_137_RECENCY_BAND.TEN_PLUS_YEARS]: "10+ years ago",
5329
- [CVC_137_RECENCY_BAND.UNKNOWN]: "Unknown",
5330
- [CVC_137_RECENCY_BAND.DATA_NOT_COLLECTED]: "Data not collected",
5331
- [CVC_137_RECENCY_BAND.ANONYMOUS]: "Anonymous",
5332
- [CVC_137_RECENCY_BAND.PREFERS_NOT_TO_ANSWER]: "Client prefers not to answer",
5333
- };
5334
-
5335
- // All CVC-137 values as an array (for Mongoose schema enum validation)
5336
- export const CVC_137_VALUES: CVC137Value[] = [
5337
- CVC_137_RECENCY_BAND.WITHIN_3_MONTHS,
5338
- CVC_137_RECENCY_BAND.MONTHS_3_TO_6,
5339
- CVC_137_RECENCY_BAND.MONTHS_6_TO_12,
5340
- CVC_137_RECENCY_BAND.ONE_YEAR_OR_MORE,
5341
- CVC_137_RECENCY_BAND.LESS_THAN_3_YEARS,
5342
- CVC_137_RECENCY_BAND.YEARS_3_TO_10,
5343
- CVC_137_RECENCY_BAND.TEN_PLUS_YEARS,
5344
- CVC_137_RECENCY_BAND.UNKNOWN,
5345
- CVC_137_RECENCY_BAND.DATA_NOT_COLLECTED,
5346
- CVC_137_RECENCY_BAND.ANONYMOUS,
5347
- CVC_137_RECENCY_BAND.PREFERS_NOT_TO_ANSWER,
5348
- ];
5349
-
5350
- // Selectable values for UI dropdowns (excludes missingness codes)
5351
- export const CVC_137_SELECTABLE_VALUES: CVC137Value[] = [
5352
- CVC_137_RECENCY_BAND.WITHIN_3_MONTHS,
5353
- CVC_137_RECENCY_BAND.MONTHS_3_TO_6,
5354
- CVC_137_RECENCY_BAND.MONTHS_6_TO_12,
5355
- CVC_137_RECENCY_BAND.ONE_YEAR_OR_MORE,
5356
- CVC_137_RECENCY_BAND.LESS_THAN_3_YEARS,
5357
- CVC_137_RECENCY_BAND.YEARS_3_TO_10,
5358
- CVC_137_RECENCY_BAND.TEN_PLUS_YEARS,
5359
- ];
5360
-
5361
- // Missingness values
5362
- export const CVC_137_MISSINGNESS_VALUES: CVC137Value[] = [
5363
- CVC_137_RECENCY_BAND.UNKNOWN,
5364
- CVC_137_RECENCY_BAND.DATA_NOT_COLLECTED,
5365
- CVC_137_RECENCY_BAND.ANONYMOUS,
5366
- CVC_137_RECENCY_BAND.PREFERS_NOT_TO_ANSWER,
5367
- ];
5368
-
5369
- // ─── CVC-197: Juvenile Justice Episode Type ────────────────────────
5370
- // Types of juvenile justice system involvement episodes.
5371
- // Reference: https://www.notion.so/htilabs/CVC-197-Juvenile-Justice-Episode-Type
5372
-
5373
- export const CVC_197_JUVENILE_JUSTICE_EPISODE = {
5374
- DIVERSION_PROGRAM: "diversion_program",
5375
- PROBATION_SUPERVISION: "probation_supervision",
5376
- PENDING_ADJUDICATION: "pending_adjudication",
5377
- DETENTION_STAY: "detention_stay",
5378
- RESIDENTIAL_JJ_PLACEMENT: "residential_jj_placement",
5379
- // Missingness values
5380
- DATA_NOT_COLLECTED: "DNC",
5381
- UNKNOWN: "UNK",
5382
- ANONYMOUS: "ANON",
5383
- } as const;
5384
-
5385
- export type CVC197Value =
5386
- (typeof CVC_197_JUVENILE_JUSTICE_EPISODE)[keyof typeof CVC_197_JUVENILE_JUSTICE_EPISODE];
5387
-
5388
- export const CVC_197_LABELS: Record<CVC197Value, string> = {
5389
- [CVC_197_JUVENILE_JUSTICE_EPISODE.DIVERSION_PROGRAM]: "Diversion program",
5390
- [CVC_197_JUVENILE_JUSTICE_EPISODE.PROBATION_SUPERVISION]:
5391
- "Probation supervision",
5392
- [CVC_197_JUVENILE_JUSTICE_EPISODE.PENDING_ADJUDICATION]:
5393
- "Pending adjudication",
5394
- [CVC_197_JUVENILE_JUSTICE_EPISODE.DETENTION_STAY]: "Detention stay",
5395
- [CVC_197_JUVENILE_JUSTICE_EPISODE.RESIDENTIAL_JJ_PLACEMENT]:
5396
- "Residential JJ placement",
5397
- [CVC_197_JUVENILE_JUSTICE_EPISODE.DATA_NOT_COLLECTED]: "Data not collected",
5398
- [CVC_197_JUVENILE_JUSTICE_EPISODE.UNKNOWN]: "Unknown",
5399
- [CVC_197_JUVENILE_JUSTICE_EPISODE.ANONYMOUS]: "Anonymous",
5400
- };
5401
-
5402
- // All CVC-197 values as an array (for Mongoose schema enum validation)
5403
- export const CVC_197_VALUES: CVC197Value[] = [
5404
- CVC_197_JUVENILE_JUSTICE_EPISODE.DIVERSION_PROGRAM,
5405
- CVC_197_JUVENILE_JUSTICE_EPISODE.PROBATION_SUPERVISION,
5406
- CVC_197_JUVENILE_JUSTICE_EPISODE.PENDING_ADJUDICATION,
5407
- CVC_197_JUVENILE_JUSTICE_EPISODE.DETENTION_STAY,
5408
- CVC_197_JUVENILE_JUSTICE_EPISODE.RESIDENTIAL_JJ_PLACEMENT,
5409
- CVC_197_JUVENILE_JUSTICE_EPISODE.DATA_NOT_COLLECTED,
5410
- CVC_197_JUVENILE_JUSTICE_EPISODE.UNKNOWN,
5411
- CVC_197_JUVENILE_JUSTICE_EPISODE.ANONYMOUS,
5412
- ];
5413
-
5414
- // Selectable values for UI dropdowns (excludes missingness codes)
5415
- export const CVC_197_SELECTABLE_VALUES: CVC197Value[] = [
5416
- CVC_197_JUVENILE_JUSTICE_EPISODE.DIVERSION_PROGRAM,
5417
- CVC_197_JUVENILE_JUSTICE_EPISODE.PROBATION_SUPERVISION,
5418
- CVC_197_JUVENILE_JUSTICE_EPISODE.PENDING_ADJUDICATION,
5419
- CVC_197_JUVENILE_JUSTICE_EPISODE.DETENTION_STAY,
5420
- CVC_197_JUVENILE_JUSTICE_EPISODE.RESIDENTIAL_JJ_PLACEMENT,
5421
- ];
5422
-
5423
- // Missingness values
5424
- export const CVC_197_MISSINGNESS_VALUES: CVC197Value[] = [
5425
- CVC_197_JUVENILE_JUSTICE_EPISODE.DATA_NOT_COLLECTED,
5426
- CVC_197_JUVENILE_JUSTICE_EPISODE.UNKNOWN,
5427
- CVC_197_JUVENILE_JUSTICE_EPISODE.ANONYMOUS,
5428
- ];
@@ -11,6 +11,45 @@
11
11
  * - Selectability flags for leaf vs branch nodes
12
12
  *
13
13
  * @see https://github.com/htilabstech/thread2 for the source of truth
14
+ *
15
+ * ---
16
+ *
17
+ * **DEPRECATION NOTICE (as of 0.3.0)**
18
+ *
19
+ * All exported constants and helpers in this module are deprecated in favor
20
+ * of the generalized CVC data layer (`CvcRegistryService`), which loads
21
+ * catalog data from MongoDB at runtime rather than from a hardcoded JSON
22
+ * bundle. Nothing is being removed yet — removal is tracked in a downstream
23
+ * consumer-migration epic after Thread + PAVE cut over.
24
+ *
25
+ * Migration pointers (by symbol):
26
+ * - `IC_48_BY_ID` / `getIC48CategoryById` / `getIC48Label`
27
+ * → `CvcRegistryService.getEntryByCode(scope, code)`
28
+ * (NOTE: the primary key changes from integer ID to the positional
29
+ * 7-segment code.)
30
+ * - `IC_48_BY_CODE` / `getIC48CategoryByCode`
31
+ * → `CvcRegistryService.getEntryByCode(scope, code)`
32
+ * - `IC_48_CATEGORIES` / `IC_48_SERVICE_CATALOG`
33
+ * → `CvcRegistryService.getEntries(scope, 'service_categories')`
34
+ * or `CvcRegistryService.getActiveRegistry(scope)`
35
+ * - `getIC48SelectableCategories`
36
+ * → `CvcRegistryService.getSelectableEntries(scope, 'service_categories')`
37
+ * - `getIC48ChildCategories`
38
+ * → `CvcRegistryService.getChildren(scope, domain, parentKey)`
39
+ * - `getIC48TopicCategories`
40
+ * → `CvcRegistryService.getEntries(scope, 'service_categories')`
41
+ * filtered to level-1 entries (no direct 1:1 helper)
42
+ * - `getIC48ParentCategory` / `getIC48AncestorCategories`
43
+ * / `getIC48TopicForCategory`
44
+ * → `CvcRegistryService.getAncestors(scope, domain, key)`
45
+ * - `IC_48_CRISIS_SERVICES` → deferred to the **thread application layer**
46
+ * (`service-catalog-rules.v1.json#coreCrisisCodes[]` in the thread rig).
47
+ * NOT replaced by a platform-common field.
48
+ * - `IC_48_DERIVATION_SERVICES` → application-layer concern; define per-app.
49
+ *
50
+ * See `src/services/cvcRegistryService.ts` and the locked CVC Implementation
51
+ * Spec at `/gt/docs/data/cvcs/`. These symbols will be removed in a future
52
+ * major version after Thread + PAVE migrate off the legacy API.
14
53
  */
15
54
 
16
55
  import catalogData from "./service-catalog.json" with { type: "json" };
@@ -59,20 +98,52 @@ export interface IC48Catalog {
59
98
 
60
99
  // ─── Catalog Data ────────────────────────────────────────────────────
61
100
 
62
- /** The full IC-48 service catalog */
101
+ /**
102
+ * The full IC-48 service catalog.
103
+ *
104
+ * @deprecated Use `CvcRegistryService.getActiveRegistry(scope)` (or
105
+ * `getRegistry`) from `@htilabs/platform-common-models` instead. The new
106
+ * CVC data layer loads registries from MongoDB at runtime.
107
+ * See the module-level deprecation notice above for the full migration
108
+ * table. This constant will be removed in a future major version after
109
+ * Thread + PAVE migrate.
110
+ */
63
111
  export const IC_48_SERVICE_CATALOG = catalogData as IC48Catalog;
64
112
 
65
- /** All service categories as an array */
113
+ /**
114
+ * All service categories as an array.
115
+ *
116
+ * @deprecated Use `CvcRegistryService.getEntries(scope, 'service_categories')`
117
+ * from `@htilabs/platform-common-models` instead.
118
+ * See the module-level deprecation notice above. This constant will be
119
+ * removed in a future major version after Thread + PAVE migrate.
120
+ */
66
121
  export const IC_48_CATEGORIES = IC_48_SERVICE_CATALOG.categories;
67
122
 
68
123
  // ─── Lookup Maps (built once at module load) ─────────────────────────
69
124
 
70
- /** Map of category ID to category object for O(1) lookup */
125
+ /**
126
+ * Map of category ID to category object for O(1) lookup.
127
+ *
128
+ * @deprecated Use `CvcRegistryService.getEntryByCode(scope, code)` from
129
+ * `@htilabs/platform-common-models` instead.
130
+ * NOTE: the primary key changes from integer ID to the positional
131
+ * 7-segment code. See the module-level deprecation notice above.
132
+ * This constant will be removed in a future major version after
133
+ * Thread + PAVE migrate.
134
+ */
71
135
  export const IC_48_BY_ID: ReadonlyMap<number, IC48Category> = new Map(
72
136
  IC_48_CATEGORIES.map((cat) => [cat.id, cat])
73
137
  );
74
138
 
75
- /** Map of category code to category object for O(1) lookup */
139
+ /**
140
+ * Map of category code to category object for O(1) lookup.
141
+ *
142
+ * @deprecated Use `CvcRegistryService.getEntryByCode(scope, code)` from
143
+ * `@htilabs/platform-common-models` instead.
144
+ * See the module-level deprecation notice above. This constant will be
145
+ * removed in a future major version after Thread + PAVE migrate.
146
+ */
76
147
  export const IC_48_BY_CODE: ReadonlyMap<string, IC48Category> = new Map(
77
148
  IC_48_CATEGORIES.map((cat) => [cat.code, cat])
78
149
  );
@@ -83,6 +154,11 @@ export const IC_48_BY_CODE: ReadonlyMap<string, IC48Category> = new Map(
83
154
  * Get a service category by its numeric ID.
84
155
  * @param id - The category ID
85
156
  * @returns The category or undefined if not found
157
+ * @deprecated Use `CvcRegistryService.getEntryByCode(scope, code)` from
158
+ * `@htilabs/platform-common-models` instead.
159
+ * NOTE: the primary key changes from integer ID to the positional
160
+ * 7-segment code. See the module-level deprecation notice above.
161
+ * Will be removed in a future major version after Thread + PAVE migrate.
86
162
  */
87
163
  export function getIC48CategoryById(id: number): IC48Category | undefined {
88
164
  return IC_48_BY_ID.get(id);
@@ -92,6 +168,10 @@ export function getIC48CategoryById(id: number): IC48Category | undefined {
92
168
  * Get a service category by its hierarchical code.
93
169
  * @param code - The category code (e.g., "01-04-01")
94
170
  * @returns The category or undefined if not found
171
+ * @deprecated Use `CvcRegistryService.getEntryByCode(scope, code)` from
172
+ * `@htilabs/platform-common-models` instead. See the module-level
173
+ * deprecation notice above. Will be removed in a future major version
174
+ * after Thread + PAVE migrate.
95
175
  */
96
176
  export function getIC48CategoryByCode(code: string): IC48Category | undefined {
97
177
  return IC_48_BY_CODE.get(code);
@@ -101,6 +181,11 @@ export function getIC48CategoryByCode(code: string): IC48Category | undefined {
101
181
  * Get the label for a service category by ID.
102
182
  * @param id - The category ID
103
183
  * @returns The label or "Unknown Service" if not found
184
+ * @deprecated Use `CvcRegistryService.getEntryByCode(scope, code)` and read
185
+ * the entry's label from `@htilabs/platform-common-models` instead.
186
+ * NOTE: the primary key changes from integer ID to the positional
187
+ * 7-segment code. See the module-level deprecation notice above.
188
+ * Will be removed in a future major version after Thread + PAVE migrate.
104
189
  */
105
190
  export function getIC48Label(id: number): string {
106
191
  return IC_48_BY_ID.get(id)?.label ?? "Unknown Service";
@@ -110,6 +195,10 @@ export function getIC48Label(id: number): string {
110
195
  * Get all children of a category (direct descendants only).
111
196
  * @param parentId - The parent category ID
112
197
  * @returns Array of child categories
198
+ * @deprecated Use `CvcRegistryService.getChildren(scope, domain, parentKey)`
199
+ * from `@htilabs/platform-common-models` instead. See the module-level
200
+ * deprecation notice above. Will be removed in a future major version
201
+ * after Thread + PAVE migrate.
113
202
  */
114
203
  export function getIC48ChildCategories(parentId: number): IC48Category[] {
115
204
  return IC_48_CATEGORIES.filter((cat) => cat.parentId === parentId);
@@ -118,6 +207,11 @@ export function getIC48ChildCategories(parentId: number): IC48Category[] {
118
207
  /**
119
208
  * Get all selectable (leaf) categories.
120
209
  * @returns Array of selectable categories
210
+ * @deprecated Use
211
+ * `CvcRegistryService.getSelectableEntries(scope, 'service_categories')`
212
+ * from `@htilabs/platform-common-models` instead. See the module-level
213
+ * deprecation notice above. Will be removed in a future major version
214
+ * after Thread + PAVE migrate.
121
215
  */
122
216
  export function getIC48SelectableCategories(): IC48Category[] {
123
217
  return IC_48_CATEGORIES.filter((cat) => cat.isSelectable);
@@ -126,6 +220,10 @@ export function getIC48SelectableCategories(): IC48Category[] {
126
220
  /**
127
221
  * Get the root/topic categories (level 1, no parent).
128
222
  * @returns Array of topic-level categories
223
+ * @deprecated Use `CvcRegistryService.getEntries(scope, 'service_categories')`
224
+ * and filter to level-1 entries instead (no direct 1:1 helper exists in
225
+ * the new API). See the module-level deprecation notice above. Will be
226
+ * removed in a future major version after Thread + PAVE migrate.
129
227
  */
130
228
  export function getIC48TopicCategories(): IC48Category[] {
131
229
  return IC_48_CATEGORIES.filter((cat) => cat.level === 1 && cat.parentId === null);
@@ -135,6 +233,10 @@ export function getIC48TopicCategories(): IC48Category[] {
135
233
  * Get the parent category for a given category.
136
234
  * @param id - The category ID
137
235
  * @returns The parent category or undefined if none/not found
236
+ * @deprecated Use `CvcRegistryService.getAncestors(scope, domain, key)` and
237
+ * take the first ancestor from `@htilabs/platform-common-models` instead.
238
+ * See the module-level deprecation notice above. Will be removed in a
239
+ * future major version after Thread + PAVE migrate.
138
240
  */
139
241
  export function getIC48ParentCategory(id: number): IC48Category | undefined {
140
242
  const cat = IC_48_BY_ID.get(id);
@@ -146,6 +248,10 @@ export function getIC48ParentCategory(id: number): IC48Category | undefined {
146
248
  * Get all ancestor categories (parent, grandparent, etc.) for a category.
147
249
  * @param id - The category ID
148
250
  * @returns Array of ancestor categories from immediate parent to root
251
+ * @deprecated Use `CvcRegistryService.getAncestors(scope, domain, key)` from
252
+ * `@htilabs/platform-common-models` instead. See the module-level
253
+ * deprecation notice above. Will be removed in a future major version
254
+ * after Thread + PAVE migrate.
149
255
  */
150
256
  export function getIC48AncestorCategories(id: number): IC48Category[] {
151
257
  const ancestors: IC48Category[] = [];
@@ -168,6 +274,10 @@ export function getIC48AncestorCategories(id: number): IC48Category[] {
168
274
  * Get the topic (level 1) category for any category in the tree.
169
275
  * @param id - The category ID
170
276
  * @returns The topic-level ancestor or undefined
277
+ * @deprecated Use `CvcRegistryService.getAncestors(scope, domain, key)` and
278
+ * filter to the level-1 entry from `@htilabs/platform-common-models`
279
+ * instead. See the module-level deprecation notice above. Will be removed
280
+ * in a future major version after Thread + PAVE migrate.
171
281
  */
172
282
  export function getIC48TopicForCategory(id: number): IC48Category | undefined {
173
283
  const cat = IC_48_BY_ID.get(id);
@@ -181,6 +291,17 @@ export function getIC48TopicForCategory(id: number): IC48Category | undefined {
181
291
  // ─── Well-Known Service IDs ──────────────────────────────────────────
182
292
  // These are commonly used service IDs for crisis services and derivation.
183
293
 
294
+ /**
295
+ * Well-known IC-48 IDs for crisis services.
296
+ *
297
+ * @deprecated This set is deferred to the **thread application layer**
298
+ * (`service-catalog-rules.v1.json#coreCrisisCodes[]` in the thread rig).
299
+ * It is intentionally NOT replaced by a field on platform-common models.
300
+ * Downstream consumers should move their crisis-service lookups into
301
+ * their own rig's configuration/rules file. See the module-level
302
+ * deprecation notice above. Will be removed in a future major version
303
+ * after Thread + PAVE migrate.
304
+ */
184
305
  export const IC_48_CRISIS_SERVICES = {
185
306
  /** Interpreter Services (01-07-06) */
186
307
  INTERPRETER: 158,
@@ -192,6 +313,16 @@ export const IC_48_CRISIS_SERVICES = {
192
313
  EMERGENCY_SHELTER: 99,
193
314
  } as const;
194
315
 
316
+ /**
317
+ * Well-known IC-48 IDs used by Thread's service-derivation logic.
318
+ *
319
+ * @deprecated This set is an application-layer concern and should be
320
+ * defined per-app (e.g., in the consuming rig's rules file) rather than
321
+ * in platform-common. Use `CvcRegistryService.getEntryByCode(scope, code)`
322
+ * to resolve individual entries at runtime if you still need a
323
+ * platform-common lookup. See the module-level deprecation notice above.
324
+ * Will be removed in a future major version after Thread + PAVE migrate.
325
+ */
195
326
  export const IC_48_DERIVATION_SERVICES = {
196
327
  /** Advocacy services */
197
328
  ADVOCACY: 20,
@@ -221,5 +352,16 @@ export const IC_48_DERIVATION_SERVICES = {
221
352
  INTERPRETER: 158,
222
353
  } as const;
223
354
 
355
+ /**
356
+ * @deprecated Mirrors {@link IC_48_CRISIS_SERVICES}; see that constant's
357
+ * deprecation notice. Will be removed in a future major version after
358
+ * Thread + PAVE migrate.
359
+ */
224
360
  export type IC48CrisisServiceId = (typeof IC_48_CRISIS_SERVICES)[keyof typeof IC_48_CRISIS_SERVICES];
361
+
362
+ /**
363
+ * @deprecated Mirrors {@link IC_48_DERIVATION_SERVICES}; see that constant's
364
+ * deprecation notice. Will be removed in a future major version after
365
+ * Thread + PAVE migrate.
366
+ */
225
367
  export type IC48DerivationServiceId = (typeof IC_48_DERIVATION_SERVICES)[keyof typeof IC_48_DERIVATION_SERVICES];
@@ -0,0 +1,31 @@
1
+ /**
2
+ * @htilabs/platform-common-models — CVC Source-of-Truth (SOT) re-exports
3
+ *
4
+ * Pre-parsed SOT JSON envelopes, exposed as named constants so consumers can
5
+ * load them without filesystem access. tsup bundles the JSON contents into
6
+ * the compiled `cvcs/index.js` at build time.
7
+ *
8
+ * The seed CLI in `scripts/seed-cvc.ts` still reads these files via `fs` so
9
+ * it can iterate over a directory; the bundled exports here are for runtime
10
+ * consumers (Thread, PAVE, tests) that just need the data.
11
+ *
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.
17
+ *
18
+ * See locked spec §2 (envelope shape) and §9.2 (entry shape).
19
+ */
20
+
21
+ import serviceCategoriesSot from "./serviceCategories.v1.0.0.json" with { type: "json" };
22
+ import serviceStatesSot from "./serviceStates.v1.0.0.json" with { type: "json" };
23
+ import serviceMechanismsSot from "./serviceMechanisms.v1.0.0.json" with { type: "json" };
24
+ import missingnessSot from "./missingness.v1.0.0.json" with { type: "json" };
25
+
26
+ export {
27
+ serviceCategoriesSot,
28
+ serviceStatesSot,
29
+ serviceMechanismsSot,
30
+ missingnessSot,
31
+ };
@@ -0,0 +1,50 @@
1
+ {
2
+ "domain": "missingness",
3
+ "name": "Universal Missingness Values",
4
+ "version": "1.0.0",
5
+ "levels": {
6
+ "0": "Unknown or Missing"
7
+ },
8
+ "entries": [
9
+ {
10
+ "code": "00-00-00-00-00-00-00",
11
+ "key": "missingness_root",
12
+ "title": "Unknown, Redacted, or Missing",
13
+ "selectable": false,
14
+ "parentCode": null,
15
+ "childCodes": [
16
+ "00-00-00-00-00-00-01",
17
+ "00-00-00-00-00-00-02",
18
+ "00-00-00-00-00-00-03"
19
+ ],
20
+ "definition": "Root group for values indicating absent, withheld, or uncollected data."
21
+ },
22
+ {
23
+ "code": "00-00-00-00-00-00-01",
24
+ "key": "unknown",
25
+ "title": "Unknown",
26
+ "selectable": true,
27
+ "parentCode": "00-00-00-00-00-00-00",
28
+ "childCodes": [],
29
+ "definition": "Value is unknown at time of entry."
30
+ },
31
+ {
32
+ "code": "00-00-00-00-00-00-02",
33
+ "key": "anonymous",
34
+ "title": "Anonymous",
35
+ "selectable": true,
36
+ "parentCode": "00-00-00-00-00-00-00",
37
+ "childCodes": [],
38
+ "definition": "Value is intentionally withheld or redacted."
39
+ },
40
+ {
41
+ "code": "00-00-00-00-00-00-03",
42
+ "key": "data_not_collected",
43
+ "title": "Data not collected",
44
+ "selectable": true,
45
+ "parentCode": "00-00-00-00-00-00-00",
46
+ "childCodes": [],
47
+ "definition": "No attempt was made to collect the value."
48
+ }
49
+ ]
50
+ }