@htilabs/platform-common-models 0.85.0 → 0.87.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 (64) hide show
  1. package/README.md +30 -0
  2. package/dist/{index-XWSYon40.d.cts → index-1pWiqEBC.d.cts} +1 -1
  3. package/dist/{index-Bh1zO_Vu.d.ts → index-uz57Fic9.d.ts} +1 -1
  4. package/dist/index.cjs +12 -1
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.d.cts +3 -3
  7. package/dist/index.d.ts +3 -3
  8. package/dist/index.js +12 -1
  9. package/dist/index.js.map +1 -1
  10. package/dist/models/index.d.cts +2 -2
  11. package/dist/models/index.d.ts +2 -2
  12. package/dist/org-directory/index.cjs +8 -2
  13. package/dist/org-directory/index.cjs.map +1 -1
  14. package/dist/org-directory/index.d.cts +11 -2
  15. package/dist/org-directory/index.d.ts +11 -2
  16. package/dist/org-directory/index.js +8 -2
  17. package/dist/org-directory/index.js.map +1 -1
  18. package/dist/org-merge/index.cjs +8 -2
  19. package/dist/org-merge/index.cjs.map +1 -1
  20. package/dist/org-merge/index.js +8 -2
  21. package/dist/org-merge/index.js.map +1 -1
  22. package/dist/points-of-contact/index.cjs +229 -24
  23. package/dist/points-of-contact/index.cjs.map +1 -1
  24. package/dist/points-of-contact/index.d.cts +50 -5
  25. package/dist/points-of-contact/index.d.ts +50 -5
  26. package/dist/points-of-contact/index.js +226 -23
  27. package/dist/points-of-contact/index.js.map +1 -1
  28. package/dist/reader-BmhzOis-.d.ts +273 -0
  29. package/dist/reader-DfQtdw6n.d.cts +273 -0
  30. package/dist/schemas/index.cjs +12 -1
  31. package/dist/schemas/index.cjs.map +1 -1
  32. package/dist/schemas/index.d.cts +57 -27
  33. package/dist/schemas/index.d.ts +57 -27
  34. package/dist/schemas/index.js +12 -1
  35. package/dist/schemas/index.js.map +1 -1
  36. package/dist/seat-logs/index.cjs +815 -0
  37. package/dist/seat-logs/index.cjs.map +1 -0
  38. package/dist/seat-logs/index.d.cts +274 -0
  39. package/dist/seat-logs/index.d.ts +274 -0
  40. package/dist/seat-logs/index.js +742 -0
  41. package/dist/seat-logs/index.js.map +1 -0
  42. package/dist/validation/index.d.cts +1 -1
  43. package/dist/validation/index.d.ts +1 -1
  44. package/package.json +6 -1
  45. package/src/orgDirectory/__tests__/programDetails.test.ts +2 -1
  46. package/src/orgDirectory/__tests__/programTeamLink.test.ts +107 -0
  47. package/src/orgDirectory/schemas.ts +8 -1
  48. package/src/pointsOfContact/__tests__/seatContactLog.test.ts +170 -0
  49. package/src/pointsOfContact/readRules.ts +22 -4
  50. package/src/pointsOfContact/reader.ts +95 -1
  51. package/src/pointsOfContact/schemas.ts +4 -3
  52. package/src/schemas/organization-program.ts +25 -2
  53. package/src/seatLogs/__tests__/seatLogs.review.test.ts +222 -0
  54. package/src/seatLogs/__tests__/seatLogs.test.ts +335 -0
  55. package/src/seatLogs/index.ts +15 -0
  56. package/src/seatLogs/log.ts +700 -0
  57. package/src/seatLogs/personId.ts +100 -0
  58. package/src/seatLogs/personSlugWordlists.ts +40 -0
  59. package/src/seatLogs/reader.ts +143 -0
  60. package/src/seatLogs/schemas.ts +118 -0
  61. package/dist/{agency-CnVTwLeV.d.ts → agency-BHv54o79.d.ts} +4 -4
  62. package/dist/{agency-8ufZJJDH.d.cts → agency-Djp57S71.d.cts} +4 -4
  63. package/dist/{cvcEntry-D787utvP.d.cts → cvcEntry-DAuhe0cd.d.cts} +8 -8
  64. package/dist/{cvcEntry-D787utvP.d.ts → cvcEntry-DAuhe0cd.d.ts} +8 -8
