@htilabs/platform-common-models 0.55.0 → 0.56.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.
@@ -0,0 +1,1037 @@
1
+ /**
2
+ * The Level 3 category filter (`caseViewingAccess`, `recordViewing`,
3
+ * `caseSurfacesOn`, `viewingComponentOpen`) — ported from PAVE's
4
+ * `packages/domain/src/viewingScope.test.ts` (pave-2.0 develop 41f5f916), minus
5
+ * the stub-projection and `effectiveViewingLevel` blocks (they stay in PAVE; the
6
+ * shared level is `viewingLevelFromFunctions`). The resolver is this package's
7
+ * own binding of the CVC-236 SOT, the one PAVE and Thread bind.
8
+ */
9
+ import { describe, expect, it } from "vitest";
10
+
11
+ import {
12
+ type CaseViewingAccess,
13
+ caseSurfacesAsStub,
14
+ caseSurfacesOn,
15
+ caseViewingAccess as caseViewingAccessShared,
16
+ recordViewing as recordViewingShared,
17
+ resolveViewingPolicy,
18
+ viewingComponentOpen,
19
+ type ViewingContext,
20
+ viewingPolicyVocabulary,
21
+ type ViewingRecord,
22
+ viewingWhitelistFromPolicy,
23
+ } from "../authz/index.js";
24
+ import { coreInformationScopeSot } from "../cvcs/index.js";
25
+ import {
26
+ type CoreInformationScopeSot,
27
+ createInformationScopeResolver,
28
+ scopeMigrationsFromSot,
29
+ scopeRowsFromSot,
30
+ } from "../services/informationScope.js";
31
+
32
+ const sot = coreInformationScopeSot as unknown as CoreInformationScopeSot;
33
+ const INFORMATION_SCOPE_V4 = createInformationScopeResolver({
34
+ rows: scopeRowsFromSot(sot),
35
+ migrations: scopeMigrationsFromSot(sot),
36
+ });
37
+
38
+ const caseViewingAccess = (c: ViewingContext): CaseViewingAccess =>
39
+ caseViewingAccessShared(c, INFORMATION_SCOPE_V4);
40
+ const recordViewing = (
41
+ a: CaseViewingAccess,
42
+ r: ViewingRecord,
43
+ v: string | null | undefined,
44
+ ) => recordViewingShared(a, r, v, INFORMATION_SCOPE_V4);
45
+
46
+ const VIEWER = "user-viewer";
47
+
48
+ function ctx(over: Partial<ViewingContext> = {}): ViewingContext {
49
+ return {
50
+ canSeeCase: true,
51
+ ownedByViewer: false,
52
+ level: 3,
53
+ whitelist: { informationScope: ["system_info"], scopeVocab: 5 },
54
+ ...over,
55
+ };
56
+ }
57
+
58
+ function l3(
59
+ list: readonly string[],
60
+ scopeVocab: number = 5,
61
+ over: Partial<ViewingContext> = {},
62
+ ): CaseViewingAccess {
63
+ return caseViewingAccess(
64
+ ctx({ whitelist: { informationScope: list, scopeVocab }, ...over }),
65
+ );
66
+ }
67
+
68
+ function sees(
69
+ access: CaseViewingAccess,
70
+ record: ViewingRecord,
71
+ viewer: string | null = VIEWER,
72
+ ): boolean {
73
+ return recordViewing(access, record, viewer).visible;
74
+ }
75
+
76
+ const ALL_KINDS = ["client", "offenders", "family", "others"] as const;
77
+
78
+ // ─── § 5 row 1 — level 1 (search) ─────────────────────────────────────────────
79
+
80
+ describe("§ 5 row 1 — internal viewer, level 1 (search)", () => {
81
+ const access = caseViewingAccess(ctx({ level: 1 }));
82
+
83
+ it("surfaces the case as the stub on search only", () => {
84
+ expect(access).toEqual({ mode: "stub", level: 1 });
85
+ expect(caseSurfacesAsStub(access)).toBe(true);
86
+ expect(caseSurfacesOn(access, "search")).toBe(true);
87
+ expect(caseSurfacesOn(access, "autocomplete")).toBe(false);
88
+ expect(caseSurfacesOn(access, "open")).toBe(false);
89
+ });
90
+
91
+ it("never opens a record — not even another person's name", () => {
92
+ for (const kind of ALL_KINDS) {
93
+ expect(
94
+ recordViewing(access, { homeRow: "names", subjectKind: kind }, VIEWER),
95
+ ).toEqual({ visible: false, reason: "not_opened" });
96
+ }
97
+ });
98
+
99
+ it("ignores the whitelist below level 3 (levels 1 and 2 carry no data-type dimension)", () => {
100
+ const wide = caseViewingAccess(
101
+ ctx({
102
+ level: 1,
103
+ whitelist: { informationScope: ["primary_client"], scopeVocab: 5 },
104
+ }),
105
+ );
106
+ expect(wide).toEqual({ mode: "stub", level: 1 });
107
+ });
108
+ });
109
+
110
+ // ─── § 5 row 2 — level 2 (autocomplete) ───────────────────────────────────────
111
+
112
+ describe("§ 5 row 2 — internal viewer, level 2 (autocomplete)", () => {
113
+ const access = caseViewingAccess(ctx({ level: 2 }));
114
+
115
+ it("surfaces the same stub on search and autocomplete, never opens", () => {
116
+ expect(access).toEqual({ mode: "stub", level: 2 });
117
+ expect(caseSurfacesOn(access, "search")).toBe(true);
118
+ expect(caseSurfacesOn(access, "autocomplete")).toBe(true);
119
+ expect(caseSurfacesOn(access, "open")).toBe(false);
120
+ expect(
121
+ recordViewing(
122
+ access,
123
+ { homeRow: "health_status", subjectKind: "client" },
124
+ VIEWER,
125
+ ).visible,
126
+ ).toBe(false);
127
+ });
128
+ });
129
+
130
+ // ─── § 5 row 3 — level 3 (case components) ────────────────────────────────────
131
+
132
+ describe("§ 5 row 3 — internal viewer, level 3 (case components)", () => {
133
+ it("opens the case", () => {
134
+ const access = l3(["system_info", "health_accommodation"]);
135
+ expect(access.mode).toBe("whitelist");
136
+ expect(caseSurfacesOn(access, "open")).toBe(true);
137
+ expect(caseSurfacesOn(access, "autocomplete")).toBe(true);
138
+ });
139
+
140
+ it("surfaces on search / autocomplete as a case row, not the stub (canon L248233; V6)", () => {
141
+ // Level 3 is never the stub. The row's fields go through the whitelist on the
142
+ // wire (viewingProjection.ts), not here.
143
+ const access = l3(["system_info"]);
144
+ expect(caseSurfacesOn(access, "search")).toBe(true);
145
+ expect(caseSurfacesAsStub(access)).toBe(false);
146
+ });
147
+
148
+ it("a Health whitelist shows the client's health AND a child's (every person on the record)", () => {
149
+ const access = l3(["system_info", "health_accommodation"]);
150
+ for (const kind of ALL_KINDS) {
151
+ expect(
152
+ sees(access, { homeRow: "health_status", subjectKind: kind }),
153
+ ).toBe(true);
154
+ expect(
155
+ sees(access, { homeRow: "accommodation_needs", subjectKind: kind }),
156
+ ).toBe(true);
157
+ }
158
+ });
159
+
160
+ it("a sub-category whitelist (health_status) covers that sub-category under every person", () => {
161
+ const access = l3(["system_info", "health_status"]);
162
+ expect(
163
+ sees(access, { homeRow: "health_status", subjectKind: "family" }),
164
+ ).toBe(true);
165
+ expect(
166
+ sees(access, { homeRow: "health_status", subjectKind: "offenders" }),
167
+ ).toBe(true);
168
+ expect(
169
+ sees(access, { homeRow: "accommodation_needs", subjectKind: "family" }),
170
+ ).toBe(false);
171
+ });
172
+
173
+ it("shows nothing the whitelist does not name (deny by default)", () => {
174
+ const access = l3(["system_info", "health_accommodation"]);
175
+ expect(
176
+ sees(access, { homeRow: "victimization", subjectKind: "client" }),
177
+ ).toBe(false);
178
+ expect(sees(access, { homeRow: "addresses", subjectKind: "client" })).toBe(
179
+ false,
180
+ );
181
+ expect(sees(access, { homeRow: "case_notes", subjectKind: "client" })).toBe(
182
+ false,
183
+ );
184
+ expect(
185
+ recordViewing(
186
+ access,
187
+ { homeRow: "victimization", subjectKind: "client" },
188
+ VIEWER,
189
+ ),
190
+ ).toEqual({ visible: false, reason: "not_covered" });
191
+ });
192
+
193
+ it("an Identifying whitelist shows another person's names under their kind", () => {
194
+ const access = l3(["system_info", "identifying"]);
195
+ for (const kind of ALL_KINDS) {
196
+ expect(sees(access, { homeRow: "names", subjectKind: kind })).toBe(true);
197
+ expect(
198
+ sees(access, { homeRow: "identifying.other", subjectKind: kind }),
199
+ ).toBe(true);
200
+ }
201
+ });
202
+
203
+ it("always shows the client's stub rows and system info, even on an empty (deny-all) whitelist", () => {
204
+ const access = l3([]);
205
+ expect(
206
+ recordViewing(
207
+ access,
208
+ { homeRow: "names", subjectKind: "client" },
209
+ VIEWER,
210
+ ),
211
+ ).toEqual({ visible: true, reason: "stub_row" });
212
+ expect(sees(access, { homeRow: "dob", subjectKind: "client" })).toBe(true);
213
+ expect(
214
+ sees(access, { homeRow: "system_info", subjectKind: "client" }),
215
+ ).toBe(true);
216
+ expect(
217
+ sees(access, { homeRow: "system_info", subjectKind: "offenders" }),
218
+ ).toBe(true);
219
+ });
220
+
221
+ it("never treats another person's name as the stub", () => {
222
+ const access = l3([]);
223
+ for (const kind of ["offenders", "family", "others"] as const) {
224
+ expect(
225
+ recordViewing(access, { homeRow: "names", subjectKind: kind }, VIEWER),
226
+ ).toEqual({ visible: false, reason: "not_covered" });
227
+ expect(sees(access, { homeRow: "dob", subjectKind: kind })).toBe(false);
228
+ }
229
+ });
230
+
231
+ it("a per-kind, person-type or other_named_persons code covers nothing (no per-kind viewing)", () => {
232
+ for (const code of [
233
+ "offenders.risk",
234
+ "offenders",
235
+ "family.health_accommodation",
236
+ "other_named_persons",
237
+ ]) {
238
+ const access = l3(["system_info", code]);
239
+ for (const kind of ALL_KINDS) {
240
+ for (const homeRow of ["victimization", "health_status", "names"]) {
241
+ const decision = recordViewing(
242
+ access,
243
+ { homeRow, subjectKind: kind },
244
+ VIEWER,
245
+ );
246
+ if (kind === "client" && homeRow === "names") {
247
+ expect(decision.reason).toBe("stub_row");
248
+ } else {
249
+ expect(decision).toEqual({ visible: false, reason: "not_covered" });
250
+ }
251
+ }
252
+ }
253
+ }
254
+ });
255
+
256
+ it("is symmetric across persons: what one kind sees, every kind sees", () => {
257
+ for (const list of [["risk"], ["victimization"], ["primary_client"]]) {
258
+ const access = l3(["system_info", ...list]);
259
+ const seen = ALL_KINDS.map((kind) =>
260
+ sees(access, { homeRow: "victimization", subjectKind: kind }),
261
+ );
262
+ expect(seen).toEqual([true, true, true, true]);
263
+ }
264
+ });
265
+
266
+ it("refuses an unknown home row or a per-kind code passed as a home (fails closed)", () => {
267
+ const access = l3(["primary_client", "other_named_persons", "system_info"]);
268
+ expect(
269
+ recordViewing(
270
+ access,
271
+ { homeRow: "no_such_row", subjectKind: "client" },
272
+ VIEWER,
273
+ ),
274
+ ).toEqual({ visible: false, reason: "unknown_row" });
275
+ expect(
276
+ recordViewing(
277
+ access,
278
+ { homeRow: "offenders.risk", subjectKind: "offenders" },
279
+ VIEWER,
280
+ ),
281
+ ).toEqual({ visible: false, reason: "unknown_row" });
282
+ // A retired v3 code is not a live home either.
283
+ expect(sees(access, { homeRow: "hiv_status", subjectKind: "client" })).toBe(
284
+ false,
285
+ );
286
+ });
287
+
288
+ it("with NO viewing policy on file renders every component (Crysta 2026-11-03; canon L259150)", () => {
289
+ const access = caseViewingAccess(ctx({ whitelist: null }));
290
+ expect(access).toEqual({ mode: "full", reason: "no_viewing_policy" });
291
+ for (const homeRow of [
292
+ "victimization",
293
+ "safe_locations",
294
+ "case_notes",
295
+ "summary_ida",
296
+ ]) {
297
+ expect(sees(access, { homeRow, subjectKind: "client" })).toBe(true);
298
+ }
299
+ for (const surface of ["search", "autocomplete", "open"] as const) {
300
+ expect(caseSurfacesOn(access, surface)).toBe(true);
301
+ }
302
+ });
303
+
304
+ it("no policy never raises a role below level 3: the role bound still stands", () => {
305
+ expect(caseViewingAccess(ctx({ level: 0, whitelist: null }))).toEqual({
306
+ mode: "none",
307
+ reason: "level_0",
308
+ });
309
+ expect(caseViewingAccess(ctx({ level: 2, whitelist: null }))).toEqual({
310
+ mode: "stub",
311
+ level: 2,
312
+ });
313
+ });
314
+
315
+ it("an empty list is a deliberate deny-all, unlike no policy (canon L258645)", () => {
316
+ const access = l3([]);
317
+ expect(access.mode).toBe("whitelist");
318
+ expect(
319
+ sees(access, { homeRow: "victimization", subjectKind: "client" }),
320
+ ).toBe(false);
321
+ expect(
322
+ sees(access, { homeRow: "safe_locations", subjectKind: "client" }),
323
+ ).toBe(false);
324
+ expect(sees(access, { homeRow: "names", subjectKind: "client" })).toBe(
325
+ true,
326
+ );
327
+ expect(
328
+ sees(access, { homeRow: "system_info", subjectKind: "family" }),
329
+ ).toBe(true);
330
+ });
331
+ });
332
+
333
+ // ─── WI-4 — off by default is ignored on viewing ──────────────────────────────
334
+
335
+ describe("WI-4 — off by default does not apply to viewing", () => {
336
+ const r = INFORMATION_SCOPE_V4;
337
+
338
+ it("a Health whitelist shows health_status — the row the HIV-era codes merged into", () => {
339
+ const access = l3(["system_info", "health_accommodation"]);
340
+ expect(
341
+ sees(access, { homeRow: "health_status", subjectKind: "client" }),
342
+ ).toBe(true);
343
+ });
344
+
345
+ it("a stored v3 whitelist naming hiv_status (off by default in v3) reads as health_status and shows it", () => {
346
+ const access = l3(["system_info", "hiv_status"], 3);
347
+ expect(access.mode).toBe("whitelist");
348
+ if (access.mode !== "whitelist") return;
349
+ expect(access.reading.informationScope).toContain("health_status");
350
+ expect(
351
+ sees(access, { homeRow: "health_status", subjectKind: "client" }),
352
+ ).toBe(true);
353
+ expect(
354
+ sees(access, { homeRow: "health_status", subjectKind: "family" }),
355
+ ).toBe(true);
356
+ });
357
+
358
+ it("shows rows that are off by default for sharing when whitelisted, with no enablement", () => {
359
+ const offRows = [
360
+ "immigration_status",
361
+ "immigration_applications",
362
+ "full_ida",
363
+ ];
364
+ for (const code of offRows) {
365
+ // Precondition: really off by default for sharing, and not shareable un-enabled.
366
+ expect(r.row(code)?.shareableDefault).toBe(false);
367
+ expect(r.isIncludedOnShare(["system_info", "primary_client"], code)).toBe(
368
+ false,
369
+ );
370
+ }
371
+ const access = l3([
372
+ "system_info",
373
+ "immigration_legal_status",
374
+ "instrument_full",
375
+ ]);
376
+ expect(
377
+ sees(access, { homeRow: "immigration_status", subjectKind: "client" }),
378
+ ).toBe(true);
379
+ expect(
380
+ sees(access, {
381
+ homeRow: "immigration_applications",
382
+ subjectKind: "others",
383
+ }),
384
+ ).toBe(true);
385
+ expect(sees(access, { homeRow: "full_ida", subjectKind: "client" })).toBe(
386
+ true,
387
+ );
388
+ });
389
+ });
390
+
391
+ // ─── Crysta 2026-11-03 — the floor is a sharing clamp, not a viewing rule ─────
392
+
393
+ describe("Safe & confidential locations on the viewing axis", () => {
394
+ it("are an ordinary row of the contact category: a whitelist covering it shows them, with no role", () => {
395
+ for (const list of [["system_info", "contact"], ["safe_locations"]]) {
396
+ const access = l3(list);
397
+ for (const kind of ALL_KINDS) {
398
+ expect(
399
+ recordViewing(
400
+ access,
401
+ { homeRow: "safe_locations", subjectKind: kind },
402
+ VIEWER,
403
+ ),
404
+ ).toEqual({ visible: true, reason: "covered" });
405
+ }
406
+ }
407
+ });
408
+
409
+ it("are hidden when the whitelist does not cover them", () => {
410
+ const access = l3(["system_info", "health_accommodation", "contact_info"]);
411
+ expect(
412
+ recordViewing(
413
+ access,
414
+ { homeRow: "safe_locations", subjectKind: "client" },
415
+ VIEWER,
416
+ ),
417
+ ).toEqual({ visible: false, reason: "not_covered" });
418
+ });
419
+
420
+ it("is visible on a case the viewer owns", () => {
421
+ const access = caseViewingAccess(ctx({ ownedByViewer: true }));
422
+ expect(
423
+ sees(access, { homeRow: "safe_locations", subjectKind: "client" }),
424
+ ).toBe(true);
425
+ });
426
+ });
427
+
428
+ // ─── § 5 row 4 — the author ───────────────────────────────────────────────────
429
+
430
+ describe("§ 5 row 4 — the author always sees their own record", () => {
431
+ const own: ViewingRecord = {
432
+ homeRow: "victimization",
433
+ subjectKind: "client",
434
+ authorUserId: VIEWER,
435
+ };
436
+
437
+ it("at every level and mode on a case they can see, even where the whitelist would hide it", () => {
438
+ const accesses: CaseViewingAccess[] = [
439
+ caseViewingAccess(ctx({ level: 0 })),
440
+ caseViewingAccess(ctx({ level: 1 })),
441
+ caseViewingAccess(ctx({ level: 2 })),
442
+ l3([]),
443
+ l3(["system_info", "contact"]),
444
+ ];
445
+ for (const access of accesses) {
446
+ expect(recordViewing(access, own, VIEWER)).toEqual({
447
+ visible: true,
448
+ reason: "author",
449
+ });
450
+ }
451
+ });
452
+
453
+ it("but NOT on a case they cannot see: row 5 is checked before row 4 (fail closed, V2)", () => {
454
+ for (const level of [0, 1, 2, 3] as const) {
455
+ const access = caseViewingAccess(
456
+ ctx({ canSeeCase: false, ownedByViewer: true, level }),
457
+ );
458
+ expect(recordViewing(access, own, VIEWER)).toEqual({
459
+ visible: false,
460
+ reason: "cannot_see_case",
461
+ });
462
+ }
463
+ });
464
+
465
+ it("including their own safe-locations record", () => {
466
+ expect(
467
+ recordViewing(
468
+ l3(["contact"]),
469
+ {
470
+ homeRow: "safe_locations",
471
+ subjectKind: "client",
472
+ authorUserId: VIEWER,
473
+ },
474
+ VIEWER,
475
+ ).reason,
476
+ ).toBe("author");
477
+ });
478
+
479
+ it("an authorless record or an anonymous viewer is nobody's", () => {
480
+ const access = l3([]);
481
+ expect(sees(access, { ...own, authorUserId: null })).toBe(false);
482
+ expect(sees(access, { ...own, authorUserId: "" }, "")).toBe(false);
483
+ expect(sees(access, { ...own, authorUserId: " " }, " ")).toBe(false);
484
+ expect(sees(access, own, null)).toBe(false);
485
+ expect(sees(access, { ...own, authorUserId: "someone-else" })).toBe(false);
486
+ });
487
+ });
488
+
489
+ // ─── § 5 row 5 — cannot see the case ──────────────────────────────────────────
490
+
491
+ describe("§ 5 row 5 — someone who cannot see the case sees nothing on it", () => {
492
+ it("whatever their level, ownership flag or whitelist", () => {
493
+ for (const level of [0, 1, 2, 3] as const) {
494
+ const access = caseViewingAccess(
495
+ ctx({
496
+ canSeeCase: false,
497
+ ownedByViewer: true,
498
+ level,
499
+ whitelist: null,
500
+ }),
501
+ );
502
+ expect(access).toEqual({ mode: "none", reason: "cannot_see_case" });
503
+ for (const surface of ["search", "autocomplete", "open"] as const) {
504
+ expect(caseSurfacesOn(access, surface)).toBe(false);
505
+ }
506
+ expect(
507
+ recordViewing(
508
+ access,
509
+ { homeRow: "names", subjectKind: "client" },
510
+ VIEWER,
511
+ ),
512
+ ).toEqual({ visible: false, reason: "cannot_see_case" });
513
+ expect(
514
+ sees(access, { homeRow: "system_info", subjectKind: "client" }),
515
+ ).toBe(false);
516
+ }
517
+ });
518
+
519
+ it("level 0 (none of the three level functions) sees nothing of a non-owned case", () => {
520
+ const access = caseViewingAccess(ctx({ level: 0 }));
521
+ expect(access).toEqual({ mode: "none", reason: "level_0" });
522
+ expect(caseSurfacesOn(access, "search")).toBe(false);
523
+ expect(sees(access, { homeRow: "names", subjectKind: "client" })).toBe(
524
+ false,
525
+ );
526
+ });
527
+
528
+ it("an owned case is fully visible at any level", () => {
529
+ const access = caseViewingAccess(ctx({ ownedByViewer: true, level: 0 }));
530
+ expect(access).toEqual({ mode: "full", reason: "owned" });
531
+ expect(
532
+ sees(access, { homeRow: "full_ida", subjectKind: "offenders" }),
533
+ ).toBe(true);
534
+ });
535
+ });
536
+
537
+ // ─── Stored whitelists — v3 read through the policy subject ───────────────────
538
+
539
+ describe("stored whitelists — read as a policy (successor whole, dated version row due)", () => {
540
+ it("a stamp-3 list takes the successor and flags the version row", () => {
541
+ const access = l3(["system_info", "offender_facilitator"], 3);
542
+ if (access.mode !== "whitelist") throw new Error("expected whitelist");
543
+ expect(access.oneHomeCarry).toBe(true);
544
+ expect(access.reading.versionRowRequired).toBe(true);
545
+ expect(access.reading.subject).toBe("policy");
546
+ expect(access.reading.retained).toEqual([]);
547
+ expect(access.reading.informationScope).toEqual(
548
+ expect.arrayContaining(["offenders.identifying", "offenders.risk"]),
549
+ );
550
+ // The successor is per-kind, and a per-kind code covers nothing on the
551
+ // viewing axis: a v3 `offender_facilitator` whitelist LOSES the offender
552
+ // rows it saw under v3 (a narrowing, never a widening — spec-feedback V3).
553
+ for (const kind of ALL_KINDS) {
554
+ expect(
555
+ sees(access, { homeRow: "victimization", subjectKind: kind }),
556
+ ).toBe(false);
557
+ }
558
+ expect(sees(access, { homeRow: "names", subjectKind: "offenders" })).toBe(
559
+ false,
560
+ );
561
+ });
562
+
563
+ it("a stamp-5 list (canon's v4 vocabulary) reads as itself, no version row", () => {
564
+ const access = l3(["system_info", "risk"], 5);
565
+ if (access.mode !== "whitelist") throw new Error("expected whitelist");
566
+ expect(access.oneHomeCarry).toBe(false);
567
+ expect(access.reading.versionRowRequired).toBe(false);
568
+ });
569
+
570
+ it("an unsupported or absent stamp reads nothing but the stub (fails closed)", () => {
571
+ for (const v of [null, 2, 6]) {
572
+ const access = caseViewingAccess(
573
+ ctx({
574
+ whitelist: { informationScope: ["primary_client"], scopeVocab: v },
575
+ }),
576
+ );
577
+ if (access.mode !== "whitelist") throw new Error("expected whitelist");
578
+ expect(access.reading.unsupportedVersion).toBe(true);
579
+ expect(access.oneHomeCarry).toBe(false);
580
+ expect(
581
+ sees(access, { homeRow: "victimization", subjectKind: "client" }),
582
+ ).toBe(false);
583
+ expect(sees(access, { homeRow: "names", subjectKind: "client" })).toBe(
584
+ true,
585
+ );
586
+ }
587
+ });
588
+
589
+ it("NO LEGACY DATA: an unstamped whitelist is unsupported and grants nothing (shared unstampedReading seam)", () => {
590
+ // Ruling 2026-10-10: nothing has shipped, so an unstamped list is never a
591
+ // legacy list to migrate — it reads through the ONE unstamped rule.
592
+ for (const v of [undefined, null, "4" as unknown as number]) {
593
+ const access = caseViewingAccess(
594
+ ctx({
595
+ whitelist: {
596
+ informationScope: ["primary_client", "instruments", "contact"],
597
+ scopeVocab: v,
598
+ },
599
+ }),
600
+ );
601
+ if (access.mode !== "whitelist") throw new Error("expected whitelist");
602
+ expect(access.reading.unsupportedVersion).toBe(true);
603
+ // Only System metadata, which every list carries (handoff § 2 rule 1).
604
+ expect(access.reading.informationScope).toEqual(["system_info"]);
605
+ expect(access.oneHomeCarry).toBe(false);
606
+ for (const homeRow of [
607
+ "victimization",
608
+ "health_status",
609
+ "case_notes",
610
+ "summary_ida",
611
+ ]) {
612
+ expect(sees(access, { homeRow, subjectKind: "client" })).toBe(false);
613
+ }
614
+ // Only the client's stub rows survive (the header identity floor).
615
+ expect(sees(access, { homeRow: "names", subjectKind: "client" })).toBe(
616
+ true,
617
+ );
618
+ }
619
+ });
620
+
621
+ it("a null stored list is deny-all, not unconfigured", () => {
622
+ const access = caseViewingAccess(
623
+ ctx({ whitelist: { informationScope: null, scopeVocab: 5 } }),
624
+ );
625
+ expect(access.mode).toBe("whitelist");
626
+ expect(
627
+ sees(access, { homeRow: "victimization", subjectKind: "client" }),
628
+ ).toBe(false);
629
+ });
630
+ });
631
+
632
+ // ─── INSTRUMENTS § 14.1 ruling 5 — the pre-v4 ONE-HOME carry ──────────────────
633
+
634
+ describe("ONE-HOME carry — a pre-v4 whitelist keeps the IDA determination / needs result", () => {
635
+ const ida: ViewingRecord = {
636
+ homeRow: "summary_ida",
637
+ subjectKind: "client",
638
+ domain: "ida_determination",
639
+ };
640
+ const needs: ViewingRecord = {
641
+ homeRow: "summary_needs_assessment",
642
+ subjectKind: "client",
643
+ domain: "needs_assessment",
644
+ };
645
+ const followup: ViewingRecord = { ...needs, domain: "recommended_followup" };
646
+
647
+ it("risk on a stamp-3 list unlocks the IDA determination only (canon L259192)", () => {
648
+ for (const list of [["risk"]]) {
649
+ const access = l3(["system_info", ...list], 3);
650
+ expect(recordViewing(access, ida, VIEWER)).toEqual({
651
+ visible: true,
652
+ reason: "one_home_carry",
653
+ });
654
+ // Domain grain: the rest of the IDA summary row and other instruments stay hidden.
655
+ expect(
656
+ sees(access, {
657
+ homeRow: "summary_ida",
658
+ subjectKind: "client",
659
+ domain: "trafficking_risk_assessment",
660
+ }),
661
+ ).toBe(false);
662
+ expect(
663
+ sees(access, { homeRow: "summary_ida", subjectKind: "client" }),
664
+ ).toBe(false);
665
+ expect(sees(access, needs)).toBe(false);
666
+ }
667
+ });
668
+
669
+ it("services on a stamp-3 list unlocks the needs result and follow-up", () => {
670
+ const access = l3(["system_info", "services"], 3);
671
+ expect(sees(access, needs)).toBe(true);
672
+ expect(sees(access, followup)).toBe(true);
673
+ expect(sees(access, ida)).toBe(false);
674
+ });
675
+
676
+ it("canon reads the category: a list naming only a sub-category carries nothing", () => {
677
+ const access = l3(["system_info", "victimization", "service_history"], 3);
678
+ expect(sees(access, ida)).toBe(false);
679
+ expect(sees(access, needs)).toBe(false);
680
+ });
681
+
682
+ it("applies under every person on the record", () => {
683
+ const access = l3(["system_info", "risk"], 3);
684
+ expect(sees(access, { ...ida, subjectKind: "family" })).toBe(true);
685
+ });
686
+
687
+ it("does not apply to a v4 list (stamp 5, read as it is)", () => {
688
+ const access = l3(["system_info", "risk", "services"], 5);
689
+ expect(sees(access, ida)).toBe(false);
690
+ expect(sees(access, needs)).toBe(false);
691
+ });
692
+
693
+ it("is moot when the list covers Screens & assessments", () => {
694
+ const access = l3(["system_info", "instrument_summary"], 3);
695
+ expect(recordViewing(access, ida, VIEWER).reason).toBe("covered");
696
+ });
697
+ });
698
+
699
+ // ─── The effective level (CVC-133 logic_notes) ────────────────────────────────
700
+
701
+ // ─── Fail-closed on out-of-type input (review of pv-p7authz-infoscope-v4-viewing) ──
702
+
703
+ describe("fail-closed ladder — out-of-type inputs never reach a wider branch", () => {
704
+ // The caller's types say boolean / 0..3, but these values arrive from
705
+ // stored config and JSON; each must land on the NARROWEST branch.
706
+ const asCtx = (over: Record<string, unknown>): ViewingContext =>
707
+ ({ ...ctx(), ...over }) as unknown as ViewingContext;
708
+
709
+ it("a level that is not exactly 0..3 is level 0, never the whitelist", () => {
710
+ for (const level of [
711
+ undefined,
712
+ null,
713
+ NaN,
714
+ "1",
715
+ "3",
716
+ 1.5,
717
+ 2.5,
718
+ 4,
719
+ -1,
720
+ Infinity,
721
+ ]) {
722
+ expect(caseViewingAccess(asCtx({ level }))).toEqual({
723
+ mode: "none",
724
+ reason: "level_0",
725
+ });
726
+ }
727
+ });
728
+
729
+ it("canSeeCase that is not exactly true sees nothing", () => {
730
+ for (const canSeeCase of ["false", "true", 1, undefined, null, {}]) {
731
+ expect(
732
+ caseViewingAccess(asCtx({ canSeeCase, ownedByViewer: true })),
733
+ ).toEqual({ mode: "none", reason: "cannot_see_case" });
734
+ }
735
+ });
736
+
737
+ it("ownedByViewer that is not exactly true is not owned", () => {
738
+ for (const ownedByViewer of ["false", "true", 1, {}]) {
739
+ const access = caseViewingAccess(asCtx({ ownedByViewer, level: 1 }));
740
+ expect(access).toEqual({ mode: "stub", level: 1 });
741
+ }
742
+ });
743
+
744
+ it("an absent (undefined) whitelist is out-of-type, not `no policy`: it reads as empty", () => {
745
+ const access = caseViewingAccess(asCtx({ whitelist: undefined }));
746
+ expect(access.mode).toBe("whitelist");
747
+ expect(
748
+ sees(access, { homeRow: "victimization", subjectKind: "client" }),
749
+ ).toBe(false);
750
+ });
751
+ });
752
+
753
+ // ─── Canon's viewing-policy vocabulary stamp (pv-p7authz-viewing-stamp5-scope-vocab) ──
754
+ //
755
+ // The stored `scopeVocab` is canon's OWN counter for the Internal Viewing tab's
756
+ // vocabulary, not the CVC-236 tree version: the hub stamps 5 for the four-level
757
+ // v4 tree (platform-prototype `src/screens.jsx` setLevel / toggleGroup / setAcctLevel
758
+ // "INFOSCOPE-V4-BUILD-2026-10-10: authored on vocabulary 5"), 4 for ONE-HOME and 3 for
759
+ // the Instruments catalog. Canon's reader (`recordOpenAccess`, pin 462c8a24): the
760
+ // ONE-HOME carry at `scopeVocab < 4` (L259192) and the v4 alias at `scopeVocab < 5`
761
+ // (L259231-L259234).
762
+
763
+ describe("viewingPolicyVocabulary — canon's stamp, mapped onto the resolver's tree", () => {
764
+ it("reads 3, 4 and 5 and nothing else", () => {
765
+ expect(viewingPolicyVocabulary(3)).toEqual({
766
+ scopeVersion: 3,
767
+ oneHomeCarry: true,
768
+ identifyingAlias: true,
769
+ });
770
+ expect(viewingPolicyVocabulary(4)).toEqual({
771
+ scopeVersion: 3,
772
+ oneHomeCarry: false,
773
+ identifyingAlias: true,
774
+ });
775
+ expect(viewingPolicyVocabulary(5)).toEqual({
776
+ scopeVersion: 4,
777
+ oneHomeCarry: false,
778
+ identifyingAlias: false,
779
+ });
780
+ for (const stamp of [
781
+ 0,
782
+ 1,
783
+ 2,
784
+ 6,
785
+ 7,
786
+ 100,
787
+ 4.5,
788
+ -5,
789
+ NaN,
790
+ "5",
791
+ null,
792
+ undefined,
793
+ ]) {
794
+ expect(viewingPolicyVocabulary(stamp)).toBeNull();
795
+ }
796
+ });
797
+ });
798
+
799
+ describe("stored whitelists — canon's vocabulary stamps 3, 4 and 5", () => {
800
+ function atVocab(
801
+ list: readonly string[],
802
+ scopeVocab: unknown,
803
+ ): CaseViewingAccess {
804
+ return caseViewingAccess(
805
+ ctx({
806
+ whitelist: {
807
+ informationScope: list,
808
+ scopeVocab,
809
+ } as unknown as ViewingContext["whitelist"],
810
+ }),
811
+ );
812
+ }
813
+ const household: ViewingRecord = {
814
+ homeRow: "relationships_household",
815
+ subjectKind: "client",
816
+ };
817
+ const dynamics: ViewingRecord = {
818
+ homeRow: "victimization",
819
+ subjectKind: "client",
820
+ domain: "relationship_dynamics",
821
+ };
822
+ const victimStatus: ViewingRecord = {
823
+ homeRow: "victimization",
824
+ subjectKind: "client",
825
+ domain: "victim_status",
826
+ };
827
+ const ida: ViewingRecord = {
828
+ homeRow: "summary_ida",
829
+ subjectKind: "client",
830
+ domain: "ida_determination",
831
+ };
832
+
833
+ it("a stamp-5 list is the v4 tree read literally: no version row, no alias", () => {
834
+ const access = atVocab(
835
+ ["system_info", "relationships_household", "health_status"],
836
+ 5,
837
+ );
838
+ if (access.mode !== "whitelist") throw new Error("expected whitelist");
839
+ expect(access.reading.unsupportedVersion).toBe(false);
840
+ expect(access.reading.storedVersion).toBe(4);
841
+ expect(access.reading.versionRowRequired).toBe(false);
842
+ expect(access.reading.unknown).toEqual([]);
843
+ expect(sees(access, household)).toBe(true);
844
+ expect(
845
+ sees(access, { homeRow: "health_status", subjectKind: "client" }),
846
+ ).toBe(true);
847
+ });
848
+
849
+ it("stamp 5 does NOT alias identifying (canon: scopeVocab < 5 only)", () => {
850
+ const access = atVocab(["system_info", "identifying"], 5);
851
+ expect(sees(access, household)).toBe(false);
852
+ expect(sees(access, dynamics)).toBe(false);
853
+ expect(sees(access, { homeRow: "addresses", subjectKind: "client" })).toBe(
854
+ true,
855
+ );
856
+ });
857
+
858
+ it.each([3, 4])(
859
+ "stamp %i: identifying opens Relationships & household at category grain (L259232)",
860
+ (stamp) => {
861
+ const access = atVocab(["system_info", "identifying"], stamp);
862
+ if (access.mode !== "whitelist") throw new Error("expected whitelist");
863
+ expect(access.reading.storedVersion).toBe(3);
864
+ expect(access.reading.versionRowRequired).toBe(true);
865
+ expect(recordViewing(access, household, VIEWER)).toEqual({
866
+ visible: true,
867
+ reason: "covered",
868
+ });
869
+ expect(sees(access, { ...household, subjectKind: "offenders" })).toBe(
870
+ true,
871
+ );
872
+ },
873
+ );
874
+
875
+ it.each([3, 4])(
876
+ "stamp %i: identifying without risk carries relationship_dynamics at DOMAIN grain (L259233)",
877
+ (stamp) => {
878
+ const access = atVocab(["system_info", "identifying"], stamp);
879
+ expect(recordViewing(access, dynamics, VIEWER)).toEqual({
880
+ visible: true,
881
+ reason: "identifying_alias_carry",
882
+ });
883
+ // Never a category widening: the rest of Victimization records stays hidden.
884
+ expect(sees(access, victimStatus)).toBe(false);
885
+ expect(
886
+ sees(access, { homeRow: "victimization", subjectKind: "client" }),
887
+ ).toBe(false);
888
+ },
889
+ );
890
+
891
+ it("stamp 4 with identifying AND risk: the dynamic is covered by risk itself", () => {
892
+ const access = atVocab(["system_info", "identifying", "risk"], 4);
893
+ expect(recordViewing(access, dynamics, VIEWER)).toEqual({
894
+ visible: true,
895
+ reason: "covered",
896
+ });
897
+ expect(sees(access, household)).toBe(true);
898
+ });
899
+
900
+ it("the alias needs identifying itself: a list without it opens neither", () => {
901
+ for (const stamp of [3, 4]) {
902
+ const access = atVocab(["system_info", "contact", "names"], stamp);
903
+ expect(sees(access, household)).toBe(false);
904
+ expect(sees(access, dynamics)).toBe(false);
905
+ }
906
+ });
907
+
908
+ it("the ONE-HOME carry is stamp 3 only (scopeVocab < 4, L259192); stamp 4 reads risk as it is", () => {
909
+ expect(sees(atVocab(["system_info", "risk"], 3), ida)).toBe(true);
910
+ expect(sees(atVocab(["system_info", "risk"], 4), ida)).toBe(false);
911
+ expect(sees(atVocab(["system_info", "risk"], 5), ida)).toBe(false);
912
+ });
913
+
914
+ it("a stamp-4 list is read against the v3 tree: a v4-only code is unknown and opens nothing", () => {
915
+ const access = atVocab(["system_info", "relationships_household"], 4);
916
+ if (access.mode !== "whitelist") throw new Error("expected whitelist");
917
+ expect(access.reading.unknown).toEqual(["relationships_household"]);
918
+ expect(sees(access, household)).toBe(false);
919
+ });
920
+
921
+ it.each([1, 2, 6, 7, 99])(
922
+ "stamp %i is unsupported and reads nothing but the stub (fails closed)",
923
+ (stamp) => {
924
+ const access = atVocab(
925
+ ["system_info", "primary_client", "identifying", "risk"],
926
+ stamp,
927
+ );
928
+ if (access.mode !== "whitelist") throw new Error("expected whitelist");
929
+ expect(access.reading.unsupportedVersion).toBe(true);
930
+ expect(access.reading.informationScope).toEqual(["system_info"]);
931
+ expect(sees(access, household)).toBe(false);
932
+ expect(sees(access, dynamics)).toBe(false);
933
+ expect(sees(access, ida)).toBe(false);
934
+ expect(
935
+ sees(access, { homeRow: "addresses", subjectKind: "client" }),
936
+ ).toBe(false);
937
+ expect(sees(access, { homeRow: "names", subjectKind: "client" })).toBe(
938
+ true,
939
+ );
940
+ },
941
+ );
942
+ });
943
+
944
+ // ─── The governing policy → the Level 3 filter (contract § 2 truth table) ────
945
+
946
+ describe("viewingWhitelistFromPolicy → caseViewingAccess (contract § 2, Level 3 rows)", () => {
947
+ const ACCOUNT = "0123456789abcdef01234567";
948
+ const TEAM = "89abcdef0123456789abcdef";
949
+ const ALL_ON = [
950
+ "notes",
951
+ "identifying",
952
+ "contact",
953
+ "health_accommodation",
954
+ "risk",
955
+ "services",
956
+ "instruments",
957
+ "relationships_household",
958
+ ];
959
+ const rowWith = (over: Record<string, unknown>) => ({
960
+ id: `viewpol-${ACCOUNT}`,
961
+ familyId: `viewpol-${ACCOUNT}`,
962
+ version: 1,
963
+ species: "viewing",
964
+ level: 3,
965
+ scopeVocab: 5,
966
+ visibleGroups: ALL_ON,
967
+ assignments: [{ scope: "account" }],
968
+ account_id: ACCOUNT,
969
+ active: true,
970
+ ...over,
971
+ });
972
+ const accessFor = (rows: unknown[], over: Partial<ViewingContext> = {}) => {
973
+ const query = { accountId: ACCOUNT, teamId: TEAM };
974
+ const policy = resolveViewingPolicy(rows, query, INFORMATION_SCOPE_V4);
975
+ return caseViewingAccess(ctx({ whitelist: viewingWhitelistFromPolicy(policy), ...over }));
976
+ };
977
+ const VICTIMIZATION = { homeRow: "victimization", subjectKind: "client" } as const;
978
+ const NAMES = { homeRow: "names", subjectKind: "client" } as const;
979
+
980
+ it("own case: the full record, whatever governs", () => {
981
+ expect(accessFor([rowWith({ visibleGroups: [] })], { ownedByViewer: true })).toEqual({
982
+ mode: "full",
983
+ reason: "owned",
984
+ });
985
+ });
986
+
987
+ it("no row on file: the full record (Level 3, every category)", () => {
988
+ expect(accessFor([])).toEqual({ mode: "full", reason: "no_viewing_policy" });
989
+ });
990
+
991
+ it("every category on: Risk-related shows", () => {
992
+ expect(sees(accessFor([rowWith({})]), VICTIMIZATION)).toBe(true);
993
+ });
994
+
995
+ it("Risk-related off: Risk-related content is hidden, the rest shows", () => {
996
+ const access = accessFor([rowWith({ visibleGroups: ALL_ON.filter((c) => c !== "risk") })]);
997
+ expect(sees(access, VICTIMIZATION)).toBe(false);
998
+ expect(sees(access, { homeRow: "health_status", subjectKind: "client" })).toBe(true);
999
+ });
1000
+
1001
+ it("a stored empty list, or a row with no list: the stub and system information only", () => {
1002
+ for (const visibleGroups of [[], null, undefined]) {
1003
+ const access = accessFor([rowWith({ visibleGroups })]);
1004
+ expect(access.mode).toBe("whitelist");
1005
+ expect(sees(access, VICTIMIZATION)).toBe(false);
1006
+ expect(sees(access, NAMES)).toBe(true);
1007
+ expect(viewingComponentOpen(access, "system_info", INFORMATION_SCOPE_V4)).toBe(true);
1008
+ expect(viewingComponentOpen(access, "contact", INFORMATION_SCOPE_V4)).toBe(false);
1009
+ }
1010
+ });
1011
+
1012
+ it("unavailable: the whitelist reads nothing (and its level 0 shows nothing anyway)", () => {
1013
+ const access = accessFor([rowWith({ level: 7 })]);
1014
+ expect(access.mode).toBe("whitelist");
1015
+ expect(sees(access, VICTIMIZATION)).toBe(false);
1016
+ expect(accessFor([rowWith({ level: 7 })], { level: 0 })).toEqual({ mode: "none", reason: "level_0" });
1017
+ });
1018
+
1019
+ it("Level 2 and Level 1 surface the stub; neither opens", () => {
1020
+ const two = accessFor([rowWith({})], { level: 2 });
1021
+ expect(caseSurfacesOn(two, "autocomplete")).toBe(true);
1022
+ expect(caseSurfacesOn(two, "open")).toBe(false);
1023
+ const one = accessFor([rowWith({})], { level: 1 });
1024
+ expect(caseSurfacesOn(one, "search")).toBe(true);
1025
+ expect(caseSurfacesOn(one, "autocomplete")).toBe(false);
1026
+ expect(caseSurfacesAsStub(one)).toBe(true);
1027
+ });
1028
+
1029
+ it("viewingComponentOpen: full opens everything; a stub opens nothing; a per-kind or retired row never opens", () => {
1030
+ expect(viewingComponentOpen({ mode: "full", reason: "owned" }, "risk", INFORMATION_SCOPE_V4)).toBe(true);
1031
+ expect(viewingComponentOpen({ mode: "stub", level: 2 }, "names", INFORMATION_SCOPE_V4)).toBe(false);
1032
+ const access = accessFor([rowWith({})]);
1033
+ expect(viewingComponentOpen(access, "risk", INFORMATION_SCOPE_V4)).toBe(true);
1034
+ expect(viewingComponentOpen(access, "offenders.risk", INFORMATION_SCOPE_V4)).toBe(false);
1035
+ expect(viewingComponentOpen(access, "hiv_status", INFORMATION_SCOPE_V4)).toBe(false);
1036
+ });
1037
+ });