@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
@@ -1,10 +1,10 @@
1
1
  /**
2
2
  * CVC-236 v4 information-scope resolver.
3
3
  *
4
- * PRIMARY binding: the package SOT (`coreInformationScope.v2.0.0.json`, co-o73.1)
4
+ * PRIMARY binding: the package SOT (`coreInformationScope.v2.1.0.json`, co-o73.1)
5
5
  * through `scopeRowsFromSot` / `scopeMigrationsFromSot`. CROSS-CHECK: the canon's
6
- * generated CSV pair (prototype @ 6dab8a95, byte-identical at 00179edc) must equal
7
- * the adapter output row for row.
6
+ * generated CSV pair (prototype @ e86dd89c SIGNED-GRAIN, byte-identical at 7ca7e586)
7
+ * must equal the adapter output row for row.
8
8
  *
9
9
  * Spec: INFOSCOPE_V4_DEV_HANDOFF_2026-10-09.md § 2 rules 1–7, § 3, § 7 row 6;
10
10
  * scenarios from INFOSCOPE_PHASE4_STRESS_TEST_2026-10-09.md § 1 and the runner
@@ -33,12 +33,14 @@ import {
33
33
  type CoreInformationScopeSot,
34
34
  } from "../informationScopeSot.js";
35
35
  import {
36
+ INFOSCOPE_V3_PLACEMENTS,
36
37
  INFOSCOPE_V4_CANON_BLOBS,
37
38
  INFOSCOPE_V4_CANON_SHA,
38
39
  fixtureBodyBlobSha,
39
40
  fixtureText,
40
41
  loadCsvMigrations,
41
42
  loadCsvRows,
43
+ loadV3Placements,
42
44
  type InfoscopeFixture,
43
45
  } from "./fixtures/infoscope-v4/loadInfoscopeV4Fixtures.js";
44
46
 
@@ -59,6 +61,11 @@ const isFloor = (c: string): boolean => scope.row(c)?.platformFloor === true;
59
61
  const isOff = (c: string): boolean => scope.row(c)?.shareableDefault === false;
60
62
  const ENABLED_ALL = codes.filter((c) => isOff(c) && !isFloor(c));
61
63
  const KINDS = ["offenders", "family", "others"] as const;
64
+ /** Whose list is read (ruling 2026-10-09: required, no default). */
65
+ const RELEASE = { subject: "release" } as const;
66
+ const SHARE = { subject: "share" } as const;
67
+ const POLICY = { subject: "policy" } as const;
68
+ const SUBJECTS = [RELEASE, SHARE, POLICY] as const;
62
69
  /** Order-insensitive list equality (output order follows the bound tree's row order). */
63
70
  const same = (got: readonly string[], want: readonly string[]): void =>
64
71
  expect([...got].sort()).toEqual([...want].sort());
@@ -200,6 +207,20 @@ describe("binding — the SOT through the adapters; the canon CSV pair as cross-
200
207
  expect(csv).toHaveLength(104);
201
208
  expect(migrations).toHaveLength(103);
202
209
  same([...new Set(csv.map(line))], migrations.map(line));
210
+ // Canon's qualified labels are exactly the SOT's qualifier fields.
211
+ const merge = csv.filter((m) => m.label === "row (merge; signed release keeps its grain)");
212
+ same(
213
+ merge.map((m) => m.from),
214
+ migrations.filter((m) => m.releaseReading === "retain").map((m) => m.from),
215
+ );
216
+ same(
217
+ csv.filter((m) => m.informational === true).map((m) => m.from),
218
+ migrations.filter((m) => m.informational === true).map((m) => m.from),
219
+ );
220
+ for (const m of migrations) {
221
+ const c = csv.find((x) => x.from === m.from && x.rule === m.rule);
222
+ expect(m.note, m.from).toBe(c?.note);
223
+ }
203
224
  });
204
225
 
