@htilabs/platform-common-models 0.13.0 → 0.14.0

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 (63) hide show
  1. package/dist/constants/index.cjs +106 -0
  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 +98 -0
  6. package/dist/constants/index.js.map +1 -1
  7. package/dist/{cvcEntry-ctHTp2df.d.cts → cvcEntry-0BIB9sen.d.cts} +36 -36
  8. package/dist/{cvcEntry-ctHTp2df.d.ts → cvcEntry-0BIB9sen.d.ts} +36 -36
  9. package/dist/cvcs/index.cjs +562 -120
  10. package/dist/cvcs/index.cjs.map +1 -1
  11. package/dist/cvcs/index.d.cts +589 -121
  12. package/dist/cvcs/index.d.ts +589 -121
  13. package/dist/cvcs/index.js +562 -120
  14. package/dist/cvcs/index.js.map +1 -1
  15. package/dist/enums/index.cjs +22 -2
  16. package/dist/enums/index.cjs.map +1 -1
  17. package/dist/enums/index.d.cts +29 -9
  18. package/dist/enums/index.d.ts +29 -9
  19. package/dist/enums/index.js +22 -2
  20. package/dist/enums/index.js.map +1 -1
  21. package/dist/{index-4DiJrn7y.d.ts → index-CDoqrfc1.d.ts} +1 -1
  22. package/dist/{index-qreOzXYS.d.cts → index-Zu_mOJRn.d.cts} +1 -1
  23. package/dist/index.cjs +690 -122
  24. package/dist/index.cjs.map +1 -1
  25. package/dist/index.d.cts +3 -3
  26. package/dist/index.d.ts +3 -3
  27. package/dist/index.js +682 -122
  28. package/dist/index.js.map +1 -1
  29. package/dist/models/index.d.cts +2 -2
  30. package/dist/models/index.d.ts +2 -2
  31. package/dist/{platform-auth-Dv5fu0Fh.d.cts → platform-auth-CrF5U_JH.d.cts} +113 -3
  32. package/dist/{platform-auth-Dv5fu0Fh.d.ts → platform-auth-CrF5U_JH.d.ts} +113 -3
  33. package/dist/schemas/index.cjs +296 -0
  34. package/dist/schemas/index.cjs.map +1 -1
  35. package/dist/schemas/index.d.cts +11 -11
  36. package/dist/schemas/index.d.ts +11 -11
  37. package/dist/schemas/index.js +296 -0
  38. package/dist/schemas/index.js.map +1 -1
  39. package/dist/types/index.d.cts +2 -2
  40. package/dist/types/index.d.ts +2 -2
  41. package/package.json +26 -27
  42. package/src/__sot__/coreIndicatorFields.ts +4 -4
  43. package/src/__sot__/coreIndicators.pin.json +62 -2
  44. package/src/__sot__/scoringEmits.pin.json +9 -4
  45. package/src/__tests__/__snapshots__/cvc-sot.snap +11 -11
  46. package/src/__tests__/cvc-136-scoring-invariant.test.ts +89 -28
  47. package/src/__tests__/cvc-drift-gate.test.ts +165 -32
  48. package/src/__tests__/cvc-sot-snapshot.test.ts +21 -12
  49. package/src/__tests__/cvc-structural.test.ts +8 -8
  50. package/src/__tests__/incident-participation-roles-canon.test.ts +424 -0
  51. package/src/__tests__/referral-entity-category-canon.test.ts +383 -0
  52. package/src/constants/ic.ts +321 -3
  53. package/src/cvcs/{coreIndicators.v1.0.0.json → coreIndicators.v1.1.0.json} +93 -10
  54. package/src/cvcs/{highestEducationLevelCompleted.v1.0.0.json → highestEducationLevelCompleted.v1.1.0.json} +1 -1
  55. package/src/cvcs/incidentParticipationRoles.v1.1.0.json +433 -0
  56. package/src/cvcs/{incomeBenefitsSources.v1.0.0.json → incomeBenefitsSources.v1.1.0.json} +1 -1
  57. package/src/cvcs/index.ts +8 -8
  58. package/src/cvcs/{referralEntityCategory.v1.0.0.json → referralEntityCategory.v1.1.0.json} +192 -54
  59. package/src/cvcs/{serviceStates.v1.0.0.json → serviceStates.v1.1.0.json} +1 -1
  60. package/src/cvcs/{sourceSubtype.v1.1.0.json → sourceSubtype.v1.2.0.json} +1 -1
  61. package/src/cvcs/{verificationMethod.v1.0.0.json → verificationMethod.v1.1.0.json} +1 -1
  62. package/src/generated/cvc-enums.ts +29 -9
  63. package/src/cvcs/incidentParticipationRoles.v1.0.0.json +0 -212
@@ -18,20 +18,25 @@
18
18
  * THE PIN
19
19
  * -------
20
20
  * `SCORING_EMITS_BY_CODE` is the key set of `emits_by_code` in
21
- * `weights/risk.weights.json` at htilabstech/hti-scoring@9b5d654 (169 codes).
21
+ * `weights/risk.weights.json` at htilabstech/hti-scoring@9c209cf (174 codes).
22
22
  * It is a COMMITTED PIN, not a live read - platform-common must not take a
23
23
  * build-time dependency on the scoring repo. When @hti/scoring starts emitting
24
24
  * a new code, bumping this list is a deliberate, reviewable commit that forces
25
25
  * the matching CVC-136 entry to be authored in the same PR.
26
26
  *
