@htilabs/platform-common-models 0.39.0 → 0.41.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 (48) hide show
  1. package/README.md +86 -0
  2. package/dist/age/index.cjs +136 -0
  3. package/dist/age/index.cjs.map +1 -0
  4. package/dist/age/index.d.cts +136 -0
  5. package/dist/age/index.d.ts +136 -0
  6. package/dist/age/index.js +105 -0
  7. package/dist/age/index.js.map +1 -0
  8. package/dist/index.cjs +159 -0
  9. package/dist/index.cjs.map +1 -1
  10. package/dist/index.d.cts +2 -1
  11. package/dist/index.d.ts +2 -1
  12. package/dist/index.js +150 -0
  13. package/dist/index.js.map +1 -1
  14. package/dist/share-rules/index.cjs +822 -0
  15. package/dist/share-rules/index.cjs.map +1 -0
  16. package/dist/share-rules/index.d.cts +804 -0
  17. package/dist/share-rules/index.d.ts +804 -0
  18. package/dist/share-rules/index.js +736 -0
  19. package/dist/share-rules/index.js.map +1 -0
  20. package/dist/sharing-ceiling/index.cjs +51 -0
  21. package/dist/sharing-ceiling/index.cjs.map +1 -1
  22. package/dist/sharing-ceiling/index.d.cts +87 -1
  23. package/dist/sharing-ceiling/index.d.ts +87 -1
  24. package/dist/sharing-ceiling/index.js +47 -0
  25. package/dist/sharing-ceiling/index.js.map +1 -1
  26. package/package.json +12 -1
  27. package/src/age/__tests__/ageFromDob.test.ts +192 -0
  28. package/src/age/ageFromDob.ts +269 -0
  29. package/src/age/index.ts +8 -0
  30. package/src/index.ts +4 -0
  31. package/src/shareRules/__tests__/caseShareLane.test.ts +259 -0
  32. package/src/shareRules/__tests__/magicLinkAddresses.test.ts +107 -0
  33. package/src/shareRules/__tests__/platformApps.test.ts +133 -0
  34. package/src/shareRules/__tests__/releaseTerms.test.ts +358 -0
  35. package/src/shareRules/__tests__/senderRoiPosture.test.ts +284 -0
  36. package/src/shareRules/__tests__/sharingMethods.test.ts +105 -0
  37. package/src/shareRules/caseShareLane.ts +289 -0
  38. package/src/shareRules/index.ts +31 -0
  39. package/src/shareRules/magicLinkAddresses.ts +185 -0
  40. package/src/shareRules/platformApps.ts +168 -0
  41. package/src/shareRules/releaseTerms.ts +359 -0
  42. package/src/shareRules/reportPurposes.ts +50 -0
  43. package/src/shareRules/senderRoiPosture.ts +296 -0
  44. package/src/shareRules/sharingMethods.ts +204 -0
  45. package/src/sharingCeiling/__tests__/threadLift.test.ts +353 -0
  46. package/src/sharingCeiling/coverage.ts +63 -0
  47. package/src/sharingCeiling/defaults.ts +106 -0
  48. package/src/sharingCeiling/index.ts +7 -0
