@htilabs/platform-common-models 0.86.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 (44) hide show
  1. package/README.md +18 -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.d.cts +3 -3
  5. package/dist/index.d.ts +3 -3
  6. package/dist/models/index.d.cts +2 -2
  7. package/dist/models/index.d.ts +2 -2
  8. package/dist/org-merge/index.cjs.map +1 -1
  9. package/dist/org-merge/index.js.map +1 -1
  10. package/dist/points-of-contact/index.cjs +222 -23
  11. package/dist/points-of-contact/index.cjs.map +1 -1
  12. package/dist/points-of-contact/index.d.cts +50 -5
  13. package/dist/points-of-contact/index.d.ts +50 -5
  14. package/dist/points-of-contact/index.js +219 -22
  15. package/dist/points-of-contact/index.js.map +1 -1
  16. package/dist/reader-BmhzOis-.d.ts +273 -0
  17. package/dist/reader-DfQtdw6n.d.cts +273 -0
  18. package/dist/schemas/index.d.cts +25 -25
  19. package/dist/schemas/index.d.ts +25 -25
  20. package/dist/seat-logs/index.cjs +815 -0
  21. package/dist/seat-logs/index.cjs.map +1 -0
  22. package/dist/seat-logs/index.d.cts +274 -0
  23. package/dist/seat-logs/index.d.ts +274 -0
  24. package/dist/seat-logs/index.js +742 -0
  25. package/dist/seat-logs/index.js.map +1 -0
  26. package/dist/validation/index.d.cts +1 -1
  27. package/dist/validation/index.d.ts +1 -1
  28. package/package.json +6 -1
  29. package/src/pointsOfContact/__tests__/seatContactLog.test.ts +170 -0
  30. package/src/pointsOfContact/readRules.ts +22 -4
  31. package/src/pointsOfContact/reader.ts +95 -1
  32. package/src/pointsOfContact/schemas.ts +4 -3
  33. package/src/seatLogs/__tests__/seatLogs.review.test.ts +222 -0
  34. package/src/seatLogs/__tests__/seatLogs.test.ts +335 -0
  35. package/src/seatLogs/index.ts +15 -0
  36. package/src/seatLogs/log.ts +700 -0
  37. package/src/seatLogs/personId.ts +100 -0
  38. package/src/seatLogs/personSlugWordlists.ts +40 -0
  39. package/src/seatLogs/reader.ts +143 -0
  40. package/src/seatLogs/schemas.ts +118 -0
  41. package/dist/{agency-CnVTwLeV.d.ts → agency-BHv54o79.d.ts} +4 -4
  42. package/dist/{agency-8ufZJJDH.d.cts → agency-Djp57S71.d.cts} +4 -4
  43. package/dist/{cvcEntry-D787utvP.d.cts → cvcEntry-DAuhe0cd.d.cts} +8 -8
  44. package/dist/{cvcEntry-D787utvP.d.ts → cvcEntry-DAuhe0cd.d.ts} +8 -8