@@ -1,4 +1,4 @@
1
- export { A as AgencyOrgTypeFieldsInput, a as AgencyOrgTypeFieldsSchema, b as AgencyTypeKeyInput, c as AgencyTypeKeySchema, C as CvcCode, d as CvcCodeSchema, e as CvcDomain, t as CvcEntry, f as CvcEntrySchema, g as CvcEnvelope, h as CvcEnvelopeSchema, i as CvcKey, j as CvcKeySchema, u as CvcValidationError, O as OrgTypeFieldsSchema, k as OrgTypeSelectableKeyInput, l as OrgTypeSelectableKeySchema, P as PrimaryLanguageEntry, v as PrimaryLanguageEntrySchema, S as ServiceCategoryEntry, m as ServiceCategoryEntrySchema, n as SetOrgTypeInput, o as SetOrgTypeInputSchema, T as TeamApp, p as TeamAppSchema, q as TeamDirectoryFieldsInput, r as TeamDirectoryFieldsSchema, x as getCvcLevel, s as orgTypeFieldsShape, y as validateCvc, w as withOrgTypeFields } from '../agency-8ufZJJDH.cjs';
1
+ export { A as AgencyOrgTypeFieldsInput, a as AgencyOrgTypeFieldsSchema, b as AgencyTypeKeyInput, c as AgencyTypeKeySchema, C as CvcCode, d as CvcCodeSchema, e as CvcDomain, t as CvcEntry, f as CvcEntrySchema, g as CvcEnvelope, h as CvcEnvelopeSchema, i as CvcKey, j as CvcKeySchema, u as CvcValidationError, O as OrgTypeFieldsSchema, k as OrgTypeSelectableKeyInput, l as OrgTypeSelectableKeySchema, P as PrimaryLanguageEntry, v as PrimaryLanguageEntrySchema, S as ServiceCategoryEntry, m as ServiceCategoryEntrySchema, n as SetOrgTypeInput, o as SetOrgTypeInputSchema, T as TeamApp, p as TeamAppSchema, q as TeamDirectoryFieldsInput, r as TeamDirectoryFieldsSchema, x as getCvcLevel, s as orgTypeFieldsShape, y as validateCvc, w as withOrgTypeFields } from '../agency-Djp57S71.cjs';
2
2
  export { V as VSP_TWO_STEP_ISSUE, v as vspTwoStepHolds } from '../agency-BXvE4yWu.cjs';
3
3
  import 'zod';
4
4
  import '../org-type-D_FG4KdN.cjs';
@@ -1,4 +1,4 @@
1
- export { A as AgencyOrgTypeFieldsInput, a as AgencyOrgTypeFieldsSchema, b as AgencyTypeKeyInput, c as AgencyTypeKeySchema, C as CvcCode, d as CvcCodeSchema, e as CvcDomain, t as CvcEntry, f as CvcEntrySchema, g as CvcEnvelope, h as CvcEnvelopeSchema, i as CvcKey, j as CvcKeySchema, u as CvcValidationError, O as OrgTypeFieldsSchema, k as OrgTypeSelectableKeyInput, l as OrgTypeSelectableKeySchema, P as PrimaryLanguageEntry, v as PrimaryLanguageEntrySchema, S as ServiceCategoryEntry, m as ServiceCategoryEntrySchema, n as SetOrgTypeInput, o as SetOrgTypeInputSchema, T as TeamApp, p as TeamAppSchema, q as TeamDirectoryFieldsInput, r as TeamDirectoryFieldsSchema, x as getCvcLevel, s as orgTypeFieldsShape, y as validateCvc, w as withOrgTypeFields } from '../agency-CnVTwLeV.js';
1
+ export { A as AgencyOrgTypeFieldsInput, a as AgencyOrgTypeFieldsSchema, b as AgencyTypeKeyInput, c as AgencyTypeKeySchema, C as CvcCode, d as CvcCodeSchema, e as CvcDomain, t as CvcEntry, f as CvcEntrySchema, g as CvcEnvelope, h as CvcEnvelopeSchema, i as CvcKey, j as CvcKeySchema, u as CvcValidationError, O as OrgTypeFieldsSchema, k as OrgTypeSelectableKeyInput, l as OrgTypeSelectableKeySchema, P as PrimaryLanguageEntry, v as PrimaryLanguageEntrySchema, S as ServiceCategoryEntry, m as ServiceCategoryEntrySchema, n as SetOrgTypeInput, o as SetOrgTypeInputSchema, T as TeamApp, p as TeamAppSchema, q as TeamDirectoryFieldsInput, r as TeamDirectoryFieldsSchema, x as getCvcLevel, s as orgTypeFieldsShape, y as validateCvc, w as withOrgTypeFields } from '../agency-BHv54o79.js';
2
2
  export { V as VSP_TWO_STEP_ISSUE, v as vspTwoStepHolds } from '../agency-NEW6NOGD.js';
3
3
  import 'zod';
4
4
  import '../org-type-BYQb9Qzq.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@htilabs/platform-common-models",
3
- "version": "0.85.0",
3
+ "version": "0.87.0",
4
4
  "description": "Shared constants, types, and models for HTI Labs applications",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -116,6 +116,11 @@
116
116
  "types": "./dist/grant-registry/index.d.ts",
117
117
  "import": "./dist/grant-registry/index.js",
118
118
  "require": "./dist/grant-registry/index.cjs"
119
+ },
120
+ "./seat-logs": {
121
+ "types": "./dist/seat-logs/index.d.ts",
122
+ "import": "./dist/seat-logs/index.js",
123
+ "require": "./dist/seat-logs/index.cjs"
119
124
  }
