@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
@@ -0,0 +1,273 @@
1
+ import { z } from 'zod';
2
+ import { NameTypeKeys } from './enums/index.js';
3
+
4
+ /**
5
+ * A seat's NAME log and CONTACT log: the stored entry shapes.
6
+ *
7
+ * Canon: platform-prototype `src/screens.jsx` @ 398fb24 `SeatNamesLedger`
8
+ * (L25149-L25288) and `SeatMethodsLedger` (L24981-L25137), over the object
9
+ * store `src/objectStore.js` (`addEntry` / `act`, L660-L740) and the spine
10
+ * cascade `src/objectStructuresEngine.generated.js` (`HTI_OBJECT_SPINE`,
11
+ * L942-L1049).
12
+ *
13
+ * The record (Person Data Object, step 6c, Crysta 2026-10-11): "a seat's name
14
+ * and contact rails stay keyed by the seat". So an entry's subject is the seat
15
+ * (`subject_type: "user"`, `subject_id` = the platform-db `users._id`, string
16
+ * form). A registry person's name rides the same log with
17
+ * `subject_type: "person"` (Person decision B).
18
+ *
19
+ * Names, contact details and addresses are not fields of a Person; each is
20
+ * its own log that points at the subject, so every entry carries its own
21
+ * source and dates (Person § 3). An entry is never edited in place: a
22
+ * correction inserts a new entry and archives the old one (`period_end`), and
23
+ * a retired entry stays in the log with its dates.
24
+ *
25
+ * Field shapes are the prototype's as stored: open dates are the empty string
26
+ * `""` (not null), a closed entry carries `period_end` `YYYY-MM-DD`; the store
27
+ * stamps an `events[]` audit trail (`{ act, at, actor }`) and a phone's
28
+ * `digits` key.
29
+ */
30
+
31
+ /** Platform-db collection holding name entries (all subjects). */
32
+ declare const SEAT_NAMES_COLLECTION = "seat_names";
33
+ /** Platform-db collection holding contact entries (all subjects). */
34
+ declare const SEAT_CONTACTS_COLLECTION = "seat_contacts";
35
+ /** Whose log: a seat (`users._id`) or a registry person (`per-…` id). */
36
+ declare const SEAT_LOG_SUBJECT_TYPES: readonly ["user", "person"];
37
+ type SeatLogSubjectType = (typeof SEAT_LOG_SUBJECT_TYPES)[number];
38
+ /** The two contact types the seat ledger carries (prototype Email / Phone chips). */
39
+ declare const SEAT_CONTACT_TYPES: readonly ["email", "phone"];
40
+ type SeatContactType = (typeof SEAT_CONTACT_TYPES)[number];
41
+ /** CVC-1 `name_type` keys (the prototype stores `alias` / `legal`). */
42
+ declare const SEAT_NAME_TYPES: [keyof typeof NameTypeKeys, ...(keyof typeof NameTypeKeys)[]];
43
+ type SeatNameType = keyof typeof NameTypeKeys;
44
+ /** The name types the profile's add row offers, in its chip order. */
45
+ declare const SEAT_NAME_ADD_TYPES: readonly [{
46
+ readonly name_type: "alias";
47
+ readonly label: "Also known as";
48
+ }, {
49
+ readonly name_type: "legal";
50
+ readonly label: "Legal name";
51
+ }];
52
+ /** One audit event the store stamps on an entry. */
53
+ declare const SeatLogEventSchema: z.ZodObject<{
54
+ /** `add`, `set_display`, `set_preferred`, `archive`, or `cascade` (a sibling's flag moved). */
55
+ act: z.ZodString;
56
+ /** ISO instant. */
57
+ at: z.ZodString;
58
+ /** The acting seat's id. */
59
+ actor: z.ZodString;
60
+ }, "strip", z.ZodTypeAny, {
61
+ at: string;
62
+ act: string;
63
+ actor: string;
64
+ }, {
65
+ at: string;
66
+ act: string;
67
+ actor: string;
68
+ }>;
69
+ type SeatLogEvent = z.infer<typeof SeatLogEventSchema>;
70
+ /** One name in a seat's (or registry person's) name log. */
71
+ declare const SeatNameEntrySchema: z.ZodObject<{
72
+ name_type: z.ZodEnum<["unknown" | "missingness_root" | "anonymous" | "data_not_collected" | "alias" | "code_name" | "handle_screenname" | "legal" | "maiden_former" | "nickname" | "street_name" | "trade_name_stage_name", ...("unknown" | "missingness_root" | "anonymous" | "data_not_collected" | "alias" | "code_name" | "handle_screenname" | "legal" | "maiden_former" | "nickname" | "street_name" | "trade_name_stage_name")[]]>;
73
+ /** The name as written. */
74
+ raw: z.ZodString;
75
+ /** The display name: one live entry per subject carries it. */
76
+ is_display: z.ZodBoolean;
77
+ /** Set with the display mark on the profile (prototype acts both together). */
78
+ is_preferred: z.ZodBoolean;
79
+ entry_id: z.ZodString;
80
+ subject_id: z.ZodString;
81
+ subject_type: z.ZodEnum<["user", "person"]>;
82
+ period_start: z.ZodUnion<[z.ZodLiteral<"">, z.ZodString]>;
83
+ period_end: z.ZodUnion<[z.ZodLiteral<"">, z.ZodString]>;
84
+ /** Where the entry came from (`admin_hub` on the profile). */
85
+ source: z.ZodString;
86
+ /** How it was captured (`direct_entry` on the profile). */
87
+ method: z.ZodString;
88
+ notes: z.ZodString;
89
+ events: z.ZodOptional<z.ZodArray<z.ZodObject<{
90
+ /** `add`, `set_display`, `set_preferred`, `archive`, or `cascade` (a sibling's flag moved). */
91
+ act: z.ZodString;
92
+ /** ISO instant. */
93
+ at: z.ZodString;
94
+ /** The acting seat's id. */
95
+ actor: z.ZodString;
96
+ }, "strip", z.ZodTypeAny, {
97
+ at: string;
98
+ act: string;
99
+ actor: string;
100
+ }, {
101
+ at: string;
102
+ act: string;
103
+ actor: string;
104
+ }>, "many">>;
105
+ }, "strip", z.ZodTypeAny, {
106
+ is_preferred: boolean;
107
+ subject_type: "user" | "person";
108
+ subject_id: string;
109
+ notes: string;
110
+ name_type: "unknown" | "missingness_root" | "anonymous" | "data_not_collected" | "alias" | "code_name" | "handle_screenname" | "legal" | "maiden_former" | "nickname" | "street_name" | "trade_name_stage_name";
111
+ raw: string;
112
+ is_display: boolean;
113
+ entry_id: string;
114
+ period_start: string;
115
+ period_end: string;
116
+ source: string;
117
+ method: string;
118
+ events?: {
119
+ at: string;
120
+ act: string;
121
+ actor: string;
122
+ }[] | undefined;
123
+ }, {
124
+ is_preferred: boolean;
125
+ subject_type: "user" | "person";
126
+ subject_id: string;
127
+ notes: string;
128
+ name_type: "unknown" | "missingness_root" | "anonymous" | "data_not_collected" | "alias" | "code_name" | "handle_screenname" | "legal" | "maiden_former" | "nickname" | "street_name" | "trade_name_stage_name";
129
+ raw: string;
130
+ is_display: boolean;
131
+ entry_id: string;
132
+ period_start: string;
133
+ period_end: string;
134
+ source: string;
135
+ method: string;
136
+ events?: {
137
+ at: string;
138
+ act: string;
139
+ actor: string;
140
+ }[] | undefined;
141
+ }>;
142
+ type SeatNameEntry = z.infer<typeof SeatNameEntrySchema>;
143
+ /** One email or phone in a seat's contact log. */
144
+ declare const SeatContactEntrySchema: z.ZodObject<{
145
+ contact_type: z.ZodEnum<["email", "phone"]>;
146
+ /** Email trimmed; phone in the store's canonical display form ({@link canonSeatContactValue}). */
147
+ value: z.ZodString;
148
+ use: z.ZodString;
149
+ /** The preferred entry of its type: one live entry per subject and type carries it. */
150
+ is_preferred: z.ZodBoolean;
151
+ safety_status: z.ZodString;
152
+ /** Phone only: the identity key ({@link seatContactKey}), stamped by the store. */
153
+ digits: z.ZodOptional<z.ZodString>;
154
+ entry_id: z.ZodString;
155
+ subject_id: z.ZodString;
156
+ subject_type: z.ZodEnum<["user", "person"]>;
157
+ period_start: z.ZodUnion<[z.ZodLiteral<"">, z.ZodString]>;
158
+ period_end: z.ZodUnion<[z.ZodLiteral<"">, z.ZodString]>;
159
+ /** Where the entry came from (`admin_hub` on the profile). */
160
+ source: z.ZodString;
161
+ /** How it was captured (`direct_entry` on the profile). */
162
+ method: z.ZodString;
163
+ notes: z.ZodString;
164
+ events: z.ZodOptional<z.ZodArray<z.ZodObject<{
165
+ /** `add`, `set_display`, `set_preferred`, `archive`, or `cascade` (a sibling's flag moved). */
166
+ act: z.ZodString;
167
+ /** ISO instant. */
168
+ at: z.ZodString;
169
+ /** The acting seat's id. */
170
+ actor: z.ZodString;
171
+ }, "strip", z.ZodTypeAny, {
172
+ at: string;
173
+ act: string;
174
+ actor: string;
175
+ }, {
176
+ at: string;
177
+ act: string;
178
+ actor: string;
179
+ }>, "many">>;
180
+ }, "strip", z.ZodTypeAny, {
181
+ value: string;
182
+ is_preferred: boolean;
183
+ subject_type: "user" | "person";
184
+ subject_id: string;
185
+ notes: string;
186
+ entry_id: string;
187
+ period_start: string;
188
+ period_end: string;
189
+ source: string;
190
+ method: string;
191
+ contact_type: "email" | "phone";
192
+ use: string;
193
+ safety_status: string;
194
+ events?: {
195
+ at: string;
196
+ act: string;
197
+ actor: string;
198
+ }[] | undefined;
199
+ digits?: string | undefined;
200
+ }, {
201
+ value: string;
202
+ is_preferred: boolean;
203
+ subject_type: "user" | "person";
204
+ subject_id: string;
205
+ notes: string;
206
+ entry_id: string;
207
+ period_start: string;
208
+ period_end: string;
209
+ source: string;
210
+ method: string;
211
+ contact_type: "email" | "phone";
212
+ use: string;
213
+ safety_status: string;
214
+ events?: {
215
+ at: string;
216
+ act: string;
217
+ actor: string;
218
+ }[] | undefined;
219
+ digits?: string | undefined;
220
+ }>;
221
+ type SeatContactEntry = z.infer<typeof SeatContactEntrySchema>;
222
+ /** The subject an operation acts on. */
223
+ interface SeatLogSubject {
224
+ subject_type: SeatLogSubjectType;
225
+ subject_id: string;
226
+ }
227
+
228
+ /**
229
+ * Raw-driver reads of the seat logs (no mongoose, no driver import), typed
230
+ * structurally like the points-of-contact reads: a `mongodb` `Db` or a
231
+ * mongoose connection's `.db` both fit. Ids are the string form, so no
232
+ * ObjectId is needed. A stored row that does not match the entry shape
233
+ * throws by default (an unreadable log never reads as empty); a read that
234
+ * must go on past one bad row passes `{ invalid: "skip" }`.
235
+ */
236
+
237
+ /** The slice of a driver `Db` the reads use. */
238
+ interface SeatLogDbLike {
239
+ collection(name: string): {
240
+ find(filter: Record<string, unknown>): {
241
+ toArray(): Promise<unknown[]>;
242
+ };
243
+ };
244
+ }
245
+ /** A stored entry that does not match the contract. */
246
+ declare class SeatLogShapeError extends Error {
247
+ readonly entryId: string | null;
248
+ readonly issues: string[];
249
+ constructor(entryId: string | null, issues: string[]);
250
+ }
251
+ /** How a read treats a stored row that does not match the entry shape. */
252
+ interface SeatLogReadOptions {
253
+ /**
254
+ * `throw` (default): the read fails with {@link SeatLogShapeError} — for a
255
+ * write path, which must not act on a log it cannot fully read.
256
+ * `skip`: the row is left out of its subject's log and reported to
257
+ * `onInvalidRow`; the rest of the read goes on.
258
+ */
259
+ invalid?: "throw" | "skip";
260
+ onInvalidRow?: (error: SeatLogShapeError) => void;
261
+ }
262
+ /**
263
+ * Each subject's name entries (live and retired), in entry_id order, keyed by
264
+ * the subject id as asked (matched case-insensitively). Absent ids have no log.
265
+ */
266
+ declare function readSeatNameLogs(db: SeatLogDbLike, subjectIds: readonly string[], subjectType?: SeatLogSubjectType, opts?: SeatLogReadOptions): Promise<Map<string, SeatNameEntry[]>>;
267
+ /**
268
+ * Each subject's contact entries (live and retired), in entry_id order, keyed
269
+ * by the subject id as asked (matched case-insensitively). Absent ids have no log.
270
+ */
271
+ declare function readSeatContactLogs(db: SeatLogDbLike, subjectIds: readonly string[], subjectType?: SeatLogSubjectType, opts?: SeatLogReadOptions): Promise<Map<string, SeatContactEntry[]>>;
272
+
273
+ export { type SeatNameEntry as S, type SeatLogSubject as a, type SeatContactEntry as b, type SeatContactType as c, type SeatNameType as d, SEAT_CONTACTS_COLLECTION as e, SEAT_CONTACT_TYPES as f, SEAT_LOG_SUBJECT_TYPES as g, SEAT_NAMES_COLLECTION as h, SEAT_NAME_ADD_TYPES as i, SEAT_NAME_TYPES as j, SeatContactEntrySchema as k, type SeatLogDbLike as l, type SeatLogEvent as m, SeatLogEventSchema as n, type SeatLogReadOptions as o, SeatLogShapeError as p, type SeatLogSubjectType as q, SeatNameEntrySchema as r, readSeatContactLogs as s, readSeatNameLogs as t };
@@ -0,0 +1,273 @@
1
+ import { z } from 'zod';
2
+ import { NameTypeKeys } from './enums/index.cjs';
3
+
4
+ /**
5
+ * A seat's NAME log and CONTACT log: the stored entry shapes.
6
+ *
7
+ * Canon: platform-prototype `src/screens.jsx` @ 398fb24 `SeatNamesLedger`
8
+ * (L25149-L25288) and `SeatMethodsLedger` (L24981-L25137), over the object
9
+ * store `src/objectStore.js` (`addEntry` / `act`, L660-L740) and the spine
10
+ * cascade `src/objectStructuresEngine.generated.js` (`HTI_OBJECT_SPINE`,
11
+ * L942-L1049).
12
+ *
13
+ * The record (Person Data Object, step 6c, Crysta 2026-10-11): "a seat's name
14
+ * and contact rails stay keyed by the seat". So an entry's subject is the seat
15
+ * (`subject_type: "user"`, `subject_id` = the platform-db `users._id`, string
16
+ * form). A registry person's name rides the same log with
17
+ * `subject_type: "person"` (Person decision B).
18
+ *
19
+ * Names, contact details and addresses are not fields of a Person; each is
20
+ * its own log that points at the subject, so every entry carries its own
21
+ * source and dates (Person § 3). An entry is never edited in place: a
22
+ * correction inserts a new entry and archives the old one (`period_end`), and
23
+ * a retired entry stays in the log with its dates.
24
+ *
25
+ * Field shapes are the prototype's as stored: open dates are the empty string
26
+ * `""` (not null), a closed entry carries `period_end` `YYYY-MM-DD`; the store
27
+ * stamps an `events[]` audit trail (`{ act, at, actor }`) and a phone's
28
+ * `digits` key.
29
+ */
30
+
31
+ /** Platform-db collection holding name entries (all subjects). */
32
+ declare const SEAT_NAMES_COLLECTION = "seat_names";
33
+ /** Platform-db collection holding contact entries (all subjects). */
34
+ declare const SEAT_CONTACTS_COLLECTION = "seat_contacts";
35
+ /** Whose log: a seat (`users._id`) or a registry person (`per-…` id). */
36
+ declare const SEAT_LOG_SUBJECT_TYPES: readonly ["user", "person"];
37
+ type SeatLogSubjectType = (typeof SEAT_LOG_SUBJECT_TYPES)[number];
38
+ /** The two contact types the seat ledger carries (prototype Email / Phone chips). */
39
+ declare const SEAT_CONTACT_TYPES: readonly ["email", "phone"];
40
+ type SeatContactType = (typeof SEAT_CONTACT_TYPES)[number];
41
+ /** CVC-1 `name_type` keys (the prototype stores `alias` / `legal`). */
42
+ declare const SEAT_NAME_TYPES: [keyof typeof NameTypeKeys, ...(keyof typeof NameTypeKeys)[]];
43
+ type SeatNameType = keyof typeof NameTypeKeys;
44
+ /** The name types the profile's add row offers, in its chip order. */
45
+ declare const SEAT_NAME_ADD_TYPES: readonly [{
46
+ readonly name_type: "alias";
47
+ readonly label: "Also known as";
48
+ }, {
49
+ readonly name_type: "legal";
50
+ readonly label: "Legal name";
51
+ }];
52
+ /** One audit event the store stamps on an entry. */
53
+ declare const SeatLogEventSchema: z.ZodObject<{
54
+ /** `add`, `set_display`, `set_preferred`, `archive`, or `cascade` (a sibling's flag moved). */
55
+ act: z.ZodString;
56
+ /** ISO instant. */
57
+ at: z.ZodString;
58
+ /** The acting seat's id. */
59
+ actor: z.ZodString;
60
+ }, "strip", z.ZodTypeAny, {
61
+ at: string;
62
+ act: string;
63
+ actor: string;
64
+ }, {
65
+ at: string;
66
+ act: string;
67
+ actor: string;
68
+ }>;
69
+ type SeatLogEvent = z.infer<typeof SeatLogEventSchema>;
70
+ /** One name in a seat's (or registry person's) name log. */
71
+ declare const SeatNameEntrySchema: z.ZodObject<{
72
+ name_type: z.ZodEnum<["unknown" | "missingness_root" | "anonymous" | "data_not_collected" | "alias" | "code_name" | "handle_screenname" | "legal" | "maiden_former" | "nickname" | "street_name" | "trade_name_stage_name", ...("unknown" | "missingness_root" | "anonymous" | "data_not_collected" | "alias" | "code_name" | "handle_screenname" | "legal" | "maiden_former" | "nickname" | "street_name" | "trade_name_stage_name")[]]>;
73
+ /** The name as written. */
74
+ raw: z.ZodString;
75
+ /** The display name: one live entry per subject carries it. */
76
+ is_display: z.ZodBoolean;
77
+ /** Set with the display mark on the profile (prototype acts both together). */
78
+ is_preferred: z.ZodBoolean;
79
+ entry_id: z.ZodString;
80
+ subject_id: z.ZodString;
81
+ subject_type: z.ZodEnum<["user", "person"]>;
82
+ period_start: z.ZodUnion<[z.ZodLiteral<"">, z.ZodString]>;
83
+ period_end: z.ZodUnion<[z.ZodLiteral<"">, z.ZodString]>;
84
+ /** Where the entry came from (`admin_hub` on the profile). */
85
+ source: z.ZodString;
86
+ /** How it was captured (`direct_entry` on the profile). */
87
+ method: z.ZodString;
88
+ notes: z.ZodString;
89
+ events: z.ZodOptional<z.ZodArray<z.ZodObject<{
90
+ /** `add`, `set_display`, `set_preferred`, `archive`, or `cascade` (a sibling's flag moved). */
91
+ act: z.ZodString;
92
+ /** ISO instant. */
93
+ at: z.ZodString;
94
+ /** The acting seat's id. */
95
+ actor: z.ZodString;
96
+ }, "strip", z.ZodTypeAny, {
97
+ at: string;
98
+ act: string;
99
+ actor: string;
100
+ }, {
101
+ at: string;
102
+ act: string;
103
+ actor: string;
104
+ }>, "many">>;
105
+ }, "strip", z.ZodTypeAny, {
106
+ is_preferred: boolean;
107
+ subject_type: "user" | "person";
108
+ subject_id: string;
109
+ notes: string;
110
+ name_type: "unknown" | "missingness_root" | "anonymous" | "data_not_collected" | "alias" | "code_name" | "handle_screenname" | "legal" | "maiden_former" | "nickname" | "street_name" | "trade_name_stage_name";
111
+ raw: string;
112
+ is_display: boolean;
113
+ entry_id: string;
114
+ period_start: string;
115
+ period_end: string;
116
+ source: string;
117
+ method: string;
118
+ events?: {
119
+ at: string;
120
+ act: string;
121
+ actor: string;
122
+ }[] | undefined;
123
+ }, {
124
+ is_preferred: boolean;
125
+ subject_type: "user" | "person";
126
+ subject_id: string;
127
+ notes: string;
128
+ name_type: "unknown" | "missingness_root" | "anonymous" | "data_not_collected" | "alias" | "code_name" | "handle_screenname" | "legal" | "maiden_former" | "nickname" | "street_name" | "trade_name_stage_name";
129
+ raw: string;
130
+ is_display: boolean;
131
+ entry_id: string;
132
+ period_start: string;
133
+ period_end: string;
134
+ source: string;
135
+ method: string;
136
+ events?: {
137
+ at: string;
138
+ act: string;
139
+ actor: string;
140
+ }[] | undefined;
141
+ }>;
142
+ type SeatNameEntry = z.infer<typeof SeatNameEntrySchema>;
143
+ /** One email or phone in a seat's contact log. */
144
+ declare const SeatContactEntrySchema: z.ZodObject<{
145
+ contact_type: z.ZodEnum<["email", "phone"]>;
146
+ /** Email trimmed; phone in the store's canonical display form ({@link canonSeatContactValue}). */
147
+ value: z.ZodString;
148
+ use: z.ZodString;
149
+ /** The preferred entry of its type: one live entry per subject and type carries it. */
150
+ is_preferred: z.ZodBoolean;
151
+ safety_status: z.ZodString;
152
+ /** Phone only: the identity key ({@link seatContactKey}), stamped by the store. */
153
+ digits: z.ZodOptional<z.ZodString>;
154
+ entry_id: z.ZodString;
155
+ subject_id: z.ZodString;
156
+ subject_type: z.ZodEnum<["user", "person"]>;
157
+ period_start: z.ZodUnion<[z.ZodLiteral<"">, z.ZodString]>;
158
+ period_end: z.ZodUnion<[z.ZodLiteral<"">, z.ZodString]>;
159
+ /** Where the entry came from (`admin_hub` on the profile). */
160
+ source: z.ZodString;
161
+ /** How it was captured (`direct_entry` on the profile). */
162
+ method: z.ZodString;
163
+ notes: z.ZodString;
164
+ events: z.ZodOptional<z.ZodArray<z.ZodObject<{
165
+ /** `add`, `set_display`, `set_preferred`, `archive`, or `cascade` (a sibling's flag moved). */
166
+ act: z.ZodString;
167
+ /** ISO instant. */
168
+ at: z.ZodString;
169
+ /** The acting seat's id. */
170
+ actor: z.ZodString;
171
+ }, "strip", z.ZodTypeAny, {
172
+ at: string;
173
+ act: string;
174
+ actor: string;
175
+ }, {
176
+ at: string;
177
+ act: string;
178
+ actor: string;
179
+ }>, "many">>;
180
+ }, "strip", z.ZodTypeAny, {
181
+ value: string;
182
+ is_preferred: boolean;
183
+ subject_type: "user" | "person";
184
+ subject_id: string;
185
+ notes: string;
186
+ entry_id: string;
187
+ period_start: string;
188
+ period_end: string;
189
+ source: string;
190
+ method: string;
191
+ contact_type: "email" | "phone";
192
+ use: string;
193
+ safety_status: string;
194
+ events?: {
195
+ at: string;
196
+ act: string;
197
+ actor: string;
198
+ }[] | undefined;
199
+ digits?: string | undefined;
200
+ }, {
201
+ value: string;
202
+ is_preferred: boolean;
203
+ subject_type: "user" | "person";
204
+ subject_id: string;
205
+ notes: string;
206
+ entry_id: string;
207
+ period_start: string;
208
+ period_end: string;
209
+ source: string;
210
+ method: string;
211
+ contact_type: "email" | "phone";
212
+ use: string;
213
+ safety_status: string;
214
+ events?: {
215
+ at: string;
216
+ act: string;
217
+ actor: string;
218
+ }[] | undefined;
219
+ digits?: string | undefined;
220
+ }>;
221
+ type SeatContactEntry = z.infer<typeof SeatContactEntrySchema>;
222
+ /** The subject an operation acts on. */
223
+ interface SeatLogSubject {
224
+ subject_type: SeatLogSubjectType;
225
+ subject_id: string;
226
+ }
227
+
228
+ /**
229
+ * Raw-driver reads of the seat logs (no mongoose, no driver import), typed
230
+ * structurally like the points-of-contact reads: a `mongodb` `Db` or a
231
+ * mongoose connection's `.db` both fit. Ids are the string form, so no
232
+ * ObjectId is needed. A stored row that does not match the entry shape
233
+ * throws by default (an unreadable log never reads as empty); a read that
234
+ * must go on past one bad row passes `{ invalid: "skip" }`.
235
+ */
236
+
237
+ /** The slice of a driver `Db` the reads use. */
238
+ interface SeatLogDbLike {
239
+ collection(name: string): {
240
+ find(filter: Record<string, unknown>): {
241
+ toArray(): Promise<unknown[]>;
242
+ };
243
+ };
244
+ }
245
+ /** A stored entry that does not match the contract. */
246
+ declare class SeatLogShapeError extends Error {
247
+ readonly entryId: string | null;
248
+ readonly issues: string[];
249
+ constructor(entryId: string | null, issues: string[]);
250
+ }
251
+ /** How a read treats a stored row that does not match the entry shape. */
252
+ interface SeatLogReadOptions {
253
+ /**
254
+ * `throw` (default): the read fails with {@link SeatLogShapeError} — for a
255
+ * write path, which must not act on a log it cannot fully read.
256
+ * `skip`: the row is left out of its subject's log and reported to
257
+ * `onInvalidRow`; the rest of the read goes on.
258
+ */
259
+ invalid?: "throw" | "skip";
260
+ onInvalidRow?: (error: SeatLogShapeError) => void;
261
+ }
262
+ /**
263
+ * Each subject's name entries (live and retired), in entry_id order, keyed by
264
+ * the subject id as asked (matched case-insensitively). Absent ids have no log.
265
+ */
266
+ declare function readSeatNameLogs(db: SeatLogDbLike, subjectIds: readonly string[], subjectType?: SeatLogSubjectType, opts?: SeatLogReadOptions): Promise<Map<string, SeatNameEntry[]>>;
267
+ /**
268
+ * Each subject's contact entries (live and retired), in entry_id order, keyed
269
+ * by the subject id as asked (matched case-insensitively). Absent ids have no log.
270
+ */
271
+ declare function readSeatContactLogs(db: SeatLogDbLike, subjectIds: readonly string[], subjectType?: SeatLogSubjectType, opts?: SeatLogReadOptions): Promise<Map<string, SeatContactEntry[]>>;
272
+
273
+ export { type SeatNameEntry as S, type SeatLogSubject as a, type SeatContactEntry as b, type SeatContactType as c, type SeatNameType as d, SEAT_CONTACTS_COLLECTION as e, SEAT_CONTACT_TYPES as f, SEAT_LOG_SUBJECT_TYPES as g, SEAT_NAMES_COLLECTION as h, SEAT_NAME_ADD_TYPES as i, SEAT_NAME_TYPES as j, SeatContactEntrySchema as k, type SeatLogDbLike as l, type SeatLogEvent as m, SeatLogEventSchema as n, type SeatLogReadOptions as o, SeatLogShapeError as p, type SeatLogSubjectType as q, SeatNameEntrySchema as r, readSeatContactLogs as s, readSeatNameLogs as t };
@@ -6230,7 +6230,18 @@ var organizationProgramSchemaDefinition = {
6230
6230
  */
6231
6231
  locationId: { type: String, required: false },
6232
6232
  /** The editor's notes. */
6233
- notes: { type: String, required: false }
6233
+ notes: { type: String, required: false },
6234
+ /**
6235
+ * The first team that works for the program (`teams._id` as a string;
6236
+ * canon `team_id`). Equal to `teamIds[0]` when both are written.
6237
+ */
6238
+ teamId: { type: String, required: false },
6239
+ /**
6240
+ * Every team that works for the program (canon `team_ids`; one program may
6241
+ * have several teams). `default: undefined`, so a row with no link stores
6242
+ * nothing and reads as absent, never as an empty list.
6243
+ */
6244
+ teamIds: { type: [String], required: false, default: void 0 }
6234
6245
  };
6235
6246
  function buildOrganizationProgramSchema() {
6236
6247
  return new import_mongoose13.Schema(organizationProgramSchemaDefinition, { _id: false });