@@ -0,0 +1,274 @@
1
+ import { S as SeatNameEntry, a as SeatLogSubject, b as SeatContactEntry, c as SeatContactType, d as SeatNameType } from '../reader-DfQtdw6n.cjs';
2
+ export { e as SEAT_CONTACTS_COLLECTION, f as SEAT_CONTACT_TYPES, g as SEAT_LOG_SUBJECT_TYPES, h as SEAT_NAMES_COLLECTION, i as SEAT_NAME_ADD_TYPES, j as SEAT_NAME_TYPES, k as SeatContactEntrySchema, l as SeatLogDbLike, m as SeatLogEvent, n as SeatLogEventSchema, o as SeatLogReadOptions, p as SeatLogShapeError, q as SeatLogSubjectType, r as SeatNameEntrySchema, s as readSeatContactLogs, t as readSeatNameLogs } from '../reader-DfQtdw6n.cjs';
3
+ import 'zod';
4
+ import '../enums/index.cjs';
5
+
6
+ /**
7
+ * The seat name log and contact log: the rules every writer applies. Pure, no
8
+ * I/O. Each operation takes the subject's current entries, returns the next
9
+ * entries plus which entries were inserted and which changed, so the caller
10
+ * writes exactly those rows (insert the new, update the changed) and never
11
+ * rewrites the whole log.
12
+ *
13
+ * Canon: platform-prototype `src/screens.jsx` @ 398fb24 (`SeatNamesLedger`
14
+ * L25149-L25288, `SeatMethodsLedger` L24981-L25137, `umSeatPhoneGuard`
15
+ * L24972-L24978, the email / name guards L25335-L25340), the store's
16
+ * `addEntry` / `act` (`src/objectStore.js` L660-L740: phone normalized at the
17
+ * boundary, the `digits` key stamped, `events[]` appended) and the spine
18
+ * cascade (`src/objectStructuresEngine.generated.js` L942-L1049: one display
19
+ * name per subject, one preferred contact per subject and type, an archived
20
+ * entry loses both flags).
21
+ *
22
+ * Rules carried here:
23
+ * - Display / preferred invariants: one live `is_display` (and with it
24
+ * `is_preferred`, which the profile always moves together) per subject on
25
+ * the name log; one live `is_preferred` per subject AND contact type on the
26
+ * contact log. The first live entry takes the mark.
27
+ * - Correction = insert the new entry, carry the mark onto it, archive the
28
+ * old one (`period_end` = today). Never edit in place. Correcting INTO a
29
+ * value already live hands that entry the mark and archives the wrong one.
30
+ * - A name log with no entries reads its seat's flat name as a synthetic
31
+ * `__flat__` row; the log is seeded from it (a `legal` display entry) only
32
+ * on the first real act.
33
+ * - The display name can't be retired (the ✕ is absent on its row); a
34
+ * preferred contact can't be retired while another live entry of its type
35
+ * exists.
36
+ * - Every act targets a LIVE entry; a retired entry id is refused
37
+ * (`entry_not_live`) with nothing changed — a stale tab or a double submit
38
+ * never moves a mark onto, re-dates or corrects a retired entry.
39
+ * - `events[]` is stamped as the store stamps it: per store call, `cascade`
40
+ * on every row whose display / preferred / period_end changed (the target
41
+ * included), then the call's own event (`add`, `set_display`,
42
+ * `set_preferred`, `archive`) on its target.
43
+ * - Entry ids: the default minter never collides within one act; the store
44
+ * needs a unique index on `entry_id` for collisions across requests.
45
+ */
46
+
47
+ /** The synthetic row id a seat with no name log shows its flat name under. */
48
+ declare const FLAT_NAME_ENTRY_ID = "__flat__";
49
+ /** Who acts and when. `mintId` overrides the default id shape (tests). */
50
+ interface SeatLogContext {
51
+ /** The acting seat's id (stamped on `events[]`). */
52
+ actor: string;
53
+ /** ISO instant; `period_end` on an archive is its day. Defaults to now. */
54
+ at?: string;
55
+ /**
56
+ * Mints an entry id. Default {@link mintSeatLogEntryId}. An id that clashes
57
+ * with a row already in the log is re-minted (up to 20 tries).
58
+ */
59
+ mintId?: (kind: "name" | "contact", subject: SeatLogSubject) => string;
60
+ }
61
+ /** What an operation did. `entries` is the subject's whole next log. */
62
+ interface SeatLogChange<E> {
63
+ entries: E[];
64
+ /** New rows to insert. */
65
+ inserted: E[];
66
+ /** Existing rows whose flags, dates, notes or events changed. */
67
+ updated: E[];
68
+ }
69
+ /** A refused act: the reason, in the profile's words. */
70
+ declare class SeatLogRefusal extends Error {
71
+ readonly code: "name_blank" | "display_name_not_retirable" | "preferred_contact_not_retirable" | "entry_not_found" | "entry_not_live" | "email_shape" | "email_taken" | "phone_no_digits" | "phone_too_short" | "phone_too_long";
72
+ constructor(code: "name_blank" | "display_name_not_retirable" | "preferred_contact_not_retirable" | "entry_not_found" | "entry_not_live" | "email_shape" | "email_taken" | "phone_no_digits" | "phone_too_short" | "phone_too_long", message: string);
73
+ }
74
+ /**
75
+ * The entry id: the prototype's shape, `nm-<subject>-rt<time><rand>` /
76
+ * `ci-<subject>-rt<time><rand>`, with 8 random base-36 characters where the
77
+ * prototype has 1, so two ids minted in the same millisecond do not collide
78
+ * (36^8 ≈ 2.8 × 10^12). Within one act a clash with a row already in the log
79
+ * is re-minted (see {@link SeatLogContext.mintId}); across subjects and
80
+ * requests the store's unique index on `entry_id` is the backstop.
81
+ */
82
+ declare function mintSeatLogEntryId(kind: "name" | "contact", subject: SeatLogSubject): string;
83
+ /** The profile's refusal for a blank name. */
84
+ declare const SEAT_NAME_BLANK_REFUSAL = "A member keeps a name \u2014 the directory row can't go blank.";
85
+ /** Live entries, in log order. */
86
+ declare function liveSeatNames(entries: readonly SeatNameEntry[]): SeatNameEntry[];
87
+ /** Retired entries ("Past names"). */
88
+ declare function pastSeatNames(entries: readonly SeatNameEntry[]): SeatNameEntry[];
89
+ /** The display entry: the live one marked display, else the first live one, else null. */
90
+ declare function seatDisplayNameEntry(entries: readonly SeatNameEntry[]): SeatNameEntry | null;
91
+ /**
92
+ * The seat's flat `name` projection: the display entry's `raw`, or `null`
93
+ * when the log has no live entry (the caller keeps the flat name as it is —
94
+ * the prototype only writes a non-empty projection).
95
+ */
96
+ declare function seatNameProjection(entries: readonly SeatNameEntry[]): string | null;
97
+ /** A synthetic display row standing for the flat name when the log is empty. */
98
+ type FlatNameRow = Pick<SeatNameEntry, "entry_id" | "raw" | "name_type" | "is_display">;
99
+ /**
100
+ * The rows the Names list draws: the live log, or the flat name as one
101
+ * `__flat__` display row when the log has none (nothing is written for it).
102
+ */
103
+ declare function seatNameRows(entries: readonly SeatNameEntry[], flatName: string | null | undefined): (SeatNameEntry | FlatNameRow)[];
104
+ /**
105
+ * Seed the log from the seat's flat name (a `legal` display entry). A no-op
106
+ * when the log already has a live entry or the flat name is blank. Every act
107
+ * below does this first; exposed for a caller that needs the log minted.
108
+ */
109
+ declare function seedSeatNameLog(entries: readonly SeatNameEntry[], subject: SeatLogSubject, flatName: string | null | undefined, ctx: SeatLogContext): SeatLogChange<SeatNameEntry>;
110
+ /**
111
+ * Add a name. Seeds from the flat name first; a name already live (exact
112
+ * text) is a no-op; the first live name becomes the display name.
113
+ */
114
+ declare function addSeatName(entries: readonly SeatNameEntry[], subject: SeatLogSubject, input: {
115
+ raw: string;
116
+ name_type: SeatNameType;
117
+ }, ctx: SeatLogContext & {
118
+ flatName?: string | null;
119
+ }): SeatLogChange<SeatNameEntry>;
120
+ /** Make an entry the display name (★); moves the preferred mark with it. */
121
+ declare function setSeatDisplayName(entries: readonly SeatNameEntry[], subject: SeatLogSubject, entryId: string, ctx: SeatLogContext & {
122
+ flatName?: string | null;
123
+ }): SeatLogChange<SeatNameEntry>;
124
+ /**
125
+ * Correct a name: insert the corrected entry ("Corrects “old”" in its notes),
126
+ * carry the display mark onto it, archive the old one. `entryId` may be
127
+ * `__flat__` (the log is seeded from the flat name, then corrected). The same
128
+ * text (after trimming) is a no-op.
129
+ */
130
+ declare function correctSeatName(entries: readonly SeatNameEntry[], subject: SeatLogSubject, entryId: string, next: string, ctx: SeatLogContext & {
131
+ flatName?: string | null;
132
+ }): SeatLogChange<SeatNameEntry>;
133
+ /** Retire a name (stays in the log, dated). The display name is refused. */
134
+ declare function retireSeatName(entries: readonly SeatNameEntry[], subject: SeatLogSubject, entryId: string, ctx: SeatLogContext): SeatLogChange<SeatNameEntry>;
135
+ /**
136
+ * How a phone is DRAWN and stored on the seat log: every non-digit dropped, a
137
+ * redundant US `1` dropped, `(AAA) BBB-CCCC`, `+cc (AAA) BBB-CCCC` past ten
138
+ * digits. Canon `formatPhone` (objectStructuresEngine L232-L244), verbatim in
139
+ * behaviour. Empty when there is no digit.
140
+ */
141
+ declare function formatSeatPhone(s: string): string;
142
+ /**
143
+ * How a value is WRITTEN (PHONE-NORMALIZE 2026-08-28): trimmed; a phone in
144
+ * {@link formatSeatPhone}'s form, or as typed when it has no digit. Canon
145
+ * `canonContactValue` (objectStore L618-L623).
146
+ */
147
+ declare function canonSeatContactValue(type: SeatContactType, value: string): string;
148
+ /**
149
+ * WHICH contact this is (PHONE-DIGITS-KEY 2026-08-28): a phone's digits with a
150
+ * leading US `1` dropped; an email's lowercased text. Canon `contactKey`
151
+ * (objectStore L648-L657) over `phoneDigits` (engine L268-L272).
152
+ */
153
+ declare function seatContactKey(type: SeatContactType, value: string): string;
154
+ /**
155
+ * The phone guard (`umSeatPhoneGuard`): `""` when acceptable (blank included —
156
+ * a seat may have no number on file), else the refusal in the profile's words.
157
+ * 7-15 digits (the object spine's `detectFromInput` bounds).
158
+ */
159
+ declare function seatPhoneRefusal(value: string): string;
160
+ /**
161
+ * The email guard: `""` when acceptable (blank included), else the refusal.
162
+ * `otherSeatEmails` are the addresses on OTHER seats (the directory-uniqueness
163
+ * check); the caller supplies them.
164
+ */
165
+ declare function seatEmailRefusal(value: string, otherSeatEmails?: Iterable<string>): string;
166
+ /** Live email and phone entries, in log order. */
167
+ declare function liveSeatContacts(entries: readonly SeatContactEntry[]): SeatContactEntry[];
168
+ /** Retired entries ("Past contact details"). */
169
+ declare function pastSeatContacts(entries: readonly SeatContactEntry[]): SeatContactEntry[];
170
+ /** The preferred live entry of a type, else the first live one, else null. */
171
+ declare function preferredSeatContact(entries: readonly SeatContactEntry[], type: SeatContactType): SeatContactEntry | null;
172
+ /**
173
+ * The seat's flat `email` projection (the login projection): the preferred
174
+ * email's value, or `""` when the log has no live email. Canon
175
+ * `syncEmailProjection` (screens.jsx L24987-L24993).
176
+ */
177
+ declare function seatEmailProjection(entries: readonly SeatContactEntry[]): string;
178
+ /** Whether the ✕ is offered: not on the preferred entry while another of its type is live. */
179
+ declare function canRetireSeatContact(entries: readonly SeatContactEntry[], entry: SeatContactEntry): boolean;
180
+ /**
181
+ * Add an email or phone. Refused by the type's guard; normalized; a value
182
+ * already live of the same type (by {@link seatContactKey}) is a no-op; the
183
+ * first live entry of its type becomes preferred.
184
+ */
185
+ declare function addSeatContact(entries: readonly SeatContactEntry[], subject: SeatLogSubject, input: {
186
+ contact_type: SeatContactType;
187
+ value: string;
188
+ }, ctx: SeatLogContext & {
189
+ otherSeatEmails?: Iterable<string>;
190
+ }): SeatLogChange<SeatContactEntry>;
191
+ /** Make an entry the preferred of its type (☆ prefer). */
192
+ declare function setPreferredSeatContact(entries: readonly SeatContactEntry[], subject: SeatLogSubject, entryId: string, ctx: SeatLogContext): SeatLogChange<SeatContactEntry>;
193
+ /**
194
+ * Correct an email or phone. Guarded and normalized like an add. Re-typing the
195
+ * same value in another shape is a no-op. Correcting INTO a live value of the
196
+ * same type hands it the preferred mark and archives the wrong one; otherwise
197
+ * the corrected entry is inserted ("Corrects “old”"), takes the mark, and the
198
+ * old one is archived.
199
+ */
200
+ declare function correctSeatContact(entries: readonly SeatContactEntry[], subject: SeatLogSubject, entryId: string, next: string, ctx: SeatLogContext & {
201
+ otherSeatEmails?: Iterable<string>;
202
+ }): SeatLogChange<SeatContactEntry>;
203
+ /** Retire an email or phone (stays in the log, dated). See {@link canRetireSeatContact}. */
204
+ declare function retireSeatContact(entries: readonly SeatContactEntry[], subject: SeatLogSubject, entryId: string, ctx: SeatLogContext): SeatLogChange<SeatContactEntry>;
205
+
206
+ /**
207
+ * The Person id: `per-<first>-<second>`, name-free (Person § "The id carries no
208
+ * name": "Display names carry identity; ids are stable and name-free").
209
+ *
210
+ * Canon: platform-prototype `src/screens.jsx` @ 398fb24 `mintPersonId`
211
+ * (L24354-L24363), drawing from the directory's `person_slug_wordlists`
212
+ * (`first`, `second`), which the records repo's directory generator
213
+ * (`tools/build_platform_directory.py`) emits.
214
+ *
215
+ * The wordlists default to the vendored copy of the records monolith's
216
+ * `PERSON_FIRST` / `PERSON_SECOND` (`./personSlugWordlists.ts`); a caller may
217
+ * still pass a directory build's `person_slug_wordlists` instead.
218
+ */
219
+ /** The directory build's slug wordlists. */
220
+ interface PersonSlugWordlists {
221
+ first: readonly string[];
222
+ second: readonly string[];
223
+ }
224
+ /** `per-` then two lowercase words, optionally a numeric suffix (`-<n>`) when the pair pool was full. */
225
+ declare const PERSON_ID_PATTERN: RegExp;
226
+ /** True for a string shaped like a Person id. */
227
+ declare function isPersonId(v: unknown): v is string;
228
+ /**
229
+ * Mint a Person id not in `taken`. `null` only when there are no wordlists
230
+ * (empty or `null`) — refuse rather than invent a shape.
231
+ *
232
+ * As the prototype (`mintPersonId`, screens.jsx L24352-L24363): up to 200
233
+ * random draws of `per-<first>-<second>`. If all 200 are taken, the whole
234
+ * two-word space is scanned in list order for a free pair. When every pair is
235
+ * taken (45 × 45 = 2,025 with the vendored lists), the records generator's
236
+ * full-pool rule applies (`generatePersonSlug`, records monolith: after its
237
+ * random tries fail it returns `<first>-<second>-<number 0-999>`): up to 200
238
+ * random `per-<first>-<second>-<0-999>`, then a deterministic scan over the
239
+ * pairs and suffixes 0, 1, 2, … until one is free, so a mint always ends.
240
+ *
241
+ * `taken` is a snapshot (every person id already held by a seat or a registry
242
+ * person; the caller supplies it), so two concurrent mints can return the
243
+ * same id: the store needs a UNIQUE index on the person id, and a caller
244
+ * retries the mint on a duplicate-key error. `random` must return `[0, 1)`;
245
+ * an out-of-range value is clamped. `wordlists` left `undefined` uses the
246
+ * vendored lists ({@link PERSON_SLUG_WORDLISTS}).
247
+ */
248
+ declare function mintPersonId(wordlists?: PersonSlugWordlists | null | undefined, taken?: Iterable<string | null | undefined>, random?: () => number): string | null;
249
+ /** Mint a Person id from the vendored wordlists, not in `taken` (or `null`). */
250
+ declare function mintNewPersonId(taken?: Iterable<string | null | undefined>, random?: () => number): string | null;
251
+
252
+ /**
253
+ * The Person id wordlists, vendored.
254
+ *
255
+ * Source: the records repo (htilabstech/prototype) @ 1be43ed5, the monolith
256
+ * `HTI-LEADS-PAVE-Thread-prototype.html` consts `PERSON_FIRST` and
257
+ * `PERSON_SECOND`, copied unchanged. The same lists reach the Platform
258
+ * prototype as the directory build's `person_slug_wordlists`
259
+ * (records `tools/build_platform_directory.py` → platform-prototype
260
+ * `src/data.js` `HTI_DIRECTORY.person_slug_wordlists`; equal at 398fb24).
261
+ *
262
+ * Do not hand-edit. A word added or removed in the records monolith is
263
+ * re-copied here; an id already minted keeps its words either way (ids are
264
+ * never re-derived from these lists).
265
+ */
266
+
267
+ /** `PERSON_FIRST` (45 words). */
268
+ declare const PERSON_SLUG_FIRST: readonly string[];
269
+ /** `PERSON_SECOND` (45 words). */
270
+ declare const PERSON_SLUG_SECOND: readonly string[];
271
+ /** The vendored wordlists, the default for `mintPersonId`. */
272
+ declare const PERSON_SLUG_WORDLISTS: PersonSlugWordlists;
273
+
274
+ export { FLAT_NAME_ENTRY_ID, type FlatNameRow, PERSON_ID_PATTERN, PERSON_SLUG_FIRST, PERSON_SLUG_SECOND, PERSON_SLUG_WORDLISTS, type PersonSlugWordlists, SEAT_NAME_BLANK_REFUSAL, SeatContactEntry, SeatContactType, type SeatLogChange, type SeatLogContext, SeatLogRefusal, SeatLogSubject, SeatNameEntry, SeatNameType, addSeatContact, addSeatName, canRetireSeatContact, canonSeatContactValue, correctSeatContact, correctSeatName, formatSeatPhone, isPersonId, liveSeatContacts, liveSeatNames, mintNewPersonId, mintPersonId, mintSeatLogEntryId, pastSeatContacts, pastSeatNames, preferredSeatContact, retireSeatContact, retireSeatName, seatContactKey, seatDisplayNameEntry, seatEmailProjection, seatEmailRefusal, seatNameProjection, seatNameRows, seatPhoneRefusal, seedSeatNameLog, setPreferredSeatContact, setSeatDisplayName };
@@ -0,0 +1,274 @@
1
+ import { S as SeatNameEntry, a as SeatLogSubject, b as SeatContactEntry, c as SeatContactType, d as SeatNameType } from '../reader-BmhzOis-.js';
2
+ export { e as SEAT_CONTACTS_COLLECTION, f as SEAT_CONTACT_TYPES, g as SEAT_LOG_SUBJECT_TYPES, h as SEAT_NAMES_COLLECTION, i as SEAT_NAME_ADD_TYPES, j as SEAT_NAME_TYPES, k as SeatContactEntrySchema, l as SeatLogDbLike, m as SeatLogEvent, n as SeatLogEventSchema, o as SeatLogReadOptions, p as SeatLogShapeError, q as SeatLogSubjectType, r as SeatNameEntrySchema, s as readSeatContactLogs, t as readSeatNameLogs } from '../reader-BmhzOis-.js';
3
+ import 'zod';
4
+ import '../enums/index.js';
5
+
6
+ /**
7
+ * The seat name log and contact log: the rules every writer applies. Pure, no
8
+ * I/O. Each operation takes the subject's current entries, returns the next
9
+ * entries plus which entries were inserted and which changed, so the caller
10
+ * writes exactly those rows (insert the new, update the changed) and never
11
+ * rewrites the whole log.
12
+ *
13
+ * Canon: platform-prototype `src/screens.jsx` @ 398fb24 (`SeatNamesLedger`
14
+ * L25149-L25288, `SeatMethodsLedger` L24981-L25137, `umSeatPhoneGuard`
15
+ * L24972-L24978, the email / name guards L25335-L25340), the store's
16
+ * `addEntry` / `act` (`src/objectStore.js` L660-L740: phone normalized at the
17
+ * boundary, the `digits` key stamped, `events[]` appended) and the spine
18
+ * cascade (`src/objectStructuresEngine.generated.js` L942-L1049: one display
19
+ * name per subject, one preferred contact per subject and type, an archived
20
+ * entry loses both flags).
21
+ *
22
+ * Rules carried here:
23
+ * - Display / preferred invariants: one live `is_display` (and with it
24
+ * `is_preferred`, which the profile always moves together) per subject on
25
+ * the name log; one live `is_preferred` per subject AND contact type on the
26
+ * contact log. The first live entry takes the mark.
27
+ * - Correction = insert the new entry, carry the mark onto it, archive the
28
+ * old one (`period_end` = today). Never edit in place. Correcting INTO a
29
+ * value already live hands that entry the mark and archives the wrong one.
30
+ * - A name log with no entries reads its seat's flat name as a synthetic
31
+ * `__flat__` row; the log is seeded from it (a `legal` display entry) only
32
+ * on the first real act.
33
+ * - The display name can't be retired (the ✕ is absent on its row); a
34
+ * preferred contact can't be retired while another live entry of its type
35
+ * exists.
36
+ * - Every act targets a LIVE entry; a retired entry id is refused
37
+ * (`entry_not_live`) with nothing changed — a stale tab or a double submit
38
+ * never moves a mark onto, re-dates or corrects a retired entry.
39
+ * - `events[]` is stamped as the store stamps it: per store call, `cascade`
40
+ * on every row whose display / preferred / period_end changed (the target
41
+ * included), then the call's own event (`add`, `set_display`,
42
+ * `set_preferred`, `archive`) on its target.
43
+ * - Entry ids: the default minter never collides within one act; the store
44
+ * needs a unique index on `entry_id` for collisions across requests.
45
+ */
46
+
47
+ /** The synthetic row id a seat with no name log shows its flat name under. */
48
+ declare const FLAT_NAME_ENTRY_ID = "__flat__";
49
+ /** Who acts and when. `mintId` overrides the default id shape (tests). */
50
+ interface SeatLogContext {
51
+ /** The acting seat's id (stamped on `events[]`). */
52
+ actor: string;
53
+ /** ISO instant; `period_end` on an archive is its day. Defaults to now. */
54
+ at?: string;
55
+ /**
56
+ * Mints an entry id. Default {@link mintSeatLogEntryId}. An id that clashes
57
+ * with a row already in the log is re-minted (up to 20 tries).
58
+ */
59
+ mintId?: (kind: "name" | "contact", subject: SeatLogSubject) => string;
60
+ }
61
+ /** What an operation did. `entries` is the subject's whole next log. */
62
+ interface SeatLogChange<E> {
63
+ entries: E[];
64
+ /** New rows to insert. */
65
+ inserted: E[];
66
+ /** Existing rows whose flags, dates, notes or events changed. */
67
+ updated: E[];
68
+ }
69
+ /** A refused act: the reason, in the profile's words. */
70
+ declare class SeatLogRefusal extends Error {
71
+ readonly code: "name_blank" | "display_name_not_retirable" | "preferred_contact_not_retirable" | "entry_not_found" | "entry_not_live" | "email_shape" | "email_taken" | "phone_no_digits" | "phone_too_short" | "phone_too_long";
72
+ constructor(code: "name_blank" | "display_name_not_retirable" | "preferred_contact_not_retirable" | "entry_not_found" | "entry_not_live" | "email_shape" | "email_taken" | "phone_no_digits" | "phone_too_short" | "phone_too_long", message: string);
73
+ }
74
+ /**
75
+ * The entry id: the prototype's shape, `nm-<subject>-rt<time><rand>` /
76
+ * `ci-<subject>-rt<time><rand>`, with 8 random base-36 characters where the
77
+ * prototype has 1, so two ids minted in the same millisecond do not collide
78
+ * (36^8 ≈ 2.8 × 10^12). Within one act a clash with a row already in the log
79
+ * is re-minted (see {@link SeatLogContext.mintId}); across subjects and
80
+ * requests the store's unique index on `entry_id` is the backstop.
81
+ */
82
+ declare function mintSeatLogEntryId(kind: "name" | "contact", subject: SeatLogSubject): string;
83
+ /** The profile's refusal for a blank name. */
84
+ declare const SEAT_NAME_BLANK_REFUSAL = "A member keeps a name \u2014 the directory row can't go blank.";
85
+ /** Live entries, in log order. */
86
+ declare function liveSeatNames(entries: readonly SeatNameEntry[]): SeatNameEntry[];
87
+ /** Retired entries ("Past names"). */
88
+ declare function pastSeatNames(entries: readonly SeatNameEntry[]): SeatNameEntry[];
89
+ /** The display entry: the live one marked display, else the first live one, else null. */
90
+ declare function seatDisplayNameEntry(entries: readonly SeatNameEntry[]): SeatNameEntry | null;
91
+ /**
92
+ * The seat's flat `name` projection: the display entry's `raw`, or `null`
93
+ * when the log has no live entry (the caller keeps the flat name as it is —
94
+ * the prototype only writes a non-empty projection).
95
+ */
96
+ declare function seatNameProjection(entries: readonly SeatNameEntry[]): string | null;
97
+ /** A synthetic display row standing for the flat name when the log is empty. */
98
+ type FlatNameRow = Pick<SeatNameEntry, "entry_id" | "raw" | "name_type" | "is_display">;
99
+ /**
100
+ * The rows the Names list draws: the live log, or the flat name as one
101
+ * `__flat__` display row when the log has none (nothing is written for it).
102
+ */
103
+ declare function seatNameRows(entries: readonly SeatNameEntry[], flatName: string | null | undefined): (SeatNameEntry | FlatNameRow)[];
104
+ /**
105
+ * Seed the log from the seat's flat name (a `legal` display entry). A no-op
106
+ * when the log already has a live entry or the flat name is blank. Every act
107
+ * below does this first; exposed for a caller that needs the log minted.
108
+ */
109
+ declare function seedSeatNameLog(entries: readonly SeatNameEntry[], subject: SeatLogSubject, flatName: string | null | undefined, ctx: SeatLogContext): SeatLogChange<SeatNameEntry>;
110
+ /**
111
+ * Add a name. Seeds from the flat name first; a name already live (exact
112
+ * text) is a no-op; the first live name becomes the display name.
113
+ */
114
+ declare function addSeatName(entries: readonly SeatNameEntry[], subject: SeatLogSubject, input: {
115
+ raw: string;
116
+ name_type: SeatNameType;
117
+ }, ctx: SeatLogContext & {
118
+ flatName?: string | null;
119
+ }): SeatLogChange<SeatNameEntry>;
120
+ /** Make an entry the display name (★); moves the preferred mark with it. */
121
+ declare function setSeatDisplayName(entries: readonly SeatNameEntry[], subject: SeatLogSubject, entryId: string, ctx: SeatLogContext & {
122
+ flatName?: string | null;
123
+ }): SeatLogChange<SeatNameEntry>;
124
+ /**
125
+ * Correct a name: insert the corrected entry ("Corrects “old”" in its notes),
126
+ * carry the display mark onto it, archive the old one. `entryId` may be
127
+ * `__flat__` (the log is seeded from the flat name, then corrected). The same
128
+ * text (after trimming) is a no-op.
129
+ */
130
+ declare function correctSeatName(entries: readonly SeatNameEntry[], subject: SeatLogSubject, entryId: string, next: string, ctx: SeatLogContext & {
131
+ flatName?: string | null;
132
+ }): SeatLogChange<SeatNameEntry>;
133
+ /** Retire a name (stays in the log, dated). The display name is refused. */
134
+ declare function retireSeatName(entries: readonly SeatNameEntry[], subject: SeatLogSubject, entryId: string, ctx: SeatLogContext): SeatLogChange<SeatNameEntry>;
135
+ /**
136
+ * How a phone is DRAWN and stored on the seat log: every non-digit dropped, a
137
+ * redundant US `1` dropped, `(AAA) BBB-CCCC`, `+cc (AAA) BBB-CCCC` past ten
138
+ * digits. Canon `formatPhone` (objectStructuresEngine L232-L244), verbatim in
139
+ * behaviour. Empty when there is no digit.
140
+ */
141
+ declare function formatSeatPhone(s: string): string;
142
+ /**
143
+ * How a value is WRITTEN (PHONE-NORMALIZE 2026-08-28): trimmed; a phone in
144
+ * {@link formatSeatPhone}'s form, or as typed when it has no digit. Canon
145
+ * `canonContactValue` (objectStore L618-L623).
146
+ */
147
+ declare function canonSeatContactValue(type: SeatContactType, value: string): string;
148
+ /**
149
+ * WHICH contact this is (PHONE-DIGITS-KEY 2026-08-28): a phone's digits with a
150
+ * leading US `1` dropped; an email's lowercased text. Canon `contactKey`
151
+ * (objectStore L648-L657) over `phoneDigits` (engine L268-L272).
152
+ */
153
+ declare function seatContactKey(type: SeatContactType, value: string): string;
154
+ /**
155
+ * The phone guard (`umSeatPhoneGuard`): `""` when acceptable (blank included —
156
+ * a seat may have no number on file), else the refusal in the profile's words.
157
+ * 7-15 digits (the object spine's `detectFromInput` bounds).
158
+ */
159
+ declare function seatPhoneRefusal(value: string): string;
160
+ /**
161
+ * The email guard: `""` when acceptable (blank included), else the refusal.
162
+ * `otherSeatEmails` are the addresses on OTHER seats (the directory-uniqueness
163
+ * check); the caller supplies them.
164
+ */
165
+ declare function seatEmailRefusal(value: string, otherSeatEmails?: Iterable<string>): string;
166
+ /** Live email and phone entries, in log order. */
167
+ declare function liveSeatContacts(entries: readonly SeatContactEntry[]): SeatContactEntry[];
168
+ /** Retired entries ("Past contact details"). */
169
+ declare function pastSeatContacts(entries: readonly SeatContactEntry[]): SeatContactEntry[];
170
+ /** The preferred live entry of a type, else the first live one, else null. */
171
+ declare function preferredSeatContact(entries: readonly SeatContactEntry[], type: SeatContactType): SeatContactEntry | null;
172
+ /**
173
+ * The seat's flat `email` projection (the login projection): the preferred
174
+ * email's value, or `""` when the log has no live email. Canon
175
+ * `syncEmailProjection` (screens.jsx L24987-L24993).
176
+ */
177
+ declare function seatEmailProjection(entries: readonly SeatContactEntry[]): string;
178
+ /** Whether the ✕ is offered: not on the preferred entry while another of its type is live. */
179
+ declare function canRetireSeatContact(entries: readonly SeatContactEntry[], entry: SeatContactEntry): boolean;
180
+ /**
181
+ * Add an email or phone. Refused by the type's guard; normalized; a value
182
+ * already live of the same type (by {@link seatContactKey}) is a no-op; the
183
+ * first live entry of its type becomes preferred.
184
+ */
185
+ declare function addSeatContact(entries: readonly SeatContactEntry[], subject: SeatLogSubject, input: {
186
+ contact_type: SeatContactType;
187
+ value: string;
188
+ }, ctx: SeatLogContext & {
189
+ otherSeatEmails?: Iterable<string>;
190
+ }): SeatLogChange<SeatContactEntry>;
191
+ /** Make an entry the preferred of its type (☆ prefer). */
192
+ declare function setPreferredSeatContact(entries: readonly SeatContactEntry[], subject: SeatLogSubject, entryId: string, ctx: SeatLogContext): SeatLogChange<SeatContactEntry>;
193
+ /**
194
+ * Correct an email or phone. Guarded and normalized like an add. Re-typing the
195
+ * same value in another shape is a no-op. Correcting INTO a live value of the
196
+ * same type hands it the preferred mark and archives the wrong one; otherwise
197
+ * the corrected entry is inserted ("Corrects “old”"), takes the mark, and the
198
+ * old one is archived.
199
+ */
200
+ declare function correctSeatContact(entries: readonly SeatContactEntry[], subject: SeatLogSubject, entryId: string, next: string, ctx: SeatLogContext & {
201
+ otherSeatEmails?: Iterable<string>;
202
+ }): SeatLogChange<SeatContactEntry>;
203
+ /** Retire an email or phone (stays in the log, dated). See {@link canRetireSeatContact}. */
204
+ declare function retireSeatContact(entries: readonly SeatContactEntry[], subject: SeatLogSubject, entryId: string, ctx: SeatLogContext): SeatLogChange<SeatContactEntry>;
205
+
206
+ /**
207
+ * The Person id: `per-<first>-<second>`, name-free (Person § "The id carries no
208
+ * name": "Display names carry identity; ids are stable and name-free").
209
+ *
210
+ * Canon: platform-prototype `src/screens.jsx` @ 398fb24 `mintPersonId`
211
+ * (L24354-L24363), drawing from the directory's `person_slug_wordlists`
212
+ * (`first`, `second`), which the records repo's directory generator
213
+ * (`tools/build_platform_directory.py`) emits.
214
+ *
215
+ * The wordlists default to the vendored copy of the records monolith's
216
+ * `PERSON_FIRST` / `PERSON_SECOND` (`./personSlugWordlists.ts`); a caller may
217
+ * still pass a directory build's `person_slug_wordlists` instead.
218
+ */
219
+ /** The directory build's slug wordlists. */
220
+ interface PersonSlugWordlists {
221
+ first: readonly string[];
222
+ second: readonly string[];
223
+ }
224
+ /** `per-` then two lowercase words, optionally a numeric suffix (`-<n>`) when the pair pool was full. */
225
+ declare const PERSON_ID_PATTERN: RegExp;
226
+ /** True for a string shaped like a Person id. */
227
+ declare function isPersonId(v: unknown): v is string;
228
+ /**
229
+ * Mint a Person id not in `taken`. `null` only when there are no wordlists
230
+ * (empty or `null`) — refuse rather than invent a shape.
231
+ *
232
+ * As the prototype (`mintPersonId`, screens.jsx L24352-L24363): up to 200
233
+ * random draws of `per-<first>-<second>`. If all 200 are taken, the whole
234
+ * two-word space is scanned in list order for a free pair. When every pair is
235
+ * taken (45 × 45 = 2,025 with the vendored lists), the records generator's
236
+ * full-pool rule applies (`generatePersonSlug`, records monolith: after its
237
+ * random tries fail it returns `<first>-<second>-<number 0-999>`): up to 200
238
+ * random `per-<first>-<second>-<0-999>`, then a deterministic scan over the
239
+ * pairs and suffixes 0, 1, 2, … until one is free, so a mint always ends.
240
+ *
241
+ * `taken` is a snapshot (every person id already held by a seat or a registry
242
+ * person; the caller supplies it), so two concurrent mints can return the
243
+ * same id: the store needs a UNIQUE index on the person id, and a caller
244
+ * retries the mint on a duplicate-key error. `random` must return `[0, 1)`;
245
+ * an out-of-range value is clamped. `wordlists` left `undefined` uses the
246
+ * vendored lists ({@link PERSON_SLUG_WORDLISTS}).
247
+ */
248
+ declare function mintPersonId(wordlists?: PersonSlugWordlists | null | undefined, taken?: Iterable<string | null | undefined>, random?: () => number): string | null;
249
+ /** Mint a Person id from the vendored wordlists, not in `taken` (or `null`). */
250
+ declare function mintNewPersonId(taken?: Iterable<string | null | undefined>, random?: () => number): string | null;
251
+
252
+ /**
253
+ * The Person id wordlists, vendored.
254
+ *
255
+ * Source: the records repo (htilabstech/prototype) @ 1be43ed5, the monolith
256
+ * `HTI-LEADS-PAVE-Thread-prototype.html` consts `PERSON_FIRST` and
257
+ * `PERSON_SECOND`, copied unchanged. The same lists reach the Platform
258
+ * prototype as the directory build's `person_slug_wordlists`
259
+ * (records `tools/build_platform_directory.py` → platform-prototype
260
+ * `src/data.js` `HTI_DIRECTORY.person_slug_wordlists`; equal at 398fb24).
261
+ *
262
+ * Do not hand-edit. A word added or removed in the records monolith is
263
+ * re-copied here; an id already minted keeps its words either way (ids are
264
+ * never re-derived from these lists).
265
+ */
266
+
267
+ /** `PERSON_FIRST` (45 words). */
268
+ declare const PERSON_SLUG_FIRST: readonly string[];
269
+ /** `PERSON_SECOND` (45 words). */
270
+ declare const PERSON_SLUG_SECOND: readonly string[];
271
+ /** The vendored wordlists, the default for `mintPersonId`. */
272
+ declare const PERSON_SLUG_WORDLISTS: PersonSlugWordlists;
273
+
274
+ export { FLAT_NAME_ENTRY_ID, type FlatNameRow, PERSON_ID_PATTERN, PERSON_SLUG_FIRST, PERSON_SLUG_SECOND, PERSON_SLUG_WORDLISTS, type PersonSlugWordlists, SEAT_NAME_BLANK_REFUSAL, SeatContactEntry, SeatContactType, type SeatLogChange, type SeatLogContext, SeatLogRefusal, SeatLogSubject, SeatNameEntry, SeatNameType, addSeatContact, addSeatName, canRetireSeatContact, canonSeatContactValue, correctSeatContact, correctSeatName, formatSeatPhone, isPersonId, liveSeatContacts, liveSeatNames, mintNewPersonId, mintPersonId, mintSeatLogEntryId, pastSeatContacts, pastSeatNames, preferredSeatContact, retireSeatContact, retireSeatName, seatContactKey, seatDisplayNameEntry, seatEmailProjection, seatEmailRefusal, seatNameProjection, seatNameRows, seatPhoneRefusal, seedSeatNameLog, setPreferredSeatContact, setSeatDisplayName };