@htilabs/platform-common-models 0.54.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.
Files changed (41) hide show
  1. package/README.md +90 -0
  2. package/dist/authz/index.cjs +353 -2
  3. package/dist/authz/index.cjs.map +1 -1
  4. package/dist/authz/index.d.cts +330 -9
  5. package/dist/authz/index.d.ts +330 -9
  6. package/dist/authz/index.js +339 -1
  7. package/dist/authz/index.js.map +1 -1
  8. package/dist/{index-XWSYon40.d.cts → index-Bj-s0nZy.d.cts} +1 -1
  9. package/dist/{index-Bh1zO_Vu.d.ts → index-DvAypMJV.d.ts} +1 -1
  10. package/dist/index.cjs +503 -2
  11. package/dist/index.cjs.map +1 -1
  12. package/dist/index.d.cts +4 -4
  13. package/dist/index.d.ts +4 -4
  14. package/dist/index.js +483 -2
  15. package/dist/index.js.map +1 -1
  16. package/dist/models/index.d.cts +2 -2
  17. package/dist/models/index.d.ts +2 -2
  18. package/dist/schemas/index.d.cts +25 -25
  19. package/dist/schemas/index.d.ts +25 -25
  20. package/dist/sharing-ceiling/index.cjs +152 -2
  21. package/dist/sharing-ceiling/index.cjs.map +1 -1
  22. package/dist/sharing-ceiling/index.d.cts +214 -2
  23. package/dist/sharing-ceiling/index.d.ts +214 -2
  24. package/dist/sharing-ceiling/index.js +145 -2
  25. package/dist/sharing-ceiling/index.js.map +1 -1
  26. package/package.json +1 -1
  27. package/src/__tests__/authz-resolve.test.ts +5 -0
  28. package/src/__tests__/authz-viewing-policy.test.ts +685 -0
  29. package/src/__tests__/authz-viewing-scope.test.ts +1037 -0
  30. package/src/__tests__/core-function-default-bounds.test.ts +2 -2
  31. package/src/authz/functionDoor.ts +4 -4
  32. package/src/authz/index.ts +2 -0
  33. package/src/authz/resolveEffectiveFunctions.ts +6 -4
  34. package/src/authz/viewingPolicy.ts +525 -0
  35. package/src/authz/viewingScope.ts +359 -0
  36. package/src/sharingCeiling/__tests__/fireShareEvent.test.ts +437 -0
  37. package/src/sharingCeiling/fireShareEvent.ts +352 -0
  38. package/src/sharingCeiling/index.ts +4 -0
  39. package/src/sharingCeiling/resolve.ts +31 -5
  40. package/dist/{cvcEntry-D787utvP.d.cts → cvcEntry-BLeRivoF.d.cts} +8 -8
  41. package/dist/{cvcEntry-D787utvP.d.ts → cvcEntry-BLeRivoF.d.ts} +8 -8
