@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.
- package/README.md +86 -0
- package/dist/age/index.cjs +136 -0
- package/dist/age/index.cjs.map +1 -0
- package/dist/age/index.d.cts +136 -0
- package/dist/age/index.d.ts +136 -0
- package/dist/age/index.js +105 -0
- package/dist/age/index.js.map +1 -0
- package/dist/index.cjs +159 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.js +150 -0
- package/dist/index.js.map +1 -1
- package/dist/share-rules/index.cjs +822 -0
- package/dist/share-rules/index.cjs.map +1 -0
- package/dist/share-rules/index.d.cts +804 -0
- package/dist/share-rules/index.d.ts +804 -0
- package/dist/share-rules/index.js +736 -0
- package/dist/share-rules/index.js.map +1 -0
- package/dist/sharing-ceiling/index.cjs +51 -0
- package/dist/sharing-ceiling/index.cjs.map +1 -1
- package/dist/sharing-ceiling/index.d.cts +87 -1
- package/dist/sharing-ceiling/index.d.ts +87 -1
- package/dist/sharing-ceiling/index.js +47 -0
- package/dist/sharing-ceiling/index.js.map +1 -1
- package/package.json +12 -1
- package/src/age/__tests__/ageFromDob.test.ts +192 -0
- package/src/age/ageFromDob.ts +269 -0
- package/src/age/index.ts +8 -0
- package/src/index.ts +4 -0
- package/src/shareRules/__tests__/caseShareLane.test.ts +259 -0
- package/src/shareRules/__tests__/magicLinkAddresses.test.ts +107 -0
- package/src/shareRules/__tests__/platformApps.test.ts +133 -0
- package/src/shareRules/__tests__/releaseTerms.test.ts +358 -0
- package/src/shareRules/__tests__/senderRoiPosture.test.ts +284 -0
- package/src/shareRules/__tests__/sharingMethods.test.ts +105 -0
- package/src/shareRules/caseShareLane.ts +289 -0
- package/src/shareRules/index.ts +31 -0
- package/src/shareRules/magicLinkAddresses.ts +185 -0
- package/src/shareRules/platformApps.ts +168 -0
- package/src/shareRules/releaseTerms.ts +359 -0
- package/src/shareRules/reportPurposes.ts +50 -0
- package/src/shareRules/senderRoiPosture.ts +296 -0
- package/src/shareRules/sharingMethods.ts +204 -0
- package/src/sharingCeiling/__tests__/threadLift.test.ts +353 -0
- package/src/sharingCeiling/coverage.ts +63 -0
- package/src/sharingCeiling/defaults.ts +106 -0
- package/src/sharingCeiling/index.ts +7 -0
|
@@ -0,0 +1,804 @@
|
|
|
1
|
+
import { RoiMethodKey, SharePurposeKey } from '../enums/index.cjs';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Which apps put a share recipient on the platform, and which app a team's
|
|
5
|
+
* shares land in — the two app-membership readings the magic-link and
|
|
6
|
+
* CaseShare-lane rules (./magicLinkAddresses.ts, ./caseShareLane.ts) stand on.
|
|
7
|
+
*
|
|
8
|
+
* Lifted unchanged from Thread `@thread/shared` @ thread develop f021be2:
|
|
9
|
+
* - `shareEdge.ts` L21-L125 — `RecipientPlatformSnapshot`,
|
|
10
|
+
* `recipientPlatformFromApps`, `recipientUsesApp`, `agencyIdKey` and their
|
|
11
|
+
* private helpers (th-a2dfb, Ava A7);
|
|
12
|
+
* - `teamLanding.ts` (whole file) — `teamLandingApp`, `teamLandsInPave`,
|
|
13
|
+
* `teamLandsInThread` (th-ng838.4 MINOR-1).
|
|
14
|
+
* They moved because the lifted rules import them; they are small and pure
|
|
15
|
+
* and read only `PLATFORM_TOOL` (this package). Behaviour and doc comments
|
|
16
|
+
* are Thread's.
|
|
17
|
+
*
|
|
18
|
+
* Pure: no mongoose, no I/O, no SOT import.
|
|
19
|
+
*/
|
|
20
|
+
interface RecipientPlatformSnapshot {
|
|
21
|
+
readonly recipientOnPlatform: boolean;
|
|
22
|
+
/**
|
|
23
|
+
* The recipient org's apps EXACTLY as read (non-empty strings, case kept —
|
|
24
|
+
* e.g. ["TRAIL", "THREAD"]): the audit basis the edge stores. It is NOT
|
|
25
|
+
* the on-platform test — an org on TRAIL alone has a non-empty basis and
|
|
26
|
+
* is off-platform (th-a2dfb). Read `recipientOnPlatform`.
|
|
27
|
+
*/
|
|
28
|
+
readonly recipientOnPlatformBasis: string[];
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Whether an ORGANIZATION's `apps` (read as {@link appsAsRead} reads them)
|
|
32
|
+
* include `app`, trimmed of ASCII whitespace and case-insensitively — the ONE
|
|
33
|
+
* agency app-membership test (the shareable listing, the A7 derivation and
|
|
34
|
+
* the CaseShare rule's LEADS-only agency reading all use it; th-fbb8e
|
|
35
|
+
* review). A TEAM's landing app is read strictly instead
|
|
36
|
+
* ({@link teamLandingApp}: the first entry, an exact uppercase PLATFORM_TOOL
|
|
37
|
+
* code).
|
|
38
|
+
*/
|
|
39
|
+
declare function recipientUsesApp(apps: unknown, app: string): boolean;
|
|
40
|
+
/**
|
|
41
|
+
* The key one agency (or team) id is compared under across its stored forms:
|
|
42
|
+
* a 24-hex id lower-cased (an ObjectId's hex and every hex string written from
|
|
43
|
+
* it agree), anything else exactly as given. The ONE 24-hex normaliser
|
|
44
|
+
* (th-fbb8e review).
|
|
45
|
+
*/
|
|
46
|
+
declare function agencyIdKey(id: unknown): string;
|
|
47
|
+
/**
|
|
48
|
+
* Ava A7: "a magic-link recipient is a share recipient that is not using HTI
|
|
49
|
+
* Platform apps". th-a2dfb: the ROUTING rule — on-platform ⇔ the org uses at
|
|
50
|
+
* least one daily casework app (THREAD / PAVE / LEADS — trimmed, any case;
|
|
51
|
+
* a bare-string `apps` value is a one-item list), the
|
|
52
|
+
* platform's `networkReachFor` — so the picker's reach chip and the lane
|
|
53
|
+
* agree: an org on TRAIL / ECHO alone has no inbox to receive a CaseShare,
|
|
54
|
+
* reads Magic Link and rides the magic link.
|
|
55
|
+
*
|
|
56
|
+
* KNOWN DIVERGENCE (veto-able, pending a ruling): the monolith's share-edge
|
|
57
|
+
* derivation `_onPlatformFor` (HTI-LEADS-PAVE-Thread-prototype.html
|
|
58
|
+
* L343282-343299 over `_orgAppsMono` L343036 @ prototype 40f57adf) stamps
|
|
59
|
+
* the edge `value: apps.length > 0` over ALL daily apps, echo / trail
|
|
60
|
+
* included. Thread stamps `recipientOnPlatform` by the casework rule so the
|
|
61
|
+
* stamp matches the lane the share actually took; the basis keeps every app
|
|
62
|
+
* as read, so nothing the monolith records is lost.
|
|
63
|
+
*
|
|
64
|
+
* The EDGE records the derivation and its basis; the org is never marked
|
|
65
|
+
* ("derived from the org's apps_used, never typed on the org").
|
|
66
|
+
*/
|
|
67
|
+
declare function recipientPlatformFromApps(apps: unknown): RecipientPlatformSnapshot;
|
|
68
|
+
/** The team's landing app — its first declared app code, or undefined. */
|
|
69
|
+
declare function teamLandingApp(apps: readonly unknown[] | null | undefined): string | undefined;
|
|
70
|
+
/** True iff the team's landing app is PAVE (the intake-referral target). */
|
|
71
|
+
declare function teamLandsInPave(apps: readonly unknown[] | null | undefined): boolean;
|
|
72
|
+
/** True iff the team's landing app is THREAD (the cross-team inbox lane). */
|
|
73
|
+
declare function teamLandsInThread(apps: readonly unknown[] | null | undefined): boolean;
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* The two method vocabularies a share and a release speak, and the one
|
|
77
|
+
* reading between them.
|
|
78
|
+
*
|
|
79
|
+
* - A SHARE's `method` — `SHARING_METHOD` (`case_share`, `magic_link`,
|
|
80
|
+
* `email`, …) with its on-screen words `SHARING_METHOD_LABELS`. Lifted
|
|
81
|
+
* unchanged from Thread `@thread/shared` `constants/ic.ts` L343-L374
|
|
82
|
+
* @ thread develop f021be2 (a small pure constant; the keys are the
|
|
83
|
+
* literals PAVE already uses, `apps/web/lib/share-config.ts`).
|
|
84
|
+
* - A RELEASE's approved sending methods — CVC-332 `core-share_method`
|
|
85
|
+
* stored tokens (ROI Data Object § 4, ruling 5, Crysta 2026-10-20:
|
|
86
|
+
* "Sending methods use the CVC-332 stored tokens in every app"), derived
|
|
87
|
+
* from this package's `RoiMethodKeys` minus its Level-0 missingness keys.
|
|
88
|
+
* Lifted unchanged from Thread `constants/releaseMethod.ts` L41-L177; the
|
|
89
|
+
* zod write schema (`releaseMethodWriteSchema`) stays in Thread, so no
|
|
90
|
+
* zod schema crosses a package boundary.
|
|
91
|
+
*
|
|
92
|
+
* Reads: a stored `case_share` reads as `thread_caseshare`, a stored
|
|
93
|
+
* `magic_link` as `thread_magic_link`; a retired `physical_mail` reads as
|
|
94
|
+
* itself (it matches no share). Stored rows are never rewritten.
|
|
95
|
+
*
|
|
96
|
+
* Pure: no mongoose, no I/O, no SOT import (`RoiMethodKeys` is the generated
|
|
97
|
+
* key map).
|
|
98
|
+
*/
|
|
99
|
+
|
|
100
|
+
declare const SHARING_METHOD: {
|
|
101
|
+
readonly CASE_SHARE: "case_share";
|
|
102
|
+
readonly MAGIC_LINK: "magic_link";
|
|
103
|
+
readonly EMAIL: "email";
|
|
104
|
+
readonly FAX: "fax";
|
|
105
|
+
readonly SECURE_PORTAL: "secure_portal";
|
|
106
|
+
readonly PHYSICAL_MAIL: "physical_mail";
|
|
107
|
+
readonly IN_PERSON: "in_person";
|
|
108
|
+
};
|
|
109
|
+
type SharingMethodValue = (typeof SHARING_METHOD)[keyof typeof SHARING_METHOD];
|
|
110
|
+
declare const SHARING_METHOD_VALUES: readonly ["case_share", "magic_link", "email", "fax", "secure_portal", "physical_mail", "in_person"];
|
|
111
|
+
declare const SHARING_METHOD_LABELS: Record<SharingMethodValue, string>;
|
|
112
|
+
/** The SOT's Level-0 rows: never a method a client agrees to. */
|
|
113
|
+
declare const ROI_METHOD_MISSINGNESS_KEYS: readonly ["missingness_root", "unknown", "anonymous", "data_not_collected"];
|
|
114
|
+
type RoiMethodMissingnessKey = (typeof ROI_METHOD_MISSINGNESS_KEYS)[number];
|
|
115
|
+
/** A CVC-332 sending-method token — what a release stores. */
|
|
116
|
+
type ReleaseMethodValue = Exclude<RoiMethodKey, RoiMethodMissingnessKey>;
|
|
117
|
+
/** Every CVC-332 token, in the SOT's order. */
|
|
118
|
+
declare const RELEASE_METHOD_VALUES: [ReleaseMethodValue, ...ReleaseMethodValue[]];
|
|
119
|
+
/** Named handles onto the SOT tokens (typed against it — a rename upstream
|
|
120
|
+
* fails the build here). */
|
|
121
|
+
declare const RELEASE_METHOD: {
|
|
122
|
+
readonly CASESHARE: "thread_caseshare";
|
|
123
|
+
readonly MAGIC_LINK: "thread_magic_link";
|
|
124
|
+
readonly EMAIL: "email";
|
|
125
|
+
readonly FAX: "fax";
|
|
126
|
+
readonly SECURE_PORTAL: "secure_portal";
|
|
127
|
+
readonly IN_PERSON: "in_person";
|
|
128
|
+
};
|
|
129
|
+
/** The pre-alignment spellings a stored release may still carry. */
|
|
130
|
+
declare const LEGACY_RELEASE_METHOD_ALIASES: Readonly<Record<string, ReleaseMethodValue>>;
|
|
131
|
+
/** Retired, not minted (no CVC-332 code). Read as itself; never written. */
|
|
132
|
+
declare const RETIRED_RELEASE_METHODS: readonly string[];
|
|
133
|
+
/** Every value a stored release's method list may hold (Mongoose enum,
|
|
134
|
+
* the read schema). */
|
|
135
|
+
declare const STORED_RELEASE_METHOD_VALUES: [string, ...string[]];
|
|
136
|
+
/** True for a CVC-332 token. */
|
|
137
|
+
declare function isReleaseMethod(value: unknown): value is ReleaseMethodValue;
|
|
138
|
+
/**
|
|
139
|
+
* A stored release method read through the alias: `case_share` →
|
|
140
|
+
* `thread_caseshare`, `magic_link` → `thread_magic_link`; anything else as
|
|
141
|
+
* it is (a retired `physical_mail` stays `physical_mail`).
|
|
142
|
+
*/
|
|
143
|
+
declare function normalizeReleaseMethod(value: unknown): string;
|
|
144
|
+
/**
|
|
145
|
+
* A stored release's method list, read: every entry through the alias, no
|
|
146
|
+
* duplicates, and the entries that are not CVC-332 tokens (`physical_mail`)
|
|
147
|
+
* split out so the caller can report them.
|
|
148
|
+
*/
|
|
149
|
+
declare function readReleaseMethods(methods: unknown): {
|
|
150
|
+
readonly methods: readonly ReleaseMethodValue[];
|
|
151
|
+
readonly unrecognized: readonly string[];
|
|
152
|
+
};
|
|
153
|
+
/**
|
|
154
|
+
* A SHARE's method read into the release's vocabulary, so R19 compares like
|
|
155
|
+
* with like: an absent method is CaseShare (the legacy rows / `POST /shares`),
|
|
156
|
+
* `case_share` → `thread_caseshare`, `magic_link` → `thread_magic_link`, the
|
|
157
|
+
* shared spellings (email, fax, secure_portal, in_person) as they are.
|
|
158
|
+
*/
|
|
159
|
+
declare function releaseMethodOfShareMethod(method: unknown): string;
|
|
160
|
+
/**
|
|
161
|
+
* A RELEASE's method read back into the share-method space
|
|
162
|
+
* (`SHARING_METHOD`), the inverse of `releaseMethodOfShareMethod`:
|
|
163
|
+
* `thread_caseshare` (or a stored `case_share`) → `case_share`,
|
|
164
|
+
* `thread_magic_link` (or `magic_link`) → `magic_link`, the shared spellings
|
|
165
|
+
* (email, fax, secure_portal, in_person) and a retired `physical_mail` as
|
|
166
|
+
* they are. The share-boundary rule and the composer compare a release's
|
|
167
|
+
* list against a share's `method` in this space.
|
|
168
|
+
*/
|
|
169
|
+
declare function sharingMethodOfReleaseMethod(value: unknown): string;
|
|
170
|
+
/**
|
|
171
|
+
* Display words for a release method. Thread's existing on-screen words
|
|
172
|
+
* (`SHARING_METHOD_LABELS`) — this change moves the stored token, not the
|
|
173
|
+
* copy. An unrecognized value reads as itself.
|
|
174
|
+
*/
|
|
175
|
+
declare function releaseMethodLabel(value: unknown): string;
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* The REPORT purposes — the share purposes the law compels, which no release
|
|
179
|
+
* requirement can gate (§ 5.77): `mandatory_reporting` and
|
|
180
|
+
* `authority_reporting`.
|
|
181
|
+
*
|
|
182
|
+
* Moved with the release-terms rule (./releaseTerms.ts), which exempts these
|
|
183
|
+
* purposes from the release's method term. A small pure constant, written as
|
|
184
|
+
* the two CVC-84 keys and typed against this package's `SharePurposeKey`, so
|
|
185
|
+
* a key renamed upstream fails the build here.
|
|
186
|
+
*
|
|
187
|
+
* Where it came from: Thread `@thread/shared` `constants/shareRoiWaiver.ts`
|
|
188
|
+
* L144-L168 @ thread develop f021be2 (`ROI_WAIVER_EXEMPT_PURPOSES`,
|
|
189
|
+
* `isRoiWaiverExemptPurpose`). Thread DERIVES the list from its
|
|
190
|
+
* `SHARE_PURPOSE_CONFIG[p].legalOverride` flag; that flag is Thread's own
|
|
191
|
+
* config, not in this package's CVC-84 SOT, so the list is written out here.
|
|
192
|
+
* It is byte-identical to Thread's derivation and to PAVE's
|
|
193
|
+
* `ROI_POSTURE_EXEMPT_PURPOSES` (`@pave/db/lookups/roiPosture.ts:129`).
|
|
194
|
+
* Thread's re-point keeps its derivation and pins it equal to this list.
|
|
195
|
+
*
|
|
196
|
+
* Pure: no mongoose, no I/O, no SOT import.
|
|
197
|
+
*/
|
|
198
|
+
|
|
199
|
+
/** The purposes compelled by law (no release requirement applies). */
|
|
200
|
+
declare const ROI_WAIVER_EXEMPT_PURPOSES: readonly SharePurposeKey[];
|
|
201
|
+
/**
|
|
202
|
+
* True when this purpose is compelled by law and no release requirement applies.
|
|
203
|
+
*
|
|
204
|
+
* An ABSENT purpose is NOT exempt. Every queued share written before the
|
|
205
|
+
* purpose dimension existed carries none, and reading absence as an exemption
|
|
206
|
+
* would retroactively excuse the entire back catalogue.
|
|
207
|
+
*/
|
|
208
|
+
declare function isRoiWaiverExemptPurpose(purpose: string | undefined | null): boolean;
|
|
209
|
+
|
|
210
|
+
/** Whether this recipient is a Magic Link partner (see the module note). */
|
|
211
|
+
declare function derivesOffPlatformRecipient(recipient: {
|
|
212
|
+
readonly isSelf?: boolean | undefined;
|
|
213
|
+
readonly apps?: readonly unknown[] | null | undefined;
|
|
214
|
+
}): boolean;
|
|
215
|
+
/**
|
|
216
|
+
* th-333y1 — one of a partner's Referrals (magic link) contacts, as the apps
|
|
217
|
+
* carry it: the Point of contact's display name (null when it has none) and
|
|
218
|
+
* the PREFERRED email the magic link is addressed to.
|
|
219
|
+
*
|
|
220
|
+
* Read from platform-db `pointsofcontact` through the platform-common reader
|
|
221
|
+
* (`listReferralContactsForPartner`, `@htilabs/platform-common-models/points-of-contact`):
|
|
222
|
+
* every ACTIVE, CONFIRMED, non-confidential contact on the partner tagged
|
|
223
|
+
* `REFERRALS_MAGIC_LINK`, one per distinct email (Crysta 2026-08-23 / POC-
|
|
224
|
+
* UNIFIED-CONTACT-MODEL R1, restated in the prototype kickoff
|
|
225
|
+
* `KICKOFF_SERVICE_LISTING_AND_PARTNER_CONTACT_BUILD_2026-10-14.md` @ c6380f73
|
|
226
|
+
* L13, D2: "The magic link is addressed to every `REFERRALS_MAGIC_LINK`
|
|
227
|
+
* holder on the recipient"). Another advocate's pending contact (an in-app add
|
|
228
|
+
* HTI Labs has not confirmed) is never read; the asking advocate's own are,
|
|
229
|
+
* marked `pending`.
|
|
230
|
+
*/
|
|
231
|
+
interface MagicLinkContact {
|
|
232
|
+
readonly name: string | null;
|
|
233
|
+
readonly email: string;
|
|
234
|
+
/**
|
|
235
|
+
* The ASKING advocate's own in-app add, still waiting for HTI Labs to
|
|
236
|
+
* confirm it (Nate 2026-10-15; the reader's `includeOwnPendingFor`). Shown
|
|
237
|
+
* "pending HTI review". Nobody else's pending add is ever read.
|
|
238
|
+
*/
|
|
239
|
+
readonly pending?: true;
|
|
240
|
+
}
|
|
241
|
+
/** The most addresses one magic-link share is emailed to (wire bound). */
|
|
242
|
+
declare const MAGIC_LINK_MAX_ADDRESSES = 25;
|
|
243
|
+
/**
|
|
244
|
+
* th-333y1 — the addresses ONE magic-link share is emailed to, in order:
|
|
245
|
+
* trimmed, empty entries dropped, de-duplicated case-insensitively (the first
|
|
246
|
+
* spelling wins), capped at {@link MAGIC_LINK_MAX_ADDRESSES}. The composer
|
|
247
|
+
* (what the review card prints), the create door and the drain (what is
|
|
248
|
+
* sent) all read this one rule.
|
|
249
|
+
*/
|
|
250
|
+
declare function magicLinkAddresses(...lists: ReadonlyArray<ReadonlyArray<string | null | undefined>>): string[];
|
|
251
|
+
/**
|
|
252
|
+
* th-333y1 — how many distinct addresses {@link magicLinkAddresses} leaves
|
|
253
|
+
* out at the cap (0 when none). Callers log the count / show "+N not
|
|
254
|
+
* included" — never the addresses.
|
|
255
|
+
*/
|
|
256
|
+
declare function magicLinkAddressOverflow(...lists: ReadonlyArray<ReadonlyArray<string | null | undefined>>): number;
|
|
257
|
+
/**
|
|
258
|
+
* pl-iza — the ONE sentence every sender-facing surface uses for who a magic
|
|
259
|
+
* link goes to: the visible addresses, then how many CONFIDENTIAL holders
|
|
260
|
+
* also receive it — never their address or name (canon CVC-338
|
|
261
|
+
* `REFERRALS_MAGIC_LINK`: "A confidential holder still receives it; the
|
|
262
|
+
* sender never sees the address."; ruling Nate 2026-10-15).
|
|
263
|
+
*
|
|
264
|
+
* Verbatim port of the prototype's `window.HTI_MAGIC_LINK_TO_TEXT`
|
|
265
|
+
* (`HTI-LEADS-PAVE-Thread-prototype.html` @ 184893b6 L164656-L164663):
|
|
266
|
+
* "a@x, b@y + 1 confidential recipient" · "1 confidential recipient" ·
|
|
267
|
+
* "2 confidential recipients" · "" (nobody).
|
|
268
|
+
*/
|
|
269
|
+
declare function magicLinkToText(to: ReadonlyArray<string> | null | undefined, confidentialCount: number | null | undefined): string;
|
|
270
|
+
/**
|
|
271
|
+
* pl-iza — how many confidential holders the cap leaves out: the send emails
|
|
272
|
+
* the visible addresses first, then the confidential holders up to
|
|
273
|
+
* {@link MAGIC_LINK_MAX_ADDRESSES} in all (`confidential.deliver(sendOne,
|
|
274
|
+
* { capacity: 25 - visible })`). A count derived from two counts only, so it
|
|
275
|
+
* discloses nothing a sender does not already see. Folded into every
|
|
276
|
+
* "(+N not included)" note.
|
|
277
|
+
*/
|
|
278
|
+
declare function magicLinkConfidentialOverflow(visibleCount: number, confidentialCount: number | null | undefined): number;
|
|
279
|
+
/** The slice of a queued `poc` the magic-link address rules read. */
|
|
280
|
+
interface MagicLinkPocAddresses {
|
|
281
|
+
readonly email?: string | null | undefined;
|
|
282
|
+
readonly contactEmails?: readonly string[] | null | undefined;
|
|
283
|
+
readonly addedEmails?: readonly string[] | null | undefined;
|
|
284
|
+
readonly confidentialCount?: number | null | undefined;
|
|
285
|
+
}
|
|
286
|
+
/** Whether a queued `poc` names a visible address: typed, reviewed, or added. */
|
|
287
|
+
declare function magicLinkPocHasVisibleAddress(poc: MagicLinkPocAddresses | null | undefined): boolean;
|
|
288
|
+
/**
|
|
289
|
+
* pl-iza — a magic-link `poc` whose ONLY address is the confidential-holder
|
|
290
|
+
* count (canon D(ii): a confidential holder is a holder). The create door's
|
|
291
|
+
* schema accepts it; the handler then requires the server to see a holder.
|
|
292
|
+
*/
|
|
293
|
+
declare function magicLinkConfidentialOnly(poc: MagicLinkPocAddresses | null | undefined): boolean;
|
|
294
|
+
|
|
295
|
+
/**
|
|
296
|
+
* Lifted unchanged from Thread `@thread/shared` `shareReleaseTerms.ts` (the
|
|
297
|
+
* whole module, L1-L313) @ thread develop f021be2. Its Thread-only imports
|
|
298
|
+
* were cut as listed below the module note; Thread's note follows.
|
|
299
|
+
*
|
|
300
|
+
* THE RELEASE'S TERMS AT THE SHARE BOUNDARY — the pure rule, ONE copy
|
|
301
|
+
* (Next Steps declutter spec 2026-10-17, R19 / R21; v2.2 R66 / R67;
|
|
302
|
+
* Kickoff 07b step 6).
|
|
303
|
+
*
|
|
304
|
+
* - R19 (+R66) — the METHOD. A release lists the ways the client agreed
|
|
305
|
+
* their information may be sent (`approvedSharingMethods`, the
|
|
306
|
+
* `SHARING_METHOD` vocabulary a share's `method` uses). A share by a
|
|
307
|
+
* method the release does not list is REFUSED — the remedy is a renewal
|
|
308
|
+
* that adds the method (a signed release is never edited).
|
|
309
|
+
* - R21 (+R67) — the END DATE. A share never outlives its release (ruling
|
|
310
|
+
* E): a blank / no-time-limit expiry takes the release's end date; a
|
|
311
|
+
* later date is REFUSED (never capped silently).
|
|
312
|
+
*
|
|
313
|
+
* ## One implementation
|
|
314
|
+
*
|
|
315
|
+
* The server's doors (apps/api `helpers/share-release-terms.ts`, which keeps
|
|
316
|
+
* only the I/O: refusal codes, the drain's failedReason, the 422 reply) and
|
|
317
|
+
* the web composer (`ShareComposer` / `releaseTerms.ts` /
|
|
318
|
+
* `methodAvailability.ts`) both call THESE functions — the same shape as
|
|
319
|
+
* `shareRoiBasis.ts`. The composer had its own copy once, and the two drifted
|
|
320
|
+
* (pre-review M2 / M3 / L3, Kickoff 07b). Pure — no I/O, no logging.
|
|
321
|
+
*
|
|
322
|
+
* ## Exemptions
|
|
323
|
+
*
|
|
324
|
+
* As the prototype exempts every release question (`shareReleaseOf` /
|
|
325
|
+
* `shareReleaseMethodGaps`, monolith @ 31e3cf68 L344975-344987): an
|
|
326
|
+
* own-agency team (no release governs it — the ROI-basis ladder's rung 3,
|
|
327
|
+
* `isInternalIntakeReferral`) for both rules, and a reporting
|
|
328
|
+
* (legal-override) purpose (`isRoiWaiverExemptPurpose`, § 5.77) for the
|
|
329
|
+
* method rule. R21 binds only the methods the PLATFORM delivers (R76).
|
|
330
|
+
*
|
|
331
|
+
* ## Dependencies, cut from `@thread/shared` (the lift)
|
|
332
|
+
*
|
|
333
|
+
* - `SHARING_METHOD` / `SHARING_METHOD_LABELS` and
|
|
334
|
+
* `sharingMethodOfReleaseMethod` — moved to ./sharingMethods.ts.
|
|
335
|
+
* - `isRoiWaiverExemptPurpose` — moved to ./reportPurposes.ts.
|
|
336
|
+
* - `isInternalIntakeReferral` (Thread `constants/shareDeliveryKey.ts`
|
|
337
|
+
* L101-L122) — a two-line predicate, inlined below as
|
|
338
|
+
* `isSameAgencySend`, unchanged.
|
|
339
|
+
* - `ROI_BASIS_REASON.ROI_ON_FILE` (Thread `constants/ic.ts` L708) — the one
|
|
340
|
+
* basis REASON this rule reads, kept as the literal
|
|
341
|
+
* {@link ROI_BASIS_REASON_ROI_ON_FILE}; `roiBasis.reason` is typed
|
|
342
|
+
* `string` so either app's reason type passes.
|
|
343
|
+
*
|
|
344
|
+
* Pure — no mongoose, no I/O, no SOT import.
|
|
345
|
+
*/
|
|
346
|
+
/**
|
|
347
|
+
* The ROI-basis ladder's rung-1 REASON — "the send cites a live ROI" — the
|
|
348
|
+
* only reason under which a cited release binds a share
|
|
349
|
+
* ({@link operativeReleaseOf}). Thread's `ROI_BASIS_REASON.ROI_ON_FILE`
|
|
350
|
+
* (`constants/ic.ts` L708), which Thread maps to the basis `on_file`.
|
|
351
|
+
*/
|
|
352
|
+
declare const ROI_BASIS_REASON_ROI_ON_FILE: "roi_on_file";
|
|
353
|
+
/** The fields of a release these rules read. */
|
|
354
|
+
interface ReleaseTerms {
|
|
355
|
+
readonly approvedSharingMethods?: unknown;
|
|
356
|
+
readonly expirationDate?: unknown;
|
|
357
|
+
}
|
|
358
|
+
/** A share's method, canonical: an ABSENT method (legacy rows,
|
|
359
|
+
* `POST /shares`) is CaseShare. */
|
|
360
|
+
declare function shareMethodOf(method: unknown): string;
|
|
361
|
+
/** True for a method the platform delivers — the methods R21 binds. */
|
|
362
|
+
declare function isBrokeredSharingMethod(method: unknown): boolean;
|
|
363
|
+
/** A `SHARING_METHOD` value's words ("CaseShare", "Email", …). */
|
|
364
|
+
declare function sharingMethodLabel(method: string): string;
|
|
365
|
+
/** "A", "A and B", "A, B and C". */
|
|
366
|
+
declare function releaseListWords(words: readonly string[]): string;
|
|
367
|
+
/**
|
|
368
|
+
* The share is exempt from EVERY release term: an own-agency send (no
|
|
369
|
+
* release governs it — the ladder's rung-3 predicate).
|
|
370
|
+
*/
|
|
371
|
+
declare function isReleaseTermsExemptRecipient(input: {
|
|
372
|
+
readonly senderAgencyId: string;
|
|
373
|
+
readonly recipientAgencyId: string;
|
|
374
|
+
}): boolean;
|
|
375
|
+
/**
|
|
376
|
+
* The method rule does not apply to this purpose: a reporting
|
|
377
|
+
* (legal-override) purpose exercises no release term (§ 5.77).
|
|
378
|
+
*/
|
|
379
|
+
declare function isReleaseMethodExemptPurpose(sharePurpose: string | null | undefined): boolean;
|
|
380
|
+
/**
|
|
381
|
+
* The OPERATIVE release of a share — the release whose terms bind it — or
|
|
382
|
+
* `undefined`. `release` is the cited release as the caller resolved it
|
|
383
|
+
* (followed through a renewal); it binds only when the ladder took it as the
|
|
384
|
+
* authority (rung 1 — a live release naming this recipient). An own-agency
|
|
385
|
+
* share is bound by no release (the prototype's `shareReleaseOf`: an
|
|
386
|
+
* internal team has none).
|
|
387
|
+
*/
|
|
388
|
+
declare function operativeReleaseOf<R extends ReleaseTerms>(input: {
|
|
389
|
+
readonly release: R | null | undefined;
|
|
390
|
+
readonly roiBasis: {
|
|
391
|
+
readonly reason: string;
|
|
392
|
+
};
|
|
393
|
+
readonly senderAgencyId: string;
|
|
394
|
+
readonly recipientAgencyId: string;
|
|
395
|
+
}): R | undefined;
|
|
396
|
+
/**
|
|
397
|
+
* The methods a release lists, or `null` when it lists none. An EMPTY (or
|
|
398
|
+
* absent) `approvedSharingMethods` names no method and restricts nothing —
|
|
399
|
+
* the prototype reads it so (`shareReleaseMethodGaps` /
|
|
400
|
+
* `shareAllowedMethods` filter on `env.methods.length`), and every release
|
|
401
|
+
* written before the method list existed carries `[]` (the schema default).
|
|
402
|
+
* OPEN ITEM: whether an empty list should instead refuse every method is a
|
|
403
|
+
* product ruling the record does not make. Every listed string counts — an
|
|
404
|
+
* unknown legacy value is still a listed method; it just never matches a
|
|
405
|
+
* method the platform offers. Returned in the SHARE-method space
|
|
406
|
+
* (`SHARING_METHOD`), whichever spelling the release stored.
|
|
407
|
+
*/
|
|
408
|
+
declare function releaseListedMethods(release: ReleaseTerms | undefined): readonly string[] | null;
|
|
409
|
+
/**
|
|
410
|
+
* R19 (+R66) — the refusal sentence when the operative release does not list
|
|
411
|
+
* the share's method, else `null`.
|
|
412
|
+
*/
|
|
413
|
+
declare function releaseMethodRefusal(input: {
|
|
414
|
+
readonly method: unknown;
|
|
415
|
+
/** The OPERATIVE release (`operativeReleaseOf`), or `undefined`. */
|
|
416
|
+
readonly release: ReleaseTerms | undefined;
|
|
417
|
+
readonly sharePurpose: string | null | undefined;
|
|
418
|
+
}): string | null;
|
|
419
|
+
/** The UTC calendar day of an instant, `YYYY-MM-DD`. */
|
|
420
|
+
declare const utcCalendarDay: (d: Date) => string;
|
|
421
|
+
/** The last instant of `d`'s UTC calendar day (`…T23:59:59.999Z`). */
|
|
422
|
+
declare function endOfUtcDay(d: Date): Date;
|
|
423
|
+
/**
|
|
424
|
+
* The last instant a share under this release may run: the END of the
|
|
425
|
+
* release's end DAY, or `null` when the release has no end date (or there is
|
|
426
|
+
* no release). The release wizard stores its end as `D T00:00:00.000Z`
|
|
427
|
+
* (`RoiWizardHost` `toIsoDateTime`) while the composer stores a picked day as
|
|
428
|
+
* `D T23:59:59.999Z` (`ShareComposer` `toIsoExpirationDatetime`) — both mean
|
|
429
|
+
* "through day D", so the release is read as running through the whole day.
|
|
430
|
+
*/
|
|
431
|
+
declare function releaseEndOfDay(release: ReleaseTerms | undefined): Date | null;
|
|
432
|
+
/** The release's end DAY, `YYYY-MM-DD`, or `null` (no end date / release). */
|
|
433
|
+
declare function releaseEndDay(release: ReleaseTerms | undefined): string | null;
|
|
434
|
+
type ShareExpiryDecision = {
|
|
435
|
+
readonly kind: "ok";
|
|
436
|
+
/** The share's effective end date; `null` = no end date. */
|
|
437
|
+
readonly expirationDate: Date | null;
|
|
438
|
+
/** `noTimeLimit` as it should now read beside the date. */
|
|
439
|
+
readonly noTimeLimit: boolean;
|
|
440
|
+
/** True when the date was taken from the release (R21). */
|
|
441
|
+
readonly fromRelease: boolean;
|
|
442
|
+
/**
|
|
443
|
+
* The latest instant anything delivered under this share may live —
|
|
444
|
+
* the end of the release's end day — or `null` when no release bounds
|
|
445
|
+
* it. A magic link's one-day floor never reaches past it.
|
|
446
|
+
*/
|
|
447
|
+
readonly releaseEnd: Date | null;
|
|
448
|
+
} | {
|
|
449
|
+
readonly kind: "refused";
|
|
450
|
+
readonly message: string;
|
|
451
|
+
/** The share's end day and the release's, `YYYY-MM-DD`. */
|
|
452
|
+
readonly shareDay: string;
|
|
453
|
+
readonly releaseDay: string;
|
|
454
|
+
};
|
|
455
|
+
/**
|
|
456
|
+
* R21 (+R67) — the share's effective end date under its operative release.
|
|
457
|
+
*
|
|
458
|
+
* - no operative release, or one with no end date → the share's own
|
|
459
|
+
* choice, unchanged (blank stays "no end date");
|
|
460
|
+
* - a recorded method (not platform-delivered, R76) → unchanged;
|
|
461
|
+
* - blank / `noTimeLimit` → the END of the release's end day, so the
|
|
462
|
+
* share lasts through that day;
|
|
463
|
+
* - on or before the release's end DAY → kept;
|
|
464
|
+
* - a later day → REFUSED. Never capped: a date the advocate picked is
|
|
465
|
+
* theirs, and silently moving it would hide that the share ends sooner
|
|
466
|
+
* than they chose.
|
|
467
|
+
*
|
|
468
|
+
* The comparison is by UTC CALENDAR DAY, never instant: the web stores the
|
|
469
|
+
* same day at different instants (`releaseEndOfDay`), so picking the
|
|
470
|
+
* release's own end day must be allowed.
|
|
471
|
+
*/
|
|
472
|
+
declare function shareExpiryUnderRelease(input: {
|
|
473
|
+
readonly method: unknown;
|
|
474
|
+
readonly expirationDate: unknown;
|
|
475
|
+
readonly noTimeLimit: unknown;
|
|
476
|
+
/** The OPERATIVE release (`operativeReleaseOf`), or `undefined`. */
|
|
477
|
+
readonly release: ReleaseTerms | undefined;
|
|
478
|
+
}): ShareExpiryDecision;
|
|
479
|
+
|
|
480
|
+
/**
|
|
481
|
+
* Lifted unchanged from Thread `@thread/shared` `caseShareLane.ts` (the whole
|
|
482
|
+
* module, L1-L279) @ thread develop f021be2; its helpers now come from
|
|
483
|
+
* ./platformApps.ts (lifted with it). Behaviour and copy are Thread's,
|
|
484
|
+
* including Thread's recorded LEADS deviation and the refusal sentences that
|
|
485
|
+
* name Thread ("Thread could not read how …"). An app other than Thread that
|
|
486
|
+
* adopts this rule inherits both; changing them is a product decision, not
|
|
487
|
+
* part of this lift. Pure: no mongoose, no I/O, no SOT import. Thread's
|
|
488
|
+
* module note follows.
|
|
489
|
+
*
|
|
490
|
+
* Where a CaseShare LANDS — the ONE rule the composer (`resolveRowWireMethod`
|
|
491
|
+
* and its send gate, apps/web) and every send door (the queued-share create,
|
|
492
|
+
* the queue drain, `POST /shares` and PAVE "Retry delivery", apps/api
|
|
493
|
+
* `helpers/case-share-lane.ts`) read, so the client and the server can never
|
|
494
|
+
* disagree about a share's lane (th-fbb8e).
|
|
495
|
+
*
|
|
496
|
+
* Thread-local — NOT a platform CVC.
|
|
497
|
+
*
|
|
498
|
+
* ## Canon
|
|
499
|
+
*
|
|
500
|
+
* A share lands in the RECEIVING TEAM's app — `team.apps_used[0]` — for every
|
|
501
|
+
* on-platform recipient and every purpose. When the advocate names only an
|
|
502
|
+
* organization, it lands with that organization's default share team
|
|
503
|
+
* (`resolveDefaultShareTeamMono`, the front door). With no team at all, or a
|
|
504
|
+
* team with no app, canon falls back to PAVE, and any landing app other than
|
|
505
|
+
* pave / thread / leads is clamped to PAVE: `_landApp =
|
|
506
|
+
* _landTeam.apps_used[0] || "pave"` (monolith L340192, the clamp L340201). The
|
|
507
|
+
* advocate never picks an app: the composer offers one CaseShare channel, the
|
|
508
|
+
* landing app is stored on the sent row and the receipt reads "Claim it in
|
|
509
|
+
* <app>" (monolith L340168-340207, L337131, L346163-346255 @ prototype
|
|
510
|
+
* c2900116).
|
|
511
|
+
*
|
|
512
|
+
* ## Thread's one recorded deviation (CATALOG ShareComposer Known deviations
|
|
513
|
+
* #18, packages/shared CLAUDE.md edge case 28)
|
|
514
|
+
*
|
|
515
|
+
* A team whose first app is LEADS lands as a THREAD CaseShare: Thread cannot
|
|
516
|
+
* deliver into LEADS (canon relays through a LEADS bridge, L340272, Thread has
|
|
517
|
+
* none — Nate, 2026-10-16, as on develop before th-fbb8e). So does a
|
|
518
|
+
* LEADS-only agency (apps hold LEADS and neither THREAD nor PAVE) with no team
|
|
519
|
+
* or a team with no app: mandated and legal-override reports to LEADS-only
|
|
520
|
+
* agencies keep working.
|
|
521
|
+
*
|
|
522
|
+
* ## The only refusals
|
|
523
|
+
*
|
|
524
|
+
* A NAMED team that is gone or inactive (choose the team again), and a setup
|
|
525
|
+
* that cannot be READ — the teams, the configured default share team where it
|
|
526
|
+
* decides, or the agency's apps where the LEADS-only reading decides
|
|
527
|
+
* (retryable). Rep counts never choose the lane.
|
|
528
|
+
*/
|
|
529
|
+
/** The two in-app lanes Thread delivers a CaseShare on. */
|
|
530
|
+
declare const CASE_SHARE_LANE: {
|
|
531
|
+
readonly THREAD: "thread";
|
|
532
|
+
readonly PAVE: "pave";
|
|
533
|
+
};
|
|
534
|
+
type CaseShareLane = (typeof CASE_SHARE_LANE)[keyof typeof CASE_SHARE_LANE];
|
|
535
|
+
/**
|
|
536
|
+
* The refusal keys — the `<key>: <sentence>` prefix of a drain
|
|
537
|
+
* `failedReason` and the `code` of a door's refusal:
|
|
538
|
+
* - `MISMATCH` — the claimed lane is not the receiving team's (a browser on
|
|
539
|
+
* an older composer, a carried method state, a forged body). Permanent.
|
|
540
|
+
* - `TEAM_UNAVAILABLE` — the team the share names is gone or no longer
|
|
541
|
+
* active. Permanent: the advocate chooses the team again.
|
|
542
|
+
* - `UNVERIFIED` — what decides the lane (the teams, the configured default
|
|
543
|
+
* share team, or the agency's apps for the LEADS-only reading) could not
|
|
544
|
+
* be read. Retryable.
|
|
545
|
+
*/
|
|
546
|
+
declare const CASE_SHARE_LANE_FAILURE: {
|
|
547
|
+
readonly MISMATCH: "case_share_lane_mismatch";
|
|
548
|
+
readonly TEAM_UNAVAILABLE: "case_share_team_unavailable";
|
|
549
|
+
readonly UNVERIFIED: "case_share_lane_unverified";
|
|
550
|
+
};
|
|
551
|
+
type CaseShareLaneFailureCode = (typeof CASE_SHARE_LANE_FAILURE)[keyof typeof CASE_SHARE_LANE_FAILURE];
|
|
552
|
+
interface CaseShareLaneFailure {
|
|
553
|
+
readonly code: CaseShareLaneFailureCode;
|
|
554
|
+
readonly message: string;
|
|
555
|
+
}
|
|
556
|
+
/** A receiving team as the rule reads it. */
|
|
557
|
+
interface CaseShareLandingTeam {
|
|
558
|
+
readonly id: string;
|
|
559
|
+
readonly name: string;
|
|
560
|
+
/** Declared apps (strict uppercase PLATFORM_TOOL codes); the FIRST lands. */
|
|
561
|
+
readonly apps?: readonly unknown[] | null;
|
|
562
|
+
/** The account's declared default team (Admin Hub "Default team"). */
|
|
563
|
+
readonly defaultTeam?: boolean;
|
|
564
|
+
}
|
|
565
|
+
/** The answer of the rule: a lane, or why there is none. */
|
|
566
|
+
type CaseShareLanding = {
|
|
567
|
+
readonly ok: true;
|
|
568
|
+
readonly lane: CaseShareLane;
|
|
569
|
+
/** The receiving team, or null when none resolved. */
|
|
570
|
+
readonly team: CaseShareLandingTeam | null;
|
|
571
|
+
} | ({
|
|
572
|
+
readonly ok: false;
|
|
573
|
+
} & CaseShareLaneFailure);
|
|
574
|
+
/** The receiving team as resolved: a team, none, a stale named id, unread. */
|
|
575
|
+
type CaseShareReceivingTeam = CaseShareLandingTeam | null | "stale" | "unverified";
|
|
576
|
+
/** The refusal for a named team that is gone or no longer active. */
|
|
577
|
+
declare function caseShareStaleTeamFailure(name: string | undefined): CaseShareLaneFailure;
|
|
578
|
+
/** The refusal when what decides the lane cannot be read. */
|
|
579
|
+
declare function caseShareLaneUnverified(name: string | undefined): CaseShareLaneFailure;
|
|
580
|
+
/**
|
|
581
|
+
* Whether the landing depends on the AGENCY's apps: no team resolved, or a
|
|
582
|
+
* team declaring no app — the only cases the LEADS-only reading decides.
|
|
583
|
+
* A door that cannot read the apps answers "unverified" only then.
|
|
584
|
+
*/
|
|
585
|
+
declare function caseShareLandingNeedsAgencyApps(team: CaseShareReceivingTeam): boolean;
|
|
586
|
+
/**
|
|
587
|
+
* The DEFAULT SHARE TEAM when a share names no team — canon's
|
|
588
|
+
* single-organization ladder (`resolveDefaultShareTeamMono`, monolith
|
|
589
|
+
* L346163-346255 @ c2900116): the admin-configured team, else the one
|
|
590
|
+
* declared default team (more than one declared is ambiguous and skipped),
|
|
591
|
+
* else the only team, else — when `inApp` is given — the only / first team in
|
|
592
|
+
* that app, else the first team by id. `null` only when there are no teams.
|
|
593
|
+
* The landing rule reads it with no app (canon passes `app = null` at
|
|
594
|
+
* landing); the intake-team resolver with the PAVE app.
|
|
595
|
+
*/
|
|
596
|
+
declare function pickDefaultShareTeam<T extends CaseShareLandingTeam>(teams: readonly T[], configuredDefaultShareTeamId: string | null, inApp?: (team: T) => boolean): {
|
|
597
|
+
readonly team: T;
|
|
598
|
+
readonly via: DefaultShareTeamVia;
|
|
599
|
+
} | null;
|
|
600
|
+
type DefaultShareTeamVia = "configured" | "account_declared" | "auto_single" | "auto_single_in_app" | "first_in_app" | "first_team";
|
|
601
|
+
/**
|
|
602
|
+
* The lane a CaseShare lands on with its receiving team (the one named, or the
|
|
603
|
+
* organization's default share team), or why there is none:
|
|
604
|
+
* - the team's first app THREAD → Thread; PAVE → PAVE; LEADS → Thread (the
|
|
605
|
+
* recorded deviation);
|
|
606
|
+
* - no team, or a team with no app → PAVE (canon's fallback) — except a
|
|
607
|
+
* LEADS-only agency → Thread (the deviation), which needs the agency's
|
|
608
|
+
* apps: when they could not be read (`agencyAppsUnread`) the answer is
|
|
609
|
+
* unverified;
|
|
610
|
+
* - any other first app → PAVE (canon's clamp);
|
|
611
|
+
* - a stale named team, or an unreadable directory → refused.
|
|
612
|
+
*/
|
|
613
|
+
declare function caseShareLandingLane(recipient: {
|
|
614
|
+
/** The recipient agency's display name (for the message). */
|
|
615
|
+
readonly name?: string;
|
|
616
|
+
/** The recipient agency's directory `apps` (the LEADS-only reading). */
|
|
617
|
+
readonly agencyApps?: unknown;
|
|
618
|
+
/** The agency's apps could not be read (failed or ambiguous). */
|
|
619
|
+
readonly agencyAppsUnread?: boolean;
|
|
620
|
+
readonly team: CaseShareReceivingTeam;
|
|
621
|
+
}): CaseShareLanding;
|
|
622
|
+
/** The refusal for a CLAIMED lane that is not the landing one. */
|
|
623
|
+
declare function caseShareLaneMismatch(recipient: {
|
|
624
|
+
readonly name?: string;
|
|
625
|
+
readonly team: CaseShareLandingTeam | null;
|
|
626
|
+
}, landing: CaseShareLane, claimed: CaseShareLane): CaseShareLaneFailure | null;
|
|
627
|
+
|
|
628
|
+
/**
|
|
629
|
+
* Lifted unchanged from Thread `@thread/shared` `services/roiPosture.ts` (the
|
|
630
|
+
* whole module, L1-L268) @ thread develop f021be2. The share-gate rule the
|
|
631
|
+
* composer and every send door apply is L165-L268 (`senderRoiPostureForTeam`,
|
|
632
|
+
* `resolveAgencyRoiPosture`, `resolveSenderRoiPosture`); L1-L164 (the posture
|
|
633
|
+
* types and canon's read of the stored `roiPolicy` slice,
|
|
634
|
+
* `readAuthoredRoiPosture`) moved with it because L165-L268 is typed by and
|
|
635
|
+
* fed from them. Its one Thread import, `vspReleasePosture`, moved too.
|
|
636
|
+
*
|
|
637
|
+
* NOTE: `"required" | "waived"` here is the account's release POSTURE (canon
|
|
638
|
+
* `ROI_POLICY_POSTURES`), not a share's release BASIS — CVC-331's retirement
|
|
639
|
+
* of the basis `waived` does not reach it.
|
|
640
|
+
*
|
|
641
|
+
* Pure: no mongoose, no I/O, no SOT import. Thread's module note follows.
|
|
642
|
+
*
|
|
643
|
+
* The SENDING account's release posture — "does a share from this account
|
|
644
|
+
* need a signed release on file?" — read PURELY from the platform agency
|
|
645
|
+
* row's fields (th-u142w). No I/O: the API reads the row
|
|
646
|
+
* (`apps/api/src/helpers/roi-requirement.ts`) and calls these; the ROI basis
|
|
647
|
+
* ladder (`shareRoiBasis.ts`) and the share composer consume the answer.
|
|
648
|
+
*
|
|
649
|
+
* ## The ladder — canon `roiPostureFor`
|
|
650
|
+
*
|
|
651
|
+
* Canon (prototype `d85f05b7`, `HTI-LEADS-PAVE-Thread-prototype.html`
|
|
652
|
+
* L329214-L329319; the platform resolver `HTI_SHARE_POLICY_API.roiPostureFor`,
|
|
653
|
+
* platform-prototype `a6f1f3a5` `src/data.js` L51848-L51904; GDR § 5.17
|
|
654
|
+
* amendment 2026-08-19, `GLOBAL_DESIGN_RULES.md` L3728-L3756):
|
|
655
|
+
*
|
|
656
|
+
* 1. AUTHORED wins, in BOTH directions — the account's
|
|
657
|
+
* `policies.roiPosture.agencyDefault` (`"required" | "waived"`; null /
|
|
658
|
+
* absent = un-authored), authored in Platform Admin Hub → Policies →
|
|
659
|
+
* Consent & ROI (platform-prototype `src/screens.jsx` L15009-L15074,
|
|
660
|
+
* `ConsentRoiTab`).
|
|
661
|
+
* 2. else DERIVED from the AFFIRMED directory VSP flag (canon
|
|
662
|
+
* VSP-TRISTATE-2026-10-08, L329259-L329272): `false` → waived; `true`
|
|
663
|
+
* and never-captured → required (`vspReleasePosture`).
|
|
664
|
+
* 3. a team override may only TIGHTEN — `teamOverrides[teamId] ===
|
|
665
|
+
* "required"` upgrades a waived posture; nothing downgrades required
|
|
666
|
+
* (L329306-L329310; CAM invariants 3/6).
|
|
667
|
+
*
|
|
668
|
+
* ## Deviation from canon at the share gate — the team rung (ruled, th-u142w)
|
|
669
|
+
*
|
|
670
|
+
* Rungs 1–2 and the bad-value reading match canon exactly. Rung 3 does NOT:
|
|
671
|
+
* canon's resolver has it, but canon's GATING sites call
|
|
672
|
+
* `senderAgencyRequiresROI()` with no team (L337935, L338110 →
|
|
673
|
+
* `roiPostureFor(undefined)`), so canon never applies a team override at
|
|
674
|
+
* the share gate. Thread applies it, keyed by the SENDING record's
|
|
675
|
+
* `teamOwner`, at every send door and in the composer — as PAVE does
|
|
676
|
+
* (`shareRecordService.ts` L3097-L3102 @ pave-2.0 `0ae6c7f0e`: "The posture
|
|
677
|
+
* ladder's team override is the SENDING team's"), so Thread and PAVE answer
|
|
678
|
+
* identically. It only ever TIGHTENS (waived → required), never relaxes.
|
|
679
|
+
* Recorded in CATALOG.md ShareComposer Known deviations #24 and
|
|
680
|
+
* packages/shared CLAUDE.md edge case 41 (coordinator ruling 2026-10-13).
|
|
681
|
+
*
|
|
682
|
+
* Legal-override purposes keep their own rule: the exemption is the
|
|
683
|
+
* CALLER's (canon L329241-L329247: "This function does not know about
|
|
684
|
+
* purposes and must not be taught to") — the basis ladder's rung 2.
|
|
685
|
+
*
|
|
686
|
+
* ## How a bad stored value reads — exactly canon's reading
|
|
687
|
+
*
|
|
688
|
+
* Canon reads the slice with strict equality and nothing else, so a value
|
|
689
|
+
* outside the shape simply does not count (coordinator ruling 2026-10-13:
|
|
690
|
+
* Thread gives the same answer as canon, the platform and PAVE for the same
|
|
691
|
+
* data):
|
|
692
|
+
*
|
|
693
|
+
* - `agencyDefault`: `(tabDoc.agencyDefault === "required" ||
|
|
694
|
+
* tabDoc.agencyDefault === "waived") ? tabDoc.agencyDefault : null`
|
|
695
|
+
* (monolith L329297-L329298; platform `data.js` L51883) — anything else
|
|
696
|
+
* is UN-AUTHORED and the VSP rung decides.
|
|
697
|
+
* - a team: `(tabDoc.teamOverrides || {})[teamId] === "required"`
|
|
698
|
+
* (monolith L329306; `data.js` L51899) — any other value IGNORES that
|
|
699
|
+
* team (it never tightens and, since a team can only tighten, it can
|
|
700
|
+
* never widen either).
|
|
701
|
+
* - a slice that is not an object reads neither (`"waived".agencyDefault`
|
|
702
|
+
* is `undefined`; the slice is read as `(p && p.roiPosture) || null`,
|
|
703
|
+
* L329287): un-authored, no team overrides.
|
|
704
|
+
*
|
|
705
|
+
* Every such value is reported in `issues` (coded, never the value) so the
|
|
706
|
+
* reader can log it — a malformed slice is a platform-writer defect worth
|
|
707
|
+
* seeing, not a silent no-op.
|
|
708
|
+
*
|
|
709
|
+
* ## Where the authored posture lives
|
|
710
|
+
*
|
|
711
|
+
* The platform writer (platform `lib/agency-consent/repository.ts`
|
|
712
|
+
* `setRoiPolicy`, schema `lib/agency-consent/schemas.ts` `RoiPolicySchema`,
|
|
713
|
+
* route `app/api/admin/agency-consent/route.ts` @ platform develop
|
|
714
|
+
* `31df78d`) stores canon's `policies.roiPosture` slice as
|
|
715
|
+
* `platform-db.agencies.<agency>.roiPolicy = { agencyDefault, teamOverrides }`
|
|
716
|
+
* — the SAME row Thread already reads `vsp` from. Thread reads it there,
|
|
717
|
+
* READ-ONLY, and never writes it. Team-override KEYS are the platform's team
|
|
718
|
+
* ids (`listAgencyTeams`: a `teams` row's `entity_id`, else `id`, else
|
|
719
|
+
* `String(_id)`); the API translates them to the `teams._id` hex a Thread
|
|
720
|
+
* record's `teamOwner` holds before they reach `SenderRoiPostureView`.
|
|
721
|
+
*/
|
|
722
|
+
/**
|
|
723
|
+
* The release posture the affirmed flag implies (canon L329146): only an
|
|
724
|
+
* affirmed `false` waives; `true` and never-captured both require one.
|
|
725
|
+
*
|
|
726
|
+
* Moved with this module from Thread `@thread/shared`
|
|
727
|
+
* `services/agencyVspSignal.ts` L93-L101 @ thread develop f021be2, unchanged
|
|
728
|
+
* (a one-line pure function; the affirmed-flag reader `affirmedAgencyVsp`
|
|
729
|
+
* stays with each app's agency read).
|
|
730
|
+
*/
|
|
731
|
+
declare function vspReleasePosture(affirmed: boolean | null): "required" | "waived";
|
|
732
|
+
/** The two authored postures (canon `ROI_POLICY_POSTURES`). */
|
|
733
|
+
type RoiReleasePosture = "required" | "waived";
|
|
734
|
+
/** The platform agency-row field this read consults (`agencies.roiPolicy`). */
|
|
735
|
+
declare const AUTHORED_ROI_POSTURE_FIELD = "roiPolicy";
|
|
736
|
+
/** A stored value canon would not count — coded, never the value itself. */
|
|
737
|
+
type AuthoredRoiPostureIssue = "roi_policy_not_object" | "agency_default_invalid" | "team_overrides_not_object" | "team_override_value_invalid";
|
|
738
|
+
/** The authored posture, as canon reads it off the agency row. */
|
|
739
|
+
interface AuthoredRoiPostureRead {
|
|
740
|
+
/** A `roiPolicy` value is stored at all (well-formed or not). */
|
|
741
|
+
readonly present: boolean;
|
|
742
|
+
/** `null` = un-authored — the VSP rung decides. */
|
|
743
|
+
readonly agencyDefault: RoiReleasePosture | null;
|
|
744
|
+
/** The platform team keys whose value is exactly `"required"`. */
|
|
745
|
+
readonly requiredTeamKeys: readonly string[];
|
|
746
|
+
/** Values canon ignored (for the reader's warn log). Empty when clean. */
|
|
747
|
+
readonly issues: readonly AuthoredRoiPostureIssue[];
|
|
748
|
+
}
|
|
749
|
+
declare const ABSENT_AUTHORED_ROI_POSTURE: AuthoredRoiPostureRead;
|
|
750
|
+
/**
|
|
751
|
+
* Read a stored `roiPolicy` value the way canon does (see the module header).
|
|
752
|
+
* Total — never throws.
|
|
753
|
+
*/
|
|
754
|
+
declare function readAuthoredRoiPosture(raw: unknown): AuthoredRoiPostureRead;
|
|
755
|
+
/** Which rung decided — the administrator-facing "why". */
|
|
756
|
+
type SenderRoiPostureSource = "authored" | "derived_vsp" | "team_override";
|
|
757
|
+
interface SenderRoiPosture {
|
|
758
|
+
readonly posture: RoiReleasePosture;
|
|
759
|
+
/** `posture === "required"`. */
|
|
760
|
+
readonly required: boolean;
|
|
761
|
+
readonly source: SenderRoiPostureSource;
|
|
762
|
+
/** The derived (VSP) default, whatever decided. */
|
|
763
|
+
readonly derivedDefault: RoiReleasePosture;
|
|
764
|
+
/** Coded rule path (no ids beyond a team id; no PII). */
|
|
765
|
+
readonly rulePath: string;
|
|
766
|
+
}
|
|
767
|
+
/**
|
|
768
|
+
* The account's posture with the team rung NOT yet applied, plus the teams
|
|
769
|
+
* that tighten it — the shape the server hands the composer, so both apply
|
|
770
|
+
* the team rung with ONE function (`senderRoiPostureForTeam`).
|
|
771
|
+
* `tightenedTeamIds` are in the id space of the team the caller will pass
|
|
772
|
+
* (the API translates platform keys to `teams._id` hex first).
|
|
773
|
+
*/
|
|
774
|
+
interface SenderRoiPostureView {
|
|
775
|
+
readonly agency: SenderRoiPosture;
|
|
776
|
+
readonly tightenedTeamIds: readonly string[];
|
|
777
|
+
}
|
|
778
|
+
/** Rungs 1–2: authored > the affirmed VSP default. Pure and total. */
|
|
779
|
+
declare function resolveAgencyRoiPosture(input: {
|
|
780
|
+
readonly authored: AuthoredRoiPostureRead;
|
|
781
|
+
/** The AFFIRMED VSP flag (`affirmedAgencyVsp`) — null = never captured. */
|
|
782
|
+
readonly affirmedVsp: boolean | null;
|
|
783
|
+
}): SenderRoiPosture;
|
|
784
|
+
/**
|
|
785
|
+
* Rung 3: a team override only TIGHTENS a waived posture — applied at the
|
|
786
|
+
* share gate as PAVE does, a recorded DEVIATION from canon's gating sites,
|
|
787
|
+
* which pass no team at all (see the module header). Absent team ⇒ the rung
|
|
788
|
+
* is skipped (canon's gating behaviour, and PAVE's resolver with
|
|
789
|
+
* `teamId === undefined`).
|
|
790
|
+
*/
|
|
791
|
+
declare function senderRoiPostureForTeam(view: SenderRoiPostureView, sendingTeamId?: string | null | undefined): SenderRoiPosture;
|
|
792
|
+
interface ResolveSenderRoiPostureInput {
|
|
793
|
+
readonly authored: AuthoredRoiPostureRead;
|
|
794
|
+
readonly affirmedVsp: boolean | null;
|
|
795
|
+
/**
|
|
796
|
+
* The sending team, in the SAME id space as the authored team keys. Absent
|
|
797
|
+
* ⇒ the team rung is skipped.
|
|
798
|
+
*/
|
|
799
|
+
readonly sendingTeamId?: string | null | undefined;
|
|
800
|
+
}
|
|
801
|
+
/** The whole ladder over one id space (authored keys = team ids). */
|
|
802
|
+
declare function resolveSenderRoiPosture(input: ResolveSenderRoiPostureInput): SenderRoiPosture;
|
|
803
|
+
|
|
804
|
+
export { ABSENT_AUTHORED_ROI_POSTURE, AUTHORED_ROI_POSTURE_FIELD, type AuthoredRoiPostureIssue, type AuthoredRoiPostureRead, CASE_SHARE_LANE, CASE_SHARE_LANE_FAILURE, type CaseShareLanding, type CaseShareLandingTeam, type CaseShareLane, type CaseShareLaneFailure, type CaseShareLaneFailureCode, type CaseShareReceivingTeam, type DefaultShareTeamVia, LEGACY_RELEASE_METHOD_ALIASES, MAGIC_LINK_MAX_ADDRESSES, type MagicLinkContact, type MagicLinkPocAddresses, RELEASE_METHOD, RELEASE_METHOD_VALUES, RETIRED_RELEASE_METHODS, ROI_BASIS_REASON_ROI_ON_FILE, ROI_WAIVER_EXEMPT_PURPOSES, type RecipientPlatformSnapshot, type ReleaseMethodValue, type ReleaseTerms, type ResolveSenderRoiPostureInput, type RoiReleasePosture, SHARING_METHOD, SHARING_METHOD_LABELS, SHARING_METHOD_VALUES, STORED_RELEASE_METHOD_VALUES, type SenderRoiPosture, type SenderRoiPostureSource, type SenderRoiPostureView, type ShareExpiryDecision, type SharingMethodValue, agencyIdKey, caseShareLandingLane, caseShareLandingNeedsAgencyApps, caseShareLaneMismatch, caseShareLaneUnverified, caseShareStaleTeamFailure, derivesOffPlatformRecipient, endOfUtcDay, isBrokeredSharingMethod, isReleaseMethod, isReleaseMethodExemptPurpose, isReleaseTermsExemptRecipient, isRoiWaiverExemptPurpose, magicLinkAddressOverflow, magicLinkAddresses, magicLinkConfidentialOnly, magicLinkConfidentialOverflow, magicLinkPocHasVisibleAddress, magicLinkToText, normalizeReleaseMethod, operativeReleaseOf, pickDefaultShareTeam, readAuthoredRoiPosture, readReleaseMethods, recipientPlatformFromApps, recipientUsesApp, releaseEndDay, releaseEndOfDay, releaseListWords, releaseListedMethods, releaseMethodLabel, releaseMethodOfShareMethod, releaseMethodRefusal, resolveAgencyRoiPosture, resolveSenderRoiPosture, senderRoiPostureForTeam, shareExpiryUnderRelease, shareMethodOf, sharingMethodLabel, sharingMethodOfReleaseMethod, teamLandingApp, teamLandsInPave, teamLandsInThread, utcCalendarDay, vspReleasePosture };
|