@htilabs/platform-common-models 0.8.17 → 0.8.19

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 (41) hide show
  1. package/dist/constants/index.cjs.map +1 -1
  2. package/dist/constants/index.js.map +1 -1
  3. package/dist/cvcs/index.cjs +4346 -21
  4. package/dist/cvcs/index.cjs.map +1 -1
  5. package/dist/cvcs/index.d.cts +6683 -2020
  6. package/dist/cvcs/index.d.ts +6683 -2020
  7. package/dist/cvcs/index.js +4344 -21
  8. package/dist/cvcs/index.js.map +1 -1
  9. package/dist/{index-C0J3f169.d.ts → index-4DiJrn7y.d.ts} +1 -1
  10. package/dist/{index-EPjPjR0z.d.cts → index-qreOzXYS.d.cts} +1 -1
  11. package/dist/index.cjs +4681 -32
  12. package/dist/index.cjs.map +1 -1
  13. package/dist/index.d.cts +350 -18
  14. package/dist/index.d.ts +350 -18
  15. package/dist/index.js +4677 -32
  16. package/dist/index.js.map +1 -1
  17. package/dist/models/index.d.cts +2 -2
  18. package/dist/models/index.d.ts +2 -2
  19. package/dist/schemas/index.cjs.map +1 -1
  20. package/dist/schemas/index.d.cts +25 -25
  21. package/dist/schemas/index.d.ts +25 -25
  22. package/dist/schemas/index.js.map +1 -1
  23. package/package.json +1 -1
  24. package/src/__sot__/README.md +36 -1
  25. package/src/__sot__/coreIndicatorFields.ts +331 -0
  26. package/src/__sot__/coreIndicators.pin.json +1929 -1
  27. package/src/__sot__/cvcIndex.pin.json +8 -4
  28. package/src/__tests__/__snapshots__/cvc-sot.snap +11 -3
  29. package/src/__tests__/cvc-181-182-country-parity.test.ts +163 -0
  30. package/src/__tests__/cvc-drift-gate.test.ts +407 -12
  31. package/src/__tests__/cvc-sot-snapshot.test.ts +31 -3
  32. package/src/__tests__/cvc-structural.test.ts +8 -0
  33. package/src/constants/ic.ts +14 -0
  34. package/src/cvcs/countries.v1.0.0.json +3077 -0
  35. package/src/cvcs/determinationHelperCategories.v1.0.0.json +1166 -0
  36. package/src/cvcs/index.ts +4 -0
  37. package/src/cvcs/personRelationships.v1.0.0.json +67 -2
  38. package/src/cvcs/relationshipConcern.v1.0.0.json +28 -19
  39. package/src/generated/cvc-enums.ts +350 -14
  40. package/dist/{cvcEntry-DaDrEuTa.d.cts → cvcEntry-ctHTp2df.d.cts} +8 -8
  41. package/dist/{cvcEntry-DaDrEuTa.d.ts → cvcEntry-ctHTp2df.d.ts} +8 -8
@@ -24,6 +24,12 @@
24
24
  * - A false "CVC-69 is broken" conclusion, caused by comparing an ENTRY count
25
25
  * against a SELECTABLE count (assertion F).
26
26
  *
27
+ * And then the gate itself had a blind spot, because the coreIndicators pin held
28
+ * only a SET OF CODE NAMES. Two consecutive refreshes each shipped half their
29
+ * delta — 0.8.14 dropped a definition revision, 0.8.17 dropped a label rename
30
+ * plus a deprecation qualifier — and both passed green. Assertion H closes it:
31
+ * the pin now carries what the catalog SAYS about each code, field by field.
32
+ *
27
33
  * Every assertion below maps to a real bug that shipped. This test is HERMETIC:
28
34
  * it reads only the committed pins in `src/__sot__/`, so it runs on every PR with
29
35
  * no cross-repo auth. The pins are refreshed (and upstream drift is detected) by
@@ -40,6 +46,16 @@ import { fileURLToPath } from "node:url";
40
46
 
41
47
  import { describe, it, expect } from "vitest";
42
48
 
49
+ import {
50
+ LEAKED_HEX_ESCAPE,
51
+ NORMALIZATION_EXEMPTIONS,
52
+ PROJECTED_FIELDS,
53
+ normalizeCatalogValue,
54
+ normalizeSotValue,
55
+ projectSotEntry,
56
+ } from "../__sot__/coreIndicatorFields.js";
57
+ import type { ProjectedIndicatorFields } from "../__sot__/coreIndicatorFields.js";
58
+
43
59
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
44
60
  const CVCS_DIR = path.resolve(__dirname, "..", "cvcs");
45
61
  const SOT_DIR = path.resolve(__dirname, "..", "__sot__");
@@ -56,7 +72,7 @@ const cvcIndexPin = JSON.parse(
56
72
  ) as Pin & { numbers: Record<string, string[]> };
57
73
  const coreIndicatorsPin = JSON.parse(
58
74
  readFileSync(path.join(SOT_DIR, "coreIndicators.pin.json"), "utf-8"),
59
- ) as Pin & { codes: string[] };
75
+ ) as Pin & { codes: string[]; fields: Record<string, ProjectedIndicatorFields> };
60
76
  const scoringEmitsPin = JSON.parse(
61
77
  readFileSync(path.join(SOT_DIR, "scoringEmits.pin.json"), "utf-8"),
62
78
  ) as Pin & { codes: string[] };