27
- * SCORING IS AHEAD OF THE CODEBOOK ON 2 CODES
28
- * -------------------------------------------
29
- * `coercive_debt_pressure_youth` and `debt_terms_deceptive_youth` are emitted
30
- * by @hti/scoring but are NOT in the prototype's canonical
31
- * `data/core_indicators.yaml` (208 codes) at HEAD a596eb9. They are KEPT
32
- * (210 = 208 + 2) and flagged `pendingUpstreamAdoption: true` in the SOT JSON.
33
- * Dropping them because they are "not in the prototype" would break the
34
- * scoring contract. That is the trap this test exists to prevent.
27
+ * SCORING IS NO LONGER AHEAD OF THE CODEBOOK (0 CODES)
28
+ * ----------------------------------------------------
29
+ * From 0.8.13 through the 622410b refresh, `coercive_debt_pressure_youth` and
30
+ * `debt_terms_deceptive_youth` were emitted by @hti/scoring (9b5d654) but
31
+ * were NOT in the prototype's canonical `data/core_indicators.yaml`. They were
32
+ * KEPT and flagged `pendingUpstreamAdoption: true` because dropping a code
33
+ * scoring emits would break the scoring contract — that is the trap this test
34
+ * exists to prevent. hti-scoring 9c209cf retired both emits in favour of the
35
+ * canonical `coercive_debt_pressure` / `debt_terms_deceptive` (whose upstream
36
+ * rows carry the `_youth` names as `legacy_aliases`), and the catalog never
37
+ * adopted them, so at c53378f / 9c209cf they are WITHDRAWN: no emitter, no
38
+ * catalog row, nothing left to protect. `PENDING_UPSTREAM_ADOPTION` is kept as
39
+ * an EMPTY list so the next genuinely-ahead emit has a named place to land.
35
40
  */
36
41
 
37
42
  import { readFileSync } from "node:fs";
@@ -49,12 +54,19 @@ const SOT_FILE = path.resolve(
49
54
  __dirname,
50
55
  "..",
51
56
  "cvcs",
52
- "coreIndicators.v1.0.0.json",
57
+ "coreIndicators.v1.1.0.json",
53
58
  );
54
59
 
55
60
  /**
56
61
  * `Object.keys(RISK_WEIGHTS.emits_by_code)` at
57
- * htilabstech/hti-scoring@9b5d654 (weights/risk.weights.json). 169 codes.
62
+ * htilabstech/hti-scoring@9c209cf (weights/risk.weights.json). 174 codes.
63
+ * 9b5d654 -> 9c209cf: +8 (`child_welfare_system_involvement`,
64
+ * `clients_unaware_of_third_party_coordination`,
65
+ * `constraints_due_to_legal_status`,
66
+ * `depends_on_spouse_or_family_for_immigration_status`,
67
+ * `does_not_control_housing`, `juvenile_justice_system_involvement`,
68
+ * `oppressive_home_life`, `recent_separation`) / -3 (`living_with_abuser`,
69
+ * `coercive_debt_pressure_youth`, `debt_terms_deceptive_youth`).
58
70
  * PINNED - see the module header before editing.
59
71
  */
