@htilabs/platform-common-models 0.29.0 → 0.32.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 CHANGED
@@ -16,6 +16,378 @@ Package exports are organized into a public root API and a small number of
16
16
  dedicated subpaths (`/validation`, `/cvcs`) — consult `package.json` for the
17
17
  authoritative `exports` map.
18
18
 
19
+ ## points-of-contact / 0.32.0
20
+
21
+ 0.32.0 (pl-iza) is additive: confidential Referrals (magic link) holders
22
+ receive magic links, and the sender sees only how many. Canon: CVC-338
23
+ `REFERRALS_MAGIC_LINK` (prototype `data/cvcs/core_contact_purpose.yaml` @
24
+ 184893b6 L95), "A confidential holder still receives it; the sender never
25
+ sees the address."; HANDOFF.md @ 184893b6 L569, L575 (POC-PROFILE-ALIGNMENTS
26
+ D(ii)). Ruling: Nate, 2026-10-15. (0.31.0 is claimed by PR #219.)
27
+
28
+ - **The network view is unchanged.** A confidential row is still absent from
29
+ every view another organization sees (`toNetworkView`, `getContact`,
30
+ `listContactsForSubject`, the referral `recipients` and `unreachable`).
31
+ - **`listReferralContactsForPartner`** keeps its signature. Its result gains
32
+ `confidentialCount: number`, the number of distinct confidential holder
33
+ addresses, for the sender's "+ 1 confidential recipient" / "N confidential
34
+ recipients" line. `unreachable` is unchanged: ids of VISIBLE contacts only,
35
+ safe to show a sender.
36
+ - **`resolveMagicLinkRecipients(db, partner, opts)`** (send-only, same
37
+ options) returns `MagicLinkSendList`: `{ recipients, unreachable,
38
+ confidential, confidentialUnreachableCount }`, where `confidential` is a
39
+ `ConfidentialReferralRecipients` (an interface, exported as a type only).
40
+ The implementation is not exported: obtain values only via
41
+ `resolveMagicLinkRecipients`. `confidentialUnreachableCount` is a
42
+ SERVER-SIDE diagnostic, never returned to a sender: confidential holder rows
43
+ that cannot be sent to (no email, a seat with none or not found), plus
44
+ skipped rows that do not match the contract and may be confidential.
45
+ - **`ConfidentialReferralRecipients`**: its implementation carries the
46
+ addresses in a private field. Public: `count`; `toJSON()` → `{ count }`;
47
+ `util.inspect` →
48
+ `ConfidentialReferralRecipients(n)`; and `deliver(sendOne, { capacity? })`
49
+ → `{ count, delivered, failed, overflow, firstErrorName }`. `deliver` sends
50
+ to the first `capacity` holders (all when omitted), one at a time;
51
+ `overflow` is `max(0, count - capacity)`. It catches every `sendOne` error,
52
+ keeping only its `name` ("Error" when the name is not a plain identifier or
53
+ cannot be read), and never rejects for a failed send. `sendOne` is
54
+ `(address: string) => void | Promise<void>` and must THROW (or reject) on
55
+ failure: returning normally counts as delivered.
56
+ - **What a sender may see.** Only `count` (or `confidentialCount`), or one
57
+ all-or-nothing status. `delivered`, `failed`, `overflow` and
58
+ `firstErrorName` are server-side, for audit only.
59
+ - **Has a holder.** A partner has a magic-link holder when
60
+ `recipients.length + confidentialCount > 0`. Canon D(ii): a confidential
61
+ holder is a holder, so the listing-contact fallback does not fire over it,
62
+ and the send must not refuse a partner whose only holders are confidential.
63
+ - **Which rows count.** Active, `confirmed`, `is_confidential: true`, tagged
64
+ Referrals (magic link), on the same rollup (the partner's agency and its
65
+ programs, teams and locations, its service listings, and its org), at the
66
+ preferred email (the seat's for a seat-linked holder). A separate query; the
67
+ visible and own-pending queries are unchanged, and no index changes. Seats
68
+ are resolved once per read, over the visible and confidential rows
69
+ together. A pending confidential row is not routed until it is confirmed;
70
+ an inactive or untagged one never is. A row that does not match the
71
+ contract and may be confidential (in the confidential query, or a visible
72
+ or pending row whose stored `is_confidential` is malformed, e.g. `"true"`
73
+ or `1`, which matches `{ $ne: true }`) is skipped and counted in
74
+ `confidentialUnreachableCount`, never thrown (its error would name its id),
75
+ so it never blocks the visible sends. Any other corrupt row still throws.
76
+ - **De-duplication is oracle-safe.** Confidential addresses are deduped
77
+ among THEMSELVES only: `confidentialCount` is the number of distinct
78
+ confidential addresses, and no visible, pending, typed or added address
79
+ moves it. `deliver` takes no caller addresses at all. Otherwise an advocate
80
+ could learn an address by watching a number change: adding or typing it,
81
+ or seeing their pending add confirmed by a steward or a visible seat's
82
+ email edited to match. An overlap with any other recipient is simply sent
83
+ twice: the holder gets a duplicate link, which the advocate cannot observe.
84
+ - **Store counts only.** A share, receipt, event or log carries
85
+ `confidential.count` (or `confidentialCount`), never an id or an address.
86
+ - **The transport must not log `to`.** Every address `sendOne` receives is a
87
+ confidential one. Thread's SES dev transport logs the recipient
88
+ (`apps/api/src/services/ses/client.ts` @ 029d91a95 L122-L140, `to:
89
+ args.to` at L128): a confidential send must not go through it as is.
90
+ - **Lower tiers.** On a lower-tier deployment, confidential holders redirect
91
+ to the advocate like every other recipient (the caller's existing redirect
92
+ applies to the address `sendOne` receives). A redirected message must not
93
+ name the address it was meant for: a redirect banner or header that lists
94
+ the original recipients shows "1 confidential recipient" instead.
95
+
96
+ ```ts
97
+ import { resolveMagicLinkRecipients } from "@htilabs/platform-common-models/points-of-contact";
98
+
99
+ const send = await resolveMagicLinkRecipients(platformDb, partner, {
100
+ resolveSeats,
101
+ includeOwnPendingFor: verifiedToken.sub, // the advocate's own pending adds, marked `pending`
102
+ });
103
+ if (send.recipients.length + send.confidential.count === 0) {
104
+ // no magic-link holder: the listing-contact fallback applies
105
+ }
106
+ // The visible picks (pre-filled, own-pending, typed), deduped among themselves.
107
+ const visible = [...new Set([...pickedRecipients.map((r) => r.email), ...typedAddresses])];
108
+ for (const to of visible) await mailer.sendMagicLink(to); // throws on failure
109
+ // The confidential holders: the same mailer, which must throw on failure and never log `to`.
110
+ const audit = await send.confidential.deliver((to) => mailer.sendMagicLink(to), {
111
+ capacity: Math.max(0, MAX_SENDS - visible.length),
112
+ });
113
+ share.magic_link_confidential = send.confidential.count; // a count, never an address
114
+ log.info(
115
+ { confidential: audit, confidentialUnreachable: send.confidentialUnreachableCount },
116
+ "magic link sent",
117
+ ); // server-side audit numbers only, never returned to the sender
118
+ ```
119
+
120
+ ## points-of-contact / 0.30.0 (BREAKING)
121
+
122
+ 0.30.0 (pl-e98, pl-f4c) reshapes the Point of contact contract. There is no
123
+ prod data, so it is a clean cut: no legacy acceptance, no read shim for the
124
+ stored single fields, no migration (Nate, 2026-10-15). Every consumer
125
+ (platform writer and editor, Thread, PAVE) changes in its own lane.
126
+
127
+ **pl-f4c: a site is stored `location`, displayed "Site".** The UDD names the
128
+ object Site, but its stored names, ids and columns stay `location` (schema of
129
+ record hti-features `udd-schemas/location/Location.v1.json`; canon
130
+ `ORG_STACK_DATA_OBJECTS_2026-10-01.md` @ fa0fd0b0 L236). `POC_SUBJECT_TYPES`
131
+ is now `agency · org · program · team · location · service`. **`site` is now
132
+ refused** everywhere: owner schema, stored row (reads throw) and
133
+ `PocSubjectRef`. New: `POC_SUBJECT_TYPE_LABELS` / `pocSubjectTypeLabel`
134
+ (`location` → "Site").
135
+
136
+ **pl-e98: a contact holds `emails[]` and `phones[]`.** Crysta's 2026-08-24
137
+ multi-entry correction. Canon's Admin Hub ledger stores each address as
138
+ `{type, value, preferred}` (platform-prototype `src/agencyhub.jsx` @ 6f428116
139
+ `methodsFor` L8107-L8132, the save L8181); here the type is the list.
140
+
141
+ ```ts
142
+ // StoredContactEntrySchema; PocContactEntry = z.infer<typeof StoredContactEntrySchema>
143
+ interface PocContactEntry {
144
+ value: string; // email (lowercased) or phone as typed (trimmed)
145
+ is_preferred: boolean; // the CONTACT rail's flag (ObjectDirectoryEntry.mjs @ fa0fd0b0 L52)
146
+ }
147
+ ```
148
+
149
+ The contact-level `is_primary` (the subject's primary contact) is unrelated
150
+ and unchanged. There is no per-entry use label: CVC-154
151
+ `contact_info_use_type` is investigative-only, and canon's pickers give PAVE
152
+ and Thread no codes and the Platform no picker at all
153
+ (`data/cvcs/core_contact_info_use_type.yaml` @ fa0fd0b0 L93-L97).
154
+
155
+ - **The preferred rule (writers).** `PocEmailListSchema` / `PocPhoneListSchema`
156
+ accept `{ value, is_preferred? }` entries: at most one marked preferred, and
157
+ the list is normalized to exactly one (the marked entry, else the first:
158
+ canon L8126-L8129). The same email twice, the same phone line twice (by
159
+ digits, canon's `phoneDigits`), or a phone with no digit is refused. At most
160
+ `POC_MAX_CONTACT_ENTRIES` (10) per list. A list in an edit replaces the
161
+ stored list; **clearing is `emails: []`, `null` is refused**.
162
+ - **Phones are stored as typed, trimmed**, as this object's canon writer, the
163
+ Admin Hub ledger, stores them (`agencyhub.jsx` @ 6f428116 L8124-L8125,
164
+ L8173, L8511-L8518). `pocPhoneDigits` (canon's `phoneDigits`,
165
+ `leads-app/server/objectStructuresEngine.generated.mjs` @ fa0fd0b0
166
+ L282-L286) is the duplicate key only. **Accepted: an extension makes a
167
+ distinct line** (`402-677-3902 x5` and `402-677-3902` differ by digits, so
168
+ both may sit on one contact). `formatPocPhone` mirrors canon's `formatPhone`
169
+ (L246-L256) as a **display-only** helper readers apply; canon calls it
170
+ "display only" (L229-L245). It is lossy and is never written back.
171
+ - **Stored lists are read leniently.** `PointOfContactDocSchema` repairs a
172
+ stored list the same way (emails trimmed and lowercased, empty and repeated
173
+ entries dropped, a missing or null `is_preferred` read as false, no
174
+ preferred → the first, several → the first marked), so one row never takes
175
+ down a partner's read. Only structurally invalid data (not an array, a
176
+ non-object entry, a non-string value, a non-boolean flag) throws.
177
+ - **Read helpers:** `preferredContactEntry(list)`, `preferredEmail(contact)`,
178
+ `preferredPhone(contact)`, over a stored row or any view. Every view also
179
+ carries read-only `email` / `phone`: the reachable preferred address (the
180
+ seat's for a seat-linked contact). Views hold copies, never the row's arrays.
181
+ - `pocIdentityKey` keys a write-in on its name and its **preferred** email.
182
+ - `listReferralContactsForPartner` sends to each tagged contact's
183
+ **preferred** email (the view's `email`), deduped on it. A seat's email is
184
+ trimmed and lowercased first.
185
+ - **Body-builder types:** `PocDetailsInput`, `PocInAppInput`, `PocSeedInput`,
186
+ `PocPatchInput` (`z.input` of the schemas: defaulted fields optional).
187
+
188
+ **Upgrading the platform to 0.30.0:**
189
+
190
+ - **No data existed before 0.30.0; no migration.** No platform database has
191
+ a `pointsofcontact` collection (platform-prod, -db, -dev, -test and -train
192
+ checked 2026-10-15), so there are no 0.28.0 rows and no old indexes to
193
+ drop. `ensurePocIndexes` (below) only creates indexes.
194
+ - **HTTP wire change.** `PocInAppSchema` is the body of
195
+ `POST /api/partner-contacts`. A caller sends `emails: [{ value }]` (at
196
+ least one) and optional `phones`, never `email` / `phone`. Thread and PAVE
197
+ write through `mintPartnerContact` (below) instead of calling it.
198
+ - **The writer maps an identity unique-index collision to a domain error**
199
+ (platform's job).
200
+
201
+ **Thread and PAVE write pending in-app contacts directly via
202
+ `mintPartnerContact`; no HTTP** (pl-bt1, pl-e98). The in-app partner add is
203
+ the platform's `addPartnerContact` (the store behind
204
+ `POST /api/partner-contacts`), moved into this subpath so all three apps run
205
+ one implementation against their own platform-db handle:
206
+
207
+ ```ts
208
+ import { ObjectId } from "mongodb"; // or mongoose.Types.ObjectId
209
+ import { mintPartnerContact } from "@htilabs/platform-common-models/points-of-contact";
210
+
211
+ const r = await mintPartnerContact(
212
+ platformDb, // the deployment's own, long-lived, primary reads
213
+ {
214
+ app: "thread", // a server constant: pave · thread · leads
215
+ partner: { org_id }, // and/or agency_id, from the recipient picker
216
+ contact: { display_name, emails: [{ value }], phones }, // PocInAppInput
217
+ actor: { id: verifiedToken.sub }, // Auth0 `sub`, server-side from the verified token
218
+ },
219
+ { ObjectId },
220
+ );
221
+ if (r.ok) r.value; // PartnerContactReceipt: { id, status, created, subject_type, subject_id, agency_id, org_id }
222
+ else r.reason; // PartnerContactFailureReason; r.status is the HTTP status the platform route answers
223
+ ```
224
+
225
+ - **Same rules, same order, same codes as the platform store.** Actor
226
+ (`actor_required`), app (`invalid_app`), strict `PocInAppSchema` body
227
+ (`invalid_contact`; Referrals (magic link) always added first), strict
228
+ `PartnerContactSelectorSchema` (`invalid_partner`); the partner resolved to
229
+ `String(agencies._id)` / `String(organizations._id)` in any accepted form,
230
+ a mapped `registry_agencies` row included, an org with a genuine-mirror
231
+ agency rewritten onto the agency (`owner_not_found`, `owner_mismatch`); a
232
+ canonical singleton or PAVE 2.0-shape org refused (`canonical_org`,
233
+ `foreign_row_shape`). Then the existing rows answer, matched on the
234
+ package identity rule (`pocIdentityKey`: `writein:<name>|<preferred
235
+ email>`, trimmed and lowercased): a visible tagged contact, or the caller's
236
+ own pending add (`created: false`, nothing written); the caller's own
237
+ removed add is `contact_deactivated`. The caller's outstanding pending adds are capped at
238
+ `POC_IN_APP_PENDING_CAP_PER_PARTNER` (5) per partner and
239
+ `POC_IN_APP_PENDING_CAP_PER_ACTOR` (25) overall (`too_many_pending_adds`,
240
+ 429). The writer then checks the indexes it relies on
241
+ (`checkPocIndexes`: refuses `indexes_missing`, 503) and the row lands
242
+ `pending`, `origin: in_app`, `added_in_app: <app>`, version 1. A raced
243
+ identical add (`duplicate_pending_add` on
244
+ `POC_IN_APP_PENDING_INDEX`) answers with the winner's row. Every code is in
245
+ `PARTNER_CONTACT_FAILURE_REASONS`.
246
+ - **Returns, never throws, a domain refusal; logs nothing.** No message
247
+ carries a stored value (a driver's duplicate-key message echoes the email,
248
+ so it is never returned). A read or write error, or a stored row that does
249
+ not parse (`PointOfContactShapeError`), propagates.
250
+ - **Dedupe is by identity, never by a shared mailbox** (ruling 2026-10-15).
251
+ The interim platform rule "shares ANY email" (matcher `$in` on
252
+ `emails.value`, multikey pending index) is a defect, reproduced on a real
253
+ MongoDB: with Bob `[bob★, intake@]` listed, an add of Jane `[jane★,
254
+ intake@]` returned Bob's id and Jane was never stored; an adder's pending
255
+ add blocked their next add sharing the mailbox (Dan); and a removed row
256
+ sharing a secondary mailbox refused every later add with a false
257
+ `contact_deactivated` (Eve). Now the matcher and the pending unique index
258
+ both key on the stored scalar `identity_key`, so Jane, Dan and Eve each
259
+ land, while the same name with the same preferred email (whatever its
260
+ other emails) is one person: a retry answers with the first row, and a race
261
+ of the two recovers through `duplicate_pending_add` to the winner.
262
+ - **The pieces the platform store imports** (so the index and the matcher can
263
+ never disagree, which the race recovery depends on):
264
+ `POINT_OF_CONTACT_INDEXES.inAppPending` / `.pendingQueue` (aliased
265
+ `POC_IN_APP_PENDING_INDEX` / `POC_PENDING_QUEUE_INDEX`),
266
+ `POC_IN_APP_PENDING_INDEX_KEY` (`agency_id, subject_type, subject_id,
267
+ identity_key, createdBy`), `POC_IN_APP_PENDING_INDEX_FILTER`,
268
+ `pocRowsWithIdentity(db, subject, identityKey)` (the matcher) and
269
+ `pocDuplicateKeyFailure(err)`
270
+ (E11000 → `duplicate_pending_add` · `primary_exists` · `duplicate_contact`
271
+ · `duplicate_contact_id` · `duplicate_key`, by index name then key pattern;
272
+ null for any other error).
273
+ - **The writer never creates an index (least privilege; fail closed).**
274
+ Before its insert it reads `listIndexes` once per handle
275
+ (`checkPocIndexes`, exported for a readiness probe): the `id` index must be
276
+ unique, and `POC_IN_APP_PENDING_INDEX` must exist with exactly
277
+ `POC_IN_APP_PENDING_INDEX_KEY` (fields, order, direction), `unique: true`
278
+ and exactly `POC_IN_APP_PENDING_INDEX_FILTER`, under any name. A missing
279
+ collection (NamespaceNotFound) or index is `indexes_missing` (503); a pass
280
+ is memoized per handle, a refusal is not.
281
+ - **`ensurePocIndexes(db)` is the PLATFORM's.** It creates the full
282
+ `pointsofcontact` index set (every `POINT_OF_CONTACT_INDEXES` entry,
283
+ `inAppPending` and `pendingQueue` included) with plain `createIndex` calls:
284
+ idempotent, memoized per handle, retried after a failure, a server refusal
285
+ propagated. No migration and no drop. The platform must deploy and run it
286
+ before any Thread or PAVE caller writes; until then every app add is
287
+ `indexes_missing`.
288
+ - **The caps bound a burst.** After its insert each add counts the adder's
289
+ pending rows (per partner, then overall); over the cap it deletes its own
290
+ row and is `too_many_pending_adds`. No more than the cap ever survive (the
291
+ survivor that counted last counted every survivor), on a real server too;
292
+ the price is a spurious 429 under contention (a burst may withdraw rows
293
+ that would have fit; a retry lands). The platform's earlier rank-based
294
+ check let a burst of 12 leave 7-10 rows against a cap of 5. The bound
295
+ needs every count to read the primary (see the caller contract).
296
+
297
+ **Caller contract** (Thread, PAVE, LEADS: everything the package cannot
298
+ check for you):
299
+
300
+ - **Accepted risk: direct writes (Nate, 2026-10-15).** Thread and PAVE write
301
+ pending in-app contacts straight to platform-db through
302
+ `mintPartnerContact`, not through the platform's HTTP route. This widens
303
+ the trust boundary: their database credential needs `insert` and `remove`
304
+ on `pointsofcontact`, and MongoDB privileges cannot scope a write by
305
+ `status`, so a compromised app credential could write any row shape. That
306
+ wider boundary is accepted. The writer itself always writes `status:
307
+ "pending"`, `origin: "in_app"` (no argument names a status, origin or
308
+ owner), and only the platform (its steward confirm, or the partner's own
309
+ editor) ever makes a row `confirmed`.
310
+ - **Actor.** `actor.id` is the advocate's Auth0 `sub`, taken server-side from
311
+ the verified token, as the platform route takes `auth0Sub`. Never a request
312
+ body value, a client header or a `users._id`. `createdBy`, the adder's
313
+ dedupe, caps and removed-add refusal all key on it.
314
+ - **App.** `app` is the caller's own server constant (`"thread"`, `"pave"`),
315
+ never a request value. The caller checks the advocate's token
316
+ `allowed_apps` holds that app, by the deployment's keys: the exact app key,
317
+ plus `<app>_train` only on a training deployment (the platform's
318
+ `PARTNER_ADD_<APP>_APP_KEYS` rule). A training deployment never holds a
319
+ write handle to a production platform-db.
320
+ - **Handle.** The deployment's own platform-db (`mongodb` `Db` or a mongoose
321
+ connection's `.db`), long-lived: the index check is memoized per handle
322
+ object, and `client.db(name)` returns a new object on every call, so call
323
+ it once. Reads must go to the primary (no `secondary*` read preference on
324
+ this handle or its client): the caps' bound and the race recovery read
325
+ what was just written.
326
+ - **Time.** `now` is the server's clock or omitted, never a request value.
327
+ - **Partner.** Pass only the `agency_id` / `org_id` the advocate picked in
328
+ the recipient picker (the same ids the magic-link pre-fill reads), never a
329
+ free-typed or body-supplied subject.
330
+ - **Pre-fill.** To show the advocate their OWN pending adds in the
331
+ magic-link pre-fill, read with
332
+ `listReferralContactsForPartner(db, partner, { resolveSeats,
333
+ includeOwnPendingFor: verifiedToken.sub })` (the same `sub` as the
334
+ writer's `actor.id`). See below.
335
+ - **Confidential holders (pl-iza, 0.32.0).** Never return, persist, or log
336
+ a confidential address; use `confidentialCount` / `confidential.count`;
337
+ only `deliver` touches addresses. A sender sees the count (or one
338
+ all-or-nothing status), never `deliver`'s per-holder numbers. The
339
+ `sendOne` transport must not log `to`.
340
+ - **Logging.** On a thrown error log only its `name` and `code`: a
341
+ `PointOfContactShapeError` lists a stored row's issues and a driver error
342
+ can echo a stored value. Refusals carry no stored value.
343
+ - **Order of deployment.** The platform deploys and runs `ensurePocIndexes`
344
+ first; an app's writes are refused (`indexes_missing`) until it has.
345
+ - **Database privileges** the calling app's user needs on platform-db:
346
+ `find` on `agencies`, `organizations`, `registry_agencies` and
347
+ `pointsofcontact` (`countDocuments` is a `find`); `insert`, `remove` (a
348
+ withdrawn over-cap row) and `listIndexes` on `pointsofcontact`. No
349
+ `createIndex`, `dropIndex`, `update` or any other collection.
350
+
351
+ **The adder's own pending adds in the pre-fill** (Nate, 2026-10-15).
352
+ `listReferralContactsForPartner(db, partner, { resolveSeats,
353
+ includeOwnPendingFor: sub })` returns the partner's confirmed, network-visible
354
+ Referrals (magic link) recipients as before, then the asking advocate's OWN
355
+ pending in-app adds on that partner (active, `origin: in_app`, `createdBy`
356
+ = `sub`, tagged Referrals (magic link)), each marked `pending: true`
357
+ (`ReferralRecipient.pending`) so a UI can label it. Nobody else's pending add
358
+ is ever returned; confidential rows stay excluded (counted only, see 0.32.0); an
359
+ email a confirmed recipient already has is not repeated. `sub` is the
360
+ advocate's Auth0 `sub` from the verified token, the same pinning as the
361
+ writer's `actor.id`. Without the option the read is unchanged.
362
+
363
+ **Known deviations:**
364
+
365
+ - Seat-linked contacts still read ONE email and ONE phone from `users` until
366
+ a person Contact log exists (pl-9h4). Canon's motivating case (Crysta's own
367
+ seat-linked contact, `ct-crysta`) is therefore not yet met.
368
+ - Entries are removed, not retired. Canon's write-in ledger keeps retired
369
+ entries stamped `retiredOn` (retire-not-remove, `agencyhub.jsx` L8181-L8185).
370
+ - The identity key uses the preferred email only, as canon's uses the card's
371
+ flat email (`agencyhub.jsx` `hubSavePocs` L382-L384). Changing the preferred email changes
372
+ `identity_key`, and a secondary email shared with another row is not
373
+ deduplicated.
374
+
375
+ **Breaking surface** (every export whose shape changed):
376
+
377
+ | Export | 0.28.0 | 0.30.0 |
378
+ |---|---|---|
379
+ | `POC_SUBJECT_TYPES` / `PocSubjectType` | `… · site · …` | `… · location · …` |
380
+ | `PocSubjectRef` | `subject_type: "site"` | `subject_type: "location"` |
381
+ | `PocOwnerSchema` / `PocOwner` | accepts `site` | accepts `location` |
382
+ | `PocDetailsSchema` / `PocDetails` | `email?`, `phone?` | `emails?`, `phones?` (`PocContactEntry[]`; single fields refused) |
383
+ | `PocInAppSchema` / `PocInApp` | `email` (required), `phone?` | `emails` (at least one), `phones?` |
384
+ | `PocSeedSchema` / `PocSeed`, `PocPatchSchema` / `PocPatch` | via `PocDetailsSchema` | via `PocDetailsSchema` |
385
+ | `PointOfContactDocSchema` / `PointOfContactDoc` | `email`, `phone` | `emails`, `phones` |
386
+ | `PocRuleInput` | `email`, `phone` | `emails`, `phones` |
387
+ | `pocIdentityKey` input | `email` | `emails` (keys on the preferred) |
388
+ | `PointOfContactOwnerView` / `PointOfContactStewardView` | `email`, `phone` (stored) | `emails`, `phones` (row's own) + read-only `email`, `phone` (reachable preferred) |
389
+ | `PointOfContactNetworkView` / `ReferralRecipient` | `email`, `phone` | adds `emails`, `phones`; `email` / `phone` are the preferred entries' projections |
390
+
19
391
  ## CVC-136 core indicators 1.2.0 / 0.29.0
20
392
 
21
393
  0.29.0 appends ONE core indicator, `potential_trafficking_victim_recorded`
@@ -57,7 +429,7 @@ What it holds:
57
429
  `readServiceListings(db, query, { categories })`, the one raw-driver read
58
430
  (by org, org + program, category keys or id).
59
431
 
60
- Folded into the unpublished 0.28.0 (co-6zr), so every app reads listings as
432
+ Folded into 0.28.0 before its release (co-6zr), so every app reads listings as
61
433
  the Platform's own Network reads do (platform `feat/pl-srl-followups`,
62
434
  pl-6uk / pl-avy):
63
435
 
@@ -104,6 +476,7 @@ What it holds:
104
476
  - `toDirectoryOrganizationView` (one view over both shapes),
105
477
  `readDirectoryOrganization` and `readAgencyOwnOrganization`, the raw-driver
106
478
  reads (pass `toObjectId` so a string id matches an ObjectId `_id`).
479
+
107
480
  ## points-of-contact / 0.28.0
108
481
 
109
482
  0.28.0 (pl-3r8) ships the **Point of contact** read contract at