@htilabs/platform-common-models 0.20.0 → 0.21.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 (53) hide show
  1. package/dist/cvcs/index.cjs +222 -120
  2. package/dist/cvcs/index.cjs.map +1 -1
  3. package/dist/cvcs/index.d.cts +223 -117
  4. package/dist/cvcs/index.d.ts +223 -117
  5. package/dist/cvcs/index.js +222 -120
  6. package/dist/cvcs/index.js.map +1 -1
  7. package/dist/enums/index.cjs.map +1 -1
  8. package/dist/enums/index.d.cts +4 -4
  9. package/dist/enums/index.d.ts +4 -4
  10. package/dist/enums/index.js.map +1 -1
  11. package/dist/{index-I-DiX9eQ.d.ts → index-CDoqrfc1.d.ts} +1 -1
  12. package/dist/{index-CoVr1jIV.d.cts → index-Zu_mOJRn.d.cts} +1 -1
  13. package/dist/index.cjs +320 -137
  14. package/dist/index.cjs.map +1 -1
  15. package/dist/index.d.cts +3 -3
  16. package/dist/index.d.ts +3 -3
  17. package/dist/index.js +319 -137
  18. package/dist/index.js.map +1 -1
  19. package/dist/information-scope/index.cjs +98 -17
  20. package/dist/information-scope/index.cjs.map +1 -1
  21. package/dist/information-scope/index.d.cts +142 -13
  22. package/dist/information-scope/index.d.ts +142 -13
  23. package/dist/information-scope/index.js +97 -17
  24. package/dist/information-scope/index.js.map +1 -1
  25. package/dist/models/index.d.cts +2 -2
  26. package/dist/models/index.d.ts +2 -2
  27. package/dist/schemas/index.d.cts +25 -25
  28. package/dist/schemas/index.d.ts +25 -25
  29. package/dist/services/index.cjs +98 -17
  30. package/dist/services/index.cjs.map +1 -1
  31. package/dist/services/index.d.cts +1 -1
  32. package/dist/services/index.d.ts +1 -1
  33. package/dist/services/index.js +97 -17
  34. package/dist/services/index.js.map +1 -1
  35. package/package.json +1 -1
  36. package/src/__tests__/__snapshots__/cvc-sot.snap +2 -2
  37. package/src/__tests__/core-information-scope-invariant.test.ts +141 -15
  38. package/src/__tests__/cvc-sot-snapshot.test.ts +4 -3
  39. package/src/__tests__/cvc-structural.test.ts +2 -2
  40. package/src/__tests__/location-type-routing-invariant.test.ts +1 -1
  41. package/src/cvcs/{coreInformationScope.v2.0.0.json → coreInformationScope.v2.1.0.json} +190 -88
  42. package/src/cvcs/index.ts +2 -2
  43. package/src/cvcs/{roiScope.v1.3.0.json → roiScope.v1.4.0.json} +26 -26
  44. package/src/generated/cvc-enums.ts +4 -4
  45. package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v3_placements.projection.csv +12 -0
  46. package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v4.migrations.csv +27 -27
  47. package/src/services/__tests__/fixtures/infoscope-v4/information_scope_v4.rows.csv +1 -1
  48. package/src/services/__tests__/fixtures/infoscope-v4/loadInfoscopeV4Fixtures.ts +85 -14
  49. package/src/services/__tests__/informationScopeResolver.test.ts +336 -22
  50. package/src/services/informationScopeResolver.ts +226 -19
  51. package/src/services/informationScopeSot.ts +50 -8
  52. package/dist/{cvcEntry-BCj1OWqL.d.cts → cvcEntry-0BIB9sen.d.cts} +8 -8
  53. package/dist/{cvcEntry-BCj1OWqL.d.ts → cvcEntry-0BIB9sen.d.ts} +8 -8
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@htilabs/platform-common-models",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
4
4
  "description": "Shared constants, types, and models for HTI Labs applications",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -584,7 +584,7 @@
584
584
  },
585
585
  "roi_scope": {
586
586
  "count": 31,
587
- "hash": "e3154d8e0e332324dc36f58f542fda07d7e028b68aafba6eca8a0743f7330a02"
587
+ "hash": "85061fbf2e71364a82308fa11c2aa2e87d27dfb61804568480b2f027a6e23df6"
588
588
  },