@@ -0,0 +1,296 @@
1
+ /**
2
+ * Lifted unchanged from Thread `@thread/shared` `services/roiPosture.ts` (the
3
+ * whole module, L1-L268) @ thread develop f021be2. The share-gate rule the
4
+ * composer and every send door apply is L165-L268 (`senderRoiPostureForTeam`,
5
+ * `resolveAgencyRoiPosture`, `resolveSenderRoiPosture`); L1-L164 (the posture
6
+ * types and canon's read of the stored `roiPolicy` slice,
7
+ * `readAuthoredRoiPosture`) moved with it because L165-L268 is typed by and
8
+ * fed from them. Its one Thread import, `vspReleasePosture`, moved too.
9
+ *
10
+ * NOTE: `"required" | "waived"` here is the account's release POSTURE (canon
11
+ * `ROI_POLICY_POSTURES`), not a share's release BASIS — CVC-331's retirement
12
+ * of the basis `waived` does not reach it.
13
+ *
14
+ * Pure: no mongoose, no I/O, no SOT import. Thread's module note follows.
15
+ *
16
+ * The SENDING account's release posture — "does a share from this account
17
+ * need a signed release on file?" — read PURELY from the platform agency
18
+ * row's fields (th-u142w). No I/O: the API reads the row
19
+ * (`apps/api/src/helpers/roi-requirement.ts`) and calls these; the ROI basis
20
+ * ladder (`shareRoiBasis.ts`) and the share composer consume the answer.
21
+ *
22
+ * ## The ladder — canon `roiPostureFor`
23
+ *
24
+ * Canon (prototype `d85f05b7`, `HTI-LEADS-PAVE-Thread-prototype.html`
25
+ * L329214-L329319; the platform resolver `HTI_SHARE_POLICY_API.roiPostureFor`,
26
+ * platform-prototype `a6f1f3a5` `src/data.js` L51848-L51904; GDR § 5.17
27
+ * amendment 2026-08-19, `GLOBAL_DESIGN_RULES.md` L3728-L3756):
28
+ *
29
+ * 1. AUTHORED wins, in BOTH directions — the account's
30
+ * `policies.roiPosture.agencyDefault` (`"required" | "waived"`; null /
31
+ * absent = un-authored), authored in Platform Admin Hub → Policies →
32
+ * Consent & ROI (platform-prototype `src/screens.jsx` L15009-L15074,
33
+ * `ConsentRoiTab`).
34
+ * 2. else DERIVED from the AFFIRMED directory VSP flag (canon
35
+ * VSP-TRISTATE-2026-10-08, L329259-L329272): `false` → waived; `true`
36
+ * and never-captured → required (`vspReleasePosture`).
37
+ * 3. a team override may only TIGHTEN — `teamOverrides[teamId] ===
38
+ * "required"` upgrades a waived posture; nothing downgrades required
39
+ * (L329306-L329310; CAM invariants 3/6).
40
+ *
41
+ * ## Deviation from canon at the share gate — the team rung (ruled, th-u142w)
42
+ *
43
+ * Rungs 1–2 and the bad-value reading match canon exactly. Rung 3 does NOT:
44
+ * canon's resolver has it, but canon's GATING sites call
45
+ * `senderAgencyRequiresROI()` with no team (L337935, L338110 →
46
+ * `roiPostureFor(undefined)`), so canon never applies a team override at
47
+ * the share gate. Thread applies it, keyed by the SENDING record's
48
+ * `teamOwner`, at every send door and in the composer — as PAVE does
49
+ * (`shareRecordService.ts` L3097-L3102 @ pave-2.0 `0ae6c7f0e`: "The posture
50
+ * ladder's team override is the SENDING team's"), so Thread and PAVE answer
51
+ * identically. It only ever TIGHTENS (waived → required), never relaxes.
52
+ * Recorded in CATALOG.md ShareComposer Known deviations #24 and
53
+ * packages/shared CLAUDE.md edge case 41 (coordinator ruling 2026-10-13).
54
+ *
55
+ * Legal-override purposes keep their own rule: the exemption is the
56
+ * CALLER's (canon L329241-L329247: "This function does not know about
57
+ * purposes and must not be taught to") — the basis ladder's rung 2.
58
+ *
59
+ * ## How a bad stored value reads — exactly canon's reading
60
+ *
61
+ * Canon reads the slice with strict equality and nothing else, so a value
62
+ * outside the shape simply does not count (coordinator ruling 2026-10-13:
63
+ * Thread gives the same answer as canon, the platform and PAVE for the same
64
+ * data):
65
+ *
66
+ * - `agencyDefault`: `(tabDoc.agencyDefault === "required" ||
67
+ * tabDoc.agencyDefault === "waived") ? tabDoc.agencyDefault : null`
68
+ * (monolith L329297-L329298; platform `data.js` L51883) — anything else
69
+ * is UN-AUTHORED and the VSP rung decides.
70
+ * - a team: `(tabDoc.teamOverrides || {})[teamId] === "required"`
71
+ * (monolith L329306; `data.js` L51899) — any other value IGNORES that
72
+ * team (it never tightens and, since a team can only tighten, it can
73
+ * never widen either).
74
+ * - a slice that is not an object reads neither (`"waived".agencyDefault`
75
+ * is `undefined`; the slice is read as `(p && p.roiPosture) || null`,
76
+ * L329287): un-authored, no team overrides.
77
+ *
78
+ * Every such value is reported in `issues` (coded, never the value) so the
79
+ * reader can log it — a malformed slice is a platform-writer defect worth
80
+ * seeing, not a silent no-op.
81
+ *
82
+ * ## Where the authored posture lives
83
+ *
84
+ * The platform writer (platform `lib/agency-consent/repository.ts`
85
+ * `setRoiPolicy`, schema `lib/agency-consent/schemas.ts` `RoiPolicySchema`,
86
+ * route `app/api/admin/agency-consent/route.ts` @ platform develop
87
+ * `31df78d`) stores canon's `policies.roiPosture` slice as
88
+ * `platform-db.agencies.<agency>.roiPolicy = { agencyDefault, teamOverrides }`
89
+ * — the SAME row Thread already reads `vsp` from. Thread reads it there,
90
+ * READ-ONLY, and never writes it. Team-override KEYS are the platform's team
91
+ * ids (`listAgencyTeams`: a `teams` row's `entity_id`, else `id`, else
92
+ * `String(_id)`); the API translates them to the `teams._id` hex a Thread
93
+ * record's `teamOwner` holds before they reach `SenderRoiPostureView`.
94
+ */
95
+
96
+ /**
97
+ * The release posture the affirmed flag implies (canon L329146): only an
98
+ * affirmed `false` waives; `true` and never-captured both require one.
99
+ *
100
+ * Moved with this module from Thread `@thread/shared`
101
+ * `services/agencyVspSignal.ts` L93-L101 @ thread develop f021be2, unchanged
102
+ * (a one-line pure function; the affirmed-flag reader `affirmedAgencyVsp`
103
+ * stays with each app's agency read).
104
+ */
105
+ export function vspReleasePosture(
106
+ affirmed: boolean | null,
107
+ ): "required" | "waived" {
108
+ return affirmed === false ? "waived" : "required";
109
+ }
110
+
111
+ /** The two authored postures (canon `ROI_POLICY_POSTURES`). */
112
+ export type RoiReleasePosture = "required" | "waived";
113
+
114
+ /** The platform agency-row field this read consults (`agencies.roiPolicy`). */
115
+ export const AUTHORED_ROI_POSTURE_FIELD = "roiPolicy";
116
+
117
+ /** A stored value canon would not count — coded, never the value itself. */
118
+ export type AuthoredRoiPostureIssue =
119
+ | "roi_policy_not_object"
120
+ | "agency_default_invalid"
121
+ | "team_overrides_not_object"
122
+ | "team_override_value_invalid";
123
+
124
+ /** The authored posture, as canon reads it off the agency row. */
125
+ export interface AuthoredRoiPostureRead {
126
+ /** A `roiPolicy` value is stored at all (well-formed or not). */
127
+ readonly present: boolean;
128
+ /** `null` = un-authored — the VSP rung decides. */
129
+ readonly agencyDefault: RoiReleasePosture | null;
130
+ /** The platform team keys whose value is exactly `"required"`. */
131
+ readonly requiredTeamKeys: readonly string[];
132
+ /** Values canon ignored (for the reader's warn log). Empty when clean. */
133
+ readonly issues: readonly AuthoredRoiPostureIssue[];
134
+ }
135
+
136
+ export const ABSENT_AUTHORED_ROI_POSTURE: AuthoredRoiPostureRead = {
137
+ present: false,
138
+ agencyDefault: null,
139
+ requiredTeamKeys: [],
140
+ issues: [],
141
+ };
142
+
143
+ function isPlainObject(value: unknown): value is Record<string, unknown> {
144
+ return (
145
+ typeof value === "object" &&
146
+ value !== null &&
147
+ !Array.isArray(value) &&
148
+ Object.getPrototypeOf(value) === Object.prototype
149
+ );
150
+ }
151
+
152
+ /**
153
+ * Read a stored `roiPolicy` value the way canon does (see the module header).
154
+ * Total — never throws.
155
+ */
156
+ export function readAuthoredRoiPosture(raw: unknown): AuthoredRoiPostureRead {
157
+ if (raw === undefined || raw === null) return ABSENT_AUTHORED_ROI_POSTURE;
158
+ if (!isPlainObject(raw)) {
159
+ return {
160
+ present: true,
161
+ agencyDefault: null,
162
+ requiredTeamKeys: [],
163
+ issues: ["roi_policy_not_object"],
164
+ };
165
+ }
166
+ const issues: AuthoredRoiPostureIssue[] = [];
167
+
168
+ const def = raw.agencyDefault;
169
+ let agencyDefault: RoiReleasePosture | null = null;
170
+ if (def === "required" || def === "waived") agencyDefault = def;
171
+ else if (def !== undefined && def !== null) {
172
+ issues.push("agency_default_invalid");
173
+ }
174
+
175
+ const requiredTeamKeys: string[] = [];
176
+ const overrides = raw.teamOverrides;
177
+ if (overrides !== undefined && overrides !== null) {
178
+ if (!isPlainObject(overrides)) {
179
+ issues.push("team_overrides_not_object");
180
+ } else {
181
+ let invalidTeamValue = false;
182
+ for (const [teamKey, value] of Object.entries(overrides)) {
183
+ if (value === "required") requiredTeamKeys.push(teamKey);
184
+ else invalidTeamValue = true;
185
+ }
186
+ if (invalidTeamValue) issues.push("team_override_value_invalid");
187
+ }
188
+ }
189
+ return { present: true, agencyDefault, requiredTeamKeys, issues };
190
+ }
191
+
192
+ /** Which rung decided — the administrator-facing "why". */
193
+ export type SenderRoiPostureSource =
194
+ | "authored"
195
+ | "derived_vsp"
196
+ | "team_override";
197
+
198
+ export interface SenderRoiPosture {
199
+ readonly posture: RoiReleasePosture;
200
+ /** `posture === "required"`. */
201
+ readonly required: boolean;
202
+ readonly source: SenderRoiPostureSource;
203
+ /** The derived (VSP) default, whatever decided. */
204
+ readonly derivedDefault: RoiReleasePosture;
205
+ /** Coded rule path (no ids beyond a team id; no PII). */
206
+ readonly rulePath: string;
207
+ }
208
+
209
+ /**
210
+ * The account's posture with the team rung NOT yet applied, plus the teams
211
+ * that tighten it — the shape the server hands the composer, so both apply
212
+ * the team rung with ONE function (`senderRoiPostureForTeam`).
213
+ * `tightenedTeamIds` are in the id space of the team the caller will pass
214
+ * (the API translates platform keys to `teams._id` hex first).
215
+ */
216
+ export interface SenderRoiPostureView {
217
+ readonly agency: SenderRoiPosture;
218
+ readonly tightenedTeamIds: readonly string[];
219
+ }
220
+
221
+ /** Rungs 1–2: authored > the affirmed VSP default. Pure and total. */
222
+ export function resolveAgencyRoiPosture(input: {
223
+ readonly authored: AuthoredRoiPostureRead;
224
+ /** The AFFIRMED VSP flag (`affirmedAgencyVsp`) — null = never captured. */
225
+ readonly affirmedVsp: boolean | null;
226
+ }): SenderRoiPosture {
227
+ const derivedDefault = vspReleasePosture(input.affirmedVsp);
228
+ const authored = input.authored.agencyDefault;
229
+ if (authored !== null) {
230
+ return {
231
+ posture: authored,
232
+ required: authored === "required",
233
+ source: "authored",
234
+ derivedDefault,
235
+ rulePath: `agencies.roiPolicy.agencyDefault=${authored} (Consent & ROI)`,
236
+ };
237
+ }
238
+ return {
239
+ posture: derivedDefault,
240
+ required: derivedDefault === "required",
241
+ source: "derived_vsp",
242
+ derivedDefault,
243
+ rulePath: `agencies.vsp=${input.affirmedVsp === null ? "null (never captured)" : String(input.affirmedVsp)} → ${derivedDefault}`,
244
+ };
245
+ }
246
+
247
+ /**
248
+ * Rung 3: a team override only TIGHTENS a waived posture — applied at the
249
+ * share gate as PAVE does, a recorded DEVIATION from canon's gating sites,
250
+ * which pass no team at all (see the module header). Absent team ⇒ the rung
251
+ * is skipped (canon's gating behaviour, and PAVE's resolver with
252
+ * `teamId === undefined`).
253
+ */
254
+ export function senderRoiPostureForTeam(
255
+ view: SenderRoiPostureView,
256
+ sendingTeamId?: string | null | undefined,
257
+ ): SenderRoiPosture {
258
+ if (
259
+ view.agency.posture === "waived" &&
260
+ typeof sendingTeamId === "string" &&
261
+ sendingTeamId.length > 0 &&
262
+ view.tightenedTeamIds.includes(sendingTeamId)
263
+ ) {
264
+ return {
265
+ ...view.agency,
266
+ posture: "required",
267
+ required: true,
268
+ source: "team_override",
269
+ rulePath: `agencies.roiPolicy.teamOverrides[${sendingTeamId}]=required (teams tighten, never relax)`,
270
+ };
271
+ }
272
+ return view.agency;
273
+ }
274
+
275
+ export interface ResolveSenderRoiPostureInput {
276
+ readonly authored: AuthoredRoiPostureRead;
277
+ readonly affirmedVsp: boolean | null;
278
+ /**
279
+ * The sending team, in the SAME id space as the authored team keys. Absent
280
+ * ⇒ the team rung is skipped.
281
+ */
282
+ readonly sendingTeamId?: string | null | undefined;
283
+ }
284
+
285
+ /** The whole ladder over one id space (authored keys = team ids). */
286
+ export function resolveSenderRoiPosture(
287
+ input: ResolveSenderRoiPostureInput,
288
+ ): SenderRoiPosture {
289
+ return senderRoiPostureForTeam(
290
+ {
291
+ agency: resolveAgencyRoiPosture(input),
292
+ tightenedTeamIds: input.authored.requiredTeamKeys,
293
+ },
294
+ input.sendingTeamId,
295
+ );
296
+ }
@@ -0,0 +1,204 @@
1
+ /**
2
+ * The two method vocabularies a share and a release speak, and the one
3
+ * reading between them.
4
+ *
5
+ * - A SHARE's `method` — `SHARING_METHOD` (`case_share`, `magic_link`,
6
+ * `email`, …) with its on-screen words `SHARING_METHOD_LABELS`. Lifted
7
+ * unchanged from Thread `@thread/shared` `constants/ic.ts` L343-L374
8
+ * @ thread develop f021be2 (a small pure constant; the keys are the
9
+ * literals PAVE already uses, `apps/web/lib/share-config.ts`).
10
+ * - A RELEASE's approved sending methods — CVC-332 `core-share_method`
11
+ * stored tokens (ROI Data Object § 4, ruling 5, Crysta 2026-10-20:
12
+ * "Sending methods use the CVC-332 stored tokens in every app"), derived
13
+ * from this package's `RoiMethodKeys` minus its Level-0 missingness keys.
14
+ * Lifted unchanged from Thread `constants/releaseMethod.ts` L41-L177; the
15
+ * zod write schema (`releaseMethodWriteSchema`) stays in Thread, so no
16
+ * zod schema crosses a package boundary.
17
+ *
18
+ * Reads: a stored `case_share` reads as `thread_caseshare`, a stored
19
+ * `magic_link` as `thread_magic_link`; a retired `physical_mail` reads as
20
+ * itself (it matches no share). Stored rows are never rewritten.
21
+ *
22
+ * Pure: no mongoose, no I/O, no SOT import (`RoiMethodKeys` is the generated
23
+ * key map).
24
+ */
25
+
26
+ import {
27
+ RoiMethodKeys as PlatformRoiMethodKeys,
28
+ type RoiMethodKey,
29
+ } from "../generated/cvc-enums.js";
30
+
31
+ // ─── A share's method (Thread constants/ic.ts L343-L374) ────────────────────
32
+
33
+ export const SHARING_METHOD = {
34
+ CASE_SHARE: "case_share",
35
+ MAGIC_LINK: "magic_link",
36
+ EMAIL: "email",
37
+ FAX: "fax",
38
+ SECURE_PORTAL: "secure_portal",
39
+ PHYSICAL_MAIL: "physical_mail",
40
+ IN_PERSON: "in_person",
41
+ } as const;
42
+
43
+ export type SharingMethodValue =
44
+ (typeof SHARING_METHOD)[keyof typeof SHARING_METHOD];
45
+
46
+ export const SHARING_METHOD_VALUES = [
47
+ SHARING_METHOD.CASE_SHARE,
48
+ SHARING_METHOD.MAGIC_LINK,
49
+ SHARING_METHOD.EMAIL,
50
+ SHARING_METHOD.FAX,
51
+ SHARING_METHOD.SECURE_PORTAL,
52
+ SHARING_METHOD.PHYSICAL_MAIL,
53
+ SHARING_METHOD.IN_PERSON,
54
+ ] as const;
55
+
56
+ export const SHARING_METHOD_LABELS: Record<SharingMethodValue, string> = {
57
+ [SHARING_METHOD.CASE_SHARE]: "CaseShare",
58
+ [SHARING_METHOD.MAGIC_LINK]: "Magic Link",
59
+ [SHARING_METHOD.EMAIL]: "Email",
60
+ [SHARING_METHOD.FAX]: "Fax",
61
+ [SHARING_METHOD.SECURE_PORTAL]: "Secure Portal",
62
+ [SHARING_METHOD.PHYSICAL_MAIL]: "Physical Mail",
63
+ [SHARING_METHOD.IN_PERSON]: "In-Person",
64
+ };
65
+
66
+ // ─── A release's methods, CVC-332 (Thread constants/releaseMethod.ts L41-L177)
67
+
68
+ /** The SOT's Level-0 rows: never a method a client agrees to. */
69
+ const ROI_METHOD_MISSINGNESS_KEYS = [
70
+ "missingness_root",
71
+ "unknown",
72
+ "anonymous",
73
+ "data_not_collected",
74
+ ] as const;
75
+
76
+ type RoiMethodMissingnessKey = (typeof ROI_METHOD_MISSINGNESS_KEYS)[number];
77
+
78
+ /** A CVC-332 sending-method token — what a release stores. */
79
+ export type ReleaseMethodValue = Exclude<RoiMethodKey, RoiMethodMissingnessKey>;
80
+
81
+ const MISSINGNESS = new Set<string>(ROI_METHOD_MISSINGNESS_KEYS);
82
+
83
+ /** Every CVC-332 token, in the SOT's order. */
84
+ export const RELEASE_METHOD_VALUES = (
85
+ Object.keys(PlatformRoiMethodKeys) as RoiMethodKey[]
86
+ ).filter((key): key is ReleaseMethodValue => !MISSINGNESS.has(key)) as [
87
+ ReleaseMethodValue,
88
+ ...ReleaseMethodValue[],
89
+ ];
90
+
91
+ /** Named handles onto the SOT tokens (typed against it — a rename upstream
92
+ * fails the build here). */
93
+ export const RELEASE_METHOD = {
94
+ CASESHARE: "thread_caseshare",
95
+ MAGIC_LINK: "thread_magic_link",
96
+ EMAIL: "email",
97
+ FAX: "fax",
98
+ SECURE_PORTAL: "secure_portal",
99
+ IN_PERSON: "in_person",
100
+ } as const satisfies Record<string, ReleaseMethodValue>;
101
+
102
+ /** The pre-alignment spellings a stored release may still carry. */
103
+ export const LEGACY_RELEASE_METHOD_ALIASES: Readonly<
104
+ Record<string, ReleaseMethodValue>
105
+ > = {
106
+ [SHARING_METHOD.CASE_SHARE]: RELEASE_METHOD.CASESHARE,
107
+ [SHARING_METHOD.MAGIC_LINK]: RELEASE_METHOD.MAGIC_LINK,
108
+ };
109
+
110
+ /** Retired, not minted (no CVC-332 code). Read as itself; never written. */
111
+ export const RETIRED_RELEASE_METHODS: readonly string[] = [
112
+ SHARING_METHOD.PHYSICAL_MAIL,
113
+ ];
114
+
115
+ /** Every value a stored release's method list may hold (Mongoose enum,
116
+ * the read schema). */
117
+ export const STORED_RELEASE_METHOD_VALUES = [
118
+ ...RELEASE_METHOD_VALUES,
119
+ ...Object.keys(LEGACY_RELEASE_METHOD_ALIASES),
120
+ ...RETIRED_RELEASE_METHODS,
121
+ ] as [string, ...string[]];
122
+
123
+ const RELEASE_METHOD_SET = new Set<string>(RELEASE_METHOD_VALUES);
124
+
125
+ /** True for a CVC-332 token. */
126
+ export function isReleaseMethod(value: unknown): value is ReleaseMethodValue {
127
+ return typeof value === "string" && RELEASE_METHOD_SET.has(value);
128
+ }
129
+
130
+ /**
131
+ * A stored release method read through the alias: `case_share` →
132
+ * `thread_caseshare`, `magic_link` → `thread_magic_link`; anything else as
133
+ * it is (a retired `physical_mail` stays `physical_mail`).
134
+ */
135
+ export function normalizeReleaseMethod(value: unknown): string {
136
+ const s = String(value);
137
+ return LEGACY_RELEASE_METHOD_ALIASES[s] ?? s;
138
+ }
139
+
140
+ /**
141
+ * A stored release's method list, read: every entry through the alias, no
142
+ * duplicates, and the entries that are not CVC-332 tokens (`physical_mail`)
143
+ * split out so the caller can report them.
144
+ */
145
+ export function readReleaseMethods(methods: unknown): {
146
+ readonly methods: readonly ReleaseMethodValue[];
147
+ readonly unrecognized: readonly string[];
148
+ } {
149
+ const out: ReleaseMethodValue[] = [];
150
+ const unrecognized: string[] = [];
151
+ for (const raw of Array.isArray(methods) ? methods : []) {
152
+ const m = normalizeReleaseMethod(raw);
153
+ if (isReleaseMethod(m)) {
154
+ if (!out.includes(m)) out.push(m);
155
+ } else if (!unrecognized.includes(m)) {
156
+ unrecognized.push(m);
157
+ }
158
+ }
159
+ return { methods: out, unrecognized };
160
+ }
161
+
162
+ /**
163
+ * A SHARE's method read into the release's vocabulary, so R19 compares like
164
+ * with like: an absent method is CaseShare (the legacy rows / `POST /shares`),
165
+ * `case_share` → `thread_caseshare`, `magic_link` → `thread_magic_link`, the
166
+ * shared spellings (email, fax, secure_portal, in_person) as they are.
167
+ */
168
+ export function releaseMethodOfShareMethod(method: unknown): string {
169
+ if (method === undefined || method === null || method === "") {
170
+ return RELEASE_METHOD.CASESHARE;
171
+ }
172
+ return normalizeReleaseMethod(method);
173
+ }
174
+
175
+ /**
176
+ * A RELEASE's method read back into the share-method space
177
+ * (`SHARING_METHOD`), the inverse of `releaseMethodOfShareMethod`:
178
+ * `thread_caseshare` (or a stored `case_share`) → `case_share`,
179
+ * `thread_magic_link` (or `magic_link`) → `magic_link`, the shared spellings
180
+ * (email, fax, secure_portal, in_person) and a retired `physical_mail` as
181
+ * they are. The share-boundary rule and the composer compare a release's
182
+ * list against a share's `method` in this space.
183
+ */
184
+ export function sharingMethodOfReleaseMethod(value: unknown): string {
185
+ const m = normalizeReleaseMethod(value);
186
+ return (
187
+ Object.entries(LEGACY_RELEASE_METHOD_ALIASES).find(
188
+ ([, token]) => token === m,
189
+ )?.[0] ?? m
190
+ );
191
+ }
192
+
193
+ /**
194
+ * Display words for a release method. Thread's existing on-screen words
195
+ * (`SHARING_METHOD_LABELS`) — this change moves the stored token, not the
196
+ * copy. An unrecognized value reads as itself.
197
+ */
198
+ export function releaseMethodLabel(value: unknown): string {
199
+ const m = normalizeReleaseMethod(value);
200
+ const share = (Object.entries(LEGACY_RELEASE_METHOD_ALIASES).find(
201
+ ([, token]) => token === m,
202
+ )?.[0] ?? m) as SharingMethodValue;
203
+ return SHARING_METHOD_LABELS[share] ?? m;
204
+ }