120
125
  },
121
126
  "files": [
@@ -58,7 +58,8 @@ describe("the stored names", () => {
58
58
 
59
59
  it("are declared by the Mongoose fragment and the row schema, after the existing keys", () => {
60
60
  const fragmentKeys = Object.keys(organizationProgramSchemaDefinition);
61
- expect(fragmentKeys.slice(-7)).toEqual([...PROGRAM_DETAIL_KEYS]);
61
+ // The seven details follow the nine keys published before 0.76.0 (the team link, 0.86.0, follows them).
62
+ expect(fragmentKeys.slice(9, 16)).toEqual([...PROGRAM_DETAIL_KEYS]);
62
63
  expect([...ORGANIZATION_PROGRAM_ROW_KEYS]).toEqual(fragmentKeys);
63
64
  // The nine keys published before 0.76.0 are unchanged and still first.
64
65
  expect(fragmentKeys.slice(0, 9)).toEqual([
@@ -0,0 +1,107 @@
1
+ /**
2
+ * The program's team link on `organizations.programs[]` (0.86.0): `teamId`
3
+ * (the first linked team) and `teamIds` (every linked team; one program may
4
+ * have several, Crysta 2026-10-18). Canon: the UDD Program object's
5
+ * `team_id` · `team_ids` (platform-prototype `src/agencyhub.jsx`
6
+ * `roElevateProgramToTeam`, `linkTeamToProgramH`), stored camelCase like the
7
+ * rest of the row.
8
+ */
9
+
10
+ import mongoose, { Schema } from "mongoose";
11
+ import { describe, expect, it } from "vitest";
12
+
13
+ import {
14
+ addOrganizationProgramsField,
15
+ organizationProgramSchemaDefinition,
16
+ } from "../../schemas/organization-program.js";
17
+ import { ORGANIZATION_PROGRAM_ROW_KEYS, OrganizationProgramRowSchema } from "../index.js";
18
+
19
+ const LINKED = {
20
+ programId: "prog-1",
21
+ name: "Crisis Shelter",
22
+ teamId: "65f000000000000000000001",
23
+ teamIds: ["65f000000000000000000001", "65f000000000000000000002"],
24
+ };
25
+
26
+ describe("the keys", () => {
27
+ it("the row keys list both, last, after every key published before", () => {
28
+ expect([...ORGANIZATION_PROGRAM_ROW_KEYS].slice(-2)).toEqual(["teamId", "teamIds"]);
29
+ expect([...ORGANIZATION_PROGRAM_ROW_KEYS]).toEqual(
30
+ Object.keys(organizationProgramSchemaDefinition),
31
+ );
32
+ });
33
+
34
+ it("the fragment declares them optional; the list does not default to empty", () => {
35
+ expect(organizationProgramSchemaDefinition.teamId).toEqual({ type: String, required: false });
36
+ expect(organizationProgramSchemaDefinition.teamIds).toEqual({
37
+ type: [String],
38
+ required: false,
39
+ default: undefined,
40
+ });
41
+ });
42
+ });
43
+
44
+ describe("the row schema", () => {
45
+ it("parses a row with the link, exactly as stored", () => {
46
+ const parsed = OrganizationProgramRowSchema.parse(LINKED);
47
+ expect(parsed.teamId).toBe(LINKED.teamId);
48
+ expect(parsed.teamIds).toEqual(LINKED.teamIds);
49
+ });
50
+
51
+ it("parses a row without them as no link", () => {
52
+ const parsed = OrganizationProgramRowSchema.parse({ programId: "p", name: "N" });
53
+ expect(parsed.teamId).toBeUndefined();
54
+ expect(parsed.teamIds).toBeUndefined();
55
+ });
56
+
57
+ it("a malformed link reads as not on record and never fails the row", () => {
58
+ const parsed = OrganizationProgramRowSchema.safeParse({
59
+ programId: "p",
60
+ name: "N",
61
+ teamId: 7,
62
+ teamIds: "t1",
63
+ });
64
+ expect(parsed.success).toBe(true);
65
+ const link = parsed.success ? [parsed.data.teamId, parsed.data.teamIds] : null;
66
+ expect(link).toEqual([undefined, undefined]);
67
+ });
68
+
69
+ it("still drops a key outside the fragment", () => {
70
+ const parsed = OrganizationProgramRowSchema.parse({
71
+ ...LINKED,
72
+ team_ids: ["t9"],
73
+ somethingElse: 1,
74
+ });
75
+ expect("team_ids" in parsed).toBe(false);
76
+ expect("somethingElse" in parsed).toBe(false);
77
+ });
78
+ });
79
+
80
+ describe("the Mongoose fragment", () => {
81
+ const schema = new Schema({ name: String });
82
+ addOrganizationProgramsField(schema);
83
+ const Org = mongoose.model("ProgramTeamLinkFragmentOrg", schema);
84
+ const storedPrograms = (doc: { toObject(): unknown }) =>
85
+ (doc.toObject() as { programs: Record<string, unknown>[] }).programs;
86
+
87
+ it("keeps the link on a cast (a program edit no longer erases it)", () => {
88
+ const doc = new Org({ name: "Org", programs: [LINKED] });
89
+ expect(doc.validateSync()).toBeUndefined();
90
+ const stored = storedPrograms(doc)[0]!;
91
+ expect([stored.teamId, stored.teamIds]).toEqual([LINKED.teamId, LINKED.teamIds]);
92
+ });
93
+
94
+ it("a row with no link stores neither key (absent, never an empty list)", () => {
95
+ const doc = new Org({ name: "Org", programs: [{ programId: "p", name: "N" }] });
96
+ const stored = storedPrograms(doc)[0]!;
97
+ expect("teamId" in stored).toBe(false);
98
+ expect("teamIds" in stored).toBe(false);
99
+ });
100
+
101
+ it("still drops the sheet's snake_case spelling", () => {
102
+ const snake = { programId: "p", name: "N", team_ids: ["t9"] };
103
+ const doc = new Org({ name: "Org", programs: [snake] });
104
+ const stored = storedPrograms(doc)[0]!;
105
+ expect("team_ids" in stored).toBe(false);
106
+ });
107
+ });
@@ -27,6 +27,8 @@ export const ORGANIZATION_PROGRAM_ROW_KEYS = Object.freeze([
27
27
  "operatingEndDate",
28
28
  "locationId",
29
29
  "notes",
30
+ "teamId",
31
+ "teamIds",
30
32
  ] as const);
31
33
 
32
34
  export type OrganizationProgramRowKey = (typeof ORGANIZATION_PROGRAM_ROW_KEYS)[number];
@@ -43,7 +45,8 @@ const detailText = z.string().nullish().catch(undefined);
43
45
  * One stored program row. `programId` + `name` are required; the rest are
44
46
  * optional and may be null. Unknown keys are stripped (a reader never relies
45
47
  * on a key outside the fragment). The seven Program-record detail keys
46
- * (`programType` … `notes`, 0.76.0) never fail the row.
48
+ * (`programType` … `notes`, 0.76.0) and the team link (`teamId`, `teamIds`,
49
+ * 0.86.0) never fail the row: a value of the wrong kind reads as not on record.
47
50
  */
48
51
  export const OrganizationProgramRowSchema = z.object({
49
52
  programId: z.string().min(1),
@@ -64,6 +67,10 @@ export const OrganizationProgramRowSchema = z.object({
64
67
  operatingEndDate: detailText,
65
68
  locationId: detailText,
66
69
  notes: detailText,
70
+ /** The first team that works for the program (canon `team_id`). */
71
+ teamId: detailText,
72
+ /** Every team that works for the program (canon `team_ids`). */
73
+ teamIds: z.array(z.string()).nullish().catch(undefined),
67
74
  });
68
75
 
69
76
  export type OrganizationProgramRow = z.infer<typeof OrganizationProgramRowSchema>;
@@ -0,0 +1,170 @@
1
+ /**
2
+ * pl-9h4: a seat-linked point of contact reads the seat's contact log
3
+ * (`seat_contacts`) when the seat resolver is wrapped in `withSeatContactLogs`.
4
+ */
5
+ import { describe, expect, it } from "vitest";
6
+
7
+ import { addSeatContact, setPreferredSeatContact } from "../../seatLogs/log.js";
8
+ import type { SeatContactEntry, SeatLogSubject } from "../../seatLogs/schemas.js";
9
+ import {
10
+ pocIdentityKey,
11
+ seatContactListsFromLog,
12
+ toNetworkView,
13
+ toStewardView,
14
+ withSeatContactLogs,
15
+ type PointOfContactDoc,
16
+ type SeatReach,
17
+ type SeatResolver,
18
+ } from "../index.js";
19
+
20
+ const SEAT: SeatLogSubject = { subject_type: "user", subject_id: "u-seat" };
21
+ let n = 0;
22
+ const ctx = { actor: "u-admin", at: "2026-11-16T15:00:00.000Z", mintId: () => `ci-${++n}` };
23
+
24
+ function log(): SeatContactEntry[] {
25
+ let es: SeatContactEntry[] = [];
26
+ es = addSeatContact(es, SEAT, { contact_type: "email", value: "Old@A.org" }, ctx).entries;
27
+ es = addSeatContact(es, SEAT, { contact_type: "email", value: "New@A.org" }, ctx).entries;
28
+ es = addSeatContact(es, SEAT, { contact_type: "phone", value: "4026773902" }, ctx).entries;
29
+ es = addSeatContact(es, SEAT, { contact_type: "phone", value: "4025550100" }, ctx).entries;
30
+ const newer = es.find((e) => e.value === "New@A.org")!;
31
+ return setPreferredSeatContact(es, SEAT, newer.entry_id, ctx).entries;
32
+ }
33
+
34
+ function seatRow(): PointOfContactDoc {
35
+ const d: PointOfContactDoc = {
36
+ id: "poc-seat", subject_type: "agency", subject_id: "agency-a", agency_id: "agency-a",
37
+ org_id: "org-a", user_id: "u-seat", person_id: null, display_name: null, emails: [], phones: [],
38
+ purposes: [], urgent_methods: [], is_primary: false, is_confidential: false, active: true,
39
+ notes: null, status: "confirmed", origin: "admin_hub", added_in_app: "platform",
40
+ identity_key: "x", confirmed_by: "steward", confirmed_at: "2026-10-14T00:00:00.000Z",
41
+ deactivated_by: null, deactivated_at: null, version: 1, createdBy: "u1",
42
+ createdAt: "2026-10-14T00:00:00.000Z", updatedBy: "u1", updatedAt: "2026-10-14T00:00:00.000Z",
43
+ };
44
+ return { ...d, identity_key: pocIdentityKey(d) };
45
+ }
46
+
47
+ const flat: SeatResolver = async (ids) => new Map<string, SeatReach>(
48
+ ids.map((id) => [id, { email: "flat@a.org", phone: "555-0000", name: "Sam Seat" }]),
49
+ );
50
+
51
+ function dbWith(rows: SeatContactEntry[]) {
52
+ const asked: string[] = [];
53
+ return {
54
+ asked,
55
+ db: {
56
+ collection: (name: string) => {
57
+ asked.push(name);
58
+ return {
59
+ find: (f: Record<string, unknown>) => ({
60
+ toArray: async () => rows.filter((r) =>
61
+ r.subject_type === f.subject_type &&
62
+ ((f.subject_id as { $in: string[] }).$in).includes(r.subject_id)),
63
+ }),
64
+ };
65
+ },
66
+ },
67
+ };
68
+ }
69
+
70
+ describe("seat contact log in points of contact (pl-9h4)", () => {
71
+ it("lists every live email and phone with the log's preferred mark", () => {
72
+ expect(seatContactListsFromLog(log())).toEqual({
73
+ emails: [{ value: "old@a.org", is_preferred: false }, { value: "new@a.org", is_preferred: true }],
74
+ phones: [
75
+ { value: "(402) 677-3902", is_preferred: true },
76
+ { value: "(402) 555-0100", is_preferred: false },
77
+ ],
78
+ });
79
+ expect(seatContactListsFromLog([])).toBeNull();
80
+ });
81
+
82
+ it("a seat-linked contact reads the log; a seat with no log keeps users' email and phone", async () => {
83
+ const { db, asked } = dbWith(log());
84
+ const resolve = withSeatContactLogs(db, flat);
85
+ const seats = await resolve(["u-seat", "u-other"]);
86
+ expect(asked).toEqual(["seat_contacts"]);
87
+
88
+ const v = toNetworkView(seatRow(), seats.get("u-seat"))!;
89
+ expect(v.email).toBe("new@a.org");
90
+ expect(v.emails.map((e) => e.value)).toEqual(["old@a.org", "new@a.org"]);
91
+ expect(v.phone).toBe("(402) 677-3902");
92
+ expect(v.phones).toHaveLength(2);
93
+ expect(v.display_name).toBe("Sam Seat");
94
+
95
+ const other = toNetworkView(seatRow(), seats.get("u-other"))!;
96
+ expect([other.emails, other.phones]).toEqual([
97
+ [{ value: "flat@a.org", is_preferred: true }],
98
+ [{ value: "555-0000", is_preferred: true }],
99
+ ]);
100
+ });
101
+
102
+ it("the steward view's seat is a copy, never the resolver's arrays", async () => {
103
+ const { db } = dbWith(log());
104
+ const seats = await withSeatContactLogs(db, flat)(["u-seat"]);
105
+ const seat = seats.get("u-seat")!;
106
+ const s = toStewardView(seatRow(), seat);
107
+ expect(s.seat?.emails).toEqual(seat.emails);
108
+ expect(s.seat?.emails).not.toBe(seat.emails);
109
+ expect(s.email).toBe("new@a.org");
110
+ });
111
+ });
112
+
113
+ describe("withSeatContactLogs: pre-review fixes (B1, B2, S3, S5)", () => {
114
+ const phoneOnly = () =>
115
+ addSeatContact([], SEAT, { contact_type: "phone", value: "4025550100" }, ctx).entries;
116
+ const emailOnly = () =>
117
+ addSeatContact([], SEAT, { contact_type: "email", value: "Log@A.org" }, ctx).entries;
118
+
119
+ it("B1: a seat the base resolver left out (ended, unknown) stays out", async () => {
120
+ const { db } = dbWith(phoneOnly());
121
+ const ended: SeatResolver = async () => new Map();
122
+ const seats = await withSeatContactLogs(db, ended)(["u-seat"]);
123
+ expect(seats.has("u-seat")).toBe(false);
124
+ const v = toNetworkView(seatRow(), seats.get("u-seat"))!;
125
+ expect([v.emails, v.phones]).toEqual([[], []]);
126
+ });
127
+
128
+ it("B2: a phone-only log keeps the flat email; an email-only log keeps the flat phone", async () => {
129
+ const p = (await withSeatContactLogs(dbWith(phoneOnly()).db, flat)(["u-seat"])).get("u-seat")!;
130
+ const pv = toNetworkView(seatRow(), p)!;
131
+ expect([pv.email, pv.phone]).toEqual(["flat@a.org", "(402) 555-0100"]);
132
+ const e = (await withSeatContactLogs(dbWith(emailOnly()).db, flat)(["u-seat"])).get("u-seat")!;
133
+ const ev = toNetworkView(seatRow(), e)!;
134
+ expect([ev.email, ev.phone]).toEqual(["log@a.org", "555-0000"]);
135
+ });
136
+
137
+ it("S3: a seat id asked upper-case reads the log stored lower-case", async () => {
138
+ const hex = "0123456789abcdef01234567";
139
+ const subject = { subject_type: "user" as const, subject_id: hex };
140
+ const es = addSeatContact([], subject, { contact_type: "email", value: "hex@a.org" }, ctx).entries;
141
+ const seats = await withSeatContactLogs(dbWithForms(es).db, flat)([hex.toUpperCase()]);
142
+ expect(seats.get(hex.toUpperCase())?.email).toBe("hex@a.org");
143
+ });
144
+
145
+ it("S5: a malformed row is skipped for its seat (per-type fallback), never thrown", async () => {
146
+ const bad = { ...phoneOnly()[0], entry_id: "ci-bad", notes: undefined } as unknown as SeatContactEntry;
147
+ const good = emailOnly();
148
+ const skipped: string[] = [];
149
+ const seats = await withSeatContactLogs(dbWith([...good, bad]).db, flat, {
150
+ onInvalidRow: (e) => skipped.push(e.entryId ?? ""),
151
+ })(["u-seat"]);
152
+ const v = toNetworkView(seatRow(), seats.get("u-seat"))!;
153
+ expect([v.email, v.phone]).toEqual(["log@a.org", "555-0000"]);
154
+ expect(skipped).toEqual(["ci-bad"]);
155
+ });
156
+ });
157
+
158
+ /** Like `dbWith`, but matches `subject_id` exactly as Mongo would (no case folding). */
159
+ function dbWithForms(rows: SeatContactEntry[]) {
160
+ return {
161
+ db: {
162
+ collection: () => ({
163
+ find: (f: Record<string, unknown>) => ({
164
+ toArray: async () => rows.filter((r) =>
165
+ ((f.subject_id as { $in: string[] }).$in).includes(r.subject_id)),
166
+ }),
167
+ }),
168
+ },
169
+ };
170
+ }
@@ -62,6 +62,14 @@ export interface SeatReach {
62
62
  email: string | null;
63
63
  phone: string | null;
64
64
  name: string | null;
65
+ /**
66
+ * The seat's live emails from its contact log (pl-9h4), preferred marked.
67
+ * When present, a seat-linked contact reads these instead of `email`.
68
+ * Absent = the seat has no contact log yet: `email` is read as one entry.
69
+ */
70
+ emails?: PocContactEntry[];
71
+ /** The seat's live phones from its contact log; the same rule against `phone`. */
72
+ phones?: PocContactEntry[];
65
73
  }
66
74
 
67
75
  /** The steward view: everything but the identity key, seat resolved. */
@@ -89,7 +97,7 @@ export interface PointOfContactNetworkView {
89
97
  agency_id: string | null;
90
98
  org_id: string | null;
91
99
  display_name: string | null;
92
- /** The row's emails, or the seat's email as one preferred entry when the contact is seat-linked and a seat resolver was given. */
100
+ /** The row's emails, or for a seat-linked contact (a seat resolver given) the seat's contact-log emails, else its email as one preferred entry. */
93
101
  emails: PocContactEntry[];
94
102
  /** The row's phones, or the seat's phone as one preferred entry (the same rules as `emails`). */
95
103
  phones: PocContactEntry[];
@@ -140,6 +148,7 @@ const copyEntries = (list: readonly PocContactEntry[]): PocContactEntry[] =>
140
148
 
141
149
  /**
142
150
  * Where the contact is reached: the row's own lists, or for a seat-linked row
151
+ * the seat's contact-log lists when the resolver carried them (pl-9h4), else
143
152
  * the seat's email (trimmed, lowercased) and phone as one preferred entry
144
153
  * each. Always fresh arrays.
145
154
  */
@@ -151,11 +160,20 @@ function reachOf(
151
160
  const one = (v: string | null | undefined): PocContactEntry[] =>
152
161
  v ? [{ value: v, is_preferred: true }] : [];
153
162
  return {
154
- emails: one(seat?.email?.trim().toLowerCase()),
155
- phones: one(seat?.phone?.trim()),
163
+ emails: seat?.emails ? copyEntries(seat.emails) : one(seat?.email?.trim().toLowerCase()),
164
+ phones: seat?.phones ? copyEntries(seat.phones) : one(seat?.phone?.trim()),
156
165
  };
157
166
  }
158
167
 
168
+ /** A copy of the seat's reach (its lists too), so a view never shares the resolver's arrays. */
169
+ function copySeat(seat: SeatReach | null | undefined): SeatReach | null {
170
+ if (!seat) return null;
171
+ const out: SeatReach = { ...seat };
172
+ if (seat.emails) out.emails = copyEntries(seat.emails);
173
+ if (seat.phones) out.phones = copyEntries(seat.phones);
174
+ return out;
175
+ }
176
+
159
177
  const preferredValue = (list: readonly PocContactEntry[]): string | null =>
160
178
  preferredContactEntry(list)?.value ?? null;
161
179
 
@@ -173,7 +191,7 @@ export function toStewardView(
173
191
  purposes: [...d.purposes],
174
192
  urgent_methods: [...d.urgent_methods],
175
193
  purpose_labels: d.purposes.map(contactPurposeLabel),
176
- seat: d.user_id ? (seat ?? null) : null,
194
+ seat: d.user_id ? copySeat(seat) : null,
177
195
  email: preferredValue(reach.emails),
178
196
  phone: preferredValue(reach.phones),
179
197
  };
@@ -16,6 +16,9 @@
16
16
  * ObjectId filter for `users._id`; the reader passes a {@link SeatResolver}
17
17
  * that reads its own `users`. The partner rollup REQUIRES one, so a reader
18
18
  * cannot silently drop seat-linked referral contacts.
19
+ * Wrap it in {@link withSeatContactLogs} to read each seat's contact log
20
+ * (every email and phone, with the log's preferred mark) instead of the one
21
+ * email and phone on `users` (pl-9h4).
19
22
  *
20
23
  * ## Confidential Referrals (magic link) holders (pl-iza, 0.32.0)
21
24
  *
@@ -31,7 +34,21 @@
31
34
  * row that may be confidential is counted, never thrown.
32
35
  */
33
36
 
34
- import { POINTS_OF_CONTACT_COLLECTION, type PointOfContactDoc } from "./schemas.js";
37
+ import {
38
+ liveSeatContacts,
39
+ preferredSeatContact,
40
+ } from "../seatLogs/log.js";
41
+ import {
42
+ readSeatContactLogs,
43
+ type SeatLogDbLike,
44
+ type SeatLogShapeError,
45
+ } from "../seatLogs/reader.js";
46
+ import type { SeatContactEntry } from "../seatLogs/schemas.js";
47
+ import {
48
+ POINTS_OF_CONTACT_COLLECTION,
49
+ type PocContactEntry,
50
+ type PointOfContactDoc,
51
+ } from "./schemas.js";
35
52
  import {
36
53
  byContactReadingOrder,
37
54
  normalizePointOfContact,
@@ -59,6 +76,83 @@ export interface PocDbLike {
59
76
  /** Resolves seat ids (platform-db `users._id`, string form) to their reach. Missing ids are simply absent. */
60
77
  export type SeatResolver = (userIds: readonly string[]) => Promise<ReadonlyMap<string, SeatReach>>;
61
78
 
79
+ /**
80
+ * A seat's contact log → the lists a seat-linked contact reads (pl-9h4): the
81
+ * live emails (lowercased, as this module keeps emails) and phones, each with
82
+ * the log's preferred mark (one per type; the first when none is marked).
83
+ * `null` when the log has no live entry of either type — the caller then
84
+ * keeps the seat's flat `email` / `phone`.
85
+ */
86
+ export function seatContactListsFromLog(
87
+ entries: readonly SeatContactEntry[],
88
+ ): { emails: PocContactEntry[]; phones: PocContactEntry[] } | null {
89
+ const live = liveSeatContacts(entries);
90
+ if (!live.length) return null;
91
+ const listOf = (type: "email" | "phone"): PocContactEntry[] => {
92
+ const pref = preferredSeatContact(live, type);
93
+ const seen = new Set<string>();
94
+ const out: PocContactEntry[] = [];
95
+ for (const e of live) {
96
+ if (e.contact_type !== type) continue;
97
+ const value = type === "email" ? e.value.trim().toLowerCase() : e.value.trim();
98
+ if (!value || seen.has(value)) continue;
99
+ seen.add(value);
100
+ out.push({ value, is_preferred: e === pref });
101
+ }
102
+ return out;
103
+ };
104
+ return { emails: listOf("email"), phones: listOf("phone") };
105
+ }
106
+
107
+ /**
108
+ * Wrap a seat resolver so seat-linked contacts read each seat's contact log
109
+ * (`seat_contacts`, subject_type `user`) instead of the single `users`
110
+ * email / phone (pl-9h4).
111
+ *
112
+ * - Only seats `resolve` returned are enriched. A seat it leaves out (an
113
+ * ended seat in the network read, an id with no `users` row) stays out:
114
+ * its log never publishes it.
115
+ * - Per type: the log's emails (with `email` = its preferred) replace the
116
+ * seat's flat email only when the log has a live email; likewise phones.
117
+ * A type the log has no live entry of keeps what `resolve` returned.
118
+ * - Ids are matched case-insensitively, as the base resolvers match
119
+ * `users._id`; the result is keyed by the id as asked.
120
+ * - A stored log row that does not match the entry shape is skipped for its
121
+ * seat (reported to `onInvalidRow`) and never fails the read; a read ERROR
122
+ * propagates.
123
+ */
124
+ export function withSeatContactLogs(
125
+ db: SeatLogDbLike,
126
+ resolve: SeatResolver,
127
+ opts: { onInvalidRow?: (error: SeatLogShapeError) => void } = {},
128
+ ): SeatResolver {
129
+ return async (userIds) => {
130
+ const base = await resolve(userIds);
131
+ const ids = userIds.filter((id) => base.has(id));
132
+ const out = new Map<string, SeatReach>(base);
133
+ if (!ids.length) return out;
134
+ const logs = await readSeatContactLogs(db, ids, "user", {
135
+ invalid: "skip",
136
+ onInvalidRow: opts.onInvalidRow,
137
+ });
138
+ for (const id of ids) {
139
+ const lists = seatContactListsFromLog(logs.get(id) ?? []);
140
+ if (!lists) continue;
141
+ const next: SeatReach = { ...base.get(id)! };
142
+ if (lists.emails.length) {
143
+ next.emails = lists.emails;
144
+ next.email = lists.emails.find((e) => e.is_preferred)?.value ?? null;
145
+ }
146
+ if (lists.phones.length) {
147
+ next.phones = lists.phones;
148
+ next.phone = lists.phones.find((e) => e.is_preferred)?.value ?? null;
149
+ }
150
+ out.set(id, next);
151
+ }
152
+ return out;
153
+ };
154
+ }
155
+
62
156
  /**
63
157
  * A subject, always read together with its agency where ids can collide.
64
158
  * Program, team and location ids can be slugs two agencies share, so their reads
@@ -59,9 +59,10 @@
59
59
  *
60
60
  * ## Known deviations (0.30.0)
61
61
  *
62
- * - A seat-linked contact still reads ONE email and ONE phone from `users`
63
- * until a person Contact log exists (pl-9h4). Canon's motivating case
64
- * (Crysta's own seat-linked contact) is therefore not yet met.
62
+ * - A seat-linked contact reads the seat's contact log (`seat_contacts`)
63
+ * when the reader's seat resolver carries it (`withSeatContactLogs`,
64
+ * pl-9h4, 0.87.0); a seat with no log yet still reads ONE email and ONE
65
+ * phone from `users`.
65
66
  * - An entry is removed, not retired: canon's write-in ledger keeps retired
66
67
  * entries stamped `retiredOn` (retire-not-remove, L8181-L8185); this list
67
68
  * keeps only the live ones.
@@ -71,9 +71,21 @@
71
71
  * type is offered, whose site a program may name) live with the pure reader
72
72
  * `../orgDirectory/programDetails.ts`.
73
73
  *
74
+ * ## The team link (0.86.0)
75
+ *
76
+ * `teamId` and `teamIds` are the UDD Program object's `team_id` · `team_ids`
77
+ * (canon platform-prototype `src/agencyhub.jsx` `roElevateProgramToTeam`,
78
+ * `linkTeamToProgramH`): which team or teams work for the program. One program
79
+ * may have several teams (Crysta 2026-10-18, "One program, two teams"):
80
+ * `teamIds` lists every linked team, `teamId` is the first of them. Both are
81
+ * optional; absent means no team is linked, as before. Stored camelCase like
82
+ * the rest of the row. Declaring them here is what keeps them: the strict
83
+ * sub-schema dropped them on cast, so a link written today was erased by the
84
+ * next program edit. Nothing reads them yet.
85
+ *
74
86
  * Still NOT on the row (UDD columns production does not store yet):
75
- * `agency_id`, `app`, `team_id` / `team_ids`, `grant_id` (derived from the
76
- * dated award link), `can_refer_to`, `enrollment_subtypes`.
87
+ * `agency_id`, `app`, `grant_id` (derived from the dated award link),
88
+ * `can_refer_to`, `enrollment_subtypes`.
77
89
  *
78
90
  * ## Who dedupes
79
91
  *
@@ -169,6 +181,17 @@ export const organizationProgramSchemaDefinition = {
169
181
  locationId: { type: String, required: false },
170
182
  /** The editor's notes. */
171
183
  notes: { type: String, required: false },
184
+ /**
185
+ * The first team that works for the program (`teams._id` as a string;
186
+ * canon `team_id`). Equal to `teamIds[0]` when both are written.
187
+ */
188
+ teamId: { type: String, required: false },
189
+ /**
190
+ * Every team that works for the program (canon `team_ids`; one program may
191
+ * have several teams). `default: undefined`, so a row with no link stores
192
+ * nothing and reads as absent, never as an empty list.
193
+ */
194
+ teamIds: { type: [String], required: false, default: undefined },
172
195
  } as const;
173
196
 
174
197
  /**