589
589
  "roi_status": {
590
590
  "count": 9,
@@ -704,7 +704,7 @@
704
704
  },
705
705
  "core_information_scope": {
706
706
  "count": 146,
707
- "hash": "98f2ba7146b986b66f6ebdf66acfc34fc0da21cc787055fb58de070d5cc5f5bb"
707
+ "hash": "598ef5e2b8562fc87bdf7de50fc9fb547cae03535e633f1efef7acc54d55ad32"
708
708
  }
709
709
  }
710
710
  }
@@ -2,7 +2,8 @@
2
2
  * CORE INFORMATION SCOPE (CVC-236) — the v4 tree and the invariants adoption depends on
3
3
  * =====================================================================================
4
4
  *
5
- * SOT v2.0.0 absorbs the canonical CVC-236 v4 tree (prototype
5
+ * SOT v2.0.0 (amended by v2.1.0: Crysta's release-grain ruling, 2026-10-09)
6
+ * absorbs the canonical CVC-236 v4 tree (prototype
6
7
  * `core_information_scope.v4.draft.yaml`, signed 2026-10-09; developer handoff
7
8
  * `docs/share-roi/INFOSCOPE_V4_DEV_HANDOFF_2026-10-09.md`):
8
9
  *
@@ -69,6 +70,9 @@ interface Entry {
69
70
  restrictionSuccessors?: string[];
70
71
  restrictionSuccessorCodes?: string[];
71
72
  migrationRule?: string;
73
+ v3Fields?: string[];
74
+ v3Domains?: string[];
75
+ v3FieldsNote?: string;
72
76
  }
73
77
 
74
78
  interface MigrationLine {
@@ -79,6 +83,10 @@ interface MigrationLine {
79
83
  toCodes: string[];
80
84
  note: string;
81
85
  widens: boolean;
86
+ releaseReading?: string;
87
+ releaseReadingNote?: string;
88
+ policyReading?: string;
89
+ informational?: boolean;
82
90
  }
83
91
 
84
92
  interface Envelope {
@@ -100,6 +108,15 @@ interface Envelope {
100
108
  readAt: string;
101
109
  unstamped: string;
102
110
  rules: Record<string, string>;
111
+ ruling: {
112
+ date: string;
113
+ by: string;
114
+ source: string;
115
+ text: string[];
116
+ applies: string;
117
+ membership: string;
118
+ canon: string;
119
+ };
103
120
  table: MigrationLine[];
104
121
  };
105
122
  entries: Entry[];
@@ -108,8 +125,8 @@ interface Envelope {
108
125
  const read = (f: string): Envelope =>
109
126
  JSON.parse(readFileSync(path.join(cvcDir, f), "utf8")) as Envelope;
110
127
 
111
- const scope = read("coreInformationScope.v2.0.0.json");
112
- const roi = read("roiScope.v1.3.0.json");
128
+ const scope = read("coreInformationScope.v2.1.0.json");
129
+ const roi = read("roiScope.v1.4.0.json");
113
130
 
114
131
  const byCode = new Map(scope.entries.map((e) => [e.code, e]));
115
132
  const byKey = new Map(scope.entries.map((e) => [e.key, e]));
@@ -574,7 +591,9 @@ describe("core_information_scope v4 — retirements and the from-to table (hando
574
591
  subtract: 1,
575
592
  "retired before v4": 17,
576
593
  });
577
- expect(Object.keys(m.rules).sort()).toEqual([...Object.keys(counts), "widens"].sort());
594
+ expect(Object.keys(m.rules).sort()).toEqual(
595
+ [...Object.keys(counts), "widens", "releaseReading", "policyReading", "informational"].sort(),
596
+ );
578
597
  for (const l of table) {
579
598
  expect(byKey.get(l.from)?.code, l.from).toBe(l.fromCode);
580
599
  expect(l.toCodes, l.from).toEqual(l.to.map((t) => liveKey(t)?.code));
@@ -619,7 +638,8 @@ describe("core_information_scope v4 — retirements and the from-to table (hando
619
638
 
620
639
  it("flags exactly the readings that WIDEN: a target shared by more than one v3 code", () => {
621
640
  // Computed: an identity/row line widens when its target is also another
622
- // v3 code's identity/row target. Pinned: consent widening, OPEN (Crysta).
641
+ // v3 code's identity/row target. Pinned; consent widening RULED 2026-10-09
642
+ // (Crysta; canon SIGNED-GRAIN): see `releaseReading` below.
623
643
  const sel = table.filter((l) => l.rule === "identity" || l.rule === "row");
624
644
  const sources = new Map<string, Set<string>>();
625
645
  for (const l of sel) {
@@ -651,6 +671,89 @@ describe("core_information_scope v4 — retirements and the from-to table (hando
651
671
  ).toEqual(PINNED);
652
672
  // Only identity and row lines can widen.
653
673
  expect(table.filter((l) => l.widens && l.rule !== "identity" && l.rule !== "row")).toEqual([]);
674
+ // RULED 2026-10-09 (Crysta; canon SIGNED-GRAIN): the nine merge folds are
675
+ // retained for a signed release / share; the widening IDENTITY line canon
676
+ // leaves unmarked reads as its successor (itself) for every subject, with
677
+ // a stated reason; every widening line is a policy's successor.
678
+ const identityWidening = table.filter((l) => l.widens && l.rule === "identity").map((l) => l.from);
679
+ expect(identityWidening).toEqual(["immigration_status"]);
680
+ expect(table.filter((l) => l.releaseReading === "retain").map((l) => l.from).sort()).toEqual(
681
+ PINNED.filter((k) => !identityWidening.includes(k)),
682
+ );
683
+ for (const l of table.filter((x) => x.releaseReading === "successor")) {
684
+ expect(identityWidening, l.from).toContain(l.from);
685
+ expect(l.releaseReadingNote, l.from).toMatch(/followed canon/);
686
+ }
687
+ expect(table.filter((l) => l.widens).every((l) => l.releaseReading !== undefined)).toBe(true);
688
+ expect(table.filter((l) => !l.widens).every((l) => l.releaseReading === undefined)).toBe(true);
689
+ expect(table.filter((l) => l.policyReading === "successor").map((l) => l.from).sort()).toEqual(PINNED);
690
+ for (const k of PINNED) {
691
+ expect(scope._supersedes.notes[k], k).toContain("RULED 2026-10-09");
692
+ expect(scope._supersedes.notes[k], k).not.toMatch(/OPEN, owner Crysta/);
693
+ }
694
+ });
695
+
696
+ it("carries the v3 field membership each retained unit keeps (canon placements, never hand-typed)", () => {
697
+ const retained = table.filter((l) => l.releaseReading === "retain");
698
+ // The units carrying membership are exactly the retained lines' sources.
699
+ expect(sortedKeys(rows.filter((e) => e.v3Fields !== undefined))).toEqual(
700
+ retained.map((l) => l.from).sort(),
701
+ );
702
+ const EXPECTED: Record<string, string[]> = {
703
+ mental_health_status: ["capture.mental_health_status"],
704
+ substance_use_status: ["capture.substance_use_status"],
705
+ chronic_health_status: ["capture.chronic_health_severity", "capture.long_term_conditions"],
706
+ disability_subtypes: ["capture.has_disability"],
707
+ hiv_status: ["capture.hiv_status"],
708
+ federal_protection_applications: ["capture.legal_action_type"],
709
+ le_report_status: ["capture.le_report_status"],
710
+ uscis_alien_number: [],
711
+ tvap_enrollment: [],
712
+ };
713
+ for (const l of retained) {
714
+ const e = byKey.get(l.from);
715
+ expect(e?.v3Fields, l.from).toEqual(EXPECTED[l.from]);
716
+ expect(l.to, l.from).toHaveLength(1);
717
+ // v3Domains are the category-grain families of those fields.
718
+ const family = byKey.get(l.from)?.parentKey === "health_accommodation"
719
+ ? "access_accommodations"
720
+ : "immigration_legal_status";
721
+ expect(e?.v3Domains, l.from).toEqual(e?.v3Fields?.length ? [family] : []);
722
+ if (e?.v3Fields?.length === 0) expect(e.v3FieldsNote, l.from).toMatch(/RETAINS NOTHING/);
723
+ }
724
+ // The identity line follows canon (no retain), both facts on its line.
725
+ expect(liveKey("immigration_status")?.v3Fields).toBeUndefined();
726
+ const imm = table.find((l) => l.from === "immigration_status");
727
+ expect(imm?.releaseReadingNote).toContain("v3 control of `capture.immigration_status`");
728
+ expect(imm?.releaseReadingNote).toContain("`replacesV3`");
729
+ expect(scope.migrations.ruling.membership).toContain(
730
+ "INFOSCOPE_FIELD_PLACEMENTS_V4_2026-10-08.csv (`home_unit_today`) @ 00179edc",
731
+ );
732
+ expect(scope._source).toContain("INFOSCOPE_FIELD_PLACEMENTS_V4_2026-10-08.csv");
733
+ });
734
+
735
+ it("marks exactly the retired-before-v4 lines informational (ruling 2), readings unchanged", () => {
736
+ const info = table.filter((l) => l.informational === true);
737
+ expect(info).toHaveLength(17);
738
+ expect(info).toEqual(table.filter((l) => l.rule === "retired before v4"));
739
+ const odd = table.filter((l) => l.informational !== undefined && l.informational !== true);
740
+ expect(odd).toEqual([]);
741
+ });
742
+
743
+ it("records Crysta's ruling verbatim, with what is still pending in canon", () => {
744
+ const r = scope.migrations.ruling;
745
+ expect([r.date, r.by]).toEqual(["2026-10-09", "Crysta"]);
746
+ expect(r.source).toContain("https://htilabs-us.slack.com/archives/D0811D2R6QN/p1791581735053759");
747
+ expect(r.text).toHaveLength(2);
748
+ expect(r.text[0]).toContain("a SIGNED RELEASE keeps the grain it was signed at.");
749
+ expect(r.text[0]).toContain(
750
+ "Policies and presets (agency-authored, not consent) take the merged successor with a dated " +
751
+ "version row.",
752
+ );
753
+ expect(r.text[1]).toContain("The retired_v3 rows are informational");
754
+ expect(r.canon).toMatch(/^Absorbed from canon at [0-9a-f]{8} \(SIGNED-GRAIN, 2026-10-09\)/);
755
+ expect(scope._source).toMatch(/v4\.draft\.yaml @ e86dd89c /);
756
+ expect(scope._status).toContain("RULED 2026-10-09");
654
757
  });
655
758
 
656
759
  it("sends a v2-era or unstamped list through canon's pinned v2 -> v3 table first", () => {
@@ -804,11 +907,12 @@ describe("core_information_scope — carried-over rulings", () => {
804
907
  });
805
908
 
806
909
  // ═══════════════════════════════════════════════════════════════════════════
807
- describe("core_information_scope — v2.0.0 supersedes v1.1.0", () => {
910
+ describe("core_information_scope — v2.1.0 (amends 2.0.0) supersedes v1.1.0", () => {
808
911
  const sup = scope._supersedes;
809
912
 
810
- it("is version 2.0.0, superseding 1.1.0, with no code withdrawn", () => {
811
- expect(scope.version).toBe("2.0.0");
913
+ it("is version 2.1.0, superseding 1.1.0, with no code withdrawn", () => {
914
+ expect(scope.version).toBe("2.1.0");
915
+ expect(scope._status).toContain("VERSION 2.1.0 amends 2.0.0 (MINOR, additive");
812
916
  expect(sup.version).toBe("1.1.0");
813
917
  expect(sup.retiredCodes).toEqual([]);
814
918
  });
@@ -831,17 +935,18 @@ describe("core_information_scope — v2.0.0 supersedes v1.1.0", () => {
831
935
  });
832
936
 
833
937
  it("leaves no superseded file behind for the registry to resolve", () => {
834
- for (const v of ["1.0.0", "1.1.0"]) {
938
+ for (const v of ["1.0.0", "1.1.0", "2.0.0"]) {
835
939
  expect(() => readFileSync(path.join(cvcDir, `coreInformationScope.v${v}.json`))).toThrow();
836
940
  }
837
941
  });
838
942
  });
839
943
 
840
- describe("roi_scope — v1.3.0 supersedes v1.2.0", () => {
944
+ describe("roi_scope — v1.4.0 (amends 1.3.0) supersedes v1.2.0", () => {
841
945
  const sup = roi._supersedes;
842
946
 
843
- it("is version 1.3.0, superseding 1.2.0, identity keyMap, nothing withdrawn", () => {
844
- expect(roi.version).toBe("1.3.0");
947
+ it("is version 1.4.0, superseding 1.2.0, identity keyMap, nothing withdrawn", () => {
948
+ expect(roi.version).toBe("1.4.0");
949
+ expect(roi._status).toContain("VERSION 1.4.0 amends 1.3.0 (MINOR: readings only");
845
950
  expect(sup.version).toBe("1.2.0");
846
951
  expect(sup.retiredCodes).toEqual([]);
847
952
  expect(Object.keys(sup.keyMap)).toEqual(roi.entries.map((e) => e.key));
@@ -849,7 +954,7 @@ describe("roi_scope — v1.3.0 supersedes v1.2.0", () => {
849
954
  for (const [from, to] of Object.entries(sup.keyMap)) expect(to, from).toBe(from);
850
955
  });
851
956
 
852
- it("notes each new retirement with its CVC-236 twin's reading", () => {
957
+ it("notes each new retirement with its CVC-236 twin's reading (release grain for a signed ROI)", () => {
853
958
  const newly = roi.entries
854
959
  .filter((e) => e.retired === true && !["screen_notes", "background"].includes(e.key))
855
960
  .map((e) => e.key);
@@ -858,13 +963,34 @@ describe("roi_scope — v1.3.0 supersedes v1.2.0", () => {
858
963
  for (const k of newly) {
859
964
  const twin = byKey.get(k);
860
965
  for (const s of twin?.successors ?? []) expect(sup.notes[k], k).toContain(`\`${s}\``);
861
- expect(sup.notes[k], k).toContain("CVC-236 v2.0.0 retired the same key");
966
+ expect(sup.notes[k], k).toContain("CVC-236 retired the same key");
862
967
  expect(sup.notes[k], k).toContain("unstamped and v2-era");
968
+ const def = roi.entries.find((e) => e.key === k)?.definition ?? "";
969
+ const line = scope.migrations.table.find(
970
+ (l) => l.from === k && l.rule !== "subtract" && l.rule !== "identity",
971
+ );
972
+ expect(def, k).toContain(`CVC-236 v${scope.version}'s \`migrations\``);
973
+ expect(def, k).not.toMatch(/v2\.0\.0/);
974
+ if (line?.releaseReading === "retain") {
975
+ // A stored ROI is a SIGNED RELEASE: it keeps the twin's v3 grain.
976
+ for (const text of [def, sup.notes[k]]) {
977
+ expect(text, k).toContain("An ROI is a SIGNED RELEASE");
978
+ expect(text, k).toContain("a policy or preset naming the same code takes");
979
+ const fields = twin?.v3Fields ?? [];
980
+ if (fields.length === 0) expect(text, k).toContain("RETAINS NOTHING");
981
+ for (const f of fields) expect(text, k).toContain(`\`${f}\``);
982
+ }
983
+ } else {
984
+ expect(line?.informational, k).toBe(true);
985
+ expect(def, k).toContain("`informational`");
986
+ }
863
987
  }
988
+ expect(roi._source).toContain(`coreInformationScope.v${scope.version}.json`);
989
+ expect(roi._source).not.toMatch(/coreInformationScope\.v2\.0\.0/);
864
990
  });
865
991
 
866
992
  it("leaves no superseded file behind", () => {
867
- for (const v of ["1.0.0", "1.1.0", "1.2.0"]) {
993
+ for (const v of ["1.0.0", "1.1.0", "1.2.0", "1.3.0"]) {
868
994
  expect(() => readFileSync(path.join(cvcDir, `roiScope.v${v}.json`))).toThrow();
869
995
  }
870
996
  });
@@ -657,7 +657,7 @@ const SOT_SPECS: readonly SotSpec[] = [
657
657
  // retired to match CVC-236 v2.0.0, the v4 tree — codes kept, never reused)
658
658
  // + 4 missingness = 31. SOT v1.3.0 (supersedes 1.2.0: the retirements are
659
659
  // not additive; co-bwc "one answer to offerable").
660
- { file: "roiScope.v1.3.0.json", domain: "roi_scope", expectedCount: 31 },
660
+ { file: "roiScope.v1.4.0.json", domain: "roi_scope", expectedCount: 31 },
661
661
  // 5 stored-ROI lifecycle states (@pave/domain ROI_STATUSES) + 4 = 9
662
662
  { file: "roiStatus.v1.0.0.json", domain: "roi_status", expectedCount: 9 },
663
663
  // 2 HMIS FY2026 "P2 Referrals Provided" outcomes (attained / not_attained)
@@ -744,11 +744,12 @@ const SOT_SPECS: readonly SotSpec[] = [
744
744
  // groups · 3 person types · 38 categories · 43 sub-categories (34
745
745
  // `subcategory` + 9 LEADS `sub-category`) · 1 rest row · 28 instrument rows) + 27 RETIRED tombstones (every v1.1.0 code v4 no longer
746
746
  // carries — codes kept, never reused) + 1 missingness root + 3
747
- // workspace-standard missingness children = 146. SOT v2.0.0 (supersedes
747
+ // workspace-standard missingness children = 146. SOT v2.1.0 (amends 2.0.0,
748
+ // additive release-grain fields; 2.0.0 superseded
748
749
  // 1.1.0: 25 new retirements, categories selectable). Generated by
749
750
  // scripts/gen-core-information-scope.py; codes are FROZEN there.
750
751
  {
751
- file: "coreInformationScope.v2.0.0.json",
752
+ file: "coreInformationScope.v2.1.0.json",
752
753
  domain: "core_information_scope",
753
754
  expectedCount: 146,
754
755
  },
@@ -184,7 +184,7 @@ const SOT_FILES: readonly SotFile[] = [
184
184
  // ─── 0.8.12 vocabulary batch ───
185
185
  { file: "coreFunctions.v1.1.0.json", expectedDomain: "core_functions" },
186
186
  { file: "needsAssessmentChangeType.v1.0.0.json", expectedDomain: "needs_assessment_change_type" },
187
- { file: "roiScope.v1.3.0.json", expectedDomain: "roi_scope" },
187
+ { file: "roiScope.v1.4.0.json", expectedDomain: "roi_scope" },
188
188
  { file: "roiStatus.v1.0.0.json", expectedDomain: "roi_status" },
189
189
  { file: "coreReferralOutcome.v1.0.0.json", expectedDomain: "core_referral_outcome" },
190
190
  { file: "assertionDomain.v1.1.0.json", expectedDomain: "assertion_domain" },
@@ -235,7 +235,7 @@ const SOT_FILES: readonly SotFile[] = [
235
235
  { file: "suggestionSource.v1.0.0.json", expectedDomain: "suggestion_source" },
236
236
  // CVC-236 — generated by scripts/gen-core-information-scope.py. Omitted from
237
237
  // this list since it was authored; added with the priorities_safety unit.
238
- { file: "coreInformationScope.v2.0.0.json", expectedDomain: "core_information_scope" },
238
+ { file: "coreInformationScope.v2.1.0.json", expectedDomain: "core_information_scope" },
239
239
  // ─── GDR §10.1 CAR-contract vocabularies (provisional 900-block; PAVE
240
240
  // @pave/domain verbatim; bead pv-pgdr-cvc-source-gdr-10-1-bulk-publish). ───
241
241
  { file: "assertionStatus.v1.0.0.json", expectedDomain: "assertion_status" },
@@ -51,7 +51,7 @@ const read = (f: string): { entries: Entry[]; _source?: string } =>
51
51
  };
52
52
 
53
53
  const lt = read("locationType.v1.0.0.json");
54
- const scope = read("coreInformationScope.v2.0.0.json");
54
+ const scope = read("coreInformationScope.v2.1.0.json");
55
55
  const byKey = new Map(lt.entries.map((e) => [e.key, e]));
56
56
  const scopeByKey = new Map(scope.entries.map((e) => [e.key, e]));
57
57
  const reasons = lt.entries.filter((e) => e.key !== "missingness_root");