60
72
  const SCORING_EMITS_BY_CODE: readonly string[] = [
@@ -80,24 +92,27 @@ const SCORING_EMITS_BY_CODE: readonly string[] = [
80
92
  "branding_or_unusual_tattoos_tied_to_control",
81
93
  "cannot_stop_working_or_freely_leave",
82
94
  "child_not_abusers_in_household",
95
+ "child_welfare_system_involvement",
96
+ "clients_unaware_of_third_party_coordination",
83
97
  "coerced_to_misrepresent_identity_or_activity",
84
98
  "coercive_debt_pressure",
85
- "coercive_debt_pressure_youth",
86
99
  "coercive_migration_or_forced_travel",
87
100
  "cognitive_or_functional_impairment_affecting_consent",
88
101
  "commercial_sex_association_words_or_places",
89
102
  "concerning_mannerisms_anxious_fearful_depressed",
90
103
  "concerning_sexual_behavior_pattern",
104
+ "constraints_due_to_legal_status",
91
105
  "control_quota_required",
92
106
  "cs_activity_criminal_org_connection",
93
107
  "cs_industry_related_criminal_history",
94
108
  "current_injuries_from_abuser",
95
109
  "currently_minor_in_commercial_sex",
96
110
  "debt_terms_deceptive",
97
- "debt_terms_deceptive_youth",
98
111
  "denied_basic_needs",
99
112
  "depends_on_employer_for_immigration_status",
113
+ "depends_on_spouse_or_family_for_immigration_status",
100
114
  "does_not_control_finances_or_earnings",
115
+ "does_not_control_housing",
101
116
  "does_not_control_identity_documents",
102
117
  "employer_keeps_pay_or_pays_less_than_expected",
103
118
  "engages_in_commercial_sex_act",
@@ -135,11 +150,11 @@ const SCORING_EMITS_BY_CODE: readonly string[] = [
135
150
  "inability_to_account_for_self",
136
151
  "intimate_partner_violence_reported_to_law_enforcement",
137
152
  "juvenile_justice_or_child_welfare_involvement",
153
+ "juvenile_justice_system_involvement",
138
154
  "labor_services_activity_recorded",
139
155
  "limited_english_proficiency",
140
156
  "limited_independence",
141
157
  "lives_or_sleeps_at_place_of_work",
142
- "living_with_abuser",
143
158
  "meets_or_has_sex_with_internet_contacts",
144
159
  "monitored_or_isolated_by_controlling_party",
145
160
  "much_older_intimate_partner",
@@ -148,6 +163,7 @@ const SCORING_EMITS_BY_CODE: readonly string[] = [
148
163
  "new_to_commercial_sex_industry",
149
164
  "non_consensual_photography_or_recording",
150
165
  "not_in_control_of_immigration_documentation",
166
+ "oppressive_home_life",
151
167
  "other_instability_or_vulnerability_factors",
152
168
  "owes_money_and_cannot_pay_off",
153
169
  "paid_or_owes_fee_to_arrange_travel_to_us",
@@ -164,6 +180,7 @@ const SCORING_EMITS_BY_CODE: readonly string[] = [
164
180
  "prior_victimization_or_abuse_history",
165
181
  "promise_of_work_different_than_current_work",
166
182
  "received_things_of_value_while_missing_from_care",
183
+ "recent_separation",
167
184
  "recruited_by_third_party_into_cs_industry",
168
185
  "relies_on_temporary_resources_for_basic_needs",
169
186
  "reports_physical_harm_by_employer_or_partner",
@@ -229,11 +246,11 @@ const SCORING_EMITS_BY_CODE: readonly string[] = [
229
246
  "youth_watched_filmed_or_photographed_sexually_explicit",
230
247
  ];
231
248
 
232
- /** Codes @hti/scoring emits that upstream `core_indicators.yaml` has not yet adopted. */
233
- const PENDING_UPSTREAM_ADOPTION: readonly string[] = [
234
- "coercive_debt_pressure_youth",
235
- "debt_terms_deceptive_youth",
236
- ];
249
+ /**
250
+ * Codes @hti/scoring emits that upstream `core_indicators.yaml` has not yet
251
+ * adopted. EMPTY as of c53378f / 9c209cf — see the module header.
252
+ */
253
+ const PENDING_UPSTREAM_ADOPTION: readonly string[] = [];
237
254
 
238
255
  const envelope = CvcEnvelopeSchema.parse(
239
256
  JSON.parse(readFileSync(SOT_FILE, "utf-8")),
@@ -244,6 +261,8 @@ const substantive = envelope.entries.filter(
244
261
  (e) => e.code.split("-")[1] !== "000",
245
262
  );
246
263
  const substantiveKeys = new Set(substantive.map((e) => e.key));
264
+ const isDeprecated = (e: object): boolean =>
265
+ (e as { deprecated?: unknown }).deprecated === true;
247
266
 
248
267
  describe("CVC-136 core_indicators", () => {
249
268
  it("is numbered 136 in segment 1 of every code", () => {
@@ -261,14 +280,22 @@ describe("CVC-136 core_indicators", () => {
261
280
  ]);
262
281
  });
263
282
 
264
- it("has exactly 216 substantive codes (214 canonical + 2 scoring-ahead)", () => {
283
+ it("has exactly 222 substantive codes (220 canonical + 0 scoring-ahead + 2 deprecated)", () => {
265
284
  // 0.8.14 refreshed the catalog pin a596eb9 (208) -> 84a1b67 (213):
266
285
  // +5 upstream mints, 0 withdrawn.
267
- // This refresh took it again 84a1b67 (213) -> 622410b (214): +1 upstream
268
- // mint (`active_protective_order`, minted 2026-08-08), 0 withdrawn. The 2
269
- // scoring-ahead codes are unchanged and still absent upstream.
270
- expect(substantive.length).toBe(216);
271
- expect(envelope.entries.length).toBe(220);
286
+ // 622410b refresh: 84a1b67 (213) -> 622410b (214): +1 upstream mint
287
+ // (`active_protective_order`, minted 2026-08-08), 0 withdrawn.
288
+ // c53378f refresh: 622410b (214) -> c53378f (220): +6 upstream mints
289
+ // (`disclosed_fear_at_intake`, `does_not_control_housing`,
290
+ // `oppressive_home_life`, `recent_separation`, `survival_sex`,
291
+ // `unable_to_speak_freely`), 0 withdrawn upstream; the 2 scoring-ahead
292
+ // `_youth` codes leave the allowlist (scoring 9c209cf no longer emits
293
+ // them) and become DEPRECATED read-only rows — kept because PAVE 2.0
294
+ // `develop` still writes both from the IDA (see the drift gate's
295
+ // `CVC136_DEPRECATED`). SOT version 1.0.0 -> 1.1.0 in the same change.
296
+ expect(substantive.length).toBe(222);
297
+ expect(substantive.filter((e) => !isDeprecated(e)).length).toBe(220);
298
+ expect(envelope.entries.length).toBe(226);
272
299
  });
273
300
 
274
301
  it("has no duplicate keys", () => {
@@ -277,8 +304,8 @@ describe("CVC-136 core_indicators", () => {
277
304
  });
278
305
 
279
306
  describe("CVC-136 <-> @hti/scoring emits_by_code invariant", () => {
280
- it("pins exactly 169 emitted codes", () => {
281
- expect(new Set(SCORING_EMITS_BY_CODE).size).toBe(169);
307
+ it("pins exactly 174 emitted codes", () => {
308
+ expect(new Set(SCORING_EMITS_BY_CODE).size).toBe(174);
282
309
  });
283
310
 
284
311
  it("EVERY code @hti/scoring emits exists in CVC-136", () => {
@@ -295,7 +322,9 @@ describe("CVC-136 <-> @hti/scoring emits_by_code invariant", () => {
295
322
  expect(missing).toHaveLength(0);
296
323
  });
297
324
 
298
- it("the 2 scoring-ahead codes are present and flagged pendingUpstreamAdoption", () => {
325
+ it("the scoring-ahead list is EMPTY; any entry must be present and flagged pendingUpstreamAdoption", () => {
326
+ // Guard the escape hatch: scoring is not ahead of the catalog at 9c209cf.
327
+ expect(PENDING_UPSTREAM_ADOPTION).toEqual([]);
299
328
  for (const code of PENDING_UPSTREAM_ADOPTION) {
300
329
  const entry = substantive.find((e) => e.key === code);
301
330
  expect(entry, `${code} must be present in CVC-136`).toBeDefined();
@@ -317,6 +346,38 @@ describe("CVC-136 <-> @hti/scoring emits_by_code invariant", () => {
317
346
  expect(substantiveKeys.has("unusual_work_circumstances_general")).toBe(false);
318
347
  expect(substantiveKeys.has("unusual_work_circumstances")).toBe(true);
319
348
  });
349
+
350
+ it("the former `_youth` scoring-ahead codes are DEPRECATED (read-only, superseded), never live; their canonical rows ship", () => {
351
+ // hti-scoring 9c209cf retired these emits and the catalog never adopted
352
+ // them — but PAVE 2.0 `develop` @ 07f3ccd still writes both from the IDA
353
+ // (`IDA-syn-missing_care-4i`/`-4ii`), so the keys stay resolvable here as
354
+ // deprecated rows pointing at their canonical successors.
355
+ for (const [key, successor] of [
356
+ ["coercive_debt_pressure_youth", "coercive_debt_pressure"],
357
+ ["debt_terms_deceptive_youth", "debt_terms_deceptive"],
358
+ ] as const) {
359
+ const row = substantive.find((e) => e.key === key) as
360
+ | (typeof substantive)[number] & { deprecated?: unknown; supersededBy?: unknown }
361
+ | undefined;
362
+ expect(row, `${key} must still resolve`).toBeDefined();
363
+ expect(row!.selectable).toBe(false);
364
+ expect(row!.deprecated).toBe(true);
365
+ expect(row!.supersededBy).toBe(successor);
366
+ expect(SCORING_EMITS_BY_CODE, `${key} is not emitted`).not.toContain(key);
367
+ expect(substantiveKeys.has(successor)).toBe(true);
368
+ expect(SCORING_EMITS_BY_CODE, `${successor} is emitted`).toContain(successor);
369
+ }
370
+ });
371
+
372
+ it("the hardcoded emit set is identical to scoringEmits.pin.json (one SoT, pinned twice on purpose)", () => {
373
+ // Two declarations of the 174-code emit set exist — this hand-pinned list
374
+ // (so a pin-file edit alone cannot move the invariant) and the generated
375
+ // pin — and they must never drift apart.
376
+ const pin = JSON.parse(
377
+ readFileSync(path.resolve(__dirname, "..", "__sot__", "scoringEmits.pin.json"), "utf8"),
378
+ ) as { codes: string[] };
379
+ expect([...SCORING_EMITS_BY_CODE].sort()).toEqual([...pin.codes].sort());
380
+ });
320
381
  });
321
382
 
322
383
  describe("CVC-136 SOT JSON <-> hand-coded ic.ts array", () => {
@@ -371,15 +371,63 @@ const INDEX_ABSENT: Record<string, { cvc: number; reason: string }> = {
371
371
 
372
372
  /**
373
373
  * The ONLY codes CVC-136 may carry that `core_indicators.yaml` does not.
374
- * @hti/scoring EMITS these two, so dropping them would break the scoring
375
- * contract — scoring is genuinely AHEAD of the catalog here. They are flagged
376
- * `pendingUpstreamAdoption: true` in the SOT JSON. Upstream must adopt or
377
- * deprecate them; until then this list must stay EXACTLY these two.
374
+ * A code belongs here only while @hti/scoring EMITS it and the catalog has not
375
+ * adopted it — dropping such a code would break the scoring contract, so
376
+ * scoring is genuinely AHEAD of the catalog. Each must be flagged
377
+ * `pendingUpstreamAdoption: true` in the SOT JSON.
378
+ *
379
+ * EMPTY as of coreIndicators@c53378f / scoringEmits@9c209cf. From 0.8.13 it
380
+ * held exactly `coercive_debt_pressure_youth` and `debt_terms_deceptive_youth`;
381
+ * hti-scoring 9c209cf retired both emits in favour of the canonical
382
+ * `coercive_debt_pressure` / `debt_terms_deceptive` (whose upstream rows carry
383
+ * the `_youth` names as `legacy_aliases`) and the catalog never adopted them.
384
+ * Both left this allowlist and became DEPRECATED rows (see
385
+ * `CVC136_DEPRECATED` below) — not withdrawn, because PAVE 2.0 still writes
386
+ * them. Until scoring is ahead again this list must stay EXACTLY empty.
387
+ */
388
+ const SCORING_AHEAD_OF_CATALOG: readonly string[] = [];
389
+
390
+ /**
391
+ * CVC-136 keys the catalog no longer carries but a consumer still WRITES, kept
392
+ * read-only in the SOT as `selectable: false` + `deprecated: true` +
393
+ * `supersededBy: <canonical key>` (the CVC-69 `incidentParticipationRoles`
394
+ * v1.1.0 shape). A deprecated row is not an invention: it is a retired key with
395
+ * a resolution path INSIDE this SOT, so an assertion already stored under it
396
+ * never dangles and the positional number can never be reissued to another
397
+ * meaning.
398
+ *
399
+ * Why these two are here and not simply gone (verified 2026-10-06 against the
400
+ * consumers' `develop` heads, not assumed): PAVE 2.0 @ 07f3ccd emits both from
401
+ * the In-Depth Assessment — `IDA-syn-missing_care-4i` / `-4ii`
402
+ * (`packages/api-core/src/rules/assessments/ida/emits.ts`,
403
+ * `packages/assessments-registry/src/instruments/ida.ts`), keys both in
404
+ * `determination-evidence/crosswalk.ts`, and still scores them from its
405
+ * 2026-07-17 vendored `risk.weights.json` — so stored PAVE assertions can carry
406
+ * either key today. Thread @ 28580ab has no writer (its 2026-09-30 vendored
407
+ * weights do not emit them; its only mention is a generated prototype catalog
408
+ * copy nothing validates against). Removing the rows would leave PAVE's stored
409
+ * values with no resolution anywhere in platform-common (ADR row 9: "being
410
+ * written to survivor records today. This cannot stay unresolved.").
411
+ *
412
+ * EXIT CRITERIA — a row leaves this map only when (a) PAVE's IDA emits the
413
+ * canonical key instead (PAVE parity card) AND (b) stored `_youth` assertions
414
+ * have been migrated or confirmed absent in `platform-prod`. Until then this
415
+ * map must stay EXACTLY these two.
378
416
  */
379
- const SCORING_AHEAD_OF_CATALOG: readonly string[] = [
380
- "coercive_debt_pressure_youth",
381
- "debt_terms_deceptive_youth",
382
- ];
417
+ const CVC136_DEPRECATED: Readonly<Record<string, string>> = {
418
+ coercive_debt_pressure_youth: "coercive_debt_pressure",
419
+ debt_terms_deceptive_youth: "debt_terms_deceptive",
420
+ };
421
+
422
+ /**
423
+ * Positional CVC-136 numbers (the second segment of the code) that are HELD by a
424
+ * deprecated row and may never be issued to any other key. Pinned by value so a
425
+ * future refresh that drops the deprecated row and reuses the slot fails here.
426
+ */
427
+ const CVC136_HELD_SLOTS: Readonly<Record<string, string>> = {
428
+ "033": "coercive_debt_pressure_youth",
429
+ "050": "debt_terms_deceptive_youth",
430
+ };
383
431
 
384
432
  // ─── Helpers ────────────────────────────────────────────────────────────────
385
433
 
@@ -387,9 +435,18 @@ const CODE_RE = /^\d{3}(-\d{3}){6}$/;
387
435
  const KEY_RE = /^[a-z][a-z0-9_]*$/;
388
436
  const isMissingness = (e: Entry): boolean => e.code.split("-")[1] === "000";
389
437
  const substantiveOf = (d: Domain): Entry[] => d.entries.filter((e) => !isMissingness(e));
438
+ const isDeprecated = (e: Entry): boolean =>
439
+ (e as Entry & { deprecated?: unknown }).deprecated === true;
390
440
 
391
441
  const cvc136 = DOMAINS.find((d) => d.domain === "core_indicators")!;
442
+ /** Every substantive CVC-136 key, deprecated rows INCLUDED — the set a stored value must resolve against. */
392
443
  const cvc136Keys = new Set(substantiveOf(cvc136).map((e) => e.key));
444
+ /** The LIVE CVC-136 key set — what the catalog must account for and what a new write may use. */
445
+ const cvc136LiveKeys = new Set(
446
+ substantiveOf(cvc136)
447
+ .filter((e) => !isDeprecated(e))
448
+ .map((e) => e.key),
449
+ );
393
450
 
394
451
  // ═══════════════════════════════════════════════════════════════════════════
395
452
  // A. SCORING EXPRESSIBILITY
@@ -404,7 +461,7 @@ describe("GATE A — every code @hti/scoring emits exists in CVC-136", () => {
404
461
  `(This is how the entire perpetrator lane went missing — facilitator scoring\n` +
405
462
  " was unexpressible for an entire release.)\n\n" +
406
463
  ` MISSING: ${missing.join(", ")}\n\n` +
407
- "TO FIX: add each code to src/cvcs/coreIndicators.v1.0.0.json (sourced from\n" +
464
+ "TO FIX: add each code to src/cvcs/coreIndicators.v1.1.0.json (sourced from\n" +
408
465
  ` ${coreIndicatorsPin.sourceRepo}/${coreIndicatorsPin.sourceFile}` +
409
466
  ` @ ${coreIndicatorsPin.sourceSha}),\n` +
410
467
  " then regenerate CVC_136_CORE_INDICATOR_VALUES in src/constants/ic.ts.\n" +
@@ -423,8 +480,10 @@ describe("GATE B — CVC-136 invents nothing", () => {
423
480
  const catalog = new Set(coreIndicatorsPin.codes);
424
481
  const allowed = new Set(SCORING_AHEAD_OF_CATALOG);
425
482
 
426
- it("every CVC-136 code is in core_indicators.yaml or the annotated allowlist", () => {
427
- const invented = [...cvc136Keys].filter((k) => !catalog.has(k) && !allowed.has(k)).sort();
483
+ it("every LIVE CVC-136 code is in core_indicators.yaml or the annotated allowlist", () => {
484
+ // Deprecated rows are excluded here and policed by their own block below:
485
+ // they are retired keys with an in-SOT successor, not inventions.
486
+ const invented = [...cvc136LiveKeys].filter((k) => !catalog.has(k) && !allowed.has(k)).sort();
428
487
  if (invented.length > 0) {
429
488
  throw new Error(
430
489
  `${invented.length} INVENTED code(s) in CVC-136 — they exist in neither\n` +
@@ -434,7 +493,7 @@ describe("GATE B — CVC-136 invents nothing", () => {
434
493
  "(0.8.12 shipped 56 of these — `vc_*`, `csi_*`, `csctx_*`, `dv_*`, `net_*`,\n" +
435
494
  " `auto_*` rollup prefixes consumed by nobody. They are not indicators.)\n\n" +
436
495
  ` INVENTED: ${invented.join(", ")}\n\n` +
437
- "TO FIX: remove them from src/cvcs/coreIndicators.v1.0.0.json — OR, if\n" +
496
+ "TO FIX: remove them from src/cvcs/coreIndicators.v1.1.0.json — OR, if\n" +
438
497
  " @hti/scoring genuinely emits them ahead of the catalog, add them to\n" +
439
498
  " SCORING_AHEAD_OF_CATALOG in this file WITH `pendingUpstreamAdoption: true`\n" +
440
499
  " on the entry, and raise adoption with the codebook owner.",
@@ -443,12 +502,15 @@ describe("GATE B — CVC-136 invents nothing", () => {
443
502
  expect(invented).toEqual([]);
444
503
  });
445
504
 
446
- it("the scoring-ahead allowlist is EXACTLY the 2 known codes, each flagged", () => {
505
+ it("the scoring-ahead allowlist is EXACTLY empty; any future entry must be emitted, absent upstream, and flagged", () => {
447
506
  // Guard the escape hatch: it must not quietly become a dumping ground.
448
- expect([...SCORING_AHEAD_OF_CATALOG].sort()).toEqual([
449
- "coercive_debt_pressure_youth",
450
- "debt_terms_deceptive_youth",
451
- ]);
507
+ expect([...SCORING_AHEAD_OF_CATALOG].sort()).toEqual([]);
508
+ // The former `_youth` pair must not creep back in as LIVE rows by any route.
509
+ for (const code of Object.keys(CVC136_DEPRECATED)) {
510
+ expect(scoringEmitsPin.codes, `${code} is no longer emitted by scoring`).not.toContain(code);
511
+ expect(coreIndicatorsPin.codes, `${code} is still absent upstream`).not.toContain(code);
512
+ expect(cvc136LiveKeys.has(code), `${code} must not be a LIVE CVC-136 row`).toBe(false);
513
+ }
452
514
  for (const code of SCORING_AHEAD_OF_CATALOG) {
453
515
  expect(scoringEmitsPin.codes, `${code} must actually be emitted by scoring`).toContain(code);
454
516
  expect(coreIndicatorsPin.codes, `${code} must still be absent upstream`).not.toContain(code);
@@ -458,6 +520,50 @@ describe("GATE B — CVC-136 invents nothing", () => {
458
520
  expect(entry?.["pendingUpstreamAdoption"], `${code} must be flagged`).toBe(true);
459
521
  }
460
522
  });
523
+
524
+ it("the deprecated set is EXACTLY the 2 former scoring-ahead codes, each read-only with an in-SOT successor", () => {
525
+ const deprecatedRows = substantiveOf(cvc136).filter(isDeprecated) as (Entry & {
526
+ deprecated?: unknown;
527
+ supersededBy?: unknown;
528
+ pendingUpstreamAdoption?: unknown;
529
+ })[];
530
+ expect(deprecatedRows.map((e) => e.key).sort()).toEqual(Object.keys(CVC136_DEPRECATED).sort());
531
+ for (const row of deprecatedRows) {
532
+ const successor = CVC136_DEPRECATED[row.key];
533
+ expect(row.selectable, `${row.key} must not be offered for new writes`).toBe(false);
534
+ expect(row.supersededBy, `${row.key} must name its canonical successor`).toBe(successor);
535
+ expect(row.pendingUpstreamAdoption, `${row.key} is deprecated, not scoring-ahead`).toBeUndefined();
536
+ // The successor is a LIVE, selectable, catalog-backed row — so the
537
+ // resolution path a reader follows lands on something real.
538
+ const target = substantiveOf(cvc136).find((e) => e.key === successor);
539
+ expect(target, `${row.key} -> ${successor} must resolve in CVC-136`).toBeDefined();
540
+ expect(target!.selectable, `${successor} must be selectable`).toBe(true);
541
+ expect(isDeprecated(target!), `${successor} must not itself be deprecated`).toBe(false);
542
+ expect(catalog.has(successor), `${successor} must be in core_indicators.yaml`).toBe(true);
543
+ // A deprecated row has no emitter in scoring — if it did, it would be
544
+ // live (or scoring-ahead), not deprecated.
545
+ expect(scoringEmitsPin.codes, `${row.key} must not be emitted by scoring`).not.toContain(row.key);
546
+ }
547
+ });
548
+
549
+ it("the held positional slots (136-033, 136-050) belong to their deprecated keys and are never reissued", () => {
550
+ const bySlot = new Map<string, Entry[]>();
551
+ for (const e of substantiveOf(cvc136)) {
552
+ const slot = e.code.split("-")[1];
553
+ bySlot.set(slot, [...(bySlot.get(slot) ?? []), e]);
554
+ }
555
+ for (const [slot, holder] of Object.entries(CVC136_HELD_SLOTS)) {
556
+ const occupants = bySlot.get(slot) ?? [];
557
+ expect(
558
+ occupants.map((e) => e.key),
559
+ `slot 136-${slot} must be held by exactly its deprecated key`,
560
+ ).toEqual([holder]);
561
+ expect(isDeprecated(occupants[0]!), `slot 136-${slot} holder must be deprecated`).toBe(true);
562
+ }
563
+ // And no slot anywhere in CVC-136 is shared by two keys.
564
+ const shared = [...bySlot.entries()].filter(([, es]) => es.length > 1);
565
+ expect(shared.map(([s, es]) => `${s}: ${es.map((e) => e.key).join(",")}`)).toEqual([]);
566
+ });
461
567
  });
462
568
 
463
569
  // ═══════════════════════════════════════════════════════════════════════════
@@ -657,17 +763,28 @@ describe("GATE F — entry counts and selectable counts are never conflated", ()
657
763
  }
658
764
  });
659
765
 
660
- it("CVC-69 regression: 20 entries = 15 selectable + 4 group rows + missingness_root", () => {
766
+ it("CVC-69 regression: 31 entries = 21 selectable + 4 group rows + 5 deprecated + missingness_root", () => {
767
+ // v1.1.0 (canon re-mirror) adds a THIRD kind of non-selectable row: the five
768
+ // superseded v1.0.0 keys, kept read-only (`deprecated: true`). They are
769
+ // neither group rows nor missingness, and must not be counted as either.
770
+ const isDeprecated = (e: Entry): boolean =>
771
+ (e as Entry & { deprecated?: boolean }).deprecated === true;
661
772
  const d = DOMAINS.find((x) => x.domain === "incident_participation_roles")!;
662
773
  const selectable = d.entries.filter((e) => e.selectable);
663
- const groupRows = d.entries.filter((e) => !e.selectable && !isMissingness(e));
774
+ const deprecated = d.entries.filter((e) => !e.selectable && isDeprecated(e));
775
+ const groupRows = d.entries.filter(
776
+ (e) => !e.selectable && !isMissingness(e) && !isDeprecated(e),
777
+ );
664
778
  const missRoot = d.entries.filter((e) => !e.selectable && isMissingness(e));
665
779
 
666
- expect(d.entries.length, "total entries").toBe(20);
667
- expect(selectable.length, "selectable").toBe(15);
780
+ expect(d.entries.length, "total entries").toBe(31);
781
+ expect(selectable.length, "selectable").toBe(21);
782
+ expect(deprecated.length, "non-selectable deprecated (superseded) roles").toBe(5);
668
783
  expect(groupRows.length, "non-selectable group rows").toBe(4);
669
784
  expect(missRoot.length, "non-selectable missingness_root").toBe(1);
670
- expect(selectable.length + groupRows.length + missRoot.length).toBe(20);
785
+ expect(
786
+ selectable.length + deprecated.length + groupRows.length + missRoot.length,
787
+ ).toBe(31);
671
788
  // If a consumer's boot-check ever asserts `entries.length === 14`, it is the
672
789
  // CONSUMER that is wrong, not CVC-69.
673
790
  });
@@ -768,7 +885,7 @@ describe("GATE H — CVC-136 restates every field the catalog states", () => {
768
885
  ` ${absent.join(", ")}\n\n` +
769
886
  "GATE B only checks the other direction (CVC-136 invents nothing), so a\n" +
770
887
  " catalog code dropped on refresh would otherwise pass unnoticed.\n" +
771
- "TO FIX: add each to src/cvcs/coreIndicators.v1.0.0.json.",
888
+ "TO FIX: add each to src/cvcs/coreIndicators.v1.1.0.json.",
772
889
  );
773
890
  }
774
891
  expect(absent).toEqual([]);
@@ -807,7 +924,7 @@ describe("GATE H — CVC-136 restates every field the catalog states", () => {
807
924
  "0.8.17 dropped a label rename plus a deprecation qualifier).\n\n" +
808
925
  `${mismatches.join("\n")}\n\n` +
809
926
  "TO FIX: copy the `catalog:` value printed above into the matching entry\n" +
810
- " of src/cvcs/coreIndicators.v1.0.0.json.\n" +
927
+ " of src/cvcs/coreIndicators.v1.1.0.json.\n" +
811
928
  " COPY THE PRINTED VALUE, not the raw scalar out of\n" +
812
929
  ` ${coreIndicatorsPin.sourceRepo}/${coreIndicatorsPin.sourceFile}` +
813
930
  ` @ ${coreIndicatorsPin.sourceSha}.\n` +
@@ -1014,11 +1131,27 @@ describe("SOT pins carry their provenance", () => {
1014
1131
  // unchanged row, CVC-85 and CVC-145 status promotions) carry no pin delta:
1015
1132
  // the pin captures the NUMBER -> NAMES map, not the status column.
1016
1133
  // coreIndicators advanced to 84a1b67 in 0.8.14 (+5 upstream mints, 0
1017
- // withdrawn) and to 622410b in this refresh (+1: `active_protective_order`,
1134
+ // withdrawn) and to 622410b in the next refresh (+1: `active_protective_order`,
1018
1135
  // minted upstream 2026-08-08, `code_status: canonical`, plus the projected-
1019
- // field revisions on 136-007 / 136-094); scoringEmits is unchanged,
1020
- // so the 2 SCORING_AHEAD_OF_CATALOG codes remain ahead of the catalog
1021
- // exactly as before.
1136
+ // field revisions on 136-007 / 136-094); scoringEmits was unchanged there,
1137
+ // so the 2 SCORING_AHEAD_OF_CATALOG codes remained ahead of the catalog.
1138
+ //
1139
+ // 2026-10-06 — coreIndicators 622410b -> c53378f (214 -> 220: +6 upstream
1140
+ // mints `disclosed_fear_at_intake`, `does_not_control_housing`,
1141
+ // `oppressive_home_life`, `recent_separation`, `survival_sex`,
1142
+ // `unable_to_speak_freely`; 0 withdrawn; plus 1 projected-field revision,
1143
+ // the `exploitative_pricing_tier_low` (136-061) definition). scoringEmits
1144
+ // 9b5d654 -> 9c209cf (169 -> 174: +8 emitted / -3). The -3 includes both
1145
+ // SCORING_AHEAD_OF_CATALOG codes (`coercive_debt_pressure_youth`,
1146
+ // `debt_terms_deceptive_youth`): scoring now emits only the canonical
1147
+ // `coercive_debt_pressure` / `debt_terms_deceptive`, whose upstream rows
1148
+ // carry the `_youth` names as `legacy_aliases`, and the catalog never
1149
+ // adopted the `_youth` codes. They leave the allowlist (now EMPTY) but are
1150
+ // NOT withdrawn: PAVE 2.0 `develop` still writes both from the IDA, so
1151
+ // they become DEPRECATED rows (`CVC136_DEPRECATED`) with their canonical
1152
+ // successors — the CVC-69 v1.1.0 shape. The SOT file moves to v1.1.0 in
1153
+ // the same change (non-additive content under a published version trips
1154
+ // the seeder's §9.1.2 guard). cvcIndex stays at 622410b (not refreshed).
1022
1155
  //
1023
1156
  // coreIndicators was WIDENED (not bumped) to carry the projected `fields`
1024
1157
  // that GATE H enforces — same SHA, same 214 codes, more of what the catalog
@@ -1045,10 +1178,10 @@ describe("SOT pins carry their provenance", () => {
1045
1178
  // written next to it. This is the shape every reserved-row authoring should
1046
1179
  // take: bind, do not bump.
1047
1180
  expect(cvcIndexPin.sourceSha).toBe("622410b");
1048
- expect(coreIndicatorsPin.sourceSha).toBe("622410b");
1049
- expect(scoringEmitsPin.sourceSha).toBe("9b5d654");
1181
+ expect(coreIndicatorsPin.sourceSha).toBe("c53378f");
1182
+ expect(scoringEmitsPin.sourceSha).toBe("9c209cf");
1050
1183
  expect(Object.keys(cvcIndexPin.numbers).length, "cvcIndexPin.numbers rows").toBe(86);
1051
- expect(coreIndicatorsPin.codes.length).toBe(214);
1052
- expect(scoringEmitsPin.codes.length).toBe(169);
1184
+ expect(coreIndicatorsPin.codes.length).toBe(220);
1185
+ expect(scoringEmitsPin.codes.length).toBe(174);
1053
1186
  });
1054
1187
  });
@@ -64,14 +64,17 @@ const SOT_SPECS: readonly SotSpec[] = [
64
64
  // additive per Thread Phase-0 SOT Block D) = 15; +2 PROVISIONAL attempt-reason
65
65
  // buckets (`unable_to_provide_service_fit`, `unable_to_provide_access_barrier`)
66
66
  // for the Thread th-epqet.3 7-bucket lifecycle = 17.
67
- { file: "serviceStates.v1.0.0.json", domain: "service_states", expectedCount: 17 },
67
+ { file: "serviceStates.v1.1.0.json", domain: "service_states", expectedCount: 17 },
68
68
  // Spec §8.1 — "Entries: 147" + 4 missingness = 151
69
69
  { file: "serviceCategories.v1.0.0.json", domain: "service_categories", expectedCount: 151 },
70
- // CVC-69 — 4 group parents + 12 role leaves + 4 missingness = 20
70
+ // CVC-69 v1.1.0 (canon re-mirror, ADDITIVE) — 4 group parents + 18 canon
71
+ // roles (13 Level 1 + 5 Level-2 sub-items) + 5 superseded v1.0.0 roles kept
72
+ // read-only (`deprecated`) + 4 missingness = 31. See
73
+ // incident-participation-roles-canon.test.ts for the key-set pin.
71
74
  {
72
- file: "incidentParticipationRoles.v1.0.0.json",
75
+ file: "incidentParticipationRoles.v1.1.0.json",
73
76
  domain: "incident_participation_roles",
74
- expectedCount: 20,
77
+ expectedCount: 31,
75
78
  },
76
79
  // CVC-130 — 6 flat role leaves + 4 missingness = 10
77
80
  {
@@ -231,7 +234,7 @@ const SOT_SPECS: readonly SotSpec[] = [
231
234
  // `trade_vocational` non-degree credential leaf (180-008) + 1 missingness
232
235
  // root + 4 canonical missingness children (includes PNA) = 13.
233
236
  {
234
- file: "highestEducationLevelCompleted.v1.0.0.json",
237
+ file: "highestEducationLevelCompleted.v1.1.0.json",
235
238
  domain: "highest_education_level_completed",
236
239
  expectedCount: 13,
237
240
  },
@@ -372,18 +375,22 @@ const SOT_SPECS: readonly SotSpec[] = [
372
375
  domain: "location_type",
373
376
  expectedCount: 17,
374
377
  },
375
- // CVC-48 — hierarchical referral entity categories = 43.
378
+ // CVC-48 v1.1.0 (canon v1.3 re-mirror, ADDITIVE) — v1.0.0's 43 + 3 canon
379
+ // leaves (Adult Protective Services, School / academic institution, Legal
380
+ // services provider) = 46: 45 of canon's 46 rows + missingness_root. Canon's
381
+ // `02-02-01-00` Hotline is deliberately not carried; see
382
+ // referral-entity-category-canon.test.ts.
376
383
  {
377
- file: "referralEntityCategory.v1.0.0.json",
384
+ file: "referralEntityCategory.v1.1.0.json",
378
385
  domain: "referral_entity_category",
379
- expectedCount: 43,
386
+ expectedCount: 46,
380
387
  },
381
388
  // CVC-171 — 5 L1 type groups + 30 L2 source codes + 1 additive L1
382
389
  // `victim_compensation` group leaf (171-006) + 5 missingness = 41.
383
390
  // Additive orphan leaves: informal_income (171-001-002) under earned_income
384
391
  // and family_friend_support (171-004-003) under transfer_support.
385
392
  {
386
- file: "incomeBenefitsSources.v1.0.0.json",
393
+ file: "incomeBenefitsSources.v1.1.0.json",
387
394
  domain: "income_benefits_sources",
388
395
  expectedCount: 41,
389
396
  },
@@ -426,7 +433,7 @@ const SOT_SPECS: readonly SotSpec[] = [
426
433
  // categories, with cross-CVC context in definitions) + 1 missingness root +
427
434
  // 3 canonical missingness children = 35.
428
435
  {
429
- file: "sourceSubtype.v1.1.0.json",
436
+ file: "sourceSubtype.v1.2.0.json",
430
437
  domain: "source_subtype",
431
438
  expectedCount: 39,
432
439
  },
@@ -464,7 +471,7 @@ const SOT_SPECS: readonly SotSpec[] = [
464
471
  // qa_audit_passed, supervisor_review) + 1 missingness root + 3 canonical
465
472
  // missingness children = 9.
466
473
  {
467
- file: "verificationMethod.v1.0.0.json",
474
+ file: "verificationMethod.v1.1.0.json",
468
475
  domain: "verification_method",
469
476
  expectedCount: 11,
470
477
  },
@@ -656,7 +663,9 @@ const SOT_SPECS: readonly SotSpec[] = [
656
663
  { file: "coreDhState.v1.0.0.json", domain: "dh_state", expectedCount: 9 },
657
664
  // 0.8.14: 214 -> 219 (catalog refresh a596eb9 -> 84a1b67; +5 mints, 0 withdrawn).
658
665
  // 622410b refresh: 219 -> 220 (catalog refresh 84a1b67 -> 622410b; +1 mint, 0 withdrawn).
659
- { file: "coreIndicators.v1.0.0.json", domain: "core_indicators", expectedCount: 220 },
666
+ // c53378f refresh: 220 -> 224 (catalog refresh 622410b -> c53378f; +6 mints, 0 withdrawn
667
+ // upstream; the 2 scoring-ahead `_youth` codes withdrawn — hti-scoring 9c209cf no longer emits them).
668
+ { file: "coreIndicators.v1.1.0.json", domain: "core_indicators", expectedCount: 226 },
660
669
  { file: "riskSeverityBand.v1.0.0.json", domain: "risk_severity_band", expectedCount: 9 },
661
670
  { file: "adminRoles.v1.0.0.json", domain: "admin_roles", expectedCount: 14 },
662
671
  { file: "userRoles.v1.0.0.json", domain: "user_roles", expectedCount: 19 },