@htilabs/platform-common-models 0.2.0-beta.4 → 0.4.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/README.md +38 -0
  2. package/dist/constants/index.cjs +0 -843
  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 -786
  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 +2350 -0
  11. package/dist/cvcs/index.cjs.map +1 -0
  12. package/dist/cvcs/index.d.cts +2449 -0
  13. package/dist/cvcs/index.d.ts +2449 -0
  14. package/dist/cvcs/index.js +2321 -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 +3132 -843
  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 +3106 -786
  23. package/dist/index.js.map +1 -1
  24. package/dist/models/index.cjs +212 -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 +210 -0
  29. package/dist/models/index.js.map +1 -1
  30. package/dist/{platform-auth-BTbQIY3b.d.cts → platform-auth-C-G2qeGM.d.cts} +1 -297
  31. package/dist/{platform-auth-BTbQIY3b.d.ts → platform-auth-C-G2qeGM.d.ts} +1 -297
  32. package/dist/schemas/index.cjs +196 -729
  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 +190 -729
  37. package/dist/schemas/index.js.map +1 -1
  38. package/dist/services/index.cjs +1443 -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 +1418 -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 +254 -0
  47. package/dist/validation/index.cjs.map +1 -0
  48. package/dist/validation/index.d.cts +252 -0
  49. package/dist/validation/index.d.ts +252 -0
  50. package/dist/validation/index.js +221 -0
  51. package/dist/validation/index.js.map +1 -0
  52. package/package.json +36 -12
  53. package/src/__tests__/__snapshots__/cvc-sot.snap +18 -0
  54. package/src/__tests__/cvc-sot-snapshot.test.ts +184 -0
  55. package/src/__tests__/cvc-structural.test.ts +129 -0
  56. package/src/constants/ic.ts +0 -925
  57. package/src/constants/service-catalog.ts +146 -4
  58. package/src/cvcs/index.ts +30 -0
  59. package/src/cvcs/serviceCategories.v1.0.0.json +2077 -0
  60. package/src/cvcs/serviceMechanisms.v1.0.0.json +87 -0
  61. package/src/cvcs/serviceStates.v1.0.0.json +146 -0
  62. package/src/generated/cvc-enums.ts +213 -0
  63. package/src/index.ts +61 -1
  64. package/src/models/cvcEntryModel.ts +32 -0
  65. package/src/models/cvcRegistryModel.ts +35 -0
  66. package/src/models/index.ts +8 -0
  67. package/src/schemas/cvcEntry.ts +159 -0
  68. package/src/schemas/cvcRegistry.ts +150 -0
  69. package/src/schemas/index.ts +16 -0
  70. package/src/services/__tests__/cvcRegistryService.test.ts +614 -0
  71. package/src/services/cvcRegistryService.ts +729 -0
  72. package/src/services/index.ts +21 -0
  73. package/src/validation/cvc.ts +397 -0
  74. package/src/validation/index.ts +15 -0
@@ -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,30 @@
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, levels, entries }`) — validate it with
14
+ * `CvcEnvelopeSchema` from `../validation/cvc.ts` before trusting the shape,
15
+ * since these JSON files are the source of truth and the import skips runtime
16
+ * validation. Missingness entries live inside each domain's own entry list as
17
+ * of format v2 (segment 1 uses the Notion-aligned domain prefix).
18
+ *
19
+ * See locked spec §2 (envelope shape) and §9.2 (entry shape).
20
+ */
21
+
22
+ import serviceCategoriesSot from "./serviceCategories.v1.0.0.json" with { type: "json" };
23
+ import serviceStatesSot from "./serviceStates.v1.0.0.json" with { type: "json" };
24
+ import serviceMechanismsSot from "./serviceMechanisms.v1.0.0.json" with { type: "json" };
25
+
26
+ export {
27
+ serviceCategoriesSot,
28
+ serviceStatesSot,
29
+ serviceMechanismsSot,
30
+ };