205
226
  it("binding the CSV pair directly gives the same resolver answers", () => {
@@ -546,14 +567,14 @@ describe("kindForPerson (D5) — caused harm wins; EFM is asserted; neither →
546
567
 
547
568
  describe("§ 3 — readSelection / readRestriction", () => {
548
569
  it("identity: an unchanged code reads the same", () => {
549
- const r = scope.readSelection([SYS, "names", "contact_info"], 3);
570
+ const r = scope.readSelection([SYS, "names", "contact_info"], 3, RELEASE);
550
571
  same(r.informationScope, [SYS, "names", "contact_info"]);
551
572
  expect(r.codes.map((c) => c.rule)).toEqual(["identity", "identity", "identity"]);
552
573
  expect(r.unsupportedVersion).toBe(false);
553
574
  });
554
575
 
555
- it("row: retired v3 rows read as their successors", () => {
556
- const r = scope.readSelection(["hiv_status", "uscis_alien_number", "tvap_enrollment"], 3);
576
+ it("row: retired v3 rows read as their successors (a policy's reading)", () => {
577
+ const r = scope.readSelection(["hiv_status", "uscis_alien_number", "tvap_enrollment"], 3, POLICY);
557
578
  same(r.informationScope, [
558
579
  SYS,
559
580
  "health_status",
@@ -564,20 +585,20 @@ describe("§ 3 — readSelection / readRestriction", () => {
564
585
  });
565
586
 
566
587
  it("row: offender_facilitator reads as offenders.identifying + offenders.risk, never the whole kind", () => {
567
- const r = scope.readSelection([SYS, "offender_facilitator"], 3);
588
+ const r = scope.readSelection([SYS, "offender_facilitator"], 3, RELEASE);
568
589
  same(r.informationScope, [SYS, "offenders.identifying", "offenders.risk"]);
569
590
  expect(scope.isCovered(r.informationScope, "offenders.contact")).toBe(false);
570
591
  expect(scope.isCovered(r.informationScope, "offenders.health_accommodation")).toBe(false);
571
592
  });
572
593
 
573
594
  it("D11 category: risk → risk only; identifying → identifying only (never widened)", () => {
574
- const risk = scope.readSelection([SYS, "risk"], 3);
595
+ const risk = scope.readSelection([SYS, "risk"], 3, POLICY);
575
596
  same(risk.informationScope, [SYS, "risk"]);
576
597
  expect(risk.codes[1].rule).toBe("category");
577
598
  for (const kind of KINDS) {
578
599
  expect(scope.isCovered(risk.informationScope, `${kind}.risk`)).toBe(false);
579
600
  }
580
- const ident = scope.readSelection([SYS, "identifying"], 3);
601
+ const ident = scope.readSelection([SYS, "identifying"], 3, POLICY);
581
602
  same(ident.informationScope, [SYS, "identifying"]);
582
603
  for (const kind of KINDS) {
583
604
  expect(scope.isCovered(ident.informationScope, `${kind}.identifying`)).toBe(false);
@@ -597,7 +618,11 @@ describe("§ 3 — readSelection / readRestriction", () => {
597
618
  });
598
619
 
599
620
  it("retired before v4: the pre-v3 instrument codes have a stated reading, some read as nothing", () => {
600
- const r = scope.readSelection(["ida_full", "screen_notes", "background", "assessment_records"], 3);
621
+ const r = scope.readSelection(
622
+ ["ida_full", "screen_notes", "background", "assessment_records"],
623
+ 3,
624
+ RELEASE,
625
+ );
601
626
  same(r.informationScope, [SYS, "summary_ida", "full_ida"]);
602
627
  expect(r.codes.map((c) => c.rule)).toEqual(Array(4).fill("retired before v4"));
603
628
  });
@@ -606,6 +631,7 @@ describe("§ 3 — readSelection / readRestriction", () => {
606
631
  const r = scope.readSelection(
607
632
  [SYS, "offenders", "hiv_status", "offender_facilitator", "assessment_records", "nope"],
608
633
  4,
634
+ POLICY,
609
635
  );
610
636
  expect(r.codes.map((c) => [c.from, c.rule])).toEqual([
611
637
  [SYS, "identity"],
@@ -630,18 +656,23 @@ describe("§ 3 — readSelection / readRestriction", () => {
630
656
  });
631
657
 
632
658
  it("widening lines are surfaced, never hidden (SOT `widens: true`)", () => {
633
- const r = scope.readSelection(["names", "hiv_status", "immigration_status"], 3);
659
+ const r = scope.readSelection(["names", "hiv_status", "immigration_status"], 3, POLICY);
634
660
  expect(r.widened).toEqual(["hiv_status", "immigration_status"]);
635
661
  expect(r.codes.map((c) => c.widens)).toEqual([false, true, true]);
636
- expect(scope.readSelection(["immigration_status"], 4).widened).toEqual([]);
662
+ expect(scope.readSelection(["immigration_status"], 4, POLICY).widened).toEqual([]);
637
663
  expect(migrations.filter((m) => m.widens).map((m) => m.from)).toHaveLength(10);
638
664
  });
639
665
 
640
666
  it("a v2-era or unstamped list fails closed: this package ships no v2 → v3 table", () => {
641
667
  for (const version of [2, undefined]) {
642
- const r = scope.readSelection(["ida_consid", "names"], version);
643
- expect(r.unsupportedVersion).toBe(true);
644
- expect(r.informationScope).toEqual([SYS]);
668
+ for (const options of SUBJECTS) {
669
+ const r = scope.readSelection(["ida_consid", "names", "hiv_status"], version, options);
670
+ expect(r.unsupportedVersion).toBe(true);
671
+ expect(r.informationScope).toEqual([SYS]);
672
+ expect(r.retained).toEqual([]);
673
+ expect(r.widened).toEqual([]);
674
+ expect(r.versionRowRequired).toBe(false);
675
+ }
645
676
  }
646
677
  });
647
678
 
@@ -658,7 +689,7 @@ describe("§ 3 — readSelection / readRestriction", () => {
658
689
 
659
690
  it("a signed list is kept as signed — never mutated, never rewritten", () => {
660
691
  const signed = Object.freeze(["names", "hiv_status", "names"]);
661
- const r = scope.readSelection(signed, 3);
692
+ const r = scope.readSelection(signed, 3, RELEASE);
662
693
  expect(signed).toEqual(["names", "hiv_status", "names"]);
663
694
  expect(r.stored).toEqual(["names", "hiv_status", "names"]);
664
695
  expect(r.storedVersion).toBe(3);
@@ -669,7 +700,7 @@ describe("§ 3 — readSelection / readRestriction", () => {
669
700
  it.each([undefined, null, 0, 1, 2, 5, 3.5, Number.NaN, "3"])(
670
701
  "reads are total: scopeVersion %j is unsupported, so every code includes nothing",
671
702
  (version) => {
672
- const r = scope.readSelection(["names", "hiv_status"], version as number);
703
+ const r = scope.readSelection(["names", "hiv_status"], version as number, POLICY);
673
704
  expect(r.unsupportedVersion).toBe(true);
674
705
  expect(r.codes.map((c) => c.rule)).toEqual(["unknown", "unknown"]);
675
706
  expect(r.informationScope).toEqual([SYS]);
@@ -680,7 +711,7 @@ describe("§ 3 — readSelection / readRestriction", () => {
680
711
 
681
712
  it("reads are total: a null or missing list reads as empty", () => {
682
713
  for (const list of [null, undefined]) {
683
- const r = scope.readSelection(list, 3);
714
+ const r = scope.readSelection(list, 3, SHARE);
684
715
  expect(r.stored).toEqual([]);
685
716
  expect(r.informationScope).toEqual([SYS]);
686
717
  expect(scope.readRestriction(list, 4).informationScope).toEqual([]);
@@ -699,9 +730,9 @@ describe("§ 3 — readSelection / readRestriction", () => {
699
730
  const keys = Object.keys(sot._supersedes.keyMap);
700
731
  expect(keys).toHaveLength(73);
701
732
  for (const key of keys) {
702
- expect(scope.readSelection([key], 2).unsupportedVersion).toBe(true);
703
- for (const version of [3]) {
704
- const [reading] = scope.readSelection([key], version).codes;
733
+ expect(scope.readSelection([key], 2, RELEASE).unsupportedVersion).toBe(true);
734
+ for (const options of SUBJECTS) {
735
+ const [reading] = scope.readSelection([key], 3, options).codes;
705
736
  if (missingness.has(key)) {
706
737
  expect(reading.rule, key).toBe("unknown");
707
738
  expect(reading.reads).toEqual([]);
@@ -714,6 +745,289 @@ describe("§ 3 — readSelection / readRestriction", () => {
714
745
  });
715
746
  });
716
747
 
748
+ // ─── Release grain (Crysta, 2026-10-09; SOT `migrations.ruling`) ──────────
749
+
750
+ describe("release grain — a signed release keeps the grain it was signed at (ruling 2026-10-09)", () => {
751
+ const WIDENING = [
752
+ "chronic_health_status",
753
+ "disability_subtypes",
754
+ "federal_protection_applications",
755
+ "hiv_status",
756
+ "immigration_status",
757
+ "le_report_status",
758
+ "mental_health_status",
759
+ "substance_use_status",
760
+ "tvap_enrollment",
761
+ "uscis_alien_number",
762
+ ];
763
+ /** Canon's nine merge folds (`signed_release_grain: keep`): the identity line is not one. */
764
+ const RETAINED = WIDENING.filter((c) => c !== "immigration_status");
765
+ const entry = (key: string) => sot.entries.find((e) => e.key === key);
766
+
767
+ it("canon's nine merge folds are retained for a release; every widening line is a policy's successor", () => {
768
+ const retain = migrations.filter((m) => m.releaseReading === "retain");
769
+ expect(retain.map((m) => m.from).sort()).toEqual(RETAINED);
770
+ expect(migrations.filter((m) => m.widens).map((m) => m.from).sort()).toEqual(WIDENING);
771
+ expect(
772
+ migrations.filter((m) => m.releaseReading === "successor").map((m) => [m.from, m.rule]),
773
+ ).toEqual([["immigration_status", "identity"]]);
774
+ for (const m of retain) {
775
+ expect(m.policyReading, m.from).toBe("successor");
776
+ expect(m.to, m.from).toHaveLength(1);
777
+ expect(m.v3Fields, m.from).toEqual(entry(m.from)?.v3Fields);
778
+ expect(m.v3Domains, m.from).toEqual(entry(m.from)?.v3Domains);
779
+ }
780
+ const policy = migrations.filter((m) => m.policyReading !== undefined).map((m) => m.from);
781
+ expect(policy.sort()).toEqual(WIDENING);
782
+ });
783
+
784
+ it.each([RELEASE, SHARE])(
785
+ "a v3 %j naming only mental_health_status keeps its v3 fields and never reads health_status",
786
+ (options) => {
787
+ const r = scope.readSelection([SYS, "mental_health_status"], 3, options);
788
+ expect(r.subject).toBe(options.subject);
789
+ expect(r.retained).toEqual([
790
+ {
791
+ code: "mental_health_status",
792
+ v3Fields: ["capture.mental_health_status"],
793
+ v3Domains: ["access_accommodations"],
794
+ successor: "health_status",
795
+ },
796
+ ]);
797
+ expect(r.informationScope).toEqual([SYS]);
798
+ expect(scope.isCovered(r.informationScope, "health_status")).toBe(false);
799
+ expect(r.widened).toEqual([]);
800
+ expect(r.codes[1]).toEqual({
801
+ from: "mental_health_status",
802
+ rule: "row",
803
+ reads: [],
804
+ widens: false,
805
+ retained: true,
806
+ });
807
+ // Still a retired code, still recognisable (§ 3 (c)).
808
+ expect(r.retired).toEqual(["mental_health_status"]);
809
+ expect(r.versionRowRequired).toBe(false);
810
+ expect(r.note).toBeNull();
811
+ },
812
+ );
813
+
814
+ it("the same list as a policy reads health_status, flagged widened, with a dated version row due", () => {
815
+ const r = scope.readSelection([SYS, "mental_health_status"], 3, POLICY);
816
+ same(r.informationScope, [SYS, "health_status"]);
817
+ expect(r.widened).toEqual(["mental_health_status"]);
818
+ expect(r.retained).toEqual([]);
819
+ expect(r.codes[1].retained).toBe(false);
820
+ expect(r.versionRowRequired).toBe(true);
821
+ expect(r.note).toMatch(/new version row on the record, dated/);
822
+ });
823
+
824
+ it.each([RELEASE, SHARE])(
825
+ "immigration_status alone as a %j reads as itself (canon leaves the identity line unmarked)",
826
+ (options) => {
827
+ const r = scope.readSelection([SYS, "immigration_status"], 3, options);
828
+ same(r.informationScope, [SYS, "immigration_status"]);
829
+ expect(r.codes[1]).toMatchObject({ rule: "identity", widens: true, retained: false });
830
+ expect(r.widened).toEqual(["immigration_status"]);
831
+ expect(r.retained).toEqual([]);
832
+ // Both facts stated: the line is mechanically wider (`replacesV3`), and the
833
+ // A-number input was already a v3 control of capture.immigration_status.
834
+ const line = migrations.find((m) => m.from === "immigration_status");
835
+ expect(line?.releaseReadingNote).toMatch(/followed canon/);
836
+ expect(line?.releaseReadingNote).toContain("`uscis_alien_number`");
837
+ expect(line?.releaseReadingNote).toContain("v3 control of `capture.immigration_status`");
838
+ expect(entry("immigration_status")?.v3Fields).toBeUndefined();
839
+ },
840
+ );
841
+
842
+ it("immigration_status alone as a policy reads as itself (identity), flagged widened", () => {
843
+ const r = scope.readSelection([SYS, "immigration_status"], 3, POLICY);
844
+ same(r.informationScope, [SYS, "immigration_status"]);
845
+ expect(r.codes[1]).toMatchObject({ rule: "identity", widens: true, retained: false });
846
+ expect(r.widened).toEqual(["immigration_status"]);
847
+ expect(r.retained).toEqual([]);
848
+ });
849
+
850
+ it.each(["uscis_alien_number", "tvap_enrollment"])(
851
+ "%s homed no v3 field: a release retaining it retains nothing, and says so",
852
+ (code) => {
853
+ const [kept] = scope.readSelection([code], 3, RELEASE).retained;
854
+ expect(kept.v3Fields).toEqual([]);
855
+ expect(kept.v3Domains).toEqual([]);
856
+ expect(kept.note).toMatch(/RETAINS NOTHING/);
857
+ expect(kept.successor).toBe(code === "tvap_enrollment" ? "immigration_applications" : "immigration_status");
858
+ },
859
+ );
860
+
861
+ it("the v3 placements fixture is the pinned projection of canon's file", () => {
862
+ const text = fixtureText(INFOSCOPE_V3_PLACEMENTS.file);
863
+ const head = text.split("\n")[0];
864
+ expect(head).toContain(INFOSCOPE_V3_PLACEMENTS.canonSha);
865
+ expect(head).toContain(INFOSCOPE_V3_PLACEMENTS.canonBlob);
866
+ const { file, projectionBlob } = INFOSCOPE_V3_PLACEMENTS;
867
+ expect(fixtureBodyBlobSha(file)).toBe(projectionBlob);
868
+ expect(Object.keys(loadV3Placements()[0])).toEqual([...INFOSCOPE_V3_PLACEMENTS.columns]);
869
+ same([...INFOSCOPE_V3_PLACEMENTS.units], WIDENING);
870
+ });
871
+
872
+ it("every retained unit's v3Fields / v3Domains equal canon's placements (not a hand-typed copy)", () => {
873
+ const placements = loadV3Placements();
874
+ for (const code of RETAINED) {
875
+ const homed = placements.filter((r) => r.home_unit_today === code);
876
+ const [kept] = scope.readSelection([code], 3, SHARE).retained;
877
+ expect(kept.code, code).toBe(code);
878
+ expect(kept.v3Fields, code).toEqual(homed.map((r) => r.field).sort());
879
+ const domains = [...new Set(homed.map((r) => r.assertion_domain))].sort();
880
+ expect(kept.v3Domains, code).toEqual(domains);
881
+ for (const r of homed) expect(r.home_grain_today, `${code} ${r.field}`).toBe("unit");
882
+ if (homed.length === 0) expect(kept.note, code).toMatch(/RETAINS NOTHING/);
883
+ }
884
+ // The fact the immigration_status note rests on: the A-number input is a v3
885
+ // control of a field homed on immigration_status.
886
+ const aNumber = placements.filter((r) => /\buscis_alien_number\b/.test(r.controls));
887
+ expect(aNumber.map((r) => [r.field, r.home_unit_today])).toEqual([
888
+ ["capture.immigration_status", "immigration_status"],
889
+ ]);
890
+ });
891
+
892
+ it.each([RELEASE, SHARE])(
893
+ "a stamp-3 %j naming any one retained code never covers its successor and widens nothing",
894
+ (options) => {
895
+ for (const code of RETAINED) {
896
+ const successor = migrations.find((m) => m.from === code && m.rule === "row")?.to[0] as string;
897
+ const r = scope.readSelection([SYS, code], 3, options);
898
+ expect(r.retained.map((k) => [k.code, k.successor]), code).toEqual([[code, successor]]);
899
+ expect(scope.isCovered(r.informationScope, successor), code).toBe(false);
900
+ expect(r.widened, code).toEqual([]);
901
+ expect(r.informationScope, code).toEqual([SYS]);
902
+ }
903
+ },
904
+ );
905
+
906
+ it("a category a v3 release named still covers its successor rows (the category was signed)", () => {
907
+ const r = scope.readSelection([SYS, "hiv_status", "health_accommodation"], 3, RELEASE);
908
+ expect(r.retained.map((k) => k.code)).toEqual(["hiv_status"]);
909
+ same(r.informationScope, [SYS, "health_accommodation"]);
910
+ expect(scope.isCovered(r.informationScope, "health_status")).toBe(true);
911
+ });
912
+
913
+ it("a v4-stamped list of live codes reads the same for every subject", () => {
914
+ const list = [SYS, "immigration_status", "health_status", "offender_facilitator"];
915
+ const policy = scope.readSelection(list, 4, POLICY);
916
+ for (const options of [RELEASE, SHARE]) {
917
+ const r = scope.readSelection(list, 4, options);
918
+ expect(r.codes, options.subject).toEqual(policy.codes);
919
+ expect(r.informationScope).toEqual(policy.informationScope);
920
+ expect(r.widened).toEqual(policy.widened);
921
+ expect(r.retained).toEqual([]);
922
+ }
923
+ expect(policy.versionRowRequired).toBe(false);
924
+ expect(policy.note).toBeNull();
925
+ });
926
+
927
+ it("a share carries its release's stamp: frozen under a v3 release it is stamp 3 and retains", () => {
928
+ const share = scope.readSelection([SYS, "hiv_status"], 3, SHARE);
929
+ expect(share.retained.map((k) => k.code)).toEqual(["hiv_status"]);
930
+ expect(scope.isCovered(share.informationScope, "health_status")).toBe(false);
931
+ });
932
+
933
+ it.each([RELEASE, SHARE])(
934
+ "a v4-stamped %j naming a retained tombstone includes nothing — never the successor",
935
+ (options) => {
936
+ for (const code of RETAINED) {
937
+ const r = scope.readSelection([SYS, code], 4, options);
938
+ const successor = migrations.find((m) => m.from === code && m.rule === "row")?.to[0] as string;
939
+ expect(r.codes[1], code).toEqual({
940
+ from: code,
941
+ rule: "row",
942
+ reads: [],
943
+ widens: false,
944
+ retained: false,
945
+ });
946
+ expect(r.informationScope, code).toEqual([SYS]);
947
+ expect(scope.isCovered(r.informationScope, successor), code).toBe(false);
948
+ expect(r.retained, code).toEqual([]);
949
+ expect(r.widened, code).toEqual([]);
950
+ expect(r.retired, code).toEqual([code]);
951
+ // A policy at stamp 4 still reads the table (§ 3 (c)).
952
+ same(scope.readSelection([SYS, code], 4, POLICY).informationScope, [SYS, successor]);
953
+ }
954
+ },
955
+ );
956
+
957
+ it("readRestriction keeps the subtract rule; a stamp-3 restriction is a policy's: version row due", () => {
958
+ const r = scope.readRestriction(["hiv_status", "immigration_status"], 3);
959
+ same(r.informationScope, ["health_status", "immigration_status"]);
960
+ expect(r.subject).toBeNull();
961
+ expect(r.retained).toEqual([]);
962
+ expect(r.versionRowRequired).toBe(true);
963
+ expect(r.note).toMatch(/new version row on the record, dated/);
964
+ const v4 = scope.readRestriction(["health_status"], 4);
965
+ expect([v4.versionRowRequired, v4.note]).toEqual([false, null]);
966
+ expect(scope.readRestriction(["health_status"], 2).versionRowRequired).toBe(false);
967
+ });
968
+
969
+ it("the subject is required: no silent default", () => {
970
+ const read = scope.readSelection as (
971
+ list: readonly string[],
972
+ v: number,
973
+ o?: unknown,
974
+ ) => unknown;
975
+ expect(() => read(["names"], 3)).toThrow(/options.subject/);
976
+ expect(() => read(["names"], 3, {})).toThrow(/options.subject/);
977
+ expect(() => read(["names"], 3, { subject: "preset" })).toThrow(/options.subject/);
978
+ });
979
+
980
+ it("the 17 retired-before-v4 lines are informational; their reading is unchanged (ruling 2)", () => {
981
+ const info = migrations.filter((m) => m.informational === true);
982
+ expect(info).toHaveLength(17);
983
+ expect(info.every((m) => m.rule === "retired before v4")).toBe(true);
984
+ expect(migrations.filter((m) => m.rule === "retired before v4")).toEqual(info);
985
+ for (const options of SUBJECTS) {
986
+ same(scope.readSelection(["lap"], 3, options).informationScope, [SYS, "summary_lap"]);
987
+ }
988
+ });
989
+
990
+ it("binding fails closed on a retained line without its v3 membership", () => {
991
+ const base = rows.filter((r) => r.scopeCode === "system" || r.scopeCode === SYS);
992
+ expect(() =>
993
+ createInformationScopeResolver({
994
+ rows: base,
995
+ migrations: [{ from: "old", to: [SYS], rule: "row", releaseReading: "retain" }],
996
+ }),
997
+ ).toThrow(/needs one successor and its v3Fields/);
998
+ expect(() =>
999
+ createInformationScopeResolver({
1000
+ rows: base,
1001
+ migrations: [
1002
+ {
1003
+ from: "old",
1004
+ to: [SYS, "system"],
1005
+ rule: "row",
1006
+ releaseReading: "retain",
1007
+ v3Fields: [],
1008
+ v3Domains: [],
1009
+ },
1010
+ ],
1011
+ }),
1012
+ ).toThrow(/needs one successor/);
1013
+ expect(() =>
1014
+ createInformationScopeResolver({
1015
+ rows: base,
1016
+ migrations: [{ from: "old", to: [SYS], rule: "row", releaseReading: "keep" as "retain" }],
1017
+ }),
1018
+ ).toThrow(/releaseReading "keep"/);
1019
+ const stripped = {
1020
+ ...sot,
1021
+ entries: sot.entries.map((e) => {
1022
+ if (e.key !== "hiv_status") return e;
1023
+ const { v3Fields: _f, ...rest } = e;
1024
+ return rest;
1025
+ }),
1026
+ };
1027
+ expect(() => scopeMigrationsFromSot(stripped)).toThrow(/"hiv_status" has v3Fields/);
1028
+ });
1029
+ });
1030
+
717
1031
  // ─── § 7 row 6: branch-grain pick vs category-grain ceiling ────────────────
718
1032
 
719
1033
  describe("§ 7 row 6 — expand a branch pick to the ceiling's grain before clamping", () => {
@@ -959,6 +1273,6 @@ describe("construction", () => {
959
1273
  SYS,
960
1274
  "health_status",
961
1275
  ]);
962
- expect(withTombstone.readSelection(["hiv_status"], 4).codes[0].rule).toBe("row");
1276
+ expect(withTombstone.readSelection(["hiv_status"], 4, RELEASE).codes[0].rule).toBe("row");
963
1277
  });
964
1278
  });