@@ -0,0 +1,437 @@
1
+ /**
2
+ * Event-driven sharing's pure half (Kickoff 13 item 9a; home ruled
3
+ * 2026-11-01). Contract of record: platform-prototype `src/data.js`
4
+ * `policyIsListener` / `listenersFor` / `fireShareEvent`.
5
+ */
6
+ import { describe, expect, it } from "vitest";
7
+
8
+ import * as root from "../../index.js";
9
+ import {
10
+ SHARE_EVENT,
11
+ SHARE_TRIGGER_EVENTS,
12
+ fireShareEvent,
13
+ firedShareKey,
14
+ policyIsShareListener,
15
+ shareListenersFor,
16
+ shareTriggerLabel,
17
+ type SharePolicyDoc,
18
+ } from "../index.js";
19
+
20
+ const HOTLINE = "team-hotline";
21
+ const SERVICES = "team-services";
22
+ const SHELTER = "team-shelter";
23
+ const PALOMAR = "palomar";
24
+
25
+ /** A listener: ongoing + a trigger, linked Hotline → Services (inside the account). */
26
+ const insideListener: SharePolicyDoc = {
27
+ id: "pol-collab-ongoing",
28
+ familyId: "fam-collab",
29
+ name: "Joint program — keep Services current",
30
+ version: 3,
31
+ purpose: "case_collaboration",
32
+ posture: "open",
33
+ cadences: { ongoing: true, automatic: false },
34
+ trigger: { on: ["sessionSubmitted", "caseCloseRuled"] },
35
+ assignments: [
36
+ {
37
+ scope: "team_pair",
38
+ teamRowId: "tr-hotline-services",
39
+ teamId: HOTLINE,
40
+ partnerId: null,
41
+ with: { type: "team", id: SERVICES },
42
+ },
43
+ ],
44
+ };
45
+
46
+ /** A listener linked Hotline → Palomar (a partner). */
47
+ const partnerListener: SharePolicyDoc = {
48
+ id: "pol-referral-palomar-ongoing",
49
+ name: "Referral — Palomar, on submit",
50
+ purpose: "referral",
51
+ cadences: { ongoing: true },
52
+ trigger: { on: ["sessionSubmitted"] },
53
+ assignments: [
54
+ {
55
+ scope: "team_pair",
56
+ teamRowId: "tr-hotline-palomar",
57
+ teamId: HOTLINE,
58
+ partnerId: PALOMAR,
59
+ },
60
+ ],
61
+ };
62
+
63
+ const submit = (over: Record<string, unknown> = {}) => ({
64
+ event: SHARE_EVENT.SESSION_SUBMITTED,
65
+ teamId: HOTLINE,
66
+ accountId: "acct-1",
67
+ caseId: "case-9",
68
+ sessionId: "sess-1",
69
+ ...over,
70
+ });
71
+
72
+ describe("the trigger catalog", () => {
73
+ it("is the prototype's ten CVC-285 codes, and the apps' two events are in it", () => {
74
+ expect(SHARE_TRIGGER_EVENTS.map((t) => t.code)).toEqual([
75
+ "sessionSubmitted",
76
+ "caseOpened",
77
+ "caseStatusChanged",
78
+ "caseCloseRuled",
79
+ "determinationIssued",
80
+ "serviceLogged",
81
+ "noteAdded",
82
+ "shareClaimed",
83
+ "referralClaimed",
84
+ "shareAcknowledged",
85
+ ]);
86
+ expect(SHARE_EVENT.SESSION_SUBMITTED).toBe("sessionSubmitted");
87
+ expect(SHARE_EVENT.CASE_CLOSED).toBe("caseCloseRuled");
88
+ expect(shareTriggerLabel("caseCloseRuled")).toBe("Case closed");
89
+ expect(shareTriggerLabel("not-a-code")).toBe("not-a-code");
90
+ // also on the package root
91
+ expect(root.fireShareEvent).toBe(fireShareEvent);
92
+ });
93
+ });
94
+
95
+ describe("policyIsShareListener — ongoing cadence + a trigger, never a share-back", () => {
96
+ it("needs both the ongoing cadence and a trigger event", () => {
97
+ expect(policyIsShareListener(insideListener)).toBe(true);
98
+ expect(
99
+ policyIsShareListener({
100
+ ...insideListener,
101
+ cadences: { ongoing: false },
102
+ }),
103
+ ).toBe(false);
104
+ expect(policyIsShareListener({ ...insideListener, cadences: null })).toBe(
105
+ false,
106
+ );
107
+ expect(
108
+ policyIsShareListener({ ...insideListener, trigger: { on: [] } }),
109
+ ).toBe(false);
110
+ expect(policyIsShareListener({ ...insideListener, trigger: null })).toBe(
111
+ false,
112
+ );
113
+ expect(policyIsShareListener(null)).toBe(false);
114
+ });
115
+
116
+ it("a retired policy and a share-back policy never listen", () => {
117
+ expect(policyIsShareListener({ ...insideListener, active: false })).toBe(
118
+ false,
119
+ );
120
+ expect(
121
+ policyIsShareListener({
122
+ ...insideListener,
123
+ trigger: { on: ["shareClaimed"], answers: "received" },
124
+ }),
125
+ ).toBe(false);
126
+ });
127
+ });
128
+
129
+ describe("shareListenersFor — the links FROM one team", () => {
130
+ const policies = [insideListener, partnerListener];
131
+
132
+ it("names each listener's policy, row and recipient in the resolver's vocabulary", () => {
133
+ expect(shareListenersFor(policies, HOTLINE)).toEqual([
134
+ {
135
+ policy: {
136
+ id: "pol-collab-ongoing",
137
+ familyId: "fam-collab",
138
+ name: "Joint program — keep Services current",
139
+ version: 3,
140
+ },
141
+ purpose: "case_collaboration",
142
+ fromTeamId: HOTLINE,
143
+ teamRowId: "tr-hotline-services",
144
+ recipient: { kind: "sibling_team", teamId: SERVICES },
145
+ partnerTeamId: null,
146
+ events: ["sessionSubmitted", "caseCloseRuled"],
147
+ },
148
+ {
149
+ policy: {
150
+ id: "pol-referral-palomar-ongoing",
151
+ familyId: "pol-referral-palomar-ongoing",
152
+ name: "Referral — Palomar, on submit",
153
+ version: 1,
154
+ },
155
+ purpose: "referral",
156
+ fromTeamId: HOTLINE,
157
+ teamRowId: "tr-hotline-palomar",
158
+ recipient: { kind: "partner", id: PALOMAR },
159
+ partnerTeamId: null,
160
+ events: ["sessionSubmitted"],
161
+ },
162
+ ]);
163
+ });
164
+
165
+ it("is directional: the receiving team does not listen, nor does any other team", () => {
166
+ expect(shareListenersFor(policies, SERVICES)).toEqual([]);
167
+ expect(shareListenersFor(policies, SHELTER)).toEqual([]);
168
+ expect(shareListenersFor(policies, null)).toEqual([]);
169
+ expect(shareListenersFor(null, HOTLINE)).toEqual([]);
170
+ });
171
+
172
+ it("only team links listen — an account, account-internal, partner or team-default link never does", () => {
173
+ const p: SharePolicyDoc = {
174
+ ...insideListener,
175
+ assignments: [
176
+ { scope: "account" },
177
+ { scope: "account_internal" },
178
+ { scope: "account_partner", partnerId: PALOMAR },
179
+ { scope: "team", teamId: HOTLINE },
180
+ ],
181
+ };
182
+ expect(shareListenersFor([p], HOTLINE)).toEqual([]);
183
+ });
184
+
185
+ it("a link that does not say where it sends is never guessed", () => {
186
+ const p: SharePolicyDoc = {
187
+ ...insideListener,
188
+ assignments: [
189
+ { scope: "team_pair", teamRowId: "tr-x", teamId: HOTLINE },
190
+ { scope: "team_pair", teamRowId: "tr-w", teamId: HOTLINE, with: null },
191
+ {
192
+ scope: "team_pair",
193
+ teamRowId: "tr-y",
194
+ with: { type: "team", id: SERVICES },
195
+ },
196
+ {
197
+ scope: "team_pair",
198
+ teamRowId: "",
199
+ teamId: HOTLINE,
200
+ with: { type: "team", id: SERVICES },
201
+ },
202
+ {
203
+ scope: "team_pair",
204
+ teamRowId: "tr-self",
205
+ teamId: HOTLINE,
206
+ with: { type: "team", id: HOTLINE },
207
+ },
208
+ ],
209
+ };
210
+ expect(shareListenersFor([p], HOTLINE)).toEqual([]);
211
+ // malformed assignments never throw
212
+ expect(
213
+ shareListenersFor(
214
+ [{ ...insideListener, assignments: {} as never }],
215
+ HOTLINE,
216
+ ),
217
+ ).toEqual([]);
218
+ });
219
+
220
+ it("a partner's team rides as partnerTeamId (the Admin Hub's `with`); two links to the same place are one listener", () => {
221
+ const toIntake = {
222
+ scope: "team_pair" as const,
223
+ teamId: HOTLINE,
224
+ partnerId: PALOMAR,
225
+ with: { type: "team", id: "palomar-intake" },
226
+ };
227
+ const p: SharePolicyDoc = {
228
+ ...partnerListener,
229
+ assignments: [
230
+ { ...toIntake, teamRowId: "tr-1" },
231
+ { ...toIntake, teamRowId: "tr-2" },
232
+ {
233
+ scope: "team_pair",
234
+ teamRowId: "tr-3",
235
+ teamId: HOTLINE,
236
+ partnerId: PALOMAR,
237
+ },
238
+ ],
239
+ };
240
+ const ls = shareListenersFor([p], HOTLINE);
241
+ expect(ls.map((l) => [l.teamRowId, l.recipient, l.partnerTeamId])).toEqual([
242
+ ["tr-1", { kind: "partner", id: PALOMAR }, "palomar-intake"],
243
+ ["tr-3", { kind: "partner", id: PALOMAR }, null],
244
+ ]);
245
+ });
246
+
247
+ it("only the policy that HOLDS the row's cell listens (the later document wins, as the ladder reads it)", () => {
248
+ // a manual policy placed later on the same row × purpose displaces the listener
249
+ const manual: SharePolicyDoc = {
250
+ id: "pol-collab-manual",
251
+ purpose: "case_collaboration",
252
+ assignments: insideListener.assignments!,
253
+ };
254
+ expect(shareListenersFor([insideListener, manual], HOTLINE)).toEqual([]);
255
+ expect(
256
+ shareListenersFor([manual, insideListener], HOTLINE).map(
257
+ (l) => l.policy.id,
258
+ ),
259
+ ).toEqual(["pol-collab-ongoing"]);
260
+ // two listeners on one cell: one share, the holder's — never both
261
+ const second = { ...insideListener, id: "pol-collab-ongoing-2" };
262
+ expect(
263
+ shareListenersFor([insideListener, second], HOTLINE).map(
264
+ (l) => l.policy.id,
265
+ ),
266
+ ).toEqual(["pol-collab-ongoing-2"]);
267
+ // a retired later document displaces nothing (it never governs)
268
+ expect(
269
+ shareListenersFor([insideListener, { ...manual, active: false }], HOTLINE)
270
+ .length,
271
+ ).toBe(1);
272
+ // a different purpose on the same row is a different cell
273
+ expect(
274
+ shareListenersFor(
275
+ [insideListener, { ...manual, purpose: "referral" }],
276
+ HOTLINE,
277
+ ).length,
278
+ ).toBe(1);
279
+ });
280
+
281
+ it("with the account's rows: a link whose row is gone, or disagrees, fires nothing", () => {
282
+ const rows = [
283
+ {
284
+ id: "tr-hotline-services",
285
+ myTeamId: HOTLINE,
286
+ their: { type: "team", id: SERVICES },
287
+ },
288
+ { id: "tr-hotline-palomar", myTeamId: HOTLINE, their: null },
289
+ ];
290
+ const both = [insideListener, partnerListener];
291
+ expect(shareListenersFor(both, HOTLINE, { teamRows: rows }).length).toBe(2);
292
+ expect(shareListenersFor(both, HOTLINE, { teamRows: [] })).toEqual([]);
293
+ expect(
294
+ shareListenersFor(both, HOTLINE, { teamRows: [rows[1]!] }).map(
295
+ (l) => l.policy.id,
296
+ ),
297
+ ).toEqual(["pol-referral-palomar-ongoing"]);
298
+ // the row now names another receiving team, or another sender
299
+ expect(
300
+ shareListenersFor([insideListener], HOTLINE, {
301
+ teamRows: [{ ...rows[0]!, their: { type: "team", id: SHELTER } }],
302
+ }),
303
+ ).toEqual([]);
304
+ expect(
305
+ shareListenersFor([insideListener], HOTLINE, {
306
+ teamRows: [{ ...rows[0]!, myTeamId: SHELTER }],
307
+ }),
308
+ ).toEqual([]);
309
+ // and fireShareEvent passes them through
310
+ expect(fireShareEvent(both, submit(), { teamRows: [] })).toEqual([]);
311
+ });
312
+ });
313
+
314
+ describe("fireShareEvent — which listeners an event raises", () => {
315
+ const policies = [insideListener, partnerListener];
316
+
317
+ it("session submit fires every listener on the acting team that names it", () => {
318
+ const fired = fireShareEvent(policies, submit());
319
+ expect(fired.map((f) => [f.policy.id, f.purpose, f.recipient])).toEqual([
320
+ [
321
+ "pol-collab-ongoing",
322
+ "case_collaboration",
323
+ { kind: "sibling_team", teamId: SERVICES },
324
+ ],
325
+ [
326
+ "pol-referral-palomar-ongoing",
327
+ "referral",
328
+ { kind: "partner", id: PALOMAR },
329
+ ],
330
+ ]);
331
+ expect(fired.every((f) => f.event === "sessionSubmitted")).toBe(true);
332
+ expect(fired.every((f) => f.ref === "sess-1")).toBe(true);
333
+ expect(fired.every((f) => f.fromTeamId === HOTLINE)).toBe(true);
334
+ });
335
+
336
+ it("case close fires only the policies listening for it", () => {
337
+ const fired = fireShareEvent(policies, {
338
+ event: SHARE_EVENT.CASE_CLOSED,
339
+ teamId: HOTLINE,
340
+ caseId: "case-9",
341
+ });
342
+ expect(fired.map((f) => f.policy.id)).toEqual(["pol-collab-ongoing"]);
343
+ expect(fired[0]?.ref).toBe("case-9");
344
+ });
345
+
346
+ it("fires nothing for another team, an unlistened event, no team, no event or no policies", () => {
347
+ expect(fireShareEvent(policies, submit({ teamId: SERVICES }))).toEqual([]);
348
+ expect(fireShareEvent(policies, submit({ event: "noteAdded" }))).toEqual(
349
+ [],
350
+ );
351
+ expect(fireShareEvent(policies, submit({ teamId: null }))).toEqual([]);
352
+ expect(fireShareEvent(policies, submit({ event: "" }))).toEqual([]);
353
+ expect(fireShareEvent([], submit())).toEqual([]);
354
+ expect(fireShareEvent(null, submit())).toEqual([]);
355
+ expect(fireShareEvent(policies, null)).toEqual([]);
356
+ });
357
+
358
+ it("the same event on the same subject fires each listener ONCE", () => {
359
+ const first = fireShareEvent(policies, submit());
360
+ const again = fireShareEvent(policies, submit(), {
361
+ alreadyFired: first.map((f) => f.key),
362
+ });
363
+ expect(again).toEqual([]);
364
+ // one already written, the other not
365
+ const partial = fireShareEvent(policies, submit(), {
366
+ alreadyFired: [first[0]!.key],
367
+ });
368
+ expect(partial.map((f) => f.policy.id)).toEqual([
369
+ "pol-referral-palomar-ongoing",
370
+ ]);
371
+ // a different session is a different subject
372
+ const other = fireShareEvent(policies, submit({ sessionId: "sess-2" }), {
373
+ alreadyFired: first.map((f) => f.key),
374
+ });
375
+ expect(other.length).toBe(2);
376
+ });
377
+
378
+ it("the key is stable per event · subject · policy · sending team · recipient, whatever the ids contain", () => {
379
+ const [f] = fireShareEvent(policies, submit());
380
+ expect(firedShareKey(f!.event, f!.ref, f!)).toBe(f!.key);
381
+ expect(fireShareEvent(policies, submit())[0]!.key).toBe(f!.key);
382
+ const keys = fireShareEvent(policies, submit()).map((x) => x.key);
383
+ expect(new Set(keys).size).toBe(keys.length);
384
+ // separators inside ids never alias: partner "P/T" vs partner "P" + team "T"
385
+ const link = (partnerId: string, team?: string) => ({
386
+ policy: { id: "p", familyId: "p", name: "p", version: 1 },
387
+ fromTeamId: "t",
388
+ recipient: { kind: "partner" as const, id: partnerId },
389
+ partnerTeamId: team ?? null,
390
+ });
391
+ expect(firedShareKey("e", null, link("P/T"))).not.toBe(
392
+ firedShareKey("e", null, link("P", "T")),
393
+ );
394
+ expect(firedShareKey("e|x", "r", link("P"))).not.toBe(
395
+ firedShareKey("e", "x|r", link("P")),
396
+ );
397
+ });
398
+
399
+ it("the subject: an explicit ref wins; a session submit is about the session, anything else about the case", () => {
400
+ expect(fireShareEvent(policies, submit({ ref: "REC-7" }))[0]!.ref).toBe(
401
+ "REC-7",
402
+ );
403
+ expect(fireShareEvent(policies, submit())[0]!.ref).toBe("sess-1");
404
+ // a case close raised inside a session is still about the CASE — the
405
+ // same close seen from another session, or from none, is the same key
406
+ const close = (sessionId: string | null) =>
407
+ fireShareEvent(policies, {
408
+ event: SHARE_EVENT.CASE_CLOSED,
409
+ teamId: HOTLINE,
410
+ caseId: "case-9",
411
+ sessionId,
412
+ })[0]!;
413
+ expect(close("sess-A").ref).toBe("case-9");
414
+ expect(close("sess-A").key).toBe(close("sess-B").key);
415
+ expect(close("sess-A").key).toBe(close(null).key);
416
+ expect(
417
+ fireShareEvent(policies, submit({ sessionId: null, caseId: null }))[0]!
418
+ .ref,
419
+ ).toBeNull();
420
+ expect(fireShareEvent(policies, submit({ sessionId: null }))[0]!.ref).toBe(
421
+ "case-9",
422
+ );
423
+ });
424
+
425
+ it("is pure: the same input gives the same output, and the input is not touched", () => {
426
+ const frozen = JSON.stringify(policies);
427
+ expect(fireShareEvent(policies, submit())).toEqual(
428
+ fireShareEvent(policies, submit()),
429
+ );
430
+ expect(JSON.stringify(policies)).toBe(frozen);
431
+ });
432
+
433
+ it("decides nothing about what leaves: a blocked or approval posture still fires (the send door holds it)", () => {
434
+ const blocked = { ...insideListener, posture: "blocked" as const };
435
+ expect(fireShareEvent([blocked], submit()).length).toBe(1);
436
+ });
437
+ });