@@ -130,6 +146,17 @@ const CANONICAL_BINDING: Record<string, { cvc: number; indexName: string }> = {
130
146
  victim_abuse_types: { cvc: 73, indexName: "core victim abuse types cvc" },
131
147
  race_ethnicity: { cvc: 76, indexName: "core_Race:Ethnicity" },
132
148
  share_purpose: { cvc: 84, indexName: "core - share_purpose" },
149
+ // PROMOTED OUT OF INDEX_ABSENT by the 2026-08-02 live refresh. This vocabulary
150
+ // previously existed upstream only as a stray pre-08-01 CSV with no machine
151
+ // codes, so extract_final_cvcs.py emitted no index row and the domain was
152
+ // index-absent here. The refresh published the Notion page with codes minted
153
+ // 2026-08-01 (`current` · `previous` · `never` + UNK · ANON · DNC), which is
154
+ // exactly what src/cvcs/juvenileJusticeInvolvementStatus.v1.0.0.json already
155
+ // ships — so this is a linkage, not an authoring.
156
+ juvenile_justice_involvement_status: {
157
+ cvc: 95,
158
+ indexName: "core - juvenile_justice_involvement_status",
159
+ },
133
160
  homeless_status: { cvc: 96, indexName: "core - homeless_status" },
134
161
  military_branch: { cvc: 120, indexName: "core - military branch" },
135
162
  military_status: { cvc: 121, indexName: "core - military status" },
@@ -171,12 +198,31 @@ const CANONICAL_BINDING: Record<string, { cvc: number; indexName: string }> = {
171
198
  time_scope: { cvc: 174, indexName: "core - time_scope" },
172
199
  enrollment_application_status: { cvc: 175, indexName: "core - enrollment application status" },
173
200
  frequency_cadence: { cvc: 176, indexName: "core - frequency : cadence" },
174
- administering_jurisdiction: { cvc: 177, indexName: "core - administering jurisdiction" },
201
+ // Was `core - administering jurisdiction` (space) until the 2026-08-02 live
202
+ // refresh, which removed that row as a STALE DUPLICATE export and kept the
203
+ // underscore spelling. Both spellings pointed at the same vocabulary and the
204
+ // same number; only the surviving one is a legitimate binding target.
205
+ administering_jurisdiction: { cvc: 177, indexName: "core - administering_jurisdiction" },
175
206
  employment_status: { cvc: 179, indexName: "core - employment status" },
176
207
  highest_education_level_completed: {
177
208
  cvc: 180,
178
209
  indexName: "core - highest education level_completed",
179
210
  },
211
+ // PIN-ROW DISPOSITION, 2026-08-26. CVC-181's row has been in the pin since
212
+ // before the 622410b reconcile, but nothing in this package occupied 181 — it
213
+ // was a RESERVED row: a number CVC_INDEX.md speaks about that platform-common
214
+ // had never authored, in exactly the 93/196 category the pin-provenance block
215
+ // at the foot of this file describes. Authoring `countries.v1.0.0.json` flips
216
+ // it from reserved to OCCUPIED, and that flip is what this line records. The
217
+ // pin JSON itself is unchanged and must stay so — the row already says
218
+ // "core - countries" and the pin is machine-derived (`npm run sot:pins`);
219
+ // hand-editing it is forbidden by src/__sot__/README.md. What changed is our
220
+ // side of the contract, not upstream's, so the deliberate, documented edit is
221
+ // THIS binding rather than a pin bump.
222
+ //
223
+ // Note the pin row is what made this authorable at all: it is why CVC-181 was
224
+ // known to be birth-country's vocabulary and not a free number to squat on.
225
+ countries: { cvc: 181, indexName: "core - countries" },
180
226
  citizenship: { cvc: 182, indexName: "core - citizenship" },
181
227
  location_type: { cvc: 191, indexName: "core - location_type" },
182
228
  living_situation: { cvc: 192, indexName: "core - living situation" },
@@ -237,7 +283,10 @@ const INDEX_ABSENT: Record<string, { cvc: number; reason: string }> = {
237
283
  // other domain claims 67, so it is index-absent rather than a squat. Sourced
238
284
  // from the HMIS data standard via `CVC_67_HMIS_SEX` in `../constants/ic.ts`.
239
285
  hmis_sex: { cvc: 67, reason: "no CVC_INDEX row" },
240
- juvenile_justice_involvement_status: { cvc: 95, reason: "no CVC_INDEX row" },
286
+ // juvenile_justice_involvement_status (95) LEFT this list in the 622410b
287
+ // reconcile — CVC_INDEX.md now carries its row, so it is bound above. This is
288
+ // what the list is FOR: index-absence is a temporary, visible state that gets
289
+ // retired when Notion catches up, not a permanent parking spot.
241
290
  primary_language: { cvc: 122, reason: "no CVC_INDEX row" },
242
291
  hmis_relationship_to_hoh: { cvc: 129, reason: "no CVC_INDEX row" },
243
292
  core_functions: { cvc: 133, reason: "no CVC_INDEX row" },
@@ -253,7 +302,40 @@ const INDEX_ABSENT: Record<string, { cvc: number; reason: string }> = {
253
302
  hmis_project_type: { cvc: 225, reason: "no CVC_INDEX row" },
254
303
  funder: { cvc: 226, reason: "no CVC_INDEX row" },
255
304
  da_incident_severity: { cvc: 228, reason: "no CVC_INDEX row" },
256
- relationship_concern: { cvc: 231, reason: "no CVC_INDEX row" },
305
+ // relationship_concern (231) LEFT this list in the 2026-08-29 renumber — the
306
+ // OTHER way a domain retires from INDEX_ABSENT, and the one that matters.
307
+ // Jevon ratified CVC-231 to the Determination Helper categories on
308
+ // 2026-08-28. This domain had only ever held 231 as a provisional mint taken
309
+ // out of the canonical block, which is exactly why it lived here instead of
310
+ // in CANONICAL_BINDING. Left at 231 it would have become a SQUAT the moment
311
+ // the next cvcIndex pin refresh published the DH row — and per GATE C a squat
312
+ // does not merely mislabel the squatter, it makes the slot look OCCUPIED and
313
+ // hides the absence of the domain that owns it. It is renumbered to the
314
+ // provisional block at CVC-991 (see relationshipConcern.v1.0.0.json
315
+ // `_status.renumber` / `_status.numberChoice`), so `isProvisional()` now
316
+ // exempts it and no entry here is needed. The Determination Helper categories
317
+ // that own 231 are authored directly below — the gap the vacated squat had
318
+ // been hiding, closed in the same branch that vacated it.
319
+ //
320
+ // CVC-231's rightful owner, authored 2026-08-30. This is the SECOND half of the
321
+ // renumber above and the whole point of GATE C: vacating the squat exposed an
322
+ // unauthored canonical vocabulary, and the exposure is only worth anything if
323
+ // the vocabulary then gets authored. `CVC_INDEX.md` @ 622410b has no row for it
324
+ // (grep confirms: the only `determination`-prefixed rows are CVC-138
325
+ // `core - determination_level` and CVC-233 `core-DH_state`), so this is the
326
+ // `core_information_scope` disposition — numbered from the domain's own
327
+ // canonical self-declaration plus a codebook-owner ruling, index-absent until
328
+ // the extractor catches up — and NOT the CVC-181 one, which had a reserved pin
329
+ // row to bind against. NO PIN EDIT: `cvcIndex.pin.json` is machine-derived and
330
+ // `src/__sot__/README.md` forbids hand-editing it; the row arrives on its own
331
+ // refresh cycle and this domain is promoted into CANONICAL_BINDING then.
332
+ determination_helper_categories: {
333
+ cvc: 231,
334
+ reason:
335
+ "no CVC_INDEX row; number self-declared by the canonical " +
336
+ "data/cvcs/core_determination_helper_categories.yaml and ratified to this " +
337
+ "vocabulary by Jevon on 2026-08-28",
338
+ },
257
339
  };
258
340
 
259
341
  /**
@@ -589,6 +671,267 @@ describe("GATE G — code and key format", () => {
589
671
  }
590
672
  });
591
673
 
674
+ // ═══════════════════════════════════════════════════════════════════════════
675
+ // H. FIELD FIDELITY — the pin-field-blindness catcher
676
+ // ═══════════════════════════════════════════════════════════════════════════
677
+ /**
678
+ * GATES A and B compare SETS OF CODE NAMES. That is all the pin used to carry,
679
+ * and it is why two consecutive refreshes each shipped half a delta:
680
+ *
681
+ * 0.8.14 — the code delta landed; a DEFINITION REVISION that came with it
682
+ * did not. Green.
683
+ * 0.8.17 — the code delta landed; a LABEL RENAME and a load-bearing
684
+ * DEPRECATION QUALIFIER in a definition did not. Green. Caught by a
685
+ * human reading the diff, which is not a gate.
686
+ *
687
+ * A code can keep its name while everything the catalog SAYS about it is
688
+ * rewritten. `coreIndicators.pin.json` now carries the seven projected fields
689
+ * verbatim (`src/__sot__/coreIndicatorFields.ts`), and this gate asserts
690
+ * CVC-136 restates every one of them faithfully — entry by entry, field by
691
+ * field, naming the code, the field, the catalog value and the shipped value on
692
+ * failure.
693
+ *
694
+ * Normalization is the enumerated exemption list in `coreIndicatorFields.ts`,
695
+ * and H4 below PROVES each exemption is still load-bearing rather than letting
696
+ * it rot into a blanket fuzzy match.
697
+ */
698
+ describe("GATE H — CVC-136 restates every field the catalog states", () => {
699
+ const shipped = new Map<string, ProjectedIndicatorFields>(
700
+ substantiveOf(cvc136).map((e) => [
701
+ e.key,
702
+ projectSotEntry(e as unknown as Record<string, unknown>),
703
+ ]),
704
+ );
705
+ // Defaulted, NOT asserted here, on purpose. A pin regenerated by a
706
+ // pre-field-aware sot-pins.ts has no `fields` at all; reading `Object.keys`
707
+ // off `undefined` throws at COLLECTION time, which collapses the whole file
708
+ // to 0 tests and reports as an import error rather than as the named H1
709
+ // failure that says what to do. Default to empty, then fail loudly in H1.
710
+ const pinFields: Record<string, ProjectedIndicatorFields> = coreIndicatorsPin.fields ?? {};
711
+ const pinnedCodes = Object.keys(pinFields);
712
+
713
+ it("the pin carries projected fields for every pinned code", () => {
714
+ // A pin regenerated by a pre-field-aware sot-pins.ts would be silently
715
+ // field-blind — the exact failure mode this gate exists to end. Refuse it.
716
+ expect(
717
+ Object.keys(pinFields).length,
718
+ "the pin carries no fields — regenerate with npm run sot:pins",
719
+ ).toBeGreaterThan(0);
720
+ expect(pinnedCodes.sort()).toEqual([...coreIndicatorsPin.codes].sort());
721
+ for (const code of pinnedCodes) {
722
+ const fields = pinFields[code]!;
723
+ for (const field of PROJECTED_FIELDS) {
724
+ expect(fields, `${code} is missing projected field "${field}"`).toHaveProperty(field);
725
+ }
726
+ }
727
+ });
728
+
729
+ it("every pinned catalog code is present in CVC-136 (the join is total)", () => {
730
+ // Without this, a code dropped from CVC-136 would make the field comparison
731
+ // below silently SKIP it rather than fail — a gate with a hole in it.
732
+ const absent = pinnedCodes.filter((c) => !shipped.has(c)).sort();
733
+ if (absent.length > 0) {
734
+ throw new Error(
735
+ `${absent.length} code(s) in ${coreIndicatorsPin.sourceFile} ` +
736
+ `@ ${coreIndicatorsPin.sourceSha} are NOT in CVC-136:\n` +
737
+ ` ${absent.join(", ")}\n\n` +
738
+ "GATE B only checks the other direction (CVC-136 invents nothing), so a\n" +
739
+ " catalog code dropped on refresh would otherwise pass unnoticed.\n" +
740
+ "TO FIX: add each to src/cvcs/coreIndicators.v1.0.0.json.",
741
+ );
742
+ }
743
+ expect(absent).toEqual([]);
744
+ });
745
+
746
+ it(`all ${PROJECTED_FIELDS.length} projected fields match, code by code`, () => {
747
+ const mismatches: string[] = [];
748
+
749
+ for (const code of pinnedCodes) {
750
+ const catalog = pinFields[code]!;
751
+ const sot = shipped.get(code);
752
+ if (!sot) continue; // already reported by the join-is-total assertion above
753
+
754
+ for (const field of PROJECTED_FIELDS) {
755
+ // ASYMMETRIC BY DESIGN. E4's `\xNN` decode runs on the CATALOG side
756
+ // only, because CVC-136 is obliged to carry the real character rather
757
+ // than mirror the upstream escape. Decoding both sides would let a
758
+ // shipped literal `fianc\xE9(e)` compare equal and pass. E1/E2/E3/E5
759
+ // are symmetric. See NORMALIZATION_EXEMPTIONS.
760
+ const want = normalizeCatalogValue(field, catalog[field]);
761
+ const got = normalizeSotValue(field, sot[field]);
762
+ if (want === got) continue;
763
+ mismatches.push(
764
+ ` ${code} . ${field}\n` +
765
+ ` catalog: ${want === null ? "(absent)" : JSON.stringify(want)}\n` +
766
+ ` CVC-136: ${got === null ? "(absent)" : JSON.stringify(got)}`,
767
+ );
768
+ }
769
+ }
770
+
771
+ if (mismatches.length > 0) {
772
+ throw new Error(
773
+ `${mismatches.length} field(s) of CVC-136 disagree with the canonical catalog.\n` +
774
+ "The CODE SET is right and the CONTENT is stale — which is precisely what a\n" +
775
+ "code-set-only pin could never see (0.8.14 dropped a definition revision;\n" +
776
+ "0.8.17 dropped a label rename plus a deprecation qualifier).\n\n" +
777
+ `${mismatches.join("\n")}\n\n` +
778
+ "TO FIX: copy the `catalog:` value printed above into the matching entry\n" +
779
+ " of src/cvcs/coreIndicators.v1.0.0.json.\n" +
780
+ " COPY THE PRINTED VALUE, not the raw scalar out of\n" +
781
+ ` ${coreIndicatorsPin.sourceRepo}/${coreIndicatorsPin.sourceFile}` +
782
+ ` @ ${coreIndicatorsPin.sourceSha}.\n` +
783
+ " The printed value is NORMALIZED — wrap points folded, and any leaked\n" +
784
+ " `\\xNN` escape already decoded to the real character. Transcribing the\n" +
785
+ " raw YAML by hand reproduces the escape verbatim (`fianc\\xE9(e)`), which\n" +
786
+ " CVC-136 must NOT carry: the restatement's job is to fix that upstream\n" +
787
+ " defect, and a separate assertion below rejects a shipped `\\xNN`.\n" +
788
+ " Field names differ by design: the catalog's `label` is the envelope's\n" +
789
+ " `title`; `is_alert`/`alert_when` are `isAlert`/`alertWhen`. Then\n" +
790
+ " regenerate CVC_136_CORE_INDICATOR_VALUES in src/constants/ic.ts if the\n" +
791
+ " change touches a name.\n" +
792
+ " If instead the CATALOG moved, run `npm run sot:pins` and restate both.",
793
+ );
794
+ }
795
+ expect(mismatches).toEqual([]);
796
+ });
797
+
798
+ /**
799
+ * BELT AND BRACES FOR E4.
800
+ *
801
+ * The comparison above is already asymmetric, so a shipped `fianc\xE9(e)` now
802
+ * fails it. This asserts the same thing directly, without reference to the
803
+ * catalog, because it is the cheaper and more legible failure: it names E4 and
804
+ * says what a correct restatement looks like, rather than printing two long
805
+ * definitions that differ somewhere in the middle.
806
+ *
807
+ * It also holds if the catalog is ever cleaned up upstream and E4 is deleted:
808
+ * CVC-136 must never carry a Python-style hex escape regardless of why.
809
+ */
810
+ it("no shipped CVC-136 value carries a leaked `\\xNN` escape", () => {
811
+ const offenders: string[] = [];
812
+ for (const [code, fields] of shipped) {
813
+ for (const field of PROJECTED_FIELDS) {
814
+ const value = fields[field];
815
+ if (value !== null && LEAKED_HEX_ESCAPE.test(value)) {
816
+ offenders.push(` ${code} . ${field}: ${JSON.stringify(value)}`);
817
+ }
818
+ }
819
+ }
820
+ expect(
821
+ offenders,
822
+ "These CVC-136 values contain a literal `\\xNN` escape (E4-leaked-hex-escape).\n" +
823
+ "One upstream catalog scalar is authored single-quoted with Python-style\n" +
824
+ "escapes, so `fianc\\xE9` parses as six literal characters. CVC-136's job is to\n" +
825
+ "restate the REAL character (`fiancé`) — copying the raw YAML through\n" +
826
+ "mechanically carries the defect into the shipped codebook.\n" +
827
+ "TO FIX: replace each escape with the character it denotes.\n" +
828
+ `${offenders.join("\n")}`,
829
+ ).toEqual([]);
830
+ });
831
+
832
+ /**
833
+ * H4 — THE EXEMPTIONS ARE PROVEN, NOT ASSUMED.
834
+ *
835
+ * A normalization exemption is a hole in the gate. Each one below is asserted
836
+ * to be (a) still physically present — its `detect` predicate still fires on
837
+ * the raw catalog value — (b) still exercised — a RAW comparison of the fields
838
+ * it covers genuinely fails — and (c) sufficient — the normalized comparison
839
+ * of those fields passes. An exemption that stops being needed fails here and
840
+ * gets deleted, instead of silently widening the gate's blind spot forever.
841
+ *
842
+ * SCOPING, and why both (a) and (b) are needed.
843
+ *
844
+ * The self-tests used to span all seven PROJECTED_FIELDS, so an exemption
845
+ * could look alive on the strength of a DIFFERENT exemption's artifact in a
846
+ * different field. Narrowing to `exemption.fields` fixes most of that — but
847
+ * not all of it, because in the pinned catalog every prose artifact lives in
848
+ * `definition`, and E2 and E4 share BOTH a code and that field. Field scoping
849
+ * alone would still let a dead E4 ride on E2's wrap point.
850
+ *
851
+ * `detect` is what closes it: it asks whether the raw catalog value still
852
+ * contains THIS exemption's artifact — a trailing newline, an interior wrap,
853
+ * a wrapped hyphen, a `\xNN` escape, an empty string — independently of
854
+ * whether some other exemption also fires on the same value.
855
+ */
856
+ describe("the normalization exemptions are each still load-bearing", () => {
857
+ for (const exemption of NORMALIZATION_EXEMPTIONS) {
858
+ it(`${exemption.id} is exercised by ${exemption.codes.join(", ")}`, () => {
859
+ for (const code of exemption.codes) {
860
+ const catalog = pinFields[code];
861
+ const sot = shipped.get(code);
862
+ expect(catalog, `${exemption.id}: ${code} is no longer in the pin`).toBeDefined();
863
+ expect(sot, `${exemption.id}: ${code} is no longer in CVC-136`).toBeDefined();
864
+
865
+ // Scoped to the fields THIS exemption claims to cover.
866
+ const fields = exemption.fields;
867
+
868
+ const detected = fields.some((f) => {
869
+ const raw = catalog![f];
870
+ return raw !== null && exemption.detect(raw);
871
+ });
872
+ const rawDiffers = fields.some((f) => catalog![f] !== sot![f]);
873
+ const normalizedMatches = fields.every(
874
+ (f) => normalizeCatalogValue(f, catalog![f]) === normalizeSotValue(f, sot![f]),
875
+ );
876
+
877
+ expect(
878
+ detected,
879
+ `${exemption.id}: the artifact is GONE from ${code}.${fields.join("/")} — ` +
880
+ "the raw catalog value no longer contains it, so this exemption is dead. " +
881
+ "Delete it from NORMALIZATION_EXEMPTIONS in src/__sot__/coreIndicatorFields.ts " +
882
+ "rather than leaving an unused hole in the gate. (Checked separately from " +
883
+ "the raw-differs assertion below because two exemptions can overlap on one " +
884
+ "code and field — E2 and E4 do — and then a raw difference proves nothing " +
885
+ "about which of them is still needed.)",
886
+ ).toBe(true);
887
+ expect(
888
+ rawDiffers,
889
+ `${exemption.id}: ${code}.${fields.join("/")} now matches VERBATIM — this ` +
890
+ "exemption is dead. Delete it from NORMALIZATION_EXEMPTIONS in " +
891
+ "src/__sot__/coreIndicatorFields.ts rather than leaving an unused hole " +
892
+ "in the gate.",
893
+ ).toBe(true);
894
+ expect(
895
+ normalizedMatches,
896
+ `${exemption.id}: ${code}.${fields.join("/")} still differs AFTER ` +
897
+ "normalization — the exemption no longer covers what it claims to. " +
898
+ "Read the GATE H failure above.",
899
+ ).toBe(true);
900
+ }
901
+ });
902
+ }
903
+
904
+ it("every round-trip artifact in the catalog is an enumerated one", () => {
905
+ // Guard the escape hatch the way GATE B guards SCORING_AHEAD_OF_CATALOG:
906
+ // the list must stay a documented enumeration, not a dumping ground.
907
+ //
908
+ // Scoped to codes whose raw fields differ but whose NORMALIZED fields
909
+ // agree — that is the definition of a round-trip artifact. Codes that
910
+ // differ after normalization are real drift and belong to the GATE H
911
+ // failure above; reporting them here too would just double the noise.
912
+ const named = new Set<string>(NORMALIZATION_EXEMPTIONS.flatMap((e) => [...e.codes]));
913
+ const artifacts = pinnedCodes.filter((code) => {
914
+ const catalog = pinFields[code]!;
915
+ const sot = shipped.get(code);
916
+ if (!sot) return false;
917
+ const rawDiffers = PROJECTED_FIELDS.some((f) => catalog[f] !== sot[f]);
918
+ const normalizedMatches = PROJECTED_FIELDS.every(
919
+ (f) => normalizeCatalogValue(f, catalog[f]) === normalizeSotValue(f, sot[f]),
920
+ );
921
+ return rawDiffers && normalizedMatches;
922
+ });
923
+ const undocumented = artifacts.filter((c) => !named.has(c)).sort();
924
+ expect(
925
+ undocumented,
926
+ "These codes are absorbed by normalization but named by no exemption. Each is a " +
927
+ "NEW round-trip artifact: read it, confirm it is formatting and not content, then " +
928
+ "document it in NORMALIZATION_EXEMPTIONS in src/__sot__/coreIndicatorFields.ts. " +
929
+ "An undocumented one is a hole nobody has looked through.",
930
+ ).toEqual([]);
931
+ });
932
+ });
933
+ });
934
+
592
935
  // ═══════════════════════════════════════════════════════════════════════════
593
936
  // Pin provenance — the pins must say where they came from.
594
937
  // ═══════════════════════════════════════════════════════════════════════════
@@ -606,22 +949,74 @@ describe("SOT pins carry their provenance", () => {
606
949
  });
607
950
 
608
951
  it("the pinned SOT is the one this release was authored against", () => {
609
- // cvcIndex stays at a596eb9 — deliberately NOT bumped here. CVC_INDEX.md
610
- // HAS moved upstream (2026-08-02 targeted live refresh: CVC-93/95/159/177/196
611
- // rows), but absorbing it means reconciling INDEX_ABSENT for
612
- // juvenile_justice_involvement_status (95) and the child-welfare rows (93/196),
613
- // which is its own reconcile — a pin bump without conformance is exactly the
614
- // lie sot-pins.ts warns about. Tracked separately; `sot:pins:check` will keep
615
- // reporting cvcIndex drift until it lands.
952
+ // cvcIndex advanced a596eb9 -> 622410b (the 2026-08-02 targeted live-Notion
953
+ // refresh of the legal-history arc tails), WITH the conformance it implies —
954
+ // the reconcile the previous release deferred rather than fake. Four row
955
+ // deltas, and what each one actually required:
956
+ //
957
+ // CVC-177 ["core - administering jurisdiction", -> ["core - administering_jurisdiction"]
958
+ // "core - administering_jurisdiction"]
959
+ // The space-named row was a STALE DUPLICATE export and was
960
+ // removed. NOT bookkeeping: CANONICAL_BINDING was bound to the
961
+ // spelling that no longer exists, so the bump alone would have
962
+ // failed GATE C. The binding now names the surviving row.
963
+ //
964
+ // CVC-95 null -> ["core - juvenile_justice_involvement_status"]
965
+ // The domain was already authored and already correct; it sat in
966
+ // INDEX_ABSENT only because no index row existed to bind it to.
967
+ // Now bound. Left in INDEX_ABSENT it would have read as a SQUAT,
968
+ // because a number the index speaks about constrains whoever
969
+ // occupies it. Linkage only — nothing authored.
970
+ //
971
+ // CVC-93 null -> ["core - child_welfare_involvement_status"]
972
+ // CVC-196 ["core child welfare cvc", -> ["core - child_welfare_episode_type"]
973
+ // "core child welfare episode type CVC"]
974
+ // Bookkeeping. platform-common ships NO domain at 93 or 196, so
975
+ // no gate constrains them and nothing here had to change. They
976
+ // are now KNOWN-OCCUPIED numbers, which is the point: authoring
977
+ // either later must land on its own number, and a future domain
978
+ // drifting onto 93/196 is now a detectable squat rather than a
979
+ // silent one. Authoring the vocabularies themselves is clinical
980
+ // content (Crysta-owned) and is deliberately not done here.
981
+ //
982
+ // The three index-name/status-only churns in the same refresh (CVC-159
983
+ // unchanged row, CVC-85 and CVC-145 status promotions) carry no pin delta:
984
+ // the pin captures the NUMBER -> NAMES map, not the status column.
616
985
  // coreIndicators advanced to 84a1b67 in 0.8.14 (+5 upstream mints, 0
617
986
  // withdrawn) and to 622410b in this refresh (+1: `active_protective_order`,
618
987
  // minted upstream 2026-08-08, `code_status: canonical`, plus the projected-
619
988
  // field revisions on 136-007 / 136-094); scoringEmits is unchanged,
620
989
  // so the 2 SCORING_AHEAD_OF_CATALOG codes remain ahead of the catalog
621
990
  // exactly as before.
622
- expect(cvcIndexPin.sourceSha).toBe("a596eb9");
991
+ //
992
+ // coreIndicators was WIDENED (not bumped) to carry the projected `fields`
993
+ // that GATE H enforces — same SHA, same 214 codes, more of what the catalog
994
+ // says about each. The two refreshes that dropped their field delta are why.
995
+ //
996
+ // 622410b's CVC_INDEX.md is a HAND-REFRESHED live-Notion state that upstream
997
+ // marks NON-REPRODUCIBLE by `tools/extract_final_cvcs.py`: its banner says
998
+ // "Do NOT re-run tools/extract_final_cvcs.py until the next full Notion
999
+ // re-export lands — it would clobber the refreshed extracts and resurrect
1000
+ // index rows from the stale zips" — i.e. a premature re-run brings the
1001
+ // space-named CVC-177 duplicate back and takes CVC-95's row away again.
1002
+ // GATE C fails loudly on the CVC-95 half (a bound domain sits on it); the
1003
+ // 93/196 half is invisible to every gate, since GATE C only iterates bound
1004
+ // domains and occupied numbers and platform-common ships neither. The row
1005
+ // count below is what makes that half detectable at all — a regenerated pin
1006
+ // that silently drops those deliberately-recorded rows fails here.
1007
+ //
1008
+ // 2026-08-26 — CVC-181 `core - countries` was authored, and its pin row went
1009
+ // from RESERVED (a row the index speaks about that nothing occupied — the
1010
+ // 93/196 category above) to OCCUPIED. NO PIN DELTA: the row already read
1011
+ // ["core - countries"] and upstream did not move, so the pin stays at
1012
+ // 622410b and stays machine-derived. The change is on OUR side of the
1013
+ // contract and is recorded as a CANONICAL_BINDING entry with its disposition
1014
+ // written next to it. This is the shape every reserved-row authoring should
1015
+ // take: bind, do not bump.
1016
+ expect(cvcIndexPin.sourceSha).toBe("622410b");
623
1017
  expect(coreIndicatorsPin.sourceSha).toBe("622410b");
624
1018
  expect(scoringEmitsPin.sourceSha).toBe("9b5d654");
1019
+ expect(Object.keys(cvcIndexPin.numbers).length, "cvcIndexPin.numbers rows").toBe(86);
625
1020
  expect(coreIndicatorsPin.codes.length).toBe(214);
626
1021
  expect(scoringEmitsPin.codes.length).toBe(169);
627
1022
  });
@@ -338,11 +338,17 @@ const SOT_SPECS: readonly SotSpec[] = [
338
338
  // L0 missingness (anonymous, data_not_collected; Notion codebook explicitly
339
339
  // omits `unknown` at L0 — the L2 `relationship_unknown` code carries that
340
340
  // semantic instead; no PNA) + 8 L1 topics + 35 L2 canonical relationship
341
- // types + 40 L3 directional role labels + 3 L3 pet-branch roles = 89.
341
+ // types + 40 L3 directional role labels + 3 L3 pet-branch roles = 89,
342
+ // + 3 L2 LOCAL EXTENSIONS (`parental_figure_dependent`,
343
+ // `intimate_romantic_partner`, `intimate_partner_prior`) + 2 L3 directional
344
+ // roles under `parental_figure_dependent` = 94. All 5 are flagged
345
+ // `localExtension: true`; the canonical picker (prototype@622410b
346
+ // REL_CATEGORIES) offers them and the Notion-side export does not yet carry
347
+ // them. See the file's `_status.localExtension`.
342
348
  {
343
349
  file: "personRelationships.v1.0.0.json",
344
350
  domain: "person_relationships",
345
- expectedCount: 89,
351
+ expectedCount: 94,
346
352
  },
347
353
  // CVC-179 — employment_status: 1 missingness_root + 5 HMIS missingness
348
354
  // (unknown, anonymous, data_not_collected, client_doesnt_know,
@@ -574,9 +580,13 @@ const SOT_SPECS: readonly SotSpec[] = [
574
580
  // `none` = negative determination, canonical per Crysta directive 2026-05-27)
575
581
  // + 1 missingness root + 3 canonical missingness children = 8.
576
582
  { file: "htType.v1.0.0.json", domain: "ht_type", expectedCount: 8 },
577
- // PROVISIONAL CVC-231 relationship_concern — 7 TRA relationship-concern
583
+ // PROVISIONAL CVC-991 relationship_concern — 7 TRA relationship-concern
578
584
  // codes + 1 missingness root + 3 canonical missingness children = 11.
579
585
  // CVC number is PROVISIONAL pending codebook-session ratification.
586
+ // RENUMBERED 231 -> 991 on 2026-08-29: CVC-231 was ratified to the
587
+ // Determination Helper categories (Jevon, 2026-08-28), so the provisional
588
+ // mint this domain held out of the canonical block vacates to the 900-block.
589
+ // Count is unchanged — the renumber is a pure segment-1 prefix substitution.
580
590
  { file: "relationshipConcern.v1.0.0.json", domain: "relationship_concern", expectedCount: 11 },
581
591
  // CVC-137 recency_band — the CANONICAL 8-band key system adopted in 0.8.13
582
592
  // (w3m, m3_6, m6_12, y1p, y1_3, y3_10, y10p, ylt3 — the lowercase
@@ -655,6 +665,24 @@ const SOT_SPECS: readonly SotSpec[] = [
655
665
  // missingness root + 3 canonical missingness children (Unknown / Declined to
656
666
  // asnwer / Not collected, carried verbatim from the codebook) = 253.
657
667
  { file: "citizenship.v1.0.0.json", domain: "citizenship", expectedCount: 253 },
668
+ // CVC-181 — the SAME 249 countries (identical keys + ISO codes; asserted by
669
+ // cvc-181-182-country-parity.test.ts) + 1 missingness root + 3 workspace-
670
+ // standard missingness children (this codebook carries none of its own) + the
671
+ // 1 authored `non_us_unspecified` local extension = 254. The +1 over CVC-182
672
+ // is that local extension, and nothing else.
673
+ { file: "countries.v1.0.0.json", domain: "countries", expectedCount: 254 },
674
+ // CVC-231 — the Determination Helper category taxonomy: 53 canonical rows
675
+ // across the four sections (§ I Subject and Scope 5 · § II Activity 20 ·
676
+ // § III Means 24 · § IV Status 4) + 1 missingness root + 3 workspace-standard
677
+ // missingness children (this codebook carries none of its own) = 57. ALL 53 are
678
+ // selectable, including the 10 non-leaf rows — the canonical
679
+ // feeds_dh_subdomain_crossref addresses parent rows directly, so a
680
+ // category/leaf split would orphan those references.
681
+ {
682
+ file: "determinationHelperCategories.v1.0.0.json",
683
+ domain: "determination_helper_categories",
684
+ expectedCount: 57,
685
+ },
658
686
  // CVC-235 — 4 L1 trafficking-relevant roles + 1 missingness root + 3 canonical
659
687
  // missingness children = 8.
660
688
  {
@@ -206,6 +206,14 @@ const SOT_FILES: readonly SotFile[] = [
206
206
  { file: "whyNots.v1.0.0.json", expectedDomain: "why_nots" },
207
207
  // ─── 0.8.13 held-item resolutions (Job A) ───
208
208
  { file: "citizenship.v1.0.0.json", expectedDomain: "citizenship" },
209
+ // CVC-181 — the country list CVC-182 shares. Authored 2026-08-26.
210
+ { file: "countries.v1.0.0.json", expectedDomain: "countries" },
211
+ // CVC-231 — the Determination Helper category taxonomy. Authored 2026-08-30,
212
+ // on the number Jevon ratified to it on 2026-08-28.
213
+ {
214
+ file: "determinationHelperCategories.v1.0.0.json",
215
+ expectedDomain: "determination_helper_categories",
216
+ },
209
217
  { file: "traffickingRelevantRole.v1.0.0.json", expectedDomain: "trafficking_relevant_role" },
210
218
  // ─── Domains the hand-maintained list previously OMITTED (found by the
211
219
  // CVC drift gate, which scans the directory instead of a list). ───
@@ -2632,6 +2632,20 @@ export const CVC_122_LABELS: Record<CVC122Value, string> = {
2632
2632
 
2633
2633
  // ─── CVC-181: Countries (ISO 3166-1 alpha-2) ────────────────────────
2634
2634
  // Full list of countries using ISO 3166-1 alpha-2 codes.
2635
+ //
2636
+ // AS OF 2026-08-26 THE SOT IS `src/cvcs/countries.v1.0.0.json`, authored from the
2637
+ // canonical `core - countries — codebook 2.csv`. These two constants predate it and
2638
+ // are RETAINED for existing consumers; new code should import `CountryKeys` from
2639
+ // `src/generated/cvc-enums.ts` (or `countriesSot`) instead.
2640
+ //
2641
+ // The ISO SET here is exact — all 249 codes, no additions, no omissions, verified
2642
+ // against the codebook. `CVC_181_LABELS`, however, carries SHORT-FORM display labels
2643
+ // that differ from the canonical label on 16 codes: BO, CD, IR, KP, KR, LA, MK, FM,
2644
+ // MD, PS, SH, SY, TW, TZ, VE, VN ("Vietnam" vs "Viet Nam", "Korea, South" vs "Korea,
2645
+ // Republic of", …). The SOT JSON carries the canonical spelling verbatim in both
2646
+ // `title` and `canonicalLabel`. That divergence is display-only — nothing keys off
2647
+ // these strings — but it is real, and collapsing the two surfaces onto one label set
2648
+ // is its own decision (a visible UI change), deliberately not made here.
2635
2649
 
2636
2650
  export const CVC_181_COUNTRIES = {
2637
2651
  US: "US",